接口详情
GET /v1/admin/cache-operations
List operations in an explicit tenant scope
- operationId
listAdminCacheOperations- 认证
- 登录会话：主控登录后的 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.
参数
listAdminCacheOperations 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
scope_id | query | string(uuid) | 是 | Explicit active tenant scope; platform scope is never implied. |
|---|
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). |
|---|
响应
listAdminCacheOperations 响应| 状态码 | 说明 |
|---|
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/admin/cache-operations
Persist an operation in an explicit tenant scope
- operationId
createAdminCacheOperation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.manage
说明（契约原文）
queued means persisted, not dispatched.
参数
createAdminCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
scope_id | query | string(uuid) | 是 | Explicit active tenant scope; platform scope is never implied. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createAdminCacheOperation 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
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 | 是 | — |
|---|
响应
createAdminCacheOperation 响应| 状态码 | 说明 |
|---|
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/admin/cache-operations/daily-usage
Today's cache operation quotas of a tenant account (UTC+8 day; system follow-ups not counted)
- operationId
getAdminCacheDailyUsage- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
getAdminCacheDailyUsage 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
scope_id | query | string(uuid) | 是 | Explicit active tenant scope; platform scope is never implied. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
响应
getAdminCacheDailyUsage 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
PUT /v1/admin/cache-operations/daily-usage
Set a tenant account's own daily purge/prewarm limits (null follows the system setting default)
- operationId
setAdminCacheAccountLimits- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.users.manage
说明（契约原文）
Audited as cache.account_quota.update. Every key is required; a stale expected_revision (the revision of the last read) is 412.
参数
setAdminCacheAccountLimits 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
scope_id | query | string(uuid) | 是 | Explicit active tenant scope; platform scope is never implied. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
setAdminCacheAccountLimits 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer | 是 | — |
|---|
url_purge_limit | integer | null | 是 | — |
|---|
directory_purge_limit | integer | null | 是 | — |
|---|
prewarm_limit | integer | null | 是 | — |
|---|
响应
setAdminCacheAccountLimits 响应| 状态码 | 说明 |
|---|
200 | The account's quotas after the change. 字段：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. |
|---|
412 | expected_revision no longer matches the current head. |
|---|
503 | A required store is unavailable; raw dependency errors are never returned. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/cache-operations/{operation_id}
Get operation progress in an explicit tenant scope
- operationId
getAdminCacheOperation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
getAdminCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
operation_id | path | string(uuid) | 是 | — |
|---|
scope_id | query | string(uuid) | 是 | Explicit active tenant scope; platform scope is never implied. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
响应
getAdminCacheOperation 响应| 状态码 | 说明 |
|---|
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/admin/cache-operations/{operation_id}/cancel
Cancel an operation in an explicit tenant scope
- operationId
cancelAdminCacheOperation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.manage
参数
cancelAdminCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
operation_id | path | string(uuid) | 是 | — |
|---|
scope_id | query | string(uuid) | 是 | Explicit active tenant scope; platform scope is never implied. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
响应
cancelAdminCacheOperation 响应| 状态码 | 说明 |
|---|
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/admin/cache-operations/{operation_id}/resubmit
Re-submit an operation as a new one
- operationId
resubmitAdminCacheOperation- 认证
- 登录会话：主控登录后的 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.
参数
resubmitAdminCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
operation_id | path | string(uuid) | 是 | — |
|---|
scope_id | query | string(uuid) | 是 | Explicit active tenant scope; platform scope is never implied. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
响应
resubmitAdminCacheOperation 响应| 状态码 | 说明 |
|---|
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/admin/cache-operations/{operation_id}/retry
Retry an operation in an explicit tenant scope
- operationId
retryAdminCacheOperation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.manage
参数
retryAdminCacheOperation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
operation_id | path | string(uuid) | 是 | — |
|---|
scope_id | query | string(uuid) | 是 | Explicit active tenant scope; platform scope is never implied. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
响应
retryAdminCacheOperation 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表