# REST API

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

### 分布式加载

提前将UFS数据加载到worker中缓存，避免冷读对用户产生性能影响。

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

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| POST   | /api/v1/load | 无      | Content-Type: application/json |

**参数**

| **名称**    | **类型** | **必填** | **描述**              | **示例**                                                                       |
| --------- | ------ | ------ | ------------------- | ---------------------------------------------------------------------------- |
| `index`   | string | 否      | ufs 上的索引文件路径（必须已挂载） | '{"index": s3://bucket/key}'                                                 |
| `paths`   | string | 否      | 要加载的 ufs 路径列表       | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"]}'                       |
| `alias`   | string | 否      | 和paths组合使用，供后续状态查询  | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"], "alias": "database1"}' |
| `options` | object | 否      | 配置加载作业的选项           | '{"index": s3://bucket/key, "options":{"batchSize":10}}'                     |

其中，`index`和`paths`二选一. `paths`可以指定`alias`，否则内部随机生成alias返回用户。

可以使用 `options` 来配置加载作业的选项。可选字段有：

| **名称**             | **类型** | **必填** | **描述**                           |
| ------------------ | ------ | ------ | -------------------------------- |
| `batchSize`        | int    | 否      | worker从 ufs 加载数据的批处理大小           |
| `replicas`         | int    | 否      | 加载文件副本数，默认值config中设置对应路径副本或1     |
| `skipIfExists`     | bool   | 否      | 如果文件已存在，则跳过加载过程.                 |
| `loadPolicy`       | enum   | 否      | 目前仅支持 IF\_CHANGED。如果文件已更改，则更新文件。 |
| `loadMetadataOnly` | bool   | 否      | 仅加载文件元数据。                        |

**示例**

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

```json
{
  "paths": [
    "s3://my-bucket/dir/to/path"
  ],
  "options": {
    "batchSize": 1,
    "replicas": 1,
    "loadMetadataOnly": true,
    "loadPolicy": "IF_CHANGED"
  }
}
```

正常返回示例：json格式

```
{
  "target":"job-95e8a01f-d519-4c1a-8311-26714f4db623",
  "id":"1cf35e69-b6e6-4807-8aae-588e0e994277"
}
```

**错误码**

| **http状态码** | **错误码**               | **描述**                 |
| ----------- | --------------------- | ---------------------- |
| 200         | OK                    | 操作成功                   |
| 400         | Bad Request           | 请求没有正文或缺少必需字段          |
| 409         | Conflict              | 已经存在相同的job被调度，拒绝新任务的提交 |
| 500         | Internal Server Error | 意外错误                   |

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

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/load | 有      | 无         |

**参数：**

| **名称**       | **类型** | **必填** | **描述**                  | **示例**                                                                           |
| ------------ | ------ | ------ | ----------------------- | -------------------------------------------------------------------------------- |
| `target`     | string | 是      | 提交job时返回字段信息            | target=job-95e8a01f-d519-4c1a-8311-26714f4db623                                  |
| `fileList`   | bool   | 否      | 获取加载文件列表                | target=job-95e8a01f-d519-4c1a-8311-26714f4db623\&fileList=true                   |
| `fileStatus` | string | 否      | 文件列表类型\[TOTAL\|FAILURE] | target=job-95e8a01f-d519-4c1a-8311-26714f4db623\&fileList=true\&fileStatus=TOTAL |

注：3.7查询参数依然兼容, 例如:`alias`,`index`

**示例** 获取任务执行状态正常返回示例：json格式

```
{
    "id": "043cc6c2-b456-4d57-a807-a8c86256d8f2",
    "startTime": "2026-01-16T16:35:35.32+08:00",
    "endTime": "2026-01-16T16:35:42.149+08:00",
    "jobState": "SUCCEEDED",
    "timeElapsedMilliseconds": 6829,
    "paths": [
        "s3://test/index"
    ],
    "alias": "job-e7cc61f3-fdd5-45fe-a11b-e8f92f0c6d05",
    "batchSize": 200,
    "loadedBytes": 127,
    "totalBytes": 127,
    "loadedNonEmptyFiles": 1,
    "scannedFiles": 1,
    "replicas": "ALL"
}
```

获取任务列表正常返回示例：json格式

