Opções de consultas, filtros e paginação com suporte | Conceitos da API do Graph
Este tópico lista opções de consultas, filtros e operações de paginação que podem ser usadas com a API do Graph do Azure AD (Active Directory). A seção final fornece alguns exemplos de consultas comuns que podem ser executadas com a 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). Em alguns casos, você pode usar o alias me. Para obter informações sobre como endereçar o locatário, consulte Visão geral das operações.
Opções de consulta com suporte
O Graph dá suporte às seguintes opções de consulta: $filter, $orderby, $expand, $top e $format. As seguintes opções de consulta não têm suporte no momento: $count, $inlinecount e $skip.
$filter
As seguintes restrições gerais aplicam-se a consultas que contêm um filtro:
$filter não pode ser combinado com expressões de $orderby.
A filtragem não tem suporte para consultas em objetos de diretório DirectoryRole ou SubscribedSku.
Nem todas as propriedades de objetos de diretório com suporte podem ser usadas em uma expressão de filtro. Para obter informações sobre as propriedades de tipos com suporte que podem ser filtradas, consulte User, Group e Contact.
As restrições a seguir se aplicam a expressões de filtros:
Operadores lógicos: and e or têm suporte. Por exemplo:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.com')Operadores de comparação: eq (igual a), ge (maior que ou igual a) e le (menor que ou igual a) têm suporte.
Startswith tem suporte. Por exemplo:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')any tem suporte para consultas de propriedades com valores múltiplos. Por exemplo:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')Operadores aritméticos: não há suporte.
Funções: não há suporte.
Valores nulos não têm suporte como operando em expressões de filtro. Por exemplo, você não pode especificar um valor nulo para filtrar propriedades não definidas.
Para filtrar uma propriedade binária, como a issuerUserId em userIdentities, o valor deve primeiro ser codificado em base64 antes que possa ser usado na cadeia de caracteres $filter.
$orderby
$orderby irá classificar os objetos retornados pelo parâmetro especificado. Exemplo de solicitações usando a opção $orderby:
| Solicitação | Descrição |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Retorna uma lista de usuários ordenados por seu nome de exibição. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Retorna uma lista dos primeiros 50 usuários ordenados por seu nome de exibição. |
As seguintes restrições se aplicam às expressões $orderby:
Duas ordens de classificação têm suporte atualmente: DisplayName para objetos User e Group e UserPrincipalName para objetos User. A ordem de classificação padrão para usuários é por UserPrincipalName.
$orderby não pode ser combinado com expressões de $filter.
$expand
$expand irá retornar um objeto e seus objetos vinculados. Exemplo de solicitações usando a opção $expand:
| Solicitação | Descrição |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Retorna o objeto de grupo, tal como seus membros. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Retorna o objeto de usuário, tal como seus relatório diretos. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Retorna o objeto de usuário, tal como seu gerente. |
As seguintes restrições se aplicam às expressões $expand:
- O número máximo de objetos retornados para uma solicitação é de 20.
$top
$top não tem suporte para consultas em objetos de diretório DirectoryRole ou SubscribedSku.
Suporte à paginação
Você pode ler para frente e para trás no gráfico. Uma resposta que contém resultados paginados incluirá um token de salto (odata.nextLink) que permite que você vá para a próxima página de resultados. Esse token de salto pode ser combinado com um argumento de consulta previous-page=true para paginar no sentido contrário.
O seguinte exemplo de solicitação demonstra a leitura para a frente:
| Solicitação | Descrição |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
O parâmetro $skiptoken da resposta anterior está incluído e permite que você obtenha a próxima página de resultados. |
O seguinte exemplo de solicitação demonstra a leitura para trás:
| Solicitação | Descrição |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
O parâmetro $skiptoken da resposta anterior está incluído. Quando ele for combinado com o parâmetro &previous-page=true, a página anterior de resultados será recuperada. |
Os seguintes passos demonstram a solicitação/resposta entre páginas para frente e para trás:
- Uma solicitação é feita para obter uma lista dos 10 primeiros usuários de 15. A resposta contém um símbolo de salto para indicar a página final de 10 usuários.
- Para chegar aos 5 usuários finais, uma outra solicitação é feita que contém o símbolo de salto retornado da resposta anterior.
- Para paginar no sentido contrário, é feita uma solicitação usando o token de salto retornado na etapa 1 e o parâmetro &previous-page=true é adicionado à solicitação.
- A resposta contém a (primeira) página anterior de 10 usuários. Em um cenário diferente, onde mais páginas estão à esquerda, um novo símbolo de salto seria devolvido. Esse novo token de salto pode ser adicionado à solicitação, juntamente com, &previous-page=true para paginar no sentido contrário novamente.
As seguintes restrições aplicam-se às solicitações de página:
- O tamanho padrão da página é 100 bytes. O tamanho máximo da página é 999.
- As consultas em funções não oferecem suporte à paginação. Isso inclui ler os próprios objetos de função assim como membros da função.
- Consultas de listagem de recursos, como uma pesquisa por todos os usuários em um locatário (/users) dão suporte à paginação. Por exemplo:
https://graph.windows.net/contoso.com/users?api-version=1.6. No entanto, em todos os tipos, quando um filtro é aplicado, a paginação não tem suporte e apenas a primeira página de resultados é retornada. - Paginação não tem suporte para pesquisas de link, como para consultar os membros do grupo. Por exemplo:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Ordem de classificação
- O conjunto de resultados de uma consulta por todos os usuários é ordenado pela propriedade UserPrincipalName. Por exemplo:
https://graph.windows.net/contoso.com/users?api-version=1.6. - O conjunto de resultados de uma consulta por todos os outros recursos de nível superior, como Grupos, Contatos etc. é ordenado pela propriedade objectId. Por exemplo:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - A ordem dos resultados das consultas diferentes dos recursos de alto nível é indeterminada.
Consultas comuns
As seções a seguir mostram alguns exemplos de consultas comuns que podem ser executadas com a API do Graph.
Consultando recursos de nível superior
As consultas a seguir demonstram como acessar recursos de nível superior 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/directoryRoles?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 |
Outras operações de consulta
A tabela a seguir mostra mais 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 |
| Retornar todos os usuários de conta local em um locatário do Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Retornar o usuário de conta local com o nome de entrada "joe@example.com" de um locatário do Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&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.