Bulk API 2.0 パターン(インテグレーション)

このスキルは、インテグレーション エンジニア、ETL 作成者、またはミドルウェア開発者が 長時間実行される Bulk API 2.0 パイプラインを信頼性の高いものにする 必要がある場合に機能します。単に REST 呼び出しを発行するのではなく、ジョブの作成、データアップロード、必須のクローズ信号、非同期処理、結果取得、および安全な再試行をコーディネートします。Bulk API 2.0 は非同期です。成功した内部バッチは、他のバッチが失敗した場合でもロールバックされません。そのため、インテグレーション設計は、結果を レコード単位およびバッチ単位 として扱う必要があり、単一のアトミックなトランザクションとしては扱いません。この非対称性が、チームが「ジョブが失敗したからデータが一切到達しなかった」と想定する場合や、ジョブを Open から処理へ移行するステップを省略する場合に、大多数の本番インシデントを引き起こします。

プラットフォームは .../jobs/ingest/ の下にインジェストジョブを公開し、.../jobs/query/ の下にクエリジョブを公開しています。インジェストの場合、CSV データが PUT でジョブのデータ URL にアップロードされた後、PATCH でジョブ リソースに {"state":"UploadComplete"} を送信する 必要があります 。これにより Salesforce は処理を開始できます。このリクエストをスキップすると、ジョブは無期限に待機したままになります。明示的なクライアント信号の代替となるバックグラウンド タイムアウトはありません。マルチパート ジョブ作成は例外です。ジョブ メタデータと CSV を multipart/form-data としてまとめて POST する場合、Salesforce はアップロード フェーズを自動的に完了し、手動で UploadComplete を設定する必要はありません。マルチパートは、ペイロード サイズがドキュメントに記載されているマルチパート制限に適合する場合のみ選択してください。より大きい読み込みは、標準の create → upload → UploadComplete シーケンスを使用する必要があります。

運用上の制限は、インテグレーション設計時に重要です。Salesforce は最大 10,000 レコードの内部バッチを作成し、ローリング ウィンドウごとに org あたりの合計処理ボリュームを制限します(公式ガイドの Bulk API 2.0 制限 を参照)。各アップロード PUT は、ガイドで説明されている要求ごとのサイズ上限以下でなければなりません(base64 関連のガイダンスを含む)。制限を超えると、バッチの失敗またはスロットリングが発生します。コネクタは、ファイル全体を静かに再開始するのではなく、numberRecordsFailed、numberRecordsProcessed、およびエラー結果ファイルを表示する必要があります。

クエリ ジョブの場合、結果はページング CSV として到着します。ページを走査する唯一のサポートされている方法は、各 GET .../results 呼び出しから Sforce-Locator 応答ヘッダーを読み取り、そのオペーク トークンを次の呼び出しの locator クエリ パラメータとして渡し、ヘッダーの値がリテラル文字列 null になったら停止することです。ロケータ値を推測するか、ペジネーションを省略すると、抽出の一部がプラットフォームから外れます。

data/bulk-api-patterns は主なニーズが呼び出しレベルのリクエスト/レスポンス例、CSV 文法、または v1 対 v2 の比較である場合に使用します。integration/real-time-vs-batch-integration は、一括が適切か対イベントまたは同期 callout であるかが問題である場合に使用します。このインテグレーション スキルは コネクタ動作 に焦点を当てています。冪等性キー(通常はアップサート外部 ID)、複数ジョブ読み込みのシーケンシング、InProgress でのバックオフ、および successfulResults、failedResults、および unprocessedRecords の解析により次のアップロード ファイルを構築します。

---

開始する前に

このドメイン内のあらゆるものに取り組む前に、次のコンテキストを収集してください:

コンテキスト	収集する内容
認証およびインスタンス URL	OAuth アクセス トークン、API バージョン セグメント(例: v66.0)、および contentUrl で返されるすべての後続ジョブ URL 用の正しい My Domain ベース URL。
アップロード パス	シングルパート CSV PUT シーケンス対マルチパート POST create — マルチパートは設計上、手動の UploadComplete をスキップします。
失敗セマンティクス	ダウンストリーム システムが部分的成功を許容できるかどうか。できない場合、補償トランザクションは Salesforce の 外 に存在する必要があります。一括コミットはオール・オア・ナッシングではないためです。
最も一般的な誤った仮定	ジョブの作成と CSV のストリーミングは処理開始に充分だと思うこと。UploadComplete(非マルチパート)がないと、何も InProgress に入りません。
対象の制限	日次処理レコード上限、リクエストごとのペイロード サイズ、およびサポートされている maxRecords によるクエリ ページ サイズ — 使用中の API バージョン用に現在の 制限と割り当て トピックをクロスチェックします。

