方法路径摘要认证
GET/v1/admin/site-rolloutsList rollouts for one tenant scope登录会话
POST/v1/admin/site-rollouts/reconciliationsRecord the configuration proven to be active after an uncertain deployment result登录会话
GET/v1/admin/site-rollouts/{rollout_id}Get deterministic rollout progress for one tenant scope登录会话
POST/v1/admin/site-rollouts/{rollout_id}/cancelCancel queued work in a rollout登录会话
GET/v1/admin/site-rollouts/{rollout_id}/deploymentsList latest per-node deployment attempts登录会话
POST/v1/admin/site-rollouts/{rollout_id}/pausePause a running progressive rollout登录会话
POST/v1/admin/site-rollouts/{rollout_id}/resumeResume a paused progressive rollout登录会话
POST/v1/admin/site-rollouts/{rollout_id}/retry-failedAppend attempts for retryable failed deployments登录会话
POST/v1/admin/site-rollouts/{rollout_id}/startStart a held progressive rollout登录会话

契约文件:api/control-site-publications.openapi.yaml

接口详情

GET /v1/admin/site-rollouts

List rollouts for one tenant scope

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

全部需要:edge_publications.read

参数

listAdminSiteRollouts 参数
名称位置类型必填说明
scope_idquerystring(uuid)是Platform route target tenant access-scope UUID.
limitqueryinteger否—
cursorquerystring否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.

响应

listAdminSiteRollouts 响应
状态码说明
200Stable platform rollout page.

字段:items: array<AdminRollout> next_cursor?: string

400Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body.
401Authentication is missing or invalid.
403Wrong audience, missing permission, or tenant scope override.
503Storage, signing, cancellation, response validation, or another internal dependency is unavailable.

失败时怎么办

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

↑ 回到列表

POST /v1/admin/site-rollouts/reconciliations

Record the configuration proven to be active after an uncertain deployment result

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

全部需要:edge_publications.manage

说明(契约原文)

Clears the rollback_failed reconciliation gate only when the named node, tenant scope, source deployment attempt, and observed immutable config all match persisted facts. It also permits operator-confirmed recovery of a legacy failed apply only when the deployment artifact, previous identity, fresh mTLS heartbeat pointer chain, missing current/loaded identity, stopped conservative OpenResty projection, and absence of active deployments all agree. That recovery moves only the version pointers; the next healthy publication establishes the current immutable identity. The append-only reconciliation record, live IAM authorization, node-state update, and audit event commit atomically. Retrying with the same Idempotency-Key returns the same fact; changing the payload with that key returns 409.

参数

reconcileAdminNodeConfiguration 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry.
X-Request-IDheaderstring(uuid)是—
Traceparentheaderstring是—
X-Correlation-IDheaderstring(uuid)否Defaults to X-Request-ID when omitted.
X-Task-IDheaderstring否—

请求体

application/json · 必填:是

reconcileAdminNodeConfiguration 请求体
名称类型必填说明
configuration_scope_idstring(uuid)是—
node_idstring(uuid)是—
source_deployment_idstring(uuid)是—
source_deployment_attemptinteger(int32)是—
observed_config_version_idstring(uuid) | null是—
resolutionstring: agent_observed / operator_confirmed是—
evidencestring是—

响应

reconcileAdminNodeConfiguration 响应
状态码说明
201Created reconciliation fact, or the stored result of an identical retry.

字段:id: string(uuid) node_id: string(uuid) configuration_scope_id: string(uuid) source_deployment_id: string(uuid) source_deployment_attempt: integer(int32) previous_config_version_id: string(uuid) | null current_config_version_id: string(uuid) | null resolution: string: agent_observed / operator_confirmed reconciliation_required: boolean reconciled_at: string(date-time)

400Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body.
401Authentication is missing or invalid.
403Wrong audience, missing permission, or tenant scope override.
404Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response.
409Idempotency, target snapshot, rollout state, active deployment, or retry conflict.
503Storage, signing, cancellation, response validation, or another internal dependency is unavailable.

失败时怎么办

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

↑ 回到列表

GET /v1/admin/site-rollouts/{rollout_id}

Get deterministic rollout progress for one tenant scope

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

全部需要:edge_publications.read

参数

getAdminSiteRollout 参数
名称位置类型必填说明
rollout_idpathstring(uuid)是—
scope_idquerystring(uuid)是Platform route target tenant access-scope UUID.

