Utilizar o parâmetro de consulta $search nas APIs do Microsoft Graph

O $search parâmetro de consulta é um poderoso mecanismo de filtragem no Microsoft Graph que lhe permite encontrar dados específicos ao corresponder aos critérios de pesquisa.

O suporte para este parâmetro de consulta varia consoante a entidade. Algumas entidades, como Microsoft Entra recursos que derivam de directoryObject, suportam $search apenas em consultas avançadas.

Este artigo explica como utilizar o $search parâmetro de consulta de forma eficaz com três tipos de recursos principais: mensagens de correio, pessoas e objetos de Microsoft Entra ID (objetos de diretório). Vai aprender os requisitos de sintaxe específicos, as propriedades suportadas e os comportamentos de pesquisa para cada tipo de recurso.

Utilizar $search em coleções de mensagens

Pode procurar mensagens com base em propriedades de mensagens específicas. Os resultados da pesquisa são ordenados pela data e hora em que a mensagem foi enviada. Um $search pedido devolve até 1000 resultados.

Quando pesquisa mensagens sem especificar as propriedades da mensagem, a pesquisa destina-se a estas propriedades predefinidas: de, assunto e corpo.

O exemplo a seguir retorna todas as mensagens na Caixa de Entrada do usuário que contenham "pizza" em qualquer uma das três propriedades de pesquisa padrão:

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"


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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"pizza\"";
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

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


requestSearch := "\"pizza\""

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.search = "\"pizza\"";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.search('pizza')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"pizza\"";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Search '"pizza"'


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		search = "\"pizza\"",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

Em alternativa, pode procurar mensagens ao especificar nomes de propriedades de mensagens que a sintaxe KQL (Keyword Query Language) reconhece. Esses nomes de propriedades correspondem às propriedades definidas na entidade mensagem do Microsoft Graph. O Outlook e outras aplicações do Microsoft 365, como o SharePoint, suportam sintaxe KQL, que fornece um domínio de deteção comum para os respetivos arquivos de dados.

Propriedades de emails pesquisáveis	Descrição	Exemplo
attachment	Nomes de ficheiros anexados a uma mensagem de e-mail.	OBTER`../me/messages?$search="attachment:api-catalog.md"`
bcc	O campo Cco de uma mensagem de email, especificado como um endereço SMTP, nome de exibição ou alias.	OBTER`../me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients`
body	O corpo de uma mensagem de email.	OBTER`../me/messages?$search="body:excitement"`
cc	O campo Cc de uma mensagem de email, especificado como um endereço SMTP, nome de exibição ou alias.	OBTER`../me/messages?$search="cc:danas"&$select=subject,ccRecipients`
from	O remetente de uma mensagem de email, especificado como um endereço SMTP, nome de exibição ou alias.	OBTER`../me/messages?$search="from:randiw"&$select=subject,from` OBTER`../me/messages?$search="from:adelev OR from:alexw OR from: allanD"&$select=subject, from`
hasAttachment	`true` se uma mensagem de e-mail contiver um anexo que não seja um anexo inline; `false` caso contrário.	OBTER`../me/messages?$search="hasAttachments:true"`
importance	A importância de uma mensagem de e-mail que um remetente pode especificar ao enviar uma mensagem. Os valores possíveis são `low`, `medium`ou `high`.	OBTER`../me/messages?$search="importance:high"&$select=subject,importance`
kind	O tipo de mensagem. Os valores possíveis são `contacts`, `docs`, `email`, `faxes`, `im`, `journals`, `meetings`, `notes`, `posts`, `rssfeeds`, , `tasks`ou `voicemail`.	OBTER`../me/messages?$search="kind:voicemail"`
participants	Os campos de, para, Cc e Cco de uma mensagem de email, especificados como um endereço SMTP, nome de exibição ou alias.	OBTER`../me/messages?$search="participants:danas"`
received	A data em que um destinatário recebeu uma mensagem de e-mail.	OBTER`../me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime`
recipients	Os campos para, cc e bcc de uma mensagem de e-mail, especificados como um endereço SMTP, nome a apresentar ou alias.	OBTER`../me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients`
sent	A data em que uma mensagem de e-mail foi enviada pelo remetente.	OBTER`../me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime`
size	O tamanho de um item em bytes.	OBTER`../me/messages?$search="size:1..500000"`
subject	O texto na linha de assunto de uma mensagem de email.	OBTER`../me/messages?$search="subject:has"&$select=subject`
to	O campo para de uma mensagem de email, especificado como um endereço SMTP, nome de exibição ou alias.	OBTER`.../me/messages?$search="to:randiw"&$select=subject,toRecipients`

Para obter mais informações sobre propriedades de e-mail pesquisáveis, sintaxe KQL, operadores suportados e sugestões de pesquisa, veja estes artigos:

