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, タイムスタンプ, 公開状態, ..）をリクエストします。

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に達したときに終了します。

Single-object エンドポイント (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 が返した通りの辞書型のリストとして返します。入れ子になったオブジェクト（住所、通貨セット、子配列）は保持されます。

Example product node (truncated):

{
  "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 を通じて同期的にページングされます。複数百万行のストアの場合は、custom_query を bulkOperationRunQuery に対して書くか、日付フィルタ（query_filter）で増分抽出してください。
• Shopify Payments エンドポイントは登録が必要です。 payouts、disputes、balance_transactions は、Shopify Payments がストアで有効になっていない場合、空のリストを返します。
• 保護された顧客データのフィールドレベル承認。 これを行わない場合、顧客 / 注文行は PII フィールド（firstName、lastName、email、phone、zip）が空白になりますが、行自体は返されます。Dev ダッシュボードで関連するデータカテゴリを承認して、完全な 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 のリリースノート を確認してください。

#さらに詳しく

トレーニングや技術的なサポートが必要な場合は、営業担当者にお問い合わせください。または、Professional Services ページをご覧になり、見積もりをリクエストして、専門家によるプロジェクト分析を受けてください。

Data Platformの構築チームに直接質問したり、フィードバックを送ったり、交流したりするには、専用のDiscordチャネルをご利用ください。

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

当社のユーザーコミュニティにご参加ください。