Usar parâmetros de consulta para personalizar respostas

Artigo
03/09/2023

O Microsoft Graph fornece suporte a parâmetros de consulta opcionais que você pode usar para especificar e controlar a quantidade de dados retornados em uma resposta. O suporte para os parâmetros de consulta exatos variam de uma operação de API para outra e, dependendo da API, podem diferir entre os pontos de extremidade v1.0 e beta.

Dica

No ponto de extremidade beta, o prefixo $ é opcional. Por exemplo, em vez de $filter, você pode usar filter. No ponto de extremidade v1, o prefixo $ é opcional apenas para um subconjunto de APIs. Para simplificar, inclua sempre $ se estiver usando o ponto de extremidade v1.

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. Essas opções de consulta são compatíveis com o idioma de consulta OData V4 e têm suporte 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	Índices em um conjunto de resultados. Também usado por algumas APIs para implementar a paginação e pode ser usado em conjunto com `$top` os resultados da página manual.	`/me/messages?$skip=11`
$top	Define o tamanho de página de resultados.	`/users?$top=2`

Para conhecer as opções de consulta do sistema OData que uma API e suas propriedades suportam, consulte a tabela Propriedades na página de recursos e a seçã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. (Algumas APIs usam `$skip` em vez disso.)	`/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`
$ref	Atualiza a associação de entidades a uma coleção.	`POST /groups/{id}/members/$ref`
$value	Recupera ou atualiza o valor binário de um item.	`GET /me/photo/$value`
&batch	Combina várias solicitações HTTP em uma solicitação em lote.	`POST /$batch`

Codificação de parâmetros da consulta

Os valores dos parâmetros de consulta devem ser codificados por porcentagem de acordo com o RFC 3986. Por exemplo, todos os caracteres reservados em cadeias de caracteres de consulta devem estar codificados por porcentagem. Muitas ferramentas, navegadores e clientes HTTP (como o Explorador do Graph) ajudarão você com isso. Se uma consulta está falhando, uma causa possível é a falha na codificação adequada dos valores dos parâmetros da consulta. Em alguns casos, talvez você precise codificar os valores duas vezes.

Por exemplo, uma URL não codificada se parece com esta:

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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "startswith(givenName,%20'J')";
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "startswith(givenName,%20'J')"

requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter("startswith(givenName, 'J')")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(givenName,%20'J')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration);


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "startswith(givenName, 'J')"

A URL codificada corretamente tem a seguinte aparência:

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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "startswith(givenName,%20'J')";
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "startswith(givenName,%20'J')"

requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter("startswith(givenName, 'J')")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(givenName,%20'J')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration);


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "startswith(givenName, 'J')"

A URL de codificação dupla é semelhante a esta:

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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "startswith(givenName,%20'J')";
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "startswith(givenName,%20'J')"

requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter("startswith(givenName, 'J')")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(givenName,%20'J')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration);


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "startswith(givenName, 'J')"

Escape de aspas simples

Para pedidos que usem aspas simples, se os valores de qualquer parâmetro também contém aspas, elas devem ter escape duplo. Caso contrário, a solicitação falhará 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?'


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "subject eq 'let''s meet for lunch?'";
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "subject eq 'let''s meet for lunch?'"

requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.filter("subject eq 'let''s meet for lunch?'")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.filter('subject eq \'let\'\'s meet for lunch?\'')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "subject eq 'let''s meet for lunch?'";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->messages()->get($requestConfiguration);


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -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:

Como um parâmetro de cadeia de caracteres de consulta com a sintaxe $count=true para incluir uma contagem do número total de itens em uma coleção ao lado da página de valores de dados retornados do Microsoft Graph. Por exemplo, users?$count=true.
Como um segmento de URL para recuperar somente o total inteiro da coleção. Por exemplo, users/$count.
Em uma $filter expressão com operadores de igualdade para recuperar uma coleção de dados onde a propriedade filtrada é uma coleção vazia. Consulte Usar o parâmetro de consulta $filter para filtrar uma coleção de objetos.

Observação

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

Por exemplo, a solicitação a seguir retornará tanto o conjunto contato do usuário atual quanto o número de itens no conjunto contato na propriedade @odata.count.

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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Contacts.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Count = true;
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestCount := true

requestParameters := &graphconfig.ItemContactsRequestBuilderGetQueryParameters{
	Count: &requestCount,
}
configuration := &graphconfig.ItemContactsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Contacts().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

