在 Azure AI Search 中创建索引别名

重要

索引别名目前在公开预览阶段，并且根据补充使用条款提供。

在Azure AI Search中，索引别名是搜索索引的辅助名称。 可以创建与搜索索引相对应的别名，并在需要引用索引名称的地方使用该别名。 如果您需要更改应用程序指向哪个索引，它将为您提供灵活性。 与其更新生产代码中索引名称的引用，不如更新别名的映射。

可以通过 HTTP 请求（POST、GET、PUT、DELETE）针对给定的别名资源在 Azure AI Search 服务中创建和管理别名。 别名是服务级别资源，独立于搜索索引进行维护。 创建搜索索引后，可以创建映射到该搜索索引的别名。

在使用别名之前，应用程序会将请求直接发送到 hotel-samples-index。

POST /indexes/hotel-samples-index/docs/search?api-version=2025-11-01-preview
{
    "search": "pool spa +airport",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

使用别名后，应用程序会向my-alias发送请求，而my-alias映射到。

POST /indexes/my-alias/docs/search?api-version=2025-11-01-preview
{
    "search": "pool spa +airport",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

支持的方案

只能将别名用于文档操作，或用于获取和更新索引定义。

别名不能用于删除索引或测试文本标记化，也不能作为targetIndexName索引器或知识源引用。

创建索引别名

创建别名会在别名和索引名称之间建立映射。 如果请求成功，别名可用于索引、查询和其他作。

通过更新别名，可以将该别名映射到其他搜索索引。 更新现有别名时，整个定义将替换为请求正文的内容。 通常，用于更新的最佳模式是使用 GET 检索别名定义，对其进行修改，然后使用 PUT 对其进行更新。

可以使用预览 REST API、预览版 SDK 或通过 Azure 门户创建别名。 别名包含别名的 name，以及别名映射到的搜索索引的名称。 在 indexes 数组中只能指定一个索引名称。

可以创建的别名的最大数目因定价层而异。 有关详细信息，请参阅服务限制。

可以使用创建或更新别名（REST 预览）创建索引别名。

POST /aliases?api-version=2025-11-01-preview
{
    "name": "my-alias",
    "indexes": ["hotel-samples-index"]
}

将请求发送到索引别名

别名可用于所有文档操作，包括查询、编制索引、建议和自动完成。

此查询将请求发送到my-alias，该请求映射到搜索服务的实际索引上。

POST /indexes/my-alias/docs/search?api-version=2025-11-01-preview
{
    "search": "pool spa +airport",
    "searchMode": any,
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

获取别名定义

此请求按名称返回现有别名对象的列表。

GET https://[service name].search.azure.cn/aliases?api-version=[api-version]&$select=name
api-key: [admin key]

此请求返回别名定义

GET https://[service name].search.azure.cn/aliases/my-alias?api-version=[api-version]
api-key: [admin key]

更新别名

别名的最常见更新是在基础索引替换为较新版本时更改索引名称。

别名更新必须使用 PUT，如 创建或更新别名（REST 预览版）中所述。

PUT /aliases/my-alias?api-version=2025-11-01-preview
{
    "name": "my-alias",
    "indexes": ["hotel-samples-index2"]
}

对别名进行的更新可能需要 10 秒才能在系统中传播，因此在删除别名之前映射到的索引之前，应等待至少 10 秒钟。

如果尝试删除当前映射到别名的索引，该作将失败并显示 400（错误请求）和一条错误消息，指出映射到该索引的别名（es）必须被删除或映射到其他索引，然后才能删除索引。

另请参阅

  • Last updated on