Table of contents

Opções de consultas, filtros e paginação com suporte | Conceitos da API do GraphSupported queries, filters, and paging options | Graph API concepts

Jimaco Brannian|Última Atualização: 19/06/2018
|
2 Colaboradores

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).This topic lists query options, filters, and paging operations that you can use with the Azure Active Directory (AD) Graph API.A seção final fornece alguns exemplos de consultas comuns que podem ser executadas com a API do Azure AD Graph.The final section gives some examples of common queries that you can perform with the Azure AD Graph API.

Importante

Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os recursos do Azure Active Directory.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.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.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.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.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Endereçamento Addressing

Todas as consultas abaixo abordam o locatário usando um nome de domínio.The queries below all address the tenant using a domain name.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).You can replace contoso.com with one of your tenant’s registered domain names, with your tenant's ID (GUID), or with the MyOrganization alias (for delegated access).Em alguns casos, você pode usar o alias me.In some cases, you may be able to use the me alias.Para obter informações sobre como endereçar o locatário, consulte Visão geral das operações.For information about ways of addressing the tenant, see Operations overview.

Opções de consulta com suporte Supported query options

O Graph dá suporte às seguintes opções de consulta: $filter, $orderby, $expand, $top e $format.The Graph supports the following query options: $filter, $orderby, $expand, $top, and $format.As seguintes opções de consulta não têm suporte no momento: $count, $inlinecount e $skip.The following query options are not currently supported: $count, $inlinecount, and $skip.

$filter$filter

As seguintes restrições gerais aplicam-se a consultas que contêm um filtro:The following general restrictions apply to queries that contain a filter:

  • $filter não pode ser combinado com expressões de $orderby.$filter cannot be combined with $orderby expressions.

  • A filtragem não tem suporte para consultas em objetos de diretório DirectoryRole ou SubscribedSku.Filtering is not supported for queries on DirectoryRole or SubscribedSku directory objects.

  • Nem todas as propriedades de objetos de diretório com suporte podem ser usadas em uma expressão de filtro.Not all properties of supported directory objects can be used in a filter expression.Para obter informações sobre as propriedades de tipos com suporte que podem ser filtradas, consulte User, Group e Contact.For information about filterable properties of supported types, see User, Group, and Contact.

As restrições a seguir se aplicam a expressões de filtros:The following restrictions apply to filter expressions:

  • Operadores lógicos: and e or têm suporte.Logical operators: and and or are supported.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')For example: 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.Comparison operators: eq (equal to), ge (greater than or equal to), and le (less than or equal to) are supported.

  • Startswith tem suporte.startswith is supported.Por exemplo: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')For example: 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.any is supported when querying multi-valued properties.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')For example: 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.Arithmetic operators: not supported.

  • Funções: não há suporte.Functions: not supported.

  • Valores nulos não têm suporte como operando em expressões de filtro.null values are not supported as an operand in filter expressions.Por exemplo, você não pode especificar um valor nulo para filtrar propriedades não definidas.For example, you cannot specify a null value to filter for unset properties.

  • 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.To filter on a binary property such as the issuerUserId in userIdentities, the value must first be base64 encoded before it can be used in the $filter string.

$orderby$orderby

$orderby irá classificar os objetos retornados pelo parâmetro especificado.$orderby will sort the returned objects by the specified parameter.Exemplo de solicitações usando a opção $orderby:Example requests using the $orderby option:

SolicitaçãoRequestDescriçãoDescription
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.Returns a list of users ordered by their display name.
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.Returns a list of the first 50 users ordered by their display name.

As seguintes restrições se aplicam às expressões $orderby:The following restrictions apply to $orderby expressions:

  • Duas ordens de classificação têm suporte atualmente: DisplayName para objetos User e Group e UserPrincipalName para objetos User.Two sort orders are currently supported: DisplayName for User and Group objects, and UserPrincipalName for User objects.A ordem de classificação padrão para usuários é por UserPrincipalName.The default sort order for users is by UserPrincipalName.

  • $orderby não pode ser combinado com expressões de $filter.$orderby cannot be combined with $filter expressions.

