Partilhar via


Usar parâmetros de consulta para personalizar respostas

O Microsoft Graph suporta parâmetros de consulta que pode utilizar para especificar e controlar a quantidade de dados devolvidos numa resposta. O suporte para os parâmetros de consulta exatos varia de uma operação de API para outra e, dependendo da API, pode diferir entre os pontos finais v1.0 e beta .

Dica

No ponto final beta , o $ prefixo é opcional. Por exemplo, em vez de $filter, você pode usar filter. No ponto final v1.0 , o $ prefixo é opcional apenas para um subconjunto de APIs. Para simplificar, inclua $ sempre em todas as versões.

Os parâmetros de consulta podem ser opções de consulta de sistema OData ou outros parâmetros de consulta.

Opções de consulta de sistema OData

Uma operação de API do Microsoft Graph pode oferecer suporte a uma ou mais das seguintes opções de consulta de sistema OData. Estas opções de consulta são compatíveis com a linguagem de consulta OData V4 e são suportadas apenas em operações GET.

Clique nos exemplos para testá-los no Explorador do Graph.

Nome Descrição Exemplo
$count Recupera a contagem total de recursos correspondentes. /me/messages?$top=2&$count=true
$expand Recupera os recursos relacionados. /groups?$expand=members
$filter Filtra os resultados (linhas). /users?$filter=startswith(givenName,'J')
$format Retorna os resultados no formato de mídia especificado. /users?$format=json
$orderby Ordena os resultados. /users?$orderby=displayName desc
$search Retorna os resultados com base nos critérios de pesquisa. /me/messages?$search=pizza
$select Filtra as propriedades (colunas). /users?$select=givenName,surname
$skip Indexa num conjunto de resultados. Também utilizado por algumas APIs para implementar paginação e pode ser utilizado em conjunto com $top para páginar resultados manualmente. /me/messages?$skip=11
$top Define o tamanho de página de resultados. /users?$top=2

Para saber as opções de consulta do sistema OData que uma API e as respetivas propriedades suportam, veja a tabela "Propriedades" na página de recursos e a secção "Parâmetros de consulta opcionais" das operações LIST e GET para a API.

Outros parâmetros de consulta

Nome Descrição Exemplo
$skipToken Recupera a próxima página de resultados de conjuntos de resultados que abrangem várias páginas. (Em vez disso, algumas APIs utilizam $skip .) /users?$skiptoken=X%274453707402000100000017...

Outros recursos de URL OData

Os seguintes recursos OData 4.0 são segmentos de URL, não parâmetros de consulta.

Nome Descrição Exemplo
$count Recupera o total inteiro da coleção. GET /users/$count
GET /groups/{id}/members/$count

Obter uma contagem de utilizadores
$ref Atualiza a associação de entidades a uma coleção. POST /groups/{id}/members/$ref

Adicionar um membro a um grupo
$value Recupera ou atualiza o valor binário de um item. GET /me/photo/$value

Obter a fotografia de um utilizador, grupo ou equipa
&batch Combina várias solicitações HTTP em uma solicitação em lote. POST /$batch

Envio em lote JSON

Codificação de parâmetros da consulta

Os valores dos parâmetros de consulta devem ser codificados por percentagem de acordo com RFC 3986. Por exemplo, todos os carateres reservados nas cadeias de consulta têm de estar codificados por percentagem. Muitos clientes HTTP, browsers e ferramentas (como o Explorador do Graph) processam esta codificação por si. Se uma consulta falhar, uma causa possível é a falha ao codificar adequadamente os valores dos parâmetros de consulta. Em alguns casos, tem de codificar novamente os valores.

Observação

Existe um problema conhecido relacionado com a codificação de símbolos de e comercial (&) em $search expressões no ponto final v1.0 . Para obter mais informações sobre o problema e a solução recomendada, veja Problema conhecido: $search para objetos de diretório falham no caráter de e comercial codificado (&).

Por exemplo, um URL não codificado tem o seguinte aspeto:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')

O URL devidamente codificado por percentagem tem o seguinte aspeto:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')

O URL com codificação dupla tem o seguinte aspeto:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29

Escape de aspas simples

Para pedidos que utilizem plicas, se os valores de parâmetros também contiverem plicas, têm de ser escape duplos; caso contrário, o pedido falha devido a sintaxe inválida. No exemplo, o valor de cadeia de caracteres let''s meet for lunch? tem o escape de aspas simples.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'

parâmetro count

Use o $count parâmetro de consulta para recuperar a contagem do número total de itens em uma coleção ou correspondência de uma expressão. $count pode ser usado das seguintes maneiras:

  1. Como parâmetro de cadeia de consulta com a sintaxe $count=true para incluir uma contagem do número total de itens numa coleção juntamente com a página de valores de dados devolvidos pelo Microsoft Graph. Por exemplo, users?$count=true.
  2. Como um segmento de URL para recuperar somente o total inteiro da coleção. Por exemplo, users/$count.
  3. Em uma $filter expressão com operadores de igualdade para recuperar uma coleção de dados onde a propriedade filtrada é uma coleção vazia. Veja Utilizar o parâmetro de consulta $filter para filtrar uma coleção de objetos.

