Solicitar diferenças entre Azure AD Graph e Microsoft Graph

  • Artigo

Este artigo faz parte da etapa 1: examine as diferenças de API do processo para migrar aplicativos.

O Microsoft Graph e o 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 experimentar esses padrões de solicitação em relação aos seus próprios dados e saiba 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 diferenças de solicitação main entre as duas APIs:

Solicitar detalhes Azure AD Graph. Microsoft Graph
Sintaxe de 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:
-Global 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.
{version} Especifique a versão de versão do Azure AD Graph na solicitação usando um parâmetro de consulta necessário. Especifique a versão de versão do Microsoft Graph na solicitação como parte do caminho da URL logo após o ponto de extremidade do serviço.

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

Comparação de solicitação de exemplo

Suponha que você queira uma lista de todos os usuários com nomes começando com "Dan" no locatário contoso. A tabela a seguir mostra as diferenças de solicitação entre 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 (a menos que seja declarado de outra forma) 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 de aplicativo 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 que seu aplicativo realmente precisa. Use o $select parâmetro de consulta, em solicitações GET, para personalizar a resposta para incluir apenas as propriedades necessárias pelo aplicativo.

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 são retornados. Essas propriedades padrão representam as propriedades mais usadas para os recursos. Por outro lado, Azure AD Graph retorna o conjunto completo de todas as propriedades para o respectivo recurso. Quando o recurso retorna apenas as propriedades padrão, seu aplicativo precisa solicitar explicitamente outras propriedades usando o $select parâmetro de consulta.

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

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 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 fundamental no Azure AD Graph e no Microsoft Graph, criando uma rede de recursos relacionados. Por exemplo, as propriedades manager e directReports estendem o recurso do 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 uma função de diretório e assim por diante.

Azure AD solicitações do Graph usam $links para indicar relações entre recursos. Em vez disso, o Microsoft Graph usa a notação OData v4.01 $ref .

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 membro 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

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