Shopify: 技術リファレンス#

#目的

これは、主なShopifyコネクタのドキュメントの技術的な補助資料です。認証の内部、完全なエンドポイントリファレンス、ページネーション、レート制限、出力形式、制限など、データパイプラインにコネクタを統合するために必要なすべての内容をカバーしています。

#認証

#サポートされているモード

コネクタは、どちらのモードも最終的にすべてのAPIリクエストにX-Shopify-Access-Tokenヘッダーを送信する2つの相互に交換可能な認証モードをサポートしています。

access_tokenが入力されている場合、優先されます。OAuth交換はスキップされます。

#トークン形式

両方の接頭辞はアクセストークンフィールドで有効であり、コネクタによって同じように使用されます。

#非推奨の認証方法

#カスタムアプリの承認

顧客/注文/下書き注文/放棄されたチェックアウト/配送注文データについては、Shopifyではアプリレベルで保護された顧客データの承認が必要です。開発ストアでは、マーチャントがDevダッシュボードで関連するチェックボックスにチェックを入れると、即座に承認されます。App Storeを通じて配布されるプロダクションストアでは、Shopifyがリクエストを手動でレビューします。

承認が欠如している場合、APIは影響を受けたフィールドに対してACCESS_DENIEDエラーを返します。コネクタはこれらを予期したものとして扱い、取得できたデータを返します（制限されたフィールドは空白にされます）。

#アーキテクチャ

コネクタはShopify GraphQL APIからの生のJSONを返します。プラットフォームはそこで引き継ぎます。JSONペイロードから自動的にスキーマを発見し、入れ子になったオブジェクトをドット記法の列（スラッグ化されて小文字でアンダースコア付き）にフラット化し、結果をレイクハウスに保存します。Trinoを介してクエリ可能です。Shopifyがノードに追加した新しいフィールドは、次の抽出時に自動的に表示されます。

コネクタ自体は以下の責任を負います。

#APIバージョン

すべてのリクエストは、Shopify Admin GraphQL APIの2026-04バージョンをターゲットとしています。新しいバージョンに固定する前に、Shopifyのリリースノートを更新してください。スキーマの変更により、フィールドが名前を変更したり、型が変更されたりすることがあります。

#エンドポイントリファレンス

各ページネーションされたエンドポイントは、同じ呼び出し形状を共有します：

POST https://{shop}.myshopify.com/admin/api/2026-04/graphql.json
{ "query": "...", "variables": { "first": 100, "after": null } }

コネクタは、pageInfo.hasNextPage == false またはユーザー指定の max_items キャップに達するまでページを反復します。

以下の各エンドポイントについて、「出力」は 生のJSON です：ネストされたフィールドを保持した完全なGraphQL node オブジェクト。プラットフォームはダウンストリームでそれをフラット化します。

#products

ルートフィールド: products(first, after, sortKey: CREATED_AT)

デフォルトフィールド: id, handle, title, description, vendor, productType, status, tags, タイムスタンプ, totalInventory, tracksInventory, featuredImage, options, seo, onlineStoreUrl, priceRangeV2。

#product_variants

ルートフィールド: productVariants(first, after): API 2022-07以降のトップレベル；親製品IDは必要ありません。

デフォルトフィールド: id, sku, title, position, price, compareAtPrice, barcode, taxable, inventoryQuantity, availableForSale, タイムスタンプ, selectedOptions, 親 product 参照, image。

#collections

ルートフィールド: collections(first, after): マニュアル + スマートコレクションの統合ビュー。

デフォルトフィールド: id, handle, title, description, updatedAt, sortOrder, productsCount, seo, image。

#customers

ルートフィールド: customers(first, after)

デフォルトフィールド: id, firstName, lastName, email, phone, state, note, tags, タイムスタンプ, verifiedEmail, numberOfOrders, amountSpent, defaultAddress, lifetimeDuration。

PIIフィールド（firstName, lastName, email, phone, defaultAddress.zip）には、Protected Customer Dataの承認が必要です。承認がない場合、これらのフィールドは空白のまま行が返されます。

#customer_segment_members

ルートフィールド: customerSegmentMembers(first, after, segmentId: $segment_id)

まず segments エンドポイントを使用して、セグメントIDを発見してください。

#orders

