ShopifyストアのデータをGraphQL Admin APIで抽出する#

#目的

The Shopify connector extracts data from your Shopify store via the GraphQL Admin API: products, customers, orders, inventory, marketing, B2B, payments, content, and more.

40種類の組み込みエンドポイント + カスタムクエリのエスケープハッチで任意のGraphQLを実行します。

このコネクタは、Shopify API から 生のJSON を返します。プラットフォームは、入れ子になったフィールドを自動的に列に平坦化し、その結果をレイクハウスに保存します。手動でのスキーマ定義は必要ありません。

#1. 管理APIアクセストークンを取得する

あなたが自分のカスタムアプリをストアにインストールします。その後、コネクタはそのアプリの資格情報を使用してデータを読み取ります。それ以外のことは行いません。

2つの方法で認証情報を取得できます。どちらもサポートされています：

1. OVHcloud Control Centerから直接取得する方法です。
2. OVHcloud APIを使用して取得する方法です。

どちらの方法を選択しても、認証情報を取得することができます。

#パスA: Devダッシュボード（新規ストア向け）

1. partners.shopify.com にアクセスし、サインインします（無料でクレジットカードは不要です）。
2. Dev Dashboard を開き、Create app をクリックし、名前を付けます（例: data-connector）。
3. 新しいアプリで、Versions → Create a new version に移動します。
4. Access → Access scopes の下に、以下の推奨スコープリストを貼り付けます。
5. Access セクションの上部にある Request access を開き、Customer data（および Order data など）→ Data analytics を有効にし、保存します。 開発ストアではこの承認が即時行われます。
6. バージョンをPublishします。
7. Distribution セクションからアプリをストアにインストールします。
8. アプリのSettings を開き、Client ID と Client Secret をコピーします。
9. コネクタのUIでShopを入力し、Access Tokenを空白のままにし、Client ID + Client Secretを貼り付けます。コネクタは最初の実行時にそれらをオフライントークンと交換します。

#パスB: 既存のトークン（既にトークンをお持ちの場合は短縮可能）

既に、レガシーの「アプリ開発」フロー（トークンはshpat_で始まります）を通じてAdmin APIアクセストークンを取得しているか、OAuth client_credentials交換を自分で実行した場合（shpua_）は、アクセストークンフィールドに直接貼り付けてください。クライアントID / クライアントシークレットは空白のままにしてください。

#2. 資格情報の設定

コネクタは、2つの相互に交換可能な認証モードを受け入れます。

どちらも入力されている場合、直接トークンが優先されます。

#3. 推奨スコープ

このコンマ区切りリストを、カスタムアプリのバージョンのアクセススコープフィールドに貼り付けてください（Dev Dashboard → アクセス → アクセススコープ）。

read_products, read_customers, read_orders, read_draft_orders,
read_inventory, read_locations, read_discounts,
read_shopify_payments_payouts, read_shopify_payments_disputes,
read_shopify_payments_accounts, read_marketing_events,
read_content, read_users, read_shipping, read_metaobjects,
read_metaobject_definitions, read_publications, read_locales,
read_markets, read_files, read_companies, read_assigned_fulfillment_orders,
read_audit_events

スコープ名が拒否された場合は、そのスコープを削除してください。ShopifyはAPIバージョン間でスコープ名を変更しますが、コネクタは欠落したスコープを優しく処理します（警告を伴う[]を返す代わりにクラッシュしません）。

Customer / Order / Draft Order / Abandoned Checkout データの場合、Protected Customer Data の承認を有効にする必要があります（Path A、ステップ 5を参照）。これを行わない場合、これらのエンドポイントは行を返しますが、PII フィールドは空白になります。

#4. Data PlatformにShopifyソースを追加する

1. Data Platform の Connectors で、ソースストアから Shopify を探し、Select をクリックします。
2. 手順 2に記載されている Mode A（直接トークン）または Mode B（クライアント ID + クライアント シークレット）のいずれかを使用して、接続フィールドを入力します。
3. Connect をクリックします。Mode B の場合、このステップでコネクタがクライアント ID/シークレットをオフライン アクセス トークンと交換します。
4. Add an Endpoint をクリックし、ドロップダウンからエンドポイントの種類を選択します（例: products, orders, custom_query）。その後、必要なパラメータを入力します（例: segment_id, query_filter, max_items）。
5. このソースで取り込みたい追加のエンドポイントがあれば、手順 4 を繰り返します。各エンドポイントは、Lakehouse の別々のテーブルになります。
6. ソースに名前を付け、Create をクリックします。

#5. 利用可能なエンドポイントの種類

#コアコマース (14)

#B2B & マーケット (4)

