Bulk API 2.0 を使用する

学習の目的

この単元を完了すると、次のことができるようになります。

非同期要求と同期要求の違いを説明する。
Postman Web アプリケーションを使用して一括ジョブを作成する。
ジョブにデータを追加することによって Salesforce 組織にデータをインポートする。
ジョブの進行状況を監視する。
ジョブの結果を取得する。

メモ

日本語で受講されている方へ
このバッジの Trailhead ハンズオン Challenge は英語で受講していただく必要があります。英語の意味についてはかっこ内の翻訳をご参照ください。Trailhead Playground では (1) [Locale (地域)] を [United States (米国)] に、[Language (言語)] を [English (英語)] に切り替えて、(2) 英語の値のみをコピーして貼り付けてください。こちらの指示に従ってください。

翻訳版 Trailhead を活用する方法の詳細は、自分の言語の Trailhead バッジを参照してください。

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 開発者ガイド』を参照してください。

Playground と Postman の設定

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

Trailhead Playground にログインします。
Postman Web アプリケーションにログインします。
新しいトークンを取得することによって Playground を Postman に接続します。
REST GET Limits リソースを使用して接続が機能していることをテストします。

この方法は「Quick Start: Connect Postman to Salesforce (クイックスタート: Postman を Salesforce に接続する)」で学習しました。手順で不明な点がある場合は、そちらのプロジェクトを参照してください。

一括ジョブの作成

最初のステップは Salesforce API コレクションのフォーク内でジョブを作成することです。ジョブは、操作の種類と操作するデータオブジェクトを指定します。ジョブはバケットとして機能します。そこに処理するデータを追加します。

[Collections (コレクション)] で [Bulk v2] フォルダーを開きます。
[POST Create job] をクリックします。

[Bulk v2] フォルダーが開き、[POST Create job] リソースが選択されていることを示す Postman のコレクションウィンドウ。

Bulk API は REST ベースであるため、要求は、URI、HTTP メソッド、ヘッダー、ボディの 4 つのコンポーネントを持つ見慣れた REST 要求の形式になります。HTTP メソッドは POST です。

コレクション内のリソースをクリックすると、メインウィンドウに /services/data/v{{version}}/jobs/ingest という URI が作成されます。この URI について少し説明します。

/services/data を使用していますが、これは REST API に使用するのと同じエンドポイントです。Bulk API は、REST API が使用するのと同じフレームワークを使用します。つまり、Bulk API では、OAuth 認証など、REST API と同じ機能が多数サポートされています。
/jobs/ingest は、Bulk API ジョブを作成するためにリソースにアクセスしていることを示します。

POST Create Job の URI が表示されている Postman の要求ウィンドウ。

リクエストボディを作成しましょう。

Bulk API 2.0 ジョブを作成するには、lineEnding リクエスト項目を使用して、CSV 形式のテキストの作成に使用する行末を指定します。Bulk API 2.0 では、行末形式として改行 (LF) と行頭復帰と改行 (CRLF) の 2 つがサポートされています。lineEnding が指定されていない場合のデフォルト値は LF です。行末を示すために使用される文字は、オペレーティングシステムによって異なります。

UNIX/Linux/OS X では、LF (改行、「\n」、0x0A) が使用されます。
Windows/DOS では、CRLF (行頭復帰および改行、「\r\n」、0x0D0A) が使用されます。

CSV ファイルの作成に使用するテキストエディターに特定の行末形式が設定され、オペレーティングシステムのデフォルト形式よりも優先されることがあります。

ブラウザーからサンプルの CSV ボディをコピーしてテキストエディターに貼り付け、形式をクリアします。使用している OS とテキストエディターに基づいて、lineEnding リクエスト項目に適切な行末を指定します。この例では、Windows マシンを使用し、lineEnding パラメーターに「CRLF」という値を指定しています。

{
"operation" : "insert",
"object" : "Account",
"contentType" : "CSV",
"lineEnding" : "CRLF"
}

2.[Save (保存)] をクリックします。
3.[Send (送信)] をクリックし、応答を確認します。

ジョブ ID が返され、ジョブの状態が [Open (オープン)] であることや、ジョブに関するその他の詳細が表示されている Postman の応答ウィンドウ。

応答にはジョブに関するあらゆるプロパティが含まれています。まだデータを追加していないため、その多くは現時点では役に立ちません。そのいくつかを見ていきましょう。

"id" 行を見てください。これは、このジョブに対して返されたジョブ ID です。
1. 次に、要求セクションの [Tests (テスト)] タブをクリックします。
2. このスクリプトはジョブ ID を __jobID 変数に自動的に追加します。これによって今後の要求に jobID が挿入されるため、コピーして貼り付ける必要がありません。
次に "state" プロパティを見てみましょう。
1. ジョブを作成すると、このプロパティは直ちに Open 設定されます。これは、データを受信する準備ができていることを意味します。
最後に "contentUrl" プロパティを見てみましょう。
1. このプロパティは、ジョブのデータの読み込みに使用する URL を示します。

ジョブへのデータの追加

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