ルートフィールド: orders(first, after, query: $query_filter, sortKey: CREATED_AT)

query_filter は Shopify 検索構文を受け入れます（例: created_at:>=2026-01-01, financial_status:paid）。

デフォルトフィールド: id, name, legacyResourceId, ライフサイクルタイムスタンプ, displayFinancialStatus, displayFulfillmentStatus, マネーセット（totalPrice, subtotalPrice, totalTax, totalDiscounts, totalRefunded, totalShippingPrice), customer, アドレス, channelInformation。

#draft_orders

ルートフィールド: draftOrders(first, after)

デフォルトフィールド: id, name, status, email, note2, タイムスタンプ, マネーセット, customer, shippingAddress。

#abandoned_checkouts

ルートフィールド: abandonedCheckouts(first, after)

デフォルトフィールド: id, name, abandonedCheckoutUrl, タイムスタンプ, マネーセット, customer。

#fulfillment_orders

ルートフィールド: fulfillmentOrders(first, after)

デフォルトフィールド: id, status, requestStatus, タイムスタンプ, destination（アドレスフィールド）, assignedLocation, 親 order。

#tender_transactions

ルートフィールド: tenderTransactions(first, after)

デフォルトフィールド: id, paymentMethod, processedAt, remoteReference, test, amount, 親 order, user。

#locations

ルートフィールド: locations(first, after)

デフォルトフィールド: id, name, isActive, タイムスタンプ, fulfillsOnlineOrders, shipsInventory, legacyResourceId, address。

#inventory_items

ルートフィールド: inventoryItems(first, after)

デフォルトフィールド: id, sku, tracked, requiresShipping, タイムスタンプ, countryCodeOfOrigin, harmonizedSystemCode, unitCost, 親 variant + product。

#segments

ルートフィールド: segments(first, after)

デフォルトフィールド: id, name, query（セグメント定義式）, creationDate, lastEditDate。

#companies

ルートフィールド: companies(first, after): B2B専用；ストアでB2Bが有効になっていない場合は空を返します。

デフォルトフィールド: id, name, externalId, note, タイムスタンプ, locationsCount, ordersCount, totalSpent。

#company_locations

ルートフィールド: companyLocations(first, after): B2B専用。

デフォルトフィールド: id, name, externalId, note, タイムスタンプ, アドレス, 親 company。

#price_lists

ルートフィールド: priceLists(first, after): B2B / 卸売り。

デフォルトフィールド: id, name, currency, parent.adjustment, リンクされた catalog。

#catalogs

ルートフィールド: catalogs(first, after): B2Bカタログ割り当て。

デフォルトフィールド: id, title, status, リンクされた priceList。

#markets

ルートフィールド: markets(first, after): マルチリージョン構成。

デフォルトフィールド: id, name, handle, enabled, primary, webPresence.rootUrls, currencySettings.baseCurrency。

#discount_nodes

ルートフィールド: discountNodes(first, after): 自動 + コード + マニュアル割引のユニオン。

デフォルトフィールド: id, さらにタイプ付きの discount ペイロードを使用して、インラインフラグメントを使用して DiscountAutomaticBasic, DiscountAutomaticBxgy, DiscountCodeBasic, DiscountCodeBxgy, DiscountCodeFreeShipping, DiscountAutomaticFreeShipping を指定します。各バリアントは title, status, startsAt, endsAt, 使用回数を公開します。

#code_discount_nodes

ルートフィールド: codeDiscountNodes(first, after): コード割引のみ。

discount_nodes と同じフィールド形状で、DiscountCode* タイプに制限されています。

#gift_cards

ルートフィールド: giftCards(first, after): Shopify Plus専用。

デフォルトフィールド: id, enabled, expiresOn, タイムスタンプ, lastCharacters, note, balance, initialValue, 所有する customer。

#selling_plan_groups

ルートフィールド: sellingPlanGroups(first, after): サブスクリプションプラン。

デフォルトフィールド: id, name, description, createdAt, merchantCode, appId, summary, productsCount, options。

#marketing_events

ルートフィールド: marketingEvents(first, after): キャンペーン追跡。

デフォルトフィールド: id, type, remoteId, startedAt, endedAt, manageUrl, previewUrl, UTMフィールド, 所有する app。

#publications

