cdnca

开放接口

/v1/stream-groups

4 个接口 · 4 个接口支持 API Key

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
GET/v1/stream-groupsList layer-four forwarding groupsAPI Key 可调登录会话
POST/v1/stream-groupsCreate a layer-four forwarding groupAPI Key 可调登录会话
PATCH/v1/stream-groups/{id}Rename a layer-four forwarding groupAPI Key 可调登录会话
DELETE/v1/stream-groups/{id}Delete an unreferenced layer-four forwarding groupAPI Key 可调登录会话

契约文件：api/control-l4-forward.openapi.yaml

接口详情

GET /v1/stream-groups

List layer-four forwarding groups

operationId
listStreamGroups
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

说明（契约原文）

Tenant principals see only groups owned by their current user and tenant. Platform principals can list tenant groups after streams.read authorization.

参数

listStreamGroups 参数
名称位置类型必填说明
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
pagequeryinteger否—
limitqueryinteger否—
searchquerystring否—

响应

listStreamGroups 响应
状态码说明
200Stable page ordered newest first; stream_count counts live member rules.

字段：items: array<StreamGroup> total: integer(int64) page: integer limit: integer

400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/stream-groups

Create a layer-four forwarding group

operationId
createStreamGroup
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

Tenant principals are fixed to their current scope and user. Platform principals must provide target_scope_id and owner_id. Group membership alone never advances the edge configuration revision.

参数

createStreamGroup 参数
名称位置类型必填说明
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
Idempotency-Keyheaderstring是Reuse is accepted only for the exact same actor, operation, and normalized input.

请求体

application/json · 必填：是

createStreamGroup 请求体
名称类型必填说明
namestring是—
remarkstring否—
target_scope_idstring(uuid)否Required for platform principals; tenant principals may omit it or use their current scope.
owner_idstring(uuid)否Required for platform principals; tenant principals may omit it or use their current user.

响应

createStreamGroup 响应
状态码说明
201Group committed, or an exact idempotent replay returned.

字段：id: string(uuid) display_id: string scope_id: string(uuid) owner: StreamOwner | null name: string remark: string stream_count: integer(int64) revision: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
409Revision, idempotency, name, or listener-port conflict.
415Exactly one Content-Type field parsing as application/json is required.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/stream-groups/{id}

Rename a layer-four forwarding group

operationId
updateStreamGroup
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

参数

updateStreamGroup 参数
名称位置类型必填说明
idpathstring(uuid)是Exact forward group identity.
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
Idempotency-Keyheaderstring是Reuse is accepted only for the exact same actor, operation, and normalized input.
If-Matchheaderstring是Quoted positive current resource revision.

请求体

application/json · 必填：是

updateStreamGroup 请求体
名称类型必填说明
namestring是—
remarkstring否—
expected_revisioninteger(int64)是Must exactly equal the quoted If-Match revision.

响应

updateStreamGroup 响应
状态码说明
200Group updated, or an exact idempotent replay returned.

字段：id: string(uuid) display_id: string scope_id: string(uuid) owner: StreamOwner | null name: string remark: string stream_count: integer(int64) revision: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
404No visible stream matches the exact immutable stream identity.
409Revision, idempotency, name, or listener-port conflict.
415Exactly one Content-Type field parsing as application/json is required.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

DELETE /v1/stream-groups/{id}

Delete an unreferenced layer-four forwarding group

operationId
deleteStreamGroup
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

参数

deleteStreamGroup 参数
名称位置类型必填说明
idpathstring(uuid)是Exact forward group identity.
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
Idempotency-Keyheaderstring是Reuse is accepted only for the exact same actor, operation, and normalized input.
If-Matchheaderstring是Quoted positive current resource revision.

响应

deleteStreamGroup 响应
状态码说明
204Group deleted after detaching nothing; still-referenced groups conflict.
400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
404No visible stream matches the exact immutable stream identity.
409Revision, idempotency, name, or listener-port conflict.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表