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

Статья
08/22/2023

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

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

Примечание.

В настоящее время параметр запроса $search недоступен в клиентах Azure AD B2C.

Существует известная проблема, связанная с кодировкой символов амперсанда (&) в $search выражениях в конечной точке v1.0 . Дополнительные сведения о проблеме и рекомендуемое решение см. в статье Известная проблема: $search для объектов каталога завершается сбоем для символа закодированного амперсанда (&).

Использование параметра $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\"";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --search ""pizza""



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestSearch := "\"pizza\""

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

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"'


from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		search = "\"pizza\"",
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
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:samanthab@contoso.com"&$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`
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	Такие поля сообщения электронной почты, как Кому, Копия и Скрытая копия, где указан 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

API People Microsoft Graph можно использовать для получения сведений о наиболее релевантных для пользователя людях. Релевантность определяется шаблонами взаимодействия и совместной работы пользователя, а также бизнес-отношениями. API People поддерживает параметр запроса $search. Запрос $search возвращает до 250 результатов.

Поиск людей выполняется по свойствам displayName и emailAddress ресурса person.

По приведенному ниже запросу выполняется поиск человека с именем Irene McGowen в свойствах displayName и emailAddress всех людей из коллекции people вошедшего пользователя. Так как человек с именем Irene McGowan является релевантным для вошедшего пользователя, возвращается информация о нем.

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


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users people list --user-id {user-id} --search ""Irene McGowen""



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestSearch := "\"Irene McGowen\""

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

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"'


from msgraph import GraphServiceClient
from msgraph.generated.users.item.people.people_request_builder import PeopleRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = PeopleRequestBuilder.PeopleRequestBuilderGetQueryParameters(
		search = "\"Irene McGowen\"",
)

request_configuration = PeopleRequestBuilder.PeopleRequestBuilderGetRequestConfiguration(
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": "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"
           }
       }
   ]
}

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

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

Примечание.

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

Microsoft Entra ID ресурсы и их связи, производные от directoryObject, поддерживают $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");
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups list --search ""displayName:OneVideo" OR "mail:onevideo"" --consistency-level "eventual"



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
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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,
}

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


from msgraph import GraphServiceClient
from msgraph.generated.groups.groups_request_builder import GroupsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
		search = "\"displayName:OneVideo\" OR \"mail:onevideo\"",
)

request_configuration = GroupsRequestBuilder.GroupsRequestBuilderGetRequestConfiguration(
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");
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups list --search ""displayName:OneVideo"" --filter "mailEnabled eq true" --consistency-level "eventual"



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
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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,
}

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


from msgraph import GraphServiceClient
from msgraph.generated.groups.groups_request_builder import GroupsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
		filter = "mailEnabled eq true",
		search = "\"displayName:OneVideo\"",
)

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


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

В результате будут выводиться все группы с включенной поддержкой почты с именами типа "OneVideo". Результаты ограничены на основе логического соединения $filter ("И") и всего запроса в $search.

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

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

В таблице ниже приведено несколько примеров.

Класс объекта	Описание	Пример
Пользователь	Отображаемое имя пользователя из адресной книги.	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

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

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

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

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

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

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

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

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

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

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

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

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

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

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