ルートフィールド: publications(first, after): セールスチャネル公開。

デフォルトフィールド: id, name, supportsFuturePublishing, 所有する app。

#payouts / disputes / balance_transactions

ルートパス: shopifyPaymentsAccount.{payouts | disputes | balanceTransactions}(first, after)。Shopify Paymentsはストアで有効にする必要があります。shopifyPaymentsAccount がnullの場合、コネクタは空のリスト（警告付き）を返します。

デフォルトフィールド（payouts）: id, status, issuedAt, net, サマリーブレイクダウン。 デフォルトフィールド（disputes）: id, status, initiatedAt, amount, reasonDetails。 デフォルトフィールド（balance_transactions）: id, type, transactionDate, test, amount, fee, net。

#metaobjects

ルートフィールド: metaobjects(first, after, type: $metaobject_type)

まず metaobject_definitions エンドポイントを使用して、利用可能なタイプのリストを表示します。

デフォルトフィールド: id, handle, type, displayName, updatedAt, capabilities.publishable.status, fields[].{key, value, type, jsonValue}。

#metaobject_definitions

ルートフィールド: metaobjectDefinitions(first, after)

デフォルトフィールド: id, type, name, displayNameKey, description, ネストされた fieldDefinitions。

#metafield_definitions

ルートフィールド: metafieldDefinitions(first, after, ownerType: $owner_type)

デフォルトフィールド: id, namespace, key, name, description, ownerType, type.name, pinnedPosition。

#articles / blogs / pages / url_redirects / files

標準のページネーションされたコンテンツエンドポイント。各エンドポイントはタイプ付きの node オブジェクトを返します。各タイプの正確なフィールド形状については、Shopify GraphQLリファレンスを参照してください。コネクタは各エンドポイントごとに合理的なデフォルトフィールドサブセットを要求します（handle, title, body/summary, timestamps, publication status, ..）。

files の場合、クエリは MediaImage, Video, GenericFile 用のインラインフラグメントを使用するため、出力には id, alt, createdAt, fileStatus の横にメディアタイプ固有のペイロードが含まれます。

#events

ルートフィールド: events(first, after, sortKey: CREATED_AT, reverse: true): ショップ監査ログ。

デフォルトフィールド: id, message, createdAt, appTitle, attributeToApp, attributeToUser, criticalAlert。

#staff_members / delivery_profiles / fulfillment_services

標準エンドポイントで、max_items パラメータがあります。fulfillment_services は異常です。データは shop.fulfillmentServices の下にネストされ、リストとして返されます（ページネーションされません）。コネクタは特殊なパスを自動的に処理します。

#shop

パラメータはありません。ストアのメタデータ、ID、名前、ドメイン、通貨、タイムゾーン、プラン、請求先住所、プライマリドメイン、機能フラグ、タイムスタンプを含む1要素のリストを返します。小さな参照テーブルとして便利です。

#custom_query

Admin APIに対して任意のGraphQLクエリを実行します。制約:

1. クエリには $first: Int! と $after: String を変数として宣言する必要があります。
2. 1つの接続を pageInfo { hasNextPage endCursor } でページネーションする必要があります。
3. connection_path（データルートから接続へのドットパス、例: products, shop.metafields）を提供するか、コネクタに最初の edges/pageInfo 接続を応答内で自動検出させる必要があります。

コネクタは $first（デフォルトは250またはmax_itemsが設定された場合）と $after（前のページからのカーソル）を置き換え、pageInfo.hasNextPage がfalseになるまでループします。

variables を使用して、クエリで使用する追加のパラメータを渡すことができます（例: {"query": "tag:vip"} は顧客検索フィルタ）。$first / $after は予約されています。

抽出時にバリデーションが実行され、無効なクエリ（変数が不足）は最初のHTTP呼び出し前に明確なエラーを発生させます。

#ページネーション

すべてのページネーションエンドポイントは、カーソルベースのページネーション（Relayスタイルの接続）を使用します。コネクタはループします：

{
  edges { node { ... } }
  pageInfo { hasNextPage endCursor }
}

first: 100（デフォルトのページサイズ、最大250）とafter: <previous endCursor>を使用します。ループはhasNextPage == falseまたはユーザーが指定したmax_itemsに達したときに終了します。