Utilizar $search em coleções de pessoas

Pode aplicar-se $search às propriedades displayName e emailAddresses do recurso da pessoa . Os pedidos devolvem até 250 resultados por predefinição.

O pedido seguinte procura "Irene McGowan" na coleção de objetos de pessoa para o utilizador com sessão iniciada. O Microsoft Graph procura nas propriedades displayName e emailAddresses .

GET https://graph.microsoft.com/v1.0/me/people/?$search="Irene McGowen"


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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.People.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"Irene McGowen\"";
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

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


requestSearch := "\"Irene McGowen\""

requestParameters := &graphusers.ItemPeopleRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphusers.ItemPeopleRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
people, err := graphClient.Me().People().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

PersonCollectionResponse result = graphClient.me().people().get(requestConfiguration -> {
	requestConfiguration.queryParameters.search = "\"Irene McGowen\"";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let people = await client.api('/me/people/')
	.search('Irene McGowen')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\People\PeopleRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new PeopleRequestBuilderGetRequestConfiguration();
$queryParameters = PeopleRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"Irene McGowen\"";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.People

# A UPN can also be used as -UserId.
Get-MgUserPerson -UserId $userId -Search '"Irene McGowen"'


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.people.people_request_builder import PeopleRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = PeopleRequestBuilder.PeopleRequestBuilderGetQueryParameters(
		search = "\"Irene McGowen\"",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.people.get(request_configuration = request_configuration)

O exemplo a seguir mostra a resposta.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
       {
           "id": "C0BD1BA1-A84E-4796-9C65-F8A0293741D1",
           "displayName": "Irene McGowan",
           "givenName": "Irene",
           "surname": "McGowan",
           "birthday": "",
           "personNotes": "",
           "isFavorite": false,
           "jobTitle": "Auditor",
           "companyName": null,
           "yomiCompany": "",
           "department": "Finance",
           "officeLocation": "12/1110",
           "profession": "",
           "userPrincipalName": "irenem@contoso.com",
           "imAddress": "sip:irenem@contoso.com",
           "scoredEmailAddresses": [
               {
                   "address": "irenem@contoso.com",
                   "relevanceScore": -16.446060612802224
               }
           ],
           "phones": [
               {
                   "type": "Business",
                   "number": "+1 412 555 0109"
               }
           ],
           "postalAddresses": [],
           "websites": [],
           "personType": {
               "class": "Person",
               "subclass": "OrganizationUser"
           }
       }
   ]
}

Saiba mais sobre a API de Pessoas em Obter informações sobre pessoas relevantes.

Utilizar $search em coleções de objetos de diretório

Microsoft Entra ID recursos e as respetivas relações derivadas de directoryObject suportam o $search parâmetro de consulta apenas em consultas avançadas.

Observação

O parâmetro de consulta $search não está disponível no momento nos locatários Azure AD B2C.
Existe um problema conhecido em $search objetos de diretório para valores que contêm um símbolo de e comercial (&).

A implementação de pesquisa não suporta lógica "contém". Em vez disso, utiliza uma abordagem de tokenização que extrai palavras de valores de propriedade e cadeias de pesquisa através de espaços, números, maiúsculas e minúsculas diferentes, conforme mostrado nestes exemplos:

Espaços: hello world =>hello, world
Caixa diferente⁽¹⁾: HelloWorld ou helloWORLD =>hello, world
Símbolos⁽²⁾: hello.world =>hello, ., world, helloworld
Números: hello123world =>hello, 123, world

⁽¹⁾ Para diferentes maiúsculas/minúsculas, a tokenização atualmente só funciona quando a caixa muda de minúsculas para maiúsculas. Por exemplo, HELLOworld é um token único: helloworlde HelloWORld são dois tokens: hello, world.

⁽²⁾ A lógica de tokenização também combina palavras separadas apenas por símbolos. Por exemplo, procurar helloworld localizações hello-world e hello.world.

Após a tokenização, os tokens são correspondidos independentemente das maiúsculas/minúsculas originais e em qualquer ordem. Por exemplo, displayName 李四(David Li) corresponde a cadeias de pesquisa como 李四(David Li), 李四, David, Li, David), , (李四. Li 李 Uma alteração no alfabeto (por exemplo, do latim para o cirílico ou chinês) não cria um novo token. Por exemplo, displayName 蓝色group corresponde às 蓝色group cadeias de pesquisa e 蓝色 , mas não group. DisplayName group蓝色 corresponde às group蓝色 cadeias de pesquisa e group , mas não 蓝色 ou 蓝.

A pesquisa com tokens só funciona nos campos displayName e description . Qualquer campo de tipo de cadeia pode ser utilizado em $search, mas campos que não displayName e descrição predefinidos para $filterstartswith comportamento.

Por exemplo:

GET https://graph.microsoft.com/v1.0/groups/?$search="displayName:OneVideo" OR "mail:onevideo"
ConsistencyLevel: eventual


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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"displayName:OneVideo\" OR \"mail:onevideo\"";
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestSearch := "\"displayName:OneVideo\" OR \"mail:onevideo\""

requestParameters := &graphgroups.GroupsRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphgroups.GroupsRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
	requestConfiguration.queryParameters.search = "\"displayName:OneVideo\" OR \"mail:onevideo\"";
	requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});

