Page History

Description

Beschreibung

Beim Exportieren großer Datensätze über den Berichtsexport API Endpunkte im Blancco Management Portal wird die Antwort in mehrere separate Antworten aufgeteilt. Um dies zu erreichen, ist die Verwendung eines speziellen Headers als Teil der Anfrageantwort namens 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 "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.

Page size limitations

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.

erforderlich.

Auf dieser Seite wird die Paginierung näher erläutert und die Verwendung des Cursors zum Abrufen aller Daten bei der Arbeit mit größeren Datensätzen erläutert.

Beschränkungen der Seitengröße

Die Standardseitengröße ist auf maximal 100 Berichte begrenzt. Wenn die Anfrage mehr Berichte liefert, werden die Daten in mehrere Antworten aufgeteilt und der Cursor muss verwendet werden, um alle angeforderten Berichte abzurufen.

Die Seitengröße kann auch als Anforderungsparameter innerhalb der JSON-Nutzdaten festgelegt werden, wenn Sie den Endpunkt Page size can also be set as a request parameter within the JSON payload if you are using the "Export Reports (POST)" endpointverwenden. The Der Parameter "size" parameter defines the number of returned reports and allows values between definiert die Anzahl der zurückgegebenen Berichte und erlaubt Werte zwischen 1-10. As an example using Wenn Sie beispielsweise den Wert "size" value of 5 returns 5 reports per page and each page of 5 reports needs to be requested separately using the cursor.

Cursor header

von 5 verwenden, werden 5 Berichte pro Seite zurückgegeben und jede Seite mit 5 Berichten muss separat mit dem Cursor angefordert werden.

Cursor header

Falls die Antwort auf eine Anfrage sehr viele Daten enthält, wird sie in mehrere separate Antworten aufgeteilt. In diesem Fall enthalten die Header der Anfrageantwort einen 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 -Header mit einem Wert ähnlich "1234567890123,1234a12b-1234-123a-ab1c-123456a1b12c".

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.

Including the cursor to the API request

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.

Wenn die Kopfzeile in der Antwort auf die Anfrage nicht vorhanden ist, werden alle (restlichen) Daten in der Anfrage zurückgegeben. So wissen Sie, dass Sie die letzte verfügbare Seite der Daten angefordert haben.

Einbindung des Cursors in die API-Anforderung

Wenn Ihre erste Anfrage die oben erwähnte Kopfzeile zurückgibt, sind nicht alle übereinstimmenden Berichte in der bereitgestellten Antwort enthalten, und Sie müssen die restlichen Berichte anfordern, indem Sie den Cursor in die nächste Anfrage aufnehmen. Wenn Sie Ihre erste Berichtsexportanforderung senden, wird die erste Seite der Daten als Antwort geliefert und weitere Daten werden mit dem Cursor abgerufen.

Im folgenden Beispiel ist der Parameter "size" auf 1 gesetzt, so dass bei der Ausführung dieser Anfrage ein einziger Bericht zurückgegeben wird und die übrigen übereinstimmenden Berichte über Cursor angefordert werden müssenIn 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 Die Kopfzeilen der Antwort sehen ähnlich aus wie unten, einschließlich der Kopfzeile X-BLANCCO-CURSOR header which is going to be used to fetch the next report, die zum Abrufen des nächsten Berichts verwendet wird.

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 Um die nächste Seite der Daten (in diesem Fall den nächsten Einzelbericht) zu erhalten, muss der Wert der Kopfzeile 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.

Including the value as the URL parameter

in die nächste Anfrage aufgenommen werden. Je nach verwendetem API-Endpunkt gibt es zwei Möglichkeiten, den Wert aufzunehmen:

1. Fügen Sie den Wert als URL-Parameter ein (in der Endpunkt-URL)
2. Den Wert als Teil der JSON-Nutzdaten einschließen

Einige Endpunkte lassen die Verwendung beider Optionen zu. Wenn beide gleichzeitig definiert sind, wird der Wert des URL-Parameters verwendet.

Einbeziehung des Wertes als URL-Parameter

Um den Cursor als URL-Parameter einzubinden, müssen Sie die URL, an die Sie die Anfrage senden, bearbeiten und 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).Below example shows the updated URL and executing this request exports the next matching reportam Ende der URL einfügen (ohne die Anführungszeichen).

Das nachstehende Beispiel zeigt die aktualisierte URL, und die Ausführung dieser Anfrage exportiert den nächsten passenden Bericht.

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.

Including the value in the JSON payload

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

Beachten Sie, dass es erforderlich sein kann, bei der Übergabe als URL-Parameter eine hexadezimale Darstellung für das Komma zu verwenden (%2C im obigen Beispiel).

Aufnahme des Wertes in die JSON-Nutzdaten

Um den Cursor-Wert in die JSON-Nutzdaten aufzunehmen, muss er einfach als Wert für den Schlüssel "Cursor" definiert werden.

Das folgende Beispiel zeigt die aktualisierte JSON-Nutzlast, die das Schlüssel-Wert-Paar des Cursors enthält. Die Ausführung dieser Anforderung exportiert den nächsten passenden BerichtBelow 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 Um die nächste Seite mit Berichten abzurufen, muss der nächste verfügbare 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 -Wert entweder als URL-Parameter oder in der JSON-Nutzlast aktualisiert werden. Um alle passenden Berichte zu exportieren, muss dies so lange wiederholt werden, bis eine Anfrage keinen X-BLANCCO-CURSOR header anymore-Header mehr liefert.