Использование параметра запроса $search в API Microsoft Graph

2025-07-03

Параметр $search запроса — это эффективный механизм фильтрации в Microsoft Graph, который позволяет находить определенные данные, сопоставляя условия поиска.

Поддержка этого параметра запроса зависит от сущности. Некоторые сущности, например Microsoft Entra ресурсы, производные от directoryObject, поддерживаются $search только в расширенных запросах.

В этой статье объясняется, как эффективно использовать $search параметр запроса с тремя ключевыми типами ресурсов: почтовыми сообщениями, пользователями и объектами Microsoft Entra ID (объектами каталога). Вы узнаете о конкретных требованиях к синтаксису, поддерживаемых свойствах и поведении поиска для каждого типа ресурсов.

Использование $search в коллекциях сообщений

Вы можете искать сообщения на основе определенных свойств сообщений. Результаты поиска сортируются по дате и времени отправки сообщения. Запрос $search возвращает до 1000 результатов.

При поиске сообщений без указания свойств сообщения поиск предназначен для следующих свойств по умолчанию: from, subject и body.

Следующий пример кода возвращает все сообщения из папки "Входящие" вошедшего пользователя, содержащие слово "pizza" в любом из трех свойств поиска по умолчанию:

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\"";
});



mgc users messages list --user-id {user-id} --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)

Кроме того, можно искать сообщения, указав имена свойств сообщений, которые распознает синтаксис языка запросов ключевых слов (KQL). Эти имена свойств соответствуют свойствам, определенным в сущности message в Microsoft Graph. Outlook и другие приложения Microsoft 365, такие как SharePoint, поддерживают синтаксис KQL, который предоставляет общий домен обнаружения для своих хранилищ данных.

Свойство электронных писем, по которому можно выполнять поиск	Описание	Пример
attachment	Имена файлов, вложенных в сообщение электронной почты.	GET`../me/messages?$search="attachment:api-catalog.md"`
bcc	Поле Скрытая копия в сообщении электронной почты, где указан SMTP-адрес, отображаемое имя или псевдоним.	GET`../me/messages?$search="bcc:[email protected]"&$select=subject,bccRecipients`
body	Текст сообщения электронной почты.	GET`../me/messages?$search="body:excitement"`
cc	Поле Копия в сообщении электронной почты, где указан SMTP-адрес, отображаемое имя или псевдоним.	GET`../me/messages?$search="cc:danas"&$select=subject,ccRecipients`
from	Отправитель сообщения электронной почты, на которого указывает SMTP-адрес, отображаемое имя или псевдоним.	GET`../me/messages?$search="from:randiw"&$select=subject,from` GET`../me/messages?$search="from:adelev OR from:alexw OR from: allanD"&$select=subject, from`
hasAttachment	`true` Если сообщение электронной почты содержит вложение, которое не является встроенным вложением; `false` иначе.	GET`../me/messages?$search="hasAttachments:true"`
importance	Важность сообщения электронной почты, которую отправитель может указать при отправке сообщения. Возможные значения: `low`, `medium`или `high`.	GET`../me/messages?$search="importance:high"&$select=subject,importance`
kind	Тип сообщения. Возможные значения: `contacts`, `docs`, `email`, `faxes`, `im`, `journals`, `meetings`, `notes`, , `postsrssfeeds`, `tasks`или `voicemail`.	GET`../me/messages?$search="kind:voicemail"`
participants	Такие поля сообщения электронной почты, как От, Кому, Копия и Скрытая копия, где указан SMTP-адрес, отображаемое имя или псевдоним.	GET`../me/messages?$search="participants:danas"`
received	Дата получения получателем сообщения электронной почты.	GET`../me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime`
recipients	Поля to, cc и bcc сообщения электронной почты, указанные в виде SMTP-адреса, отображаемого имени или псевдонима.	GET`../me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients`
sent	Дата отправки сообщения электронной почты отправителем.	GET`../me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime`
size	Размер элемента в байтах.	GET`../me/messages?$search="size:1..500000"`
subject	Текст в строке темы сообщения электронной почты.	GET`../me/messages?$search="subject:has"&$select=subject`
to	Поле Кому в сообщении электронной почты, где указан SMTP-адрес, отображаемое имя или псевдоним.	GET`.../me/messages?$search="to:randiw"&$select=subject,toRecipients`

Дополнительные сведения о свойствах электронной почты с возможностью поиска, синтаксисе KQL, поддерживаемых операторах и советах по поиску см. в следующих статьях:

Использование $search в коллекциях пользователей

Вы можете применить к $search свойствам displayName и emailAddresses ресурса person . Запросы возвращают до 250 результатов по умолчанию.

Следующий запрос выполняет поиск "Irene McGowan" в коллекции объектов person для вошедшего пользователя. Microsoft Graph выполняет поиск свойств displayName и 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\"";
});



mgc users people list --user-id {user-id} --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)

