你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

(Azure AI 搜索 REST API) 更新索引

  • 项目

修改现有索引通常需要 删除并重新生成索引，但以下架构更改除外：

  • 向字段集合添加新字段

  • 将新创建的字段添加到 建议器

  • 添加或更改 计分配置文件

  • 添加或更改 加密密钥

  • 添加新 的自定义分析器

  • 更改 CORS 选项

  • 使用以下三种修改之一更改现有字段：

    • 更改 retrievable (值为 true 或 false)
    • 更改 searchAnalyzer 查询时使用的 ()
    • 添加或更改 synonymMaps 查询时使用的 ()

若要添加这些更新，请将索引名称放在请求 URI 上。 在请求正文中，包含完全指定的索引定义和修改。

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin key]

无法删除或更改现有字段和大多数字段属性，也不能将字段添加到建议器。 只能将新创建的字段添加到 suggester。

添加新字段时，所有现有文档都会自动获取该字段的 null 值。 在发生以下两种情况之一之前，不会使用其他存储空间： 为使用合并) (的新字段提供值，或者添加新文档。

无法更改现有的分析器、tokenizer、令牌筛选器和 char 筛选器。 只有在索引更新请求中打开标志时， allowIndexDowntime 才能将新索引添加到现有索引。 将初始向量字段添加到使用不支持矢量搜索的 API（特别是在 REST API 版本 2023-07-01 预览版之前）建立的预先存在的索引时，同样的规则适用。

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

此操作会让索引脱机几秒钟。 索引和查询请求在索引脱机时失败。 索引重新联机后，性能和写入操作可能会暂时受损几分钟。

URI 参数

参数 说明
服务名称 必需。 将其设置为搜索服务的唯一用户定义名称。
索引名称 必需。 请求 URI 指定要更新的索引的名称。
api-version 必需。 有关支持的版本列表，请参阅 API 版本。
allowIndexDowntime 可选。 默认值为 False。 对于某些更新，如添加或修改分析器、tokenizer、令牌筛选器、char 筛选器或相似性属性，设置为 true。 索引在更新期间脱机，通常不超过几秒钟。

请求标头

下表介绍必需和可选的请求标头。

字段 说明
Content-Type 必需。 将其设置为 application/json
api-key 如果使用的是 Azure 角色 ，并且请求中提供了持有者令牌，则为可选，否则需要密钥。 更新请求必须包含 api-key 设置为管理密钥 (的标头，而不是) 查询密钥。 有关详细信息 ，请参阅使用密钥身份验证连接到 Azure AI 搜索 。

请求正文

请求正文语法与 创建索引的语法相同。

更新现有索引时，正文必须包含完整的架构定义，包括要保留的任何原始定义。 通常，更新的最佳模式是使用 GET 检索索引定义，对其进行修改，然后使用 PUT 更新它。

响应

请求成功时，你应会看到“204 无内容”。

默认情况下，响应正文为空。 但是，如果 Prefer 请求标头设置为 return=representation，响应正文将包含已更新索引的 JSON。 在这种情况下，成功状态代码为“200 正常”。

另请参阅