ContactCollectionPage contacts = graphClient.me().contacts()
	.buildRequest()
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let contacts = await client.api('/me/contacts')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new ContactsRequestBuilderGetRequestConfiguration();
$queryParameters = ContactsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->contacts()->get($requestConfiguration);


Import-Module Microsoft.Graph.PersonalContacts

# A UPN can also be used as -UserId.
Get-MgUserContact -UserId $userId -CountVariable CountVar

O parâmetro de consulta $count é suportado nas coleções dos seguintes recursos utilizados com frequência e suas relações que derivam do directoryObject e somente em consultas avançadas:

parâmetro expand

Muitos recursos do Microsoft Graph expõem as propriedades declaradas do recurso, bem como 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 um conjunto de recursos. Por exemplo, as pastas de email, gerente e subordinados diretos de um usuário são todas expostas como relações.

Normalmente, você pode consultar as propriedades de um recurso ou uma de suas relações em uma única solicitação, mas não ambas. 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. Apenas uma relação pode ser expandida em uma única solicitação.

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

Snippet not available

Snippet not available


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

DriveItem driveItem = graphClient.me().drive().root()
	.buildRequest()
	.expand("children")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/me/drive/root')
	.expand('children')
	.get();

Snippet not available

Snippet not available

Com algumas coleções de recursos, você também pode especificar as propriedades a serem retornadas nos recursos expandidos adicionando um $select parâmetro. O exemplo a seguir executa a mesma consulta que o exemplo anterior, mas usa uma $select instrução para limitar as propriedades retornadas para os itens filho expandidos para as propriedades id e name .

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

Snippet not available

Snippet not available


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

DriveItem driveItem = graphClient.me().drive().root()
	.buildRequest()
	.expand("children($select=id,name)")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/me/drive/root')
	.expand('children($select=id,name)')
	.get();

Snippet not available

Snippet not available

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 Azure Active Directory que derivam de directoryObject, como usuário e grupo, o $expand normalmente retorna um máximo de 20 itens para a relação expandida e não tem @odata.nextLink. Veja mais problemas conhecidos.
$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 diretrizes sobre como usar $filter, consulte Usar 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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Format = "json";
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFormat := "json"

requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
	Format: &requestFormat,
}
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->format = "json";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration);


Import-Module Microsoft.Graph.Users

Get-MgUser -Format "json"

Observação

O parâmetro de consulta $format é compatível com vários formatos (por exemplo, atom, xml e json), mas os resultados podem não ser retornados 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, a solicitação a seguir retorna os usuários da organização ordenados por seu nome de exibição:

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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
	Orderby: [] string {"displayName"},
}
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.orderBy("displayName")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.orderby('displayName')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["displayName"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration);


Import-Module Microsoft.Graph.Users

Get-MgUser -Sort "displayName"