Ниже показан пример ответа.

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": "[email protected]",
           "imAddress": "sip:[email protected]",
           "scoredEmailAddresses": [
               {
                   "address": "[email protected]",
                   "relevanceScore": -16.446060612802224
               }
           ],
           "phones": [
               {
                   "type": "Business",
                   "number": "+1 412 555 0109"
               }
           ],
           "postalAddresses": [],
           "websites": [],
           "personType": {
               "class": "Person",
               "subclass": "OrganizationUser"
           }
       }
   ]
}

Дополнительные сведения об API People см. в этой статье.

Использование $search в коллекциях объектов каталога

Microsoft Entra ID ресурсы и их связи, производные от directoryObject, поддерживают $search параметр запроса только в расширенных запросах.

Примечание.

В настоящее время параметр запроса $search недоступен в клиентах Azure AD B2C.
Существует известная проблема с $search объектами каталога для значений, содержащих символ амперсанда (&).

Реализация поиска не поддерживает логику contains. Вместо этого используется подход к токенизации, который извлекает слова из значений свойств и выполняет поиск строк с помощью пробелов, чисел, различных регистров и символов, как показано в следующих примерах:

Пробелы: hello world =>hello, world
Разные регистры⁽¹⁾: HelloWorld или helloWORLD =>hello, world
Symbols⁽²⁾: hello.world =>hello, ., world, helloworld
Числа: hello123world =>hello, 123, world

⁽¹⁾ Для разных регистров маркеризация в настоящее время работает только при изменении регистра со строчных регистров на прописные. Например, HELLOworld является одним токеном: helloworld, и HelloWORld является двумя маркерами: hello, world.

Логика токенизации ⁽²⁾ также объединяет слова, разделенные только символами. Например, поиск и helloworldhello-worldhello.world.

После токенизации маркеры сопоставляются независимо от исходного регистра и в любом порядке. Например, displayName 李四(David Li) соответствует строкам поиска, таким как 李四(David Li), 李四, David, Li, David), (李四, . Li 李 Изменение алфавита (например, с латинской на кириллицу или китайский) не создает новый маркер. Например, displayName 蓝色group соответствует строкам 蓝色group поиска и 蓝色 , но не group. DisplayName group蓝色 соответствует строкам group蓝色 поиска и group , но не 蓝色 или 蓝.

Поиск с маркерами работает только в полях displayName и description . В можно использовать любое поле строкового типа, но по $searchумолчанию используются $filterstartswith поля, отличные от displayName и description.

Например:

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");
});



mgc groups list --search ""displayName:OneVideo" OR "mail:onevideo"" --consistency-level "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)

При этом выполняется поиск всех групп с отображаемыми именами, имеющими one маркеры и video , или почты, начинающиеся с onevideo.

Вы можете использовать $search вместе с $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");
});



mgc groups list --search ""displayName:OneVideo"" --filter "mailEnabled eq true" --consistency-level "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)

При этом выполняется поиск всех групп с поддержкой почты с отображаемыми именами, похожими на OneVideo. Результаты фильтруются на основе логического сочетания (AND) $filter и всего запроса в $search.

Синтаксис поиска соответствует следующим правилам:

Общий формат: $search="clause1" [AND | OR] "clauseX"
Количество предложений: поддерживается любое количество предложений. Также поддерживаются круглые скобки для приоритета.
Синтаксис предложения: "<property>:<text to search>"
- Необходимо указать имя свойства в предложении.
- Все предложение должно быть заключено в двойные кавычки. Если он содержит двойные кавычки или обратную косую черту, экранируйте ее с помощью обратной косой черты. Все остальные специальные символы должны быть закодированы в URL-адресе.
Логические операторы: AND операторы и OR должны находиться вне двойных кавычек и в верхнем регистре.
Поведение поиска. Поиск true поддерживается только для свойств displayName и description . Любое свойство, которое можно использовать в $filter, можно также использовать в $search. Свойства, отличные от displayName и description , по умолчанию — $filter с поведением startsWith, если поиск не поддерживается.
Токенизация. Как строковые входные данные, так $search и свойства, доступные для поиска, разделены на части по пробелам, различным регистрам и типам символов (числам и специальным символам).

В следующей таблице приведены некоторые примеры.

Класс объекта	Описание	Пример
Пользователь	Отображаемое имя пользователя из адресной книги.	GET`../users?$search="displayName:Guthr"`
Пользователь	Отображаемое имя пользователя или электронная почта из адресной книги.	GET`../users?$search="displayName:Guthr" OR "mail:Guthr"`
Группа	Отображаемое имя пользователя или описание из адресной книги.	GET`../groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive")`
Группа	Отображаемое имя адресной книги в группе с поддержкой почты.	GET`../groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"`

Поделиться через

Использование параметра запроса $search в API Microsoft Graph

Использование $search в коллекциях сообщений

Использование $search в коллекциях пользователей

Использование $search в коллекциях объектов каталога

Связанные материалы

Обратная связь

Дополнительные ресурсы