Page History

説明

When exporting large data sets using the Report Export API endpoints in the Blancco Management Portal the response is split into multiple separate responses. To achieve this use of a special header as part of the request response named Blancco Management PortalでレポートエクスポートAPIエンドポイントを使用して大量のデータセットをエクスポートする場合、応答は複数の個別のレスポンスに分割されます。そのため、リクエストレスポンスに "X-BLANCCO-CURSOR " is required.

This page will explain the pagination in more detail and help with the usage of the cursor to fetch all the data when working with larger data sets.

ページサイズの制限

Default page size is limited to a maximum of 100 reports. If the request returns more reports the data is split into multiple responses and using the cursor is required to fetch all the requested reports.

Page size can also be set as a request parameter within the JSON payload if you are using the "Export Reports (POST)" endpoint. The "size" parameter defines the number of returned reports and allows values between 1-10. As an example using "size" value of 5 returns 5 reports per page and each page of 5 reports needs to be requested separately using the cursor.

カーソルヘッダー

という特別なヘッダーを使用する必要があります。 

この記事では、ページ送り機能について詳しく説明し、大きなデータセットを扱う場合にカーソルを使用してすべてのデータを取得する方法について説明します。

ページサイズの制限

デフォルトのページサイズは最大100レポートに制限されています。リクエストがそれよりも多くのレポートを返す場合は、データは複数レスポンスに分割され、リクエストされたすべてのレポートを取得するにはカーソルを使用する必要があります。

"レポートエクスポート (POST) "エンドポイントを使用する場合は、ページサイズをJSONペイロード内の要求パラメータとして指定することもできます。"size"パラメータは返されるレポートの数を定義し、1~10の値を指定できます。例えば、"size "の値を5とすると、1ページに5つのレポートが返され、5つのレポートの各ページをカーソルを使って分割してリクエストする必要があります。

カーソルヘッダー

要求応答が大量のデータを返す場合は、複数の別々の要求応答に分割されます。この場合、要求応答ヘッダーには  "In case the request response return a lot of data it is split into multiple separate request responses. When this happens the request response headers will include a "X-BLANCCO-CURSOR" header with a value similar to "1234567890123,1234a12b-1234-123a-ab1c-123456a1b12c"のような値を持つ"X-BLANCCO-CURSOR"ヘッダーが含まれます。

x-blancco-cursor: 1234567890123,1234a12b-1234-123a-ab1c-123456a1b12c

If the header is not available on the request response all the (remaining) data was returned within the request. This is how you know you have requested the last available page of data.

APIリクエストにカーソルを含める 

If your initial request return the above mentioned header not all the matching reports were included in the provided response and you will need request the rest of the reports by including the cursor to the next request. When you send your initial Report Export request the first page of data will be provided as the response and further data is fetched using cursor.

ヘッダーがリクエスト応答で得られなかった場合は、（残りの）データはすべてリクエスト内で返されています。このようにして、入手可能な最後のページのデータをリクエストしたことを判断できます。

APIリクエストにカーソルを含める 

最初のリクエストで上記のヘッダーが返された場合、すべての一致するレポートが提供されたレスポンスに含まれていません。そして次のリクエストにカーソルを含めて、残りのレポートを要求する必要があります。最初のエクスポートリクエストを送信すると、データの最初のページがレスポンスとして提供され、それ以降のデータはカーソルを使用して取得されます。 

次の例では、リクエストの"size"パラメータが1に設定されているため、このリクエストを実行すると1つのレポートが返され、残りの一致するレポートはカーソルを使用してリクエストする必要があります。In the below example request "size" parameter is set to 1 so executing this request returns a single report and the rest of the matching reports need to be requested using cursors.

curl --request POST \
  --url https://api.eu-west-1.blancco.cloud/v1/report/export \
  --header 'Content-Type: application/json' \
  --header 'X-BLANCCO-API-KEY: {API_KEY}' \
  --data '{
  "filter": {
    "date": {
      "gte": "2020-07-01T00:00:00Z"
    }
  },
  "format": "XML",
  "container": "NONE",
  "size": 1
}'

The response headers will be similar to below, including the X応答ヘッダーには、次のレポートを取得するために使用されるX-BLANCCO-CURSOR header which is going to be used to fetch the next report.CURSORヘッダーが含まれ、以下のようになります。

