SDK do Microsoft Graph

Use esta habilidade ao integrar o Microsoft Graph em um aplicativo para acessar dados e serviços do Microsoft 365.

Sempre baseie a implementação na documentação atual do SDK do Microsoft Graph e na versão do SDK para a linguagem de destino, em vez de confiar apenas na memória.

Determine o idioma de destino primeiro

1. Use o fluxo de trabalho .NET quando o projeto contiver arquivos .cs, .csproj ou .sln, ou quando o usuário solicitar orientação em C#. Siga references/dotnet.md.
2. Use o fluxo de trabalho TypeScript / JavaScript quando o projeto contiver arquivos package.json, .ts ou .js, ou quando o usuário solicitar orientação em Node.js / navegador. Siga references/typescript.md.
3. Use o fluxo de trabalho Python quando o projeto contiver .py, pyproject.toml ou requirements.txt, ou quando o usuário solicitar orientação em Python. Siga references/python.md.
4. Se vários idiomas estiverem presentes, combine o idioma dos arquivos que estão sendo editados ou pergunte ao usuário.

Consulte sempre a documentação ao vivo

• Visão geral do Microsoft Graph: https://learn.microsoft.com/graph/overview
• Graph Explorer (experimente chamadas ao vivo): https://developer.microsoft.com/graph/graph-explorer
• Referência de permissões do Graph: https://learn.microsoft.com/graph/permissions-reference
• Use as ferramentas do MCP do Microsoft Docs quando disponíveis para buscar formas de API atuais e exemplos de SDK.

Autenticação — escolha o padrão correto

Selecionar o fluxo de autenticação errado é o erro mais comum na integração do Graph. Aplique esta árvore de decisão antes de escrever qualquer código de autenticação:

• Nunca use credenciais de cliente quando um contexto de usuário for necessário — o Graph impõe isso no nível da permissão (aplicativo vs. delegado).
• Prefira DefaultAzureCredential em aplicativos hospedados no Azure; ele tenta a identidade gerenciada primeiro e volta graciosamente para o desenvolvimento local.
• Nunca codifique segredos. Use variáveis de ambiente, Azure Key Vault ou o Gerenciador de Segredos.

Padrões de uso do SDK principal

Construindo o cliente

Sempre construa GraphServiceClient uma vez e reutilize-o (ele gerencia o cache de tokens internamente).

Passe uma credencial da biblioteca Azure Identity — nunca construa clientes HTTP brutos manualmente.

Fazendo chamadas

• Use a API de construtor fluente: client.Users[userId].Messages.GetAsync(...).
• Sempre await chamadas assíncronas.
• Especifique $select para limitar os campos retornados — o Graph retorna cargas úteis padrão grandes.
• Use $filter no lado do servidor em vez de filtrar coleções retornadas na memória.
• Use $expand para buscar recursos relacionados em uma única chamada quando os relacionamentos forem pequenos.

Paginação

O Graph pagina coleções. Nunca assuma que todos os itens chegam em uma única resposta:

• Verifique se há um @odata.nextLink na resposta.
• Use o auxiliar PageIterator do SDK (disponível em todos os três SDKs) para percorrer as páginas automaticamente.
• Defina $top para controlar o tamanho da página (o máximo varia por recurso, geralmente 999).

Padrões avançados

Requisições em lote

Combine até 20 chamadas independentes do Graph em uma única requisição HTTP usando o endpoint $batch. Use o lote quando:

• Inicializando dados para um painel ou agente que precisa de vários recursos antecipadamente.
• Reduzindo a latência em operações de alta contagem de chamadas.

As respostas em lote chegam fora de ordem — combine-as pelo campo id que você atribuiu a cada requisição.

Consultas delta

Use consultas delta para sincronizar alterações incrementalmente em vez de consultar coleções completas:

• Primeira chamada: GET /users/delta retorna todos os itens + um @odata.deltaLink.
• Chamadas subsequentes: use o deltaLink para receber apenas o que mudou desde a última sincronização.
• Suportado em: usuários, grupos, mensagens, eventos de calendário, canais do Teams e mais.
• Armazene o deltaLink de forma durável (banco de dados, blob) entre as execuções de sincronização.

Notificações de alteração (webhooks)

Assine alterações de recursos com POST /subscriptions:

• O Graph entrega eventos de alteração para sua URL de notificação HTTPS.
• As assinaturas expiram — renove-as antes de expirationDateTime (o máximo varia por recurso; geralmente de 1 a 3 dias para e-mail/calendário, até 4230 minutos para usuários/grupos).

…