除了其他 OData 查询参数,Microsoft Graph 还支持$search查询参数,以便限制请求的结果来匹配搜索条件。
对$search查询参数的支持因实体而异,某些实体(例如派生自 directoryObject的 Microsoft Azure Active Directory 资源)仅支持高级查询中的$search。
Note:
$search查询参数当前在 Azure AD B2C 租户中不可用。
对 message 集合使用 $search
可根据特定邮件属性值搜索邮件。 搜索结果按邮件发送日期和时间进行排序。 $search请求最多返回 1000 个结果。
如果确实要搜索邮件,且仅指定值,而未指定特定邮件属性,搜索依据为默认搜索属性 from、subject 和 body。
下面的示例返回登录用户收件箱中三个默认搜索属性中有任意一个包含“pizza”的所有邮件:
GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"
也可以指定下表中的邮件属性名来搜索邮件,这些属性名可由关键字查询语言 (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 |
| 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 | 电子邮件的 from、to、cc 和 bcc 字段,可指定为 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 | 电子邮件的 to 字段,可指定为 SMTP 地址、显示名称或别名。 | GET.../me/messages?$search="to:randiw"&$select=subject,toRecipients |
若要详细了解 可搜索的电子邮件属性、KQL 语法、受支持的运算符和搜索技巧,请参阅以下文章:
对 person 集合使用 $search
可以使用 Microsoft Graph People API 检索与用户最相关的人员。 相关性由用户的通信和协作模式及业务关系决定。 People API 支持 $search 查询参数。 $search 请求最多可返回 250 个结果。
人员搜索就是按 person 资源的 displayName 和 emailAddress 属性进行搜索。
以下请求在已登录用户的 人员 集合中的每个人员的 displayName 和 emailAddress 属性中,为名为“Irene McGowen”的人员执行搜索。 由于一个名为“Irene McGowan”的人员与登录用户相关,因此返回了“Irene McGowan”的信息。
GET https://graph.microsoft.com/v1.0/me/people/?$search="Irene McGowen"
以下示例显示了相应的响应。
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.onmicrosoft.com",
"imAddress": "sip:irenem@contoso.onmicrosoft.com",
"scoredEmailAddresses": [
{
"address": "irenem@contoso.onmicrosoft.com",
"relevanceScore": -16.446060612802224
}
],
"phones": [
{
"type": "Business",
"number": "+1 412 555 0109"
}
],
"postalAddresses": [],
"websites": [],
"personType": {
"class": "Person",
"subclass": "OrganizationUser"
}
}
]
}
若要了解有关 People API 的详细信息,请参阅获取相关人员的信息。
在目录对象集合上使用 $search
派生自 directoryObject 的 Azure AD 资源及其关系仅在高级查询中支持 $search 查询参数。 搜索执行 不 支持contains 。 相反,它使用词汇点化方法,该方法的工作方式是使用空格、数字、不同的大小写和符号从属性值和搜索字符串中提取单词,如以下示例所示:
- 空格:
hello world=>hello、world - 不同的大小写⁽¹⁾:
HelloWorld或helloWORLD=>hello、world - 符号⁽⁾:
hello.world=>hello、.、world,helloworld - 数字:
hello123world=>hello、123、world
⁽¹⁾ 目前,标记化仅在大小写从小写转换为大写时才有效,因此 HELLOworld 被视为一个标记:helloworld,HelloWORld 是两个标记:hello、world。
⁽²⁾ 标记化逻辑还会合并仅由符号分隔的单词;例如,搜索 helloworld 将找到 hello-world 和 hello.world。
Note:
- 标记化后,标记将独立于原始大小写进行匹配,并且将以任何顺序匹配。 例如,displayName
李四(David Li)将匹配搜索字符串,例如李四(David Li)、李四、David、Li、David)、(李四、Li 李。- 标记化搜索仅适用于 displayName 和 description 字段。 字符串类型的任何字段都可以放入
$search; displayName 和 说明之外的字段 默认为$filterstartswith行为。
例如:
HTTP
GET https://graph.microsoft.com/v1.0/groups/?$search="displayName:OneVideo OR mail:onevideo"
这将查找具有 one 和 video 令牌的所有显示名称的组,或以 onevideo 开头的邮件。
$search 可与 $filter 一起使用:
HTTP
GET https://graph.microsoft.com/v1.0/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"
这将查找显示名称类似于“OneVideo”的所有启用邮件的组。
结果是根据逻辑结合("AND")和$filter整个查询$search来限制。
搜索的语法遵循以下规则:
- 通用格式:$search="clause1" [AND | OR] "[clauseX]".
- 支持任何子句。 支持适用于优先级的括号。
- 每个子句的语法是:"<property>:<text to search>"。
- 必须在子句中指定属性名称。 可以在中使用的任何属性
$filter也可以在内使用$search。 根据属性的不同,如果属性不支持搜索,则搜索行为是“search”或“startWith”。 - 必须在双引号内声明整个子句。 如果它包含双引号或反斜杠,则应使用反斜杠进行转义。 必须对所有其他特殊字符进行 URL 编码。
- 逻辑
AND和OR运算符必须放在双引号之外,并且必须为大写。
下表显示了一些示例。
| 对象类 | 说明 | 示例 |
|---|---|---|
| 用户 | 通讯簿显示用户的名称。 | |
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" |
你在 $search 中提供的字符串输入以及可搜索属性都按空格、不同的大小写和字符类型(数字和特殊字符)划分为多个部分。
另请参阅
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 mumbi-o)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
