Solicitar diferenças entre Azure AD Graph e Microsoft Graph
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:
- Propriedades padrão em recursos de usuário e grupo, consulte usuários e grupos
- O
$selectparâmetro e outros parâmetros de consulta ODATA com suporte, consulte Usar parâmetros de consulta para personalizar respostas. - Outras otimizações recomendadas, consulte Melhores práticas.
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 .