Operation details
GET /v1/l2-nodes
查询 L2 节点成员或可添加节点
- operationId
listL2Nodes- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：node_scheduling.read
Description (from the contract)
未指定 available 或值为空时，按 sort、display_id 返回该配置的成员（不存在的配置得到空列表）；available=true 时，配置必须存在，返回本作用域未退役且尚未加入任何 L2 配置的节点，按 display_id 排序。两种模式均不分页；available=false 不合法。
Parameters
listL2Nodes Parameters| Name | In | Type | Required | Description |
|---|
target_scope_id | query | string(uuid) | No | 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) | Yes | 只允许一个非零配置 UUID。 |
|---|
available | query | string: true / | No | 最多出现一次；仅 true 或空字符串合法。 |
|---|
Responses
listL2Nodes Responses| Status | Description |
|---|
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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/l2-nodes
批量添加 L2 节点成员
- operationId
addL2Nodes- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：node_scheduling.manage
Description (from the contract)
原子添加 1 至 512 个不重复节点；配置、可选条件和未退役节点必须属于自身作用域。已加入任一 L2 配置的节点冲突返回 409。每个成员初始 revision=1、enabled=true、weight=100，node_ids 排序后 sort 从 0 按 10 递增；不返回 ETag 或 Location。写入受实时管理权限和幂等键约束，If-Match 必须为 "0"。
Parameters
addL2Nodes Parameters| Name | In | Type | Required | Description |
|---|
target_scope_id | query | string(uuid) | No | 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 | Yes | Must be the single exact quoted value "0". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
addL2Nodes Request body| Name | Type | Required | Description |
|---|
config_id | string(uuid) | Yes | — |
|---|
node_ids | array<string(uuid)> | Yes | — |
|---|
condition_id | string(uuid) | null | No | 同一作用域内未删除的匹配条件；省略或 null 表示不关联条件，零 UUID 不合法。 |
|---|
Responses
addL2Nodes Responses| Status | Description |
|---|
201 | 返回创建的成员列表或已完成请求的原结果。 Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
PUT /v1/l2-nodes/{id}
替换 L2 节点成员设置
- operationId
updateL2Node- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：node_scheduling.manage
Description (from the contract)
id 为成员 UUID，不是 node_id。完整替换条件、启用状态、权重和排序并递增修订；省略或传 null 的 condition_id 清除条件。enabled、weight、sort 不可省略或为 null；写入受自身作用域、实时管理权限、修订和幂等键约束。此单项路径不支持 GET。
Parameters
updateL2Node Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | 非零 L2 节点成员 UUID；不同于节点 node_id。 |
|---|
target_scope_id | query | string(uuid) | No | 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 | Yes | Single quoted positive decimal current revision, for example "3". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
updateL2Node Request body| Name | Type | Required | Description |
|---|
condition_id | string(uuid) | null | No | 同一作用域内未删除的匹配条件；省略或 null 表示不关联条件，零 UUID 不合法。 |
|---|
enabled | boolean | Yes | — |
|---|
weight | integer | Yes | — |
|---|
sort | integer | Yes | — |
|---|
Responses
updateL2Node Responses| Status | Description |
|---|
200 | 返回更新后的成员对象或已完成请求的原结果。 Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
DELETE /v1/l2-nodes/{id}
删除 L2 节点成员
- operationId
deleteL2Node- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：node_scheduling.manage
Description (from the contract)
id 为成员 UUID，只软删除成员关系，不删除节点。成功或幂等重放返回 204，无响应体；ETag 保留删除时修订。不存在返回 404，修订冲突返回 412。
Parameters
deleteL2Node Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | 非零 L2 节点成员 UUID；不同于节点 node_id。 |
|---|
target_scope_id | query | string(uuid) | No | 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 | Yes | Single quoted positive decimal current revision, for example "3". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Responses
deleteL2Node Responses| Status | Description |
|---|
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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list