CDNCA

开放接口

/v1/sdk-shield

17 个接口

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

方法路径摘要认证
GET/v1/sdk-shield/appsSDK 应用列表（含今日握手、租户名；租户另带套餐配额）登录会话
POST/v1/sdk-shield/apps新建 SDK 应用，返回应用与第一把 AppSecret（只这一次）登录会话
GET/v1/sdk-shield/apps/{id}SDK 应用详情（含今日握手）登录会话
PATCH/v1/sdk-shield/apps/{id}修改 SDK 应用：名称、状态（停用即拒绝该应用全部新连接）、防护参数登录会话
DELETE/v1/sdk-shield/apps/{id}删除 SDK 应用（须先解绑全部转发），吊销全部密钥登录会话
GET/v1/sdk-shield/apps/{id}/blocks拦截日志：按分钟×节点的失败原因与来源抽样（至多 1 天）登录会话
GET/v1/sdk-shield/apps/{id}/delete-preview删除前确认：应用与绑定的转发数登录会话
GET/v1/sdk-shield/apps/{id}/forwards可绑定的四层转发：作用域内全部转发，带不兼容原因与已绑定应用登录会话
PUT/v1/sdk-shield/apps/{id}/forwards整体替换应用绑定的四层转发（至多 16 条）登录会话
GET/v1/sdk-shield/apps/{id}/keys密钥列表，每把带近 24 小时通过的握手数（旧密钥归零后再吊销）登录会话
POST/v1/sdk-shield/apps/{id}/keys轮换：新增一把密钥（至多 2 把有效），返回 AppSecret（只这一次）登录会话
POST/v1/sdk-shield/apps/{id}/keys/{key_id}/revoke吊销一把密钥；最后一把有效密钥不能吊销（停用应用请改状态）登录会话
GET/v1/sdk-shield/apps/{id}/node-list/preview预览会签发的节点列表（不签名），带节点名、签名密钥与公开地址登录会话
GET/v1/sdk-shield/apps/{id}/stats统计：总数、按原因分布、趋势、来源 Top（带地区/ASN）登录会话
GET/v1/sdk-shield/module读取 SDK 游戏盾模块状态：授权、本机停用、新应用默认值、列表签名公钥、租户配额登录会话
GET/v1/sdk-shield/sdkSDK 下载清单（各语言包、版本、最低版本、大小、SHA-256）与内置公钥；各包下载地址为本主控的鉴权下载路径；开发构建未随包带归档时 packages 为空登录会话
GET/v1/sdk-shield/sdk/files/{name}下载本主控发布版本随包的 SDK 归档（登录并有 module.sdkshield；租户另需套餐含 sdk_shield）；名称取清单中下载地址的最后一段登录会话

契约文件：api/control-sdk-shield.openapi.yaml

接口详情

GET /v1/sdk-shield/apps

SDK 应用列表（含今日握手、租户名；租户另带套餐配额）

operationId
listSDKShieldApps
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

响应

listSDKShieldApps 响应
状态码说明
200Apps

字段：items: array<App> quota?: Quota

401Error
403Error
422Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/sdk-shield/apps

新建 SDK 应用，返回应用与第一把 AppSecret（只这一次）

operationId
createSDKShieldApp
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

A tenant is bounded by limits.sdk_shield_apps (409 sdk_shield_app_limit); an administrator must name tenant_scope_id. Audited sdkshield.app.create.

参数

createSDKShieldApp 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是One key per write; resend it to retry a write whose result was not seen. The same key and request (24 hours, per user and operation) answers the resource it created and creates nothing: a Secret then has replayed true and no app_secret (the secret was only in the first answer). The same key with another request: 409 idempotency_conflict. Missing, malformed or repeated: 422 validation_failed (field Idempotency-Key).

请求体

application/json · 必填：是

createSDKShieldApp 请求体
名称类型必填说明
namestring是—

响应

createSDKShieldApp 响应
状态码说明
201Created

字段：app: App secret: Secret

401Error
403Error
409Error
422Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/apps/{id}

SDK 应用详情（含今日握手）

operationId
getSDKShieldApp
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

参数

getSDKShieldApp 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).

响应

getSDKShieldApp 响应
状态码说明
200App

