Práticas recomendadas para trabalhar com o Microsoft Graph

  • Artigo

Este artigo descreve as melhores práticas que pode aplicar para ajudar as suas aplicações a tirar o máximo partido do Microsoft Graph, quer isso envolva aprender sobre o Microsoft Graph, melhorar o desempenho da aplicação ou tornar a sua aplicação mais fiável para os utilizadores 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 aceder aos dados através do Microsoft Graph, a sua aplicação tem de adquirir um token de acesso OAuth 2.0 e apresentá-lo ao Microsoft Graph em qualquer 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

Utilize a Biblioteca de Autenticação da Microsoft (MSAL) para adquirir o token de acesso ao 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 uma aplicação não ler o calendário do utilizador, não lhe conceda a permissão Calendários.Leitura . 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, o logótipo, o domínio, o estado de verificação do publicador, a declaração de privacidade e os termos de utilização da aplicação são apresentados em consentimento e noutras experiências. Configure estas definições cuidadosamente para que sejam compreendidas pelos seus utilizadores 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 obter mais informações, veja 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 utilizador 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. Neste caso, é muito provável que o utilizador com sessão iniciada não tenha privilégios para aceder ao recurso pedido. 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 aprovisionado (como a fotografia de um utilizador) ou porque foi eliminado. 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 ser limitadas em qualquer altura por vários motivos, pelo que a sua aplicação tem de estar sempre preparada para processar 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 Isto deve-se provavelmente ao facto de os serviços estarem 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 criar a sua aplicação para processar também membros desconhecidos, pode optar por receber esses membros utilizando um cabeçalho de pedido HTTP Prefer :

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 faz um pedido GET sem utilizar $select para limitar a quantidade de dados de propriedades, o Microsoft Graph inclui uma propriedade @microsoft.graph.tips que fornece uma recomendação de melhores práticas para utilizar $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. Alguns serviços já devolvem uma 204 No Content resposta para operações PUT e PATCH.

Observação

Peça respostas de representação mínimas com o cabeçalho Prefer definido como return=minimal, onde suportado. Para operações de criação, a utilização deste cabeçalho pode não ser adequada porque a sua aplicação poderá 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. Isto é mais eficiente do que simplesmente consultar 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. Isto evita a computação excessiva da sua aplicação para obter dados que a sua aplicação já tem, minimizar o tráfego de rede e reduzir a probabilidade de atingir um limiar 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 são frequentemente utilizados melhor em conjunto, porque se utilizar apenas a consulta delta, tem de descobrir o intervalo de consulta certo - demasiado curto e isso pode levar a respostas vazias, que desperdiçam recursos, demasiado longos e poderá acabar 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.

Utilize a criação de batches em que a latência de rede significativa pode ter um impacto significativo no desempenho.

Confiabilidade e suporte

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

  • Utilize o TLS 1.3 ou 1.2 para suportar todas as capacidades do Microsoft Graph. Migrar do TLS 1.0 e 1.1. Para obter mais informações, veja Ativar o suporte para o TLS 1.2 no 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. Isto ajuda a Microsoft a investigar quaisquer erros mais facilmente se precisar de comunicar 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.
    • Registe sempre o e Date a request-id partir 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.