使用 Microsoft 搜索 API 查询数据

  • 项目

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

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

常见用例

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

本节根据在查询searchRequest 正文中设置的属性和参数列出查询方法的常见用例。

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

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

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

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

EntityType 访问项目所需的权限范围 Source 评论
缩写 Acronym.Read.All Microsoft 搜索 Microsoft 搜索组织中的首字母缩略词。
bookmark Bookmark.Read.All Microsoft 搜索 Microsoft 中的书签搜索组织中的书签。
chatMessage Chat.Read、Chat.ReadWrite、ChannelMessage.Read.All Teams Teams 消息。
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 的超类。
qna QnA.Read.All Microsoft 搜索 Microsoft 搜索组织中的问题和解答。
site Sites.Read.All、Sites.ReadWrite.All SharePoint SharePoint 中的网站。

页面搜索结果

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

  • 起始数量 - 一个整数，它表示从 0 开始的起始数，在页面上列出搜索结果。 默认值为 0。

  • 大小 - 一个整数，它表示要为页面返回的结果数。 默认值为 25 个结果。 最大值为 1000 个结果。

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

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

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

最佳实践：

  • 指定初始请求中的较小的首页。 例如，将起始数量指定为 0，将大小指定为 25。

  • 通过更新起始数量和大小属性来对后续页面进行分页。 可以在每个后续请求中增加页面大小。 下表显示了一个示例。

    页面 起始数量 大小
    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）和属性限制。 XRANK 运算符根据匹配表达式中的某些字词匹配项提升项的动态排名，而不会更改与查询匹配的项。 语法和命令取决于在同一查询请求主体中指向的实体类型（在 entityTypes 属性中）。

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

折叠搜索结果

collapseProperties 属性包含一组用于折叠响应正文中的条件、字段和限制大小。 使用 collapseProperties 只会影响召回率，而不会影响排名/排序操作。

查询方法允许通过在 参数上requests指定 collapseProperties 来自定义 collapse 属性，参数是 collapseProperty 对象的集合。 这允许指定一组一个或多个折叠属性。

请注意，以下实体类型当前支持折叠结果： driveItem、 listItem、 drive、 list、 site、 externalItem。

若要有效地使用 collapse 子句，应用它的属性必须可查询，并且可排序或可精简。 使用多级折叠时，请务必注意，在多级请求中指定的每个后续属性的限制大小应等于或小于前一个请求。 如果后续属性的限制大小超过前一个限制大小，服务器将响应错误 HTTP 400 Bad Request 。

有关更多折叠结果示例，请参阅 折叠搜索结果 。

排序搜索结果

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

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

查询方法允许通过在 参数上requests指定 sortProperties 来自定义搜索顺序，该参数是 sortProperty 对象的集合。 这可用于指定一个或多个可排序的属性列表和排序顺序。

请注意，目前仅支持以下 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中包含的匹配元素。 这是通过在后续 searchRequest 的 aggregationFilters 属性中传递回 aggregationsFilterToken 值来实现的。

聚合目前仅支持在以下 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 资源支持一次传递多个类型的实体。 下表列出了支持的组合。

    实体类型 acronym 书签 消息 chatMessage 驱动器 driveItem event externalItem list listItem 人 qna 网站
    acronym True True - - - - - - - - - True -
    书签 True True - - - - - - - - - True -
    chatMessage - - - True - - - - - - - - -
    驱动器 - - - - True True - True True True - - True
    driveItem - - - - True True - True True True - - True
    event - - - - - - True - - - - - -
    externalItem - - - - True True - True True True - - True
    list - - - - True True - True True True - - True
    listItem - - - - True True - True True True - - True
    消息 - - True - - - - - - - - - -
    人 - - - - - - - - - - True - -
    qna True True - - - - - - - - - True -
    网站 - - - - True True - True True True - - True

  • 仅当将 entityType 指定为 externalItem 时，定义要使用的连接的 contentSource 属性才适用。

  • 搜索 API 不支持 首字母缩写词、 书签、 消息、 chatMessage、 事件、 人员、 qna 或 externalItem 的自定义排序。

  • 搜索 API 不支持 首字母缩略词、 书签、 消息、 事件、 站点、 人员、 qna 或 驱动器的聚合。

  • 搜索 API 不支持 首字母缩写词、 书签、 消息、 chatMessage、 事件、 人员、 qna 或 externalItem 的 xrank。

  • 来宾搜索不支持搜索 首字母缩写词、 书签、 消息、 chatMessage、 事件、 人员、 qna 或 externalItem。

  • SharePoint 搜索中的自定义项（例如自定义搜索架构或结果源）可能会干扰 Microsoft 搜索 API 操作。

  • 搜索 API 不支持站点级 搜索架构。 使用租户级或默认 搜索架构。

相关内容