Bulk API 2.0 を使用する

学習の目的

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

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

メモ

日本語で受講されている方へ
Challenge は日本語の Trailhead Playground で開始し、かっこ内の翻訳を参照しながら進めていってください。Challenge での評価は英語データを対象に行われるため、英語の値のみをコピーして貼り付けるようにしてください。日本語の組織で Challenge が不合格だった場合は、(1) この手順に従って [Locale (地域)] を [United States (米国)] に切り替え、(2) [Language (言語)] を [English (英語)] に切り替えてから、(3) [Check Challenge (Challenge を確認)] ボタンをクリックしてみることをお勧めします。

翻訳版 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 を使用して取引先レコードを作成します。

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

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

一括ジョブの作成

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

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

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 ジョブを作成するためにリソースにアクセスしていることを示します。
  

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

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

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

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

2. テキストエディターからサンプルの CSV ボディをコピーして、Postman の [Body (本文)] タブに貼り付けます。
   
3. [Save (保存)] をクリックします。
   
4. [Send (送信)] をクリックし、応答を確認します。
   

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

1. "id" 行を見てください。これは、このジョブに対して返されたジョブ ID です。
   

• [Scripts (スクリプト)] タブをクリックすると、__jobId 変数を使用してコンテキストを設定するスクリプトが表示されます。このスクリプトはジョブ ID を __jobId 変数に自動的に追加します。これによって今後の要求にジョブ ID が挿入されるため、コピーして貼り付ける必要がありません。
  
• __jobId の値は、コレクションの [Variables (変数)] タブで確認できます。
  

2. 次に "state" プロパティを見てみましょう。
   

• ジョブを作成すると、このプロパティは直ちに Open 設定されます。これは、データを受信する準備ができていることを意味します。
  

3. 最後に "contentUrl" プロパティを見てみましょう。
   

• このプロパティは、ジョブのデータの読み込みに使用する URL を示します。
  

ジョブへのデータの追加

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

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

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

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

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

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

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

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

ジョブの終了

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

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

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

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

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

ジョブの状況の確認

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

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

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

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

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

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

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

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

ジョブ結果の取得

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

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

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

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

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

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

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

リソース

• 開発者ガイド: Bulk API 2.0 開発者ガイド