创建快照

在指定的快照仓库中创建快照，备份索引数据。

API 格式 #

POST /_snapshot/{repository}/{snapshot}
PUT /_snapshot/{repository}/{snapshot}

API 作用 #

该 API 用于创建快照备份：

备份一个或多个索引到指定的快照仓库
支持选择性备份（指定索引列表）
可选包含集群全局状态
支持增量快照

API 参数 #

路径参数 #

参数	类型	是否必填	默认值	描述
`{repository}`	String	是	-	快照仓库名称
`{snapshot}`	String	是	-	快照名称

查询参数 #

参数	类型	是否必填	默认值	描述
`master_timeout`	Time	否	`30s`	连接主节点的超时时间
`wait_for_completion`	Boolean	否	`false`	是否等待快照完成后再返回响应

请求体参数 #

参数	类型	是否必填	默认值	描述
`indices`	Array	否	`["_all"]`	要包含在快照中的索引列表。支持多索引语法和别名。空数组或 `["*_all"]` 表示备份所有打开的索引
`ignore_unavailable`	Boolean	否	`false`	是否忽略不可用的索引（未找到或已关闭）
`include_global_state`	Boolean	否	`true`	是否在快照中包含集群全局状态元数据
`partial`	Boolean	否	`false`	是否允许部分快照（当某些索引的分片不可用时）
`settings`	Object	否	`{}`	仓库特定的设置（如压缩、块大小等）
`metadata`	Object	否	`null`	附加到快照的用户自定义元数据（最大 1024 字节）

请求示例 #

创建所有索引的快照 #

POST /_snapshot/my_backup/snapshot_1
{
  "indices": "*",
  "include_global_state": true
}

创建指定索引的快照 #

POST /_snapshot/my_backup/daily_backup
{
  "indices": ["index1", "index2", "logs-*"],
  "ignore_unavailable": true,
  "include_global_state": false,
  "metadata": {
    "created_by": "admin",
    "description": "Daily backup"
  }
}

等待快照完成 #

POST /_snapshot/my_backup/full_backup?wait_for_completion=true
{
  "indices": ["*"],
  "include_global_state": true
}

创建部分快照 #

POST /_snapshot/my_backup/partial_snapshot
{
  "indices": ["index1", "index2"],
  "partial": true
}

响应示例 #

wait_for_completion=false（默认） #

202 Accepted

{
  "accepted": true
}

wait_for_completion=true（成功） #

200 OK

{
  "snapshot": {
    "snapshot": "snapshot_1",
    "uuid": "K8i7oP2rR4aK9sD5fG1hJ3mN6pQ",
    "version_id": 811419996,
    "version": "8.11.4",
    "indices": ["index1", "index2"],
    "data_streams": [],
    "state": "SUCCESS",
    "start_time": "2026-02-04T12:00:00.000Z",
    "start_time_in_millis": 1738644000000,
    "end_time": "2026-02-04T12:05:00.000Z",
    "end_time_in_millis": 1738644300000,
    "duration_in_millis": 300000,
    "include_global_state": true,
    "metadata": {
      "created_by": "admin"
    },
    "total_shards": 10,
    "successful_shards": 10,
    "failed_shards": 0,
    "failures": []
  }
}

wait_for_completion=true（部分失败） #

200 OK

{
  "snapshot": {
    "snapshot": "snapshot_1",
    "uuid": "K8i7oP2rR4aK9sD5fG1hJ3mN6pQ",
    "version_id": 811419996,
    "version": "8.11.4",
    "indices": ["index1", "index2"],
    "data_streams": [],
    "state": "PARTIAL",
    "reason": "some shards failed to snapshot",
    "start_time": "2026-02-04T12:00:00.000Z",
    "start_time_in_millis": 1738644000000,
    "end_time": "2026-02-04T12:05:00.000Z",
    "end_time_in_millis": 1738644300000,
    "duration_in_millis": 300000,
    "include_global_state": true,
    "total_shards": 10,
    "successful_shards": 8,
    "failed_shards": 2,
    "failures": [
      {
        "shard": 0,
        "index": "index1",
        "node": "node-1",
        "reason": "failed to snapshot shard",
        "status": "503"
      }
    ]
  }
}

响应状态码 #

状态码	描述
202 Accepted	快照操作已启动但未完成（wait_for_completion=false）
200 OK	快照完成成功或部分成功（wait_for_completion=true）
500 Internal Server Error	快照完全失败

响应字段说明 #

快照对象字段 #

字段	类型	描述
`snapshot`	String	快照名称
`uuid`	String	快照的唯一标识符
`version_id`	Integer	创建快照的 Easysearch 版本号
`version`	String	创建快照的 Easysearch 版本字符串
`indices`	String[]	快照中包含的索引列表
`data_streams`	String[]	快照中包含的数据流列表
`state`	String	快照状态（SUCCESS、PARTIAL、FAILED）
`reason`	String/null	失败或部分失败的原因
`start_time`	String	快照开始时间（ISO 格式）
`start_time_in_millis`	Long	开始时间（毫秒时间戳）
`end_time`	String	快照结束时间（ISO 格式）
`end_time_in_millis`	Long	结束时间（毫秒时间戳）
`duration_in_millis`	Long	快照总耗时（毫秒）
`include_global_state`	Boolean	是否包含集群全局状态
`metadata`	Object	附加的用户自定义元数据
`total_shards`	Integer	快照的总分片数
`successful_shards`	Integer	成功的分片数
`failed_shards`	Integer	失败的分片数
`failures`	Array	分片失败详情数组

命名规范 #

仓库名称 #

必须是非空字符串
小写
不能包含空格
不能包含逗号、井号
不能以下划线开头

快照名称 #

必须是非空字符串
小写
不能包含空格
不能包含逗号、井号
不能以下划线开头

使用场景 #

定期备份：按计划创建定期快照
全量备份：备份所有索引和集群状态
选择性备份：仅备份重要索引
迁移准备：在数据迁移前创建快照

注意事项 #

元数据大小：用户元数据限制为 1024 字节
并发限制：同一索引的并发快照会冲突
默认索引：未指定索引时备份所有打开的索引
增量快照：只备份自上次快照以来的变更
部分快照：使用 partial=true 允许部分分片失败时仍创建快照

快照状态说明 #

状态	描述
`SUCCESS`	所有分片快照成功
`PARTIAL`	部分分片快照失败
`FAILED`	快照完全失败
`IN_PROGRESS`	快照正在进行中

实现文件 #

REST 处理器：RestCreateSnapshotAction.java
请求类：CreateSnapshotRequest.java
响应类：CreateSnapshotResponse.java
Transport Action：TransportCreateSnapshotAction.java
快照信息：SnapshotInfo.java

标签

API 格式 #

API 作用 #

API 参数 #

路径参数 #

查询参数 #

请求体参数 #

请求示例 #

创建所有索引的快照 #

创建指定索引的快照 #

等待快照完成 #

创建部分快照 #

响应示例 #

wait_for_completion=false（默认） #

wait_for_completion=true（成功） #

wait_for_completion=true（部分失败） #

响应状态码 #

响应字段说明 #

快照对象字段 #

命名规范 #

仓库名称 #

快照名称 #

使用场景 #

注意事项 #

快照状态说明 #

相关操作 #

实现文件 #