Diferenças de solicitação entre o Azure AD Graph e o Microsoft Graph

Este artigo faz parte da Etapa 1: examinar as diferenças de API na série de lista de verificação de planejamento de migração do aplicativo Graph do Azure AD.

O Microsoft Graph e a API do Graph do Azure Active Directory (Azure AD) são APIs REST que dão suporte a convenções OData para parâmetros de consulta. No entanto, a sintaxe varia entre essas duas APIs.

Use o Graph Explorer para testar esses padrões de solicitação em seus próprios dados e saber mais sobre as diferenças de solicitação e resposta antes de atualizar seu código.

Solicitações básicas

A tabela a seguir destaca as principais diferenças de solicitação entre as duas APIs:

Solicitar detalhes Azure AD Graph. Microsoft Graph
Sintaxe da solicitação https://graph.windows.net/{tenant_id}/{resource}?{version}&query-parameters https://graph.microsoft.com/{version}/{resource}?query-parameters
Pontos de extremidade de serviço:
- Globais https://graph.windows.net https://graph.microsoft.com
- US Gov L4 https://graph.microsoftazure.us https://graph.microsoft.us
- US Gov L5 (DOD) https://graph.microsoftazure.us https://dod-graph.microsoft.us
- Alemanha (aposentado) https://graph.cloudapi.de https://graph.microsoft.de
- China (21Vianet) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id} Especifique a ID do locatário ou o nome de domínio na solicitação. Opcional. A ID do locatário é inferida do token de acesso.

Se você especificar a ID do locatário, use esta sintaxe: https://graph.microsoft.com/{version}/{tenant_id}/{resource}?query-parameters.
{versão} Especifique a versão de lançamento do Azure AD Graph na solicitação usando um parâmetro de consulta necessário. Especifique a versão de lançamento do Microsoft Graph na solicitação como parte do caminho da URL logo após o ponto de extremidade de serviço.

A sintaxe do parâmetro de consulta é a mesma para o Microsoft Graph e o Azure AD Graph. No entanto, o Microsoft Graph dá suporte a mais parâmetros e recursos de consulta do que o Azure AD Graph.

Exemplo de comparação de solicitação

Suponha que você queira uma lista de todos os usuários com nomes que começam com "Dan" no locatário da Contoso. A tabela a seguir mostra as diferenças de solicitação entre o Azure AD Graph e o Microsoft Graph.

Azure AD Graph. Microsoft Graph
GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan')

Identificadores de chave primária: objectId vs id

No Azure AD Graph, todos os tipos de recursos de entidade têm um identificador exclusivo (ou chave primária) chamado objectId. Para a maioria das entidades (salvo indicação em contrário), esse identificador é chamado de id no Microsoft Graph.

Além da chave primária, algumas entidades dão suporte a um identificador de chave alternativo. Por exemplo, os recursos application e servicePrincipal no Microsoft Graph dão suporte a um identificador de chave alternativo para sua propriedade appId .

Propriedades padrão e $select

É uma prática recomendada solicitar apenas as propriedades de que seu aplicativo realmente precisa. Use o $select parâmetro query, em solicitações GET, para personalizar a resposta a fim de incluir apenas as propriedades que seu aplicativo exige.

Em alguns casos no Microsoft Graph, por exemplo, as operações GET ou LIST para recursos de usuário e grupo , apenas um subconjunto de todas as propriedades é retornado. Essas propriedades padrão representam as propriedades mais comumente usadas para os recursos. Por outro lado, o gráfico do Azure AD retorna o conjunto completo de todas as propriedades do respectivo recurso. Onde o recurso retorna apenas as propriedades padrão, seu aplicativo precisa solicitar explicitamente outras propriedades usando o $select parâmetro query.

Para ilustrar a diferença, use o Graph Explorer para executar as solicitações a seguir e comparar as diferentes respostas.

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

Observe a diferença nas respostas. A /beta versão retorna mais propriedades do que a /v1.0 versão. Se o aplicativo depender da propriedade streetAddress , por exemplo, você precisará atualizar suas v1.0 solicitações para usar o $select parâmetro de consulta para solicitar a propriedade streetAddress, além de outras propriedades de que o aplicativo precisa. Por exemplo:

https://graph.microsoft.com/v1.0/me?$select=displayName,streetAddress,city,state,postalCode

Para saber mais sobre:

Relações e propriedades de navegação

Relações (ou propriedades de navegação) são um conceito-chave no Azure AD Graph e no Microsoft Graph, criando uma rede de recursos relacionados. Por exemplo, as propriedades manager e directReports estendem o recurso de usuário para fornecer hierarquia organizacional.

As relações também definem associações como os grupos aos quais um usuário pertence, os membros pertencentes a um grupo ou a uma função de diretório e assim por diante.

As solicitações do Azure AD Graph são usadas $links para indicar relações entre recursos. O Microsoft Graph usa a notação OData v4.01 $ref em vez disso.

A tabela a seguir mostra vários exemplos:

Tarefa Azure AD Graph. Microsoft Graph
Adicionar membro POST /groups/{id}/$links/members POST /groups/{id}/members/$ref
Listar links de membros GET /groups/{id}/$links/members GET /groups/{id}/members/$ref
Listar membros GET /groups/{id}/members GET /groups/{id}/members
Remover membro DELETE /groups/{id}/$links/members/{id} DELETE /groups/{id}/members/{id}/$ref

Ao migrar seus aplicativos para o Microsoft Graph, atualize as referências que usam $links para associar recursos a serem usados $ref .

Próxima etapa

Revisar a lista de verificação de migração novamente

  • Last updated on