Consultas Comuns da API do Graph
Este tópico lista as consultas comuns que podem ser executadas com a API do Azure AD Graph. Para obter mais informações sobre as operações com suporte ao consultar o Graph, veja Supported Queries, Filters, and Paging Options in Azure AD Graph API (Consultas, Filtros e Opções de Paginação com Suporte na API do Azure AD Graph).
Importante
Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os recursos do Azure Active Directory. Nossos esforços de implantação agora estão concentrados no Microsoft Graph e não há planos de novos aprimoramento para a API do Azure AD Graph. Há um número muito limitado de cenários para os quais a API do Azure AD Graph ainda pode ser adequada. Para saber mais, confira a postagem do blog sobre Microsoft Graph ou Azure AD Graph no Centro de Desenvolvimento do Office.
Endereçamento
Todas as consultas abaixo abordam o locatário usando um nome de domínio. Você pode substituir contoso.com por um dos nomes de domínio registrados do locatário, com a ID do locatário (GUID) ou com o alias MyOrganization (para acesso delegado). Para obter informações sobre outras maneiras de tratar o locatário, consulte Addressing Entities and Operations in the Graph API (Endereçamento de Entidades e Operações na API do Graph).
Consultando recursos de alto nível
As consultas comuns a seguir demonstram como acessar os recursos de alto nível no com a API do Graph usando contoso.com como o locatário de exemplo. Observe que um cabeçalho de Autorização que contém um token de portador válido recebido do Azure AD será necessário para executar consultas em um locatário.
| Recurso de nível superior | Resultados da consulta | URI (para contoso.com) |
|---|---|---|
| Recursos de alto nível | Retorna uma lista de URI dos recursos de alto nível para serviços de diretório (também listados abaixo) | https://graph.windows.net/contoso.com?api-version=1.6 |
| Informações da empresa | Retorna informações da empresa | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Contacts | Retorna informações de contato organizacional | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Usuários | Retorna informações do usuário | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Grupos | Retorna dados do grupo | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Funções de Diretório | Retorna todas as funções de diretório ativadas no locatário | https://graph.windows.net/contoso.com/roles?api-version=1.6 |
| SubscribedSkus | Retorna as assinaturas do locatário | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Metadados do diretório | Retorna um Documento de Metadados de Serviço que descreve o modelo de dados (isto é, a estrutura e a organização de recursos do diretório) | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Operadores de consulta
A tabela a seguir mostra alguns exemplos de consultas de API do Graph usando contoso.com como o locatário de exemplo.
| Operação de consulta | URI (para contoso.com) |
|---|---|
| Listar todos os usuários e grupos | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Recuperar o usuário individual especificando o objectId ou o userPrincipalName | https://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6 https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6 |
| Solicitar e filtrar um usuário com displayName igual a “Jon Doe” | https://graph.windows.net/contoso.com/Users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Solicitar e filtrar usuários específicos com firstName igual a “Jon” | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Filtre para valores de givenName e surname. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Recuperar o grupo individual especificando o objectId | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Recuperar o gerenciador de um usuário | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Recuperar a lista de relatórios diretos de um usuário | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Recuperar uma lista de links para relatórios diretos de um usuário | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Recuperar a lista de associação de um grupo | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Recuperar uma lista de links para os membros de um grupo. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Recuperar a associação de grupo de um usuário (não transitiva) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Recuperar uma lista dos grupos do qual o usuário é membro (não transitivo) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Solicitar e filtrar os grupos com displayName >= "az" e <= "dz" | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
Observação: o espaço em branco na cadeia de caracteres da consulta deve ser codificado para URL antes de enviar uma solicitação. Por exemplo, a cadeia de caracteres de consulta a seguir, https://graph.windows.net/contoso.com/Users?$filter=displayName eq 'Jon Doe'&api-version=1.6, deve ser codificada na URL como: https://graph.windows.net/contoso.com/Users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.