响应

getAdminSiteRollout 响应
状态码说明
200Platform rollout detail derived from latest deployment attempts.

字段:id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean

400Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body.
401Authentication is missing or invalid.
403Wrong audience, missing permission, or tenant scope override.
404Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response.
503Storage, signing, cancellation, response validation, or another internal dependency is unavailable.

失败时怎么办

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

↑ 回到列表

POST /v1/admin/site-rollouts/{rollout_id}/cancel

Cancel queued work in a rollout

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

全部需要:edge_publications.manage

说明(契约原文)

Progressive cancellation marks held or unclaimed commands and their queued deployment facts cancelled; already claimed or in-flight work may still report durable terminal facts. Legacy rollouts retain their all-pending precondition. Uses rollout revision CAS and idempotency.

参数

cancelSiteRollout 参数
名称位置类型必填说明
rollout_idpathstring(uuid)是—
Idempotency-Keyheaderstring是Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry.
X-Request-IDheaderstring(uuid)是—
Traceparentheaderstring是—
X-Correlation-IDheaderstring(uuid)否Defaults to X-Request-ID when omitted.
X-Task-IDheaderstring否—

请求体

application/json · 必填:是

cancelSiteRollout 请求体
名称类型必填说明
configuration_scope_idstring(uuid)是—
expected_revisioninteger(int64)是—

响应

cancelSiteRollout 响应
状态码说明
200Updated rollout, or the stored result of an identical command retry.

字段:id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean

400Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body.
401Authentication is missing or invalid.
403Wrong audience, missing permission, or tenant scope override.
404Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response.
409Idempotency, target snapshot, rollout state, active deployment, or retry conflict.
412The source or rollout expected revision is stale.
503Storage, signing, cancellation, response validation, or another internal dependency is unavailable.

失败时怎么办

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

↑ 回到列表

GET /v1/admin/site-rollouts/{rollout_id}/deployments

List latest per-node deployment attempts

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

全部需要:edge_publications.read

参数

listAdminSiteRolloutDeployments 参数
名称位置类型必填说明
rollout_idpathstring(uuid)是—
scope_idquerystring(uuid)是Platform route target tenant access-scope UUID.
limitqueryinteger否—
cursorquerystring否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.

响应

listAdminSiteRolloutDeployments 响应
状态码说明
200Latest deployment attempt for each targeted node.

字段:items: array<AdminDeployment> next_cursor?: string

400Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body.
401Authentication is missing or invalid.
403Wrong audience, missing permission, or tenant scope override.
404Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response.
503Storage, signing, cancellation, response validation, or another internal dependency is unavailable.

失败时怎么办

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

↑ 回到列表

POST /v1/admin/site-rollouts/{rollout_id}/pause

Pause a running progressive rollout

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

全部需要:edge_publications.manage

说明(契约原文)

Re-holds commands in the released cohort that have not been claimed. Status reports already in flight remain durable facts but cannot release another cohort while the rollout is paused.

参数

pauseSiteRollout 参数
名称位置类型必填说明
rollout_idpathstring(uuid)是—
Idempotency-Keyheaderstring是Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry.
X-Request-IDheaderstring(uuid)是—
Traceparentheaderstring是—
X-Correlation-IDheaderstring(uuid)否Defaults to X-Request-ID when omitted.
X-Task-IDheaderstring否—

请求体

application/json · 必填:是

pauseSiteRollout 请求体
名称类型必填说明
configuration_scope_idstring(uuid)是—
expected_revisioninteger(int64)是—

响应

pauseSiteRollout 响应
状态码说明
200Updated rollout, or the stored result of an identical command retry.

字段:id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean

400Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body.
401Authentication is missing or invalid.
403Wrong audience, missing permission, or tenant scope override.
404Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response.
409Idempotency, target snapshot, rollout state, active deployment, or retry conflict.
412The source or rollout expected revision is stale.
503Storage, signing, cancellation, response validation, or another internal dependency is unavailable.

失败时怎么办

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

↑ 回到列表

POST /v1/admin/site-rollouts/{rollout_id}/resume

Resume a paused progressive rollout

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

全部需要:edge_publications.manage

说明(契约原文)

Recomputes the current cohort under the rollout lock. If it is terminal, the next cohort alone is released or the rollout becomes terminal; otherwise remaining held commands in the current cohort are released.

