服务端 API商业版

创建定时任务

创建一个按指定时间执行并回调业务服务的定时任务。此接口仅在 OpenIM 商业版中提供。请先在接入准备中配置 API 地址和有效 Token。

HTTP 请求

POST {API_ADDRESS}/timer/create_timer_task

请求示例

curl --request POST "${API_ADDRESS}/timer/create_timer_task" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${TOKEN}" \
  --data-raw '{
  "taskName": "示例名称",
  "taskCategory": "reminder",
  "executeAt": 1719800000000,
  "executeBefore": 0,
  "maxRetry": 1,
  "callbackConfig": {
    "callbackMethod": "example",
    "callbackPayload": "示例内容"
  },
  "userID": "user_001",
  "dedupKey": "example"
}'

商业版：此接口需要部署对应的商业版服务。接口是否可用以及具体权限以客户交付版本为准。

请求体

{
  "taskName": "示例名称",
  "taskCategory": "reminder",
  "executeAt": 1719800000000,
  "executeBefore": 0,
  "maxRetry": 1,
  "callbackConfig": {
    "callbackMethod": "example",
    "callbackPayload": "示例内容"
  },
  "userID": "user_001",
  "dedupKey": "example"
}

参数名	是否必填	类型	说明
taskName	是	string	定时任务名称。
taskCategory	是	string	定时任务业务分类。
executeAt	是	int	计划执行时间，Unix 毫秒时间戳。
executeBefore	是	int	允许执行的最晚时间，Unix 毫秒时间戳。
maxRetry	是	int	任务执行失败后的最大重试次数。
callbackConfig	是	TimerTaskCallbackConfig	结构为定时任务模块的 `TimerTaskCallbackConfig`。
userID	是	string	OpenIM 用户 ID。
dedupKey	是	string	业务幂等键，用于避免重复创建任务。

响应

请求被 OpenIM 正常处理时通常返回 200 OK。业务是否成功以响应体中的 errCode 为准。

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "task": {
      "taskID": "task_001",
      "taskName": "示例名称",
      "taskCategory": "reminder",
      "srcUserID": "user_001",
      "executeAt": 1719800000000,
      "executeBefore": 0,
      "maxRetry": 1,
      "callbackConfig": {
        "callbackMethod": "example",
        "callbackPayload": "示例内容"
      },
      "createdAt": 1719800000000,
      "updatedAt": 1719800000000,
      "dedupKey": "example"
    }
  }
}

响应参数

参数名	类型	说明
errCode	int	业务错误码，`0` 表示成功。
errMsg	string	错误简要信息，成功时通常为空。
errDlt	string	错误详细信息，成功时通常为空。
data.task	TimerTask	结构为定时任务模块的 `TimerTask`。

错误

错误响应使用 Platform API 通用结构，处理方式见错误码。

权限和限制

仅在 OpenIM 商业版中提供。
调用方必须校验操作用户和目标资源的业务权限。
请求数组和分页大小应遵循客户交付版本的服务端限制。

HTTP 请求

请求示例

请求体

响应

响应参数

错误

权限和限制

相关页面