説明

Blancco Management PortalでレポートエクスポートAPIエンドポイントを使用して大量のデータセットをエクスポートする場合、応答は複数の個別のレスポンスに分割されます。そのため、リクエストレスポンスに "X-BLANCCO-CURSOR "という特別なヘッダーを使用する必要があります。 

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

ページサイズの制限

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

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

カーソルヘッダー

要求応答が大量のデータを返す場合は、複数の別々の要求応答に分割されます。この場合、要求応答ヘッダーには  "1234567890123,1234a12b-1234-123a-ab1c-123456a1b12c"のような値を持つ"X-BLANCCO-CURSOR"ヘッダーが含まれます。

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

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

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

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

次の例では、リクエストの"size"パラメータが1に設定されているため、このリクエストを実行すると1つのレポートが返され、残りの一致するレポートはカーソルを使用してリクエストする必要があります。

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
}'

応答ヘッダーには、次のレポートを取得するために使用されるX-BLANCCO-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

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

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

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

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

カーソルをURLパラメータとして含めるには、リクエストを送信する url を編集し、"?cursor={CURSOR_VALUE}" をURLの末尾に追加します（引用符は含みません）。

次の例は、編集して更新されたURLを示しており、このリクエストを実行すると、次の一致するレポートがエクスポートされます。

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
}'

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

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

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

以下の例では、カーソルのキーと値のペアが含まれた、更新されたJSONペイロードを示しています。このリクエストを実行すると、次の一致するレポートがエクスポートされます。

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"
}'

レポートの次のページを取得するには、次に使用可能なX-BLANCCO-CURSOR値で、URLパラメータまたはJSONペイロードを更新する必要があります。すべての一致するレポートをエクスポートするには、リクエストでX-BLANCCO-CURSORヘッダーが提供されなくなるまでこれを繰り返す必要があります。