Bulk API 2.0 の使用

学習の目的

この単元を完了すると、次のことができるようになります。
  • 非同期要求と同期要求の違いを説明する。
  • ワークベンチで REST Explorer を使用して一括ジョブを作成する。
  • ジョブにデータを追加することによって Salesforce 組織にデータをインポートする。
  • ジョブの進行状況を監視する。
  • ジョブの結果を取得する。

Bulk API と非同期要求

Bulk API は、REST 規則に基づいており、大規模データセット操作用に最適化されています。これを使用して、多数のレコードを非同期で、挿入、更新、更新/挿入または削除できます。非同期とは、要求を送信してからしばらく後に結果を取得するということです。この要求はバックグラウンドで処理されます。

一方、SOAP および REST API は同期要求を使用しており、一度に少数のレコードを更新するリアルタイムのクライアントアプリケーション用に最適化されています。これらの API のいずれを使用しても多数のレコードを処理することはできますが、数十万のレコードがデータセットに含まれている場合には実用性に欠けます。Bulk API の非同期フレームワークは、千から百万単位のレコードのデータを簡単で効率的に処理できるように設計されています。

Bulk API の最も簡単な使用方法は、CSV ファイルを使ってデータローダでレコードの処理ができるようにすることです。データローダを使用すると、クライアントアプリケーションを自分で作成する必要がなくなります。ただし、独自の要件がある場合は、カスタムアプリケーションを作成する必要があることもあります。Bulk API を使用すれば、自分の手で操舵輪を握って、最適なソリューションへと舵を取ることができます。

この単元では、Bulk API の新しいバージョンである Bulk API 2.0 を使用します。この単元で学習した内容を、今もなおサポートされている前のバージョンの Bulk API に応用する場合は、異なるリソース URI を使用して、バッチとジョブを作成および管理する必要があります。前のバージョンの Bulk API の詳細は『Bulk API 開発者ガイド』を参照してください。

組織へのデータのインポート

Bulk API について学習するために、ワークベンチを使用して取引先レコードを作成します。

一括ジョブの作成

Bulk API は REST ベースであるため、ワークベンチの REST Explorer を使用して Bulk API 要求を行うことができます。
  1. Trailhead Playground にログインして、ワークベンチに移動します。
  2. [Environment (環境)] で [Production (本番)] を選択します。[API Version (API バージョン)] で、使用可能な最大の番号を選択します。必ず [I agree to the terms of service (サービス契約条件に同意します)] を選択します。
  3. [Login with Salesforce (Salesforce でログイン)] をクリックします。
  4. 上部のメニューで、[utilities (ユーティリティ)] | [REST Explorer] を選択します。

これで、データをアップロードする準備が整いました。最初のステップでは、ジョブを作成します。ジョブは、操作の種類と操作するデータオブジェクトを指定します。ジョブはパケットとして機能します。そこに処理するデータを追加します。

/jobs/ingest リソースを使用してジョブを作成します。このリソースは、現在のジョブのリストを取得するためにも使用できます。

ジョブを作成するには、リクエストボディ内でジョブのプロパティを指定して /jobs/ingest に POST 要求を送信します。Bulk API は REST ベースであるため、要求は、URI、HTTP メソッド、ヘッダー、ボディの 4 つのコンポーネントを持つ見慣れた REST 要求の形式になります。前述したように、メソッドは POST です。

URI については、URI テキストボックスのテキストを /services/data/vXX.0/jobs/ingest に置き換えます。ここで、XX.0 は使用している API のバージョンに対応します。この URI について少し説明します。
  • /services/data を使用していますが、これは REST API に使用するのと同じエンドポイントです。Bulk API は、REST API が使用するのと同じフレームワークを使用します。つまり、Bulk API では、OAuth 認証など、REST API と同じ機能が多数サポートされています。
  • /jobs/ingest は、Bulk API ジョブを作成するためにリソースにアクセス中であることを示しています。
リクエストボディには、次のテキストをコピーして貼り付けます。
{
  "operation" : "insert",
  "object" : "Account",
  "contentType" : "CSV",
  "lineEnding" : "CRLF"
}

これらのプロパティは、ジョブに送信するデータに対して挿入操作を使用することを示しています。送信するのは取引先データで、形式は CSV です。Bulk API は CSV のペイロードをサポートしています。

REST Explorer は次のようになります。

REST Explorer でのジョブ作成要求

[Execute (実行)] をクリックし、応答を確認します。

ジョブ作成応答

応答にはジョブに関するあらゆるプロパティが含まれています。まだデータを追加していないため、その多くは現時点では役に立ちません。ただし、いくつかのプロパティについては注意が必要です。ジョブ ID (id) を確認し、テキストファイルにコピーします。これは、ジョブにデータを追加したり、ジョブの状況を確認したりするのに使用します。また、state プロパティも確認します。ジョブを作成すると、このプロパティは直ちに Open 設定されます。これは、データを受信する準備ができていることを意味します。最後に、contentUrl プロパティを見ます。このプロパティは、ジョブのデータの読み込みに使用する URL を表示します。

ジョブへのデータの追加

これで、ジョブに取引先データを挿入できるようになりました。ジョブのデータは、PUT 要求のレコードセットとしてサーバーに送信されます。サーバーはレコードセットを処理し、データを Salesforce に読み込む最適な方法を判断します。必要なのは、データのアップロードのみです。