```
[
    {
        "path": "s3://test/index",
        "size": 0,
        "mTime": 0
    },
    {
        "path": "s3://test/index-copy",
        "size": 0,
        "mTime": 0
    }
]
```

**错误码**

| **http状态码** | **错误码**               | **描述** |
| ----------- | --------------------- | ------ |
| 200         | OK                    | 操作成功   |
| 404         | Not Found             | 任务不存在  |
| 500         | Internal Server Error | 意外错误   |

#### 停止加载作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| DELETE | /api/v1/load | 无      | Content-Type: application/json |

**参数：**

| **名称**   | **类型** | **必填** | **描述**       | **示例**                                                |
| -------- | ------ | ------ | ------------ | ----------------------------------------------------- |
| `target` | string | 是      | 提交job时返回字段信息 | {"target":"job-95e8a01f-d519-4c1a-8311-26714f4db623"} |

注：3.7停止参数依然兼容， 例如:`alias`,`index`

**错误码**

| **http状态码** | **错误码**     | **描述**        |
| ----------- | ----------- | ------------- |
| 200         | OK          | 操作成功          |
| 400         | Bad Request | 请求没有正文或缺少必需字段 |
| 404         | Not Found   | 加载作业不存在       |
| 410         | Gone        | 加载作业已完成       |

#### 列举加载作业列表

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/load | 有      | 无         |

**参数：**

| **名称**    | **类型** | **必填** | **描述**                                 |
| --------- | ------ | ------ | -------------------------------------- |
| `state`   | enum   | 否      | 作业状态\[RUNNING\|SUCCEEDED\|FAILED\|ALL] |
| `lastKey` | string | 否      | 从当前作键开始列举作业                            |
| `count`   | int    | 否      | 预期列出的作业数量                              |

注：没有参数将会列举所有job

**错误码**

| **http状态码** | **错误码** | **描述** |
| ----------- | ------- | ------ |
| 200         | OK      | 操作成功   |

**响应** 一个正常列举的响应：json格式

```
{
    "results": [
        {
            "id": "53b3123d-a042-4eb1-90e5-73798b963b04",
            "startTime": "2026-01-17T08:22:52.787+08:00",
            "endTime": "2026-01-17T08:22:57.289+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4502,
            "paths": [
                "s3://tidas-alluxio-test/index"
            ],
            "alias": "job-1cfb048e-7ca7-48d3-8dd3-aa2ed8472176",
            "batchSize": 200,
            "loadedBytes": 127,
            "totalBytes": 127,
            "loadedNonEmptyFiles": 1,
            "scannedFiles": 1,
            "replicas": "ALL"
        },
        {
            "id": "89e288cf-480a-40df-a45b-91c3e08cb138",
            "startTime": "2026-01-17T08:22:54.117+08:00",
            "endTime": "1970-01-01T08:00:00+08:00",
            "jobState": "RUNNING",
            "runningStage": "LOADING",
            "paths": [
                "s3://tidas-alluxio-test/index"
            ],
            "alias": "job-9869111f-99f3-4ee4-9dbe-6c0204b96aec",
            "batchSize": 200,
            "replicas": "ALL"
        }
    ]
}
```

### 释放缓存

将worker缓存数据清理，释放缓存存储空间

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

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| POST   | /api/v1/free | 无      | Content-Type: application/json |

**参数**

| **名称**    | **类型** | **必填** | **描述**              | **示例**                                                                       |
| --------- | ------ | ------ | ------------------- | ---------------------------------------------------------------------------- |
| `index`   | string | 否      | ufs 上的索引文件路径（必须已挂载） | '{"index": s3://bucket/key}'                                                 |
| `paths`   | string | 否      | 要释放的 ufs 路径列表       | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"]}'                       |
| `alias`   | string | 否      | 和paths组合使用，供后续状态查询  | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"], "alias": "database1"}' |
| `options` | object | 否      | 配置加载作业的选项           | '{"index": s3://bucket/key, "options":{"batchSize":10}}'                     |

其中，index和paths二选一。paths可以指定alias，否则内部随机生成alias返回用户。

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

| **名称**         | **类型** | **必填** | **描述**                |
| -------------- | ------ | ------ | --------------------- |
| `batchSize`    | int    | 否      | worker每秒钟释放缓存文件的速度    |
| `replicas`     | int    | 否      | 释放文件副本的数量，仅在释放文件的时候有效 |
| `indexService` | bool   | 否      | 释放目录缓存                |

**示例**

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

```json
{
    "paths": [
        "s3://tidas-alluxio-test/index",
        "s3://tidas-alluxio-test/index-copy"
    ],
    "options": {
        "batchSize": "30"
    }
}
```

正常返回示例：json格式

```
{
    "target": "job-0aafec67-53b4-488c-b988-73493b2b9ebe",
    "id": "bc0c3296-ea1f-484b-b371-300bf4d54ca6"
}
```

**错误码**

| **http状态码** | **错误码**               | **描述**                 |
| ----------- | --------------------- | ---------------------- |
| 200         | OK                    | 操作成功                   |
| 400         | Bad Request           | 请求没有正文或缺少必需字段          |
| 409         | Conflict              | 已经存在相同的job被调度，拒绝新任务的提交 |
| 500         | Internal Server Error | 意外错误                   |

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

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/free | 有      | 无         |

**参数：**

| **名称**   | **类型** | **必填** | **描述**       | **示例**                                          |
| -------- | ------ | ------ | ------------ | ----------------------------------------------- |
| `target` | string | 是      | 提交job时返回字段信息 | target=job-95e8a01f-d519-4c1a-8311-26714f4db623 |

注：3.7查询参数依然兼容， 例如:`alias`,`index`

**示例** 获取任务执行状态正常返回示例：json格式

````
```json
{
"id": "17bb4213-891b-4c3f-bc32-8d314051514b",
"startTime": "2026-01-17T21:59:11.831+08:00",
"endTime": "2026-01-17T21:59:16.104+08:00",
"jobState": "SUCCEEDED",
"timeElapsedMilliseconds": 4273,
"paths": [
    "s3://test/"
],
"alias": "job-95adb50b-4722-4a79-bd58-872cfeca48cb",
"freedBytes": 409600,
"totalBytes": 409600,
"freedFiles": 100,
"totalFiles": 100
````

} \`\`\`

**错误码**

| **http状态码** | **错误码**   | **描述** |
| ----------- | --------- | ------ |
| 200         | OK        | 操作成功   |
| 404         | Not Found | 任务不存在  |

#### 停止释放作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| DELETE | /api/v1/free | 无      | Content-Type: application/json |

**参数：**

| **名称**   | **类型** | **必填** | **描述**       | **示例**                                                |
| -------- | ------ | ------ | ------------ | ----------------------------------------------------- |
| `target` | string | 是      | 提交job时返回字段信息 | {"target":"job-95e8a01f-d519-4c1a-8311-26714f4db623"} |

注：3.7停止参数依然兼容， 例如:`alias`,`index`

**错误码**

| **http状态码** | **错误码**     | **描述**        |
| ----------- | ----------- | ------------- |
| 200         | OK          | 操作成功          |
| 400         | Bad Request | 请求没有正文或缺少必需字段 |
| 404         | Not Found   | 加载作业不存在       |
| 410         | Gone        | 加载作业已完成       |

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

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/free | 有      | 无         |

**参数：**

| **名称**    | **类型** | **必填** | **描述**                                 | **示例** |
| --------- | ------ | ------ | -------------------------------------- | ------ |
| `state`   | enum   | 否      | 作业状态\[RUNNING\|SUCCEEDED\|FAILED\|ALL] |        |
| `lastKey` | string | 否      | 从当前作键开始列举作业                            |        |
| `count`   | int    | 否      | 预期列出的作业数量                              |        |

注：没有参数将会列举所有job

**错误码**

| **http状态码** | **错误码** | **描述** |
| ----------- | ------- | ------ |
| 200         | OK      | 操作成功   |

**响应** 一个正常列举的响应：json格式

```
{
    "results": [
        {
            "id": "1498117f-bf66-4198-967d-1186588c56d1",
            "startTime": "2026-01-17T22:13:35.198+08:00",
            "endTime": "2026-01-17T22:13:40.385+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 5187,
            "paths": [
                "s3://test/rest1/test/"
            ],
            "alias": "job-312c44ac-156c-4e5a-b142-e540067ad086"
        },
        {
            "id": "3baf5ab6-c303-4a59-8678-f297870847f4",
            "startTime": "2026-01-17T22:13:26.177+08:00",
            "endTime": "2026-01-17T22:13:30.38+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4203,
            "paths": [
                "s3://test/rest/test/"
            ],
            "alias": "job-749f2cbf-32cb-44d5-aa4f-4a4e6b94689b"
        }
    ]
}
```

### 重新平衡

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

**方法：** `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"
  }
  ```

### 文件位置

计算哪些 worker 持有某个文件的缓存数据，可选择限定到特定字节段。适用于感知数据本地性的调度（Spark、Presto、Ray）以及调试缓存命中/未命中行为。

#### 获取文件或分段位置

**方法:** `GET`

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

**参数**

| **名称**              | **必填** | **描述**                                                                          |
| ------------------- | ------ | ------------------------------------------------------------------------------- |
| `path`              | 是      | 文件的 Alluxio 或 UFS 路径                                                            |
| `segments`          | 否      | 分段规格（例如 `0,2,5-7`）。设置后，响应为分段范围位置列表                                              |
| `segment_size`      | 否      | 覆盖配置的分段大小（例如 `64MB`）。仅在设置了 `segments` 时使用；默认值为 `alluxio.user.file.segment.size` |
| `check_all_workers` | 否      | `true` 表示即使一致性哈希主节点已持有该文件，也查询所有 worker。仅在未设置 `segments` 时使用                     |

**响应:**

* `200 - OK`: 操作成功。响应体的结构取决于是否提供了 `segments`。

  未提供 `segments` 时，响应为一致性哈希环生成的文件级位置映射（每个文件对应一个或多个 worker）。

  提供了 `segments` 时，响应为每个分段的位置条目列表，每条描述字节范围及持有该分段的 worker。
* `400 - Bad Request`: 缺少 `path`

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

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

### 副本放置规则

在多集群部署中，副本放置规则控制给定路径前缀的副本应分布在哪些成员集群上。规则以 Alluxio 路径前缀为键。

#### 列出所有副本规则

**方法:** `GET`

**路径:** `/api/v1/replica-rule`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功。返回以路径前缀为键、对应规则为值的映射。

  ```json
  {
    "/data/shared/": {
      "...": "ReplicaClusterPlacementRule fields"
    }
  }
  ```
* `500 - Internal Server Error`: 意外错误

#### 添加或更新副本规则

**方法:** `POST`

**路径:** `/api/v1/replica-rule`

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

`numReplicasPerCluster` 和 `rules` 两者必须且只能提供其中一个。

| **名称**                  | **类型** | **必填** | **描述**                                                              |
| ----------------------- | ------ | ------ | ------------------------------------------------------------------- |
| `path`                  | string | 是      | 规则适用的 Alluxio 路径前缀，不得为 UFS 路径                                       |
| `numReplicasPerCluster` | int    | 否      | 应用于每个成员集群的统一副本数（必须 > 0）                                             |
| `rules`                 | object | 否      | 每个集群的副本数，例如 `{"cluster-a": 2, "cluster-b": 1}`。集群名称必须已在全局客户端集群信息中注册 |

示例：

```json
{
  "path": "/data/shared/",
  "numReplicasPerCluster": 2
}
```

```json
{
  "path": "/data/shared/",
  "rules": {
    "cluster-a": 2,
    "cluster-b": 1
  }
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 缺少 `path`、`path` 为 UFS 路径、`numReplicasPerCluster` 和 `rules` 同时设置或均未设置、副本数非正，或 `rules` 中包含未知集群名称
* `500 - Internal Server Error`: 意外错误

#### 删除副本规则

**方法:** `DELETE`

**路径:** `/api/v1/replica-rule`

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

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

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求体缺失或缺少 `path`
* `500 - Internal Server Error`: 意外错误

### 集群信息

获取集群基本信息，包括集群名称、软件版本、总缓存容量与使用量，以及在线/离线 worker 数量。

#### 获取集群信息

**方法:** `GET`

**路径:** `/api/v1/cluster-info`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "name": "my-alluxio-cluster",
    "version": "3.x-15.0.0",
    "capacityBytes": 1099511627776,
    "usedBytes": 536870912000,
    "onlineWorkers": 5,
    "offlineWorkers": 1
  }
  ```
* `500 - Internal Server Error`: 意外错误

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


---

# 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/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.