Observação

  1. Em recursos que derivam do directoryObject, $count só é suportado em uma consulta avançada. Veja Capacidades avançadas de consulta em objetos de diretório.
  2. Não há suporte para o uso de $count em locatários do Microsoft Azure Active Directory B2C.

Por exemplo, o pedido seguinte devolve a coleção de contactos do utilizador atual e o número de itens na coleção de contactos numa propriedade @odata.count .

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true

Para objetos de diretório, ou seja, recursos que derivam de directoryObject, o $count parâmetro de consulta só é suportado em consultas avançadas.

parâmetro expand

Muitos recursos do Microsoft Graph expõem as propriedades declaradas do recurso e as relações delas com outros recursos. Essas relações também são chamadas de propriedades de referência ou propriedades de navegação e podem fazer referência a um único recurso ou a uma coleção de recursos. Por exemplo, as pastas de email, gerente e subordinados diretos de um usuário são todas expostas como relações.

Você pode usar o parâmetro de cadeia de caracteres de consulta $expand para incluir o recurso expandido ou a coleção referenciada por uma única relação (propriedade de navegação) em seus resultados. Para algumas APIs, apenas uma relação pode ser expandida num único pedido.

O exemplo a seguir obtém informações da unidade raiz juntamente com os itens filho de nível superior em uma unidade:

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children

Com algumas coleções de recursos, também pode especificar as propriedades a devolver nos recursos expandidos ao adicionar um $select parâmetro. O exemplo seguinte executa a mesma consulta que o exemplo anterior, mas utiliza uma $select instrução para limitar as propriedades devolvidas para os itens subordinados expandidos às propriedades do ID e do nome .

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)

Observação

  • Nem todas as relações e recursos dão suporte ao parâmetro de consulta $expand. Por exemplo, você pode expandir as relações directReports, manager e memberOf em um usuário, mas não pode expandir seus relacionamentos de eventos, mensagens ou foto. Nem todos os recursos ou relações dão suporte ao uso de $select em itens expandidos.

  • Com os recursos do Microsoft Entra que derivam de directoryObject, como utilizador e grupo, $expand normalmente devolve um máximo de 20 itens para a relação expandida e não tem @odata.nextLink. Para obter detalhes, veja Query parameter limitations (Limitações dos parâmetros de consulta).

  • $expand atualmente não é compatível com consultas avançadas.

parâmetro filter

Use o parâmetro de consulta $filter para recuperar apenas um subconjunto de um conjunto. Para obter orientações sobre como utilizar $filtero , veja Utilizar o parâmetro de consulta $filter para filtrar uma coleção de objetos.

parâmetro format

Use o parâmetro de consulta $format para especificar o formato de mídia dos itens retornados do Microsoft Graph.

Por exemplo, a seguinte solicitação retorna os usuários na organização no formato json:

GET https://graph.microsoft.com/v1.0/users?$format=json

Observação

O $format parâmetro de consulta suporta vários formatos (por exemplo, atom, xmle json) mas os resultados podem não ser devolvidos em todos os formatos.

parâmetro orderby

Use o parâmetro de consulta $orderby para especificar a ordem de classificação dos itens retornados pelo Microsoft Graph. A ordem padrão é ordem crescente.

Por exemplo, o pedido seguinte devolve os utilizadores na organização ordenados pelo respetivo nome a apresentar por ordem ascendente:

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName

Algumas APIs suportam a ordenação por entidades de tipo complexo. O pedido seguinte obtém mensagens e ordena-as pelo campo de endereço da propriedade from , que é do tipo complexo emailAddress:

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address

Para ordenar os resultados por ordem ascendente ou descendente, acrescente ou ascdesc ao nome do campo, separados por um espaço; por exemplo, ?$orderby=name desc (não codificado), ?$orderby=name%20desc (codificado por URL). Se a sequência de ordenação não for especificada, a ordem ascendente predefinida é inferida.

Com algumas APIs, você pode ordenar os resultados em várias propriedades. Por exemplo, a solicitação a seguir ordena as mensagens na caixa de entrada do usuário primeiro pelo nome da pessoa que enviou, em ordem decrescente (Z – A) e, em seguida, por assunto, em ordem ascendente (padrão).

GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject

Observação

Quando especificar $filter, o serviço infere uma sequência de ordenação para os resultados. Se você usar $orderby e $filter juntos para receber mensagens, como o servidor sempre infere uma ordem de classificação para os resultados de $filter, você deve especificar propriedades de determinadas maneiras.

O exemplo a seguir mostra uma consulta filtrada pelas propriedades subject e priority e classificadas pelas propriedades subject, priority e receivedDateTime em ordem decrescente.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc

Observação

A combinação dos parâmetros de consulta $orderby e $filter não tem suporte para objetos de diretório. Veja Capacidades avançadas de consulta em objetos de diretório.

