接口详情
GET /v1/site-publications
List publications in the authenticated tenant scope
- operationId
listTenantSitePublications- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a tenant-scoped principal with sites.read. scope_id is not accepted. Signatures, hashes, target snapshot metadata, and platform scope identifiers are omitted from tenant responses.
参数
listTenantSitePublications 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Versioned base64url HMAC-SHA256 envelope returned by the immediately preceding page. It is bound to audience, resolved tenant scope, resource kind, and the rollout ID for deployment pages. It cannot be reused across those boundaries or modified. |
|---|
响应
listTenantSitePublications 响应| 状态码 | 说明 |
|---|
200 | Stable tenant publication page with target metadata redacted. 字段：items: array<TenantPublication> current_source_revision: integer(int64) next_cursor?: string pending_modules?: array<PendingModule> automatic_failure?: AutomaticPublicationFailure |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/site-publications
Publish the authenticated tenant scope
- operationId
publishTenantSiteConfiguration- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.manage
说明（契约原文）
Requires a tenant session with sites.manage. configuration_scope_id must exactly equal the authenticated scope; authorization and scope binding complete before any publication mutation.
参数
publishTenantSiteConfiguration 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Correlation-ID | header | string(uuid) | 否 | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | 否 | — |
|---|
请求体
application/json · 必填：是
publishTenantSiteConfiguration 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
configuration_scope_id | string(uuid) | 是 | — |
|---|
expected_source_revision | integer(int64) | 是 | — |
|---|
target | ExplicitNodeTarget | LineGroupSnapshotTarget | 是 | — |
|---|
health_check | HealthCheck | 是 | — |
|---|
rollout | RolloutPolicyInput | 否 | Progressive policy for a target frozen at publication time. Nodes are ordered by UUID bytes, then assigned to the canary and fixed-size cohorts. Commands outside the released cohort remain held. The failure threshold is an absolute failed-node count within the current cohort; reaching it pauses the rollout. |
|---|
max_attempts | integer | 是 | — |
|---|
deadline | string(date-time) | 是 | Future RFC3339 deployment deadline. |
|---|
响应
publishTenantSiteConfiguration 响应| 状态码 | 说明 |
|---|
201 | Created tenant publication, or the stored result of an identical retry. 字段：id: string(uuid) source_revision: integer(int64) config_version_id: string(uuid) rollout_id: string(uuid) target: TenantPublicationTarget node_count: integer created_at: string(date-time) |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
412 | The source or rollout expected revision is stale. |
|---|
422 | Entitlement or target/resource readiness prevents publication. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/site-publications/security-activations
Get the authoritative security binding and latest activation candidate
- operationId
getSecurityPolicyActivationStatus- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
说明（契约原文）
Requires security_policies.read in the authenticated tenant scope, or a platform session holding security_policies.read or platform.admin, which reads the site's own tenant scope (the site edit page of the platform console). When no binding exists, binding, latest_candidate, and operation are null; clients use binding and active-policy CAS values 0/0 for first publish.
参数
getSecurityPolicyActivationStatus 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
site_id | query | string(uuid) | 是 | — |
|---|
policy_kind | query | string: cc / acl / waf | 是 | — |
|---|
响应
getSecurityPolicyActivationStatus 响应| 状态码 | 说明 |
|---|
200 | Authoritative binding and latest candidate from one permission-checked transaction. 字段：binding: SecurityActivationBinding | null latest_candidate: SecurityActivationCandidate | null operation: string: activation / rollback / null | null: activation / rollback / null failure_reasons?: array<object> latest_detach?: boolean rollback?: object |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/site-publications/security-activations
Stage a security policy candidate and start its canary rollout
- operationId
createSecurityPolicyActivation- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
说明（契约原文）
Requires security_policies.manage in the authenticated tenant scope. A platform session holding security_policies.manage or platform.admin starts it in the site's tenant scope without switching identity; the candidate and the audit event record the platform actor, the audit event's scope is the site's tenant scope. The candidate pins one source revision, config version, signed artifact digest, and target snapshot. The active policy and source revision do not advance until every pinned target reports healthy.
参数
createSecurityPolicyActivation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Correlation-ID | header | string(uuid) | 否 | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | 否 | — |
|---|
请求体
application/json · 必填：是
createSecurityPolicyActivation 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
site_id | string(uuid) | 是 | — |
|---|
policy_id | string(uuid) | 是 | — |
|---|
policy_version | integer(int64) | 是 | — |
|---|
expected_binding_revision | integer(int64) | 是 | — |
|---|
expected_active_policy_version | integer(int64) | 是 | — |
|---|
target_node_ids | array<string(uuid)> | 否 | Omitted or empty targets the active nodes of the site's own and its package's primary/backup line groups (no_target_nodes when there are none). |
|---|
canary_size | integer | 否 | 0 or omitted is 1 when the targets are resolved from the site. |
|---|
expires_at | string(date-time) | 是 | At most 15 minutes ahead (activation_expiry_too_late). |
|---|
detach | boolean | 否 | Withdraw the site's active library of this kind (policy_id/policy_version are the binding's active ones; the library may be deleted). policy_id differing from the binding's library rebinds the site to it; a deleted library cannot be bound (security_policy_deleted). |
|---|
响应
createSecurityPolicyActivation 响应| 状态码 | 说明 |
|---|
201 | Candidate claimed and immutable canary rollout created. 字段：candidate: SecurityActivationCandidate replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
422 | Entitlement or target/resource readiness prevents publication. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/site-publications/security-activations/rebind-status
Count bound sites still behind their WAF/CC library and those the package does not entitle
- operationId
getSecurityPolicyRebindStatus- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
说明（契约原文）
Requires security_policies.read in the authenticated tenant scope; a platform session is refused (403), it has no tenant scope to count. A library saved without a site context is republished automatically to every bound site whose binding is behind it (the site's package primary/backup line-group nodes, canary first). pending_sites counts the scope's sites still behind for policy_kind; package_denied_sites counts those whose package does not include the feature (they are retried and publish once it is enabled).
参数
getSecurityPolicyRebindStatus 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
policy_kind | query | string: waf / cc | 是 | — |
|---|
响应
getSecurityPolicyRebindStatus 响应| 状态码 | 说明 |
|---|
200 | Counts of the authenticated scope only. 字段：pending_sites: integer package_denied_sites: integer |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/site-publications/security-activations/{candidate_id}
Get a security policy activation candidate
- operationId
getSecurityPolicyActivation- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
参数
getSecurityPolicyActivation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
candidate_id | path | string(uuid) | 是 | — |
|---|
响应
getSecurityPolicyActivation 响应| 状态码 | 说明 |
|---|
200 | Current persisted candidate identity and status. 字段：id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) binding_id: string(uuid) binding_revision: integer(int64) last_bundle_id: string(uuid) last_claimed_policy_version: integer(int64) expected_active_policy_version: integer(int64) candidate_source_revision: integer(int64) candidate_config_version_id: string(uuid) candidate_artifact_sha256: array<integer> target_snapshot_sha256: array<integer> required_capabilities: array<SecurityActivationCapability> candidate_status: string: claimed / canary / expanding / healthy / failed / cancelled / expired / promoted canary_node_ids: array<string(uuid)> expand_node_ids: array<string(uuid)> expires_at: string(date-time) created_at: string(date-time) updated_at: string(date-time) recovered_at?: string(date-time) |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/site-publications/security-activations/{candidate_id}/reconcile
Reconcile canary, expansion, recovery, and promotion
- operationId
reconcileSecurityPolicyActivation- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
说明（契约原文）
Reuses the candidate config and artifact digest for every phase. Promotion uses the complete expected active, binding, publication, config, artifact, source revision, and target snapshot CAS identity.
参数
reconcileSecurityPolicyActivation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
candidate_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Correlation-ID | header | string(uuid) | 否 | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | 否 | — |
|---|
请求体
application/json · 必填：是
reconcileSecurityPolicyActivation 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
promotion_cas | SecurityActivationPromotionCAS | 是 | — |
|---|
响应
reconcileSecurityPolicyActivation 响应| 状态码 | 说明 |
|---|
200 | Reconciled candidate state or identical stored replay. 字段：candidate: SecurityActivationCandidate action: string: / wait / expand / promote / recover / fail / cancel / expire replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/site-publications/security-activations/{candidate_id}/rollback
Clone an old policy into a new monotonic version and stage it
- operationId
rollbackSecurityPolicyActivation- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
rollbackSecurityPolicyActivation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
candidate_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Correlation-ID | header | string(uuid) | 否 | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | 否 | — |
|---|
请求体
application/json · 必填：是
rollbackSecurityPolicyActivation 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
source_policy_version | integer(int64) | 是 | — |
|---|
expected_binding_revision | integer(int64) | 是 | — |
|---|
expected_active_policy_version | integer(int64) | 是 | — |
|---|
target_node_ids | array<string(uuid)> | 否 | Omitted or empty targets the candidate site's line-group nodes, as SecurityActivationCreateRequest. |
|---|
canary_size | integer | 否 | — |
|---|
expires_at | string(date-time) | 是 | At most 15 minutes ahead (activation_expiry_too_late). |
|---|
响应
rollbackSecurityPolicyActivation 响应| 状态码 | 说明 |
|---|
201 | New monotonic rollback candidate claimed. 字段：candidate: SecurityActivationCandidate replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/site-publications/{publication_id}
Get one publication in the authenticated tenant scope
- operationId
getTenantSitePublication- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
getTenantSitePublication 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
publication_id | path | string(uuid) | 是 | — |
|---|
响应
getTenantSitePublication 响应| 状态码 | 说明 |
|---|
200 | Tenant publication detail with internal metadata redacted. 字段：id: string(uuid) source_revision: integer(int64) config_version_id: string(uuid) rollout_id: string(uuid) target: TenantPublicationTarget node_count: integer created_at: string(date-time) |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表