@odata.nextLink bei Microsoft Graph folgen und mit 429-Drosselung und Batch-Limits umgehen

Worum es geht

Die Paging-Anleitung von Microsoft Graph hält fest: "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." Ein 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." Je nach API enthält diese URL "either a $skiptoken or a $skip query parameter" sowie die ursprünglichen Abfrageparameter. Die Anleitung weist an: "don't try to extract the $skiptoken or $skip value and use it in a different request". Die Referenz zu den Abfrageparametern bezeichnet das Skip-Token als "an opaque token that references the next page of results". Eine Seite "might contain zero or more results"; eine leere Seite mit einem nextLink bedeutet daher nicht, dass die Daten zu Ende sind. Clientseitiges Paging ist bei vielen Endpunkten über $top möglich (und, weniger verbreitet, über $skip/$skipToken); Standard- und Maximalwerte der Seitengrösse hängen vom jeweiligen Endpunkt ab. Zur Drosselung zeigt die Graph-Dokumentation, wie eine abgewiesene Anfrage aussieht: HTTP/1.1 429 Too Many Requests mit einem Retry-After-Header, der eine empfohlene Wartezeit in Sekunden angibt, und einem JSON-Body mit dem Fehlercode TooManyRequests. Graph selbst rät, 429 als Erkennungssignal zu verwenden, denn "backing off requests using the Retry-After delay is the fastest way to recover from throttling". Wird kein Retry-After zurückgegeben, empfiehlt Graph exponentielles Backoff. Für Massenoperationen stellt die Referenz zum JSON-Batching unmissverständlich fest: "JSON batch requests are currently limited to 20 individual requests." Jede Teilanfrage wird einzeln gegen die Drosselungslimits geprüft: Gedrosselte Teilanfragen scheitern mit 429, während "the batch itself succeeds with a status code of 200 (OK)".

Warum es wichtig ist

Der @odata.nextLink kodiert bereits anbieterspezifischen Paging-Zustand, der sich zwischen API-Versionen ändern oder pro Ressource einen anderen Mechanismus nutzen kann. Ein Client, der die URL parst oder neu erzeugt, statt ihr unverändert zu folgen, funktioniert deshalb nach dem nächsten Graph-Update unbemerkt nicht mehr. Batch-Anfragen teilen kein gemeinsames Drosselungsschicksal: Eine Teilanfrage in einem Batch kann gedrosselt werden, während die neunzehn anderen erfolgreich sind.

So wird es angewendet

• @odata.nextLink als opake URL genau so aufrufen, wie sie zurückgegeben wurde; ihre Abfrageparameter weder extrahieren noch rekonstruieren.
• Mit $top eine praxistaugliche Seitengrösse anfordern, sofern der Endpunkt clientseitiges Paging unterstützt, die Schleife aber stets anhand von @odata.nextLink steuern und nicht von einer festen Seitenzahl ausgehen.
• Bei 429 den Header Retry-After lesen und diese Anzahl Sekunden warten, bevor weitere Anfragen an denselben oder einen verwandten Endpunkt folgen. Sofortige Wiederholungen vermeiden; die Best Practices von Graph raten ausdrücklich davon ab, da "all requests accrue against your usage limits."
• Batches auf höchstens 20 Teilanfragen begrenzen und den Statuscode jeder Teilantwort einzeln prüfen: Ein 200 auf Batch-Ebene heisst nicht, dass jede Teilanfrage erfolgreich war.

Stolpersteine

Ein "resume"-Mechanismus, der einen geparsten skipToken speichert und ihn später in eine neue Abfrage einzufügen versucht; Graph dokumentiert dessen interne Struktur nicht als stabil. Eine gedrosselte Batch-Teilanfrage zu wiederholen, ohne vorher einzugrenzen, welche der bis zu 20 Einzelanfragen tatsächlich fehlgeschlagen ist.