REST API¶

Incus 与其客户端之间所有通信都通过 HTTP 上的 RESTful API 进行。此 API 在 TLS（用于远程操作）或 Unix 套接字（用于本地操作）上封装。

有关如何远程访问 API 的信息，请参见远程 API 身份验证。

提示

有关 API 如何使用的示例，请运行 Incus 客户端的任何命令（incus）并使用 --debug 标志。调试信息将显示 API 调用和返回值。
为了快速查询 API，Incus 客户端提供了一个 incus query 命令。

API 版本控制¶

可以使用 GET / 检索支持的主要 API 版本列表。

主要 API 版本升级的原因是 API 可能会破坏向后兼容性。

在不破坏向后兼容性的情况下完成的功能添加只会导致 api_extensions 的添加，客户端可以使用它来检查服务器是否支持给定功能。

返回值¶

有三种标准返回类型

标准返回值
后台操作
错误

标准返回值¶

对于标准同步操作，将返回以下 JSON 对象

{
    "type": "sync",
    "status": "Success",
    "status_code": 200,
    "metadata": {}                          // Extra resource/action specific metadata
}

HTTP 代码必须为 200。

后台操作¶

当请求导致后台操作时，HTTP 代码将设置为 202（已接受），并且 Location HTTP 标头将设置为操作 URL。

主体是一个 JSON 对象，其结构如下

{
    "type": "async",
    "status": "OK",
    "status_code": 100,
    "operation": "/1.0/instances/<id>",                     // URL to the background operation
    "metadata": {}                                          // Operation metadata (see below)
}

操作元数据结构如下所示

{
    "id": "a40f5541-5e98-454f-b3b6-8a51ef5dbd3c",           // UUID of the operation
    "class": "websocket",                                   // Class of the operation (task, websocket or token)
    "created_at": "2015-11-17T22:32:02.226176091-05:00",    // When the operation was created
    "updated_at": "2015-11-17T22:32:02.226176091-05:00",    // Last time the operation was updated
    "status": "Running",                                    // String version of the operation's status
    "status_code": 103,                                     // Integer version of the operation's status (use this rather than status)
    "resources": {                                          // Dictionary of resource types (container, snapshots, images) and affected resources
      "instances": [
        "/1.0/instances/test"
      ]
    },
    "metadata": {                                           // Metadata specific to the operation in question (in this case, exec)
      "fds": {
        "0": "2a4a97af81529f6608dca31f03a7b7e47acc0b8dc6514496eb25e325f9e4fa6a",
        "control": "5b64c661ef313b423b5317ba9cb6410e40b705806c28255f601c0ef603f079a7"
      }
    },
    "may_cancel": false,                                    // Whether the operation can be canceled (DELETE over REST)
    "err": ""                                               // The error string should the operation have failed
}

主体主要用作一种人性化的方式，可以在不必拉取目标操作的情况下查看正在发生的事情，主体中的所有信息也可以从后台操作 URL 中检索。

错误¶

在某些情况下，某些事情可能会立即出错，在这种情况下，将使用以下返回值

{
    "type": "error",
    "error": "Failure",
    "error_code": 400,
    "metadata": {}                      // More details about the error
}

HTTP 代码必须是 400、401、403、404、409、412 或 500 之一。

状态代码¶

Incus REST API 通常必须返回状态信息，无论是错误的原因、操作的当前状态还是它导出的各种资源的状态。

为了简化调试，所有这些状态都始终是双倍的。状态有一个数字表示，该表示保证永不改变，API 客户端可以依赖它。然后有一个文本版本，旨在使手动使用 API 的人更容易弄清楚发生了什么。

在大多数情况下，这些将被称为 status 和 status_code，前者是人性化的字符串表示，后者是固定的数字值。

代码始终为 3 位数，范围如下

100 到 199：资源状态（已启动、已停止、就绪、…）
200 到 399：正向操作结果
400 到 599：负向操作结果
600 到 999：将来使用

当前状态代码列表¶

代码	含义
100	操作已创建
101	已启动
102	已停止
103	正在运行
104	正在取消
105	挂起
106	正在启动
107	正在停止
108	正在中止
109	正在冻结
110	已冻结
111	已解冻
112	错误
113	就绪
200	成功
400	失败
401	已取消

递归¶

为了优化大型列表的查询，递归已针对集合实现。可以将 recursion 参数传递给针对集合的 GET 查询。

默认值为 0，这意味着将返回集合成员 URL。将其设置为 1 将使这些 URL 被它们指向的对象（通常是另一个 JSON 对象）替换。

递归是通过简单地将指向作业（URL）的任何指针替换为对象本身来实现的。

过滤¶

为了根据特定值过滤结果，已针对集合实现过滤。可以将 filter 参数传递给针对集合的 GET 查询。

实例、镜像和存储卷端点可以使用过滤。

过滤器没有默认值，这意味着将返回找到的所有结果。以下是用作过滤器参数的语言

?filter=field_name eq desired_field_assignment

该语言遵循 OData 约定，用于构建 REST API 过滤逻辑。过滤还支持逻辑运算符：非（not）、等于（eq）、不等于（ne）、和（and）、或（or）。过滤器以左结合性进行计算。包含空格的值可以用引号括起来。也支持嵌套过滤。例如，要根据配置中的字段进行过滤，您需要传递

?filter=config.field_name eq desired_field_assignment

要根据设备属性进行过滤，您需要传递

?filter=devices.device_name.field_name eq desired_field_assignment

以下是一些上述不同过滤方法的 GET 查询示例

containers?filter=name eq "my container" and status eq Running

containers?filter=config.image.os eq ubuntu or devices.eth0.nictype eq bridged

images?filter=Properties.os eq Centos and not UpdateSource.Protocol eq simplestreams

异步操作¶

任何可能需要超过一秒才能完成的操作都必须在后台执行，并将后台操作 ID 返回给客户端。

然后，客户端可以轮询状态更新或使用长轮询 API 等待通知。

通知¶

基于 WebSockets 的 API 可用于通知，存在不同的通知类型以限制发送到客户端的流量。

建议客户端在触发远程操作之前始终订阅操作通知类型，这样它就不必轮询其状态。

PUT 与 PATCH¶

Incus API 支持 PUT 和 PATCH 来修改现有对象。

PUT 用新定义替换整个对象，通常在通过 GET 获取当前对象状态后调用。

为了避免竞争条件，应从 GET 响应中读取 ETag 标头并将其作为 If-Match 发送给 PUT 请求。如果对象在 GET 和 PUT 之间被修改，这将导致 Incus 失败该请求。

PATCH 可用于通过仅指定要更改的属性来修改对象内的单个字段。要取消设置键，将其设置为为空通常就可以了，但在某些情况下，PATCH 无法正常工作，需要使用 PUT 代替。

API 结构¶

Incus 具有一个自动生成的 Swagger 规范，用于描述其 API 端点。此 API 规范的 YAML 版本可以在 rest-api.yaml 中找到。请参阅 REST API，以获取其便捷的 Web 渲染版本。