Paginierung und Verwendung des Cursors als Teil der Report Export API

Created date	Updated date	Affects version	Fix version
14 Jul 2023	20 Jul 2023	Management Portal

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 "X-BLANCCO-CURSOR" 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 "Export Reports (POST)" verwenden. Der Parameter "size" definiert die Anzahl der zurückgegebenen Berichte und erlaubt Werte zwischen 1-10. Wenn Sie beispielsweise den Wert "size" 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 "X-BLANCCO-CURSOR"-Header mit einem Wert ähnlich "1234567890123,1234a12b-1234-123a-ab1c-123456a1b12c".

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

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üssen.

Example report export request

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

Die Kopfzeilen der Antwort sehen ähnlich aus wie unten, einschließlich der Kopfzeile X-BLANCCO-CURSOR, die zum Abrufen des nächsten Berichts verwendet wird.

Example request response headers

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

Um die nächste Seite der Daten (in diesem Fall den nächsten Einzelbericht) zu erhalten, muss der Wert der Kopfzeile X-BLANCCO-CURSOR in die nächste Anfrage aufgenommen werden. Je nach verwendetem API-Endpunkt gibt es zwei Möglichkeiten, den Wert aufzunehmen:

Fügen Sie den Wert als URL-Parameter ein (in der Endpunkt-URL)
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 "?cursor={CURSOR_VALUE}" am 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.

Example report export request including cursor

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

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 Bericht.