---

コア コンセプト

インジェスト ジョブ ステート マシン(インテグレーション ビュー)

インテグレータの観点から、インジェスト ジョブは Open → UploadComplete → InProgress → JobComplete | Failed | Aborted を移動します。Open は追加の PUT アップロードが contentUrl に送信される可能性があることを意味します。UploadComplete はクライアントがアップロード完了を宣言したことを意味します。Salesforce はそのジョブにはもうデータを受け付けません。InProgress は自動バッチングとレコード操作実行に該当します。JobComplete は処理が完了したことを意味します。すべての行が成功したという意味ではなく、結果 CSV をダウンロードして数とエラーを検査してください。Failed はジョブが繰り返される内部試行後に完了できなかったことを示します(行レベルの検証エラーとは別)。Aborted は許可される場合のオペレータ主導のキャンセルです。

部分的成功と再試行スコープ

一部の行がバリデーションに失敗するか行レベルのエラーにぶつかると、Salesforce はゼロ以外の numberRecordsFailed で JobComplete に到達することができます。成功した行は確定したままです。インテグレーション層の再試行は、したがって 新しいジョブを再構築 (または新しい CSV)し、未解決の行と任意の新規挿入のみを含める必要があります。通常、failedResults と unprocessedRecords で導かれます。10 個の失敗後に百万行全体のファイルを再送信することは無駄であり、操作が自然識別子または外部識別子でキーが付けられたアップサートでない限り、重複操作のリスクがあります。

クエリ抽出とロケータ

大規模な SOQL 抽出は、繰り返される GET .../jobs/query/{id}/results 呼び出しを通じて消費される必要があります。各応答は Sforce-Locator の次のロケータを含みます。そのヘッダーがリテラル文字列 null になるまで続行してください(公式例に示されている文字列)。ロケータ トークンを合成しないでください。Salesforce によって返された値のみを再利用してください。

---

一般的なパターン

パターン 1: 強化された単一ジョブ インジェスト(create → upload → UploadComplete → poll → results)

使用時: ミドルウェアはマルチパート便利さのしきい値より大きい CSV ファイルを所有するか、ステージ内で生成します。

動作方法: POST /jobs/ingest/ を object、operation、contentType: CSV、およびファイルと一致する区切り文字/行末メタデータで実行します。PUT で contentUrl にバイトをアップロードします。PATCH で UploadComplete を送信します。GET をジョブ上で端末状態まで poll します。successfulResults、failedResults、および unprocessedRecords を個別のリソースとしてダウンロードして、次のアクションを決定します。

代替案を使用しない理由: アップロード PUT から HTTP 202 のみをポーリングすることは不十分です。アップロード応答はジョブ状態ポーリングの代替ではなく、PATCH を省略するとジョブは永遠に Open のままになります。

パターン 2: 順序付き親/子一括読み込み

使用時: 子行が親を参照し、子インジェスト ジョブが実行される前に存在する必要があります。

動作方法: 親インジェスト ジョブを実行して 完全に完了 します(結果検証を含む)。子ジョブを作成する前です。依存関係をオーケストレーション メタデータ(ワークフロー エンジン、キュー、または状態テーブル)にエンコードします。再試行された親が重複した子を起動しないようにします。

代替案を使用しない理由: 両方のジョブを同時に送信すると、軽負荷では消える間欠的な FIELD_INTEGRITY_EXCEPTION と外部キー障害が発生しますが、本番ピークで失敗します。

パターン 3: クエリ ジョブ ペジネーション ワーカー

使用時: ダウンストリーム ウェアハウスがすべてのクエリ結果セットを必要としますが、1 つの HTTP レスポンスにすべてを読み込みたくありません。

動作方法: クエリ ジョブを作成し、結果が準備完了になるまで poll し、各返された Sforce-Locator を渡して結果をループ GET します。ヘッダーが null を読み取るまで続行します。チェックポイント付きで最後の成功したロケータを保持して、再開をサポートします。

代替案を使用しない理由: maxRecords を増やすと、大きな抽出でのロケータの必要性が取り除かれるわけではなく、ページをスキップするとデータが静かに失われます。