参数

resumeSiteRollout 参数
名称位置类型必填说明
rollout_idpathstring(uuid)是—
Idempotency-Keyheaderstring是Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry.
X-Request-IDheaderstring(uuid)是—
Traceparentheaderstring是—
X-Correlation-IDheaderstring(uuid)否Defaults to X-Request-ID when omitted.
X-Task-IDheaderstring否—

请求体

application/json · 必填:是

resumeSiteRollout 请求体
名称类型必填说明
configuration_scope_idstring(uuid)是—
expected_revisioninteger(int64)是—

响应

resumeSiteRollout 响应
状态码说明
200Updated rollout, or the stored result of an identical command retry.

字段:id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean

400Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body.
401Authentication is missing or invalid.
403Wrong audience, missing permission, or tenant scope override.
404Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response.
409Idempotency, target snapshot, rollout state, active deployment, or retry conflict.
412The source or rollout expected revision is stale.
503Storage, signing, cancellation, response validation, or another internal dependency is unavailable.

失败时怎么办

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

↑ 回到列表

POST /v1/admin/site-rollouts/{rollout_id}/retry-failed

Append attempts for retryable failed deployments

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

全部需要:edge_publications.manage

说明(契约原文)

Only failed or rollback_failed latest attempts below max_attempts are retried. Existing attempts and artifact bindings remain immutable. The original rollout deadline remains authoritative; at or after that deadline can_retry is false and retry returns 409.

参数

retryFailedSiteRolloutDeployments 参数
名称位置类型必填说明
rollout_idpathstring(uuid)是—
Idempotency-Keyheaderstring是Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry.
X-Request-IDheaderstring(uuid)是—
Traceparentheaderstring是—
X-Correlation-IDheaderstring(uuid)否Defaults to X-Request-ID when omitted.
X-Task-IDheaderstring否—

请求体

application/json · 必填:是

retryFailedSiteRolloutDeployments 请求体
名称类型必填说明
configuration_scope_idstring(uuid)是—
expected_revisioninteger(int64)是—

响应

retryFailedSiteRolloutDeployments 响应
状态码说明
200Updated rollout, or the stored result of an identical command retry.

字段:id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean

400Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body.
401Authentication is missing or invalid.
403Wrong audience, missing permission, or tenant scope override.
404Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response.
409Idempotency, target snapshot, rollout state, active deployment, or retry conflict.
412The source or rollout expected revision is stale.
503Storage, signing, cancellation, response validation, or another internal dependency is unavailable.

失败时怎么办

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

↑ 回到列表

POST /v1/admin/site-rollouts/{rollout_id}/start

Start a held progressive rollout

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

全部需要:edge_publications.manage

说明(契约原文)

Releases only frozen cohort zero. Target membership and cohort assignment were fixed at publication time by ascending UUID bytes; later inventory changes cannot alter the rollout. Uses rollout revision CAS and domain idempotency.

参数

startSiteRollout 参数
名称位置类型必填说明
rollout_idpathstring(uuid)是—
Idempotency-Keyheaderstring是Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry.
X-Request-IDheaderstring(uuid)是—
Traceparentheaderstring是—
X-Correlation-IDheaderstring(uuid)否Defaults to X-Request-ID when omitted.
X-Task-IDheaderstring否—

请求体

application/json · 必填:是

startSiteRollout 请求体
名称类型必填说明
configuration_scope_idstring(uuid)是—
expected_revisioninteger(int64)是—

响应

startSiteRollout 响应
状态码说明
200Updated rollout, or the stored result of an identical command retry.

字段:id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) action: string: apply / rollback state: string: queued / running / paused / succeeded / partial_failed / failed / cancelled revision: integer(int64) max_attempts: integer progress: RolloutProgress can_cancel: boolean can_retry: boolean can_start?: boolean can_pause?: boolean can_resume?: boolean rollout?: RolloutPolicyView pause_reason?: string: / operator / failure_threshold created_at: string(date-time) updated_at: string(date-time) replayed?: boolean

400Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body.
401Authentication is missing or invalid.
403Wrong audience, missing permission, or tenant scope override.
404Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response.
409Idempotency, target snapshot, rollout state, active deployment, or retry conflict.
412The source or rollout expected revision is stale.
503Storage, signing, cancellation, response validation, or another internal dependency is unavailable.

失败时怎么办

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

↑ 回到列表