--- title: "查询快照（Cat格式）" date: 2026-03-15 lastmod: 2026-03-15 description: "以表格形式查询快照信息" tags: ["快照", "查询", "Cat API"] summary: "以紧凑的表格形式返回快照信息。 API 格式 # GET /_cat/snapshots GET /_cat/snapshots/{repository} API 作用 # 该 API 以表格形式返回快照信息： 显示所有仓库或指定仓库的快照 显示快照状态、时间、分片统计等信息 快速查看快照健康状态 API 参数 # 路径参数 # 参数 类型 是否必填 默认值 描述 {repository} String 否 所有仓库 快照仓库名称，用于过滤结果 查询参数 # 参数 类型 是否必填 默认值 描述 ignore_unavailable Boolean 否 false 是否忽略不可用的快照（损坏或暂时无法获取） master_timeout Time 否 30s 等待主节点的超时时间 format String 否 文本表格 响应格式（如 json、yaml） h String 否 所有列 逗号分隔的列名列表，指定要显示的列 help Boolean 否 false 是否返回帮助信息 s String 否 - 逗号分隔的列名或别名，用于排序 v Boolean 否 false 是否显示列标题（详细模式） 响应列说明 # 列名 别名 描述 id id, snapshot 唯一的快照 ID/名称 status s, status 快照状态 start_epoch ste, startEpoch 开始时间（1970-01-01 00:00:00 起的秒数） start_time sti, startTime 开始时间（HH:MM:SS 格式） end_epoch ete, endEpoch 结束时间（1970-01-01 00:00:00 起的秒数） end_time eti, endTime 结束时间（HH:MM:SS 格式） duration dur, duration 快照操作的持续时间 indices i, indices 快照中的索引数量 successful_shards ss, successful_shards 成功创建的分片数 failed_shards fs, failed_shards 失败的分片数 total_shards ts, total_shards 分片总数 reason r, reason 失败原因（仅在失败时显示） 请求示例 # 查询所有仓库的快照 # GET /_cat/snapshots?" --- 以紧凑的表格形式返回快照信息。 ## API 格式 ``` GET /_cat/snapshots GET /_cat/snapshots/{repository} ``` ## API 作用 该 API 以表格形式返回快照信息： - 显示所有仓库或指定仓库的快照 - 显示快照状态、时间、分片统计等信息 - 快速查看快照健康状态 ## API 参数 ### 路径参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `{repository}` | String | 否 | 所有仓库 | 快照仓库名称，用于过滤结果 | ### 查询参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `ignore_unavailable` | Boolean | 否 | `false` | 是否忽略不可用的快照（损坏或暂时无法获取） | | `master_timeout` | Time | 否 | `30s` | 等待主节点的超时时间 | | `format` | String | 否 | 文本表格 | 响应格式（如 `json`、`yaml`） | | `h` | String | 否 | 所有列 | 逗号分隔的列名列表，指定要显示的列 | | `help` | Boolean | 否 | `false` | 是否返回帮助信息 | | `s` | String | 否 | - | 逗号分隔的列名或别名，用于排序 | | `v` | Boolean | 否 | `false` | 是否显示列标题（详细模式） | ## 响应列说明 | 列名 | 别名 | 描述 | |------|------|------| | `id` | `id`, `snapshot` | 唯一的快照 ID/名称 | | `status` | `s`, `status` | 快照状态 | | `start_epoch` | `ste`, `startEpoch` | 开始时间（1970-01-01 00:00:00 起的秒数） | | `start_time` | `sti`, `startTime` | 开始时间（HH:MM:SS 格式） | | `end_epoch` | `ete`, `endEpoch` | 结束时间（1970-01-01 00:00:00 起的秒数） | | `end_time` | `eti`, `endTime` | 结束时间（HH:MM:SS 格式） | | `duration` | `dur`, `duration` | 快照操作的持续时间 | | `indices` | `i`, `indices` | 快照中的索引数量 | | `successful_shards` | `ss`, `successful_shards` | 成功创建的分片数 | | `failed_shards` | `fs`, `failed_shards` | 失败的分片数 | | `total_shards` | `ts`, `total_shards` | 分片总数 | | `reason` | `r`, `reason` | 失败原因（仅在失败时显示） | ## 请求示例 ### 查询所有仓库的快照 ``` GET /_cat/snapshots?v ``` ### 查询指定仓库的快照 ``` GET /_cat/snapshots/my_backup?v ``` ### JSON 格式响应 ``` GET /_cat/snapshots?format=json ``` ### 选择显示列 ``` GET /_cat/snapshots?h=id,status,duration,indices&v ``` ## 响应示例 ### 文本表格格式（verbose 模式） ``` id | status | start_epoch | start_time | end_epoch | end_time | duration | indices | successful_shards | failed_shards | total_shards ----------+-----------+-------------+-------------+------------+-----------+----------+---------+-------------------+---------------+------------- snap1 | SUCCESS | 1738617600 | 00:00:00 | 1738620900 | 00:55:00 | 55m | 5 | 50 | 0 | 50 snap2 | SUCCESS | 1738621200 | 01:00:00 | 1738623900 | 01:25:00 | 25m | 3 | 30 | 0 | 30 snap3 | IN_PROGRESS| 1738624500 | 02:15:00 | | | 8m | 2 | 18 | 2 | 20 snap4 | FAILED | 1738608000 | 22:00:00 | 1738611000 | 22:50:00 | 50m | 4 | 35 | 5 | 40 ``` ### JSON 格式响应 ```json [ { "id": "snap1", "status": "SUCCESS", "start_epoch": "1738617600", "start_time": "00:00:00", "end_epoch": "1738620900", "end_time": "00:55:00", "duration": "55m", "indices": "5", "successful_shards": "50", "failed_shards": "0", "total_shards": "50" }, { "id": "snap2", "status": "SUCCESS", "start_epoch": "1738621200", "start_time": "01:00:00", "end_epoch": "1738623900", "end_time": "01:25:00", "duration": "25m", "indices": "3", "successful_shards": "30", "failed_shards": "0", "total_shards": "30" } ] ``` ## 快照状态说明 | 状态 | 描述 | |------|------| | `SUCCESS` | 快照成功完成 | | `FAILED` | 快照失败 | | `IN_PROGRESS` | 快照正在创建中 | | `PARTIAL` | 快照部分完成 | ## 时间格式说明 - **时区**：所有时间戳均为 UTC 时区 - **start_epoch/end_epoch**：自 1970-01-01 00:00:00 起的秒数 - **start_time/end_time**：HH:MM:SS 格式的时间 - **duration**：人类可读的持续时间（如 `55m`、`2h30m`） ## 持续时间计算 - **进行中的快照**：`当前时间 - 开始时间` - **已完成的快照**：`结束时间 - 开始时间` ## 使用场景 1. **快速监控**：快速查看所有快照的状态 2. **健康检查**：检查快照是否有失败 3. **时间规划**：查看快照操作的持续时间 4. **容量规划**：查看分片统计信息 ## 注意事项 1. **v 参数**：使用 `?v` 显示列标题 2. **仓库过滤**：使用路径参数过滤特定仓库 3. **不可用快照**：设置 `ignore_unavailable=true` 忽略损坏的快照 4. **时间精度**：时间戳为 UTC 时区 ## 相关操作 - **GET /_snapshot/{repository}/{snapshot}**：获取详细快照信息 - **POST /_snapshot/{repository}/{snapshot}**：创建快照 - **DELETE /_snapshot/{repository}/{snapshot}**：删除快照 ## 实现文件 - **REST 处理器**：`RestSnapshotAction.java` - **请求类**：`GetSnapshotsRequest.java` - **响应类**：`GetSnapshotsResponse.java` - **快照信息**：`SnapshotInfo.java` - **基础类**：`AbstractCatAction.java`