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

2025-08-25

使用本文将搜索服务 REST API和搜索管理 REST API迁移到较新版本，以进行数据平面和控制平面操作。

下面是 REST API 的最新版本：

定向操作	REST API	状态
数据平面	`2024-07-01`	稳定
数据平面	`2025-05-01-preview`	预览
控制面板	`2025-05-01`	稳定
控制面板	`2025-02-01-preview`	预览

升级说明侧重于代码更改，这些更改可让你完成以前版本的中断性变更，以便现有代码像之前那样运行，只是针对较新的 API 版本。代码按工作顺序运行后，你可以决定是否采用较新的功能。要了解有关新功能的详细信息，请参阅矢量代码示例和新增功能。

我们建议连续升级 API 版本，并处理每个版本，直到到达最新的版本。

2023-07-01-preview 是第一个用于矢量支持的 REST API。请勿使用此 API 版本。它现已弃用，应立即迁移到稳定或更新的预览版 REST API。

注意

REST API 参考文档现已进行版本控制。对于特定于版本的内容，请打开参考页，然后使用位于目录上方右侧的选择器选取版本。

何时升级

Azure AI 搜索将后向兼容性作为最后的手段。出现以下情况时，必须进行升级：

你的代码引用了已停用或不受支持的 API 版本，并且受到一项或多项中断性变更影响。如果代码面向 2023-07-10-preview（对于矢量）、2020-06-01-preview（对于语义排序器）以及 2019-05-06（对于过时的技能和解决方法），则必须解决中断性变更。
当 API 响应中返回无法识别的属性时，代码失效。最佳做法是，应用程序应忽略它无法理解的属性。
代码仍坚持 API 请求，并尝试将其重新发送到新 API 版本。例如，如果应用程序仍存留从搜索 API 返回的延续标记（有关详细信息，请查找@search.nextPageParameters中的）。

如何升级

如果要升级数据平面版本，请查看新 API 版本的发行说明。
将请求标头中指定的api-version参数更新为较新版本。

在直接调用 REST API 的应用程序代码中，搜索现有版本的所有实例，然后将其替换为新版本。有关构建 REST 调用的详细信息，请参阅快速入门：使用 REST 进行全文搜索。

如果使用 Azure SDK，则这些包面向特定版本的 REST API。包更新可能与 REST API 更新相吻合，但每个 SDK 都根据它自己的发布计划提供，它独立于 Azure AI 搜索 REST API 版本。检查 SDK 包的更改日志，以确定包版本是否面向最新的 REST API 版本。
如果要升级数据平面版本，请查看本文中记录的重大变更并实施解决方法。从代码使用的版本开始，解决每个较新的 API 版本的任何中断性变更，直到进入最新的稳定或预览版本。

中断性变更

以下重大更改适用于数据操作。

对读取连接信息的客户端代码的破坏性更改

自 2024 年 3 月 29 日起，适用于所有支持的 REST API：

GET Skillset、GET Index 和 GET Indexer 不再在响应中返回键或连接属性。如果下游代码从 GET 响应读取密钥或连接（敏感数据），则这是一项重大更改。
如果需要检索搜索服务的管理员或查询 API 密钥，请使用搜索管理 REST API。
如果需要检索另一个 Azure 资源的连接字符串（例如 Azure 存储或 Azure Cosmos DB），请使用该资源的 API 和发布的指南获取信息。

语义排名器的重大变动

语义排名器已正式发布。2023-11-01 以下是早期版本中的中断性变更：

在 2020-06-01-preview 之后的所有版本中：semanticConfiguration 取代 searchFields 作为指定使用哪些字段进行 L2 排名的机制。
对于所有 API 版本，2023 年 7 月 14 日对 Microsoft 托管语义模型的更新使语义排序器与语言无关，从而有效地停用了 queryLanguage 属性。代码中没有“中断性变更”，但该属性被忽略。

请参阅从预览版迁移，以将代码转换为使用 semanticConfiguration。

从 2023-07-01-preview 升级

请勿使用此 API 版本。它可实现与任何较新的 API 版本不兼容的矢量查询语法。

2023-07-01-preview 现已弃用，因此不应基于此版本编写新代码，也不应在任何情况下升级到此版本。本部分介绍从 2023-07-01-preview 到任何较新的 API 版本的迁移路径。