Você também pode classificar por entidades de tipo complexo. A solicitação a seguir obtém mensagens e as classifica 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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/address" };
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
	Orderby: [] string {"from/emailAddress/address"},
}
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.orderBy("from/emailAddress/address")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.orderby('from/emailAddress/address')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["from/emailAddress/address"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->messages()->get($requestConfiguration);


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Sort "from/emailAddress/address"

Para classificar os resultados em ordem crescente ou decrescente, anexe asc ou desc ao nome do campo, separado por um espaço, por exemplo, ?$orderby=name%20desc. Se a ordem de classificação não for especificada, o padrão (ordem crescente) será inferido.

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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.MailFolders["{mailFolder-id}"].Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/name desc","subject" };
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphconfig.ItemMailFolderItemMessagesRequestBuilderGetQueryParameters{
	Orderby: [] string {"from/emailAddress/name desc","subject"},
}
configuration := &graphconfig.ItemMailFolderItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().MailFolders().ByMailFolderId("mailFolder-id").Messages().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().mailFolders("Inbox").messages()
	.buildRequest()
	.orderBy("from/emailAddress/name desc,subject")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/mailFolders/Inbox/messages')
	.orderby('from/emailAddress/name desc,subject')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["from/emailAddress/name desc","subject"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->mailFolders()->byMailFolderId('mailFolder-id')->messages()->get($requestConfiguration);


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMailFolderMessage -UserId $userId -MailFolderId $mailFolderId -Sort "from/emailAddress/name desc,subject"

Observação

Quando você especificar $filter o servidor inferirá uma ordem de classificaçã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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "Subject eq 'welcome' and importance eq 'normal'";
	requestConfiguration.QueryParameters.Orderby = new string []{ "subject","importance","receivedDateTime desc" };
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "Subject eq 'welcome' and importance eq 'normal'"

requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Orderby: [] string {"subject","importance","receivedDateTime desc"},
}
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.filter("Subject eq 'welcome' and importance eq 'normal'")
	.orderBy("subject,importance,receivedDateTime desc")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.filter('Subject eq \'welcome\' and importance eq \'normal\'')
	.orderby('subject,importance,receivedDateTime desc')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "Subject eq 'welcome' and importance eq 'normal'";
$queryParameters->orderby = ["subject","importance","receivedDateTime desc"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->messages()->get($requestConfiguration);


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "Subject eq 'welcome' and importance eq 'normal'" -Sort "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. Consulte Recursos avançados de consulta em objetos de diretório do Microsoft Azure Active Directory.

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

Use o parâmetro de consulta $select para retornar um conjunto de propriedades diferente do padrão definido para um recurso individual ou um conjunto de recursos. Com $select, você pode especificar um subconjunto ou um superconjunto das propriedades padrão.

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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "from","subject" };
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
	Select: [] string {"from","subject"},
}
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.select("from,subject")
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.select('from,subject')
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["from","subject"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->messages()->get($requestConfiguration);


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Property "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.

Em v1.0, alguns recursos Azure AD que derivam do diretórioObject, como usuário e grupo, retornam um subconjunto limitado e padrão de propriedades em leituras. Para esses recursos, você deve usar $select para retornar propriedades fora do conjunto padrão.

parâmetro skip

Use o $skip parâmetro de consulta para definir o número de itens a serem pulados no início de uma coleção. Por exemplo, a solicitação a seguir retorna eventos para o usuário classificado pela data criada, começando com o 21º evento da coleção:

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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Events.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "createdDateTime" };
	requestConfiguration.QueryParameters.Skip = 20;
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestSkip := int32(20)

requestParameters := &graphconfig.ItemEventsRequestBuilderGetQueryParameters{
	Orderby: [] string {"createdDateTime"},
	Skip: &requestSkip,
}
configuration := &graphconfig.ItemEventsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Events().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

EventCollectionPage events = graphClient.me().events()
	.buildRequest()
	.orderBy("createdDateTime")
	.skip(20)
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let events = await client.api('/me/events')
	.orderby('createdDateTime')
	.skip(20)
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new EventsRequestBuilderGetRequestConfiguration();
$queryParameters = EventsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["createdDateTime"];
$queryParameters->skip = 20;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->events()->get($requestConfiguration);


Import-Module Microsoft.Graph.Calendar

# A UPN can also be used as -UserId.
Get-MgUserEvent -UserId $userId -Sort "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 ocuparem várias páginas, essas APIs retornarão uma propriedade @odata:nextLink com uma URL que contém um parâmetro $skip. Você pode usar essa URL para retornar a próxima página de resultados. Para saber mais, confira Paginação.

Objetos de diretório , como usuário, grupo e aplicativo , não dão suporte $skipa .

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.
O parâmetro $skiptoken contém um token opaco que faz referência à próxima página de resultados e é retornado na URL fornecida 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

Use o $top parâmetro de consulta para especificar o número de itens a serem incluídos no resultado.

Se restarem mais itens no conjunto de resultados, o corpo da resposta conterá 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


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Top = 5;
});



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestTop := int32(5)

requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
	Top: &requestTop,
}
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.top(5)
	.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.top(5)
	.get();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->top = 5;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->messages()->get($requestConfiguration);


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Top 5

Observação

Tratamento de erro para parâmetros de consulta

Algumas solicitações retornarão uma mensagem de erro se um parâmetro de consulta especificado não tiver suporte. Por exemplo, você não pode usar $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, é importante observar que os parâmetros de consulta especificados em uma solicitação podem falhar silenciosamente. Isso pode ser verdadeiro para parâmetros de consulta sem suporte, bem como para combinações de parâmetros de consulta sem suporte. 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.

Usar parâmetros de consulta para personalizar respostas

Opções de consulta de sistema OData

Outros parâmetros de consulta

Outros recursos de URL OData

Codificação de parâmetros da consulta

Escape de aspas simples

parâmetro count

parâmetro expand

parâmetro filter

parâmetro format

parâmetro orderby

parâmetro search

parâmetro select

parâmetro skip

parâmetro skipToken

parâmetro top

Tratamento de erro para parâmetros de consulta

Confira também

Recursos adicionais

Recursos adicionais