使用 Microsoft 搜索 API 查询数据
重要
Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。
可使用 Microsoft 搜索 API 来查询应用程序中的 Microsoft 365 数据。
搜索请求在登录用户的上下文中运行，并使用包含委派权限的访问令牌进行标识。
警告
Microsoft Search API 请求和响应中使用的资源已重命名或删除了属性或者已被弃用。 查找有关过时的更多详细信息。 相应更新任何早期应用中的搜索 API 查询。
常见用例
Microsoft Search API 提供了查询方法，可在 Microsoft Search 中搜索数据，在其请求正文中传递 searchRequest ，定义搜索的具体内容。
本节根据在查询searchRequest 正文中设置的属性和参数列出查询方法的常见用例。
代表用户运行搜索请求。 设定搜索结果范围，以强制执行应用到项目的任何访问控制。 例如，在文件的上下文中，将在搜索请求过程中评估对文件的权限。 用户在搜索中访问的项目数不能超过从具有相同权限和访问控制的相应 GET 操作获得的项数。
| 用例 | 要在查询请求正文中定义的属性 |
|---|---|
| 根据实体类型限定搜索范围 | entityTypes |
| 页面结果 | 起始数量和大小 |
| 获取最相关的电子邮件 | enableTopResults |
| 获取选定属性 | fields |
| 在查询条款中使用 KQL | 查询 |
| 折叠搜索结果 | collapseProperties |
| 排序搜索结果 | sortProperties |
| 使用聚合优化结果 | 聚合 |
| 使用连接器搜索导入的自定义类型 | contentSources |
| 请求拼写更正 | 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 | 列表项。 文件和文件夹也作为列表项返回; listItem 是 driveItem 的超级类。 |
| externalItem | ExternalItem.Read.All | Microsoft Graph 连接器 | 所有内容通过 Microsoft Graph 连接器 API 摄取。 |
| 人员 | People.Read | Exchange Online | 组织中的个人联系人、联系人或可寻址对象。 |
| 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 封邮件按相关性排序，剩余邮件按日期/时间排序。
获取选定属性
搜索实体类型，如 消息、事件、驱动、driveItem、列表、listItem、网站、externalItem 或 人员，可以在 字段 属性中包含特定的实体属性，以便在搜索结果中返回。 这类似于使用 OData 系统查询选项，REST 请求中的 $select。 搜索 API 在技术上不支持这些查询选项，因为行为在 POST 正文中表示。
对于所有这些实体类型，指定 fields 属性可减少响应中返回的属性数，从而通过网络优化负载。
listItem、driveItem 和 externalItem 实体是唯一受支持的实体，这些实体允许在架构中配置扩展的可检索字段。 无法使用搜索 API 从所有其他实体检索扩展属性。 例如，如果在搜索架构中为 externalItem 创建了可检索字段，或者 listItem 或 driveItem 上有可检索的自定义列，则可以从搜索中检索这些属性。 若要检索文件上的扩展属性，请在请求中指定 listItem 或 driveItem 类型。
如果请求中指定的字段不在架构中，或者未标记为可检索，则响应中不会返回这些 字段 。 请求中的无效字段将忽略静默。
如果未在请求中指定任何 字段 ，将获得所有类型的默认属性集。 对于扩展属性，当请求中未传递任何字段时，listItem、driveItem 和 externalItem 的行为有所不同：
- listItem 不会返回任何自定义字段。
- driveItem 将返回具有空字段的内部 listItem。
- externalItem 将返回该特定连接的 Microsoft Graph 连接器架构中标记有 retrievable 属性的所有字段。
关键字查询语言 (KQL) 支持
在实际搜索查询字符串（查询请求正文的查询属性）中的 KQL 语法中，指定自由文本关键字、运算符（例如 AND、OR）和属性限制。
XRANK 运算符根据匹配表达式中的某些字词匹配项提升项的动态排名，而不会更改与查询匹配的项。 语法和命令取决于在同一查询请求主体中指向的实体类型（在 entityTypes 属性中）。
可搜索的属性各不相同，具体取决于实体类型。 有关详细信息，请参阅：
折叠搜索结果
collapseProperties 属性包含一组条件、字段和限制大小，这些条件、字段和限制大小用于在响应正文中折叠结果。 使用 collapseProperties 只会影响召回率，而不会影响排名/排序。
查询方法允许通过在 参数上requests指定 collapseProperties 来自定义 collapse 属性，参数是 collapseProperty 对象的集合。 这允许指定一组一个或多个折叠属性。
以下实体类型当前支持折叠结果： driveItem、 listItem、 drive、 list、 site、 externalItem。
应用折叠子句的属性需要可查询且可排序或可精简。 对于多级折叠，在多级请求中指定的每个后续属性限制大小应小于或等于上一个;否则，响应将返回错误 HTTP 400 Bad Request 。
有关显示如何折叠结果的示例，请参阅 折叠搜索结果。
排序搜索结果
响应中的搜索结果按以下默认排序顺序排列：
- message 和 event 按日期进行排序。
- 所有 SharePoint、OneDrive 人员和连接器类型都按相关性排序。
查询方法允许通过在 参数上requests指定 sortProperties 来自定义搜索顺序，该参数是 sortProperty 对象的集合。 这可用于指定一个或多个可排序的属性列表和排序顺序。
目前仅在以下 SharePoint 和 OneDrive 类型上支持对结果进行排序： driveItem、 listItem、 list、 site。
应用 sort 子句的属性需要在 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 属性中获取拼写错误的拼写更正信息。
在 searchRequest 中，指定应应用于查询以进行拼写更正的 queryAlterationOptions。 有关 queryAlterationOptions 属性的详细信息，请参阅 searchAlterationOptions。
有关如何使用拼写更正的示例，请参见请求拼写更正。
搜索显示布局
借助搜索 API，可以使用 IT 管理员为每个连接器配置的显示布局或结果模板，呈现来自连接器的搜索结果。 结果模板为自适应卡片，是布局和数据的语义上有意义的组合。
若要在 searchResponse中获取结果模板，必须在 searchRequest 中 resultTemplateOptions定义的 enableResultTemplate 属性设置为 true。 响应包括每个搜索命中的 resultTemplateId，它映射到包含在响应中的 resultTemplates 中包含的显示布局之一。
相关示例，请参阅使用搜索显示布局。
来宾搜索
借助搜索 API，来宾用户可以在 SharePoint 或 OneDrive 中搜索已与他们共享的项目。 若要访问来宾用户列表，请转到 Microsoft 365 管理中心，然后在左侧导航栏中选择“ 用户”，然后选择“ 来宾用户”。
错误处理
搜索 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 搜索中的自定义项（例如自定义搜索架构或结果源）可能会干扰搜索 API 操作Microsoft。
架构更改否决警告
自 2023 年 8 月 31 日起，Microsoft Graph 命名空间中的 externalItem 资源的 beta 版本将被弃用。 今后，请使用 Microsoft.Graph.ExternalConnectors 命名空间中的资源版本。 请确保在指定日期之前更新任何命名空间依赖项。 或者，请考虑转换到 v1.0 版本的 API。
在测试版中，已重命名或删除搜索请求和响应中使用的属性。 在大多数情况下，原始属性将被否决并被当前属性替换，如下表所列。
建议更新现有应用以使用当前属性和类型名称，并在响应中获取当前属性名称。 为了向后兼容，原始属性和类型在 2023 年 9 月 30 日之前可访问并正常运行，之后将删除它们。
| 资源 | 更改类型 | 原始属性 | 当前属性 |
|---|---|---|---|
| searchRequest | 重命名属性 | stored_fields | fields |
| searchQuery | 重命名属性 | query_string | queryString |
| searchQueryString | 弃用资源 | 不适用 | 不适用 |
| searchHit | 重命名属性 | _id | hitId |
| searchHit | 重命名属性 | _score | rank |
| searchHit | 删除属性 | _sortField | 不适用 |
| searchHit | 重命名属性 | _source | resource |
| searchHit | 重命名属性 | _summary | summary |
| entityTypes | 重命名枚举值 | unknownfuturevalue | unknownFutureValue |
相关内容
了解有关几个关键用例的详细信息：
在 Graph 浏览器 中浏览搜索 API。