Champ de l’API Cursor

Cursor

Dans les API REST et HTTP, le curseur vous aide à parcourir un large ensemble de résultats lorsque le serveur ne peut pas renvoyer toutes les lignes en une seule fois. Le serveur renvoie un ensemble de lignes (par exemple, jusqu’à 100 lignes) ainsi qu’une chaîne de caractères qui indique au serveur où reprendre dans les résultats triés lors de la requête suivante.

Lorsque la réponse est paginée, l’objet Cursor inclut généralement :

• Self : valeur de curseur pour la page en cours (le lot que vous venez de recevoir).
• Next : valeur de curseur pour la page suivante. Sur la dernière page, cette valeur est vide ou absente car il n’y a plus de résultats à récupérer.

Par exemple, si vous avez 300 enregistrements et que la taille de page maximale est de 100 lignes, la première réponse renvoie les lignes 1 à 100 et inclut un objet Cursors avec Next et Self. Pour récupérer la page de résultats suivante (par exemple, les lignes 101 à 200), appelez à nouveau l’endpoint en définissant le paramètre cursor sur la valeur Next de la réponse précédente. Continuez ce processus jusqu’à ce que l’API ne renvoie plus de valeur Next, ce qui indique qu’il n’y a plus de résultats à récupérer.

De nombreuses réponses incluent aussi un objet Links avec des URL prêtes à être appelées pour les mêmes pages. Pour en savoir plus, reportez-vous à notre article Champ de l’API Links.

Exemple

Une réponse paginée inclut souvent les valeurs Data, Links et Cursors :

{
  "Data": [ ... ],
  "Cursors": {
    "Next": "qKLVZ/HGD2XeFkiwNFWJK+nRDuOjjBRipct8qOfRjRmGUG8F5P1WzrQ4p3JFfXoErs96xb+DS0SAPW+XDUi9Zw/zdo4uHXL3TYBhodxfQQul3L4mwDk=",
    "Self": "KYhsR26Se8cQbeQm+o3LXawJXu3Pe6NvSefBcMivZ5QA+rFcRUrHTErK+TrhrUN3Ss8QUing/+jUkjgl3QOvB3kf3AZ+EOubhya5s3CWF+HGWEQkQQ=="
  },
    "Links": {
      ...
  },
}

Vous pouvez commencer par les données les plus récentes puis remonter le temps (Sorting=Descending) ou commencer au début d’une période et revenir vers le présent (Sorting=Ascending).

Le paramètre Sorting=Ascending lorsqu’un processus automatisé effectue des appels réguliers pour récupérer de nouvelles données. Par exemple, vous pouvez appeler l’API toutes les cinq minutes avec les valeurs PresetPeriod=Last24Hours, Sorting=Ascending et la valeur cursor tirée de la réponse précédente. L’API renvoie alors les lignes produites depuis votre dernière requête. Le tableau Data peut être vide si aucune ligne n’est encore disponible. Vous pouvez utiliser la valeur cursor de la réponse pour poursuivre lors de l’appel suivant.