V2.5 Create Command Jobs¶

创建命令任务

操作权限¶

使用此 API 前，确保服务账号已被授予包含下列服务和操作权限的策略。有关授权服务账号的更多信息，参见管理服务账号。

需授权的服务	所需操作权限
设备管理服务	Full Access

请求格式¶

POST https://{apigw-address}/connect-service/v2.5/commands?action=createJob

请求参数（URI）¶

名称	位置（Path/Query）	必需/可选	数据类型	描述
orgId	Query	必需	String	资产所属的组织 ID。如何获取 orgId 信息>>

请求参数（Body）¶

名称	必需/可选	数据类型	描述
name	必需	StringI18n	Job 名称。结构参见国际化名称结构体。
targetScope	必需	结构体	参见 TargetScope 结构体。
schedulePolicy	必需	结构体	参见 SchedulePolicy 结构体。
timeoutPolicy	可选	结构体	参见 TimeoutPolicy 结构体。
retryPolicy	可选	结构体	参见 RetryPolicy 结构体。
desc	必需	String	任务描述，最大长度 100。
commandInfo	必需	结构体	参见 commandInfo 结构体。

TargetScope 结构体 ¶

名称

必需/可选

数据类型

描述

targetType

必需

String

可选择 device_list、product_key。

targetDevices

可选

结构体

最大数量1000，结构体含：

productKey : string
deviceKey : string
assetId : string，资产ID

SchedulePolicy 结构体 ¶

名称	必需/可选	数据类型	描述
scheduleType	必需	String	可选择 `DISPOSABLE`，目前仅一次性触发任务。
disposableSchedulePolicy	可选	结构体	结构体含 `triggerTs`：Number，触发时间戳。

TimeoutPolicy 结构体 ¶

名称	必需/可选	数据类型	描述
inProgressTimeoutInSeconds	可选	Integer	范围 1 ~ 900（默认为 30）
ttlTimeoutInSeconds	可选	Integer	范围 0 ~ 172800（默认为 0）

RetryPolicy 结构体 ¶

名称	必需/可选	数据类型	描述
enableRetry	可选	Boolean	`true`：开启失败重试。 `false`：不开启失败重试，默认为 `false`。
retryIntervalInSeconds	`enableRetry` 为 `true` 时必填	Number	失败后自动重试间隔时间（秒）。仅在 enableRetry 时生效。范围 0 ~ 86400（默认为 300）。
retryCount	`enableRetry` 为 `true` 时必填	Number	最大自动重试次数。仅在 enableRetry 时生效，范围：1 ~ 10（默认为 3）。

CommandInfo 结构体 ¶

响应参数¶

名称	数据类型	描述
code	Number	请求返回状态值。0表示请求成功，非0表示请求失败。
msg	String	对状态码的解释和说明。请求成功为 `OK` 。
requestId	String	每次请求获取的ID，用于唯一标识一次API请求。
data	String	无。

示例¶

请求示例¶

url: https://{apigw-address}/connect-service/v2.5/commands?action=createJob&orgId=yourOrgId
method: POST
requestBody:
{
    "timeoutPolicy": {
        "inProgressTimeoutInSeconds": 30,
        "ttlTimeoutInSeconds": 20
    },
    "retryPolicy": {
        "enableRetry": true,
        "retryCount": 3,
        "retryIntervalInSeconds": 300
    },
    "name": {
        "defaultValue": "commandJobName",
        "i18nValue": {
            "en_US": "name",
            "zh_CN": "中文名"
        }
    },
    "schedulePolicy": {
        "disposableSchedulePolicy": {
            "triggerTs": 1718952446317
        },
        "scheduleType": "DISPOSABLE"
    },
    "commandInfo": {
        "commandType": "SERVICE_INVOKE",
        "serviceInvokeInfo": {
            "inputData": {
                "input": 22
            },
            "serviceId": "serviceId"
        }
    },
    "targetScope": {
        "targetDevices": [{
            "deviceKey": "deviceKey",
            "productKey": "productKey"
        }],
        "targetType": "DEVICE_LIST"
    },
    "desc": "commandJobDescription"
}

返回示例¶

{
    "code": 0,
    "msg": "OK",
    "requestId": "95c4bac0-476e-4d07-bd09-1ae096ea24a4",
    "data": "jobId"
}