Cursor
Bei REST- und HTTP-APIs hilft ein Cursor dir, bei großen Ergebnissets Seiten zu überspringen, wenn der Server nicht jede Zeile gleichzeitig ausgeben kann. Der Server gibt einen Stapel an Zeilen aus (zum Beispiel bis 100) plus einem Zeichenfolgewert, der dem Server sagt, wo er bei den sortierten Ergebnissen bei der nächsten Abfrage fortfahren soll.
Wenn die Antwort paginiert ist, enthält das Cursor-Objekt häufig:
Self– Cursor-Wert für die aktuelle Seite (der Stapel, den du gerade erhalten hast).Next– Cursor-Wert für die folgende Seite. Auf der letzten Seite ist dies leer oder wird ausgelassen, weil es nichts mehr gibt, das abgerufen werden kann.
Wenn es beispielsweise 300 Datensätze gibt und die höchste Seitengröße 100 ist, gibt die erste Antwort die Zeilen 1–100 aus und enthält ein Cursors-Objekt mit Next und Self. Rufe den Endpunkt erneut mit dem Next-Wert beim cursor von der vorherigen Antwort auf, um die nächste Seite des Ergebnisses abzurufen (zum Beispiel die Zeilen 101-200). Wiederhole diesen Vorgang, bis die API keinen Next-Wert mehr ausgibt und so anzeigt, dass es keine weiteren Ergebnisse gibt, die abgerufen werden können.
Viele Antworten enthalten auch ein Links-Objekt mit Ready-to-request-URLs für dieselben Seiten. Weitere Informationen findest du unter
Links.
Beispiel
Eine paginierte Antwort enthält häufig Data, Links und Cursors:
{
"Data": [ ... ],
"Cursors": {
"Next": "qKLVZ/HGD2XeFkiwNFWJK+nRDuOjjBRipct8qOfRjRmGUG8F5P1WzrQ4p3JFfXoErs96xb+DS0SAPW+XDUi9Zw/zdo4uHXL3TYBhodxfQQul3L4mwDk=",
"Self": "KYhsR26Se8cQbeQm+o3LXawJXu3Pe6NvSefBcMivZ5QA+rFcRUrHTErK+TrhrUN3Ss8QUing/+jUkjgl3QOvB3kf3AZ+EOubhya5s3CWF+HGWEQkQQ=="
},
"Links": {
...
},
}
Du kannst mit den neuesten Daten beginnen und dann in der Zeit zurückgehen ( Sorting=Descending) oder mit dem Beginn eines vergangenen Zeitraums starten und zum aktuellen Zeitpunkt hinarbeiten (Sorting=Ascending).
Sorting=Ascending ist nützlich, wenn ein automatisierter Prozess neue Daten abruft. Du kannst zum Beispiel die API alle fünf Minuten mit PresetPeriod=Last24Hours, Sorting=Ascending und dem cursor-Wert aus der vorherigen Antwort aufrufen. Die API gibt die Zeilen aus, die seit deiner letzten Abfrage erstellt wurden. Das Data-Array kann leer sein, wenn noch keine neuen Zeilen verfügbar sind. Du kannst den cursor aus der Antwort beim nächsten Aufruf verwenden, um fortzufahren.