云端任务接口用于让 GrowthOS 指挥客户站点连接器执行操作。典型任务包括发布文章、删除文章、回滚内容、应用 SEO/GEO overlay。 任务领取会改变任务状态，因此必须使用 POST /site/jobs/next。连接器领取任务后需要在 lease 过期前执行，并通过完成接口回传结果。

​
接口总览

能力方法路径调用方
领取下一条任务POST/site/jobs/next插件或客户站点 worker
完成任务POST/site/jobs/{id}/complete插件或客户站点 worker

​
通用请求头

Header必填说明
Authorization: Bearer <site_token>是站点服务端 token
Content-Type: application/json写接口必填请求体格式
Idempotency-Key建议领取和完成任务重试时保持一致

​
POST /site/jobs/next

领取一条待执行任务。成功领取后，任务会变成 running，并返回 claimToken 与 leaseUntil。 
POST /api/connector/v1/site/jobs/next
Authorization: Bearer <site_token>
Content-Type: application/json
Idempotency-Key: claim-worker-01-20260601T120000

​
请求示例

curl -X POST "$CONNECTOR_API_BASE/site/jobs/next" \
  -H "Authorization: Bearer YOUR_SITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: claim-worker-01-20260601T120000" \
  -d '{}'

​
成功响应

{
  "ok": true,
  "data": {
    "siteId": "site_id",
    "job": {
      "id": "job_id",
      "type": "publish_article",
      "status": "running",
      "title": "Publish article",
      "attempts": 1,
      "maxAttempts": 3,
      "claimToken": "claim_token",
      "leaseUntil": "2026-06-01T08:05:00.000Z",
      "payload": {
        "contentId": "content_id",
        "externalId": "wp-post-43",
        "type": "post",
        "locale": "zh-CN",
        "path": "/archives/43",
        "title": "Article title",
        "content": "<p>Article HTML</p>",
        "action": "publish"
      },
      "createdAt": "2026-06-01T08:00:00.000Z",
      "updatedAt": "2026-06-01T08:00:00.000Z"
    }
  },
  "requestId": "request_id"
}
没有可领取任务时： 
{
  "ok": true,
  "data": {
    "siteId": "site_id",
    "job": null
  },
  "requestId": "request_id"
}

​
Job 字段

字段说明
id任务 ID
type任务类型，例如 sync_content、publish_article、apply_seo_overlay
status当前任务状态
payload任务载荷，结构随任务类型变化
attempts当前尝试次数
maxAttempts最大尝试次数
claimToken本次领取凭证，完成任务时必须带回
leaseUntil租约过期时间

​
POST /site/jobs//complete

回传任务执行结果。完成接口必须携带领取任务时返回的 claimToken。 
POST /api/connector/v1/site/jobs/{id}/complete
Authorization: Bearer <site_token>
Content-Type: application/json
Idempotency-Key: complete-job-id-attempt-1

​
Path 参数

参数类型必填说明
idstring是任务 ID

​
Body 参数

字段类型必填说明
okboolean是任务是否执行成功
claimTokenstring是领取任务时返回的 claimToken
result.externalIdstring成功时建议客户站点侧内容 ID
result.urlstring成功时建议客户站点侧访问 URL
result.pathstring成功时建议客户站点侧路径
result.statusstring否客户站点侧状态
result.messagestring否说明信息
result.dataobject否扩展结果
errorstring失败时建议错误原因

​
成功示例

curl -X POST "$CONNECTOR_API_BASE/site/jobs/job_id/complete" \
  -H "Authorization: Bearer YOUR_SITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: complete-job-id-attempt-1" \
  -d '{
    "ok": true,
    "claimToken": "claim_token",
    "result": {
      "externalId": "wp-post-43",
      "url": "https://customer.example/archives/43",
      "path": "/archives/43",
      "status": "published"
    }
  }'

​
失败示例

{
  "ok": false,
  "claimToken": "claim_token",
  "error": "WordPress publish failed: permission denied"
}

​
完成响应

{
  "ok": true,
  "data": {
    "job": {
      "id": "job_id",
      "type": "publish_article",
      "status": "succeeded",
      "completedAt": "2026-06-01T08:01:00.000Z",
      "updatedAt": "2026-06-01T08:01:00.000Z"
    }
  },
  "requestId": "request_id"
}

​
Lease 机制

字段说明
claimToken任务领取凭证，完成任务时必须带回
leaseUntil当前领取租约过期时间
attempts本任务已尝试次数
maxAttempts本任务最大可尝试次数
如果连接器崩溃或网络中断，GrowthOS 会恢复过期任务。连接器不应并发执行同一任务，也不应在 claimToken 不匹配时强行回传成功。

​
常见错误

HTTP错误码说明处理建议
400INVALID_REQUEST缺少 claimToken 或请求体格式错误修正请求体
401INVALID_TOKENtoken 无效检查站点 token
404NOT_FOUND任务不存在停止处理该任务
409RESOURCE_CONFLICT租约不匹配、任务已完成或幂等冲突重新领取任务或复用正确幂等键
429RATE_LIMITED请求过快按 Retry-After 退避重试

​
实现要点

  • worker 应按固定间隔轮询 POST /site/jobs/next。
  • 任务执行失败也要调用完成接口，并返回 ok: false。
  • 发布、删除、回滚等站点侧操作也应做幂等处理。
  • 网络超时后重试完成任务时，要复用同一个 Idempotency-Key 和 claimToken。