ワークベンチで新規要求を作成します。URI テキストボックスのテキストを /services/data/v XX.0/jobs/ingest/ jobID/batches に置き換えます。jobID をコピーしたジョブ ID に置き換えます。HTTP メソッドには PUT を選択します。

この例では、4 つの取引先のみが含まれるレコードセットを追加します。通常、Bulk API は数千~数百万件のレコードを追加するために使用されますが、原理は同じです。次の CSV テキストをリクエストボディにコピーします。
"Name"
"Sample Bulk API Account 1"
"Sample Bulk API Account 2"
"Sample Bulk API Account 3"
"Sample Bulk API Account 4"

ジョブ作成時の指定に合わせて CSV データを使用しています。

[Headers (ヘッダー)] をクリックして、Content-Type を text/csv に変更します。要求は次のようになります。

REST Explorer を使用したジョブデータの追加

[実行] をクリックします。

応答には、Salesforce がジョブデータを正常に受信したことを示す状況コード 201 (作成済み) のみが含まれます。

ジョブの終了

データを送信したので、Salesforce にデータ処理を実行する時間であることを知らせる必要があります。そのために、ジョブの状況を Open から UploadComplete に変更します。
URI テキストボックスのテキストを /services/data/v XX.0/jobs/ingest/ jobID に置き換えます。さらに、XX を、使用している API バージョンに置き換え、jobID をジョブの ID に置き換えます。HTTP メソッドには PATCH を選択します。[Headers (ヘッダー)] をクリックして、Content-Type を application/json に変更します。リクエストボディのテキストを次の JSON テキストに置き換えます。
{
   "state" : "UploadComplete"
}

[実行] をクリックします。応答にはジョブの状況に関する情報が含まれます。state プロパティはジョブの状況が UploadComplete であることを示しています。この時点で、Salesforce はジョブの処理を開始します。

ジョブの状況の確認

データを送信しました。データのアップロードが完了したことを Salesforce に知らせました。要求が処理されるかどうかはサーバ次第です。API または Salesforce UI を使用してジョブの状況を確認することにより、サーバの進行状況を監視できます。Salesforce では、[設定] から、[クイック検索] ボックスに「一括データ読み込みジョブ」と入力し、[一括データ読み込みジョブ] を選択します。このページでジョブの状況を確認できます。または、ジョブ ID をクリックすると、状況を確認し、そのジョブの詳細な結果を取得できます。

API では、/jobs/ingest/ jobID リソースを使用してジョブを監視します。URI テキストボックスのテキストを /services/data/v XX.0/jobs/ingest/ jobID に置き換え、通常の置き換えを行います。HTTP メソッドには GET を選択します。

[実行] をクリックします。表示は次のようになります。
ジョブの状況の確認

state が JobComplete ではなく、UploadComplete のままの場合でも、Salesforce はジョブをまだ処理しています。ご安心ください。まもなく処理されます。その間、ちょっとラム酒でも 1 杯飲みに行って、戻ってきてから同じ要求を試します。幸いにもジョブの処理が完了している場合は、引き続きジョブ結果を取得します。処理が完了していなければ、またラム酒を飲みに行くのもよいでしょう。

ジョブ結果の取得

ジョブの状況が JobComplete (または Failed) になると、レコードが正常に処理されたか否かの形で、結果情報を取得できます。

最初に、正常に処理されたレコードを見てみましょう。ワークベンチの REST Explorer で、URI テキストボックスのテキストを /services/data/v XX.0/jobs/ingest/ jobID/successfulResults に置き換え、通常の置き換えを行います。HTTP メソッドには GET を選択します。

[実行] をクリックします。表示は次のようになります。

成功した結果の確認

Salesforce は、正常に処理されたジョブのすべてのレコードのリストを含む CSV を返します。このモジュールでは、取引先レコードをいくつか作成しました。CSV データには、作成したレコードのレコード ID、sf__Created 列の true 値が含まれています。

一部のレコードを処理できない場合もあります。ジョブがすでに存在する取引先レコードを作成しようとしたか、ジョブデータに必須項目が含まれていないと考えられます。このような場合は、処理中にエラーが発生したレコードのリストと、何が問題なのかに関する詳細を Salesforce から取得できます。

REST Explorer で、URI テキストボックスのテキストを /services/data/v XX.0/jobs/ingest/ jobID/failedResults に置き換え、通常の置き換えを行います。HTTP メソッドには GET を選択します。

[実行] をクリックします。結果は次のようになります。

失敗した結果の確認

Salesforce は、処理中にエラーが発生したレコードのリスト、レコード ID、エラーメッセージを含む CSV を提供します。この場合、すべてのレコードは正常に挿入されたため、レコードのリストは空です。キャプテン、やりましたね。

リソース

Bulk API 2.0 開発者ガイド

Bulk API 開発者ガイド (この単元には含まれていない古いバージョンの Bulk API)

ワークベンチ

無料で学習を続けましょう!
続けるにはアカウントにサインアップしてください。
サインアップすると次のような機能が利用できるようになります。
  • 各自のキャリア目標に合わせてパーソナライズされたおすすめが表示される
  • ハンズオン Challenge やテストでスキルを練習できる
  • 進捗状況を追跡して上司と共有できる
  • メンターやキャリアチャンスと繋がることができる