レポートエクスポートAPIのページ送り機能とカーソルの使用方法

作成日	更新日	影響を受けるバージョン	修正バージョン
14 Jul 2023	20 Jul 2023	Management Portal

説明

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つあります:

値をURLパラメータとして (エンドポイントURLに) 含める
値をJSONペイロードの一部に含める

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

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

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

次の例は、このようにして編集したリクエスト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パラメータとして渡す場合、コンマに16進数表記を使用する必要があることに注意してください (上記の例では%2C) 。

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

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

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