date: Thu, 20 Jul 2023 12:52:17 GMT
content-type: application/xml;charset=UTF-8
content-length: 4994
apigw-requestid: ABCd1e-2fgHIJk=
vary: Origin
vary: Access-Control-Request-Method
vary: Access-Control-Request-Headers
x-blancco-cursor: 1234567890123,1234a12b-cd1e-1234-a123-1a2345b6789c
content-disposition: attachment; filename=reports.xml
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
x-frame-options: SAMEORIGIN

To get the next page of data (in this case the next individual report) the value of the X-BLANCCO-CURSOR header needs to be included in the next request. There are two possibilities to include the value depending on API endpoint being used:

1. Include the value as the URL parameter (in the endpoint URL)
2. Include the value as part of the JSON payload

Some endpoints allow using both options, if both are defined at the same time the URL parameter value will be used.

URLパラメータに値を含める

次のページのデータ（この例の場合は次の個別レポート） を取得するには、X-BLANCCO-CURSORヘッダーの値を次のリクエストに含める必要があります。使用するAPIエンドポイントによって、この値を含める方法が2つあります:

1. 値をURLパラメータとして （エンドポイントURLに）含める
2. 値をJSONペイロードの一部に含める

エンドポイントによっては、どちらの方法も使用できますが、両方が同時に指定された場合は、URLパラメータの値が使用されます。

URLパラメータに値を含める

カーソルをURLパラメータとして含めるには、リクエストを送信する url を編集し、In order to include the cursor as a URL parameter you need to edit the url you are sending the request to and include "?cursor={CURSOR_VALUE}" to the end of the URL (without the quotes).をURLの末尾に追加します（引用符は含みません）。

次の例は、編集して更新されたURLを示しており、このリクエストを実行すると、次の一致するレポートがエクスポートされます。Below example shows the updated URL and executing this request exports the next matching report.

curl --request POST \
  --url  https://api.eu-west-1.blancco.cloud/v1/report/export?cursor=1234567890123%2C1234a12b-cd1e-1234-a123-1a2345b6789c\
  --header 'Content-Type: application/json' \
  --header 'X-BLANCCO-API-KEY: {API_KEY}' \
  --data '{
  "filter": {
    "date": {
      "gte": "2020-07-01T00:00:00Z"
    }
  },
  "format": "XML",
  "container": "NONE",
  "size": 1
}'

Note that it may be required to use hexadecimal presentation for the comma (%2C in above example) when passed as a URL parameter.

JSONペイロードに値を含める

To include the cursor value in the JSON payload it simply needs to be defined as the value for key named "cursor".

URLパラメータとして渡す場合、コンマ （上記の例では%2C）に16進数表記を使用する必要がある場合があることに注意してください。

JSONペイロードに値を含める

カーソル値をJSONペイロードに含めるには、"cursor "というキーの値として定義します。

以下の例では、カーソルのキーと値のペアが含まれた、更新されたJSONペイロードを示しています。このリクエストを実行すると、次の一致するレポートがエクスポートされます。Below example show the updated JSON payload with the cursor key-value pair being included. Executing this request exports the next matching report.

curl --request POST \
  --url  https://api.eu-west-1.blancco.cloud/v1/report/export \
  --header 'Content-Type: application/json' \
  --header 'X-BLANCCO-API-KEY: {API_KEY}' \
  --data '{
  "filter": {
    "date": {
      "gte": "2020-07-01T00:00:00Z"
    }
  },
  "format": "XML",
  "container": "NONE",
  "size": 1,
  "cursor": "1234567890123,1234a12b-cd1e-1234-a123-1a2345b6789c"
}'

To fetch the next page of reports the next available X-BLANCCO-CURSOR value needs to be updated either as the URL parameter or to the JSON payload. To export all the matching reports this needs to be repeated until a request doesn't provide the X-BLANCCO-CURSOR header anymore.レポートの次のページを取得するには、次に使用可能なX-BLANCCO-CURSOR値で、URLパラメータまたはJSONペイロードを更新する必要があります。すべての一致するレポートをエクスポートするには、リクエストでX-BLANCCO-CURSORヘッダーが提供されなくなるまでこれを繰り返す必要があります。