$expand$expand

$expand irá retornar um objeto e seus objetos vinculados.$expand will return an object and its linked objects.Exemplo de solicitações usando a opção $expand:Example requests using the $expand option:

SolicitaçãoRequestDescriçãoDescription
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.Returns both the group object as well as its members.
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.Returns both the user object as well as its direct reports.
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.Returns both the user object as well as its manager.

As seguintes restrições se aplicam às expressões $expand:The following restrictions apply to $expand expressions:

  • O número máximo de objetos retornados para uma solicitação é de 20.The maximum number of returned objects for a request is 20.

$top$top

$top não tem suporte para consultas em objetos de diretório DirectoryRole ou SubscribedSku.$top is not supported for queries on DirectoryRole or SubscribedSku directory objects.

Suporte à paginação Paging support

Você pode ler para frente e para trás no gráfico.You can page forward and backward in the Graph.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.A response that contains paged results will include a skip token (odata.nextLink) that allows you to get the next page of results.Esse token de salto pode ser combinado com um argumento de consulta previous-page=true para paginar no sentido contrário.This skip token can be combined with a previous-page=true query argument to page backwards.

O seguinte exemplo de solicitação demonstra a leitura para a frente:The follow example request demonstrates paging forward:

SolicitaçãoRequestDescriçãoDescription
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.The $skiptoken parameter from the previous response is included, and allows you to get the next page of results.

O seguinte exemplo de solicitação demonstra a leitura para trás:The following example request demonstrates paging backward:

SolicitaçãoRequestDescriçãoDescription
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.The $skiptoken parameter from the previous response is included.Quando ele for combinado com o parâmetro &previous-page=true, a página anterior de resultados será recuperada.When this is combined with the &previous-page=true parameter, the previous page of results will be retrieved.

Os seguintes passos demonstram a solicitação/resposta entre páginas para frente e para trás:The following steps demonstrate the request/response flow to page forward and backward:

  1. Uma solicitação é feita para obter uma lista dos 10 primeiros usuários de 15.A request is made to get a list of the first 10 users out of 15.A resposta contém um símbolo de salto para indicar a página final de 10 usuários.The response contains a skip token to indicate the final page of 10 users.
  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.To get the final 5 users, another request is made that contains the skip token returned from the previous response.
  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.To page backward, a request is made using the skip token returned in step 1 and the parameter &previous-page=true is added to the request.
  4. A resposta contém a (primeira) página anterior de 10 usuários.The response contains the previous (first) page of 10 users.Em um cenário diferente, onde mais páginas estão à esquerda, um novo símbolo de salto seria devolvido.In a different scenario where more pages are left, a new skip token would be returned.Esse novo token de salto pode ser adicionado à solicitação, juntamente com, &previous-page=true para paginar no sentido contrário novamente.This new skip token can be added to the request along with &previous-page=true to page backward again.

As seguintes restrições aplicam-se às solicitações de página:The following restrictions apply to paged requests:

  • O tamanho padrão da página é 100 bytes.The default page size is 100.O tamanho máximo da página é 999.The maximum page size is 999.
  • As consultas em funções não oferecem suporte à paginação.Queries against roles do not support paging.Isso inclui ler os próprios objetos de função assim como membros da função.This includes reading role objects themselves as well as role members.
  • Consultas de listagem de recursos, como uma pesquisa por todos os usuários em um locatário (/users) dão suporte à paginação.Resource listing, such as a search for all users in a tenant (/users), queries do support paging.Por exemplo: https://graph.windows.net/contoso.com/users?api-version=1.6.For example: 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.However, across all types when a filter is applied, paging is not supported and only the first page of results is returned.
  • Paginação não tem suporte para pesquisas de link, como para consultar os membros do grupo.Paging is not supported for link searches, such as for querying group members.Por exemplo: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.For example: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.

