在 Microsoft Graph API 中使用 $search 查询参数

2025-07-24

$search查询参数是 Microsoft Graph 中功能强大的筛选机制，可用于通过匹配搜索条件查找特定数据。

此查询参数的支持因实体而异。某些实体（如派生自 directoryObject 的资源Microsoft Entra）仅在高级查询中支持$search。

本文介绍如何对三种关键资源类型有效地使用$search查询参数：邮件、人员和 Microsoft Entra ID对象 (目录对象) 。了解每种资源类型的特定语法要求、支持的属性和搜索行为。

对消息集合使用$search

可以根据特定的邮件属性搜索邮件。搜索结果按邮件发送的日期和时间排序。请求 $search 最多返回 1,000 个结果。

在不指定邮件属性的情况下搜索邮件时，搜索目标为以下默认属性： 发件人、主题和正文。

下面的示例返回登录用户收件箱中三个默认搜索属性中有任意一个包含“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\"";
});



// 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) 语法识别的消息属性名称来搜索消息。这些属性名对应于 Microsoft Graph message 实体中定义的属性。 Outlook 和其他 Microsoft 365 应用程序（如 SharePoint）支持 KQL 语法，该语法为其数据存储提供通用的发现域。

可搜索的电子邮件属性	说明	示例
attachment	附加到电子邮件的文件的名称。	GET`../me/messages?$search="attachment:api-catalog.md"`
bcc	电子邮件的 bcc 字段，可指定为 SMTP 地址、显示名称或别名。	GET`../me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients`
body	电子邮件正文。	GET`../me/messages?$search="body:excitement"`
cc	电子邮件的 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`、`notesjournalsimpostsrssfeedsmeetings`、 `tasks`或。`voicemail`	GET`../me/messages?$search="kind:voicemail"`
participants	电子邮件的 from、to、cc 和 bcc 字段，可指定为 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	电子邮件的 to 字段，可指定为 SMTP 地址、显示名称或别名。	GET`.../me/messages?$search="to:randiw"&$select=subject,toRecipients`

有关可搜索电子邮件属性、KQL 语法、支持的运算符和搜索提示的详细信息，请参阅以下文章：

对人员集合使用$search

可以应用于$search人员资源的 displayName 和 emailAddresses 属性。默认情况下，请求最多返回 250 个结果。

以下请求在已登录用户的 person 对象集合中搜索“Irene McGowan”。 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\"";
});



// 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": "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"
           }
       }
   ]
}

若要了解有关 People API 的详细信息，请参阅获取相关人员的信息。

对目录对象集合使用$search

Microsoft Entra ID资源及其派生自 directoryObject 的关系仅在高级查询中支持$search查询参数。

注意

$search查询参数当前在 Azure AD B2C 租户中不可用。
对于包含和号 (&) 符号的值，在目录对象上存在已知问题$search。

搜索实现不支持“包含”逻辑。相反，它使用标记化方法，该方法使用空格、数字、不同大小写和符号从属性值中提取单词，并使用不同的大小写和符号搜索字符串，如以下示例所示：

空格： hello world =>hello， world
不同大小写⁽¹⁾： HelloWorld 或 helloWORLD =>hello， world
Symbols⁽²⁾： hello.world =>hello， .， world， helloworld
数字： hello123world =>hello、 123、 world

⁽¹⁾ 对于不同的大小写，目前仅当大小写从小写更改为大写时，标记化才有效。例如， HELLOworld 是单个标记： helloworld，是 HelloWORld 两个标记： hello、 world。

⁽²⁾ 标记化逻辑还合并了仅用符号分隔的单词。例如，搜索 helloworld finds hello-world 和 hello.world。

标记化后，无论原始大小写和顺序如何，标记都会匹配。例如，displayName 李四(David Li) 匹配搜索字符串，如 李四(David Li)、、李四、DavidLi、David)(李四、、 Li 李。字母 (（如从拉丁语更改为西里尔文或中文) ）不会创建新令牌。例如， displayName 蓝色group 与和 蓝色 搜索字符串匹配蓝色group，但与匹配。group DisplayName group蓝色 与和 group 搜索字符串匹配group蓝色，但与或 蓝匹配蓝色。

标记化搜索仅适用于 displayName 和 description 字段。任何字符串类型字段都可以在中使用 $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");
});



// 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的邮件。

可以与 $filter一$search起使用：

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)

这会搜索显示名称类似于“OneVideo”的所有已启用邮件的组。根据和中$search整个查询 (AND) $filter 的逻辑关联筛选结果。

搜索语法遵循以下规则：

常规格式：$search=“clause1” [AND |OR] “clauseX”
子句数：支持任意数量的子句。还支持使用括号表示优先级。
子句语法：“<property>：<text to search>”
- 必须在子句中指定属性名称。
- 整个子句必须用双引号引起来。如果它包含双引号或反斜杠，请使用反斜杠对其进行转义。所有其他特殊字符都必须经过 URL 编码。
逻辑运算符： AND 和 OR 运算符必须位于双引号外，且为大写。
搜索行为：仅 displayName 和 description 属性支持真实搜索。可以在中使用的任何属性$filter也可以在内使用 $search。如果不支持搜索，则 displayName 和 description 以外的属性默认 $filter 为具有“startsWith”行为。
标记化：在中 $search 提供的字符串输入和可搜索属性按空格、不同的大小写和字符类型 (数字和特殊字符) 拆分为部分。

下表显示了一些示例：

对象类	说明	示例
用户	通讯簿显示用户的名称。	GET`../users?$search="displayName:Guthr"`
用户	通讯簿显示用户的名称或邮件。	GET`../users?$search="displayName:Guthr" OR "mail:Guthr"`
Group	通讯簿显群组的名称或说明。	GET`../groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive")`
Group	通讯簿在启用邮件组上显示名称。	GET`../groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"`

通过

在 Microsoft Graph API 中使用 $search 查询参数

对消息集合使用$search

对人员集合使用$search

对目录对象集合使用$search

相关内容

反馈

其他资源