📈

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

2021/10/01に公開

GraphQL

API

Shopify

tech

この記事について

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

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

Shopify アプリのご紹介

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

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

Bulk operation APIs

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

In this section

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

OBJECTS

`BulkOperation`（`object`）

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

バルク操作は、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

Node

サンプル｜ 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
      }
    }
  }
}

MUTATIONS

`bulkOperationCancel`（`mutaition`）

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

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!]!)
ミューテーションの実行によって発生したエラーのリスト。

`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!]!)
ミューテーションの実行によって発生したエラーのリスト。

ENUMS

BulkOperationStatus (enum)

一括操作のステータス。

Values

CANCELED
キャンセルされた操作

CANCELING
キャンセル中の操作

COMPLETED
完了した操作

CREATED
作成された操作

EXPIRED
期限が切れた操作 URL

FAILED
失敗した操作

RUNNING
実行中の操作

`BulkOperationStatus` を返すタイプ

BulkOperation.status

`BulkOperationType` (`enum`)

一括操作のタイプ。

Values

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

QUERY
操作はクエリです

Shopify アプリのご紹介

Discussion

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

この記事について

Shopify アプリのご紹介

Bulk operation APIs

In this section

OBJECTS

BulkOperation（object）

Fields

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

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

実装｜ Implements

サンプル｜ Samples

MUTATIONS

bulkOperationCancel（mutaition）

Interactive example

Arguments

Return fields

bulkOperationRunMutation (mutation)

Interactive example

Arguments

Return fields

bulkOperationRunQuery (mutation)

Interactive example

Arguments

Return fields

ENUMS

Values

BulkOperationStatus を返すタイプ

BulkOperationType (enum)

Values

Shopify アプリのご紹介

Discussion

`BulkOperation`（`object`）

`bulkOperationCancel`（`mutaition`）

`bulkOperationRunMutation` (`mutation`)

`bulkOperationRunQuery` (`mutation`)

`BulkOperationStatus` を返すタイプ

`BulkOperationType` (`enum`)