---
title: "查询快照状态"
date: 2026-02-11
lastmod: 2026-02-11
description: "介绍如何在 Easysearch 中查询快照的当前状态和进度。"
tags: ["快照", "状态", "监控"]
summary: "此 API 用于获取快照的当前状态信息。
API #  GET /_snapshot/_status GET /_snapshot/{repository}/_status GET /_snapshot/{repository}/{snapshot}/_status API 的作用 #  返回快照的当前状态信息，包括：
 正在进行中的快照：正在执行的快照进度 已完成的快照：快照的详细统计信息 快照统计：文档数量、字节数、分片状态等  API 的参数 #  路由参数 #     参数 类型 是否必需 描述     repository string 可选 仓库名称
默认：_all（所有仓库）   snapshot string 可选 快照名称
默认：所有快照    查询字符串参数 #     参数 类型 是否必需 默认值 描述     ignore_unavailable boolean 可选 false 是否忽略不可用的快照"
---


此 API 用于获取快照的当前状态信息。

## API

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

## API 的作用

返回快照的当前状态信息，包括：

- **正在进行中的快照**：正在执行的快照进度
- **已完成的快照**：快照的详细统计信息
- **快照统计**：文档数量、字节数、分片状态等

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `repository` | string | 可选 | 仓库名称<br>默认：`_all`（所有仓库） |
| `snapshot` | string | 可选 | 快照名称<br>默认：所有快照 |

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `ignore_unavailable` | boolean | 可选 | false | 是否忽略不可用的快照<br>`true`：遇到不可用快照不报错<br>`false`：不可用快照会抛出异常 |
| `master_timeout` | time | 可选 | 30s | 等待主节点发现的超时时间 |

## 请求示例

```bash
# 查询所有仓库中所有快照的状态
GET /_snapshot/_status

# 查询指定仓库中所有快照的状态
GET /_snapshot/my-repo/_status

# 查询指定仓库中特定快照的状态
GET /_snapshot/my-repo/snapshot1/_status

# 忽略不可用的快照
GET /_snapshot/_status?ignore_unavailable=true

# 设置主节点超时时间
GET /_snapshot/_status?master_timeout=60s
```

## 响应示例

### 成功响应 - 正在进行中的快照

```json
{
  "snapshots": [
    {
      "snapshot": "snapshot1",
      "repository": "my-repo",
      "state": "IN_PROGRESS",
      "indices": ["index1", "index2", "index3"],
      "shards": {
        "total": 9,
        "pending": 3,
        "successful": 6,
        "failed": 0
      },
      "stats": {
        "incremental": {
          "file_count": 15,
          "size_in_bytes": 524288000
        },
        "total": {
          "file_count": 15,
          "size_in_bytes": 524288000
        },
        "start_time_in_millis": 1707033600000,
        "time_in_millis": 15000
      }
    }
  ]
}
```

### 成功响应 - 已完成的快照

```json
{
  "snapshots": [
    {
      "snapshot": "snapshot1",
      "repository": "my-repo",
      "state": "SUCCESS",
      "indices": ["index1", "index2", "index3"],
      "shards": {
        "total": 9,
        "successful": 9,
        "failed": 0
      },
      "stats": {
        "incremental": {
          "file_count": 150,
          "size_in_bytes": 5242880000
        },
        "total": {
          "file_count": 150,
          "size_in_bytes": 5242880000
        },
        "start_time_in_millis": 1707033600000,
        "time_in_millis": 45000
      }
    }
  ]
}
```

### 响应字段说明

| 字段 | 描述 |
|------|------|
| `snapshot` | 快照名称 |
| `repository` | 仓库名称 |
| `state` | 快照状态<br>`IN_PROGRESS`：进行中<br>`SUCCESS`：成功<br>`FAILED`：失败<br>`PARTIAL`：部分成功 |
| `indices` | 快照包含的索引列表 |
| `shards.total` | 总分片数 |
| `shards.pending` | 等待处理的分片数 |
| `shards.successful` | 成功的分片数 |
| `shards.failed` | 失败的分片数 |
| `stats.incremental.file_count` | 增量文件数量 |
| `stats.incremental.size_in_bytes` | 增量文件大小（字节） |
| `stats.total.file_count` | 总文件数量 |
| `stats.total.size_in_bytes` | 总文件大小（字节） |
| `stats.start_time_in_millis` | 开始时间（毫秒） |
| `stats.time_in_millis` | 耗时（毫秒） |

## 使用场景

1. **进度监控**：监控正在进行中的快照进度
2. **问题排查**：诊断快照失败的原因
3. **信息查询**：获取已完成的快照统计信息
4. **容量评估**：评估快照占用的存储空间

## 快照状态说明

| 状态 | 描述 |
|------|------|
| `IN_PROGRESS` | 快照正在进行中 |
| `SUCCESS` | 快照成功完成 |
| `FAILED` | 快照失败 |
| `PARTIAL` | 部分分片失败 |
| `INCOMPATIBLE` | 快照与当前版本不兼容 |

## 监控建议

1. **定期检查**：定期检查快照进度
2. **失败告警**：对失败的快照设置告警
3. **存储监控**：监控快照占用的存储空间
4. **时间跟踪**：记录快照完成时间用于容量规划

## 注意事项

1. 此 API 只支持 GET 方法
2. 默认查询所有仓库和所有快照
3. 不可用的快照默认会导致错误，使用 `ignore_unavailable=true` 忽略
4. 正在进行中的快照会返回实时进度信息

## 相关文档

- [创建快照](./create-snapshot.md)
- [查询快照信息](./get-snapshot-info.md)
- [删除快照](./delete-snapshot.md)
- [恢复快照](./restore-snapshot.md)