字段：id: string(uuid) app_id: string name: string tenant: Tenant status: string: active / disabled skew_seconds: integer fail_threshold: integer fail_window_seconds: integer ban_seconds: integer handshake_rate_per_second: integer forward_count: integer(int64) active_key_ids: array<integer> today?: Today revision: integer created_at: string(date-time) updated_at: string(date-time)

401Error
403Error
404Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/sdk-shield/apps/{id}

修改 SDK 应用：名称、状态（停用即拒绝该应用全部新连接）、防护参数

operationId
updateSDKShieldApp
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

status disabled makes every bound forward refuse new connections (app_disabled) after the next publication. expected_revision refuses a stale edit (409 revision_conflict). Audited sdkshield.app.update / disable / enable.

参数

updateSDKShieldApp 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).

请求体

application/json · 必填：是

updateSDKShieldApp 请求体
名称类型必填说明
expected_revisioninteger否—
namestring否—
statusstring: active / disabled否—
skew_secondsinteger否—
fail_thresholdinteger否—
fail_window_secondsinteger否—
ban_secondsinteger否0 = disconnect only
handshake_rate_per_secondinteger否0 = no cap

响应

updateSDKShieldApp 响应
状态码说明
200Updated

字段：id: string(uuid) app_id: string name: string tenant: Tenant status: string: active / disabled skew_seconds: integer fail_threshold: integer fail_window_seconds: integer ban_seconds: integer handshake_rate_per_second: integer forward_count: integer(int64) active_key_ids: array<integer> today?: Today revision: integer created_at: string(date-time) updated_at: string(date-time)

401Error
403Error
404Error
409Error
422Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

DELETE /v1/sdk-shield/apps/{id}

删除 SDK 应用（须先解绑全部转发），吊销全部密钥

operationId
deleteSDKShieldApp
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

Audited sdkshield.app.delete.

参数

deleteSDKShieldApp 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).

响应

deleteSDKShieldApp 响应
状态码说明
204Deleted
401Error
403Error
404Error
409Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/apps/{id}/blocks

拦截日志：按分钟×节点的失败原因与来源抽样（至多 1 天）

operationId
listSDKShieldAppBlocks
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

参数

listSDKShieldAppBlocks 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).
fromquerystring(date-time)否RFC 3339; default 24 hours before to
toquerystring(date-time)否RFC 3339; default now
node_idquerystring(uuid)否Only this node

响应

listSDKShieldAppBlocks 响应
状态码说明
200Blocks, newest first

字段：items: array<BlockMinute>

401Error
403Error
404Error
422Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/apps/{id}/delete-preview

删除前确认：应用与绑定的转发数

operationId
previewSDKShieldAppDelete
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

参数

previewSDKShieldAppDelete 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).

响应

previewSDKShieldAppDelete 响应
状态码说明
200Preview

字段：app: App forward_count: integer(int64) deletable: boolean

401Error
403Error
404Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/apps/{id}/forwards

可绑定的四层转发：作用域内全部转发，带不兼容原因与已绑定应用

operationId
listSDKShieldAppForwards
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

参数

listSDKShieldAppForwards 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).

响应

listSDKShieldAppForwards 响应
状态码说明
200Forwards

字段：items: array<Forward>

401Error
403Error
404Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

PUT /v1/sdk-shield/apps/{id}/forwards

整体替换应用绑定的四层转发（至多 16 条）

operationId
setSDKShieldAppForwards
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

Any incompatible forward refuses the whole change with 422 sdk_shield_forward_incompatible; error.details.forwards lists every one with its reasons (the codes of Forward.incompatible). Binding republishes the scope. Audited sdkshield.forwards.update.

参数

setSDKShieldAppForwards 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).

请求体

application/json · 必填：是

setSDKShieldAppForwards 请求体
名称类型必填说明
forward_idsarray<string(uuid)>是—

响应

setSDKShieldAppForwards 响应
状态码说明
200Bound forwards

字段：forward_ids: array<string(uuid)>

401Error
403Error
404Error
422Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/apps/{id}/keys

密钥列表，每把带近 24 小时通过的握手数（旧密钥归零后再吊销）

operationId
listSDKShieldAppKeys
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

参数

listSDKShieldAppKeys 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).

响应

listSDKShieldAppKeys 响应
状态码说明
200Keys

