# バッチジョブ

1 回のファイルアップロードで複数の API リクエストを非同期で処理します。

Batch Jobs API を使用すると、Stripe リソースに対する一括操作を実行できます。操作ごとに個別の API コールを行うと、レート制限が適用される可能性があります。代わりに、すべての操作を含むファイルをアップロードして、Stripe で非同期に処理できます。1 回限りの移行、一括更新、多数のリソースを処理する操作には、バッチジョブを使用します。

## バッチジョブを使用する状況

バッチジョブは、次の用途に適しています。

- **一括移行**: 大量のサブスクリプションを新しい請求モードに移行します。
- **大規模な更新**: 多数のアカウントまたはサブスクリプションを一度に更新します。

バッチジョブは次の用途には適していません。

- 即時の同期応答を必要とする操作。
- 厳しいタイミング要件によるリアルタイム処理
- 単一の API リクエスト。
- 顧客を作成してからそのサブスクを作成するなど、あるリクエストが別のリクエストの結果に依存する順次処理フロー。この場合は、各ステップを個別のバッチジョブとして実行します。詳細については、[複数のバッチに分けて関連オブジェクトを作成する](https://docs.stripe.com/batch-api/create.md#create-related-objects-across-batches)をご覧ください。
- 単一のバッチでの同じオブジェクトに対する複数回の更新。バッチジョブでは処理の順序が保証されないため、オブジェクトの最終的な状態は予測できません。

## バッチジョブの仕組み

各バッチジョブは 4 つのステップで構成されます。詳細については、[バッチジョブを実行する](https://docs.stripe.com/batch-api/create.md)をご覧ください。

1. [バッチジョブを作成](https://docs.stripe.com/batch-api/create.md#create-a-batch-job)し、ターゲット API エンドポイントを指定します。
2. リクエストを含む[入力ファイルをアップロードします](https://docs.stripe.com/batch-api/create.md#upload-the-input-file)。
3. Webhook またはポーリングを使用して[ジョブステータスを監視](https://docs.stripe.com/batch-api/create.md#monitor-job-status)します。
4. [結果をダウンロード](https://docs.stripe.com/batch-api/create.md#download-the-results)します。

## サポート対象のエンドポイント

Batch Jobs API は、Stripe リソース全体の多くのエンドポイントをサポートしています。各バッチジョブは 1 つのエンドポイントを対象とし、バッチ内のすべてのリクエストはそのエンドポイントに送信されます。

利用可能なエンドポイントの完全なリストについては、[サポート対象のエンドポイント](https://docs.stripe.com/batch-api/supported-endpoints.md)をご覧ください。

## 制限事項

以下の制限事項を確認してください。

- 入力ファイルは 5 GB に制限されています。これより大きいファイルを処理する場合は、複数のバッチジョブに分割します。

- バッチジョブでサポートされるのは JSONL (改行区切り JSON) ファイルのみです。CSV やその他の形式には対応していません。

- バッチ内のリクエストで使用できるのは `POST` または `DELETE` のみです。バッチジョブは `GET` に対応していません。

- バッチ内のすべてのリクエストは、同じ API エンドポイントを対象とする必要があります。

- バッチジョブでは処理の順序が保証されず、結果ファイルも入力ファイルの順序には従いません。各結果をそのリクエストと照合するには、`id` フィールドを使用します。

- バッチジョブの最大処理期間は 7 日間です。この期間を超えるジョブは `timeout` ステータスに移行し、一部の結果を利用できます。

- バッチジョブには、1 回の実行につきデフォルトで 200 万行という制限がありますが、一部の[サポート対象エンドポイント](https://docs.stripe.com/batch-api/supported-endpoints.md)には、これより低い制限が適用されます。エンドポイントの制限を超えるジョブは検証に失敗し、リクエストは一切処理されません。より多くのリクエストを処理するには、[ワークロードを順次実行するバッチジョブに分割してください](https://docs.stripe.com/batch-api/best-practices.md#split-large-workloads)。これ以上の処理能力が必要な場合は、[Stripe サポート](https://support.stripe.com/contact)にお問い合わせください。

- ジョブの完了後、結果は 30 日間ダウンロード可能です。バッチジョブを取得するたびに、Stripe から新しいダウンロード URL が返されます。

- アップロード URL はジョブの作成から 5 分後に有効期限が切れます。その後、ジョブは `upload_timeout` に移行するため、新しいジョブを作成する必要があります。

- アップロード URL に対する HTTP `PUT` リクエストで、入力ファイルをアップロードする必要があります。この URL では `POST` などのその他のメソッドは受け付けられません。
