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

#目的

Shopifyコネクタは、GraphQL Admin APIを介してShopifyストアからデータを抽出します：製品、顧客、注文、在庫、マーケティング、B2B、決済、コンテンツなど。

40種類の組み込みエンドポイント + カスタムクエリのエスケープハッチによる任意のGraphQL。

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

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

独自のカスタムアプリをストアにインストールします。コネクタはそのアプリの認証情報を使用してデータを読み取ります。それ以外のことは何も行いません。

認証情報を取得する2つの方法があり、どちらもサポートされています：

#パスA：Devダッシュボード（新しいストアに推奨）

1. partners.shopify.comにアクセスし、サインインします（無料、カード不要）。
2. Devダッシュボードを開き、アプリを作成をクリックし、名前を付けます（例：data-connector）。
3. 新しいアプリで、バージョン → 新しいバージョンを作成に移動します。
4. アクセス → アクセススコープの下に、以下の推奨スコープリストを貼り付けます。
5. アクセスセクションの上部でアクセスをリクエストを開き、顧客データ（および注文データなど）→ データ分析を有効にし、保存します。開発ストアではこの承認が即座に行われます。
6. バージョンを公開します。
7. 配布セクションからアプリをストアにインストールします。
8. アプリの設定を開き、クライアントIDとクライアントシークレットをコピーします。
9. コネクタUIでShopを入力し、アクセストークンを空白のままにし、クライアントID + クライアントシークレットを貼り付けます。コネクタは最初の実行時にそれらをオフライントークンと交換します。

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

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

#2. 認証情報を設定する

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

両方が入力されている場合、直接トークンが優先されます。

#3. 推奨スコープ

このカンマ区切りのリストをカスタムアプリバージョンのアクセススコープフィールドに貼り付けます（Devダッシュボード → アクセス → アクセススコープ）：

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バージョン間でスコープ名を変更しますが、コネクタは欠落したスコープを優雅に処理します（警告を表示して[]を返す代わりにクラッシュしません）。

顧客 / 注文 / 下書き注文 / 放棄されたチェックアウトデータには、保護された顧客データの承認を有効にする必要があります（パスA、ステップ5を参照）。それなしでは、そのエンドポイントは行を返しますが、PIIフィールドは空白になります。

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

1. Data Platformのコネクタで、ソースストア内のShopifyを見つけ、選択をクリックします。
2. ステップ2からモードA（直接トークン）またはモードB（クライアントID + クライアントシークレット）を使用して接続フィールドを入力します。
3. 接続をクリックします。モードBの場合、コネクタはこのステップでクライアントID/シークレットをオフラインアクセストークンと交換します。
4. エンドポイントを追加をクリックし、ドロップダウンからエンドポイントタイプを選択します（例：products, orders, custom_query）、その後、必要なパラメータを入力します（例：segment_id, query_filter, max_items）。
5. このソースで取り込みたい追加のエンドポイントごとにステップ4を繰り返します。各エンドポイントはレイクハウス内の別々のテーブルになります。
6. ソースに名前を付け、作成をクリックします。

#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）は、Max Itemsフィールドを公開しています。これは「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. Connection Pathフィールドを設定するか（例：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：空にします
• Connection Path：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"}
• Connection Path：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：空にします
• Connection Path：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：空にします
• Connection Path：orders

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

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

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：空にします
• Connection Path：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を宣言する必要があります。これはGraphQLの宣言であり、Shopifyがそれらを期待するようにします。コネクタはその後、ページごとにその値を実行時に注入します。Variables UIフィールドは、クエリで宣言した追加変数の値（例：$query、$ownerType、$segmentId）用です。firstやafterをそこに入力しないでください。コネクタはそれらを上書きします。
• max_itemsは組み込みエンドポイントと同様に適用されます：セクション6を参照してください。

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

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

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

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

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

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. Plan & Scope Gating

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

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

#さらに詳しく

当社のソリューションのトレーニングや技術的な実装支援が必要な場合は、営業担当者にお問い合わせください、またはProfessional Servicesページをご覧ください。見積もりをリクエストし、当社の専門家がプロジェクトを分析してください。

専用Discordチャネルで、Data Platformを構築するチームと直接質問したり、フィードバックを送信したり、交流したりしてください。

OVHcloudサービスについてサポートが必要な場合は、Help Centreでリクエストを作成してください。

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