火山方舟
火山方舟
API参考
请输入
- 文档首页
火山方舟Managed Agents APIEnvironments自建 Worker续租 Work
复制全文
下载 pdf续租 Work
文档反馈
问问助手POST https://ark.cn-beijing.volces.com/api/v3/environments/{environment_id}/work/{work_id}/heartbeat
执行 Work 期间，Worker 应每 30～60 秒调用本接口续租。
认领后的第一次心跳会将 Work 状态从 starting 更新为 active。
Worker 应在认领和续租时传入同一个非空 Ark-Worker-ID。省略该请求头可兼容未设置 Worker ID 的旧客户端，但不能恢复已停止的 Work。
后续请求应将上一次响应的 last_heartbeat 原样传入 expected_last_heartbeat。
Ark-Worker-ID 与认领该 Work 的 Worker 不一致、多个 Worker 同时续租，或 expected_last_heartbeat 不是最近一次返回值时，服务端返回 HTTP 412 PreconditionFailed。
收到该错误后，应先查询 Work 的最新状态。
确认仍由当前 Worker 执行后，再发送心跳。
若心跳中断，Work 会在最近一次成功心跳的租约到期并经过 60 秒宽限期后进入 stopped。
因租约到期停止后，认领该 Work 的原 Worker 可以携带相同的非空 Ark-Worker-ID 再次发送心跳。服务端校验所有权后，将 Work 直接恢复为 active 并续租，不会重新排队，也不会转交其他 Worker。处于 stopping 状态或因其他原因停止的 Work 不能通过心跳恢复。
若响应的 lease_extended 为 false，Worker 应停止执行并退出心跳循环。
鉴权
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数
Path 参数
environment_id string 必选 | 环境 ID
要操作的 Environment ID，以 env- 开头。填写创建环境或查询环境列表接口取得的 ID。
work_id string 必选 | Work 标识符
要续租的 Work 唯一标识，取自拉取 Work 接口响应中的 id，以 sesn- 开头。
Query 参数
在 URL Query String 中传入。
desired_ttl_seconds integer 默认值 300 | 期望租约 TTL
Worker 期望本次续租采用的租约 TTL，单位为秒。
说明
传入正数时使用请求值；省略或传入非正数时，服务端按 300 秒处理。
expected_last_heartbeat string | 乐观并发校验值
用于防止多个 Worker 同时续租同一 Work。第一次心跳可省略，也可传 NO_HEARTBEAT；后续请求必须原样传入上一次响应的 last_heartbeat。默认值：NO_HEARTBEAT
Header 参数
在 HTTP 请求头中传入。
Ark-Worker-ID string | Worker 实例 ID
执行该 Work 的 Worker 实例 ID。应与认领 Work 时传入的非空 Ark-Worker-ID 完全一致。省略或传空字符串时，服务端按匿名 Worker 处理心跳，但不能恢复已停止的 Work。
响应参数
last_heartbeat string | 最近心跳时间
服务端记录的本次心跳时间，格式为 RFC 3339。发送下一次心跳时，将该值原样传入 expected_last_heartbeat。
lease_extended boolean | 租约是否续上
本次心跳是否延长 Work 租约。true 表示已正常续租，或原 Worker 已将因租约到期停止的 Work 恢复为 active 并续租；false 表示当前状态不允许续租。是否继续执行需结合 state 判断。
state string | 当前状态
Work 当前状态。可选值：queued、active、stopping、stopped。
说明
- queued：Work 仍处于待认领状态，应先调用认领 Work 接口，不应开始执行。
- active：Work 正在执行，或已由原 Worker 从租约到期导致的停止状态恢复，可以继续发送心跳。
- stopping：已收到停止请求，应停止当前任务。
- stopped：本次心跳未恢复 Work，不应继续执行或发送心跳。
ttl_seconds integer | 实际生效 TTL
服务端为当前 Work 记录的租约 TTL，单位为秒。
type string | 对象类型
类型标识，固定为 work_heartbeat。
续租 Work
发起调试等同于请求真实调用，可能产生云产品费用，请谨慎操作！
Request
cURL
curl -sS --fail-with-body -X POST \
"https://ark.cn-beijing.volces.com/api/v3/environments/<ENVIRONMENT_ID>/work/<WORK_ID>/heartbeat?desired_ttl_seconds=300&expected_last_heartbeat=NO_HEARTBEAT" \
-H "Authorization: Bearer $ARK_API_KEY"Response
{
"last_heartbeat": "2026-10-19T08:30:35Z",
"lease_extended": true,
"state": "active",
"ttl_seconds": 300,
"type": "work_heartbeat"
}最近更新时间：2026.10.28 15:45:26
这个页面对您有帮助吗？
有用
有用
无用
无用