更新 Worker 任务

方法: PUT

端点: /api/v2/worker-tasks/{workerTaskId}

认证: 支持 Authorization: Bearer <YOUR_API_KEY>、api-key: <YOUR_API_KEY> 和 ?token=<YOUR_API_KEY>。推荐优先使用 Bearer token。

在线试用

PUT/api/v2/worker-tasks/{workerTaskId}Update worker task

AuthenticationRequired

Auth mode

Authorization: Bearerapi-key headerQuery token

API token

Stored only in this browser tab. Sent only to https://openapi.coreclaw.com.

Parameters

workerTaskIdpath · stringRequired

Saved Worker task template slug. Get it from the `data.list[].slug` field of `GET /api/v2/worker-tasks`. The playground prefills a sample slug; replace it with your own.

Request BodyRequiredapplication/json

FieldTypeRequiredDescription

descriptionstringOptionalTask description. Omit to keep current description.

recipient_emailstringOptionalEmail address notified when the task finishes.

schedule_datestringOptionalStart date/time for the schedule. YYYY-MM-DD or YYYY-MM-DD HH:mm.

schedule_dayintegerOptionalDay of month for monthly schedule (1-31). Omit to keep current. Single-day compatibility field; prefer schedule_days. Constraints: range 1-31.

schedule_day_intervalintegerOptionalRepeat every N days for daily schedules. Default 1. Constraints: minimum 1.

schedule_daysstringOptionalDays of month for monthly schedules, comma-separated (e.g. 1,15,31).

schedule_enabledenum: 0, 1OptionalSchedule switch. 0=disabled, 1=enabled. Constraints: allowed values: `0`, `1`.

schedule_hour_intervalintegerOptionalRepeat every N hours for schedule_type=5. Required when type 5. Range 1-23. Constraints: range 1-23.

schedule_minute_intervalintegerOptionalRepeat every N minutes for schedule_type=6. Required when type 6. Range 1-59. Constraints: range 1-59.

schedule_once_datestringOptionalOnce schedule date in YYYY-MM-DD.

schedule_timestringOptionalSchedule time in HH:mm.

schedule_timezonestringOptionalIANA timezone for the schedule. Default Asia/Shanghai (e.g. UTC, America/New_York).

schedule_typeenum: 1, 2, 3, 4, 5, 6OptionalSchedule type. 1=daily, 2=weekly, 3=monthly, 4=once, 5=every N hours, 6=every N minutes. Constraints: allowed values: `1`, `2`, `3`, `4`, `5`, `6`.

schedule_weekdayenum: 1, 2, 3, 4, 5, 6, 7OptionalWeekday for weekly schedule. 1=Monday ... 7=Sunday. Omit to keep current. Single-day compatibility field; prefer schedule_weekdays. Constraints: range 1-7; allowed values: `1`, `2`, `3`, `4`, `5`, `6`, `7`.

schedule_weekdaysstringOptionalDays of week for weekly schedules, comma-separated (e.g. 1,3,5).

task_template_idintegerOptionalAssociated task template ID.

titlestringOptionalTask title. Omit to keep current title.

Request body (JSON)Reset to example

{ "description": "Scrape Google Maps business records on a schedule.", "recipient_email": "YOUR_RECIPIENT_EMAIL", "schedule_date": "YOUR_SCHEDULE_DATE", "schedule_day": 1, "schedule_day_interval": 1, "schedule_days": "YOUR_SCHEDULE_DAYS", "schedule_enabled": 0, "schedule_hour_interval": 1, "schedule_minute_interval": 1, "schedule_once_date": "2026-08-01", "schedule_time": "09:00", "schedule_timezone": "YOUR_SCHEDULE_TIMEZONE", "schedule_type": 1, "schedule_weekday": 1, "schedule_weekdays": "YOUR_SCHEDULE_WEEKDAYS", "task_template_id": 0, "title": "Google Maps Scraper (Task)" }

Send Request Clear all

什么时候使用这个接口

用于更新任务模板的标题、描述或调度配置；省略的字段保持原值。

标识符说明

• workerTaskId 是已保存任务模板的 slug。

路径参数

参数	必填	类型	说明
workerTaskId	是	string	已保存 Worker 任务模板的 slug，可从 GET /api/v2/worker-tasks 响应的 data.list[].slug 获取。

请求体

使用 Content-Type: application/json 发送请求体。表格中的必填/选填描述字段本身是否必须提供；整个请求体是否必填以在线试用区的 Request Body 标记为准。

