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

Статья
2024-07-18

В дополнение к другим параметрам запросов OData Microsoft Graph поддерживает параметр запроса $search для ограничения результатов запроса с помощью условия поиска.

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

Почтовые сообщения
API Люди
объекты Microsoft Entra ID или объекты каталога

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

Вы можете искать сообщения на основе значения в определенных свойствах сообщения. Результаты поиска сортируются по дате и времени отправки сообщения. Запрос $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. Синтаксис KQL поддерживается в Outlook и других приложениях Microsoft 365, например SharePoint. Благодаря этому возможно использование общего домена обнаружения для соответствующих хранилищ данных.

Свойство электронных писем, по которому можно выполнять поиск	Описание	Пример
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`, `posts`, `rssfeeds`, `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 в коллекциях person

Вы можете применить к $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.

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

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

Поддержка поиска с разметкой работает только в полях displayName и description. Любое поле типа String может быть помещено в $search; поля, отличные от displayName и description по умолчанию для $filterstartswith поведения.

Например:

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. В зависимости от свойства поведение поиска — "поиск" или $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

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

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

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

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

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

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