#プロモーション & ロイヤルティ (4)

#マーケティング & Shopify決済 (5)

#メタデータ & カスタムデータ (3)

#コンテンツ (5)

#管理 & オペレーション (4)

#シングルオブジェクト (1)

#カスタムGraphQL (1)

custom_query の場合、GraphQL は $first: Int! と $after: String を変数として宣言し、pageInfo { hasNextPage endCursor } で接続をページネーションする必要があります。コネクタはカーソルを自動的に挿入します。

#6. ページネーション & max_items

ShopifyのGraphQL APIは、一度にすべての結果を返すことはありません。すべてのリストはページネーションされています。コネクタは自動的にページネーションを処理します。UIで制御できるのは、max_itemsフィールドだけです。

#max_itemsフィールド

すべてのエンドポイント（組み込みとcustom_query）は、最大項目数フィールドを公開しています。これは「Nレコードを収集した後で停止する」とコネクタに指示します。さらに多くのレコードが利用可能でも。

#背景で動作する仕組み

コネクタはページサイズを動的に選択します。

page_size = min(100, max_items - already_collected)   # if max_items is set
page_size = 100                                        # if max_items is empty

各リクエストは、その数のレコードをShopifyに要求します。max_itemsに達したりhasNextPage: falseしたりすると、ループが停止します。

したがって、max_items: 5は正確に1つのHTTPリクエスト（first=5, after=null）をトリガーします。ページネーションループはありません。2回目の呼び出しはありません。自分でページネーションロジックを記述する必要はありません。

#「最初のページのみを取得」

「最初のページのみ」を明示的に切り替えるトグルはありません。ただし、Shopifyがページサイズを250に制限しているため、max_itemsを250以下に設定すると、1つのHTTPリクエストが保証されます。「自然なShopifyページサイズ」（デフォルトで50–100）が必要な場合は、max_items: 50または100を設定します。

#すべてのエンドポイントに適用

これは、次のように同じ方法で動作します。

• 40の組み込みエンドポイント（products、orders、customers、...）。
• custom_queryエンドポイント：コネクタは引き続きfirstとafterをクエリに注入し、max_itemsを尊重します。

GraphQLクエリ自体でfirst: 5を記述する必要はありません。first: $firstを記述し、コネクタがmax_itemsに基づいて正しい値を注入させます。

#7. カスタムクエリ：例

custom_queryエンドポイントは、Admin APIに対して記述した任意のGraphQLを受け付けます。3つのルールが適用されます。

1. クエリ変数に$first: Int!と$after: Stringを宣言します。
2. pageInfo { hasNextPage endCursor }で1つの接続をページネーションします。
3. 接続パスフィールドを設定するか（例：products）、コネクタが接続を自動検出するようにします。

以下は、一般的なケースの具体的なテンプレートです。どれかをGraphQLクエリフィールドに貼り付け、Variablesフィールドに必要に応じて入力し、実行します。

#例1：基本的な製品（いくつかのフィールドのみ）

ダウンストリームの結合にIDとタイトルのみが必要な場合、20フィールドのデフォルトproductsエンドポイントの代わりに便利です。

