Microsoft Graph : maîtriser pagination, batching et throttling

L’essentiel

La pagination exige de suivre @odata.nextLink jusqu’à son absence. Recalculer l’URL ou ignorer la page suivante produit un export incomplet sans forcément générer d’erreur.

Le JSON batching combine jusqu’à vingt sous-requêtes dans un appel HTTP, mais chaque sous-requête est évaluée séparément. Le lot peut répondre 200 alors que certaines réponses internes sont 429 ou en erreur.

Lors d’un throttling, le client respecte Retry-After. Sans en-tête, il utilise un backoff exponentiel borné avec jitter. Les SDK gèrent certains retries individuels, mais les sous-requêtes batchées échouées doivent être reconstruites explicitement.

La pagination exige de suivre @odata.nextLink jusqu’à son absence. Recalculer l’URL ou ignorer la page suivante produit un export incomplet sans forcément générer d’erreur.

Pourquoi cette technologie existe

Les limites Graph varient par service, type de ressource, tenant et nature des opérations. Une boucle agressive de polling ou de writes peut pénaliser l’application et le tenant.

La robustesse inclut aussi permissions minimales, authentification, corrélation, idempotence et gestion des erreurs. Le batching réduit les allers-retours, pas les limites de chaque service.

Pagination, batching et throttling Graph s’appuie sur la chaîne Request → Page/Batch → Response → Retry. Comprendre le rôle de chaque étape permet de distinguer la demande envoyée, le traitement réellement effectué et l’état finalement observé.

Les dépendances importantes sont application Entra et permissions minimales, endpoint et version vérifiés, secret absent du code et méthode d’authentification sûre, opérations d’écriture idempotentes ou protégées. Elles font partie du fonctionnement de la technologie: leur absence peut expliquer un résultat sans remettre en cause le composant étudié.

Les cas limites les plus utiles à connaître sont Export incomplet, Batch 200 mais objets manquent et 429 répétés. Ils montrent où le modèle nominal peut diverger et quelles données permettent de lire cette divergence.

Le parcours devient plus concret en suivant les composants dans leur ordre réel. Request ouvre la séquence: URI, permission, filtre et identifiant de corrélation. Page/Batch prend ensuite le relais: nextLink ou enveloppe de sous-requêtes. Le traitement se poursuit avec Response, où Statut global et statuts individuels. Enfin, Retry ferme la boucle: Retry-After, backoff, jitter et reprise idempotente. Cette lecture évite de confondre un ordre envoyé avec son exécution, puis son exécution avec l’état restitué à l’administrateur. Elle indique aussi où chercher l’heure, l’identité et le résultat qui permettront de rapprocher deux observations.

Les limites se comprennent mieux à partir de situations concrètes. « Export incomplet » conduit d’abord à vérifier Compteur pages et nextLink, car la cause possible est nextLink ignoré. Pour « Batch 200 mais objets manquent », la preuve utile devient Status par id. Les cas « 429 répétés » et « 403 » montrent enfin que deux symptômes proches peuvent appartenir à des phases différentes. Cette distinction n’est pas un détour de dépannage: elle fait partie du modèle de fonctionnement et explique la manière dont Pagination, batching et throttling Graph expose ses états, ses délais et ses erreurs.

Dans un environnement réel, les conditions application Entra et permissions minimales, endpoint et version vérifiés, secret absent du code et méthode d’authentification sûre, opérations d’écriture idempotentes ou protégées doivent être réunies en même temps. La validation porte ensuite sur toutes pages parcourues, lots de vingt maximum, chaque sous-réponse inspectée et Retry-After respecté. Ce croisement est important: un prérequis confirme que le scénario peut fonctionner, alors qu’un contrôle de validation prouve qu’il a effectivement fonctionné. Il reste donc possible d’avoir une plateforme éligible mais mal configurée, ou une première exécution réussie dont l’état n’est pas encore visible dans le service. Le modèle présenté dans cet article sert précisément à lire ces écarts sans attribuer trop vite le résultat au mauvais composant. Il donne aussi au support un vocabulaire commun pour décrire l’étape atteinte et la preuve encore manquante.

Architecture, composants et flux de données

Une collection Graph retourne value et peut fournir @odata.nextLink. Ce lien est opaque: je l’utilise tel quel, car il peut contenir skiptoken, filtres encodés ou état de service.

Un batch POST /$batch contient des requêtes avec id, method, url et éventuellement body/headers. L’ordre n’est pas garanti sans dependsOn. Vingt requêtes constituent la limite d’un lot JSON Graph.

Le throttling retourne généralement 429 et Retry-After. Un batch HTTP 200 n’indique que l’acceptation de l’enveloppe; le client inspecte status et headers de chaque réponse avant de marquer le lot réussi.

Prérequis, compatibilité et limites de support

Le fonctionnement décrit suppose application Entra et permissions minimales, endpoint et version vérifiés, secret absent du code et méthode d’authentification sûre, opérations d’écriture idempotentes ou protégées, journal corrélé et limites de retry. Ces conditions permettent de distinguer une limite de Pagination, batching et throttling Graph d’un scénario simplement non éligible.

