Suportado consultas, filtros e as opções de paginação | Conceitos da Graph API
Este tópico lista as operações de paginação que pode utilizar com a Graph API do Azure Active Directory (AD), filtros e as opções de consulta. A secção final fornece alguns exemplos de consultas comuns que pode realizar com a Azure AD Graph API.
Importante
Recomendamos vivamente que utilize Microsoft Graph em vez do AD Graph API do Azure para aceder aos recursos do Azure Active Directory. A nossa esforços de desenvolvimento são agora concentrated no Microsoft Graph e estão a ser planeados sem melhoramentos adicionais para AD Graph API do Azure. Existem um número muito limitado de cenários para o qual AD Graph API do Azure ainda poderá ser apropriado; Para obter mais informações, consulte o Microsoft Graph ou o Azure AD Graph blogue no Dev Center do Office.
Endereçamento
As consultas abaixo todos os endereços de inquilino utilizando um nome de domínio. Pode substituir contoso.com um dos nomes de domínio registado do seu inquilino, com o ID do inquilino (GUID) ou com o MyOrganization alias (para acesso delegado). Em alguns casos, poderá utilizar o me alias. Para obter informações sobre formas de endereçamento de inquilino, consulte descrição geral de operações.
Opções de consulta suportada
O gráfico suporta as seguintes opções de consulta: $filter, $orderby, $expand, $top, e $format. As seguintes opções de consulta não são atualmente suportadas: $count, $inlinecount, e $skip.
$filter
As seguintes restrições gerais que se aplicam a consultas que contêm um filtro:
$filter não pode ser combinado com $orderby expressões.
Filtragem não é suportada para consultas DirectoryRole ou SubscribedSku objetos de diretório.
Nem todas as propriedades de objetos de diretório suportadas podem ser utilizadas numa expressão de filtro. Para obter informações sobre as propriedades de filtráveis dos tipos suportados, consulte utilizador, grupo, e contacte.
As seguintes restrições aplicam-se para expressões de filtro:
Operadores lógicos: e e ou são suportados. 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 ou igual a) e le (menor ou igual a) são suportados.
startswith é suportada. Por exemplo:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')qualquer é suportada ao consultar as propriedades com múltiplos valores. 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éticas: não suportado.
Funções: não suportado.
nulo valores não são suportados como operando em expressões de filtro. Por exemplo, não é possível especificar um nulo valor a filtrar propriedades.
Para filtrar, tal como uma propriedade binária a issuerUserId no userIdentities, o valor tem de ser primeiro antes de poder ser utilizada na cadeia de $filter de codificado em base64.
$orderby
$orderby ordenar os objetos devolvidos pelo parâmetro especificado. Pedidos de exemplo utilizando a opção de $orderby:
| Pedido | Descrição |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Devolve uma lista de utilizadores ordenados pelo respetivo nome de apresentação. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Devolve uma lista dos primeiro 50 utilizadores ordenados pelo respetivo nome de apresentação. |
As seguintes restrições aplicam-se para $orderby expressões:
As ordens de ordenação dois atualmente são suportadas: DisplayName para utilizador e grupo objetos, e UserPrincipalName para utilizador objetos. A sequência de ordenação predefinidas para os utilizadores é por UserPrincipalName.
$orderby não pode ser combinado com $filter expressões.
$expand
$expand irá devolver um objeto e os respetivos objetos ligados. Pedidos de exemplo utilizando o $expanda opção:
| Pedido | Descrição |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Devolve o objecto do grupo, bem como os seus membros. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Devolve os o objeto de utilizador, bem como os relatórios diretos. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Devolve tanto o objeto de utilizador, bem como respetivo gestor. |
As seguintes restrições aplicam-se para $expanda expressões:
- O número máximo de objetos devolvidos de um pedido é 20.
$top
$top não é suportado para consultas no DirectoryRole ou SubscribedSku objetos de diretório.
Suporte de paginação
Pode página frente e para trás no gráfico. Uma resposta que contém resultados paginados irá incluir um token de ignorar (odata.nextLink) que permite-lhe obter a página seguinte do resultados. Este token skip pode ser combinado com um página anterior = true argumento para a página efeitos de consulta.
Pedido de exemplo a seguir mostra como paginação reencaminhar:
| Pedido | Descrição |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
O $skiptoken parâmetro da resposta anterior está incluído e permite-lhe obter a página seguinte do resultados. |
O pedido de exemplo seguinte demonstra a paginação trás:
| Pedido | Descrição |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
O $skiptoken parâmetro da resposta anterior está incluído. Quando isto é combinado com o & página anterior = true será obtido parâmetro, a página de resultados anterior. |
Os passos seguintes demonstram o fluxo de pedido/resposta para a frente e para trás:
- É efetuado um pedido para obter uma lista dos primeiras 10 utilizadores fora 15. A resposta contém um token skip para indicar a página final de 10 utilizadores.
- Para obter os utilizadores de 5 finais, outro pedido é efetuado que contém o token skip devolvido na resposta anterior.
- A página trás, é efetuado um pedido utilizando o token skip devolvido no passo 1 e o parâmetro & página anterior = true é adicionada ao pedido.
- A resposta contém a página anterior (primeira) de 10 utilizadores. No outro cenário onde mais páginas são mantidas, seria possível devolver um novo token de ignorar. Este novo token skip pode ser adicionado ao pedido juntamente com & página anterior = true para a página para trás novamente.
As seguintes restrições aplicam-se a pedidos paginados:
- O tamanho da página predefinido é 100. O tamanho máximo de página é 999.
- As consultas em relação às funções não suportam a paginação. Isto inclui ao ler os objectos de função próprios, bem como a função de membros.
- Listar, por exemplo, uma procura para todos os utilizadores de um inquilino de recursos (/users), consultas suporta paginação. Por exemplo:
https://graph.windows.net/contoso.com/users?api-version=1.6. No entanto, em todos os tipos quando um filtro ser aplicado, não é suportada paginação e é devolvida apenas a primeira página de resultados. - A paginação não é suportada para pesquisas de ligação, tal 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.
Sequência de ordenação
- O conjunto de resultados de uma consulta para todos os utilizadores está ordenado pelo UserPrincipalName propriedade. Por exemplo:
https://graph.windows.net/contoso.com/users?api-version=1.6. - O conjunto de resultados de uma consulta para todos os outros recursos de nível superior, tais como grupos, contactos, etc. está ordenado pelo objectId propriedade. Por exemplo:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - A ordem dos resultados de consultas diferente de recursos de nível superior é indeterminada.
Consultas comuns
As secções seguintes mostram alguns exemplos de consultas comuns que pode realizar com a Graph API.
Consulta de recursos de nível superior
As consultas seguintes demonstram como aceder a recursos de nível superior com a Graph API utilizando contoso.com como o inquilino de exemplo. Tenha em atenção que um cabeçalho de autorização que contém um token de portador válido recebido do Azure AD irá ser necessário para executar consultas contra um inquilino.
| Recurso de nível superior | Resultados da consulta | URI (para contoso.com) |
|---|---|---|
| Recursos de nível superior | Devolve URI lista dos recursos de nível superior dos serviços do directory (também listados abaixo) | https://graph.windows.net/contoso.com?api-version=1.6 |
| Informações da empresa | Devolve informações de empresa | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Contactos | Informações de contacto devolve organizacional | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Users | Devolve informações do utilizador | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Grupos | Devolve dados de grupo | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Funções de diretório | Devolve todas as funções de diretório ativada no inquilino do | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Devolve a subscrições do inquilino | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Metadados do diretório | Devolve um documento de metadados do serviço que descreve o modelo de dados (ou seja, a estrutura e a organização de recursos de diretório) | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Outras operações de consulta
A tabela seguinte mostra alguns exemplos adicionais consultas Graph API utilizando contoso.com como o inquilino de exemplo.
| Operação de consulta | URI (para contoso.com) |
|---|---|
| Listar todos os utilizadores e grupos | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Obter utilizadores individuais especificando o objectId ou 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 |
| Pedir e filtrar para um utilizador com o displayName igual a "Jon Silva" | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Pedir e filtrar para utilizadores específicos com firstName igual a "Jon" | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Filtrar por valores givenName e apelido. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Obter grupo individuais especificando o objectId | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Obter o Gestor do utilizador | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Obter a lista de relatórios diretos de um utilizador | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Obter uma lista de ligações para relatórios diretos de um utilizador | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Obter a lista de membros de um grupo | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Obter uma lista de ligações para os membros de um grupo. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Obter associação a grupos do utilizador (não transitiva) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Obter uma lista dos grupos de que o utilizador é membro de (não transitiva) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Pedido e filtrar grupos com o displayName > = "az" e < = "dz" | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Devolver todos os utilizadores da conta local num inquilino do Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Utilizador de retorno de conta local com o nome de início de sessão "joe@example.com" de um inquilino 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 |
Tenha em atenção: o espaço em branco na cadeia de consulta deve ser com codificação URL antes de enviar um pedido. Por exemplo, a seguinte consulta cadeia, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, deve ser URL codificado como: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.