query ($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    edges {
      node {
        id
        title
        handle
        vendor
        createdAt
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

• Variables：空にします
• 接続パス：products（または自動検出のために空にします）

#例2：日付フィルター付きの注文

組み込みordersエンドポイントを複製しますが、フィルターとフィールド選択の両方を調整できます。フィルターはVariablesを通じて渡します。

query ($first: Int!, $after: String, $query: String) {
  orders(first: $first, after: $after, query: $query, sortKey: CREATED_AT) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        totalPriceSet { shopMoney { amount currencyCode } }
        customer { id email }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

• Variables：{"query": "created_at:>=2026-04-01 AND financial_status:paid"}
• 接続パス：orders

完全な検索構文は、shopify.dev/docs/api/usage/search-syntaxでドキュメント化されています。

#例3：バリアントとメタフィールド付きの製品

デフォルトのproductsエンドポイントが不十分な場合。各製品のバリアントをインラインで取得し、いくつかの特定のメタフィールドを取得します。

query ($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    edges {
      node {
        id
        title
        variants(first: 50) {
          edges {
            node { id sku price inventoryQuantity }
          }
        }
        metafields(first: 10, namespace: "custom") {
          edges {
            node { key value type }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

• Variables：空にします
• 接続パス：products

#例4：注文行項目（トップレベルのエンドポイントとして公開されていないサブリソース）

各注文の行項目は組み込みエンドポイントではありません。それらを取得する唯一の方法はカスタムクエリです。

query ($first: Int!, $after: String) {
  orders(first: $first, after: $after, query: "status:any", sortKey: CREATED_AT) {
    edges {
      node {
        id
        name
        lineItems(first: 50) {
          edges {
            node {
              id
              title
              quantity
              originalUnitPriceSet { shopMoney { amount currencyCode } }
              variant { id sku }
            }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

• Variables：空にします
• 接続パス：orders

#例5：ネストされた接続（接続パスを使用）

接続がルートにない場合、例：特定のShopify Payments残高取引の注文。接続パスを明示的に設定します。

query ($first: Int!, $after: String) {
  shopifyPaymentsAccount {
    payouts(first: $first, after: $after) {
      edges {
        node {
          id
          status
          issuedAt
          summary {
            chargesGross { amount currencyCode }
            refundsFee { amount currencyCode }
          }
        }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
}

• Variables：空にします
• 接続パス：shopifyPaymentsAccount.payouts*（必要です。自動検出はここで動作しますが、複数の接続が異なる深さにある場合は明示的な方が明確です）

#ヒント

• GraphiQL Explorerで最初にテストします。Shopifyはhttps://{shop}.myshopify.com/admin/api/explorerでGraphiQLを提供しています。クエリを構築して検証した後、コネクタに貼り付けます。自動補完とスキーマドキュメントにより、反復処理がはるかに高速になります。
• フィールドの発見。完全なスキーマは、shopify.dev/docs/api/admin-graphql/latestでドキュメント化されています。各タイプのページには、利用可能なフィールドとそのコストがリストされています。
• 2つの場所、2つの役割。クエリ文字列は、変数リストに$first: Int!と$after: Stringを宣言する必要があります。これは、Shopifyがそれらを期待するGraphQL宣言です。コネクタはその後、ページごとにその値を実行時に注入します。Variables UIフィールドは、クエリで宣言した追加変数の値（例：$query、$ownerType、$segmentId）用です。firstやafterをそこに入力しないでください。コネクタはそれらを上書きします。
• max_itemsは組み込みエンドポイントと同様に適用されます：セクション6を参照してください。

#8. クイック例：製品の抽出

1. エンドポイントタイプ：products
2. 最大項目数：1000（または空にしてすべてを抽出）
3. テーブル抽出を実行します。

コネクタは生のJSONを返します。プラットフォームは自動的にネストされたフィールドをフラット化します（例：featuredImage.urlは列featuredimage_urlになります）。

焦点を当てたクエリ：例：過去30日間の注文のみ

1. エンドポイントタイプ：orders
2. クエリフィルター：created_at:>=2026-04-01
3. 最大項目数：空

query_filterフィールドはShopify検索構文を受け付けます。

#9. ベストプラクティス

#ショップ名を1回正規化

コネクタはmy-store、my-store.myshopify.com、またはhttps://my-store.myshopify.com/を受け付けます。3つとも同じホストに解決します。最も読みやすいものを選択します。

#狭い抽出にcustom_queryを使用

デフォルトのクエリは、レコードごとに約10–20フィールドを返します。数百万のレコードがあり、数十のフィールドのみが必要な場合は、そのフィールドのみを含むcustom_queryを記述します。クエリコストはフィールド数にほぼ比例します。

#クライアントID + シークレットでトークンを更新

Mode B（クライアントID + クライアントシークレット）を設定した場合、コネクタは各ジョブ開始時にOAuth交換を再実行します。これにより、漏洩/回転したトークンは、Devダッシュボードでシークレットを再発行することで置き換えられ、コネクタ構成を変更する必要はありません。

#注文のデフォルトquery_filter

注文エンドポイントは、デフォルトでstatus:anyを使用して、すべての注文（開いている、閉じている、キャンセルされた）を含めます。開いている注文のみが必要な場合は、query_filter: status:openを設定します。

#10. プランおよびスコープによるゲーティング

一部のエンドポイントは、プランまたはスコープによって制限されています：

スコープまたはプランが不足している場合、コネクタは警告をログに記録し、そのエンドポイントに対して空のリストを返します。他のテーブルは引き続き動作します。

#さらに詳しく

当社のソリューションを実装するためのトレーニングや技術サポートが必要な場合は、営業担当者にお問い合わせください、またはこのリンクをクリックして見積もりを依頼し、当社のプロフェッショナルサービスの専門家にプロジェクトのカスタム分析を依頼してください。

Data Platformの開発チームと直接質問したり、フィードバックを送信したり、交流したりするには、専用のDiscordチャネルにアクセスしてください。

OVHcloudサービスについてサポートが必要な場合は、ヘルプセンターでリクエストを作成してください。

ユーザーコミュニティに参加してください。