Práticas recomendadas para trabalhar com o Microsoft Graph

  • Artigo

Este artigo descreve as práticas recomendadas que você pode aplicar para ajudar seus aplicativos a aproveitar ao máximo o Microsoft Graph, seja aprendendo sobre o Microsoft Graph, melhorando o desempenho do aplicativo ou tornando seu aplicativo mais confiável para os usuários finais.

Usar o Graph Explorer para saber mais sobre a API

A melhor maneira de começar a explorar os dados disponíveis pelo Microsoft Graph é usando o Graph Explorer. O Graph Explorer permite criar solicitações REST (com suporte completo para CRUD), adaptar os cabeçalhos de solicitação HTTP e ver as respostas dos dados. Para ajudar você a começar, o Graph Explorer também oferece um conjunto de consultas de exemplo.

Experimente novas APIs antes de integrá-las em seu aplicativo.

Autenticação

Para acessar dados por meio do Microsoft Graph, seu aplicativo precisará adquirir um token de acesso OAuth 2.0 e apresentá-lo ao Microsoft Graph em uma das seguintes opções:

  • O cabeçalho de solicitação HTTP Authorization, como um token de Portador
  • O construtor do cliente gráfico ao usar uma biblioteca de cliente do Microsoft Graph

Use a API da Biblioteca de Autenticação Microsoft, MSAL, para adquirir o token de acesso para o Microsoft Graph.

Aplique as seguintes práticas recomendadas de consentimento e autorização ao aplicativo:

  • Aplicar privilégios mínimos. Conceda aos usuários e aplicativos apenas a permissão com privilégios mínimos necessário para chamar a API. Verifique a seção de permissões nos tópicos do método (por exemplo, confira criando um usuário) e escolha as permissões com privilégios mínimos. Por exemplo, se o aplicativo ler apenas o perfil do usuário conectado no momento, conceda User.Read em vez de User.ReadBasic.All. Se um aplicativo não ler o calendário do usuário, não conceda a permissão Calendars.Read. Uma ver uma lista completa de permissões, confira referência de permissões.

  • Use o tipo de permissão correto com base nos cenários. Evite usar tanto o aplicativo quanto as permissões delegadas no mesmo aplicativo. Se você estiver criando um aplicativo interativo em que um usuário conectado esteja presente, seu aplicativo deverá usar as permissões delegadas. Se, no entanto, seu aplicativo for executado sem um usuário conectado, como um serviço ou daemon em segundo plano, seu aplicativo deverá usar as permissões de aplicativo.

    Cuidado

    O uso de permissões de aplicativo em cenários interativos pode colocar seu aplicativo em risco de conformidade e segurança. Ele pode elevar inadvertidamente os privilégios de um usuário para acessar dados, ignorando as políticas configuradas por um administrador.

  • Esteja atento ao configurar seu aplicativo. Isso afetará diretamente as experiências do usuário final e do administrador, além da adoção e segurança do aplicativo. Por exemplo:

    • O nome, logotipo, domínio, status de verificação do editor, declaração de privacidade e termos de uso do seu aplicativo aparecerão no consentimento e em outras experiências. Defina essas configurações com cuidado para que sejam compreendidas pelos usuários finais.
    • Leve em consideração quem consentirá com seu aplicativo, seja o usuário final ou administrador, e configure seu aplicativo para solicitar permissões de forma adequada.
    • Certifique-se de entender a diferença entre consentimento estático, dinâmico e incremental.

  • Considere usar aplicativos multilocatários. Tenha em mente que os clientes podem ter vários controles de aplicativo e consentimentos em diferentes estados. Por exemplo:

    • os administradores de locatários podem desabilitar a capacidade dos usuários finais permitirem os aplicativos. Nesse caso, um administrador precisaria consentir em nome de seus usuários.
    • Os administradores de locatários podem definir políticas de autorização personalizadas, como impedir que os usuários leiam perfis de outros usuários ou limitar a criação de grupos de autoatendimento a um conjunto limitado de usuários. Nesse caso, seu aplicativo deve esperar lidar com a resposta de erro 403 Forbidden ao agir em nome de um usuário.

Controlar as respostas com eficiência

Dependendo das solicitações feitas ao Microsoft Graph, seus aplicativos devem estar preparados para lidar com diferentes tipos de respostas. Veja a seguir algumas das práticas mais importantes a seguir para garantir que seu aplicativo se comporte de maneira confiável e previsível para seus usuários finais.

Paginação

