Por que usar um Microsoft Graph SDK

Quando o Proxy de Desenvolvimento deteta que a sua aplicação faz pedidos da API Microsoft Graph sem usar um SDK, sugere migrar para um SDK. Esta orientação existe porque os SDKs Microsoft Graph simplificam significativamente o trabalho com APIs Microsoft Graph e ajudam a construir aplicações mais robustas.

Benefícios dos SDKs Microsoft Graph

Os SDKs Microsoft Graph oferecem inúmeras vantagens em relação à realização de chamadas HTTP brutas.

Gestão de autenticação incorporada

Os SDKs integram-se com bibliotecas de autenticação como a Microsoft Authentication Library (MSAL), gerindo automaticamente a aquisição, atualização e gestão dos tokens. Não precisas de implementar manualmente o fluxo OAuth 2.0 nem preocupar-te com a expiração do token.

Lógica automática de tentativa para limitação

Os serviços Microsoft 365 implementam restrição para garantir a fiabilidade do serviço. Quando a sua aplicação recebe uma 429 Too Many Requests resposta, o SDK gere automaticamente as tentativas com atrasos de recuo apropriados, respeitando o Retry-After cabeçalho que o Microsoft Graph retorna.

Tratamento adequado da paginação

Muitos endpoints Microsoft Graph devolvem resultados paginados. Os SDKs fornecem iteradores incorporados que gerem de forma transparente a obtenção de páginas subsequentes, por isso não precisa de rastrear manualmente os valores de @odata.nextLink nem de fazer outros pedidos.

Segurança de tipos e IntelliSense

Os SDKs fornecem modelos fortemente tipados para pedidos e respostas, dando-lhe suporte IntelliSense no seu IDE. Os modelos de tipo reduzem erros e aceleram o desenvolvimento ao detetar problemas em tempo de compilação em vez de em tempo de execução.

Suporte para processamento em lote

Os SDKs suportam agrupar múltiplos pedidos numa única chamada HTTP, reduzindo a sobrecarga da rede e melhorando o desempenho. O batching também ajuda a manter-se dentro dos limites de restrição ao reduzir o número de pedidos individuais.

Consultas Delta

Os SDKs simplificam a implementação de consultas delta que permitem sincronizar eficientemente as alterações de dados desde o seu último pedido. Usar consultas delta é crucial para construir aplicações responsivas que precisam de se manter sincronizadas com os dados do Microsoft 365.

Arquitetura de camada intermédia para personalização

Os SDKs usam um pipeline middleware personalizável para adicionar registos, modificar cabeçalhos, implementar políticas de retentativas personalizadas ou injetar outros comportamentos sem alterar o código da sua aplicação.

Padrões de API consistentes

Os SDKs fornecem padrões consistentes entre diferentes plataformas e linguagens, facilitando a partilha de conhecimento entre membros da equipa e entre projetos.

O que as chamadas HTTP brutas não captam

Quando faz chamadas HTTP brutas para o Microsoft Graph, precisa de implementar várias funcionalidades críticas por si próprio.

Implementação manual da lógica de tentativas

Sem um SDK, deve implementar lógica de retentativas para o tratamento de 429 responses, incluindo:

• Análise dos valores dos Retry-After cabeçalhos
• Implementação de recuo exponencial
• Lidar com diferentes cenários de erro
• Evitar explosões de repetições sob carga pesada

Gestão manual da paginação

Você precisa de:

• Verifique todas as respostas para @odata.nextLink
• Faça mais pedidos para cada página
• Resultados agregados em várias páginas
• Lidar com falhas parciais durante a paginação

Boilerplate de gestão de erros

O Microsoft Graph pode devolver várias respostas de erro com diferentes estruturas. Sem SDK, precisas de:

• Corpos de resposta a erros de análise
• Trate de diferentes códigos de estado HTTP de forma adequada
• Extrair mensagens de erro significativas para registo
• Implementar comportamento de alternativa para erros inesperados

Complexidade de autenticação

Gerir a autenticação manualmente requer:

• Implementação de fluxos OAuth 2.0
• Armazenamento e segurança de tokens
• Gestão da renovação dos tokens antes da expiração
• Gerir diferentes cenários de autenticação (permissões delegadas vs. permissões de aplicação)

SDKs disponíveis

A Microsoft fornece SDKs oficiais para as seguintes plataformas:

Alternativas à utilização de um SDK

Embora os SDKs sejam recomendados para a maioria dos cenários, há casos em que outras abordagens podem ser mais adequadas:

Cliente gerado por Kiota

Se a sua aplicação usar apenas um pequeno subconjunto das APIs Microsoft Graph, considere gerar um cliente com o Kiota em vez de usar o SDK completo. O Kiota gera um cliente leve e fortemente tipado, adaptado às APIs específicas de que precisa, reduzindo a sua pegada de dependências enquanto continua a oferecer segurança de tipos e construção de solicitações.

Utilização mínima da API

Se estiveres a escrever um script ou ferramenta rápida que faz apenas algumas chamadas de API, a sobrecarga de configurar um SDK pode não ser justificada. Nestes casos, as chamadas HTTP diretas podem ser mais simples. No entanto, ainda precisa de tratar da autenticação e das respostas de erro por si próprio, o que pode rapidamente adicionar complexidade mesmo para scripts simples.

Linguagem não suportada

Se estiveres a usar uma linguagem de programação que não tem um SDK oficial, precisas de fazer chamadas HTTP diretas. Também podes considerar usar o Kiota para gerar um cliente para a tua linguagem, se o Kiota o suportar.

Quando o SDK ainda não suporta uma funcionalidade específica

O Microsoft Graph adiciona continuamente novas funcionalidades. Ocasionalmente, uma nova API ou funcionalidade pode não ter imediatamente uma API fluente no SDK. Na maioria dos casos, ainda pode usar o SDK para fazer pedidos arbitrários usando uma cadeia de caminho, o que lhe dá os benefícios do middleware do SDK (autenticação, tentativas, registos) sem necessidade de construtores de pedidos tipados. Se o SDK não oferecer suporte ao pedido de forma alguma, pode recorrer a chamadas HTTP diretas até que o suporte ao SDK seja adicionado.

Ambientes sensíveis ao desempenho

Em cenários como funções serverless ou edge computing, onde o tempo de arranque a frio e o tamanho do pacote são importantes, uma abordagem mais leve usando clientes gerados por Kiota ou chamadas HTTP diretas pode ser mais adequada.

Próximos passos

Aprenda como atualizar a sua aplicação para usar um Microsoft Graph SDK:

Conteúdo relacionado

• Visão geral do SDK do Microsoft Graph
• Escolha um fornecedor de autenticação Microsoft Graph
• Instalar o Microsoft Graph SDK
• Melhores práticas para trabalhar com o Microsoft Graph