Base de connaissances GetMyBot

Pagination

Récupérer une longue liste par morceaux sans manquer d’enregistrements : taille de page, décalage offset et curseur before.

Sur cette page

L’API renvoie les longues listes, comme les clients ou les messages, par morceaux appelés pages. Charger les pages suivantes est la pagination. Une application n’a ainsi pas besoin de récupérer tout l’historique en une seule requête.

Deux méthodes indiquent où reprendre : sauter un nombre d’éléments déjà lus (décalage) ou transmettre un repère vers le dernier élément lu (curseur). La méthode prise en charge par chaque endpoint figure dans la référence API.

Méthode 1 : offset et X-Total-Count

limit indique la taille de la page, offset le nombre d’enregistrements à sauter. Par exemple, limit=50&offset=100 demande jusqu’à 50 éléments après les 100 premiers. Ajoutez ces paramètres après ? dans l’URL :

curl -H "Authorization: Bearer <JETON_PERSONNEL>" \
  "https://votre-domaine/api/bots/BOT_ID/users?limit=50&offset=100"

Le total figure dans l’en-tête de réponse X-Total-Count. Après chaque réponse, augmentez offset du nombre réellement reçu, tant qu’il reste inférieur à X-Total-Count. Le corps de la réponse est le tableau des éléments de la page courante.

Le décalage a une limite

On ne peut pas parcourir indéfiniment la liste par décalage. Un offset supérieur à 100 000 produit 400 sur tout endpoint qui accepte le décalage. La réponse propose de réduire le résultat avec un filtre ou d’utiliser un curseur.

Un grand décalage coûte cher à la base de données : elle doit examiner les lignes sautées pour produire la page suivante. Pour les grandes listes, préférez des filtres, un curseur ou un export.

Si la liste dépasse 100 000 éléments, vous n’atteindrez pas sa fin avec offset. Vous pouvez :

  • filtrer selon les critères de l’endpoint, tels que période, canal ou état ;
  • passer au curseur si l’endpoint le prend en charge, comme les listes de paiements et d’enregistrements de collection qui acceptent les deux méthodes ;
  • utiliser l’export de la section si vous avez besoin de l’ensemble des données.

Chaque endpoint fixe sa propre taille maximale de page

Il n’existe pas de valeur maximale unique pour limit : selon la liste, elle peut être de 200, 500 ou 1 000. La valeur exacte figure dans la référence API.

La réaction à un limit trop élevé varie aussi :

  • certains endpoints refusent la requête avec 400 et un message comme « limit must be at most 500, got 5000 » ;
  • d’autres utilisent silencieusement la valeur par défaut, souvent 100, et renvoient moins d’éléments que demandé.

En pratique, ne supposez jamais que la page reçue a la taille demandée. Mesurez le tableau reçu et augmentez offset de cette longueur. Sinon, demander 5 000 éléments et n’en recevoir que 100 pourrait vous faire sauter 98 % des données sans erreur.

Pour la même raison, une page vide ne doit pas être votre seul signal de fin : prenez en compte X-Total-Count et le nombre réel d’éléments.

Méthode 2 : curseur before et has_more

Le curseur sert aux flux ordonnés dans le temps, comme les messages d’une conversation. La requête accepte limit et éventuellement before, l’identifiant ou le repère du dernier élément déjà reçu :

curl -H "Authorization: Bearer <JETON_PERSONNEL>" \
  "https://votre-domaine/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

La réponse contient une page et l’indicateur has_more. Tant qu’il vaut true, recommencez en plaçant dans before le curseur du dernier élément obtenu. Quand il vaut false, vous avez atteint la dernière page.

Choisir la méthode

C’est l’endpoint qui fixe la méthode. Les listes de référence utilisent souvent offset et X-Total-Count ; les flux chronologiques utilisent before et has_more. Vérifiez la page de l’endpoint dans la référence API.

Pour aller plus loin