Seguir @odata.nextLink en Microsoft Graph y gestionar el throttling 429 y los límites de lotes

Qué es

La guía de paginación de Microsoft Graph indica 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", y que el cliente "must continue to call Microsoft Graph with the @odata.nextLink property returned in each response until the @odata.nextLink property is no longer returned". Según la API, esa URL contiene "either a $skiptoken or a $skip query parameter" además de los parámetros de consulta originales, y la guía advierte: "don't try to extract the $skiptoken or $skip value and use it in a different request". La referencia de parámetros de consulta describe el skip token como "an opaque token that references the next page of results". Una página "might contain zero or more results", de modo que una página vacía con un nextLink no significa que la paginación haya terminado. Muchos endpoints permiten paginar desde el cliente con $top (y, con menor alcance, con $skip y $skipToken); los tamaños de página predeterminado y máximo dependen de cada endpoint. En cuanto al throttling, la guía de Graph muestra el aspecto de una solicitud rechazada: HTTP/1.1 429 Too Many Requests con un encabezado Retry-After que indica en segundos la espera sugerida, y un cuerpo JSON con el código de error TooManyRequests. Graph aconseja tomar 429 como señal de detección, porque "backing off requests using the Retry-After delay is the fastest way to recover from throttling"; si no se devuelve Retry-After, recomienda un retroceso exponencial. Para las operaciones masivas, la referencia de lotes JSON de Graph afirma sin rodeos que "JSON batch requests are currently limited to 20 individual requests," y que cada subsolicitud se evalúa por separado frente a los límites de throttling: las que se ven limitadas fallan con 429, mientras que "the batch itself succeeds with a status code of 200 (OK)".

Por qué importa

Como @odata.nextLink ya codifica un estado de paginación propio del proveedor (que puede cambiar entre versiones de la API o usar un mecanismo distinto según el recurso), cualquier cliente que intente analizarlo o regenerarlo en lugar de seguirlo tal cual dejará de funcionar sin avisar con la siguiente actualización de Graph. Además, las solicitudes de un lote no comparten el mismo destino frente al throttling: una subsolicitud puede ser limitada mientras las otras diecinueve se completan correctamente.

Cómo aplicarlo

• Sigue @odata.nextLink como una URL opaca, exactamente como se devuelve; no extraigas ni reconstruyas sus parámetros de consulta.
• Usa $top para pedir un tamaño de página razonable cuando el endpoint admita paginación desde el cliente, pero itera siempre según @odata.nextLink en lugar de suponer un número fijo de páginas.
• Ante un 429, lee Retry-After y espera esa cantidad de segundos antes de enviar otra solicitud al mismo endpoint o a uno relacionado; evita los reintentos inmediatos, que las buenas prácticas de Graph desaconsejan expresamente porque "all requests accrue against your usage limits."
• Mantén los lotes en 20 subsolicitudes como máximo y comprueba el código de estado de cada subrespuesta: un 200 a nivel de lote no significa que todas las subsolicitudes hayan tenido éxito.

Trampas

Construir un mecanismo de «reanudación» que guarde un skipToken ya analizado e intente insertarlo más tarde en una consulta nueva; Graph no documenta su estructura interna como estable. Reintentar una subsolicitud limitada de un lote sin aislar cuál de los hasta 20 elementos falló realmente.