parâmetro search

Use o parâmetro de consulta $search para restringir os resultados de uma solicitação para corresponder a um critério de pesquisa. Sua sintaxe e comportamento variam de uma operação de API para outra. Para ver a sintaxe para $search em diferentes recursos, consulte Usar o parâmetro de consulta $search para corresponder a um critério de pesquisa.

parâmetro select

Utilize o $select parâmetro de consulta para devolver um subconjunto de propriedades de um recurso. Com $select, você pode especificar um subconjunto ou um superconjunto das propriedades padrão.

Quando faz um pedido GET sem utilizar $select para limitar a quantidade de dados de propriedades, o Microsoft Graph inclui uma propriedade @microsoft.graph.tips que fornece uma recomendação de melhores práticas para utilizar $select semelhante à seguinte mensagem:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Por exemplo, ao recuperar as mensagens do usuário conectado, você pode especificar que somente as propriedades from e subject sejam retornadas:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Importante

Em geral, recomendamos que você use $select para limitar as propriedades retornadas por uma consulta àqueles exigidas pelo aplicativo. Isso se aplica particularmente a consultas com o potencial de retornar um conjunto de resultados amplo. Limitar as propriedades retornadas em cada linha reduzirá a carga de rede e ajudará a melhorar o desempenho do aplicativo.

Na v1.0, alguns recursos do Microsoft Entra que derivam de directoryObject, como utilizador e grupo, devolvem um subconjunto limitado e predefinido de propriedades nas leituras. Para estes recursos, tem de utilizar $select para devolver propriedades fora do conjunto predefinido.

parâmetro skip

Utilize o $skip parâmetro de consulta para definir o número de itens a ignorar no início de uma coleção. Por exemplo, o pedido seguinte devolve eventos para o utilizador ordenados por data criada, começando pelo 21º evento na coleção:

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20

Algumas APIs do Microsoft Graph, como Email e Calendário do Outlook (mensagem, evento e calendário), usam $skip para implementar a paginação. Quando os resultados de uma consulta abrangem várias páginas, estas APIs devolvem uma propriedade @odata.nextLink com um URL que contém um $skip parâmetro. Você pode usar essa URL para retornar a próxima página de resultados. Para saber mais, confira Paginação.

Os objetos de diretório, como o utilizador, o grupo e a aplicação , não suportam $skip.

parâmetro skipToken

Algumas solicitações retornam várias páginas de dados, devido à paginação do lado do servidor ou devido ao uso do parâmetro $top para limitar o tamanho da página da resposta. Muitas APIs do Microsoft Graph usam o parâmetro de consulta skipToken para fazer referência a páginas subsequentes do resultado.
Este parâmetro contém um token opaco que referencia a página seguinte dos resultados e é devolvido no URL fornecido na propriedade @odata.nextLink na resposta. Para saber mais, confira Paginação.

Observação

Se você estiver usando a OData Count (adicionando $count=true na cadeia de caracteres de consulta) para consultas em objetos de diretório, a propriedade @odata.count estará presente apenas na primeira página.

O cabeçalho consistencyLevel necessário para consultas avançadas em objetos de diretório não está incluído por padrão em solicitações de página subsequentes. Ele deve ser definido explicitamente nas páginas subsequentes.

parâmetro top

Utilize o $top parâmetro de consulta para especificar o número de itens a incluir no resultado.

Se mais itens permanecerem no conjunto de resultados, o corpo da resposta contém um parâmetro @odata.nextLink . Esse parâmetro contém uma URL que você pode usar para obter a próxima página de resultados. Para saber mais, confira Paginação.

O valor mínimo de $top é 1 e o máximo depende da API correspondente.

Por exemplo, a seguinte solicitação de lista de mensagens retorna as cinco primeiras mensagens na caixa de correio do usuário:

GET https://graph.microsoft.com/v1.0/me/messages?$top=5

Observação

O cabeçalho consistencyLevel necessário para consultas avançadas em objetos de diretório não está incluído por padrão em solicitações de página subsequentes. Ele deve ser definido explicitamente nas páginas subsequentes.

Tratamento de erro para parâmetros de consulta

Alguns pedidos devolvem uma mensagem de erro se não for suportado um parâmetro de consulta especificado. Por exemplo, não pode utilizar $expand na user/photo relação.

https://graph.microsoft.com/v1.0/me?$expand=photo
{
    "error":{
        "code":"ExpandNotSupported",
        "message":"Expand is not allowed for property 'Photo' according to the entity schema.",
        "innerError":{
            "request-id":"1653fefd-bc31-484b-bb10-8dc33cb853ec",
            "date":"2017-07-31T20:55:01"
        }
    }
}

No entanto, por vezes, os parâmetros de consulta especificados num pedido falham silenciosamente. Por exemplo, para parâmetros de consulta não suportados e para combinações não suportadas de parâmetros de consulta. Nesses casos, você deve examinar os dados retornados pela solicitação para determinar se os parâmetros de consulta que especificou tiveram o efeito desejado.