Ao consultar uma coleção de recursos, você deve esperar que o Microsoft Graph retorne o conjunto de resultados em várias páginas, devido aos limites de tamanho da página do lado do servidor. Quando um conjunto de resultados se estende por várias páginas, o Microsoft Graph retorna uma propriedade @odata.nextLink na resposta que contém uma URL para a próxima página de resultados.

Por exemplo, listar as mensagens de usuários conectados:

GET https://graph.microsoft.com/v1.0/me/messages

retornaria uma resposta contendo uma propriedade @odata.nextLink, se o conjunto de resultados exceder o limite de tamanho de página do lado do servidor.

"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=23"

Observação

Seu aplicativo deve sempre lidar com a possibilidade das respostas serem paginadas sem processamento e usar a propriedade @odata.nextLink para obter o próximo conjunto paginado de resultados, até que todas as páginas do conjunto de resultados sejam lidas. A página final não conterá uma propriedade @odata.nextLink. Você deve incluir a URL inteira na propriedade @odata.nextLink na solicitação da próxima página de resultados, tratando toda a URL como uma cadeia de caracteres opaca.

Para saber mais, confira paginação.

Como tratar erros esperados

Como seu aplicativo tem que lidar com todas as respostas de erro (nos intervalos 400 e 500), dê especial atenção a determinados erros e respostas esperados que estão listados na tabela a seguir.

Tópico Código de erro HTTP Prática recomendada
O usuário não tem acesso 403 Se seu aplicativo estiver em execução, ele poderá encontrar esse erro, mesmo que tenha recebido as permissões necessárias por meio de uma experiência de consentimento. Nesse caso, é mais provável que o usuário conectado não tenha privilégios para acessar o recurso solicitado. Seu aplicativo deve fornecer um erro genérico de "Acesso negado" para o usuário conectado.
Não encontrado 404 Em certos casos, um recurso solicitado pode não ser encontrado. Por exemplo, um recurso pode não existir porque ainda não foi provisionado (como a foto de um usuário) ou porque foi excluído. Alguns recursos excluídos podem ser totalmente restaurados em até 30 dias após a exclusão, como recursos de usuários, grupos e aplicativos, portanto, o aplicativo também deve levar isso em consideração.
Limitação 429 As APIs podem limitar a qualquer momento por diversos motivos, portanto, seu aplicativo deve sempre estar preparado para manipular 429 respostas. Essa resposta de erro inclui o campo Retry-After no cabeçalho de resposta HTTP. Desativar solicitações usando o atraso Retry-After é a forma mais rápida de se recuperar da limitação. Para saber mais, confira limitação.
Serviço indisponível 503 O motivo mais provável é que os serviços estejam ocupados. Você deve empregar uma estratégia de retirada similar à 429. Além disso, você deve sempre fazer novas solicitações de novas tentativas em uma nova conexão HTTP.

Manipular futuros membros em enumerações evolutivas

Adicionar membros a enumerações existentes pode interromper aplicativos que já usam essas enumerações. Enumeração evolutiva é um mecanismo que o Microsoft Graph API usa para adicionar novos membros às enumerações existentes sem causar uma mudança radical aos aplicativos.

As enumeração evolutivas possuem um membro chamado sentinela que unknownFutureValue demarca membros conhecidos que foram definidos inicialmente na enumeração, e membros desconhecidos que são acrescentados posteriormente ou que serão definidos no futuro. Internamente, os membros conhecidos são mapeados para valores numéricos que são menores que o membro sentinela, e os membros desconhecidos são maiores que o membro sentinela. A documentação de uma enumeração evolutiva lista os possíveis valores de cadeia de caracteres em ordem crescente: membros conhecidos, seguidos por unknownFutureValue, seguidos por membros desconhecidos. Como outros tipos de enumerações, você deve sempre fazer referência aos membros de enumeração evolutiva por seus valores de cadeia.de cadeia de caracteres.

Por padrão, uma operação GET retorna apenas membros conhecidos por propriedades de tipos de enumeração evolutiva e seu aplicativo precisa lidar apenas com os membros conhecidos. Se você projetar seu aplicativo para também lidar com membros desconhecidos, poderá optar por receber esses membros usando um cabeçalho de solicitação Prefer HTTP:

Prefer: include-unknown-enum-members

Armazenamento de dados no local

Idealmente, seu aplicativo deveria fazer chamadas para o Microsoft Graph para recuperar dados em tempo real conforme necessário. Você só deve armazenar em cache ou armazenar dados localmente se um cenário específico assim o exigir e, se esse caso de uso for abrangido pelos seus termos de uso e pela política de privacidade e não violar os termos de uso das APIs da Microsoft. O aplicativo também deve implementar políticas adequadas de retenção e de exclusão.