矢量索引的门户升级

Azure 门户支持 2023-07-01-preview 索引的一键式升级路径。它检测矢量字段，并提供迁移按钮。

迁移路径从 2023-07-01-preview 到 2024-05-01-preview。
更新仅限于矢量字段定义和矢量搜索算法配置。
更新是单向更新。升级将无法逆转。升级索引后，必须使用 2024-05-01-preview 或更高版本来查询索引。

没有用于升级矢量查询语法的门户迁移。有关查询语法更改，请参阅代码升级。

在选择“迁移”之前，请选择“编辑 JSON”以首先查看更新的架构。你应该会发现一个符合代码升级部分所述更改的模式。门户迁移仅处理具有一个矢量搜索算法配置的索引。它创建映射到 2023-07-01-preview 矢量搜索算法的默认配置文件。具有多个矢量搜索配置的索引需要手动迁移。

矢量索引和查询的代码升级

创建或更新索引（2023-07-01-preview）中引入了矢量搜索支持。

从 2023-07-01-preview 升级到任何较新的稳定版本或预览版需要：

重命名和重组索引中的矢量配置
重写矢量查询

使用本部分中的说明从 2023-07-01-preview 迁移矢量字段、配置和查询。

调用获取索引以检索现有定义。

修改矢量搜索配置。 2023-11-01 及更高版本引入了矢量配置文件的概念，将矢量相关的配置捆绑在一个名称下。较新版本还将 algorithmConfigurations 重命名为 algorithms。

将 algorithmConfigurations 重命名为 algorithms。这只是数组的重命名。内容是向后兼容的。这意味着可以使用现有的 HNSW 配置参数。
添加 profiles，为每个配置提供名称和算法配置。

迁移 (2023-07-01-preview) 前：

  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

迁移 (2023-11-01) 后：

  "vectorSearch": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }

修改矢量字段定义，将 vectorSearchConfiguration 替换为 vectorSearchProfile。请确保配置文件名称解析为新的矢量配置文件定义，而不是算法配置名称。其他矢量字段属性保持不变。例如，它们不能筛选、排序或分面，也不能使用分析器或规范化器或同义词映射。

(2023-07-01-preview) 之前：

  {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

(2023-11-01) 后:

  {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

调用创建或更新索引来发布更改。

修改搜索 POST 以更改查询语法。此 API 更改支持多态矢量查询类型。

将 vectors 重命名为 vectorQueries。
对于每个矢量查询，请添加 kind，将其设置为 vector。
对于每个矢量查询，请将 value 重命名为 vector。
（可选）如果使用vectorFilterMode，请添加。对于在 2023-10-01后创建的索引，默认值为预筛选。在该日期之前创建的索引仅支持后筛选，而不考虑筛选模式是如何设置的。

(2023-07-01-preview) 之前：

{
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}

(2023-11-01) 后:

{
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}

这些步骤完成 2023-11-01 稳定 API 版本或更新预览版 API 版本的迁移。

升级到 2020-06-30

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

知识存储，通过技能组创建的扩充内容的持久存储，创建的目的是通过其他应用程序进行下游分析和处理。知识存储是通过 Azure AI 搜索 REST API 创建的，但它驻留在 Azure 存储中。

中断性变更

如果针对早期 API 版本编写的代码包含以下功能，那么该代码在 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

此 API 版本中正式可用的功能包括：

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

中断性变更

如果针对早期 API 版本编写的代码包含以下功能，那么该代码在 2019-05-06 及更高版本上会中断：

Azure Cosmos DB 的 Type 属性。对于面向 Azure Cosmos DB for NoSQL API 数据源的索引器，请将 "type": "documentdb" 更改为 "type": "cosmosdb"。
如果索引器错误处理包括对 status 属性的引用，则应将其删除。我们从错误响应中删除了状态，因为它没有提供有用的信息。
响应中不再返回数据源连接字符串。从 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 参考

共用方式為

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

何时升级

如何升级

中断性变更

对读取连接信息的客户端代码的破坏性更改

语义排名器的重大变动

从 2023-07-01-preview 升级

矢量索引的门户升级

矢量索引和查询的代码升级

升级到 2020-06-30

中断性变更

行为更改

升级到 2019-05-06

中断性变更

升级复杂类型

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

后续步骤

其他資源