Seguir o @odata.nextLink do Microsoft Graph e lidar com o throttling 429 e os limites de batch

O que é

O guia de paginação do Microsoft Graph afirma 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," e que o 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." Dependendo da API, essa URL contém "either a $skiptoken or a $skip query parameter" além dos parâmetros originais da consulta, e o guia de paginação diz "don't try to extract the $skiptoken or $skip value and use it in a different request"; a referência de parâmetros de consulta descreve o skip token como "an opaque token that references the next page of results". Uma página "might contain zero or more results", portanto uma página vazia que traga um nextLink não indica o fim. A paginação pelo cliente está disponível em muitos endpoints por meio de $top (e, com menos abrangência, de $skip/$skipToken); os tamanhos de página padrão e máximo dependem de cada endpoint. Sobre o throttling, a orientação do Graph mostra o formato de uma requisição rejeitada: HTTP/1.1 429 Too Many Requests com um cabeçalho Retry-After que indica, em segundos, o tempo de espera sugerido, e um corpo JSON com o código de erro TooManyRequests. O próprio Graph recomenda tratar o 429 como sinal de detecção, porque "backing off requests using the Retry-After delay is the fastest way to recover from throttling"; quando nenhum Retry-After é retornado, ele recomenda backoff exponencial. Para operações em massa, a referência de batching JSON do Graph afirma claramente que "JSON batch requests are currently limited to 20 individual requests," e cada sub-requisição é avaliada individualmente contra os limites de throttling: as limitadas falham com 429, enquanto "the batch itself succeeds with a status code of 200 (OK)".

Por que importa

Como o @odata.nextLink já codifica um estado de paginação específico do provedor (que pode mudar entre versões da API ou usar um mecanismo diferente por recurso), qualquer cliente que tente interpretá-lo ou regenerá-lo, em vez de segui-lo exatamente como veio, vai quebrar silenciosamente na próxima atualização do Graph. As requisições em lote não compartilham o mesmo destino quanto ao throttling: uma sub-requisição de um batch pode ser limitada enquanto as outras dezenove têm sucesso.

Como aplicar

• Siga o @odata.nextLink como uma URL opaca, exatamente como foi retornada; não extraia nem reconstrua seus parâmetros de consulta.
• Use $top para pedir um tamanho de página prático quando o endpoint oferecer paginação pelo cliente, mas itere sempre seguindo o @odata.nextLink, em vez de presumir um número fixo de páginas.
• Ao receber 429, leia o Retry-After e aguarde essa quantidade de segundos antes de qualquer nova requisição ao mesmo endpoint ou a endpoints relacionados; evite novas tentativas imediatas, que as boas práticas do Graph desaconselham explicitamente, pois "all requests accrue against your usage limits."
• Mantenha os batches com no máximo 20 sub-requisições e verifique o código de status de cada sub-resposta: um 200 no nível do batch não significa que todas as sub-requisições tiveram sucesso.

Armadilhas

Criar um mecanismo de "retomada" que armazene um skipToken já extraído e tente encaixá-lo mais tarde em uma nova consulta; o Graph não documenta sua estrutura interna como estável. Repetir a tentativa de uma sub-requisição de batch limitada sem isolar quais dos até 20 itens de fato falharam.