Otimizações

Em geral, por motivos de desempenho e até mesmo segurança ou privacidade, você só deve obter os dados que seu aplicativo realmente precisar e nada mais.

Usar projeções

Escolha apenas as propriedades que seu aplicativo realmente precisa e nada mais já que isso evitará tráfego de rede e processamento de dados desnecessários em seu aplicativo (e no serviço).

Observação

Use o parâmetro de consulta $select para limitar as propriedades devolvidas por uma consulta àquelas exigidas pelo aplicativo.

Por exemplo, ao recuperar as mensagens do usuário conectado, você pode especificar que somente as propriedades from e subject sejam retornadas:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Quando você faz uma solicitação GET sem usar $select para limitar a quantidade de dados de propriedades, o Microsoft Graph inclui uma propriedade @microsoft.graph.tips que fornece uma recomendação de prática recomendada para usar $select semelhante à seguinte mensagem:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Como obter respostas mínimas

Para algumas operações, como PUT e PATCH (e, em alguns casos, POST), se seu aplicativo não precisa usar uma carga de resposta, solicite à API que retorne dados mínimos. Observe que alguns serviços já retornam uma 204 No Content resposta para operações PUT e PATCH.

Observação

Solicite respostas de representação mínimas usando o cabeçalho Prefer definido como return=minimal, em que há suporte. Para operações de criação, o uso desse cabeçalho pode não ser apropriado porque seu aplicativo pode esperar obter o serviço gerado id para o objeto recém-criado na resposta.

Controlar alterações: consulta delta e notificações de webhook

Se for preciso que o aplicativo saiba quais alterações foram feitas nos dados, você provavelmente receberá uma notificação de webhook sempre que dados de seu interesse forem alterados. Isso é mais eficiente do que simplesmente fazer pesquisas regularmente.

Use notificações de webhook para receber notificações por push quando os dados forem alterados.

Use a consulta delta se seu aplicativo tiver que armazenar em cache ou armazenar dados do Microsoft Graph localmente, e mantê-los atualizados, ou tiver que controlar alterações nos dados por qualquer outro motivo. Isso evitará a computação excessiva do aplicativo para recuperar dados que ele já possui, minimizar o tráfego de rede e reduzir a probabilidade de atingir um limite de limitação.

Use a consulta delta para manter os dados atualizados com eficiência.

Usar consultas delta e webhooks em conjunto

Os webhooks e a consulta delta geralmente funcionam melhor quando são usados em conjunto já que, se você usar a consulta delta sozinha, precisará calcular o intervalo de sondagem correto. Se esse intervalo for muito curto poderá levar a respostas vazias que desperdiçam recursos, mas, se for muito longo, você poderá acabar ficando com dados obsoletos. Você terá o melhor de dois mundos se usar as notificações de webhook como o gatilho para fazer chamadas de consulta delta.

Use as notificações de webhook como o gatilho para fazer chamadas de consulta delta. Você também deve garantir que seu aplicativo tenha um limite de pesquisa de backstop, caso nenhuma notificação seja acionada.

Envio em lote

Os lotes JSON permitem otimizar seu aplicativo combinando várias solicitações em um único objeto JSON. Combinar essas solicitações individuais em uma única solicitação em lote pode economizar latência de rede significativa para o aplicativo e conservar recursos de conexão.

Use o envio em lote onde uma latência de rede significativa pode ter um grande impacto no desempenho.

Confiabilidade e suporte

Para garantir a segurança e facilitar o suporte do aplicativo:

  • Use o TLS 1.2 para dar suporte a todos os recursos do Microsoft Graph. Para obter mais informações sobre a deprecação do Microsoft Graph TLS 1.0 e 1.1, consulte Habilitar o suporte para TLS 1.2 em seu ambiente.
  • Respeite o TTL DNS e defina a conexão TTL para correspondê-lo. Isso garantirá a disponibilidade em caso de failovers.
  • Abra conexões para todas as respostas de DNS anunciadas.
  • Gerar um GUID exclusivo e o enviar em cada solicitação REST do Microsoft Graph. Isso ajudará a Microsoft a investigar os erros com maior facilidade, caso seja necessário relatar um problema com o Microsoft Graph.
    • Em todas as solicitações do Microsoft Graph, gere um GUID exclusivo, envie-o no cabeçalho de solicitação HTTP do client-request-id e também registre-o nos logs dos aplicativos.
    • Sempre registre o request-id e Date dos cabeçalhos de resposta HTTP. Estes, juntamente com o client-request-id, são necessários ao relatar problemas emMicrosoft Q&A ou para o Suporte da Microsoft.