Postman で新しい要求を作成します。Salesforce API コレクションのフォークで、[Bulk v2] フォルダーの [PUT Upload Job Data] をクリックします。HTTP メソッドは PUT です。

この例では、4 つの取引先のみが含まれるレコードセットを追加します。通常、Bulk API は数千～数百万件のレコードを追加するために使用されますが、原理は同じです。CSV ファイルをアップロードするか、リストに貼り付けることができます。アップロードする場合は、[binary (バイナリ)] ラジオボタンを選択して .csv ファイルをアップロードします。この例では、リストに貼り付けます。

[Body(ボディ)] タブをクリックし、ドロップダウンから [Raw (未加工)] を選択します。
次のテキストをテキストエディターにコピーすることで余分な書式設定をクリアしてから、そのテキストをテキストファイルからリクエストボディ項目にコピーします。

"Name"
"Global Treasures & Mapping Company"
"Ahab’s Mighty Masts"
"Planks R Us"
"Cap’n Cook’s Kitchen Supplies"

PUT Upload Job Data の URI と、アップロードされるデータの詳細が含まれた [Body(ボディ)] 項目が表示されている Postman の要求ウィンドウ。

3.[ヘッダー] をクリックします。[Content Type (コンテンツタイプ)] は [text/csv] になっています。これは、最初の要求でコンテンツタイプを指定したためです。

[Headers (ヘッダー)] の [VALUE (値)] 項目が [text/csv] に設定されている Postman の要求ウィンドウ。

4.[Save (保存)] をクリックします。
5.[Send (送信)] をクリックします。

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

ジョブデータが正常にアップロードされたことを示す 201 ジョブ状況コードが表示されている Postman の応答ウィンドウ。

ジョブの終了

これでデータの送信が完了したため、データを処理する必要があることを Salesforce に通知する必要があります。

Salesforce API フォークで、[Bulk v2] の [Query] フォルダーの [PATCH Close or Abort a Job] をクリックします。
[Body(ボディ)] タブをクリックします。"state" に「UploadComplete」がすでに入力されています。

PATCH Close or Abort a Job の URI と、[Upload Complete (アップロード完了)] 状況を示す [Body (ボディ)] ウィンドウが表示されている Postman の要求ウィンドウ。

3.[Headers (ヘッダー)] タブをクリックすると、[Content-Type] が [application/json] に設定されています。

[Headers (ヘッダー)] の [VALUE (値)] 項目が [application/json] に設定されている Postman の要求ウィンドウ。

4.[Send (送信)] をクリックします。

ジョブの詳細と [Upload Complete (アップロード完了)] 状況が表示されている Postman の応答ウィンドウ。

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

ジョブの状況の確認

データを送信し、データのアップロードが完了したことを Salesforce に通知しました。要求が処理されるかどうかはサーバー次第です。Salesforce UI または API を使用してジョブの状況を確認することにより、サーバーの進行状況を監視できます。それぞれの方法を見ていきましょう。

Trailhead Playground でジョブの状況を確認する手順は次のとおりです。

[設定] から、[クイック検索] ボックスに 一括データ読み込みジョブ と入力します。
[一括データ読み込みジョブ] を選択します。

このページでジョブの状況を確認できます。または、ジョブ ID をクリックすると、状況を確認し、そのジョブの詳細な結果を取得できます。

過去 7 日間に完了した一括データ読み込みジョブが表示されている Salesforce の [設定] ウィンドウ。

Postman で [Bulk v2] フォルダーからジョブの状況を確認する手順は次のとおりです。

[GET Job Info] を選択します。この種類の要求に使用される HTTP メソッドは GET です。
[Send (送信)] をクリックします。

表示は次のようになります。

ジョブの詳細と [Job Complete (ジョブ完了)] のジョブ状況が表示されている Postman の応答ウィンドウ。

state が JobComplete ではなく、UploadComplete のままの場合は、Salesforce がジョブをまだ処理中です。ご安心ください。まもなく処理されます。その間、ちょっとココナッツミルクでも 1 杯飲みに行って、戻ってきてから同じ要求を試します。ジョブの処理が完了している場合は、次にジョブ結果を取得します。

ジョブ結果の取得

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

[Bulk v2] フォルダーで正常に処理されたレコードを見てみましょう。

[GET Get Job Successful Record Results] リソースをクリックします。HTTP メソッドは GET です。
[Send (送信)] をクリックします。表示は次のようになります。

返された取引先の名前が表示されている Postman の応答ウィンドウ。

Salesforce は、正常に処理されたジョブのすべてのレコードのリストを返します。このモジュールでは、取引先レコードをいくつか作成しました。1 行目は、その下に表示される返された応答値の種別を示しています。リストデータには、作成されたレコードのレコード ID、sf__Created 列の true 値、作成された取引先の名前が含まれています。

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

[GET Get Job Failed Record Results] リソースをクリックします。HTTP メソッドは今回も GET です。
[Send (送信)] をクリックします。結果は次のようになります。

この例では失敗したジョブがないためにエラーが表示されている Postman の応答ウィンドウ。

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

リソース

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