字段	必填	类型	说明
description	否	string	任务模板描述，可选。
recipient_email	否	string	任务结束时接收通知的邮箱。
schedule_day	否	integer	每月调度时的日期（1-31）。单日兼容字段；建议使用 schedule_days。
schedule_day_interval	否	integer	每天调度时每 N 天执行一次，默认 1。
schedule_days	否	string	每月调度时的日期列表，逗号分隔，如 1,15,31。
schedule_enabled	否	enum: 0, 1	调度开关：1 启用，0 关闭。
schedule_hour_interval	否	integer	schedule_type=5 时每 N 小时执行一次，必填。范围 1-23。
schedule_minute_interval	否	integer	schedule_type=6 时每 N 分钟执行一次，必填。范围 1-59。
schedule_once_date	否	string	单次调度的日期，格式 YYYY-MM-DD。
schedule_time	否	string	调度执行时间，格式 HH:mm。
schedule_timezone	否	string	调度所在 IANA 时区，默认 Asia/Shanghai（如 UTC、America/New_York）。
schedule_type	否	enum: 1, 2, 3, 4, 5, 6	调度类型：1=每天，2=每周，3=每月，4=单次，5=每 N 小时，6=每 N 分钟。
schedule_weekday	否	enum: 1, 2, 3, 4, 5, 6, 7	每周调度时的星期几（1=周一 … 7=周日）。单日兼容字段；建议使用 schedule_weekdays。
schedule_weekdays	否	string	每周调度时的星期几列表，逗号分隔，如 1,3,5。
task_template_id	否	integer	关联的任务模板 ID。
title	否	string	任务模板标题，用于展示和搜索。

调度说明

启用调度时需将 schedule_enabled 设为 1，并同时提供 schedule_type 及该类型要求的字段：

schedule_type	含义	配套字段
1	每天	schedule_time；可选 schedule_day_interval（每 N 天，默认 1）。
2	每周	schedule_time；schedule_weekdays（如 1,3,5）或 schedule_weekday。
3	每月	schedule_time；schedule_days（如 1,15,31）或 schedule_day。
4	单次	schedule_once_date（YYYY-MM-DD）和 schedule_time。
5	每 N 小时	schedule_hour_interval（1-23）。
6	每 N 分钟	schedule_minute_interval（1-59）。

调度按 schedule_timezone（默认 Asia/Shanghai）解释。API 生成的 cron 为 console 兼容格式：带秒字段且带 CRON_TZ 前缀，例如 CRON_TZ=Asia/Shanghai 0 30 9 * * *。console 调度器只注册这种格式的调度。

JSON 示例

{
  "description": "Scrape Google Maps business records on a schedule.",
  "schedule_day": 1,
  "schedule_enabled": 0,
  "schedule_once_date": "2026-08-01",
  "schedule_time": "09:00",
  "schedule_type": 1,
  "schedule_weekday": 1,
  "title": "Google Maps Scraper (Task)"
}

请求示例

curl -X PUT "https://openapi.coreclaw.com/api/v2/worker-tasks/YOUR_WORKER_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"description":"Scrape Google Maps business records on a schedule.","schedule_day":1,"schedule_enabled":0,"schedule_once_date":"2026-08-01","schedule_time":"09:00","schedule_type":1,"schedule_weekday":1,"title":"Google Maps Scraper (Task)"}'

响应示例

{
  "code": 0,
  "message": "success",
  "request_id": "req-123"
}

注意事项

• API v2 同时支持 Bearer token、旧版 api-key 请求头和 query token；新集成建议优先使用 Bearer token。
• PUT 为部分更新语义：省略的字段保持原值，无需重传整个任务对象。
• 如需更新任务输入参数本身（而非标题或调度），请使用 PUT /api/v2/worker-tasks/{workerTaskId}/input。
• API 服务本身不执行定时任务；调度到点触发依赖 console 调度器正常启动。重新保存调度配置会重新生成 console 兼容格式的 cron（带秒字段且带 CRON_TZ 前缀），供调度器注册。

HTTP 响应

HTTP 状态	应用代码	含义
200	0	请求成功。
400	11000	请求参数不合法。
401	12001	认证缺失或无效。
404	11004	目标资源不存在。
422	11000	请求语义或字段校验未通过。
429	13000	请求过于频繁。
500	10000	服务端内部错误。