通过

使用 $search 查询参数

  • 项目

除了其他 OData 查询参数，Microsoft Graph 还支持$search查询参数，以便限制请求的结果来匹配搜索条件。

对$search查询参数的支持因实体而异，有些参数（例如派生自 directoryObject 的Microsoft Entra资源），仅在高级查询中支持$search。 本文概述了以下三个main领域的搜索语法和行为：

对 message 集合使用 $search

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

如果确实要搜索邮件，且仅指定值，而未指定特定邮件属性，搜索依据为默认搜索属性 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

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 电子邮件的 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 语法、受支持的运算符和搜索技巧，请参阅以下文章：

对 person 集合使用 $search

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

以下请求在已登录用户的集合 人员 对象中搜索“Irene McGowan”。 Microsoft Graph 将搜索范围限定为 displayName 或 emailAddresses 属性。

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.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
  • 不同大小写⁽1⁾： HelloWorld 或 helloWORLD =>hello， world
  • Symbols⁽2⁾： hello.world =>hello， .， world， helloworld
  • 数字： hello123world =>hello、 123、 world

⁽1⁾对于不同的大小写，标记化目前仅在大小写从小写更改为大写时有效，因此 HELLOworld 被视为单个标记： helloworld，并且 HelloWORld 是两个标记： hello、 world。

⁽2⁾ 标记化逻辑还合并仅用符号分隔的单词;例如，搜索 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

这将查找显示名称具有 one 和 video 令牌的所有组，或以 开头 onevideo的邮件。

$search 可与 $filter 一起使用：

GET https://graph.microsoft.com/v1.0/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"
ConsistencyLevel: eventual

这将查找显示名称类似于“OneVideo”的所有启用邮件的组。 结果根据 逻辑关联 (“AND”) $filter 以及 中整个查询进行 $search限制。

搜索的语法遵循以下规则：

  • 泛型格式：$search=“clause1” [AND |OR] “\clauseX”。
  • 支持任何子句。 支持适用于优先级的括号。
  • 每个子句的语法为：“<property>：<text to search>”。
    • 必须在子句中指定属性名称。
    • 必须在双引号内声明整个子句。 如果它包含双引号或反斜杠，则应使用反斜杠进行转义。 必须对所有其他特殊字符进行 URL 编码。
  • 逻辑 AND 和 OR 运算符必须放在双引号之外，并且必须为大写。
  • 只有 displayName 和 description 属性支持 True 搜索;但 可以在 中使用的$filter任何属性也可以在 中使用$search。 根据属性，搜索行为为“search”或 $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"

相关内容