Suivre @odata.nextLink dans Microsoft Graph et gérer la limitation 429 et les limites du traitement par lots

Ce que c'est

Le guide de pagination de Microsoft Graph indique que "when there's at least one more page of data available, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the next page of results", et qu'un client "must continue to call Microsoft Graph with the @odata.nextLink property returned in each response until the @odata.nextLink property is no longer returned." Selon l'API, cette URL contient "either a $skiptoken or a $skip query parameter" ainsi que les paramètres de requête d'origine. Le guide précise "don't try to extract the $skiptoken or $skip value and use it in a different request" ; la référence des paramètres de requête décrit le skip token comme "an opaque token that references the next page of results". Une page "might contain zero or more results" : une page vide accompagnée d'un nextLink n'est donc pas la fin de la collection. La pagination côté client est disponible sur de nombreux endpoints via $top (et, de façon moins répandue, via $skip/$skipToken) ; les tailles de page par défaut et maximale dépendent de chaque endpoint. Concernant la limitation de débit, la documentation de Graph montre à quoi ressemble une requête rejetée : HTTP/1.1 429 Too Many Requests avec un en-tête Retry-After indiquant en secondes la durée d'attente suggérée, et un corps JSON contenant le code d'erreur TooManyRequests. Graph recommande de prendre 429 comme signal de détection, car "backing off requests using the Retry-After delay is the fastest way to recover from throttling" ; lorsqu'aucun Retry-After n'est renvoyé, il préconise un backoff exponentiel. Pour les opérations en masse, la référence du traitement par lots JSON de Graph est sans ambiguïté : "JSON batch requests are currently limited to 20 individual requests," chaque sous-requête étant évaluée séparément par rapport aux limites de débit : celles qui sont limitées échouent avec 429, tandis que "the batch itself succeeds with a status code of 200 (OK)".

Pourquoi c'est important

Comme @odata.nextLink encode déjà un état de pagination propre au fournisseur (qui peut changer d'une version d'API à l'autre ou reposer sur un mécanisme différent selon la ressource), tout client qui tente de l'analyser ou de le régénérer au lieu de le suivre tel quel cessera de fonctionner, sans signal d'erreur, à la prochaine mise à jour de Graph. Les sous-requêtes d'un batch ne partagent pas le même sort face à la limitation : l'une peut être limitée alors que les dix-neuf autres réussissent.

Comment l'appliquer

• Suivre @odata.nextLink comme une URL opaque, exactement telle qu'elle est renvoyée ; ne pas en extraire ni en reconstruire les paramètres de requête.
• Utiliser $top pour demander une taille de page raisonnable lorsqu'un endpoint prend en charge la pagination côté client, mais toujours boucler sur @odata.nextLink plutôt que de supposer un nombre fixe de pages.
• En cas de 429, lire Retry-After et attendre ce nombre de secondes avant toute nouvelle requête vers le même endpoint ou un endpoint apparenté ; éviter les nouvelles tentatives immédiates, que les bonnes pratiques de Graph déconseillent expressément puisque "all requests accrue against your usage limits."
• Limiter les batchs à 20 sous-requêtes au maximum et vérifier le code de statut propre à chaque sous-réponse : un 200 au niveau du batch ne signifie pas que toutes les sous-requêtes ont réussi.

Pièges

Construire un mécanisme de « reprise » qui stocke un skipToken extrait de l'URL, puis tente de l'insérer plus tard dans une nouvelle requête ; Graph ne documente pas sa structure interne comme stable. Relancer une sous-requête de batch limitée sans identifier lequel des 20 éléments au plus a réellement échoué.