Cursor
In REST- en HTTP-API’s helpt een cursor u door een grote resultatenset te bladeren wanneer de server niet alle rijen tegelijk kan retourneren. De server retourneert een batch rijen (bijvoorbeeld maximaal 100) plus een tekenreekswaarde die de server vertelt waar bij de volgende request hij verder moet gaan in de gesorteerde resultaten.
Wanneer de respons gepagineerd is, bevat het Cursor-object vaak:
Self— cursorwaarde voor de huidige pagina (de batch die u zojuist heeft ontvangen).Next— cursorwaarde voor de volgende pagina. Op de laatste pagina is deze leeg of weggelaten omdat er niets meer op te halen is.
Als er bijvoorbeeld 300 records zijn en de maximale paginagrootte 100 is, retourneert de eerste respons de rijen 1-100 en bevat het een Cursors-object met Next en Self. Roep het eindpunt opnieuw aan met de cursor ingesteld op de waarde Next uit de vorige respons om de volgende pagina met resultaten op te halen (bijvoorbeeld de rijen 101-200). Ga door met dit proces totdat de API geen Next-waarde meer retourneert, wat aangeeft dat er geen resultaten meer op te halen zijn.
Veel responses bevatten ook een Links-object met ready-to-request URL’s voor dezelfde pagina’s. Zie
Links voor meer informatie.
Voorbeeld
Een gepagineerde respons bevat vaak Data, Links en Cursors:
{
"Data": [ ... ],
"Cursors": {
"Next": "qKLVZ/HGD2XeFkiwNFWJK+nRDuOjjBRipct8qOfRjRmGUG8F5P1WzrQ4p3JFfXoErs96xb+DS0SAPW+XDUi9Zw/zdo4uHXL3TYBhodxfQQul3L4mwDk=",
"Self": "KYhsR26Se8cQbeQm+o3LXawJXu3Pe6NvSefBcMivZ5QA+rFcRUrHTErK+TrhrUN3Ss8QUing/+jUkjgl3QOvB3kf3AZ+EOubhya5s3CWF+HGWEQkQQ=="
},
"Links": {
...
},
}
U kunt beginnen met de meest recente data en teruggaan in de tijd (Sorting=Descending), of starten aan het begin van een tijdsbereik en naar het heden gaan (Sorting=Ascending).
Sorting=Ascending is handig wanneer een geautomatiseerd proces peilt op nieuwe data. U kunt de API bijvoorbeeld elke vijf minuten aanroepen met PresetPeriod=Last24Hours, Sorting=Ascending en de cursor-waarde uit de vorige respons. De API retourneert dan de rijen die zijn gegenereerd sinds uw laatste request. De Data-array kan leeg zijn als er nog geen nieuwe rijen beschikbaar zijn. U kunt de cursor uit de respons gebruiken bij de volgende aanroep om verder te gaan.