Usar 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 permite encontrar dados específicos por meio de critérios de pesquisa correspondentes.

O suporte para esse parâmetro de consulta varia de acordo com a entidade. Algumas entidades, como recursos do Microsoft Entra que derivam de directoryObject, oferecem suporte $search apenas em consultas avançadas.

Este artigo explica como usar o $search parâmetro de consulta efetivamente com três tipos de recursos principais: mensagens de email, pessoas e objetos do Microsoft Entra ID (objetos de diretório). Você aprende os requisitos de sintaxe específicos, as propriedades com suporte e os comportamentos de pesquisa para cada tipo de recurso.

Usar $search em coleções de mensagens

Você pode pesquisar mensagens com base em propriedades específicas da mensagem. Os resultados da pesquisa são classificados pela data e hora em que a mensagem foi enviada. Uma $search solicitação retorna até 1.000 resultados.

Quando você pesquisa mensagens sem especificar propriedades de mensagem, a pesquisa visa estas propriedades padrão: 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)

Como alternativa, você pode pesquisar mensagens especificando nomes de propriedade de mensagem que a sintaxe da linguagem QL por palavra-chave (KQL) reconhece. Esses nomes de propriedades correspondem às propriedades definidas na entidade mensagem do Microsoft Graph. O Outlook e outros aplicativos do Microsoft 365, como o SharePoint, dão suporte à sintaxe KQL, que fornece um domínio de descoberta comum para seus armazenamentos de dados.

Propriedades de emails pesquisáveis	Descrição	Exemplo
attachment	Nomes dos arquivos anexados a uma mensagem de email.	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 email contiver um anexo que não seja um anexo embutido; `false` caso contrário.	OBTER`../me/messages?$search="hasAttachments:true"`
importance	A importância de uma mensagem de email 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`, `imnotespostsmeetingsjournals`, , `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 email.	OBTER`../me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime`
recipients	Os campos 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="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients`
sent	A data em que uma mensagem de email 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 email pesquisáveis, sintaxe KQL, operadores compatíveis e dicas de pesquisa, consulte estes artigos:

Usar $search em coleções de pessoas

Você pode aplicar $search as propriedades displayName e emailAddresses do recurso pessoa . As solicitações retornam até 250 resultados por padrão.

A solicitação a seguir pesquisa "Irene McGowan" na coleção de objetos de pessoa para o usuário conectado. O Microsoft Graph pesquisa as 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.

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

Os recursos do Microsoft Entra ID e suas relações que derivam de directoryObject dão suporte ao $search parâmetro de consulta somente 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.
Há um problema conhecido com $search objetos no diretório para valores que contêm um símbolo de E comercial (&).

A implementação de pesquisa não dá suporte à lógica "contém". Em vez disso, ele usa uma abordagem de geração de tokens que extrai palavras de valores de propriedade e cadeias de caracteres de pesquisa usando espaços, números, maiúsculas e minúsculas diferentes e símbolos, conforme mostrado nestes exemplos:

Espaços: hello world =>hello, world
Maiúsculas e minúsculas diferentes⁽¹⁾: HelloWorld ou helloWORLD =>hello, world
Símbolos⁽²⁾: hello.world =>hello, ., world, helloworld
Números: hello123world =>hello, 123, world

⁽¹⁾ Para maiúsculas e minúsculas diferentes, a geração de tokens atualmente só funciona quando as maiúsculas e minúsculas mudam de minúsculas para maiúsculas. Por exemplo, HELLOworld é um único token: helloworld, e HelloWORld é dois tokens: hello, world.

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

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

A pesquisa tokenizada funciona apenas nos campos displayName e description . Qualquer campo de tipo de cadeia de caracteres pode ser usado em $search, mas campos diferentes de displayName e descrição têm como padrão o $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)

Isso pesquisa todos os grupos com nomes de exibição que têm one tokens e video ou email começando com onevideo.

Você pode usar $search junto 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)

Isso pesquisa todos os grupos habilitados para email com nomes de exibição que se parecem com "OneVideo". Os resultados são filtrados com base em uma conjunção lógica (E) da $filter consulta e toda a $searchconsulta no .

A sintaxe da pesquisa segue estas regras:

Formato geral: $search="cláusula1" [E | OR] "cláusula X"
Número de cláusulas: qualquer número de cláusulas é suportado. Parênteses para precedência também são suportados.
Sintaxe da cláusula: "<property>:<text to search>"
- Você deve especificar o nome da propriedade na cláusula.
- Toda a cláusula deve ser colocada entre aspas duplas. Se contiver aspas duplas ou barra invertida, escape com uma barra invertida. Todos os outros caracteres especiais devem ser codificados por URL.
Operadores lógicos: AND e OR os operadores devem estar fora das aspas duplas e em maiúsculas.
Comportamento da pesquisa: a pesquisa verdadeira só tem suporte para as 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 têm como padrão o $filter comportamento "startsWith" se a pesquisa não tiver suporte.
Geração de tokens: as entradas de cadeia de caracteres fornecidas e $search as propriedades pesquisáveis são divididas em partes por espaços, diferentes maiúsculas e minúsculas e tipos de caracteres (números e caracteres especiais).

A tabela a seguir 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 2026-08-24