使用 Microsoft 搜索 API 查询数据

项目
06/18/2022

可使用 Microsoft 搜索 API 来查询应用程序中的 Microsoft 365 数据。

搜索请求在登录用户的上下文中运行，并使用包含委派权限的访问令牌进行标识。

常见用例

Microsoft Search API 提供了查询方法，可在 Microsoft Search 中搜索数据，在其请求正文中传递 searchRequest ，定义搜索的具体内容。

本部分列出了查询方法的常见用例，具体取决于在查询 searchRequest正文中设置的属性和参数。

代表用户运行搜索请求。设定搜索结果范围，以强制执行应用到项目的任何访问控制。例如，在文件的上下文中，将在搜索请求过程中评估对文件的权限。在搜索中，用户无法访问更多的项目，但可以从具有相同权限和访问控制的相应 GET 操作中获得这些项目。

用例	要在查询请求正文中定义的属性
根据实体类型限定搜索范围	entityTypes
页面结果	起始数量和大小
获取最相关的电子邮件	enableTopResults
获取选定属性	fields
在查询条款中使用 KQL	查询
排序搜索结果	sort
使用聚合优化结果	聚合
请求拼写更正	queryAlterationOptions
搜索显示布局（预览版）	resultTemplateOptions

根据实体类型限定搜索范围

使用查询请求有效负载中的 entityTypes 属性定义搜索请求的范围。下表介绍了可用于查询的类型以及访问数据所支持的权限。

EntityType	访问项目所需的权限范围	Source	评论
message	Mail.Read、Mail.ReadWrite	Exchange Online	电子邮件。
event	Calendars.Read、Calendars.ReadWrite	Exchange Online	日历事件。
drive	Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	SharePoint	文档库。
driveItem	Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	SharePoint 和 OneDrive	文件、文件夹、页面和新闻。
列表	Sites.Read.All、Sites.ReadWrite.All	SharePoint 和 OneDrive	列表。请注意，文档库也作为列表返回。
listItem	Sites.Read.All、Sites.ReadWrite.All	SharePoint 和 OneDrive	列表项。请注意，文件和文件夹也作为列表项返回；driveItem 是 driveItem 的超类。
网站	Sites.Read.All、Sites.ReadWrite.All	SharePoint	SharePoint 中的网站。

页面搜索结果

通过在查询请求正文中指定以下两个属性来控制搜索结果的分页：

起始数量 - 一个整数，它表示从 0 开始的起始数，在页面上列出搜索结果。默认值为 0。
大小 - 一个整数，它表示要为页面返回的结果数。默认值为 25 个结果。最大值为 1000 个结果。

如果你正在搜索 event 或 message 实体，则注意以下限制：

起始数量 在第一个页面请求中必须从零开始，否则请求将导致出现 HTTP 400 Bad request。
每页的消息和事件的最大结果数（大小）为 25。

SharePoint 或 OneDrive 项没有上限。合理的页面大小是 200。较大的页面大小通常会导致更高的延迟。

最佳实践：

指定初始请求中的较小的首页。例如，将 起始数量 指定为 0，将大小指定为 25。
通过更新 起始数量 和大小属性来对后续页面进行分页。可以在每个后续请求中增加页面大小。下表显示了一个示例。

页面起始数量大小

1 0 25

2 25 50

3 75 75

4 150 100

页面	起始数量	大小
1	0	25
2	25	50
3	75	75
4	150	100

获取最相关的电子邮件

搜索 message 实体时，将 enableTopResults 指定为 true 返回邮件的混合列表：响应中的前 3 封邮件按相关性排序，剩余邮件按日期/时间排序。

获取选定属性

搜索实体类型，如 message、event、drive、driveItem、list、listItem、site、externalItem，可以在 fields 属性中包含特定的实体属性，以便在搜索结果中返回。这类似于使用 OData 系统查询选项，REST 请求中的 $select。搜索 API 技术上不支持这些查询选项，因为会在文章正文中表达该行为。

对于所有这些实体类型，指定 fields 属性可减少响应中返回的属性数，从而通过网络优化负载。

listItem 和 externalItem 实体是唯一受支持的实体，可用于获取架构中配置的扩展可检索字段。无法使用搜索 API 从所有其他实体检索扩展属性。例如，如果在搜索架构中创建了 externalItem 的可检索字段，或者在 listItem 上有可检索自定义列，则可以从搜索中检索这些属性。若要检索文件的扩展属性，请在请求中指定 listItem 类型。

如果请求中指定的字段在架构中不存在，或者未标记为可检索，则在响应中将不会返回这些字段。请求中的无效字段将忽略静默。

如果你在请求中未指定任何字段，则将获得所有类型的默认属性集。对于扩展属性，在请求中未传递任何字段时，listItem 和 externalItem 的行为不同：

listItem 不会返回任何自定义字段。
externalItem 将返回该特定连接的 Microsoft Graph 连接器架构中标记有 retrievable 属性的所有字段。

