# バッチジョブ 1 回のファイルアップロードで複数の API リクエストを非同期で処理します。 Batch Jobs API を使用すると、Stripe リソースに対して一括操作を実行できます。レート制限をトリガーする可能性のある操作ごとに個別の API コールを行う代わりに、すべての操作を含むファイルをアップロードして、Stripe に非同期で処理させることができます。1 回限りの移行、一括更新、または多くのリソースの処理が必要な操作に使用します。 ## バッチジョブを使用する状況 バッチジョブは、次の用途に適しています。 - **一括移行**: 大量のサブスクリプションを新しい請求モードに移行します。 - **大規模な更新**: 多数のアカウントまたはサブスクリプションを一度に更新します。 バッチジョブは次の用途には適していません。 - 即時の同期応答を必要とする操作。 - 厳しいタイミング要件によるリアルタイム処理 - 単一の非同期コール。 バッチジョブを処理するには、次の手順に従います。 1. [バッチジョブを作成](https://docs.stripe.com/batch-api.md#create-a-batch-job)し、ターゲット API エンドポイントを指定します。 1. [入力ファイルをアップロード](https://docs.stripe.com/batch-api.md#upload-the-input-file)して、バッチリクエストを含めます。 1. Webhook またはポーリングを使用して[ジョブステータスを監視](https://docs.stripe.com/batch-api.md#monitor-job-status)します。 1. [結果をダウンロード](https://docs.stripe.com/batch-api.md#download-the-results)します。 ## サポート対象のエンドポイント バッチジョブ API は、次のエンドポイントをサポートします。各バッチジョブは 1 つのエンドポイントを対象とし、バッチ内のすべてのリクエストはそのエンドポイントに送信されます。 | エンドポイント | パス | | -------------------------------------------------------------------------------- | ------------------------------------ | | [Update a customer](https://docs.stripe.com/api/customers/update.md) | POST `/v1/customers/:id` | | [Create a promotion code](https://docs.stripe.com/api/promotion_codes/create.md) | POST `/v1/promotion_codes` | | [Update a promotion code](https://docs.stripe.com/api/promotion_codes/update.md) | POST `/v1/promotion_codes/:id` | | [サブスクリプションの移行](https://docs.stripe.com/api/subscriptions/migrate.md) | POST `/v1/subscriptions/:id/migrate` | | [サブスクリプションを更新する](https://docs.stripe.com/api/subscriptions/update.md) | POST `/v1/subscriptions/:id` | ## 制限事項 以下の制限事項を確認してください。 - バッチファイルは 5 GB に制限されています。大量のリクエストに対して大きなファイルを処理する必要がある場合は、複数のバッチに分割してください。 - バッチジョブは JSONL (改行区切り JSON) ファイルのみサポートしています。バッチジョブは CSV やその他の形式は受け付けません。 - バッチ内のリクエストは `POST` または `DELETE` のみを使用できます。バッチジョブは `GET` をサポートしていません。 - バッチ内のすべてのリクエストは、同じ API エンドポイントを対象とする必要があります。 - バッチジョブはリクエスト処理の順序を保証しません。 - バッチジョブの最大処理時間は 24 時間です。この時間を超えるジョブは `timeout` ステータスに移行し、一部の結果を利用できます。 - 結果は、ジョブの完了後 7 日間ダウンロードできます。 - アップロード URL はジョブの作成から 5 分後に有効期限が切れます。その後、ジョブは `upload_timeout` に移行するため、新しいジョブを作成する必要があります。 - 事前署名された URL に、直接 HTTP `PUT` リクエストでファイルをアップロードします。 ## バッチジョブの作成 まず、`POST` リクエストを `/v2/core/batch_jobs` に送信してバッチジョブを作成します。ターゲットエンドポイントと処理オプションを指定します。 ```bash curl https://api.stripe.com/v2/core/batch_jobs \ -u <>: \ -H "Content-Type: application/json" \ -H "Stripe-Version: 2026-03-25.preview" \ -d '{ "endpoint": { "path": "/v1/subscriptions/:id/migrate", "http_method": "post" }, "maximum_rps": 10, "skip_validation": false }' ``` このリクエストのコンテンツタイプは JSON ファイルです。これにより、`ready_for_upload` ステータスのバッチジョブオブジェクトが返されます。アップロード URL とその有効期限は `status_details` フィールドにあります。 ```json { "id": "batchv2_AbCdEfGhIjKlMnOpQrStUvWxYz", "object": "v2.core.batch_job", "created": "2026-03-09T20:55:31.000Z", "maximum_rps": 10, "skip_validation": false, "status": "ready_for_upload", "status_details": { "ready_for_upload": { "upload_url": { "expires_at": "2026-03-09T21:00:31.000Z", "url": "https://stripeusercontent.com/files/upload/..." } } } } ``` `status_details` オブジェクトは、現在のステータスに応じて変化します。ジョブが `ready_for_upload` の場合は、事前署名付きアップロード URL とその有効期限のタイムスタンプが含まれます。 ### パラメーター | パラメーター | 必須 | 説明 | | -------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `endpoint.path` | はい | ターゲットにする API エンドポイント (`/v1/subscriptions/:id/migrate` など)。[サポート対象エンドポイント](https://docs.stripe.com/batch-api.md#supported-endpoints)をご覧ください。 | | `endpoint.http_method` | はい | エンドポイントの HTTP メソッド。現在、`post` のみがサポートされています。 | | `maximum_rps` | いいえ | 1 秒あたりに処理されるリクエストの最大数 (1 ～ 100)。デフォルトは 10 です。 | | `skip_validation` | いいえ | 入力ファイルの検証をスキップし、直ちに処理を開始するには、`true` に設定します。デフォルトは `false` です。 | | `notification_suppression` | いいえ | 基盤となる API 操作からの Webhook を送信するかどうかを制御します。操作レベルの Webhook を抑制するには、`{"scope": "all"}` を設定します。バッチレベルのイベントは、この設定に関係なく常に配信されます。デフォルトは `{"scope": "none"}` です。 | | `metadata` | いいえ | 内部追跡のキーと値のペア。メタデータは、失敗イベントなどのバッチジョブイベントに含まれます。 | ## 入力ファイルをアップロードする バッチジョブを作成したら、`status_details.ready_for_upload.upload_url.url` の URL に入力ファイルをアップロードします。ファイルの内容を指定した `PUT` リクエストを使用します。 ```bash curl {UPLOAD_URL} \ -X PUT \ -T input.jsonl \ -H "Content-Type: application/jsonlines" ``` このリクエストの入力ファイルは JSONL ファイルで、コンテンツタイプは `application/octet-stream` である必要があります。アップロードが完了すると、Stripe は自動的に処理を開始します。個別の `start` ステップはありません。 アップロード URL は、バッチジョブの作成後 5 分で有効期限が切れます。正確な期限については、`expires_at` フィールドを確認してください。ファイルをアップロードする前に URL の有効期限が切れた場合、ジョブのステータスは `upload_timeout` に変わり、新しいバッチジョブを作成する必要があります。バッチジョブを作成する前に入力ファイルを生成し、すばやくアップロードできるようにします。 ### 入力ファイル形式 ファイルは UTF-8 エンコードで、JSONL 形式 (改行区切りの JSON、1 行に 1 つのオブジェクト) を使用する必要があります。各行は、ターゲットエンドポイントへの 1 つの API リクエストを表します。CSV やその他の形式はサポートされません。 各 JSON オブジェクトは、次のフィールドをサポートしています。 | フィールド | 必須 | 説明 | | ------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- | | `id` | はい | このリクエストを結果と関連付ける一意の識別子。パスパラメータの ID とエンドポイントの ID は一致している必要がありますが、ユーザーが名前を指定する方法を自由に選択できます。`/^[A-Za-z0-9_-]+$/` と一致する必要があります。 | | `path_params` | 条件付き | エンドポイントのパスパラメータ。エンドポイントパスにプレースホルダー (`:id` など) が含まれる場合に必要です。`path_params` のキーは、エンドポイントパスのプレースホルダーと正確に一致する必要があります。 | | `params` | いいえ | API コールのリクエスト本文パラメータ。API メソッドによって異なる場合があります。 | | `context` | いいえ | Stripe アカウント ID。連結アカウントなどの特定のアカウントに対してリクエストを実行する場合に使用します。 | ### 入力ファイルの例 #### API メソッド - POST /v1/customers/:id `POST /v1/customers/:id` エンドポイントの場合: ```json {"id": "req_001", "path_params": {"id": "cus_1AbCdEfGhIjKlMn"}, "params": {"name": "Jenny Rosen", "email": "jenny@example.com"}} {"id": "req_002", "path_params": {"id": "cus_2BcDeFgHiJkLmNo"}, "params": {"name": "John Smith", "metadata": {"tier": "premium"}}} {"id": "req_003", "context": "acct_1234567890", "path_params": {"id": "cus_3CdEfGhIjKlMnOp"}, "params": {"description": "Updated by batch"}} ``` #### API メソッド - POST /v1/subscriptions/:id/migrate `POST /v1/subscriptions/:id/migrate` エンドポイントの場合: ```json {"id": "req_001", "path_params": {"id": "sub_1AbCdEfGhIjKlMn"}, "params": {"billing_cycle_anchor": "unchanged", "proration_behavior": "none"}} {"id": "req_002", "path_params": {"id": "sub_2BcDeFgHiJkLmNo"}, "params": {"billing_cycle_anchor": "unchanged", "proration_behavior": "create_prorations"}} ``` #### API メソッド - POST /v1/subscriptions/:id `POST /v1/subscriptions/:id` エンドポイントの場合: ```json {"id": "req_001", "path_params": {"id": "sub_1AbCdEfGhIjKlMn"}, "params": {"description": "Updated subscription description"}} {"id": "req_002", "path_params": {"id": "sub_2BcDeFgHiJkLmNo"}, "params": {"metadata": {"migration_batch": "v2"}}} {"id": "req_003", "path_params": {"id": "sub_3CdEfGhIjKlMnOp"}, "params": {"cancel_at_period_end": true}} ``` #### API メソッド - POST /v1/promotion_codes `POST /v1/promotion_codes` エンドポイントの場合: ```json {"id": "req_001", "params": {"coupon": "25OFF", "code": "SUMMER25"}} {"id": "req_002", "params": {"coupon": "50OFF", "code": "WINTER50", "max_redemptions": 100}} ``` #### API メソッド - POST /v1/promotion_codes/:id `POST /v1/promotion_codes/:id` エンドポイントの場合: ```json {"id": "req_001", "path_params": {"id": "promo_1AbCdEfGhIjKlMn"}, "params": {"active": false}} {"id": "req_002", "path_params": {"id": "promo_2BcDeFgHiJkLmNo"}, "params": {"metadata": {"tier": "premium"}}} ``` 各 `id` は、ファイル内で一意である必要があります。結果ファイルは入力ファイルと同じ順序ではないため、Stripe はこれを使用してリクエストと結果を関連付けます。 ## ジョブのステータスを監視する バッチジョブは、取得エンドポイントをポーリングするか、[Webhook イベント](https://docs.stripe.com/batch-api.md#webhook-events)をリッスンすることで追跡できます。本番環境の組み込みには Webhook イベントを使用することをお勧めします。 ### ステータスのポーリング ```bash curl https://api.stripe.com/v2/core/batch_jobs/{BATCH_JOB_ID} \ -u <>: \ -H "Stripe-Version: 2026-03-25.preview" ``` このリクエストのコンテンツタイプは json ファイルです。ジョブの実行中は、`status_details` にリアルタイムの進捗状況が表示されます。 ```json { "status": "in_progress", "status_details": { "in_progress": { "success_count": "1", "failure_count": "0" } } } ``` `検証`フェーズでは、`status_details` には、Stripe がこれまでに検証した行数を示す `validated_count` フィールドが含まれます。 バッチジョブの API コールは、Stripe ダッシュボードまたはワークベンチのリクエストログに表示されます。基になる API コールはリクエストログに表示されません。取得エンドポイントまたは Webhook イベントを使用して進捗を監視します。個別のリクエストの失敗をデバッグするには、結果ファイルを確認してください。 ### ジョブのライフサイクル 入力ファイルをアップロードすると、バッチジョブは次のステータスで進行します。 | ステータス | 説明 | | ------------------ | ------------------------------------------------------------------------------- | | `ready_for_upload` | バッチジョブが作成され、入力ファイルを待機しています。 | | `validating` | 入力ファイルがアップロードされ、Stripe がそのファイルを検証しています。`skip_validation` が `true` の場合はスキップされます。 | | `in_progress` | 検証が成功 (またはスキップ) し、Stripe がリクエストを処理しています。 | | `complete` | すべてのリクエストが処理されました。結果はダウンロードできます。 | | `cancelling` | キャンセルがリクエストされました。Stripe は処理中のリクエストを完了させています。 | ### Terminal ステータス | ステータス | 説明 | | ------------------- | ---------------------------------------------------------------------------------------------------------------- | | `validation_failed` | 入力ファイルにエラーが含まれています。リクエストは処理されませんでした。エラーの詳細については、バッチジョブオブジェクトを確認してください。これは、`skip_validation: false` の場合にのみ適用されます。 | | `batch_failed` | 処理中に予期しないエラーが発生しました。 | | `cancelled` | バッチジョブがキャンセルされました。一部の結果が利用可能な場合があります。 | | `upload_timeout` | ファイルがアップロードされる前にアップロード URL の有効期限が切れました。新しいバッチジョブを作成してください。 | | `timeout` | バッチジョブが最大処理時間である 24 時間を超えました。一部の結果が利用可能な場合があります。 | ### 検証 `skip_validation` が `false`(デフォルト)の場合、Stripe はリクエストを処理する前に入力ファイル全体を検証します。この検証により、次のようなエラーが検出されます。 - いずれかの行に無効な JSON がある - `id` フィールドがないか無効です。 - ID が重複しています。 - ターゲットエンドポイントに必要な `path_params` がありません。 - パラメータの形式が正しくありません。 検証が失敗すると、ステータスは `validation_failed` に変わり、Stripe はリクエストを試行しません。バッチジョブオブジェクトには、最初に発生したエラーの詳細が含まれます。 `skip_validation` が `true` の場合、アップロード後にジョブは `ready_for_upload` から `in_progress` へ直接移行します。個々のリクエストのエラーは、バッチ全体をブロックするのではなく、結果ファイルに表示されます。 ## 結果をダウンロードする バッチジョブが `complete` ステータスに達すると、`status_details` フィールドには、成功と失敗のサマリーと、出力ファイルの事前署名済みダウンロード URL が含まれます。 ```json { "id": "batchv2_AbCdEfGhIjKlMnOpQrStUvWxYz", "object": "v2.core.batch_job", "created": "2026-03-09T20:55:31.000Z", "maximum_rps": 10, "skip_validation": true, "status": "complete", "status_details": { "complete": { "success_count": "2", "failure_count": "0", "output_file": { "content_type": "application/jsonlines", "size": "8514", "download_url": { "expires_at": "2026-03-09T22:05:31.000Z", "url": "https://stripeusercontent.com/files/download/..." } } } } } ``` `status_details.complete.output_file.download_url.url` の URL を使用してファイルをダウンロードします。Stripe は、バッチジョブが次のいずれかの状態になると出力ファイルを提供します。 - `complete` - `cancelled` - `timeout` - `validation_failed` ダウンロード URL の有効期限を確認するには、`expires_at` フィールドで期限を確認します。 結果ファイルには、成功したリクエストと失敗したリクエストの両方が 1 つのファイルに含まれています。失敗を見つけるには、`status` が `200` 以外の行でフィルタリングします。 ### 結果のファイル形式 出力ファイルは JSONL 形式 (1 行に 1 つの JSON オブジェクト) を使用します。各行には次のフィールドが含まれます。 | フィールド | 説明 | | ---------- | ------------------------------------------------------- | | `id` | 入力ファイルのリクエスト ID。これを使用して、結果をリクエストと照合します。 | | `response` | 完全な API レスポンスオブジェクト。成功した場合はリソース、失敗した場合はエラーオブジェクトが含まれます。 | | `status` | HTTP ステータスコードを整数で指定します (`200`、`402` など)。 | ### 結果ファイルの例 リクエストが成功すると、API リソース全体が `response` フィールドに返されます。 ```json {"id": "req_001", "response": {"id": "sub_1AbCdEfGhIjKlMn", "object": "subscription", "status": "active", "billing_cycle_anchor": 1710021331, "current_period_end": 1712613331, "current_period_start": 1710021331}, "status": 200} {"id": "req_002", "response": {"id": "sub_2BcDeFgHiJkLmNo", "object": "subscription", "status": "active", "billing_cycle_anchor": 1710021331, "current_period_end": 1712613331, "current_period_start": 1710021331}, "status": 200} ``` 失敗したリクエストはエラーオブジェクトを返します。 ```json {"id": "req_003", "response": {"error": {"message": "This subscription cannot be migrated because it is not active. Current status is canceled.", "type": "invalid_request_error", "code": "resource_invalid_state"}}, "status": 400} ``` 結果は入力ファイルと同じ順序では返されません。`id` フィールドを使用して、各結果を対応するリクエストと照合します。 ## バッチジョブをキャンセルする まだ完了していないバッチジョブをキャンセルするには、`POST` リクエストを送信します。 ```bash curl https://api.stripe.com/v2/core/batch_jobs/{BATCH_JOB_ID}/cancel \ -u <>: \ -X POST \ -H "Stripe-Version: 2026-03-25.preview" ``` キャンセルは非同期で行われます。ジョブはまず、処理中のリクエストが完了する間 `cancelling` に移行し、その後 `cancelled` に移行します。キャンセル前に処理されたリクエストの一部の結果は、結果ファイルで確認できます。 ## Webhook イベント バッチジョブは、ライフサイクルの移行ごとに v2 シンイベントを送信します。これらのイベントを受信するには、[v2 イベント送信先](https://docs.stripe.com/event-destinations.md)を設定する必要があります。 バッチジョブイベントには、v2 イベントの送信先が必要です。これらは v1 Webhook エンドポイントには配信されません。 次のイベントを使用できます。 | イベントタイプ | 説明 | | ------------------------------------- | --------------------------------------- | | `v2.core.batch_job.created` | バッチジョブが作成されました。 | | `v2.core.batch_job.ready_for_upload` | バッチジョブでファイルをアップロードする準備ができました。 | | `v2.core.batch_job.validating` | ファイルのアップロードが完了しました。検証中です。 | | `v2.core.batch_job.validation_failed` | 入力ファイルの検証に失敗しました。 | | `v2.core.batch_job.completed` | すべてのリクエストが処理されました。 | | `v2.core.batch_job.batch_failed` | バッチジョブが予期せず失敗しました。 | | `v2.core.batch_job.canceled` | バッチジョブがキャンセルされました。 | | `v2.core.batch_job.timeout` | バッチジョブが最大処理時間を超えました。 | | `v2.core.batch_job.upload_timeout` | ファイルがアップロードされる前にアップロード URL の有効期限が切れました。 | | `v2.core.batch_job.updated` | バッチジョブのステータスまたは進捗状況が変更されました。 | すべてのバッチジョブイベントには、ジョブの作成時に指定したメタデータが含まれます。これを使用して、イベントを内部システムと関連付けることができます。 `notification_suppression`が `{"scope": "all"}`に設定されている場合、基本となる API 操作 (サブスクリプション更新イベントなど) からの Webhook は抑制されます。上記のバッチレベルのイベントは、この設定に関係なく常に配信されます。 ## 一般的なエラー ### アップロード URL の有効期限が切れています `expires_at` タイムスタンプ (ジョブ作成から 5 分後) までに入力ファイルをアップロードしない場合、バッチジョブは `upload_timeout` ステータスに移行します。新しいバッチジョブを作成し、速やかにファイルをアップロードしてください。これを回避するには、バッチジョブを作成する前に入力ファイルを生成してください。 ### 無効なリソース状態 ターゲットリソースが想定された状態でない場合、個々のリクエストが失敗する可能性があります。たとえば、`/v1/subscriptions/:id/migrate` を使用する場合、次のようになります。 - **サブスクリプションは有効ではありません**: サブスクリプションを移行するには、`active` 状態である必要があります。キャンセル済みまたは不完全なサブスクリプションでは、`resource_invalid_state` を伴う `400` エラーが返されます。 - **サブスクリプションがすでに移行されています**: すでに移行されているサブスクリプションを移行しようとすると、エラーが返されます。 リクエストごとのこれらのエラーは、結果ファイルに `200` 以外のステータスコードで示されます。バッチジョブ自体は正常に完了します (個々の行が失敗しても、バッチは処理を続行します)。 ### パスパラメータの不一致 `path_params` のキーは、エンドポイントパスのプレースホルダーと完全に一致している必要があります。たとえば、エンドポイントパスが `/v1/subscriptions/:id/migrate` の場合、`path_params` では`{"id": "sub_..."}`を使用する必要があります。プレースホルダー名とキーが一致しないと、検証エラーが発生したり、結果ファイルで `400` ステータスになったりします。 ### アップロードコンテンツタイプ アップロードの `PUT` リクエストでは、`Content-Type: application/octet-stream` を使用する必要があります。その他のコンテンツタイプは拒否されます。 ### ファイル形式のエラー `skip_validation` が`false` の場合、これらのエラーによりバッチ全体が `validation_failed` ステータスで失敗します。 - 有効な JSON ではない行 - 行に `id` フィールドがありません - 行間で `id` 値が重複しています - `A-Za-z0-9_-` 以外の文字を含む ID `skip_validation` が `true` の場合、ファイルレベルの形式エラーにより、バッチ全体がブロックされるのではなく、個々の行が失敗する可能性があります。 ### ジョブ処理のタイムアウト 24 時間を超えて実行されるバッチジョブは、`timeout` ステータスに移行します。タイムアウト前に完了したリクエストの部分的な結果は、結果ファイルで確認できます。 ## ベストプラクティス ### 適切な `maximum_rps` を選択 `maximum_rps` パラメーターは、Stripe がバッチでリクエストを処理する速度を制御します。バッチ処理では、メインの API リクエストとは別のレート制限プールが使用されるため、バッチジョブがアカウントの通常の API トラフィックに影響を与えることはありません。 - **小さい値**: 1 ～ 10 は、緊急ではない一括操作に適しています。 - **高い値**: 50 ～ 100 はバッチを迅速に処理し、さまざまなリソースにまたがる独立した操作に適しています。 ### 重要な操作に検証を使用する 部分的な処理が問題を引き起こす操作については、`skip_validation` を `false` (デフォルト) に設定してください。検証により、リクエストが実行される前にファイル全体が適切な形式になります。 入力データをすでに検証していて、ジョブのスタートアップを高速化する場合、または部分的な結果の処理が許容される場合は、`skip_validation` を`true` に設定します。 ### 大規模なワークロードを分割 5 GB を超える入力ファイルがある場合は、ワークロードを複数のバッチジョブに分割してください。複数のバッチジョブを同時に実行できます。 ### バッチ処理の前にリソースの状態を確認する バッチを送信する前に、すべてのターゲットリソースが必要な状態にあることを確認します。たとえば、サブスクリプションは、`/v1/subscriptions/:id/migrate` で移行する前にアクティブである必要があります。バッチジョブはターゲット操作を直接実行し、前提条件としてリソースの状態を変更しません。 ### 結果のエラーを処理する 各結果行の `status` フィールドを必ず確認してください。成功したバッチ内でも、個々のリクエストは失敗する可能性があります (たとえば、資金不足や無効なパラメータが原因です)。結果ファイルで `200` 以外のステータスを絞り込んで、それに応じて失敗を処理できるように組み込みを構築してください。 ### ジョブを作成する前にファイルを準備する アップロード URL は、バッチジョブの作成から 5 分後に有効期限が切れます。create エンドポイントを呼び出す前に、入力ファイルを生成し、検証します。データを動的に準備する必要がある場合は、最初にすべてのデータ取得とファイル生成を完了してから、バッチジョブを作成し、すぐにアップロードします。