Práticas recomendadas para trabalhar com o Microsoft GraphBest practices for working with Microsoft Graph

Este artigo descreve as práticas recomendadas que você pode aplicar para ajudar seus aplicativos a tirar o máximo proveito do Microsoft Graph, caso isso envolva saber mais sobre o Microsoft Graph, melhorar o desempenho do aplicativo ou tornar seu aplicativo mais confiável para os usuários finais.This article describes best practices that you can apply to help your applications get the most out of Microsoft Graph - whether that involves learning about Microsoft Graph, improving app performance, or making your application more reliable for end users.

Usar o Graph Explorer para saber mais sobre a APIUse Graph Explorer to get to know the API

A melhor maneira de começar a explorar os dados disponíveis pelo Microsoft Graph é usando o Graph Explorer.The easiest way to start exploring the data available through Microsoft Graph is to use 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.Graph Explorer lets you craft REST requests (with full CRUD support), adapt the HTTP request headers, and see the data responses. Para ajudar você a começar, o Graph Explorer também oferece um conjunto de consultas de exemplo.To help you get started, Graph Explorer also provides a set of sample queries.

Experimente novas APIs antes de integrá-las em seu aplicativo.Experiment with new APIs before you integrate them into your application.

AutenticaçãoAuthentication

Para acessar os dados no Microsoft Graph, seu aplicativo precisará adquirir um token de acesso do OAuth 2.0 e apresentá-lo ao Microsoft Graph em um dos itens a seguir:To access the data in Microsoft Graph, your application will need to acquire an OAuth 2.0 access token, and present it to Microsoft Graph in either of the following:

  • O cabeçalho de solicitação HTTP Authorization, como um token de PortadorThe HTTP Authorization request header, as a Bearer token
  • O construtor do cliente gráfico ao usar uma biblioteca de cliente do Microsoft GraphThe graph client constructor, when using a Microsoft Graph client library

Use a API da Biblioteca de Autenticação Microsoft, MSAL, para adquirir o token de acesso para o Microsoft Graph.Use the Microsoft Authentication Library API, MSAL to acquire the access token to Microsoft Graph.

