---
title: "查询快照信息"
date: 2026-03-06
lastmod: 2026-03-06
description: "查询快照的详细信息"
tags: ["快照", "查询", "备份"]
summary: "获取指定快照的详细信息，或查询仓库中的所有快照。
API 格式 #  GET /_snapshot/{repository}/{snapshot} GET /_snapshot/{repository} API 作用 #  该 API 用于检索快照信息：
 获取特定快照的详细信息和状态 列出仓库中的所有快照 检查快照的完整性和可用性 查看快照包含的索引和元数据  API 参数 #  路径参数 #     参数 类型 是否必填 默认值 描述     {repository} String 是 - 快照仓库名称   {snapshot} String 否 _all 快照名称。未指定时返回所有快照    特殊快照值：
 _all：返回仓库中的所有快照（默认） _current：返回当前正在进行的快照  查询参数 #     参数 类型 是否必填 默认值 描述     ignore_unavailable Boolean 否 false 是否忽略不可用的快照（损坏或暂时无法获取）   verbose Boolean 否 true 是否返回详细信息。设为 false 仅返回快照名称和包含的索引   master_timeout Time 否 30s 等待主节点连接的超时时间    请求示例 #  查询指定快照 #  GET /_snapshot/my_backup/snapshot_1 查询所有快照 #  GET /_snapshot/my_backup/_all 简化输出（仅名称和索引） #  GET /_snapshot/my_backup/_all?"
---


获取指定快照的详细信息，或查询仓库中的所有快照。

## API 格式

```
GET /_snapshot/{repository}/{snapshot}
GET /_snapshot/{repository}
```

## API 作用

该 API 用于检索快照信息：
- 获取特定快照的详细信息和状态
- 列出仓库中的所有快照
- 检查快照的完整性和可用性
- 查看快照包含的索引和元数据

## API 参数

### 路径参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `{repository}` | String | **是** | - | 快照仓库名称 |
| `{snapshot}` | String | 否 | `_all` | 快照名称。未指定时返回所有快照 |

**特殊快照值：**
- `_all`：返回仓库中的所有快照（默认）
- `_current`：返回当前正在进行的快照

### 查询参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `ignore_unavailable` | Boolean | 否 | `false` | 是否忽略不可用的快照（损坏或暂时无法获取） |
| `verbose` | Boolean | 否 | `true` | 是否返回详细信息。设为 `false` 仅返回快照名称和包含的索引 |
| `master_timeout` | Time | 否 | `30s` | 等待主节点连接的超时时间 |

## 请求示例

### 查询指定快照

```
GET /_snapshot/my_backup/snapshot_1
```

### 查询所有快照

```
GET /_snapshot/my_backup/_all
```

### 简化输出（仅名称和索引）

```
GET /_snapshot/my_backup/_all?verbose=false
```

### 忽略损坏的快照

```
GET /_snapshot/my_backup/_all?ignore_unavailable=true
```

## 响应示例

### 查询单个快照响应

```json
{
  "snapshots": [
    {
      "snapshot": "snapshot_1",
      "uuid": "K8i7oP2rR4aK9sD5fG1hJ3mN6pQ",
      "version_id": 811419996,
      "version": "8.11.4",
      "indices": ["index1", "index2", "index3"],
      "data_streams": ["logs-stream"],
      "include_global_state": true,
      "metadata": {
        "created_by": "admin",
        "description": "Daily backup"
      },
      "state": "SUCCESS",
      "reason": null,
      "start_time": "2026-02-04T00:00:00.000Z",
      "start_time_in_millis": 1738617600000,
      "end_time": "2026-02-04T00:05:30.000Z",
      "end_time_in_millis": 1738620930000,
      "duration_in_millis": 330000,
      "failures": [],
      "shards": {
        "total": 15,
        "failed": 0,
        "successful": 15
      }
    }
  ]
}
```

### 查询所有快照响应

```json
{
  "snapshots": [
    {
      "snapshot": "daily_2026_02_04",
      "uuid": "K8i7oP2rR4aK9sD5fG1hJ3mN6pQ",
      "version": "8.11.4",
      "indices": ["index1", "index2"],
      "state": "SUCCESS",
      "start_time": "2026-02-04T00:00:00.000Z",
      "shards": {
        "total": 10,
        "failed": 0,
        "successful": 10
      }
    },
    {
      "snapshot": "daily_2026_02_03",
      "uuid": "X7h6nQ1qS3bJ8rE4cF2gI4lO5wR",
      "version": "8.11.4",
      "indices": ["index1", "index2"],
      "state": "SUCCESS",
      "start_time": "2026-02-03T00:00:00.000Z",
      "shards": {
        "total": 10,
        "failed": 0,
        "successful": 10
      }
    }
  ]
}
```

### verbose=false 响应

```json
{
  "snapshots": [
    {
      "snapshot": "snapshot_1",
      "uuid": "K8i7oP2rR4aK9sD5fG1hJ3mN6pQ",
      "indices": ["index1", "index2", "index3"]
    },
    {
      "snapshot": "snapshot_2",
      "uuid": "X7h6nQ1qS3bJ8rE4cF2gI4lO5wR",
      "indices": ["index1", "index4"]
    }
  ]
}
```

## 响应字段说明

### 顶层字段

| 字段 | 类型 | 描述 |
|------|------|------|
| `snapshots` | Array | 快照对象数组 |

### 快照对象字段

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

### failures 数组元素

| 字段 | 类型 | 描述 |
|------|------|------|
| `index` | String | 索引名称 |
| `shard_id` | Integer | 分片 ID |
| `reason` | String | 失败原因 |

## 使用建议

1. **云仓库优化**：对于云仓库（如 S3、Azure），使用 `verbose=false` 可减少网络流量和成本
2. **定期检查**：定期查询快照状态以验证备份完整性
3. **忽略损坏**：使用 `ignore_unavailable=true` 避免因个别快照损坏而导致整体查询失败

## 快照状态说明

| 状态 | 描述 |
|------|------|
| `SUCCESS` | 快照创建成功 |
| `FAILED` | 快照创建失败 |
| `PARTIAL` | 部分分片快照失败 |
| `IN_PROGRESS` | 快照正在创建中 |

## 注意事项

1. **默认行为**：未指定快照名称时自动使用 `_all` 返回所有快照
2. **性能影响**：`verbose` 参数显著影响响应大小和性能
3. **进行中的快照**：API 可同时处理已完成和进行中的快照
4. **云存储成本**：云仓库每次 blob 读取都会产生费用，建议使用 `verbose=false`

## 相关操作

- **POST /_snapshot/{repository}/{snapshot}**：创建快照
- **DELETE /_snapshot/{repository}/{snapshot}**：删除快照
- **POST /_snapshot/{repository}/{snapshot}/_restore**：恢复快照
- **GET /_snapshot/{repository}**：查询仓库信息

## 实现文件

- **REST 处理器**：`RestGetSnapshotsAction.java`
- **请求类**：`GetSnapshotsRequest.java`
- **响应类**：`GetSnapshotsResponse.java`
- **快照信息**：`SnapshotInfo.java`