接口详情
GET /v1/admin/control-upgrade-rollouts
List durable control upgrade rollouts
- operationId
listControlUpgradeRollouts- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.read
说明（契约原文）
Requires a platform-scoped identity with control.upgrades.read. The response is ordered by created_at descending and id descending. Unknown or repeated query parameters are rejected.
参数
listControlUpgradeRollouts 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
page_size | query | integer | 否 | — |
|---|
state | query | string: queued / canary / running / paused / rolling_back / completed / failed | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
响应
listControlUpgradeRollouts 响应| 状态码 | 说明 |
|---|
200 | A page of rollout summaries. 字段：data: array<ControlUpgradeRolloutSummary> page: integer page_size: integer total: integer(int64) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/control-upgrade-rollouts
Create a durable control upgrade rollout
- operationId
createControlUpgradeRollout- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Requires control.upgrades.manage in a platform scope. The canonical request freezes the sorted target cohort, canary subset, batch size, and mandatory automatic rollback. A replay rechecks live RBAC and returns the original durable snapshot without another license call or NATS publication. A changed request under the same idempotency key returns 409.
参数
createControlUpgradeRollout 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createControlUpgradeRollout 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
schema | string | 是 | — |
|---|
node_ids | array<string(uuid)> | 是 | Canonical lowercase UUIDs in strictly increasing byte order. |
|---|
canary_node_ids | array<string(uuid)> | 是 | One or two strictly sorted canonical UUIDs, each also present in node_ids. |
|---|
batch_size | integer | 是 | — |
|---|
automatic_rollback | boolean | 是 | — |
|---|
响应
createControlUpgradeRollout 响应| 状态码 | 说明 |
|---|
201 | The rollout was created or replayed. 字段：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/control-upgrade-rollouts/{rollout_id}
Get a durable control upgrade rollout
- operationId
getControlUpgradeRollout- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.read
说明（契约原文）
Requires control.upgrades.read in a platform scope.
参数
getControlUpgradeRollout 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
rollout_id | path | string(uuid) | 是 | — |
|---|
响应
getControlUpgradeRollout 响应| 状态码 | 说明 |
|---|
200 | The rollout summary, batches, nodes, ordered state events, and durable status broker receipts. 字段：data: ControlUpgradeRolloutDetail |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/control-upgrade-rollouts/{rollout_id}/pause
Pause a running control upgrade rollout
- operationId
pauseControlUpgradeRollout- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Requires control.upgrades.manage and a current expected revision.
参数
pauseControlUpgradeRollout 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
rollout_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
pauseControlUpgradeRollout 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | string | 是 | Canonical decimal uint63 in the inclusive range 1..9223372036854775807. |
|---|
reason | string | 是 | — |
|---|
响应
pauseControlUpgradeRollout 响应| 状态码 | 说明 |
|---|
200 | The rollout transition committed, or the exact durable result was replayed. 字段：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/control-upgrade-rollouts/{rollout_id}/resume
Resume a paused control upgrade rollout
- operationId
resumeControlUpgradeRollout- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Requires control.upgrades.manage and a current expected revision.
参数
resumeControlUpgradeRollout 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
rollout_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
resumeControlUpgradeRollout 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | string | 是 | Canonical decimal uint63 in the inclusive range 1..9223372036854775807. |
|---|
reason | string | 是 | — |
|---|
响应
resumeControlUpgradeRollout 响应| 状态码 | 说明 |
|---|
200 | The rollout transition committed, or the exact durable result was replayed. 字段：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/control-upgrade-rollouts/{rollout_id}/rollback
Roll back a control upgrade rollout
- operationId
rollbackControlUpgradeRollout- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Requires control.upgrades.manage and a current expected revision. Rollback remains blocked for irreversible migrations, missing rollback artifacts, or an in-flight dispatched batch.
参数
rollbackControlUpgradeRollout 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
rollout_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
rollbackControlUpgradeRollout 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | string | 是 | Canonical decimal uint63 in the inclusive range 1..9223372036854775807. |
|---|
reason | string | 是 | — |
|---|
响应
rollbackControlUpgradeRollout 响应| 状态码 | 说明 |
|---|
200 | The rollout transition committed, or the exact durable result was replayed. 字段：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/control-upgrade-rollouts/{rollout_id}/start
Start a queued control upgrade rollout
- operationId
startControlUpgradeRollout- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Requires control.upgrades.manage and a current expected revision.
参数
startControlUpgradeRollout 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
rollout_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
startControlUpgradeRollout 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | string | 是 | Canonical decimal uint63 in the inclusive range 1..9223372036854775807. |
|---|
reason | string | 是 | — |
|---|
响应
startControlUpgradeRollout 响应| 状态码 | 说明 |
|---|
200 | The rollout transition committed, or the exact durable result was replayed. 字段：data: ControlUpgradeRolloutDetail replayed: boolean |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
413 | The request body exceeds the one MiB limit. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表