単一オブジェクトエンドポイント（shop）とネストされたリストfulfillment_servicesはページネーションをスキップします。コネクタはレスポンスを1要素のリストでラップします。

#レート制限

Shopify Admin GraphQL APIは、コストベースのレート制限を使用します（秒あたりのリクエスト数ではありません）。各クエリには接続サイズから計算されたポイントコストがあります。各ストアには、固定速度で補充されるアプリごとのバケットがあります。

現在の詳細については、Shopifyの公式レート制限ドキュメントを参照してください。

#スロットル処理

コネクタは、スロットルを3つの方法で処理します：

1. 予防的なスリープ：各レスポンスの後、extensions.cost.throttleStatusを検査します。次のページのコストが現在利用可能な予算を超える場合、バケットが補充されるまで必要な時間だけスリープします。
2. GraphQL THROTTLED エラー：Shopifyは時々HTTP 200とTHROTTLEDエラーを本文に返します。コネクタは短いバックオフの後、再試行します。
3. HTTP 429：まれですが、Retry-Afterで処理します。コネクタは最大5回再試行した後、エラーを発生させます。

#出力形式

#生のJSON

コネクタはedges[].nodeの内容を、Shopify GraphQLが返したとおりの辞書のリストとして返します。ネストされたオブジェクト（住所、通貨セット、子配列）は保持されます。

例：製品ノード（省略）：

{
  "id": "gid://shopify/Product/123",
  "handle": "snowboard",
  "title": "All-mountain snowboard",
  "vendor": "Acme",
  "productType": "Snowboard",
  "status": "ACTIVE",
  "createdAt": "2024-01-15T10:30:00Z",
  "totalInventory": 42,
  "featuredImage": {
    "url": "https://cdn.shopify.com/.../snowboard.jpg",
    "altText": "Snowboard front view"
  },
  "priceRangeV2": {
    "minVariantPrice": { "amount": "299.00", "currencyCode": "EUR" }
  }
}

#レイクハウスでフラット化

プラットフォームは自動的にネストされたオブジェクトをドット記法の列にフラット化し、その後スラッグ化します：

リストオブジェクトフィールド（例：tags、options）は自動的に展開され、リスト要素ごとに1行になります。

#制限事項

• GIDsは整数ではなく文字列です。 Shopifyの識別子はgid://shopify/Resource/12345として提供されます：ダウンストリームのクエリで文字列として保持してください。
• 一括操作はサポートされていません。 非常に大きな抽出（数百万レコード）は、GraphQL APIを通じて同期的にページネーションされます。数百万行のストアの場合、bulkOperationRunQueryに対してcustom_queryを書くか、日付フィルタ（query_filter）で増分抽出を行ってください。
• Shopify Paymentsエンドポイントは登録が必要です。 payouts、disputes、balance_transactionsは、ストアでShopify Paymentsが有効になっていない場合、空のリストを返します。
• 保護された顧客データのフィールドレベル承認。 これを行わない場合、顧客/注文行はPIIフィールド（firstName、lastName、email、phone、zip）が空白になりますが、行自体は返されます。Dev Dashboardで関連するデータカテゴリを承認して、完全なPIIを取得してください。
• サブリソースにはcustom_queryが必要です。 注文ごとの取引/返金/配送と製品ごとのメタフィールドは専用のエンドポイントではありません。ネストされたGraphQLを書く場合、custom_queryでアクセス可能です。
• B2BエンドポイントはB2Bなしでは空を返します。 companies、company_locations、catalogs、price_listsはB2Bが有効になっていないストアで[]を返します。エラーは発生せず、空のリストが返されます。
• gift_cardsはShopify Plus専用です。 下位のプランはACCESS_DENIEDを受け取り、コネクタは空のリストを返します。
• エンドポイントごとのフィールドセットは固定されています。 各組み込みエンドポイントにはデフォルトのフィールド選択があります。フィールドをカスタマイズする（より多くまたは少なく）には、custom_queryを使用してください。
• Shopify GraphQLの変更履歴。 コネクタはAPIバージョン2026-04に固定されています。新しいバージョンのフィールドの名前変更や削除は自動的に取得されません。バージョンを上げる前に、Shopifyのリリースノートを確認してください。

#さらに詳しく

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

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

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

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