Snippet not available


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Groups\GroupsRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new GroupsRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = GroupsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"displayName:OneVideo\" OR \"mail:onevideo\"";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->groups()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Groups

Get-MgGroup -Search '"displayName:OneVideo" OR "mail:onevideo"'  -ConsistencyLevel eventual


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.groups.groups_request_builder import GroupsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
		search = "\"displayName:OneVideo\" OR \"mail:onevideo\"",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.groups.get(request_configuration = request_configuration)

Esta ação procura todos os grupos com nomes a apresentar que tenham one e video tokens ou correio a partir de onevideo.

Pode utilizar $search em conjunto com $filter:

GET https://graph.microsoft.com/v1.0/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"
ConsistencyLevel: eventual


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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "mailEnabled eq true";
	requestConfiguration.QueryParameters.Search = "\"displayName:OneVideo\"";
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestFilter := "mailEnabled eq true"
requestSearch := "\"displayName:OneVideo\""

requestParameters := &graphgroups.GroupsRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Search: &requestSearch,
}
configuration := &graphgroups.GroupsRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "mailEnabled eq true";
	requestConfiguration.queryParameters.search = "\"displayName:OneVideo\"";
	requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let groups = await client.api('/groups/')
	.header('ConsistencyLevel','eventual')
	.filter('mailEnabled eq true')
	.search('displayName:OneVideo')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Groups\GroupsRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new GroupsRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = GroupsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "mailEnabled eq true";
$queryParameters->search = "\"displayName:OneVideo\"";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->groups()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Groups

Get-MgGroup -Filter "mailEnabled eq true" -Search '"displayName:OneVideo"'  -ConsistencyLevel eventual


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.groups.groups_request_builder import GroupsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
		filter = "mailEnabled eq true",
		search = "\"displayName:OneVideo\"",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.groups.get(request_configuration = request_configuration)

Esta ação procura todos os grupos com capacidade de correio com nomes a apresentar semelhantes a "OneVideo". Os resultados são filtrados com base numa conjunção lógica (AND) da $filter consulta e em toda a consulta no $search.

A sintaxe de pesquisa segue estas regras:

Formato geral: $search="clause1" [AND | OR] "clauseX"
Número de cláusulas: é suportado qualquer número de cláusulas. Os parênteses para precedência também são suportados.
Sintaxe da cláusula: "<property>:<text to search>"
- Tem de especificar o nome da propriedade na cláusula .
- Toda a cláusula tem de estar entre aspas duplas. Se contiver aspas duplas ou barra invertida, escape-a com uma barra invertida. Todos os outros carateres especiais têm de ter codificação de URL.
Operadores lógicos: AND e OR os operadores têm de estar fora das aspas duplas e em maiúsculas.
Comportamento da pesquisa: a pesquisa verdadeira só é suportada para propriedades displayName e description . Qualquer propriedade que possa ser usada em $filter também pode ser usada dentro de $search. Propriedades diferentes de displayName e descrição predefinidas para $filter com o comportamento "startsWith" se a pesquisa não for suportada.
Tokenização: as entradas de cadeia que fornece no $search e as propriedades pesquisáveis são divididas em partes por espaços, diferentes tipos de maiúsculas/minúsculas e carateres (números e carateres especiais).

A tabela seguinte mostra alguns exemplos:

Classe de objeto	Descrição	Exemplo
Usuário	O caderno de endereços exibe o nome do usuário.	OBTER`../users?$search="displayName:Guthr"`
Usuário	O caderno de endereços exibe o nome ou o email do usuário.	OBTER`../users?$search="displayName:Guthr" OR "mail:Guthr"`
Grupo	O caderno de endereços exibe o nome ou a descrição de um grupo.	OBTER`../groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive")`
Grupo	Nome de exibição do catálogo de endereços em um grupo habilitado para email.	OBTER`../groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"`

Comentários

Esta página foi útil?

Last updated on 2025-07-24

Compartilhar via

Utilizar o parâmetro de consulta $search nas APIs do Microsoft Graph

Utilizar $search em coleções de mensagens

Utilizar $search em coleções de pessoas

Utilizar $search em coleções de objetos de diretório

Conteúdo relacionado

Comentários

Recursos adicionais