接口详情
GET /v1/l2-nodes
查询 L2 节点成员或可添加节点
- operationId
listL2Nodes- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：node_scheduling.read
说明（契约原文）
未指定 available 或值为空时，按 sort、display_id 返回该配置的成员（不存在的配置得到空列表）；available=true 时，配置必须存在，返回本作用域未退役且尚未加入任何 L2 配置的节点，按 display_id 排序。两种模式均不分页；available=false 不合法。
参数
listL2Nodes 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
target_scope_id | query | string(uuid) | 否 | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
config_id | query | string(uuid) | 是 | 只允许一个非零配置 UUID。 |
|---|
available | query | string: true / | 否 | 最多出现一次；仅 true 或空字符串合法。 |
|---|
响应
listL2Nodes 响应| 状态码 | 说明 |
|---|
200 | available=true 返回候选节点列表，否则返回成员列表；无数据时 items 为空数组。 |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
401 | Stable error envelope; messages are not localization keys. |
|---|
403 | Stable error envelope; messages are not localization keys. |
|---|
404 | Stable error envelope; messages are not localization keys. |
|---|
503 | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/l2-nodes
批量添加 L2 节点成员
- operationId
addL2Nodes- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：node_scheduling.manage
说明（契约原文）
原子添加 1 至 512 个不重复节点；配置、可选条件和未退役节点必须属于自身作用域。已加入任一 L2 配置的节点冲突返回 409。每个成员初始 revision=1、enabled=true、weight=100，node_ids 排序后 sort 从 0 按 10 递增；不返回 ETag 或 Location。写入受实时管理权限和幂等键约束，If-Match 必须为 "0"。
参数
addL2Nodes 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
target_scope_id | query | string(uuid) | 否 | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
If-Match | header | string | 是 | Must be the single exact quoted value "0". |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
addL2Nodes 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
config_id | string(uuid) | 是 | — |
|---|
node_ids | array<string(uuid)> | 是 | — |
|---|
condition_id | string(uuid) | null | 否 | 同一作用域内未删除的匹配条件；省略或 null 表示不关联条件，零 UUID 不合法。 |
|---|
响应
addL2Nodes 响应| 状态码 | 说明 |
|---|
201 | 返回创建的成员列表或已完成请求的原结果。 字段：items: array<L2Node> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
401 | Stable error envelope; messages are not localization keys. |
|---|
403 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
503 | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
PUT /v1/l2-nodes/{id}
替换 L2 节点成员设置
- operationId
updateL2Node- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：node_scheduling.manage
说明（契约原文）
id 为成员 UUID，不是 node_id。完整替换条件、启用状态、权重和排序并递增修订；省略或传 null 的 condition_id 清除条件。enabled、weight、sort 不可省略或为 null；写入受自身作用域、实时管理权限、修订和幂等键约束。此单项路径不支持 GET。
参数
updateL2Node 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | 非零 L2 节点成员 UUID；不同于节点 node_id。 |
|---|
target_scope_id | query | string(uuid) | 否 | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
If-Match | header | string | 是 | Single quoted positive decimal current revision, for example "3". |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
updateL2Node 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
condition_id | string(uuid) | null | 否 | 同一作用域内未删除的匹配条件；省略或 null 表示不关联条件，零 UUID 不合法。 |
|---|
enabled | boolean | 是 | — |
|---|
weight | integer | 是 | — |
|---|
sort | integer | 是 | — |
|---|
响应
updateL2Node 响应| 状态码 | 说明 |
|---|
200 | 返回更新后的成员对象或已完成请求的原结果。 字段：id: string(uuid) display_id: string tenant_scope_id: string(uuid) config_id: string(uuid) node_id: string(uuid) condition_id: string(uuid) | null condition_name: string | null revision: integer(int64) name: string ip_address: string admin_state: string: pending / active / draining / disabled / retired online_status: string: online / offline / unknown enabled: boolean weight: integer sort: integer |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
401 | Stable error envelope; messages are not localization keys. |
|---|
403 | Stable error envelope; messages are not localization keys. |
|---|
404 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
412 | Stable error envelope; messages are not localization keys. |
|---|
503 | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
DELETE /v1/l2-nodes/{id}
删除 L2 节点成员
- operationId
deleteL2Node- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：node_scheduling.manage
说明（契约原文）
id 为成员 UUID，只软删除成员关系，不删除节点。成功或幂等重放返回 204，无响应体；ETag 保留删除时修订。不存在返回 404，修订冲突返回 412。
参数
deleteL2Node 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | 非零 L2 节点成员 UUID；不同于节点 node_id。 |
|---|
target_scope_id | query | string(uuid) | 否 | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
If-Match | header | string | 是 | Single quoted positive decimal current revision, for example "3". |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
响应
deleteL2Node 响应| 状态码 | 说明 |
|---|
204 | 软删除完成或已完成请求的结果被重放。 |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
401 | Stable error envelope; messages are not localization keys. |
|---|
403 | Stable error envelope; messages are not localization keys. |
|---|
404 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
412 | Stable error envelope; messages are not localization keys. |
|---|
503 | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表