升级到 Azure AI 搜索服务中最新的 REST API

项目
12/29/2023

根据本文说明将数据平面调用迁移到较新稳定版本的搜索 REST API。

2023-11-01 是最新的稳定版本。此版本通常提供矢量搜索支持。

注意

API 参考文档现已进行版本控制。若要获取正确的内容，请打开引用页，然后应用目录上方的版本特定筛选器。

如何升级

Azure AI 搜索努力实现向后兼容性。若要升级并继续使用现有功能，通常只需更改 API 版本号。相反，要求更改代码的情况包括：

当 API 响应中返回无法识别的属性时，代码失效。最佳做法是，应用程序应忽略它无法理解的属性。
代码仍坚持 API 请求，并尝试将其重新发送到新 API 版本。例如，如果应用程序仍存留从搜索 API 返回的延续标记（有关详细信息，请查找搜索 API 参考中的 @search.nextPageParameters）。
你的代码引用的 API 版本早于 2019-05-06，并且受该版本中一项或多项中断性变更的影响。升级到 2019-05-06 部分提供了更多详细信息。

如果上述任一情况适用于你，请更改代码以维护现有功能。否则，尽管你可能需要开始使用新版本中添加的功能，也无需进行任何更改。

升级到 2020-06-30

在此版本中，有一个中断性变更和几个行为差异。正式版功能包括：

知识存储，通过技能组创建的扩充内容的持久存储，创建的目的是通过其他应用程序进行下游分析和处理。 Azure 存储中提供了知识存储功能，你可以预配该功能，它会提供技能组的关系详情。有了此功能，索引器驱动的 AI 扩充管道除了可以填充搜索索引外，还可以填充知识存储。如果你使用了此功能的预览版，则它相当于正式版。唯一需要的代码更改是修改 api-version。

重大更改

如果代码包含以下功能，针对早期 API 版本编写的现有代码会在遇到 api-version=2020-06-30 及更高版本时中断运行：

筛选器表达式中的任何 Edm.Date 文本（由年、月、日组成的日期，例如 2020-12-12）必须遵循 Edm.DateTimeOffset 格式：2020-12-12T00:00:00Z。由于时区不同，需要进行此更改才能处理错误的或意外的查询结果。

行为更改

BM25 排名算法将以前的排名算法替换为更新的技术。 2019 年之后创建的服务会自动使用此算法。对于更早的服务，必须将参数设置为使用新算法。
在此版本中，NULL 值的排序结果发生了变化，如果排序是 asc，则 NULL 值首先出现；如果排序是 desc，则 NULL 值最后出现。如果你编写代码来处理 NULL 值的排序方式，请注意此更改。

升级到 2019-05-06

版本 2019-05-06 是 REST API 的上一个正式版。此 API 版本中正式可用的功能包括：

自动完成是一项自动提示功能，可以完成部分指定的字词输入。
复杂类型原生支持搜索索引中的结构化对象数据。
JsonLines 分析模式（Azure Blob 编制索引的一部分）可为每个 JSON 实体创建以换行符分隔的搜索文档。
AI 扩充将提供可以使用 Azure AI 服务的 AI 扩充引擎的索引编制功能。

重大变化

如果代码包含以下功能，针对早期 API 版本编写的现有代码将在遇到 api-version = 2019-05-06 及更高版本时中断运行：

Azure Cosmos DB 索引器 - 数据源现在是 `"type": "cosmosdb"`

如果使用 Azure Cosmos DB 索引器，必须将 "type": "documentdb" 更改为 "type": "cosmosdb"。

索引器执行结果错误不再提供状态

索引器执行的错误结构以前包含 status 元素。此元素已被删除，因为它并没有提供有用的信息。

索引器数据源 API 不再返回连接字符串

从 API 版本 2019-05-06 和 2019-05-06-Preview 开始，数据源 API 不再在任何 REST 操作的响应中返回连接字符串。在以前的 API 版本中，对于使用 POST 创建的数据源，Azure AI 搜索会返回 201，后跟 OData 响应，该响应包含纯文本格式的连接字符串。

“命名实体识别”认知技能现已停用

如果在代码中调用命名实体识别技能，调用会失败。替代的功能是实体识别技能 (V3)。按照已弃用的技能中的建议，迁移到支持的技能。

升级复杂类型

API 版本 2019-05-06 添加了对复杂类型的正式支持。如果你的代码在 2017-11-11-Preview 或 2016-09-01-Preview 中实现了以前关于复杂类型等效性的建议，那么从 2019-05-06 版本开始，你需要注意一些新的和更改的限制：

每个索引的子字段深度和复杂集合数目限制已降低。如果使用预览版 API 创建了超出这些限制的索引，尝试使用 API 版本 2019-05-06 更新或重新创建这些索引将会失败。如果发现自己处于这种情况，则需要重新设计架构，使其不会超出新的限制，然后重新生成索引。
从 API 版本 2019-05-06 开始，对每个文档的复杂集合元素数目施加了新的限制。如果使用预览版 API 创建了文档超出这些限制的索引，尝试使用 API 版本 2019-05-06 重建该数据的索引将会失败。如果遇发现自己处于这种情况，需要在重建数据的索引之前，减少每个文档的复杂集合元素数目。

有关详细信息，请参阅 Azure AI 搜索的服务限制。

如何升级旧的复杂类型结构

如果代码使用在早期 API 预览版中创建的复杂类型，则你可能正在使用如下所示的索引定义格式：

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

API 版本 2017-11-11-Preview 中引入了一种更新的用于定义索引字段的树形格式。在新格式中，每个复杂字段提供一个字段集合，可在该集合中定义该字段的子字段。在 API 版本 2019-05-06 中，此新格式是以独占方式使用的，使用旧格式尝试创建或更新索引将会失败。如果索引是使用旧格式创建的，则你需要使用 API 版本 2017-11-11-Preview 将其更新到新格式，然后才能使用 API 版本 2019-05-06 来管理它们。

可以执行以下步骤使用 API 版本 2017-11-11-Preview 将“平面”索引更新为新格式：

执行 GET 请求以检索索引。如果该索引已采用新格式，则无需执行后续操作。
将索引从“平面”格式转换为新格式。必须为此任务编写代码，因为在撰写本文时尚未有示例代码可用。
执行 PUT 请求，将索引更新为新格式。避免更改索引的任何其他详细信息（例如字段的可搜索性/可筛选性），因为更新索引 API 不允许那些影响现有索引的物理表达式的更改。

注意

无法在 Azure 门户中管理使用旧的“平面”格式创建的索引。请尽早将索引的“平面”表示形式升级到“树形”表示形式。

后续步骤

查看搜索 REST API 参考文档。如果遇到问题，请通过 Stack Overflow 向我们寻求帮助，或联系支持人员。

搜索服务 REST API 参考