📈

【Shopify.dev和訳】AdminAPI/GraphQL reference/Bulk operations

2021/10/01に公開約13,900字

この記事について

この記事は、AdminAPI/GraphQL reference/Bulk operationsの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Bulk operation APIs

一括操作を作成および管理します。

In this section

  • BulkOperation - データを一括でフェッチするための非同期の長時間実行操作。一括操作は、bulkOperationRunQueryミューテーションを使用して作成されます。それらが作成された後、クライアントは更新のためにstatusフィールドをポーリングする必要があります。 COMPLETEDの場合、urlフィールドには JSONL 形式のデータへのリンクが含まれます。詳細については、一括操作ガイドを参照してください。
  • BulkOperationStatus — 一括操作のステータス。
  • BulkOperationType — 一括操作のタイプ。
  • BulkOperationCancel — 実行中の一括操作のキャンセルプロセスを開始します。キャンセルが開始されてから実際に操作がキャンセルされるまで、少し時間がかかる場合があります。
  • BulkOperationRunMutation — 一括操作ミューテーションを作成して実行します。大量のデータを非同期で一括インポートする方法については、一括インポートデータガイドを参照してください。
  • BulkOperationRunQuery — 一括操作クエリを作成して実行します。詳細については、一括操作ガイドを参照してください。

https://shopify.dev/api/admin/graphql/reference/bulk-operations

OBJECTS

BulkOperationobject

データを一括でフェッチするための非同期の長時間実行操作です。

バルク操作は、bulkOperationRunQueryミューテーションを使用して作成されます。それらが作成された後、クライアントは更新のためにstatusフィールドをポーリングする必要があります。 COMPLETEDの場合、urlフィールドには JSONL 形式のデータへのリンクが含まれます。

詳細については、一括操作ガイドを参照してください。

Fields

completedAt (DateTime)
一括操作が正常に完了したとき。

createdAt (DateTime!)
一括操作が作成されたとき。

errorCode (BulkOperationErrorCode)
失敗した操作のエラーコード。

fileSize (UnsignedInt64)
urlフィールドのファイルのバイト単位のファイルサイズ。

id (ID!)
グローバル一意の識別子。

objectCount (UnsignedInt64!)
処理されたすべてのオブジェクトの実行カウント。たとえば、すべての商品とそのバリエーションを取得する場合、このフィールドは商品とバリエーションの両方をカウントします。このフィールドは、操作の進行状況を追跡するために使用できます。

partialDataUrl (URL)
失敗した操作によって返された部分的/不完全な応答データ(JSONL形式)への URL。操作が失敗してから 1 週間で有効期限が切れます。使用可能なデータがない場合は null を返します。

query (String!)
BulkOperationRunQuery で指定された GraphQL クエリドキュメント。

rootObjectCount (UnsignedInt64!)
クエリのルートで処理されたすべてのオブジェクトの実行カウント。たとえば、すべての商品とそのバリエーションを取得する場合、このフィールドは商品のみをカウントします。このフィールドは、操作の進行状況を追跡するために使用できます。

status (BulkOperationStatus!)
一括操作のステータス。

url (URL)
JSONL形式の応答データへの URL。操作が完了してから 1 週間で有効期限が切れます。

BulkOperation を返すタイプ| Types that return BulkOperation

QueryRoot.currentBulkOperation

BulkOperation のミューテーション| Mutations for BulkOperation

bulkOperationCancel
実行中の一括操作のキャンセルプロセスを開始します。
キャンセルが開始されてから実際に操作がキャンセルされるまで、少し時間がかかる場合があります。

bulkOperationRunMutation
一括操作ミューテーションを作成して実行します。
大量のデータを非同期で一括インポートする方法については、一括インポートデータガイドを参照してください。

bulkOperationRunQuery
一括操作クエリを作成して実行します。
詳細については、一括操作ガイドを参照してください。

実装| Implements

サンプル| Samples

Query
# バルクオペレーションの状態を取得する
{
  currentBulkOperation {
    status
  }
}
Response
{
  "data": {
    "currentBulkOperation": {
      "status": "COMPLETED"
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "actualQueryCost": 1,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 999,
        "restoreRate": 50
      }
    }
  }
}
Query
# 処理されたすべてのオブジェクトのカウントを取得する
{
  currentBulkOperation {
    objectCount
  }
}
Response
{
  "data": {
    "currentBulkOperation": {
      "objectCount": "1001"
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "actualQueryCost": 1,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 999,
        "restoreRate": 50
      }
    }
  }
}
Query
# クエリのルートで処理されたすべてのオブジェクトの実行カウントを取得する
{
  currentBulkOperation {
    rootObjectCount
  }
}
Response
{
  "data": {
    "currentBulkOperation": {
      "objectCount": "1001"
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "actualQueryCost": 1,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 999,
        "restoreRate": 50
      }
    }
  }
}
Query
# 一括操作の開始・終了時刻の問い合わせ
{
  currentBulkOperation {
    createdAt
    completedAt
  }
}
Response
{
  "data": {
    "currentBulkOperation": {
      "createdAt": "2021-09-03T18:59:31Z",
      "completedAt": "2021-09-03T18:59:49Z"
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "actualQueryCost": 1,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 999,
        "restoreRate": 50
      }
    }
  }
}
Query
# Poll a running query
{
  currentBulkOperation {
    id
    status
    errorCode
    createdAt
    completedAt
    objectCount
    fileSize
    url
    partialDataUrl
  }
}
Response
{
  "data": {
    "currentBulkOperation": {
      "id": "gid://shopify/BulkOperation/339073073174",
      "status": "COMPLETED",
      "errorCode": null,
      "createdAt": "2021-09-03T18:59:31Z",
      "completedAt": "2021-09-03T18:59:49Z",
      "objectCount": "1001",
      "fileSize": "1003561",
      "url": "https://storage.googleapis.com/shopify-tiers-assets-prod-us-east1/yhuadf4nstib7oj5mna24z43mb2y?GoogleAccessId=assets-us-prod%40shopify-tiers.iam.gserviceaccount.com&Expires=1631300389&Signature=fpsTV66EbhjdpKdD%2B2PZfbazW73sasZKmzOy%2FjHtAd%2FasLnW0yAhc96xkA51h%2FIdPVmDAB0uEQtMBANwKUQEtBnVodk2ihGVHDEkFtA0W1gAiPZQddSZB36utRi5OnRVXQAWLPdz9lYn4hbN7FSwx9J7X9ZW4zIzUPM288OmV9eK3wowR2v0e3joql0y82%2B6W04gfgwKv8FlLqojH9oEGXJ5aaFMvmZV1pWeHX61eQFS6uigb01SYeEfAbfR605%2F60G%2BsTA%2F%2FeuDHy2MDg08593bJcjFuaDKC5cWj4dMPz%2B9d96YC%2F8xvHNB4kDsYwWj2SCN5Ojb8gsv8rBCLcanJg%3D%3D&response-content-disposition=attachment%3B+filename%3D%22bulk-339073073174.jsonl%22%3B+filename%2A%3DUTF-8%27%27bulk-339073073174.jsonl&response-content-type=application%2Fjsonl",
      "partialDataUrl": null
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "actualQueryCost": 1,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 999,
        "restoreRate": 50
      }
    }
  }
}

