调度

定时任务、消息队列与出向 Webhook。

概览

基础路径: https://api.infrai.cc/v1/scheduling

鉴权头: Authorization: Bearer $INFRAI_API_KEY

bash

# Call any /v1/scheduling capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/scheduling/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

方法

scheduling.cron.create

POST /v1/scheduling/cron/create

创建按计划向 URL 发起 POST 的定时任务。

参数

名称	类型	必填	说明
`name`	`string`	必填	可读的任务名称。
`schedule`	`string`	必填	Cron 表达式，例如 0 9 * * *。
`url`	`string`	必填	接收定时 POST 的 URL。
`payload`	`unknown`	可选	每次运行附带的可选 JSON 负载。
`timezone`	`string`	可选	调度使用的 IANA 时区。
`retries`	`number`	可选	失败时的重试次数。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

CronRecord { cron_id, name, schedule, url, enabled, next_run_at? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/cron/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cron_expr": "0 9 * * 1", "task_type": "http_url", "task_url": "https://api.acme.com/weekly"}'

scheduling.cron.list

GET /v1/scheduling/cron/list

列出定时任务。

{ items: CronRecord[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/scheduling/cron/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.queue.publish

POST /v1/scheduling/queue/publish

向队列发布消息，可选延迟。

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称。
`payload`	`object`	必填	消息负载。
`delay_seconds`	`number`	可选	投递前的延迟（秒）。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

{ message_id }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/queue/publish \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "orders", "payload": {"order_id": "o_123"}, "priority": 5}'

scheduling.cron.get

GET /v1/scheduling/cron/get/{id}

获取单个定时任务的配置与下次运行时间

参数

名称	类型	必填	说明
`cron_id`	`string`	必填	定时任务 ID

CronRecord { cron_id, name, cron_expr, task, timezone, enabled, next_run_at? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/scheduling/cron/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.cron.update

PATCH /v1/scheduling/cron/update/{id}

更新定时任务的表达式、目标与策略

参数

名称	类型	必填	说明
`cron_id`	`string`	必填	定时任务 ID
`cron_expr`	`string`	可选	标准 5/6 段 cron 表达式
`task`	`string`	可选	触发时投递的目标 URL
`name`	`string`	可选	任务名称
`timezone`	`string`	可选	IANA 时区名（如 Asia/Shanghai）
`retry`	`number`	可选	失败重试次数（0-10）
`timeout_seconds`	`number`	可选	单次触发超时秒数（1-900）
`overlap_policy`	`"allow" \| "skip" \| "queue"`	可选	重叠策略：allow 允许 / skip 跳过 / queue 排队
`max_runs`	`number`	可选	最大运行次数，达到后自动停止
`payload`	`object`	可选	随触发发送的 JSON 负载
`headers`	`object`	可选	随触发发送的自定义请求头
`on_failure_webhook`	`string`	可选	失败时回调的 Webhook 地址
`idempotency_key`	`string`	可选	幂等键，避免重复执行

CronRecord { cron_id, name, cron_expr, task, timezone, enabled, next_run_at? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X PATCH https://api.infrai.cc/v1/scheduling/cron/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

scheduling.cron.delete

DELETE /v1/scheduling/cron/delete/{id}

删除一个定时任务

参数

名称	类型	必填	说明
`cron_id`	`string`	必填	定时任务 ID
`idempotency_key`	`string`	可选	幂等键，避免重复执行

{ cron_id, deleted }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/scheduling/cron/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.cron.pause

POST /v1/scheduling/cron/pause/{id}

暂停定时任务

参数

名称	类型	必填	说明
`cron_id`	`string`	必填	定时任务 ID
`idempotency_key`	`string`	可选	幂等键，避免重复执行

CronRecord { cron_id, enabled }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/cron/pause/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cron_id": "..."}'

scheduling.cron.resume

POST /v1/scheduling/cron/resume/{id}

恢复已暂停的定时任务

参数

名称	类型	必填	说明
`cron_id`	`string`	必填	定时任务 ID
`idempotency_key`	`string`	可选	幂等键，避免重复执行

CronRecord { cron_id, enabled, next_run_at? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/cron/resume/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cron_id": "..."}'

scheduling.cron.trigger

POST /v1/scheduling/cron/trigger/{id}

立即手动触发一次定时任务运行

参数

名称	类型	必填	说明
`cron_id`	`string`	必填	定时任务 ID
`idempotency_key`	`string`	可选	幂等键，避免重复执行

CronRun { run_id, cron_id, state, started_at }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/cron/trigger/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "cron_01HX..."}'

scheduling.cron.runs.get

GET /v1/scheduling/cron/runs/get/{id}/{run_id}

获取定时任务某次运行的详情

参数

名称	类型	必填	说明
`cron_id`	`string`	必填	定时任务 ID
`run_id`	`string`	必填	运行（CronRun）ID

CronRun { run_id, cron_id, state, started_at, finished_at?, response_status?, error? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/scheduling/cron/runs/get/ID/RUN_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.cron.retention.get

GET /v1/scheduling/cron/retention/get/{id}

查询定时任务运行历史保留天数

参数

名称	类型	必填	说明
`cron_id`	`string`	必填	定时任务 ID

{ cron_id, retention_days }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/scheduling/cron/retention/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.cron.retention.set

PUT /v1/scheduling/cron/retention/set/{id}

设置定时任务运行历史保留天数

参数

名称	类型	必填	说明
`cron_id`	`string`	必填	定时任务 ID
`retention_days`	`number`	必填	保留的运行历史天数
`idempotency_key`	`string`	可选	幂等键，避免重复执行

{ cron_id, retention_days }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X PUT https://api.infrai.cc/v1/scheduling/cron/retention/set/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retention_days": 0}'

scheduling.task.schedule

POST /v1/scheduling/task/schedule

调度一次性的定时触发任务

参数

名称	类型	必填	说明
`task`	`string`	必填	触发一次的目标 URL
`run_at`	`string`	必填	绝对触发时刻（UTC 时间）
`name`	`string`	可选	任务名称
`payload`	`object`	可选	随触发发送的 JSON 负载
`headers`	`object`	可选	随触发发送的自定义请求头
`retry`	`number`	可选	失败重试次数
`timeout_seconds`	`number`	可选	单次触发超时秒数
`secret`	`string`	可选	对触发请求做 HMAC 签名的密钥
`idempotency_key`	`string`	可选	幂等键，避免重复执行

TaskRecord { task_id, task, run_at, state }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/task/schedule \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "...", "run_at": "..."}'

scheduling.run.list

GET /v1/scheduling/run/list

分页列出调度运行记录

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标，来自上一页 next_cursor
`limit`	`number`	可选	每页返回数量

{ items: Run[], next_cursor? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/scheduling/run/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.queue.create

POST /v1/scheduling/queue/create

创建一个消息队列

参数

名称	类型	必填	说明
`name`	`string`	必填	队列名称
`type`	`"standard" \| "fifo"`	可选	队列类型：standard 标准 / fifo 先进先出
`dead_letter_queue`	`string`	可选	接收失败消息的死信队列名（须已存在）
`max_retries`	`number`	可选	转入 DLQ 前允许的 nack 次数
`message_retention_days`	`number`	可选	消息保留天数
`visibility_timeout_default`	`number`	可选	默认可见性超时（租约）秒数
`enable_priority`	`boolean`	可选	是否启用优先级
`idempotency_key`	`string`	可选	幂等键，避免重复创建

QueueRecord { queue, type, dead_letter_queue?, max_retries, visibility_timeout_default }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/queue/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "..."}'

scheduling.queue.get

GET /v1/scheduling/queue/get/{queue}

获取队列配置详情

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称

QueueRecord { queue, type, dead_letter_queue?, max_retries, visibility_timeout_default }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/scheduling/queue/get/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.queue.list

GET /v1/scheduling/queue/list

分页列出所有队列

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标，来自上一页 next_cursor
`limit`	`number`	可选	每页返回数量

{ items: QueueRecord[], next_cursor? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/scheduling/queue/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.queue.update

PATCH /v1/scheduling/queue/update/{queue}

更新队列配置

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`dead_letter_queue`	`string`	可选	死信队列名
`max_retries`	`number`	可选	转入 DLQ 前允许的 nack 次数
`message_retention_days`	`number`	可选	消息保留天数
`visibility_timeout_default`	`number`	可选	默认可见性超时秒数
`enable_priority`	`boolean`	可选	是否启用优先级
`idempotency_key`	`string`	可选	幂等键，避免重复执行

QueueRecord { queue, max_retries, visibility_timeout_default }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X PATCH https://api.infrai.cc/v1/scheduling/queue/update/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

scheduling.queue.delete

DELETE /v1/scheduling/queue/delete/{queue}

删除一个队列

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`idempotency_key`	`string`	可选	幂等键，避免重复执行

{ queue, deleted }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/scheduling/queue/delete/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.queue.purge

POST /v1/scheduling/queue/purge/{queue}

清空队列中所有消息

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`idempotency_key`	`string`	可选	幂等键，避免重复执行

{ queue, purged }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/queue/purge/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "..."}'

scheduling.queue.stats

GET /v1/scheduling/queue/stats/{queue}

获取队列统计指标

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称

QueueStats { queue, available, in_flight, dlq, oldest_age_seconds? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/scheduling/queue/stats/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.queue.publish_batch

POST /v1/scheduling/queue/publish_batch

批量发布多条消息到队列

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`messages`	`QueueMessage[]`	必填	待发布的消息数组
`idempotency_key`	`string`	可选	幂等键，避免重复发布

{ message_ids }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/queue/publish_batch \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "...", "messages": []}'

scheduling.queue.consume

POST /v1/scheduling/queue/consume

从队列拉取一批消息消费

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`max_messages`	`number`	可选	单次最多拉取的消息数
`visibility_timeout`	`number`	可选	本批消息的租约秒数；默认取队列配置

{ messages: QueueMessage[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/queue/consume \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "..."}'

scheduling.queue.ack

POST /v1/scheduling/queue/ack

确认一条已消费的消息

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`message_id`	`string`	必填	消息 ID
`idempotency_key`	`string`	可选	幂等键，避免重复执行

{ message_id, acked }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/queue/ack \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "...", "message_id": "..."}'

scheduling.queue.nack

POST /v1/scheduling/queue/nack

否认一条消息，可重新入队或转入死信

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`message_id`	`string`	必填	消息 ID
`requeue`	`boolean`	可选	true 重新入队；false 直接转入死信
`idempotency_key`	`string`	可选	幂等键，避免重复执行

{ message_id, nacked, requeued }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/queue/nack \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "...", "message_id": "..."}'

scheduling.queue.dlq.list

GET /v1/scheduling/queue/dlq/list/{queue}

分页列出死信队列中的消息

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`cursor`	`string`	可选	分页游标，来自上一页 next_cursor
`limit`	`number`	可选	每页返回数量

{ items: QueueMessage[], next_cursor? }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/scheduling/queue/dlq/list/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

scheduling.queue.dlq.redrive

POST /v1/scheduling/queue/dlq/redrive/{queue}

将死信消息重投回原队列

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`message_id`	`string`	可选	重投单条消息的 ID；省略则批量重投
`since`	`string`	可选	批量重投：该时刻及之后进入死信的全部消息
`idempotency_key`	`string`	可选	幂等键，避免重复重投

{ queue, redriven }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/queue/dlq/redrive/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "orders", "max_messages": 100}'

scheduling.queue.push_subscribe

POST /v1/scheduling/queue/push_subscribe/{queue}

为队列配置推送订阅

参数

名称	类型	必填	说明
`queue`	`string`	必填	队列名称
`url`	`string`	必填	https 推送目标地址（经 SSRF 校验）
`secret`	`string`	可选	对推送请求做 HMAC 签名的密钥
`max_retries`	`number`	可选	推送失败重试次数
`visibility_timeout`	`number`	可选	可见性超时秒数
`dead_letter_queue`	`string`	可选	死信队列名
`idempotency_key`	`string`	可选	幂等键，避免重复订阅

PushSubscription { subscription_id, queue, url }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/scheduling/queue/push_subscribe/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "orders", "forward_to": "https://api.acme.com/order-handler"}'

全部能力

本模块全部已路由能力——完整的对外 REST 契约。上方方法是带讲解的入门示例,此表是完整参考。

能力	端点	说明
`scheduling.cron.create`	`POST /v1/scheduling/cron/create`	Create a scheduled cron job; idempotent write.
`scheduling.cron.delete`	`DELETE /v1/scheduling/cron/delete/{id}`	Delete a cron job.
`scheduling.cron.get`	`GET /v1/scheduling/cron/get/{id}`	Get a single cron job's configuration and next run time.
`scheduling.cron.list`	`GET /v1/scheduling/cron/list`	List the account's cron jobs with pagination.
`scheduling.cron.pause`	`POST /v1/scheduling/cron/pause/{id}`	Pause a cron job, halting subsequent triggers.
`scheduling.cron.resume`	`POST /v1/scheduling/cron/resume/{id}`	Resume a paused cron job.
`scheduling.cron.retention.get`	`GET /v1/scheduling/cron/retention/get/{id}`	Get the retention days for cron job run history.
`scheduling.cron.retention.set`	`PUT /v1/scheduling/cron/retention/set/{id}`	Set the retention days for cron job run history.
`scheduling.cron.runs.get`	`GET /v1/scheduling/cron/runs/get/{id}/{run_id}`	Retrieve details of a single cron job execution (CronRun).
`scheduling.cron.trigger`	`POST /v1/scheduling/cron/trigger/{id}`	Manually trigger an immediate run of a scheduled cron job.
`scheduling.cron.update`	`PATCH /v1/scheduling/cron/update/{id}`	Update a cron job's schedule expression, target, overlap policy, and other fields.
`scheduling.queue.ack`	`POST /v1/scheduling/queue/ack`	Acknowledge (ack) a consumed message to remove it from the queue.
`scheduling.queue.consume`	`POST /v1/scheduling/queue/consume`	Pull a batch of messages from a queue for processing.
`scheduling.queue.create`	`POST /v1/scheduling/queue/create`	Create a message queue (standard or FIFO, with optional dead-letter queue).
`scheduling.queue.delete`	`DELETE /v1/scheduling/queue/delete/{queue}`	Delete a message queue.
`scheduling.queue.dlq.list`	`GET /v1/scheduling/queue/dlq/list/{queue}`	List messages in a queue's dead-letter queue (DLQ) with pagination.
`scheduling.queue.dlq.redrive`	`POST /v1/scheduling/queue/dlq/redrive/{queue}`	Redrive dead-letter messages back to the source queue, individually or in bulk.
`scheduling.queue.get`	`GET /v1/scheduling/queue/get/{queue}`	Retrieve a queue's configuration details.
`scheduling.queue.list`	`GET /v1/scheduling/queue/list`	List all message queues with pagination.
`scheduling.queue.nack`	`POST /v1/scheduling/queue/nack`	Negatively acknowledge (nack) a message to requeue it or route it to the DLQ.
`scheduling.queue.publish`	`POST /v1/scheduling/queue/publish`	Publish a single message to a queue (idempotent).
`scheduling.queue.publish_batch`	`POST /v1/scheduling/queue/publish_batch`	Publish multiple messages to a queue in a single batch.
`scheduling.queue.purge`	`POST /v1/scheduling/queue/purge/{queue}`	Purge all messages from a queue.
`scheduling.queue.push_subscribe`	`POST /v1/scheduling/queue/push_subscribe/{queue}`	Configure a push subscription to deliver queue messages to a callback URL.
`scheduling.queue.stats`	`GET /v1/scheduling/queue/stats/{queue}`	Retrieve queue metrics: available, in-flight, and dead-lettered message counts.
`scheduling.queue.update`	`PATCH /v1/scheduling/queue/update/{queue}`	Update a queue's DLQ, retry, and retention settings.
`scheduling.run.list`	`GET /v1/scheduling/run/list`	List scheduled run records with pagination.
`scheduling.task.schedule`	`POST /v1/scheduling/task/schedule`	Schedule a one-time task to fire once at a specified time.

完整示例

本模块的生产级端到端范例:先一次性配置,再运行业务流程,尽量覆盖本模块的多数 API。

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 2) scheduling.cron.create
curl -X POST https://api.infrai.cc/v1/scheduling/cron/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cron_expr": "0 9 * * 1", "task_type": "http_url", "task_url": "https://api.acme.com/weekly"}'

# 3) scheduling.cron.list
curl -X GET https://api.infrai.cc/v1/scheduling/cron/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 4) scheduling.queue.publish
curl -X POST https://api.infrai.cc/v1/scheduling/queue/publish \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "orders", "payload": {"order_id": "o_123"}, "priority": 5}'

# 5) scheduling.cron.get
curl -X GET https://api.infrai.cc/v1/scheduling/cron/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 6) scheduling.cron.update
curl -X PATCH https://api.infrai.cc/v1/scheduling/cron/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 7) scheduling.cron.delete
curl -X DELETE https://api.infrai.cc/v1/scheduling/cron/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 8) scheduling.cron.pause
curl -X POST https://api.infrai.cc/v1/scheduling/cron/pause/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cron_id": "..."}'

# 9) scheduling.cron.resume
curl -X POST https://api.infrai.cc/v1/scheduling/cron/resume/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cron_id": "..."}'