Pedir diferenças entre o Azure AD Graph e o Microsoft Graph

Este artigo faz parte do Passo 1: rever as diferenças da API na série de listas de verificação de planeamento de migração de aplicações do Azure AD Graph.

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

Utilize o Graph Explorer para experimentar estes padrões de pedido em relação aos seus próprios dados e saber mais sobre as diferenças de pedidos e respostas antes de atualizar o código.

Pedidos básicos

A tabela seguinte realça as diferenças main pedido entre as duas APIs:

Solicitar detalhes	Azure AD Graph.	Microsoft Graph
Sintaxe do pedido	https://graph.windows.net/{tenant_id}/{resource}?{version}&query-parameters	https://graph.microsoft.com/{version}/{resource}?query-parameters
Pontos finais 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 (Descontinuada)	https://graph.cloudapi.de	https://graph.microsoft.de
- China (21Vianet)	https://graph.chinacloudapi.cn	https://microsoftgraph.chinacloudapi.cn
{tenant_id}	Especifique o ID do inquilino ou o nome de domínio no pedido.	Opcional. O ID do inquilino é inferido a partir do token de acesso. Se especificar o ID do inquilino, utilize esta sintaxe: https://graph.microsoft.com/{version}/{tenant_id}/{resource}?query-parameters.
{version}	Especifique a versão de lançamento do Azure AD Graph no pedido com um parâmetro de consulta necessário.	Especifique a versão de lançamento do Microsoft Graph no pedido como parte do caminho do URL logo após o ponto final de serviço.

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

Comparação de pedidos de exemplo

Suponha que pretende uma lista de todos os utilizadores com nomes que comecem por "Dan" no inquilino da Contoso. A tabela seguinte mostra as diferenças de pedidos 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) denominado objectId. Para a maioria das entidades (salvo indicação em contrário), este identificador é denominado ID no Microsoft Graph.

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

Propriedades predefinidas e $select

É uma melhor prática pedir apenas as propriedades de que a sua aplicação realmente precisa. Utilize o $select parâmetro de consulta, em pedidos GET, para personalizar a resposta para incluir apenas as propriedades necessárias para a sua aplicação.

Em alguns casos no Microsoft Graph, por exemplo, as operações GET ou LIST para recursos de utilizador e de grupo , apenas é devolvido um subconjunto de todas as propriedades. Estas propriedades predefinidas representam as propriedades utilizadas mais frequentemente para os recursos. Por outro lado, Azure AD Graph devolve o conjunto completo de todas as propriedades do respetivo recurso. Quando o recurso devolve apenas as propriedades predefinidas, a aplicação tem de pedir explicitamente outras propriedades com o $select parâmetro de consulta.

Para ilustrar a diferença, utilize o Graph Explorer para executar os seguintes pedidos e comparar as diferentes respostas.

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

Repare na diferença nas respostas. A /beta versão devolve mais propriedades do que a /v1.0 versão. Se a sua aplicação depender da propriedade streetAddress , por exemplo, terá de atualizar os pedidos v1.0 para utilizar o $select parâmetro de consulta para pedir a propriedade streetAddress , além de outras propriedades de que a aplicação precisa. Por exemplo:

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

Para saber mais sobre:

• Propriedades predefinidas nos recursos do utilizador e do grupo, veja utilizadores e grupos
• O $select parâmetro e outros parâmetros de consulta OData suportados, veja Utilizar parâmetros de consulta para personalizar respostas.
• Outras otimizações recomendadas, veja Melhores práticas.

Relações e propriedades de navegação

As 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 gestor e directReports expandem o recurso de utilizador para fornecer hierarquia organizacional.

As relações também definem associações, como os grupos a que um utilizador pertence, os membros pertencentes a um grupo ou a uma função de diretório, etc.

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

A tabela seguinte mostra vários exemplos:

Tarefa	Azure AD Graph.	Microsoft Graph
Adicionar membro	POST /groups/{id}/$links/members	POST /groups/{id}/members/$ref
Listar ligações 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 as suas aplicações para o Microsoft Graph, atualize as referências que utilizam $links para associar recursos a utilizar $ref .

Próxima etapa

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