你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
创建或更新别名 (预览版 REST API)
适用于：2023-07-01-Preview、2021-04-30-Preview
重要
2023-07-01-预览版 () 无更改。
2021-04-30-Preview 添加了 API。
在 Azure AI 搜索中，别名是一个辅助名称，可用于引用用于查询、索引和其他操作的索引。
可以对创建请求使用 POST 或 PUT。 对于任一对象，请求正文中的 JSON 文档都提供对象定义。
POST https://[service name].search.windows.net/aliases?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
对于更新请求，请使用 PUT 并在 URI 上指定别名。
PUT https://[service name].search.windows.net/aliases/[alias name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
所有服务请求都需要 HTTPS。 对于 PUT，如果别名不存在，则会创建它。 如果已存在，则会将其更新为新定义。
创建别名 会在别名和索引名称之间建立映射。 如果请求成功，别名可用于索引、查询和其他操作。
通过更新别名 ，可以将该别名映射到不同的搜索索引。 更新现有别名时，整个定义将替换为请求正文的内容。 通常，用于更新的最佳模式是使用 GET 检索别名定义，对其进行修改，然后使用 PUT 更新别名定义。
注意
对别名进行的更新可能需要 10 秒才能在系统中传播，因此在删除别名之前映射到的索引之前，应等待至少 10 秒钟。
注意
可以创建的别名的最大数目因定价层而异。 有关详细信息，请参阅服务限制。
URI 参数
| 参数 | 说明 |
|---|---|
| 服务名称 | 必需。 将此值设置为搜索服务的唯一用户定义名称。 |
| 别名 | 如果使用 PUT，则为 URI 上的必需项。 名称必须为小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。 以字母或数字开头的名称后，名称的其余部分可以包含任何字母、数字和短划线，只要短划线不是连续的。 |
| api-version | 必需。 当前预览版本为 2023-07-01-Preview。 有关更多 版本，请参阅 API 版本。 |
请求标头
下表介绍必需和可选的请求标头。
| 字段 | 说明 |
|---|---|
| Content-Type | 必需。 将此值设置为 application/json |
| api-key | 如果使用的是 Azure 角色 ，并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是系统生成的唯一字符串，用于对搜索服务的请求进行身份验证。 创建请求必须包含 api-key 设置为管理密钥 (而不是查询密钥) 的标头。 有关详细信息 ，请参阅使用密钥身份验证连接到 Azure AI 搜索 。 |
请求正文
请求正文包含别名定义，其中包括别名的名称和具有单个索引名称的数组。
以下 JSON 是定义main部分的高级表示形式。
{
"name" : (optional on PUT; required on POST) "The name of the alias",
"indexes" : (required) ["The name of the index the alias is mapped to"]
}
请求包含以下属性：
| 属性 | 说明 |
|---|---|
| name | 必需。 别名的名称。 别名只能包含小写字母、数字或短划线，不能以短划线开头或结尾，并且不能包含 128 个字符。 |
| 索引 | 必需。 别名映射到的索引的名称。 数组中只能包含一个索引名称。 |
响应
对于成功的创建请求，应会看到状态代码“201 已创建”。
对于成功的更新请求，应会看到“204 无内容”。
示例
示例：索引别名
{
"name" : "my-alias",
"indexes" : ["my-index"]
}