クエリジョブの結果の取得

構文

URI

/services/data/vXX.X/jobs/query/queryJobId/results

or

1/services/data/vXX.X/jobs/query/queryJobId/results
2   ?locator=locator
3   &maxRecords=maxRecords

クエリの作成に使用したクエリ結果を取得するには、同じ API バージョンを使用してください。そうしないと、コールによって 409 エラーが返されます。

メモ

適用開始バージョン

このリソースは API バージョン 47.0 以降で使用できます。

形式

CSV

HTTP メソッド

GET

認証

Authorization: Bearer token

要求パラメータ

パラメータ	説明	必須か省略可能
queryJobId	クエリジョブの ID。	必須
locator	特定のクエリ結果セットを識別する文字列。このパラメータに値を設定すると、その結果セットのみが返されます。 このパラメータを省略すると、先頭の結果セットが返されます。 次の結果セットのロケータ文字列は、各要求の応答に示されています。「例」および「ルールとガイドライン」を参照してください。 関連するジョブが存在する限り、結果セットのロケータ文字列は変更されません。ロケータを使用すると、結果セットを何回も取得できます。	省略可能
maxRecords	クエリで取得する結果セットあたりの最大レコード数。要求は、依然としてサイズの制限を受けます。 操作するクエリ結果の数が非常に多い場合は、Salesforce からすべてのデータを受信する前にタイムアウトが発生することがあります。タイムアウトを回避するには、maxRecords パラメータでクライアントが想定する最大受信レコード数を指定します。これにより、この値を最大サイズとして、結果がより小さいセットに分割されます。 このパラメータに値を設定しない場合、サーバは、サービスに基づいてデフォルト値を使用します。	省略可能

レスポンスボディ

要求が成功した場合、状況コードは 200 (OK) となり、リクエストボディには、ジョブのクエリ結果が表示されます。次に例を示します。

1"Id","Name"
2"005R0000000UyrWIAS","Jane Dunn"
3"005R0000000GiwjIAC","George Wright"
4"005R0000000GiwoIAC","Pat Wilson"
5...

応答ヘッダー

ヘッダー	説明
Sforce-NumberOfRecords	このセット内のレコード数。
Sforce-Locator	次の結果セットのロケータ (存在する場合)。次のクエリ結果セットを取得するには、この値を別の GET 要求で使用します。 この値は擬似ランダムな文字列です (MTAwMDA など)。この文字列の長さは、結果セットの数によって変化します。 これ以上クエリ結果セットがない場合、この値は文字列の「null」になります。 「例」および「ルールとガイドライン」を参照してください。

例

次の例では、ID が 750R0000000zxr8IAA のジョブの結果が取得されます。また、locator および maxRecords クエリパラメータの使用方法も示されます。(この例では、両方を使用していますが、それぞれは独立しています。一緒に使用する必要はありません。)

最初に、先頭のクエリ結果セットを取得するために初期要求を送信します。先頭の結果セットを取得するため、locator パラメータは使用しません。

1curl --include --request GET \
2--header "Authorization: Bearer token" \
3--header "Accept: text/csv" \
4https://instance.salesforce.com/services/data/vXX.X/jobs/query/750R0000000zxr8IAA/results
5?maxRecords=50000

レスポンスボディは次のようになります。

1HTTP/1.1 200 OK
2...
3Sforce-Locator: MTAwMDA
4Sforce-NumberOfRecords: 50000
5...
6
7"Id","Name"
8"005R0000000UyrWIAS","Jane Dunn"
9"005R0000000GiwjIAC","George Wright"
10"005R0000000GiwoIAC","Pat Wilson"
11...

この応答には、Sforce-Locator ヘッダーの値として MTAwMDA が含まれています。この値が「null」でないということは、取得できるクエリ結果が他にもあることを意味します。

次のクエリ結果セットを取得するには、locator パラメータとロケータ文字列 MTAwMDA を使用して別の要求を送信します。

1curl --include --request GET \
2--header "Accept: text/csv" \
3https://instance.salesforce.com/services/data/vXX.X/jobs/query/750R0000000zxr8IAA/results
4?locator=MTAwMDA&maxRecords=50000

レスポンスボディは次のようになります。

1HTTP/1.1 200 OK
2...
3Sforce-Locator: MjAwMDAw
4Sforce-NumberOfRecords: 50000
5...
6
7"Id","Name"
8"005R0000000UyrWIAv","James Wu"
9"005R0000000GiwjIxx","Samantha Jones"
10"005R0000000GiwoIAB","Doug West"
11...

ロケータ値が変更されています。これは、取得できるクエリ結果セットが他にもあることを意味します。別の要求で新しいロケータ文字列 MjAwMDAw を使用します。

1curl --include --request GET \
2--header "Accept: text/csv" \
3https://instance.salesforce.com/services/data/vXX.X/jobs/query/750R0000000zxr8IAA/results
4?locator=MjAwMDAw&maxRecords=50000

Sforce-Locator ヘッダーの値が「null」、つまり取得する結果が他になくなるまで、このプロセスを繰り返します。

1HTTP/1.1 200 OK
2
3Sforce-Locator: null
4Sforce-NumberOfRecords: 6155
5...
6
7"Id","Name"
8...

ルールとガイドライン

クエリ結果セット全体を取得するには、以下のルールおよびガイドラインに従います。

1. /services/data/vXX.X/jobs/query/queryJobId/results を使用して、ジョブの最初の結果セットを取得します。
2. これ以上結果がない場合、Sforce-Locator ヘッダーの値は文字列の「null」になります。それ以外の場合、locator クエリパラメータをその値に設定すると、次の結果セットが取得されます。

   locator には、Sforce-Locator ヘッダーの値のみを使用してください。値を推測することは試みないでください。このパラメータの評価方法は、変更されることがあります。

   メモ

3. この手順を繰り返していくと、Sforce-Locator ヘッダーの値が文字列の「null」になります。そのセットが最後の結果セットとなります。