接口详情
GET /v1/node-line-groups
查询线路组当前修订列表
- operationId
listNodeLineGroups- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
listNodeLineGroups 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
响应
listNodeLineGroups 响应| 状态码 | 说明 |
|---|
200 | Current immutable revision of every visible line group. 字段：items: array<LineGroupRevision> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。
↑ 回到列表
POST /v1/node-line-groups
创建线路组首个不可变修订
- operationId
createNodeLineGroup- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
租户会话管理自身作用域；平台会话未指定 target_scope_id 时管理本主控平台作用域，显式指定租户作用域时拒绝写入。
参数
createNodeLineGroup 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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 · 必填：是
createNodeLineGroup 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
region | string | 否 | — |
|---|
resolved_value | string | 否 | 留空时由服务端生成稳定的小写 DNS 标签；不要填写域名后缀、端口或 IP。 |
|---|
ipv4_resolved_value | string | 否 | IPv4 专用解析值；留空时由服务端按线路组 ID 生成稳定的小写 DNS 标签。 |
|---|
l2_config_id | string(uuid) | null(uuid) | 否 | 同一作用域、同一区域且未引用其他 L2 配置的活动线路组；为空表示独立线路组。 |
|---|
failover_mode | string: primary_offline / online_less_than_backup_count | 否 | 有主IP下线时逐个启用备用IP，或在线主IP数少于备用IP数时启用全部备用IP。 |
|---|
note | string | 否 | — |
|---|
sort_order | integer(int32) | 否 | — |
|---|
health_policy | HealthPolicy | 是 | — |
|---|
endpoints | array<EndpointWrite> | 是 | — |
|---|
响应
createNodeLineGroup 响应| 状态码 | 说明 |
|---|
201 | Revision 1 created. ETag is a quoted decimal revision. 字段：group: LineGroupRevision replayed: boolean |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
GET /v1/node-line-groups/{id}
查询线路组当前修订
- operationId
getNodeLineGroup- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
getNodeLineGroup 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
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. |
|---|
响应
getNodeLineGroup 响应| 状态码 | 说明 |
|---|
200 | Current immutable revision. 字段：id: string(uuid) display_id: string tenant_scope_id: string(uuid) revision: integer(int64) name: string region: string resolved_value: string ipv4_resolved_value: string l2_config_id: string(uuid) | null(uuid) failover_mode: string: primary_offline / online_less_than_backup_count note: string sort_order: integer(int32) health_policy: HealthPolicy endpoints: array<Endpoint> statistics?: LineGroupStatistics configuration_digest: string created_by_user_id: string(uuid) created_at: string(date-time) sealed_at: string(date-time) is_platform_default?: boolean backup_states?: array<LineBackupState> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。
↑ 回到列表
PUT /v1/node-line-groups/{id}
创建线路组下一不可变修订
- operationId
updateNodeLineGroup- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
租户会话管理自身作用域；平台会话未指定 target_scope_id 时管理本主控平台作用域，显式指定租户作用域时拒绝写入。
参数
updateNodeLineGroup 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
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 · 必填：是
updateNodeLineGroup 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
region | string | 否 | — |
|---|
resolved_value | string | 否 | 留空时由服务端生成稳定的小写 DNS 标签；不要填写域名后缀、端口或 IP。 |
|---|
ipv4_resolved_value | string | 否 | IPv4 专用解析值；留空时由服务端按线路组 ID 生成稳定的小写 DNS 标签。 |
|---|
l2_config_id | string(uuid) | null(uuid) | 否 | 同一作用域、同一区域且未引用其他 L2 配置的活动线路组；为空表示独立线路组。 |
|---|
failover_mode | string: primary_offline / online_less_than_backup_count | 否 | 有主IP下线时逐个启用备用IP，或在线主IP数少于备用IP数时启用全部备用IP。 |
|---|
note | string | 否 | — |
|---|
sort_order | integer(int32) | 否 | — |
|---|
health_policy | HealthPolicy | 是 | — |
|---|
endpoints | array<EndpointWrite> | 是 | — |
|---|
响应
updateNodeLineGroup 响应| 状态码 | 说明 |
|---|
200 | New immutable current revision. 字段：group: LineGroupRevision replayed: boolean |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
DELETE /v1/node-line-groups/{id}
软删除线路组并保留不可变修订历史
- operationId
deleteNodeLineGroup- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
租户会话删除自身作用域线路组；平台会话未指定 target_scope_id 时删除本主控平台作用域线路组，显式指定租户作用域时返回 403。删除后列表、当前详情、历史详情、探测与新拓扑快照入口均不可见；同一幂等键可重放。
参数
deleteNodeLineGroup 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
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 | 是 | — |
|---|
响应
deleteNodeLineGroup 响应| 状态码 | 说明 |
|---|
204 | Soft deletion completed or the stored result was replayed. |
|---|
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. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
POST /v1/node-line-groups/{id}/decisions
计算可审计的区域健康调度决策
- operationId
decideNodeLineGroupEndpoint- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
decideNodeLineGroupEndpoint 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
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. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
decideNodeLineGroupEndpoint 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
selector | Selector | 是 | — |
|---|
requested_mode | string: weighted_baseline / weighted_rendezvous / p2c_least_loaded | 是 | — |
|---|
stable_key | string | 是 | — |
|---|
响应
decideNodeLineGroupEndpoint 响应| 状态码 | 说明 |
|---|
200 | Deterministic selection with auditable reason and fallback state. 字段：endpoint: Endpoint requested_mode: string: weighted_baseline / weighted_rendezvous / p2c_least_loaded effective_mode: string: weighted_baseline / weighted_rendezvous / p2c_least_loaded reason: string: baseline_weighted_selected / weighted_rendezvous_selected / p2c_least_loaded_selected / telemetry_insufficient / telemetry_stale_fallback / telemetry_unavailable_fallback / single_candidate_fallback / no_healthy_endpoint fallback: boolean priority: integer candidates: array<Endpoint> standby: array<Endpoint> snapshot: DecisionSnapshot |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。
↑ 回到列表
设为或取消平台默认线路组
- operationId
setNodeLineGroupPlatformDefault- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
只限平台作用域普通线路组；设为默认会取消原默认。不推进线路组修订。没选套餐的网站用它冻结 CNAME 目标 IP。
参数
setNodeLineGroupPlatformDefault 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
setNodeLineGroupPlatformDefault 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
is_platform_default | boolean | 是 | — |
|---|
响应
setNodeLineGroupPlatformDefault 响应| 状态码 | 说明 |
|---|
200 | Current line group with the new platform default flag. 字段：group: LineGroupRevision |
|---|
400 | 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. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。
↑ 回到列表
GET /v1/node-line-groups/{id}/revisions/{revision}
查询线路组历史修订
- operationId
getNodeLineGroupRevision- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
getNodeLineGroupRevision 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
revision | path | integer(int64) | 是 | — |
|---|
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. |
|---|
响应
getNodeLineGroupRevision 响应| 状态码 | 说明 |
|---|
200 | Historical immutable revision. 字段：id: string(uuid) display_id: string tenant_scope_id: string(uuid) revision: integer(int64) name: string region: string resolved_value: string ipv4_resolved_value: string l2_config_id: string(uuid) | null(uuid) failover_mode: string: primary_offline / online_less_than_backup_count note: string sort_order: integer(int32) health_policy: HealthPolicy endpoints: array<Endpoint> statistics?: LineGroupStatistics configuration_digest: string created_by_user_id: string(uuid) created_at: string(date-time) sealed_at: string(date-time) is_platform_default?: boolean backup_states?: array<LineBackupState> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。
↑ 回到列表
POST /v1/node-line-groups/{id}/rollback
将历史配置复制为新的当前修订
- operationId
rollbackNodeLineGroup- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
rollbackNodeLineGroup 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
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 · 必填：是
rollbackNodeLineGroup 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
source_revision | integer(int64) | 是 | — |
|---|
响应
rollbackNodeLineGroup 响应| 状态码 | 说明 |
|---|
200 | Historical configuration copied into current revision plus one. 字段：group: LineGroupRevision replayed: boolean |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
GET /v1/node-line-groups/{id}/target-snapshots
按来源修订查询 L1/L2 拓扑快照
- operationId
getNodeLineGroupTargetSnapshot- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
getNodeLineGroupTargetSnapshot 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
source_revision | query | integer(int64) | 是 | Single positive decimal source line-group revision. |
|---|
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. |
|---|
响应
getNodeLineGroupTargetSnapshot 响应| 状态码 | 说明 |
|---|
200 | Immutable L1 target set bound to the requested L2 source revision. 字段：id: string(uuid) revision: integer(int64) tenant_scope_id: string(uuid) source_line_group_id: string(uuid) source_revision: integer(int64) source_configuration_digest: string node_set_digest: string node_ids: array<string(uuid)> |
|---|
400 | 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. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。
↑ 回到列表
POST /v1/node-line-groups/{id}/target-snapshots
创建 L1 目标与 L2 候选拓扑快照
- operationId
createNodeLineGroupTargetSnapshot- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
createNodeLineGroupTargetSnapshot 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
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. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createNodeLineGroupTargetSnapshot 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
source_revision | integer(int64) | 是 | — |
|---|
node_ids | array<string(uuid)> | 是 | L1 target nodes. Every target has an edge to every L2 endpoint node in the source revision. |
|---|
响应
createNodeLineGroupTargetSnapshot 响应| 状态码 | 说明 |
|---|
201 | Immutable L1 target set bound to an immutable L2 source revision. 字段：id: string(uuid) revision: integer(int64) tenant_scope_id: string(uuid) source_line_group_id: string(uuid) source_revision: integer(int64) source_configuration_digest: string node_set_digest: string node_ids: array<string(uuid)> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。
↑ 回到列表