字段：items: array<Key>

401Error
403Error
404Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/sdk-shield/apps/{id}/keys

轮换：新增一把密钥（至多 2 把有效），返回 AppSecret（只这一次）

operationId
rotateSDKShieldAppKey
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

Audited sdkshield.key.create (key_id only).

参数

rotateSDKShieldAppKey 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是One key per write; resend it to retry a write whose result was not seen. The same key and request (24 hours, per user and operation) answers the resource it created and creates nothing: a Secret then has replayed true and no app_secret (the secret was only in the first answer). The same key with another request: 409 idempotency_conflict. Missing, malformed or repeated: 422 validation_failed (field Idempotency-Key).
idpathstring(uuid)是The app's row id (App.id).

响应

rotateSDKShieldAppKey 响应
状态码说明
201New key

字段：app_id: string key_id: integer app_secret?: string replayed: boolean

401Error
403Error
404Error
409Error
422Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/sdk-shield/apps/{id}/keys/{key_id}/revoke

吊销一把密钥；最后一把有效密钥不能吊销（停用应用请改状态）

operationId
revokeSDKShieldAppKey
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

Nodes refuse it as unknown_key after the next publication; open connections stay. Audited sdkshield.key.revoke.

参数

revokeSDKShieldAppKey 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).
key_idpathinteger是—

响应

revokeSDKShieldAppKey 响应
状态码说明
204Revoked
401Error
403Error
404Error
409Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/apps/{id}/node-list/preview

预览会签发的节点列表（不签名），带节点名、签名密钥与公开地址

operationId
previewSDKShieldNodeList
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

参数

previewSDKShieldNodeList 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).

响应

previewSDKShieldNodeList 响应
状态码说明
200Preview

字段：revision: integer issued_at: string(date-time) | null(date-time) expires_at: string(date-time) | null(date-time) refresh_after: integer skew_seconds: integer signing_key_id: string public_path: string public_url?: string nodes: array<PreviewNode> udp_idle_seconds: object truncated: boolean

401Error
403Error
404Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/apps/{id}/stats

统计：总数、按原因分布、趋势、来源 Top（带地区/ASN）

operationId
getSDKShieldAppStats
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

参数

getSDKShieldAppStats 参数
名称位置类型必填说明
idpathstring(uuid)是The app's row id (App.id).
fromquerystring(date-time)否RFC 3339; default 24 hours before to
toquerystring(date-time)否RFC 3339; default now
node_idquerystring(uuid)否Only this node
bucketquerystring: minute / hour否Trend bucket; default minute up to 6 hours, else hour

响应

getSDKShieldAppStats 响应
状态码说明
200Statistics

字段：from: string(date-time) to: string(date-time) bucket: string: minute / hour totals: Totals reasons: array<ReasonCount> trend: array<TrendPoint> top: array<Source>

401Error
403Error
404Error
422Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/module

读取 SDK 游戏盾模块状态：授权、本机停用、新应用默认值、列表签名公钥、租户配额

operationId
getSDKShieldModule
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

响应

getSDKShieldModule 响应
状态码说明
200Module state

字段：licensed: boolean locally_disabled: boolean defaults: Protection signing_keys: array<SigningKey> quota?: Quota

401Error
403Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/sdk

SDK 下载清单（各语言包、版本、最低版本、大小、SHA-256）与内置公钥；各包下载地址为本主控的鉴权下载路径；开发构建未随包带归档时 packages 为空

operationId
getSDKShieldSDKManifest
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

响应

getSDKShieldSDKManifest 响应
状态码说明
200SDK manifest

字段：packages: array<SDKPackage> signing_keys: array<SigningKey>

401Error
403Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/sdk-shield/sdk/files/{name}

下载本主控发布版本随包的 SDK 归档（登录并有 module.sdkshield；租户另需套餐含 sdk_shield）；名称取清单中下载地址的最后一段

operationId
downloadSDKShieldSDKFile
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

参数

downloadSDKShieldSDKFile 参数
名称位置类型必填说明
namepathstring是Archive file name, the last segment of SDKPackage.url

响应

downloadSDKShieldSDKFile 响应
状态码说明
200The archive (Content-Disposition attachment; X-Content-SHA256 is its digest, as in the manifest)
401Error
403Error
404Error
503Error

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表