关键字查询语言 (KQL) 支持

在实际搜索查询字符串（查询请求正文的查询属性）中的 KQL 语法中，指定自由文本关键字、运算符（例如 AND、OR）和属性限制。语法和命令取决于在同一查询请求主体中指向的实体类型（在 entityTypes 属性中）。

可搜索的属性各不相同，具体取决于实体类型。有关详细信息，请参阅：

排序搜索结果

响应中的搜索结果按以下默认排序顺序排列：

message 和 event 按日期进行排序。
所有 SharePoint、OneDrive 人员和连接器类型都按相关性排序。

query 方法可通过在 requests 参数中指定 sortProperties 来自定义搜索顺序，后者是 searchRequest 对象的集合。这可用于指定一个或多个可排序的属性列表和排序顺序。

请注意，目前仅支持以下 SharePoint 和 OneDrive 类型的排序结果：driveItem、listItem、list、site。

应用排序子句的属性需要在 SharePoint 搜索架构中可排序。如果请求中指定的属性不可排序或不存在，则响应将返回错误， HTTP 400 Bad Request。请注意，不能指定按使用 sortProperty 的相关性对文档进行排序。

指定 sortProperty 对象的名称时，可使用 Microsoft Graph 类型的属性名称（例如 driveItem），或搜索索引中托管属性的名称。

有关演示如何对结果进行排序的示例，请参阅对搜索结果进行排序。

使用聚合优化结果

聚合（SharePoint 中也称为精简程序）是增强搜索体验的一种常见的方式。除结果外，还提供有关匹配的搜索结果集的一些级别的聚合信息。例如，你可以提供与查询匹配的文档最多作者和表示的文件类型等信息。

在 searchRequest中，指定除了搜索结果以外应返回的聚合。每个聚合的说明在 aggregationOption 中定义，其指定要在其中计算聚合的属性，以及在响应中需要返回的 searchBucket 数目。

应用排序子句的属性需要在 SharePoint 搜索架构中可排序。如果指定的属性不可精简或不存在，则响应将返回 HTTP 400 Bad Request。

返回包含 searchBucket 对象的集合的响应后，可将搜索请求精确到 searchBucket中包含的匹配元素。为实现此操作，可将 aggregationFilters 属性中的 aggregationsFilterToken 值返回到后续 searchRequest中。

聚合目前仅支持在以下 SharePoint 和 OneDrive 类型上的任何可细化属性：driveItem、listItem、列表、网站以及在Microsoft Graph 连接器上的 externalItem。

请参阅优化搜索结果，以了解显示如何使用聚合增强和缩小搜索结果的示例。

请求拼写更正

拼写更正是处理用户查询中的拼写错误和匹配内容中正确单词之间差异的常用方法。在原始用户查询中检测到拼写错误时，可以获得原始用户查询或更正的备用查询的搜索结果。还可以在 searchresponse 的 queryAlterationResponse 属性中获取拼写错误的拼写更正信息。

在 Query 方法的请求正文中，指定应当应用于查询以进行拼写更正的 queryAlterationOptions。在 searchRequest中定义了 queryAlterationOptions 的说明。

有关如何使用拼写更正的示例，请参见请求拼写更正。

搜索显示布局

借助搜索 API，可以通过使用由 IT 管理员为每个连接器配置的显示布局或结果模板来呈现来自连接器的搜索结果。结果模板为自适应卡片，是布局和数据的语义上有意义的组合。

要在 searchresponse 中获取结果模板，必须将在 searchRequest 中 resultTemplateOptions 中定义的 enableResultTemplate 属性设置为 true。响应包括每个 searchHit 的 resultTemplateId，它映射到包含在作为响应一部分的 resultTemplates 字典中的显示布局之一。

有关演示如何呈现搜索结果的示例，请参阅使用搜索显示布局。

错误处理

搜索 API 将返回由 OData 错误对象定义所定义的错误响应，其中每个是包含代码和消息的 JSON 对象。

已知限制

搜索 API 存在以下限制：

定义查询方法，以允许一次传递一个或多个 searchRequest 实例的集合。但是，该服务当前仅支持一次传递一个 searchRequest。
searchRequest 资源支持一次传递多个类型的实体。但是，目前仅支持 SharePoint 和 OneDrive entityTypes 的组合为：driveItem、drive、site、list、listItem。当前不支持任何涉及 message、event、Sharepoint 和 OneDrive 类型或 externalItem 的组合。
仅当将 entityType 指定为 externalItem 时，定义要使用的连接的 contentSource 属性才适用。
搜索 API 不支持 message、event 或 externalItem 的自定义排序。
搜索 API 不支持 message、event、site 或 drive 的聚合。
SharePoint 搜索中的自定义设置（如自定义搜索架构或结果源）可能会干扰 Microsoft 搜索 API 的操作。