Aplique as seguintes práticas recomendadas de consentimento e autorização ao aplicativo:Apply the following best practices for consent and authorization in your app:

  • Use privilégios mínimos.Use least privilege. Apenas solicite permissões absolutamente necessárias e somente quando você precisar delas.Only request permissions that are absolutely necessary, and only when you need them. Para as APIs que o aplicativo chama, verifique a seção de permissões nos tópicos do método (por exemplo, confira como criar um usuário e escolha as permissões com menos privilégios.For the APIs your application calls, check the permissions section in the method topics (for example, see creating a user, and choose the least privileged permissions. Uma ver uma lista completa de permissões, confira referência de permissões.For a full list of permissions, see permissions reference.

  • Use o tipo de permissão correto com base nos cenários.Use the correct permission type based on scenarios. Se você estiver criando um aplicativo interativo no qual um usuário conectado está presente, seu aplicativo deverá usar permissões delegadas nas quais o aplicativo recebe permissão de atuar como um usuário conectado ao fazer chamadas para o Microsoft Graph.If you're building an interactive application where a signed in user is present, your application should use delegated permissions, where the application is delegated permission to act as the signed-in user when making calls to Microsoft Graph. Se, no entanto, seu aplicativo for executado sem um usuário conectado, como um serviço em segundo plano ou um daemon, seu aplicativo deverá usar permissões de aplicativo.If, however, your application runs without a signed-in user, such as a background service or daemon, your application should use application permissions.

    Observação: o uso de permissões de aplicativo para cenários interativos pode colocar a conformidade e a segurança de seu aplicativo em risco.Note: Using application permissions for interactive scenarios can put your application at compliance and security risk. Isso pode elevar inadvertidamente os privilégios de um usuário para acessar dados, contornando as políticas configuradas por um administrador.It can inadvertently elevate a user's privileges to access data, circumnavigating policies configured by an administrator.

  • Esteja atento ao configurar seu aplicativo.Be thoughtful when configuring your app. Isso afetará diretamente as experiências do usuário final e do administrador, além da adoção e segurança do aplicativo.This will directly affect end user and admin experiences, along with application adoption and security. Por exemplo:For example:

    • A declaração de privacidade, os termos de uso, o nome, o logotipo e o domínio do seu aplicativo serão exibidos com consentimento e outras experiências. Portanto, verifique se foram configurados com cuidado para que sejam compreendidos pelos usuários finais.Your application's privacy statement, terms of use, name, logo and domain will show up in consent and other experiences - so make sure to configure these carefully so they are understood by your end-users.
    • 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.Consider who will be consenting to your application - either end users or administrators - and configure your application to request permissions appropriately.
    • Verifique se você entende a diferença entre consentimento estático, dinâmico e incremental.Ensure that you understand the difference between static, dynamic and incremental consent.
  • Considere usar aplicativos multilocatários.Consider multi-tenant applications. Tenha em mente que os clientes podem ter vários controles de aplicativo e consentimentos em diferentes estados.Expect customers to have various application and consent controls in different states. Por exemplo:For example:

    • os administradores de locatários podem desabilitar a capacidade dos usuários finais permitirem os aplicativos.Tenant administrators can disable the ability for end users to consent to applications. Nesse caso, um administrador precisaria consentir em nome de seus usuários.In this case, an administrator would need to consent on behalf of their users.
    • 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.Tenant administrators can set custom authorization policies such as blocking users from reading other user's profiles, or limiting self-service group creation to a limited set of users. Nesse caso, seu aplicativo deve esperar que a resposta de erro 403 seja tratada ao atuar em nome de um usuário.In this case, your application should expect to handle 403 error response when acting on behalf of a user.

Controlar as respostas com eficiênciaHandle responses effectively

Dependendo das solicitações feitas ao Microsoft Graph, seus aplicativos devem estar preparados para lidar com diferentes tipos de respostas.Depending on the requests you make to Microsoft Graph, your applications should be prepared to handle different types of responses. 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.The following are some of the most important practices to follow to ensure that your application behaves reliably and predictably for your end users.

PaginaçãoPagination

Ao consultar um conjunto de recursos, você deve esperar que o Microsoft Graph retorne o conjunto de resultados em várias páginas devido aos limites de tamanho de página do lado do servidor.When querying a resource collection, you should expect that Microsoft Graph will the return result set in multiple pages, due to server-side page size limits. 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.When a result set spans multiple pages, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the next page of results.

Por exemplo, listar as mensagens de usuários conectados:For example, listing the signed-in users messages:

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.Would return a response containing an @odata.nextLink property, if the result set exceeds the server-side page size limit.

"@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.Note: Your application should always handle the possibility that the responses are paged in nature, and use the @odata.nextLink property to obtain the next paged set of results, until all pages of the result set have been read. A página final não conterá uma propriedade @odata.nextLink.The final page will not contain an @odata.nextLink property. 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.You should include the entire URL in the @odata:nextLink property in your request for the next page of results, treating the entire URL as an opaque string.

Para saber mais, confira paginação.For more details, see paging.

Como tratar erros esperadosHandling expected errors

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.While your application should handle all error responses (in the 400 and 500 ranges), pay special attention to certain expected errors and responses, listed in the following table.

TópicoTopic Código de erro HTTPHTTP error code Prática recomendadaBest practice
O usuário não tem acessoUser does not have access 403403 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.If your application is up and running, it could encounter this error even if it has been granted the necessary permissions through a consent experience. Nesse caso, é mais provável que o usuário conectado não tenha privilégios para acessar o recurso solicitado.In this case, it's most likely that the signed-in user does not have privileges to access the resource requested. Seu aplicativo deve fornecer um erro genérico de "Acesso negado" para o usuário conectado.Your application should provide a generic "Access denied" error back to the signed-in user.
Não encontradoNot found 404404 Em certos casos, um recurso solicitado pode não ser encontrado.In certain cases, a requested resource might not be found. 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.For example a resource might not exist, because it has not yet been provisioned (like a user's photo) or because it has been deleted. 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.Some deleted resources might be fully restored within 30 days of deletion - such as user, group and application resources, so your application should also take this into account.
LimitaçãoThrottling 429429 As APIs podem limitar a qualquer momento por diversos motivos, portanto, seu aplicativo deve sempre estar preparado para manipular 429 respostas.APIs might throttle at any time for a variety of reasons, so your application must always be prepared to handle 429 responses. Essa resposta de erro inclui o campo Retry-After no cabeçalho de resposta HTTP.This error response includes the Retry-After field in the HTTP response header. Desativar solicitações usando o atraso Retry-After é a forma mais rápida de se recuperar da limitação.Backing off requests using the Retry-After delay is the fastest way to recover from throttling. Para saber mais, confira limitação.For more information, see throttling.
Serviço indisponívelService unavailable 503503 O motivo mais provável é que os serviços estejam ocupados.This is likely because the services is busy. Você deve empregar uma estratégia de retirada similar à 429.You should employ a back-off strategy similar to 429. Além disso, você deve sempre fazer novas solicitações de novas tentativas em uma nova conexão HTTP.Additionally, you should always make new retry requests over a new HTTP connection.

Enums que evoluemEvolvable enums

Os aplicativos cliente podem ser desfeitos com a adição de membros a um enum existente.Client applications can be broken by the addition of members to an existing enum. Para alguns dos enums mais recentes do Microsoft Graph, um mecanismo está disponível para permitir a adição de novos membros sem implicar em uma alteração significativa.For some newer enums in Microsoft Graph, a mechanism is available to allow for adding new members without incurring a breaking change. Nesses enums mais recentes, você verá um membro sentinela comum chamado unknownFutureValue que demarca membros enum conhecidos e desconhecidos.On these newer enums, you'll see a common sentinel member called unknownFutureValue that demarcates known and unknown enum members. Os membros conhecidos terão um número menor que o membro sentinela, enquanto os membros desconhecidos terão um valor maior.Known members will have a number less than the sentinel member, while unknown members will be greater in value. Por padrão, o Microsoft Graph não retorna membros desconhecidos.By default, unknown members are not returned by Microsoft Graph. Se, no entanto, seu aplicativo tiver sido gravado para manipular a aparência de membros desconhecidos, ele poderá optar por receber membros enum desconhecidos usando um cabeçalho de solicitação HTTP Prefer.If, however, your application is written to handle the appearance of unknown members, it can opt-in to receive unknown enum members, using an HTTP Prefer request header.

Observação: se o aplicativo estiver preparado para lidar com membros enum desconhecidos, ele deverá aceitar a condição usando um cabeçalho solicitação HTTP prefer: Prefer: include-unknown-enum-members.Note: If your application is prepared to handle unknown enum members, it should opt-in by using an HTTP prefer request header: Prefer: include-unknown-enum-members.

Armazenamento de dados no localStoring data locally

Idealmente, seu aplicativo deveria fazer chamadas para o Microsoft Graph para recuperar dados em tempo real conforme necessário.Your application should ideally make calls to Microsoft Graph to retrieve data in real time as necessary. 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.You should only cache or store data locally if required for a specific scenario, and if that use case is covered by your terms of use and privacy policy, and does not violate the Microsoft APIs Terms of Use. O aplicativo também deve implementar políticas adequadas de retenção e de exclusão.Your application should also implement proper retention and deletion policies.

OtimizaçõesOptimizations

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.In general, for performance and even security or privacy reasons, you should only get the data your application really needs, and nothing more.

Usar projeçõesUse projections

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).Choose only the properties your application really needs and no more, because this saves unnecessary network traffic and data processing in your application (and in the service).

Observação: use o parâmetro de consulta $select para limitar as propriedades retornadas por uma consulta àquelas exigidas pelo aplicativo.Note: Use the $select query parameter to limit the properties returned by a query to those needed by your application.

Por exemplo, ao recuperar as mensagens do usuário conectado, você pode especificar que somente as propriedades from e subject sejam retornadas:For example, when retrieving the messages of the signed-in user, you can specify that only the from and subject properties be returned:

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

Como obter respostas mínimasGetting minimal responses

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.For some operations, such as PUT and PATCH (and in some cases POST), if your application doesn't need to make use of a response payload, you can ask the API to return minimal data. Observe que alguns serviços já retornam uma resposta 204 No Content para operações PUT e PATCH.Note that some services already return a 204 No Content response for PUT and PATCH operations.

Observação: solicite respostas de representação mínima usando um cabeçalho de solicitação HTTP onde for apropriado: Prefer: return=minimal.Note: Request minimal representation responses using an HTTP request header where appropriate: Prefer: return=minimal. Observe que, em operações de criação, isso pode não ser adequado já que o aplicativo pode estar esperando receber o serviço gerado id para o objeto recém-criado na resposta.Note that for creation operations, this might not be appropriate because your application may expect to get the service generated id for the newly created object in the response.

Controlar alterações: consulta delta e notificações de webhookTrack changes: delta query and webhook notifications

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.If your application needs to know about changes to data, you can get a webhook notification whenever data of interest has changed. Isso é mais eficiente do que simplesmente fazer pesquisas regularmente.This is more efficient than simply polling on a regular basis.

Use notificações de webhook para receber notificações por push quando os dados forem alterados.Use webhook notifications to get push notifications when data changes.

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.If your application is required to cache or store Microsoft Graph data locally, and keep that data up to date, or track changes to data for any other reasons, you should use delta query. 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.This will avoid excessive computation by your application to retrieve data your application already has, minimize network traffic, and reduce the likelihood of reaching a throttling threshold.

Use a consulta delta para manter os dados atualizados com eficiência.Use delta query to efficiently keep data up to date.

Usar consultas delta e webhooks em conjuntoUsing webhooks and delta query together

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.Webhooks and delta query are often used better together, because if you use delta query alone, you need to figure out the right polling interval - too short and this might lead to empty responses which wastes resources, too long and you might end up with stale data. Você terá o melhor de dois mundos se usar as notificações de webhook como o gatilho para fazer chamadas de consulta delta.If you use webhook notifications as the trigger to make delta query calls, you get the best of both worlds.

Use as notificações de webhook como o gatilho para fazer chamadas de consulta delta.Use webhook notifications as the trigger to make delta query calls. Você também deve garantir que seu aplicativo tenha um limite de pesquisa de backstop, caso nenhuma notificação seja acionada.You should also ensure that your application has a backstop polling threshold, in case no notifications are triggered.

Envio em loteBatching

Os lotes JSON permitem otimizar seu aplicativo combinando várias solicitações em um único objeto JSON.JSON batching allows you to optimize your application by combining multiple requests into a single JSON object. 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.Combining individual requests into a single batch request can save the application significant network latency and can conserve connection resources.

Use o envio em lote onde uma latência de rede significativa pode ter um grande impacto no desempenho.Use batching where significant network latency can have a big impact on the performance.

Confiabilidade e suporteReliability and support

Para garantir a segurança e facilitar o suporte do aplicativo:To ensure reliability and facilitate support for your application:

  • Respeite o TTL DNS e defina a conexão TTL para correspondê-lo.Honor DNS TTL and set connection TTL to match it. Isso garantirá a disponibilidade em caso de failovers.This ensures availability in case of failovers.
  • Abra conexões para todas as respostas de DNS anunciadas.Open connections to all advertised DNS answers.
  • Gerar um GUID exclusivo e o enviar em cada solicitação REST do Microsoft Graph.Generate a unique GUID and send it on each Microsoft Graph REST request. Isso ajudará a Microsoft a investigar os erros com maior facilidade, caso seja necessário relatar um problema com o Microsoft Graph.This will help Microsoft investigate any errors more easily if you need to report an issue with 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.On every request to Microsoft Graph, generate a unique GUID, send it in the client-request-id HTTP request header, and also log it in your application's logs.
    • Registre sempre o request-id, o timestamp e o x-ms-ags-diagnostic dos cabeçalhos de resposta HTTP.Always log the request-id, timestamp and x-ms-ags-diagnostic from the HTTP response headers. Estes, juntamente com o client-request-id, são necessários ao relatar problemas emMicrosoft Q&A ou para o Suporte da Microsoft.These, together with the client-request-id, are required when reporting issues in Microsoft Q&A or to Microsoft Support.