Table of contents

Opções de consultas, filtros e paginação com suporte | Conceitos da API do Graph

Jimaco Brannian|Última Atualização: 07/09/2016
|
1 Colaborador

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

A funcionalidade da API do Azure AD Graph também está disponível por meio do Microsoft Graph, uma API unificada que também inclui APIs de outros serviços Microsoft, como Outlook, OneDrive, OneNote, Planner e Office Graph, sendo todas elas acessadas por meio de um ponto de extremidade com um token de acesso.

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.

$orderby

$orderby irá classificar os objetos retornados pelo parâmetro especificado. Exemplo de solicitações usando a opção $orderby:

SolicitaçãoDescrição
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6Retorna 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.6Retorna 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çãoDescrição
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6Retorna o objeto de grupo, tal como seus membros.
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6Retorna 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.6Retorna 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çãoDescriçã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çãoDescrição
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=trueO 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:

  1. 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.
  2. Para chegar aos 5 usuários finais, uma outra solicitação é feita que contém o símbolo de salto retornado da resposta anterior.
  3. 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.
  4. 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 superiorResultados da consultaURI (para contoso.com)
Recursos de alto nívelRetorna 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 empresaRetorna informações da empresahttps://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
ContatosRetorna informações de contato organizacionalhttps://graph.windows.net/contoso.com/contacts?api-version=1.6
UsuáriosRetorna informações do usuáriohttps://graph.windows.net/contoso.com/users?api-version=1.6
GruposRetorna dados do grupohttps://graph.windows.net/contoso.com/groups?api-version=1.6
Funções de DiretórioRetorna todas as funções de diretório ativadas no locatáriohttps://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkusRetorna as assinaturas do locatáriohttps://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
Metadados do diretórioRetorna 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 consultaURI (para contoso.com)
Listar todos os usuários e gruposhttps://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 userPrincipalNamehttps://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 objectIdhttps://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
Recuperar o gerenciador de um usuáriohttps://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áriohttps://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áriohttps://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 grupohttps://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 B2Chttps://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 B2Chttps://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.

Recursos adicionais

© 2017 Microsoft