API概览-检索分析服务 Elasticsearch版(ES)-阿里云帮助中心

按操作查阅

操作	参考文档
创建、更新、删除 Collection，管理 Slice、Backing 和 Alias	管理 Collection 与 Slice
读写文档、批量处理数据与查询	文档读写与查询
配置向量字段与执行 KNN 查询	向量字段与 KNN
预热 Slice 缓存与检查任务结果	预热 Slice 缓存
复制 Slice 数据与管理复制任务	Copy Slice
创建和使用可写分支	Branch Slice（Beta）
配置向量簇与自动选择候选 Slice	向量簇召回模式
查看 Collection、Backing 和 Slice 的运行状态	CAT 观测

实例监控与权限配置见实例运维；数量上限和功能边界见Agent 引擎版使用限制。

选择请求目标

普通索引通过索引名访问。使用 Collection 时，通过 Collection 或 Collection Alias 访问数据，并按照接口要求提供 _slice。实例地址、网络和认证见创建和连接 Agent 引擎版实例。

部分响应会暴露系统管理的名称或标识，应与应用传入的业务名称区分：

响应信息	含义与使用方式
写入、读取或查询响应中的 `_index`；注册响应中的 `backing_index`	可能是 `.sc-*` 底层索引名。仅用于排查，应用仍通过 Collection 名或 Alias 访问。
返回的 `_routing`	可能是系统分配的 Slice 内部标识（`slice_uid`），与业务 Slice 名不同。不要解析或作为后续 `_slice`、`routing` 的值；继续使用应用原先传入的 Slice 名。
Slice 管理响应中的 `slice`、`slice_id`	业务 Slice 名，例如 `tenant-a`；不同于内部 `slice_uid`。
Branch 响应中的 `target_uid`	目标 Slice 的内部身份标识，用于核对重复创建结果；访问目标时仍使用 `target_slice` 名称。

同名 Slice 删除后重新注册，内部身份可以变化。应用不应根据内部标识推导业务名称或延续旧 Slice 的生命周期。

请求与结果判断

JSON 请求使用 Content-Type: application/json；Bulk 和 Multi Search 使用 Content-Type: application/x-ndjson，并保留请求体末尾换行符。
Bulk、Multi Search 和批量管理接口可能出现 item 级失败，应用不能只判断 HTTP 状态码。注册 Slice 的单个接口和批量接口可能在 HTTP 200 中报告 item 级失败；客户端既要处理非 2xx 响应，也要在成功响应中检查顶层 errors 和 items[].result。
HTTP 429 表示服务端当前拒绝请求。客户端应采用有上限的指数退避，并只重试适合重试的操作。
连接超时或 HTTP 5xx 不代表写入一定没有发生。使用稳定文档 ID 或其他幂等机制核对后再重试。
通过 URL 传递大量 _slice 时，还会受到 HTTP 请求行长度限制（默认 4096 字节，由 http.max_initial_line_length 控制）。Slice 名较长时，可能在达到 Slice 数量上限之前先触发 too_long_http_line_exception。
Collection 管理 API 常用 master_timeout（等待主节点处理请求，默认 30s）和 timeout（等待确认或当前结果，默认 30s）。管理请求返回 acknowledged=false 或发生超时，不表示服务端操作已经回滚；重试前应先查询资源当前状态。

Collection 与 Slice API 速查

以下汇总 Collection 与 Slice 场景的公开 API，不含平台内部维护接口。

用途	API
创建 Collection	`PUT /_slice_collection/{collection}`
获取 Collection	`GET /_slice_collection[/{collection}]`
更新 Collection	`POST /_slice_collection/{collection}/_update`
删除 Collection	`DELETE /_slice_collection/{collection}`
注册一个 Slice	`PUT /_slice_collection/{collection}/slices/{slice}`
批量注册 Slice	`PUT /_slice_collection/{collection}/slices`
查询单个 Slice	`GET /_slice_collection/{collection}/slices/{slice}`
分页列出 Slice	`GET /_slice_collection/{collection}/slices`
删除 Slice	`DELETE /_slice_collection/{collection}/slices/{slice}`
预创建 Backing	`PUT /_slice_collection/{collection}/backings?count={count}`
单文档读写	`/{collection}/_doc/{id}`、`/{collection}/_create/{id}`、`/{collection}/_update/{id}`、`/{collection}/_source/{id}`；自动生成 ID 时使用 `POST /{collection}/_doc`，判断文档是否存在使用 `HEAD /{collection}/_doc/{id}`
批量写入和读取	`POST /_bulk`、`POST /{collection}/_bulk`、`POST /{collection}/_mget`
查询和计数	`POST /{collection}/_search`、`POST /{collection}/_count`、`POST /_msearch`、`POST /{collection}/_msearch`
其他查询接口	`POST /{collection}/_search/template`、`POST /{collection}/_async_search`、`GET /_async_search/{id}`、`DELETE /_async_search/{id}`、`POST /{collection}/_validate/query`、`GET /{collection}/_search_shards`、`POST /{collection}/_explain/{id}`
按查询更新或删除	`POST /{collection}/_update_by_query`、`POST /{collection}/_delete_by_query`
Reindex	`POST /_reindex`
更新 Mapping	`PUT /{collection}/_mapping`
更新动态 Settings	`PUT /{collection}/_settings`
显式 Refresh	`POST /{collection}/_refresh`
预热 Slice 缓存	`POST /{collection}/_warm_slice?_slice={slice}`
查询预热任务	`GET /_tasks/{taskId}`
管理 Collection Alias	`POST /_aliases`、`GET /_alias[/{alias}]`
启动 Copy Slice	`POST /_slice_collection/{collection}/slices/{source}/_copy/{target}`
查询 Copy 状态	`GET /_slice_collection/{collection}/_copy/{copy_id}`
取消 Copy	`POST /_slice_collection/{collection}/_copy/{copy_id}/_cancel`
创建 Branch Slice（Beta）	`PUT /_slice_collection/{collection}/slices/{source}/_branch/{target}`
Collection CAT	`GET /_cat/slice_collection[/{name}]`
Backing CAT	`GET /_cat/slice_collection/{collection}/backings[/{backing}]`
CAT 观测	`GET /_cat/slice_collection/{collection}/slices[/{slice}]`
集群和节点观测	`GET /_cluster/health`、`GET /_nodes/stats`、`GET /_tasks`