# REST API

Rest API 设计用于作业、配置和集群管理。

### 分布式加载

#### 列出所有加载作业

**方法：** `GET`

**路径：** `/api/v1/load`

**参数：**

| **名称**        | **描述**       |
| ------------- | ------------ |
| `lastKey`     | 从最后一个键开始列出作业 |
| `count`       | 预期列出的作业数量    |
| 无参数时，默认列出所有任务 |              |

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "results": [
      {...}
    ]
  }
  ```

  有关作业描述的更多信息，请参阅 **“获取加载作业的进度”**
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取加载作业的进度

**方法：** `GET`

**路径：** `/api/v1/load`

**参数：**

| **名称**    | **描述**              |
| --------- | ------------------- |
| `index`   | ufs 上的索引文件路径（必须已挂载） |
| `alias`   | 路径列表的别名             |
| 最多需要一个参数。 |                     |

**响应：**

* `200 - OK`：操作成功（空值将被省略）

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0",
    "startTime": "2024-11-21T20:58:26.957+08:00",
    "state": "SUCCEEDED",
    "runningState": "",
    "errorMessage": {},
    "failedFileListPath": "",
    "paths": [
      "s3://my-bucket/dir/to/path"
    ],
    "index": "",
    "skipIfExists": false,
    "loadMetadataOnly": false,
    "verify": false,
    "bandwidth": 0,
    "timeElapsedMilliseconds": 10949,
    "loadedBytes": 10485760,
    "skippedBytes": 0,
    "totalBytes": 10485760,
    "loadedNonEmptyFiles": 1,
    "failedFiles": 0,
    "scannedFiles": 1,
    "quota": {
      "totalBytes": 0,
      "remaining": 0
    }
    "quotaCheckError": ""
  }
  ```