Ordem de classificação Sort order

  • O conjunto de resultados de uma consulta por todos os usuários é ordenado pela propriedade UserPrincipalName.The result set of a query for all users is ordered by the UserPrincipalName property.Por exemplo: https://graph.windows.net/contoso.com/users?api-version=1.6.For example: 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.The result set of a query for all other top-level resources, such as Groups, Contacts, etc. is ordered by the objectId property.Por exemplo: https://graph.windows.net/contoso.com/groups?api-version=1.6.For example: 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.The order of the results of queries other than for top-level resources is indeterminate.

Consultas comuns Common queries

As seções a seguir mostram alguns exemplos de consultas comuns que podem ser executadas com a API do Graph.The following sections show some examples of common queries you can perform with the Graph API.

Consultando recursos de nível superiorQuerying top-level resources

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.The following queries demonstrate how to access top-level resources with the Graph API using contoso.com as the example tenant.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.Note that an Authorization header containing a valid bearer token received from Azure AD will be required to run queries against a tenant.

Recurso de nível superiorTop-Level ResourceResultados da consultaQuery ResultsURI (para contoso.com)URI (for contoso.com)
Recursos de alto nívelTop-level resourcesRetorna uma lista de URI dos recursos de alto nível para serviços de diretório (também listados abaixo)Returns URI list of the top-level resources for directory services (also listed below)https://graph.windows.net/contoso.com?api-version=1.6
Informações da empresaCompany informationRetorna informações da empresaReturns company informationhttps://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
ContactsContactsRetorna informações de contato organizacionalReturns organizational contact informationhttps://graph.windows.net/contoso.com/contacts?api-version=1.6
UsuáriosUsersRetorna informações do usuárioReturns user informationhttps://graph.windows.net/contoso.com/users?api-version=1.6
GruposGroupsRetorna dados do grupoReturns group datahttps://graph.windows.net/contoso.com/groups?api-version=1.6
Funções de DiretórioDirectory RolesRetorna todas as funções de diretório ativadas no locatárioReturns all activated directory roles in the tenanthttps://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkusSubscribedSkusRetorna as assinaturas do locatárioReturns the tenant's subscriptionshttps://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
Metadados do diretórioDirectory metadataRetorna 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)Returns a Service Metadata Document that describes the data model (that is, structure and organization of directory resources)https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Outras operações de consultaOther query operations

A tabela a seguir mostra mais alguns exemplos de consultas de API do Graph usando contoso.com como o locatário de exemplo.The following table shows some additional example Graph API queries using contoso.com as the example tenant.

Operação de consultaQuery OperationURI (para contoso.com)URI (for contoso.com)
Listar todos os usuários e gruposList all Users and Groupshttps://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 userPrincipalNameRetrieve individual User by specifying the objectId or 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”Request and Filter for a user with displayName equal to “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”Request and Filter for specific users with firstName equal to “Jon”https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6
Filtre para valores de givenName e surname.Filter for givenName and surname values.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 objectIdRetrieve individual group by specifying the objectIdhttps://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
Recuperar o gerenciador de um usuárioRetrieve a user’s managerhttps://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árioRetrieve a user’s direct reports listhttps://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árioRetrieve a list of links to a user’s direct reportshttps://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 grupoRetrieve membership list of a grouphttps://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.Retrieve a list of links to the members of a group.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)Retrieve a user’s group membership (not transitive)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)Retrieve a list of the groups that the user is a member of (not transitive)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"Request and filter for groups with displayName >= "az" and <= "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 B2CReturn all local account users in an Azure Active Directory B2C tenanthttps://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 B2CReturn local account user with the sign-in name "joe@example.com" from an Azure Active Directory B2C tenanthttps://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.Note: White space in the query string should be URL-encoded before sending a request.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.For example, the following query string, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, should be URL encoded as: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.

Recursos adicionais Additional resources

© 2018 Microsoft