接口详情
GET /v1/cache-operations
List cache operations in a stable tenant snapshot
- operationId
listTenantCacheOperations- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
The cursor freezes the set of operations whose committed creation audit position is at or below the first page watermark. Mutable state, progress, and update/completion timestamps remain live on later pages.
参数
listTenantCacheOperations 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
X-Request-ID | header | string | 是 | — |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | HMAC-authenticated cursor bound to scope, filters, and a committed creation-audit watermark. It freezes membership, not mutable operation state or progress. |
|---|
site_id | query | string(uuid) | 否 | Non-disclosing filter within the effective tenant scope. A foreign or nonexistent UUID returns the same 200 response with an empty items array. |
|---|
site_display_id | query | string | 否 | Tenant-scoped stable positive site identifier displayed by the UI. |
|---|
search | query | string | 否 | Exact operation/site short ID or a case-insensitive target URL fragment. |
|---|
action | query | string: purge / prewarm | 否 | — |
|---|
target_type | query | string: exact_url / directory_prefix / whole_site | 否 | — |
|---|
state | query | string | 否 | One state or several, comma separated (any of them). |
|---|
响应
listTenantCacheOperations 响应| 状态码 | 说明 |
|---|
200 | Stable operation page. 字段：items: array<OperationSummary> next_cursor?: string state_counts?: object |
|---|
400 | Invalid or non-canonical request. |
|---|
401 | Authentication required. |
|---|
403 | Exact cache permission is absent or route audience is wrong. |
|---|
408 | Request context was cancelled or exceeded its deadline. |
|---|
503 | A required store is unavailable; raw dependency errors are never returned. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/cache-operations
Persist a purge or prewarm operation
- operationId
createTenantCacheOperation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.manage
说明（契约原文）
Returns 202 after the operation and node/target projections are committed. queued never means that a node command was dispatched. Unknown results must be retried with the same Idempotency-Key and body.
参数
createTenantCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createTenantCacheOperation 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
site_id | string(uuid) | 是 | — |
|---|
action | string: purge / prewarm | 是 | — |
|---|
target_type | string: exact_url / directory_prefix / whole_site | 是 | — |
|---|
targets | array<string(uri)> | 是 | Edge cachetask schema v2 wire envelope. At most 16 targets, each at most 16 KiB of UTF-8 bytes, with at most 64 KiB of raw target bytes across the array. The aggregate byte limit is enforced by the server in addition to this JSON Schema. |
|---|
node_ids | array<string(uuid)> | 是 | — |
|---|
max_retries | integer | 是 | — |
|---|
响应
createTenantCacheOperation 响应| 状态码 | 说明 |
|---|
202 | Durable operation accepted in queued state; no delivery is implied. 字段：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_at?: string(date-time) |
|---|
400 | Invalid or non-canonical request. |
|---|
401 | Authentication required. |
|---|
403 | Exact cache permission is absent or route audience is wrong. |
|---|
404 | Resource is absent or outside the effective tenant scope. |
|---|
408 | Request context was cancelled or exceeded its deadline. |
|---|
409 | Idempotency payload or operation state conflicts. |
|---|
503 | A required store is unavailable; raw dependency errors are never returned. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/cache-operations/daily-usage
Today's cache operation quotas of the caller's account (UTC+8 day; system follow-ups not counted)
- operationId
getTenantCacheDailyUsage- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Quotas count per account (tenant scope): the owner and its members share them across all its sites. A platform administrator's submissions on the tenant's behalf are neither counted nor refused (still audited as the administrator).
参数
getTenantCacheDailyUsage 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
X-Request-ID | header | string | 是 | — |
|---|
响应
getTenantCacheDailyUsage 响应| 状态码 | 说明 |
|---|
200 | The same limits and counts a create is checked against. 字段：scope_id: string(uuid) revision: integer url_purge: CacheDailyQuota directory_purge: object prewarm: CacheDailyQuota resets_at: string(date-time) |
|---|
400 | Invalid or non-canonical request. |
|---|
401 | Authentication required. |
|---|
403 | Exact cache permission is absent or route audience is wrong. |
|---|
404 | Resource is absent or outside the effective tenant scope. |
|---|
408 | Request context was cancelled or exceeded its deadline. |
|---|
503 | A required store is unavailable; raw dependency errors are never returned. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/cache-operations/{operation_id}
Get sanitized per-node operation progress
- operationId
getTenantCacheOperation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
getTenantCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
operation_id | path | string(uuid) | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
响应
getTenantCacheOperation 响应| 状态码 | 说明 |
|---|
200 | Sanitized cache operation. 字段：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_at?: string(date-time) |
|---|
400 | Invalid or non-canonical request. |
|---|
401 | Authentication required. |
|---|
403 | Exact cache permission is absent or route audience is wrong. |
|---|
404 | Resource is absent or outside the effective tenant scope. |
|---|
408 | Request context was cancelled or exceeded its deadline. |
|---|
503 | A required store is unavailable; raw dependency errors are never returned. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/cache-operations/{operation_id}/cancel
Cancel a queued or running cache operation
- operationId
cancelTenantCacheOperation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.manage
参数
cancelTenantCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
operation_id | path | string(uuid) | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
响应
cancelTenantCacheOperation 响应| 状态码 | 说明 |
|---|
200 | Sanitized cache operation. 字段：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_at?: string(date-time) |
|---|
400 | Invalid or non-canonical request. |
|---|
401 | Authentication required. |
|---|
403 | Exact cache permission is absent or route audience is wrong. |
|---|
404 | Resource is absent or outside the effective tenant scope. |
|---|
408 | Request context was cancelled or exceeded its deadline. |
|---|
409 | Idempotency payload or operation state conflicts. |
|---|
503 | A required store is unavailable; raw dependency errors are never returned. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/cache-operations/{operation_id}/resubmit
Re-submit an operation as a new one
- operationId
resubmitTenantCacheOperation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.manage
说明（契约原文）
Creates a new operation with the original's site, action, target type, targets and retry budget, on the nodes the original named, or on every node carrying the site now when it named none (auto_nodes). The Idempotency-Key is the batch key: with the original operation it forms the new operation's idempotency key, so a retry of one batch replays (Idempotency-Replayed) and another batch creates another operation. Audited as cache.operation.resubmit on the original operation.
参数
resubmitTenantCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
operation_id | path | string(uuid) | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
响应
resubmitTenantCacheOperation 响应| 状态码 | 说明 |
|---|
202 | Durable operation accepted in queued state; no delivery is implied. 字段：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_at?: string(date-time) |
|---|
400 | Invalid or non-canonical request. |
|---|
401 | Authentication required. |
|---|
403 | Exact cache permission is absent or route audience is wrong. |
|---|
404 | Resource is absent or outside the effective tenant scope. |
|---|
408 | Request context was cancelled or exceeded its deadline. |
|---|
409 | Idempotency payload or operation state conflicts. |
|---|
429 | The account's daily purge or prewarm limit would be exceeded (daily_limit_exceeded; error.details names the quota). |
|---|
503 | A required store is unavailable; raw dependency errors are never returned. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。429 被限速：等待后再试，降低并发。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/cache-operations/{operation_id}/retry
Requeue retryable failed projections only
- operationId
retryTenantCacheOperation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.manage
参数
retryTenantCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
operation_id | path | string(uuid) | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
响应
retryTenantCacheOperation 响应| 状态码 | 说明 |
|---|
200 | Sanitized cache operation. 字段：id: string(uuid) display_id: string site_id: string(uuid) site_display_id: string action: string: purge / prewarm target_type: string: exact_url / directory_prefix / whole_site state: string: queued / running / succeeded / partial_failed / failed / cancelled max_attempts: integer progress: Progress auto_nodes: boolean parent_operation_id?: string(uuid) targets: array<Target> nodes: array<NodeProjection> cancel_requested_at?: string(date-time) created_at: string(date-time) started_at?: string(date-time) updated_at: string(date-time) completed_at?: string(date-time) |
|---|
400 | Invalid or non-canonical request. |
|---|
401 | Authentication required. |
|---|
403 | Exact cache permission is absent or route audience is wrong. |
|---|
404 | Resource is absent or outside the effective tenant scope. |
|---|
408 | Request context was cancelled or exceeded its deadline. |
|---|
409 | Idempotency payload or operation state conflicts. |
|---|
503 | A required store is unavailable; raw dependency errors are never returned. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表