• application Entra et permissions minimales
• endpoint et version vérifiés
• secret absent du code et méthode d’authentification sûre
• opérations d’écriture idempotentes ou protégées
• journal corrélé et limites de retry

Cycle de fonctionnement, étape par étape

Le cycle de Pagination, batching et throttling Graph traverse Request → Page/Batch → Response → Retry. La procédure détaille ce que produit chaque composant et la preuve attendue avant de passer à l’étape suivante.

Dans Pagination, batching et throttling Graph, les étapes « Valider une requête minimale », « Implémenter la pagination », « Créer des batches bornés », « Rejouer seulement les échecs » séparent l’intention, son transport, son traitement et le résultat final.

Pagination sûre

Je conserve les résultats page par page et un compteur. Si une page échoue, je garde le dernier nextLink validé pour reprendre sans recommencer tout le tenant.

Je n’ajoute pas manuellement $skip lorsque le service fournit nextLink. La forme de pagination appartient à l’endpoint.

Les filtres côté serveur réduisent le volume lorsqu’ils sont supportés. Je vérifie leurs capacités sur la documentation de la ressource et je n’interprète pas un filtre ignoré comme une preuve d’absence.

Batching et réponses partielles

Chaque request reçoit un id, utilisé pour relier réponse, objet métier et opération. dependsOn exprime un ordre, mais une dépendance échouée doit être traitée explicitement.

Je sépare les lots de lecture et d’écriture. Pour les writes, je prévois la répétition partielle et je vérifie l’état avant replay afin d’éviter doublons ou modifications concurrentes.

Les 429 internes fournissent parfois retry-after dans le contenu de la sous-réponse. Le SDK ne rejoue pas automatiquement ces éléments batchés; mon code extrait le délai et ne reconstruit que les échecs transitoires.

Backoff, observabilité et limites

Retry-After est prioritaire. À défaut, le backoff exponentiel augmente l’attente à chaque tentative, ajoute un jitter et respecte un plafond. Une boucle infinie est interdite.

Je journalise request-id, client-request-id, endpoint, statut, tentative, durée et nombre d’objets sans consigner token ou données sensibles.

Pour une extraction massive, je vérifie si Graph Data Connect ou un service de reporting est plus adapté. Réduire artificiellement le délai entre requêtes ne transforme pas Graph REST en pipeline de données bulk.

Interfaces d’observation, commandes et exemples

Les exemples rendent visibles endpoint/version, permissions consenties, nombre de pages, nextLink final absent. Leur intérêt est d’identifier le producteur de chaque donnée et le moment où elle est mise à jour.

Pour Pagination, batching et throttling Graph, les interfaces documentées restent la référence de conception. Les fichiers, tâches ou clés observés localement servent à expliquer un état précis et peuvent évoluer avec le composant.

# Collecte de diagnostic
$ErrorActionPreference = 'Stop'
try {
  $uri = 'https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$top=100'
  $items = [System.Collections.Generic.List[object]]::new()
  while ($uri) {
    $page = Invoke-MgGraphRequest -Method GET -Uri $uri
    foreach ($item in $page.value) { $items.Add($item) }
    $uri = $page.'@odata.nextLink'
  }
  $items
}
catch { Write-Error "Lecture Graph impossible : $($_.Exception.Message)"; exit 1 }

BatchId=20260818-01 HttpStatus=200 Responses=20
SubRequest=07 Status=429 RetryAfter=12 Action=QueueRetry
SubRequest=12 Status=503 RetryAfter=absent Backoff=8.4
RetryBatch=20260818-01-R1 Requests=2 Delay=12
Result Success=20 Failed=0 Attempts=2

Observabilité : où lire l’état réel

Je ne journalise jamais Authorization. Je conserve les identifiants de corrélation, les statuts, Retry-After, le nombre d’objets et l’endpoint sans paramètres sensibles.

Un résultat incomplet sans erreur peut provenir d’une pagination interrompue. Je compare le nombre de pages, le compteur d’objets et la présence finale de nextLink avant de publier l’export.

• endpoint/version
• permissions consenties
• nombre de pages
• nextLink final absent
• statut par sous-requête
• Retry-After et tentatives
• request-id/client-request-id

Validation du modèle et cas d’usage

Le modèle est cohérent lorsque toutes pages parcourues, lots de vingt maximum, chaque sous-réponse inspectée et Retry-After respecté. Ces contrôles relient la configuration du service au résultat réellement observé.

• toutes pages parcourues
• lots de vingt maximum
• chaque sous-réponse inspectée
• Retry-After respecté
• limite de tentatives
• aucun secret dans logs

Limites, modes de panne et lecture des erreurs

Les écarts connus de Pagination, batching et throttling Graph incluent Export incomplet, Batch 200 mais objets manquent, 429 répétés, 403. Le tableau les replace dans leur phase et précise la donnée à contrôler.

Adoption progressive, réversibilité et vigilance

L’adoption de Pagination, batching et throttling Graph commence sur le périmètre Microsoft Graph v1.0 en priorité, REST et PowerShell, lectures volumineuses et lots JSON. Les limites et actions de réversibilité ci-dessous cadrent la progression.