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
.