https://shopify.dev/api/admin/graphql/reference/bulk-operations/bulkoperation

MUTATIONS

bulkOperationCancelmutaition

実行中の一括操作のキャンセルプロセスを開始します。
キャンセルが開始されてから実際に操作がキャンセルされるまで、少し時間がかかる場合があります。

Interactive example

これはミューテーションクエリの例です。以下の埋め込みインタラクティブツールを使用して、クエリを編集します。

Mutation
mutation bulkOperationCancel($id: ID!) {
  bulkOperationCancel(id: $id) {
    bulkOperation {
      id
    }
    userErrors {
      field
      message
    }
  }
}
Variables
{
  "id": "Z2lkOi8vU2hvcGlmeS9FeGFtcGxlLzE="
}

Arguments

Argument Description
id (ID!) required キャンセルする一括操作の ID

Return fields

bulkOperation (BulkOperation)
キャンセルするための一括操作。

userErrors ([UserError!]!)
ミューテーションの実行によって発生したエラーのリスト。

bulkOperationRunMutation (mutation)

一括操作ミューテーションを作成して実行します。
大量のデータを非同期で一括インポートする方法については、一括インポートデータガイドを参照してください。

Interactive example

これはミューテーションクエリの例です。以下の埋め込みインタラクティブツールを使用して、クエリを編集します。

Mutation
mutation bulkOperationRunMutation($mutation: String!, $stagedUploadPath: String!) {
  bulkOperationRunMutation(
    mutation: $mutation
    stagedUploadPath: $stagedUploadPath
  ) {
    bulkOperation {
      id
    }
    userErrors {
      code
      field
      message
    }
  }
}
Variables
{
  "mutation": "placeholder",
  "stagedUploadPath": "placeholder"
}

Arguments

Argument Description
clientIdentifier ( String ) クエリに使用できるオプションの識別子
mutation ( String! ) required 一括で実行されるミューテーション
stagedUploadPath ( String! ) required ミューテーション変数を含むファイルの段階的なアップロードパス

Return fields

bulkOperation (BulkOperation)
新しく作成された一括操作。

userErrors ([BulkMutationUserError!]!)
ミューテーションの実行によって発生したエラーのリスト。

https://shopify.dev/api/admin/graphql/reference/bulk-operations/bulkoperationcancel

bulkOperationRunQuery (mutation)

一括操作クエリを作成して実行します。
詳細については、一括操作ガイドを参照してください。

Interactive example

これはミューテーションクエリの例です。以下の埋め込みインタラクティブツールを使用して、クエリを編集します。

Mutation
mutation bulkOperationRunQuery($query: String!) {
  bulkOperationRunQuery(query: $query) {
    bulkOperation {
      id
    }
    userErrors {
      field
      message
    }
  }
}
Variables
{
  "query": "placeholder"
}

Arguments

Argument Description
query ( String! ) required 一括で実行されるクエリ。

Return fields

bulkOperation (BulkOperation)
新しく作成された一括操作。

userErrors ([UserError!]!)
ミューテーションの実行によって発生したエラーのリスト。

https://shopify.dev/api/admin/graphql/reference/bulk-operations/bulkoperationrunquery

ENUMS

BulkOperationStatus (enum)

https://shopify.dev/api/admin/graphql/reference/bulk-operations/bulkoperationstatus

一括操作のステータス。

Values

CANCELED
キャンセルされた操作

CANCELING
キャンセル中の操作

COMPLETED
完了した操作

CREATED
作成された操作

EXPIRED
期限が切れた操作 URL

FAILED
失敗した操作

RUNNING
実行中の操作

BulkOperationStatus を返すタイプ

https://shopify.dev/api/admin/graphql/reference/bulk-operations/bulkoperationstatus

BulkOperationType (enum)

一括操作のタイプ。

Values

MUTATION
操作はミューテーションです

QUERY
操作はクエリです

https://shopify.dev/api/admin/graphql/reference/bulk-operations/bulkoperationtype

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます