# 列出 Worker 镜像

列出创建或更新计算实例时可选择的 Worker 镜像。

```text
GET https://moi.matrixorigin.cn/newmoi/compute-resources/worker-images
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：要查询的工作区 ID，通过 `X-Workspace-ID` Header 传递。

此接口需要计算实例创建权限。

## 查询参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `worker_type` | string | 否 | 按 Worker 类型筛选。 |
| `type` | string | 否 | 按镜像键筛选。 |

## 请求示例

```bash
curl "https://moi.matrixorigin.cn/newmoi/compute-resources/worker-images?worker_type=python-worker" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## 成功响应

成功时返回 `200`，`data` 为可用镜像数组。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": [
    {
      "id": "python-worker:v1",
      "worker_type": "python-worker",
      "image_key": "python-worker",
      "type": "python-worker",
      "platform": "linux/amd64",
      "is_default": true,
      "status": "active"
    }
  ]
}
```

响应字段如下。

字段路径中的 `[]` 表示数组中的每一项。例如，`data[].id` 表示 `data` 数组中每一项的 `id` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data` | object（对象数组） | 可用镜像数组。 |
| `data[].id` | string | 镜像 ID，创建或更新时作为 `image_id` 传入。 |
| `data[].worker_type` | string | 创建或更新时作为 `worker_type` 传入。 |
| `data[].image_key` | string | 镜像的规范键；与 `type` 对应。 |
| `data[].type` | string | 镜像键；与 `image_key` 对应。 |
| `data[].tag` | string | 镜像标签。 |
| `data[].repository` | string | 镜像仓库。 |
| `data[].platform` | string | 创建或更新时作为 `platform` 传入。 |
| `data[].description` | string | 镜像说明；有值时返回。 |
| `data[].is_default` | boolean | 是否为该 Worker 类型的默认镜像。 |
| `data[].status` | string | 镜像当前状态。 |
| `data[].registered_at` | string | 注册时间；有值时返回。 |
| `data[].updated_at` | string | 最后更新时间；有值时返回。 |

## 错误响应

```json
{
  "code": "LIST_IMAGES_FAILED",
  "msg": "服务端错误",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - `worker_type` 或 `type` 的值无法被服务端接受。
  - 检查查询参数后重试。
* - `401`
  - —
  - 缺少或无效的访问凭据。
  - 检查 API Key 和工作区 Header。
* - `403`
  - `ErrForbidden`
  - 当前身份没有读取可用镜像的权限。
  - 使用有权限的凭据，或联系管理员授权。
* - `500`
  - `LIST_IMAGES_FAILED`
  - 服务无法读取 Worker 镜像列表。
  - 记录请求时间和错误信息后重试。
```

## 后续操作

将 `id`、`worker_type` 和 `platform` 组合到 `worker_images`，再[创建计算实例](create-compute-resource.md)。