---

判断ガイダンス

状況	推奨アプローチ	理由
小さいペイロード、単一 HTTP ラウンドトリップは許容可能	埋め込み CSV 付きマルチパート POST create	プラットフォームはアップロード フェーズを自動的に完了します。手動の UploadComplete は不要
ディスクまたはストリーム上で生成される大きな CSV	標準 create + チャンク化 PUT + PATCH UploadComplete	サイズ制限と明確なクローズ セマンティクスに対応
JobComplete で一部の行が失敗	失敗した行 CSV + アップサート外部 ID を持つ新しいジョブ	成功の重複を回避します。非ロールバック セマンティクスに合わせます
抽出 > 1 つの HTTP レスポンス	ロケータ駆動ペジネーション	ページング CSV 結果の唯一のサポートされたナビゲーション
夜間ボリュームが org 日次キャップに近い	ジョブを広げ、numberRecordsProcessed を監視し、ハード ストップの前にアラート	日次割り当てが枯渇した場合の静かな切り詰めを防止

---

推奨ワークフロー

1. CSV を生成する前に、API バージョン、OAuth トークン有効期間、およびオブジェクト/操作サポート(hardDelete 権限の意味を含む)を確認してください。
2. マルチパート対ステージ PUT を選択します。ステージの場合、宣言された lineEnding と columnDelimiter が物理ファイルと一致することを確認します。
3. ジョブを作成し、すべてのパートをリクエストごとのサイズ制限内でアップロードし、マルチパートがアップロード フェーズを既に完了していない限り PATCH {"state":"UploadComplete"} を送信します。
4. バックオフ スケジュールでジョブ GET をポーリングします。状態が UploadComplete または InProgress の間、Failed と Aborted を端末エラー パスとして扱い、ログを記録します。
5. JobComplete では、3 つの結果リソースをダウンロードし、監査用の生 CSV アーティファクトを保持し、ソース システムに対する数を計算します。
6. クエリ ジョブの場合、Sforce-Locator を null になるまで走査し、各ページをオブジェクト ストレージに書き込んでから前進させます。
7. 失敗/未処理の行のみで follow-up ジョブを開きます。アップサート キーまたは決定論的削除による冪等性を保持します。

---

レビュー チェックリスト

• 非マルチパート インジェストは最終 PUT 後に明示的な UploadComplete を含みます。
• ポーリングは InProgress、JobComplete、Failed、および Aborted を個別のハンドリングで区別します。
• 部分的失敗は、冪等アップサートでカバーされていない限り、スコープ付き再試行ファイル(盲目的なフル ファイル リプレイではない)を生成します。
• クエリ抽出は、発明されたトークンなしでロケータ ペジネーションを実装します。
• 親/子読み込みは、親 JobComplete に対するハード ゲートと調整により順序付けられます。
• モニタリングには Salesforce ジョブ ID、状態遷移、および外部ログの行カウンタが含まれます。

---

Salesforce 固有の落とし穴

1. 静かな「開始しない」ジョブ — アップロード後に UploadComplete を忘れると、Open のジョブが処理されずに留まります。影響: SLA は誰かがジョブを中止するまで無期限に逃されます。
2. JobComplete の誤読 — オペレータは JobComplete を「すべての行が挿入された」と扱います。影響: ダウンストリーム システムはデータがまだ足りない間にチェックポイントを前進させます。常に数を調整してください。
3. ロケータの誤用 — 作成された、または古いロケータを再利用するとエキスが破損します。影響: ウェアハウスで重複または スキップされた行。すぐに前のレスポンスからのヘッダーのみを信頼してください。

---

出力アーティファクト

アーティファクト	説明
ジョブ オーケストレーション ランブック	HTTP メソッド、状態、およびポーリング間隔を観測可能性 ID に結び付けたステップ テーブル
再試行 CSV 仕様	列リストと 2 番目のパス Bulk ジョブの外部 ID 戦略
ペジネーション監査ログ	クエリ抽出のページごとのロケータとバイト数シーケンス

---

関連スキル

• data/bulk-api-patterns — 詳細な REST 例、CSV ルール、マルチパート構造、および Bulk API v1 比較テーブル。
• integration/real-time-vs-batch-integration — 一括バッチ パスとイベント/callout パターン間のアーキテクチャレベルの選択。
• data/bulk-api-and-large-data-loads — 戦略的なサイズング、並行性の議論、および LDV 指向の読み込み計画。