* `404 - Not Found`：未找到作业

  ```json
  {
    "status": "No job found..."
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 提交或恢复加载作业

**方法：** `POST`

**路径：** `/api/v1/load`

**参数：** 无

**请求体：** `Content-Type: application/json`

最多需要一个参数。`paths` 和 `alias` 必须一起提供。

| **名称**  | **描述**                    |
| ------- | ------------------------- |
| `index` | ufs 上的索引文件路径（必须已挂载）       |
| `paths` | 要加载的 ufs 路径列表             |
| `alias` | 用于后续状态查询的要加载的 UFS 路径列表的别名 |

可以使用 `options` JSON 来配置加载作业的选项。所有选项都是可选的。可能的配置有：

| **名称**            | **描述**                                 |
| ----------------- | -------------------------------------- |
| `batchSize`       | 工作节点从 ufs 加载数据的批处理大小                   |
| `fileFilterRegex` | 用于过滤要加载的文件的正则表达式                       |
| `replicas`        | 要加载的副本数，默认值为 1。如果启用了多个副本，可以指定此参数以匹配副本数 |
| `skipIfExists`    | 如果文件已存在，则跳过加载过程                        |
| `loadPolicy`      | 目前仅支持 IF\_CHANGED。如果文件已更改，则更新文件。       |

一个 JSON 请求负载示例如下：

```json
{
  "paths": [
    "s3://my-bucket/dir/to/path"
  ],
  "options": {
    "batchSize": 0,
    "fileFilterRegx": "",
    "replicas": 0,
    "sync": true,
    "skipIfExists": false
  }
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`：使用相同路径恢复加载作业并返回先前的作业 ID

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 停止加载作业

**方法：** `DELETE`

**路径：** `/api/v1/load`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`：作业不存在或已完成

  ```json
  {
    "status": "The job doesn't exist or has already finished"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 释放缓存

#### 列出所有释放作业

**方法：** `GET`

**路径：** `/api/v1/free`

**参数：**

| **名称**        | **描述**       |
| ------------- | ------------ |
| `lastKey`     | 从最后一个键开始列出作业 |
| `count`       | 预期列出的作业数量    |
| 无参数时，默认列出所有任务 |              |

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "results": [
      {...}
    ]
  }
  ```

  有关作业描述的更多信息，请参阅 **“获取释放作业的进度”**
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取释放作业的进度

**方法：** `GET`

**路径：** `/api/v1/free`

**参数：**

| **名称**    | **描述**              |
| --------- | ------------------- |
| `index`   | ufs 上的索引文件路径（必须已挂载） |
| `alias`   | 路径列表的别名             |
| 最多需要一个参数。 |                     |

**响应：**

* `200 - OK`：操作成功（空值将被省略）

  ```json
  {
    "id": "464050c3-9900-4b2f-8716-9220cd5eb495",
    "startTime": "2024-11-21T21:21:55.764+08:00",
    "state": "SUCCEEDED",
    "errorMessage": {},
    "paths": [
      "s3://my-bucket/dir/to/path"
    ],
    "timeElapsedMilliseconds": 4197,
    "freedBytes": 10485760,
    "failedBytes": 0,
    "totalBytes": 10485760,
    "freedFiles": 1,
    "failedFiles": 0,
    "totalFiles": 10485760
  }
  ```
* `404 - Not Found`：未找到作业

  ```json
  {
    "status": "No job found..."
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 提交或恢复释放作业

**方法：** `POST`

**路径：** `/api/v1/free`

**参数：** 无

**请求体：** `Content-Type: application/json`

最多需要一个参数。`paths` 和 `alias` 必须一起提供。

| **名称**  | **描述**                    |
| ------- | ------------------------- |
| `index` | ufs 上的索引文件路径（必须已挂载）       |
| `paths` | 要释放的 ufs 路径列表             |
| `alias` | 用于后续状态查询的要加载的 UFS 路径列表的别名 |

一个 JSON 请求负载示例如下：

```json
{
  "paths": [
    "s3://my-bucket/dir/to/path"
  ],
  "index": "",
  "options": {
    "batchSize": 0,
    "sync": true,
    "recursive": true
  }
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "id": "464050c3-9900-4b2f-8716-9220cd5eb495"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`：使用相同路径恢复释放作业并返回先前的作业 ID

  ```json
  {
    "id": "464050c3-9900-4b2f-8716-9220cd5eb495"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 停止释放作业

**方法：** `DELETE`

**路径：** `/api/v1/free`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "id": "464050c3-9900-4b2f-8716-9220cd5eb495"
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`：作业不存在或已完成

  ```json
  {
    "status": "The job doesn't exist or has already finished"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 重新平衡

#### 列出所有重新平衡作业

**方法：** `GET`

**路径：** `/api/v1/rebalance`

**参数：** 无

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "results": [
      {...}
    ]
  }
  ```

  有关作业描述的更多信息，请参阅 **“获取重新平衡作业的进度”**
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取重新平衡作业的进度

**方法：** `GET`

**路径：** `/api/v1/rebalance`

**参数：**

最多需要一个参数。

| **名称**   | **描述**                                                                                  |
| -------- | --------------------------------------------------------------------------------------- |
| `id`     | POST 返回的作业 ID                                                                           |
| `target` | 重新平衡作业的目标工作节点，可以是工作节点 ID（例如 worker-54b88939-de49-46ef-acab-fe489f46d1a0）或 ALL（表示所有工作节点） |

**响应：**

* `200 - OK`：操作成功（空值将被省略）

  ```json
  {
     "succeededWorkers":2,
     "bytesPreserved":4,
     "filesLoaded":0,
     "filesPreserved":1,
     "filesFailed":0,
     "totalWorkers":2,
     "bytesPruned":226,
     "filesPruned":5,
     "bytesLoaded":0,
     "timeElapsedMilliseconds":4536,
     "runningWorkers":0,
     "startTime":"2024-12-19T23:15:07.043+08:00",
     "id":"8de63d3a-63c8-4f08-bbc1-c87e3c0fb6d9",
     "state":"SUCCEEDED",
     "failedWorkers":0
  }
  ```
* `404 - Not Found`：未找到作业

  ```json
  {
    "status": "No job found..."
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 提交或恢复重新平衡作业

**方法：** `POST`

**路径：** `/api/v1/rebalance`

**参数：** 无

**请求体：** `Content-Type: application/json`

必需字段

| **名称**   | **描述**                                                                                      |
| -------- | ------------------------------------------------------------------------------------------- |
| `target` | 重新平衡作业的目标工作节点，可以是工作节点 ID（例如 `worker-54b88939-de49-46ef-acab-fe489f46d1a0`）或 `ALL`（表示所有工作节点） |

可以使用 `options` JSON 来配置加载作业的选项。所有选项都是可选的。可能的配置有：

| **名称**           | **描述**                              |
| ---------------- | ----------------------------------- |
| `loadBatchSize`  | 加载阶段的批处理大小，与加载作业中的 batchSize 选项相同   |
| `loadBandwidth`  | 每个工作节点每秒的加载带宽（字节）。例如：10485746000... |
| `pruneBandwidth` | 每个工作节点每秒的修剪带宽（字节）。例如：10485746000... |
| `skipPrune`      | 如果重新平衡应仅加载数据并跳过修剪不属于该工作节点的数据        |

一个 JSON 请求负载示例如下：

```json
{
  "target": "ALL",
  "options": {
    "loadBatchSize": 1000,
    "loadBandwidth": 10485746000,
    "pruneBandwidth": 10485746000,
    "skipPrune": false,
  }
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`：使用相同路径恢复加载作业并返回先前的作业 ID

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 停止重新平衡作业

**方法：** `DELETE`

**路径：** `/api/v1/rebalance`

**参数：** 无

**请求体：** `Content-Type: application/json`

最多需要一个参数。

| **名称**   | **描述**                                                                                      |
| -------- | ------------------------------------------------------------------------------------------- |
| `id`     | POST 返回的作业 ID                                                                               |
| `target` | 重新平衡作业的目标工作节点，可以是工作节点 ID（例如 `worker-54b88939-de49-46ef-acab-fe489f46d1a0`）或 `ALL`（表示所有工作节点） |

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`：作业不存在或已完成

  ```json
  {
    "status": "The job doesn't exist or has already finished"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 清理过时缓存

> 此操作与[释放缓存](#shi-fang-huan-cun)操作的不同之处在于：
>
> 1. 释放作业需要一个文件或目录列表作为输入参数，以指定要从工作节点中释放的内容。清理过时缓存操作不需要此类输入，因为“过时缓存”是通过扫描工作节点缓存存储并查询当前的一致性哈希环来自动确定的。
> 2. 释放作业需要设置正确的副本数，否则如果启用了文件复制，它可能会释放比预期少的副本。清理过时缓存操作只是向集群中的所有工作节点广播，因此它总是触发所有工作节点上的过时缓存清理，无论有多少副本。

#### 开始清理过时缓存

**方法：** `POST`

**路径：** `/api/v1/cache`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "op": "clear-stale"
}
```

**响应：**

* `200 - OK`：一个空的错误对象表示操作已成功提交给所有工作节点执行

  ```json
  {
    "errors": {}
  }
  ```
* `200 - OK`：非空的错误对象表示操作未能提交给至少一个工作节点执行

  ```json
  {
    "errors": {
      "worker-host": "error message"
    }
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：指定的操作类型未实现

  ```json
  {
    "status": "OP not implemented"
  }
  ```

#### 停止清理过时缓存

**方法：** `DELETE`

**路径：** `/api/v1/cache`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "op": "clear-stale"
}
```

**响应：**

* `200 - OK`：一个空的错误对象表示所有工作节点都已成功收到停止清理过时缓存的通知

  ```json
  {
    "errors": {}
  }
  ```
* `200 - OK`：非空的错误对象表示Coordinator未能通知至少一个工作节点停止清理过时缓存

  ```json
  {
    "errors": {
      "worker-host": "error message"
    }
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：指定的操作类型未实现

  ```json
  {
    "status": "OP not implemented"
  }
  ```

### 挂载表

#### 列出挂载点

**方法：** `GET`

**路径：** `/api/v1/mount`

**参数：** 无

**响应：**

* `200 - OK`：操作成功（如果为空，将省略选项）

  ```json
  {
    "results": [
      {
        "path": "/data/",
        "ufs": "s3://my-bucket/",
        "options": {
          "s3a.secretKey": "string",
          "s3a.accessKeyId": "string"
        }
      }
    ]
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取挂载点信息

**方法：** `GET`

**路径：** `/api/v1/mount`

**参数：**

| **名称** | **描述**          |
| ------ | --------------- |
| `path` | 挂载点的 alluxio 路径 |

**响应：**

* `200 - OK`：操作成功（如果为空，将省略选项）

  ```json
  {
    "path": "/data/",
    "ufs": "s3://my-bucket/",
    "options": {
      "s3a.secretKey": "string",
      "s3a.accessKeyId": "string"
    }
  }
  ```
* `404 - Not Found`：未找到挂载点

  ```json
  {
    "status": "No mount point found for path: /data/"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 创建挂载点

**方法：** `POST`

**路径：** `/api/v1/mount`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "path": "/data",
  "ufs": "s3://my-bucket",
  "options": {
    "s3a.secretKey": "string",
    "s3a.accessKeyId": "string"
  }
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`：该路径已挂载，或 UFS 已挂载到另一个路径

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：挂载表不支持通过 API 进行管理（例如：静态文件挂载表）

  ```json
  {
    "status": "string"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除挂载点

**方法：** `DELETE`

**路径：** `/api/v1/mount`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "path": "/data"
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`：该路径未挂载到任何 UFS

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：挂载表不支持通过 API 进行管理（例如：静态文件挂载表）

  ```json
  {
    "status": "string"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 配额

#### 列出所有配额状态

**方法：** `GET`

**路径：** `/api/v1/quota`

**参数：** 无

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "results": [
      {
        "path": "/data/dir/to/path",
        "state": "Available",
        "quotaBytes": 10737418240,
        "usedBytes": 9663676416,
        "reservedBytes": 1073741824
      }
    ]
  }
  ```
* `501 - Not Implemented`：未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取配额状态

**方法：** `GET`

**路径：** `/api/v1/quota`

**参数：**

| **名称** | **描述**         |
| ------ | -------------- |
| `path` | 数据的 alluxio 路径 |

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "path": "/data/dir/to/path",
    "state": "Available",
    "quotaBytes": 10737418240,
    "usedBytes": 9663676416,
    "reservedBytes": 1073741824
  }
  ```
* `404 - Not Found`: 未找到配额

  ```json
  {
    "status": "No quota item found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: 未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 添加或更新配额

**方法:** `POST`

**路径:** `/api/v1/quota`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "quotaBytes": 10737418240
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 该路径未指向已挂载的 UFS，但必须与现有的 UFS绑定

  ```json
  {
    "status": "No mounted UFS found"
  }
  ```
* `501 - Not Implemented`: 未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除配额

**方法:** `DELETE`

**路径:** `/api/v1/quota`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: ：请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 未找到配额或其他问题

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### TTL

#### 列出所有 TTL 策略

**方法:** `GET`

**路径:** `/api/v1/ttl`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
   {
    "results": [
      {
        "path": "/data/dir/to/path",
        "ttlSeconds": 600
      }
    ]
  }
  ```
* `501 - Not Implemented`: 未启用TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取 TTL 策略

**方法:** `GET`

**路径:** `/api/v1/ttl`

**参数:**

| **名称** | **描述**         |
| ------ | -------------- |
| `path` | 数据的 alluxio 路径 |

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "path": "/data/dir/to/path",
    "ttlSeconds": 600
  }
  ```
* `404 - Not Found`: 未找到TTL

  ```json
  {
    "status": "No TTL policy found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: 未启用TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 添加或更新 TTL

**方法:** `POST`

**路径:** `/api/v1/ttl`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "ttlSeconds": 600
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 路径未指向已挂载的 UFS，但必须与现有的 UFS绑定

  ```json
  {
    "status": "No mounted UFS found"
  }
  ```
* `501 - Not Implemented`: 未启用 TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除 TTL

**方法:** `DELETE`

**路径:** `/api/v1/ttl`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 未找到TTL

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用 TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 优先级驱逐

#### 列出所有优先级驱逐策略

**方法:** `GET`

**路径:** `/api/v1/priority`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "results": [
      {
        "path": "/data/dir/to/path",
        "priority": "high"
      }
    ]
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取优先级驱逐策略

**方法:** `GET`

**路径:** `/api/v1/priority`

**参数:**

| **名称** | **描述**         |
| ------ | -------------- |
| `path` | 数据的 alluxio 路径 |

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "path": "/data/dir/to/path",
    "priority": "high"
  }
  ```
* `404 - Not Found`: 未找到优先级驱逐策略

  ```json
  {
    "status": "No priority rule found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 添加或更新优先级

**方法:** `POST`

**路径:** `/api/v1/priority`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "priority": "high"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 优先级字符串格式错误或存在其他问题

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除优先级策略

**方法:** `DELETE`

**路径:** `/api/v1/priority`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 节点管理

#### 列出所有节点

**方法:** `GET`

**路径:** `/api/v1/nodes`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "result": [
      {
        "identity": "worker-587899dd-5da5-45d4-af40-ce481acc4087",
        "address": "192.168.1.19:29989",
        "status": "ONLINE"
      },
      {
        "identity": "worker-844db66c-d7fd-46cc-8de0-2f3989360828",
        "address": "192.168.1.19:29999",
        "status": "OFFLINE"
      }
    ]
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 查询节点

**方法:** `GET`

**路径:** `/api/v1/nodes`

**参数:**

| **名称** | **描述**                                                       |
| ------ | ------------------------------------------------------------ |
| `id`   | worker id (e.g. worker-587899dd-5da5-45d4-af40-ce481acc4087) |

**响应:**

* `200 - OK`: 操作成功\
  (空值将被省略)

  ```json
  {
    "identity": "worker-587899dd-5da5-45d4-af40-ce481acc4087",
    "address": "192.168.1.19:29989",
    "status": "ONLINE"
  }
  ```
* `404 - Not Found`: 未找到worker

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 注销节点（从 etcd 中移除节点）

**方法:** `DELETE`

**路径:** `/api/v1/nodes`

**参数:**

| **名称** | **描述**                                                       |
| ------ | ------------------------------------------------------------ |
| `id`   | worker id (e.g. worker-587899dd-5da5-45d4-af40-ce481acc4087) |

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `404 - Not Found`: 未找到worker

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 全局文件索引

#### 列出所有节点

**方法:** `GET`

**路径:** `/api/v1/file_index`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "results": [
      "file:///home/yimin/alluxio/ufs/10MB",
      "file:///home/yimin/alluxio/ufs/to_load/f1"
    ]
  }
  ```
* `500 - Internal Server Error`:意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 将文件添加到全局文件索引

**方法:** `POST`

**路径:** `/api/v1/file_index`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "files": [
    "s3://foo/bar/f1",
    "s3://foo/bar/f2"
  ]
}
```

**响应:**

* `200 - OK`: 操作成功（已添加条目数）

  ```json
  {
    "entries": 10
  }
  ```
* `404 - Not Found`: 功能未启用

  ```json
  {
    "status": "Global file index is not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 从全局文件索引中移除文件

**方法:** `DELETE`

**路径:** `/api/v1/file_index`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "files": [
    "s3://foo/bar/f1",
    "s3://foo/bar/f2"
  ]
}
```

**响应:**

* `200 - OK`: 操作成功（已移除条目数）

  ```json
  {
    "entries": 10
  }
  ```
* `404 - Not Found`: 功能未启用

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 缓存过滤

#### 列出所有缓存过滤规则

**方法:** `GET`

**路径:** `/api/v1/cache-filter`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

```json
{
  "results": [
    {
      "apiVersion": 1,
      "type": "metadata",
      "rules": {
        "defaultType": "immutable",
        "defaultMaxAge": null,
        "skipCache": ["s3://bucket/mutable-dir/.*"],
        "immutable": ["s3://bucket/immutable-dir/.*"],
        "maxAge": {"s3://bucket/auto-refresh/.*":  "1d"}
      }
    },
    {
      "apiVersion": 1,
      "type": "data",
      "rules": {
        "defaultType": "immutable",
        "defaultMaxAge": null,
        "skipCache": [],
        "immutable": [],
        "maxAge": {}
      }
    }
  ]
}
```

* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用缓存过滤

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

#### 添加缓存过滤规则或更新默认规则

**方法:** `POST`

**路径:** `/api/v1/cache-filter`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "type": "data",
  "rule": "skipCache",
  "pattern": "s3a://data-bucket/c/.*"
}
```

如果规则是 `maxAge`, 则需要指定 `time` 。

```json
{
  "type": "data",
  "rule": "maxAge",
  "pattern": "s3a://auto-refresh/c/.*",
  "time": "1d"
}
```

如果要更新默认规则，请设置 `updateDefault`。无需指定 `pattern` ，因为所有未匹配其他规则的路径都将由默认规则捕获。

```json
{
  "type": "metadata",
  "rule": "skipCache",
  "updateDefault": true
}
```

**响应:**

* `200 - OK`: 操作成功
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用缓存过滤

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

#### 移除缓存过滤规则

**方法:** `DELETE`

**路径:** `/api/v1/cache-filter`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "type": "data",
  "rule": "skipCache",
  "pattern": "s3a://data-bucket/c/.*"
}
```

如果规则是`maxAge`.，无需指定`time`。此外，默认规则无法删除，只能将默认规则更改为其他规则。

**响应:**

* `200 - OK`: 操作成功
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用缓存过滤

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/ai-3.7/reference/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.