cdnca

开放接口

/v1/site-groups

5 个接口

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

方法路径摘要认证
GET/v1/site-groupsList site groups登录会话
POST/v1/site-groupsCreate a site group登录会话
GET/v1/site-groups/{id}Read one exact active site group in an authorized tenant scope登录会话
PATCH/v1/site-groups/{id}Rename a site group登录会话
DELETE/v1/site-groups/{id}Delete an unused site group登录会话

契约文件：api/control-site-groups.openapi.yaml

接口详情

GET /v1/site-groups

List site groups

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

全部需要：sites.read

参数

listSiteGroups 参数
名称位置类型必填说明
scope_idquerystring(uuid)是—
pagequeryinteger否—
limitqueryinteger否—

响应

listSiteGroups 响应
状态码说明
200Active groups ordered by creation time and ID.

字段：items: array<SiteGroup> total: integer page: integer limit: integer

400Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}.
401Authentication required.
403Permission denied.
503Site group service unavailable.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/site-groups

Create a site group

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

全部需要：sites.manage

参数

createSiteGroup 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createSiteGroup 请求体
名称类型必填说明
target_scope_idstring(uuid)是—
namestring是—
remarkstring否Optional; omission creates an empty remark and preserves the legacy request digest. Null is invalid.

响应

createSiteGroup 响应
状态码说明
201Created group or an exact completed request replay.

字段：id: string(uuid) scope_id: string(uuid) name: string remark?: string display_id?: string revision: integer created_at: string(date-time) updated_at: string(date-time) deleted_at?: string(date-time) | null(date-time)

400Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}.
401Authentication required.
403Permission denied.
409Revision, idempotency, name, or in-use conflict.
503Site group service unavailable.

失败时怎么办

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

↑ 回到列表

GET /v1/site-groups/{id}

Read one exact active site group in an authorized tenant scope

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

全部需要：sites.read

参数

getSiteGroup 参数
名称位置类型必填说明
idpathstring(uuid)是—
scope_idquerystring(uuid)是—

响应

getSiteGroup 响应
状态码说明
200Current group including its real display ID and remark. A newer revision must not be mistaken for exact write readback.

字段：id: string(uuid) scope_id: string(uuid) name: string remark?: string display_id?: string revision: integer created_at: string(date-time) updated_at: string(date-time) deleted_at?: string(date-time) | null(date-time)

400Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}.
401Authentication required.
403Permission denied.
404Site group not found.
503Site group service unavailable.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/site-groups/{id}

Rename a site group

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

全部需要：sites.manage

参数

renameSiteGroup 参数
名称位置类型必填说明
idpathstring(uuid)是—
scope_idquerystring(uuid)是—
If-Matchheaderstring是—
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

renameSiteGroup 请求体
名称类型必填说明
expected_revisioninteger是—
namestring是—
remarkstring否Omission preserves the current remark and legacy digest. An explicit empty string clears it. Null is invalid.

响应

renameSiteGroup 响应
状态码说明
200Renamed group or an exact completed request replay.

字段：id: string(uuid) scope_id: string(uuid) name: string remark?: string display_id?: string revision: integer created_at: string(date-time) updated_at: string(date-time) deleted_at?: string(date-time) | null(date-time)

400Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}.
401Authentication required.
403Permission denied.
404Site group not found.
409Revision, idempotency, name, or in-use conflict.
503Site group service unavailable.

失败时怎么办

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

↑ 回到列表

DELETE /v1/site-groups/{id}

Delete an unused site group

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

全部需要：sites.manage

参数

deleteSiteGroup 参数
名称位置类型必填说明
idpathstring(uuid)是—
scope_idquerystring(uuid)是—
If-Matchheaderstring是—
Idempotency-Keyheaderstring是—

响应

deleteSiteGroup 响应
状态码说明
204Group deleted or an exact completed request replay.
400Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}.
401Authentication required.
403Permission denied.
404Site group not found.
409Revision, idempotency, name, or in-use conflict.
503Site group service unavailable.

失败时怎么办

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

↑ 回到列表