接口详情
Page through jobs across the customer control plane
- operationId
listPlatformJobs- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.read_all platform.admin
说明（契约原文）
Requires a platform-scoped identity with jobs.read_all or platform.admin. tenant_id narrows the global query. The time window is left-closed and right-open and may not exceed 31 days. Explicit page selects numbered pagination with an exact scoped and filtered total; omit page to preserve the authenticated keyset cursor contract.
参数
listPlatformJobs 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | Inclusive RFC3339 creation-time bound. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 creation-time bound; from-to may not exceed 31 days. |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only. Omit to query all tenants. |
|---|
task_id | query | string(uuid) | 否 | Exact task UUID filter. |
|---|
status | query | array<string: queued / running / succeeded / partial_failed / failed / cancelled> | 否 | Comma-separated job states; duplicates are rejected. |
|---|
kind | query | string | 否 | — |
|---|
resource | query | string | 否 | Exact match against the canonical job subject/reference, or a case-insensitive match against a node UUID assigned to one of the job's items, so node pages can deep-link to the tasks executed on that node. |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
page | query | integer | 否 | Explicit canonical positive decimal page number, mutually exclusive with cursor even if cursor is empty. Count and rows use one read-only repeatable-read snapshot. Different requests are live snapshots and may move rows as jobs are inserted or change state. A page beyond the end returns an empty data array, the requested number and the exact total. |
|---|
响应
listPlatformJobs 响应| 状态码 | 说明 |
|---|
200 | Authenticated keyset page or explicit numbered page with a same-snapshot exact total. 字段：data: array<Job> page: Page | NumberedPage query: QueryWindow task_metadata?: array<TaskMetadata> |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
Read the integrated producer kind catalog independently of job rows
- operationId
listPlatformJobKinds- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.read_all platform.admin
说明（契约原文）
Requires jobs.read_all or platform.admin. Accepts no query parameters. Integration means a production source path creates canonical job facts, not that its producer or worker is enabled or ready in this runtime.
响应
listPlatformJobKinds 响应| 状态码 | 说明 |
|---|
200 | Registered source-backed producer kinds, independent of current job rows or runtime enablement. 字段：data: array<JobKind> |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
↑ 回到列表
Read a job visible to the platform administrator
- operationId
getPlatformJob- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.read_all platform.admin
参数
getPlatformJob 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
响应
getPlatformJob 响应| 状态码 | 说明 |
|---|
200 | Job projection without producer payload or credentials. 字段：data: Job |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
Page through a job's immutable attempt history
- operationId
listPlatformJobAttempts- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.read_all platform.admin
参数
listPlatformJobAttempts 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
响应
listPlatformJobAttempts 响应| 状态码 | 说明 |
|---|
200 | Attempt history ordered by attempt number descending. 字段：data: array<Attempt> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
Cancel a queued or running job
- operationId
cancelPlatformJob- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.manage_all platform.admin
说明（契约原文）
Requires jobs.manage_all or platform.admin. The state transition, audit, and command receipt commit atomically. The same actor and Idempotency-Key return the immutable first successful snapshot with replayed=true; reuse for another command returns 409.
参数
cancelPlatformJob 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | Strong ETag value returned by the latest job detail or command response. |
|---|
请求体
application/json · 必填：是
响应
cancelPlatformJob 响应| 状态码 | 说明 |
|---|
200 | Immutable cancelled or queued command result snapshot. 字段：data: Job replayed: boolean |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
409 | job_idempotency_conflict, job_invalid_transition, job_retries_exhausted, or job_producer_command_required: the key was reused for another command, the job changed or is ineligible, no retry attempt remains, or the job's producer owns the command. cache.operation cancel/retry is executed by the cache module (same audit and receipt as the cache operation API); job_producer_command_required is returned only for its replay, or when cache control is not enabled. |
|---|
412 | job_revision_conflict: the If-Match revision is stale; refresh the job before retrying. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
Page through append-only terminal-attempt dead letters
- operationId
listPlatformJobDeadLetters- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.read_all platform.admin
参数
listPlatformJobDeadLetters 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
响应
listPlatformJobDeadLetters 响应| 状态码 | 说明 |
|---|
200 | Dead letters ordered by terminal attempt descending. 字段：data: array<DeadLetter> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
Page through immutable per-attempt settlement receipts
- operationId
listPlatformJobSettlementReceipts- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.read_all platform.admin
参数
listPlatformJobSettlementReceipts 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
响应
listPlatformJobSettlementReceipts 响应| 状态码 | 说明 |
|---|
200 | Settlement receipts ordered by attempt descending then ordinal ascending. 字段：data: array<SettlementReceipt> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
Add one attempt and replay the latest dead-lettered job
- operationId
replayPlatformDeadLetteredJob- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.manage_all platform.admin
说明（契约原文）
Requires jobs.manage_all or platform.admin. The state transition, audit, replay fact, and command receipt commit atomically. The same actor and Idempotency-Key return the immutable first successful snapshot with replayed=true; reuse for another command returns 409.
参数
replayPlatformDeadLetteredJob 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | Strong ETag value returned by the latest job detail or command response. |
|---|
请求体
application/json · 必填：是
响应
replayPlatformDeadLetteredJob 响应| 状态码 | 说明 |
|---|
200 | Immutable cancelled or queued command result snapshot. 字段：data: Job replayed: boolean |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
409 | job_idempotency_conflict, job_invalid_transition, job_retries_exhausted, or job_producer_command_required: the key was reused for another command, the job changed or is ineligible, no retry attempt remains, or the job's producer owns the command. cache.operation cancel/retry is executed by the cache module (same audit and receipt as the cache operation API); job_producer_command_required is returned only for its replay, or when cache control is not enabled. |
|---|
412 | job_revision_conflict: the If-Match revision is stale; refresh the job before retrying. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
Page through current per-item and per-node result projections
- operationId
listPlatformJobResults- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.read_all platform.admin
参数
listPlatformJobResults 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
响应
listPlatformJobResults 响应| 状态码 | 说明 |
|---|
200 | Current item projections ordered by immutable ordinal ascending. 字段：data: array<ItemResult> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
Retry failed items in a failed or partially failed job
- operationId
retryPlatformJob- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
任一即可：jobs.manage_all platform.admin
说明（契约原文）
Requires jobs.manage_all or platform.admin and an available attempt. The state transition, audit, and command receipt commit atomically. The same actor and Idempotency-Key return the immutable first successful snapshot with replayed=true; reuse for another command returns 409.
参数
retryPlatformJob 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | Strong ETag value returned by the latest job detail or command response. |
|---|
请求体
application/json · 必填：是
响应
retryPlatformJob 响应| 状态码 | 说明 |
|---|
200 | Immutable cancelled or queued command result snapshot. 字段：data: Job replayed: boolean |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
409 | job_idempotency_conflict, job_invalid_transition, job_retries_exhausted, or job_producer_command_required: the key was reused for another command, the job changed or is ineligible, no retry attempt remains, or the job's producer owns the command. cache.operation cancel/retry is executed by the cache module (same audit and receipt as the cache operation API); job_producer_command_required is returned only for its replay, or when cache control is not enabled. |
|---|
412 | job_revision_conflict: the If-Match revision is stale; refresh the job before retrying. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表