调用该接口创建设备任务。

QPS限制

单个阿里云账号调用该接口的每秒请求数（QPS）最大限制为5。

说明 RAM用户共享阿里云账号配额。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String 是 CreateJob

系统规定参数。取值：CreateJob。
JobDocument String 是 { "serviceIdentifier": "test_service", "params": { "key1": "value1", "key2": "value2" } }

下发给设备的任务执行规则文件。数据格式为JSON，长度不超过65536个字符。

更多信息，请参见下文“JobDocument定义”。
JobName String 是 oneJob

任务名称。支持中文、英文字母、数字和下划线（_），长度范围为4~30个字符。
TargetConfig Json 是 {"targetType":"PRODUCT_KEY","targetProduct":"a1j***3d"}

设备任务的目标设备配置。

更多信息，请参见下文“TargetConfig”。
Type String 是 INVOKE_SERVICE

任务类型。取值：

  • INVOKE_SERVICE：设备批量服务调用任务。
  • SET_PROPERTY：设备批量属性设置任务。
  • PUB：Pub批量消息推送任务。
  • CUSTOM_JOB：自定义任务。
IotInstanceId String 否 iot-cn-0pp1n8t****

实例ID。您可在物联网平台控制台的实例概览页面，查看当前实例的ID。

重要
  • 若有ID值，必须传入该ID值，否则调用会失败。
  • 若无实例概览页面或ID值，则无需传入。

实例的更多信息，请参见实例概述。

Description String 否 jobDescription

任务的描述信息。长度不超过100个字符。
JobFile Json 否 { "fileKey":"5cc34***f9/tazJ***s", "signMethod":"Sha256", "sign":"***" }

自定义任务中下发给设备的文件。

仅Type为CUSTOM_JOB时，可传入此参数，且为非必传参数。

更多信息，请参见下文“JobFile定义”。
TimeoutConfig Json 否 {"inProgressTimeoutInMinutes": 60}

任务下作业执行的超时配置，数据格式为JSON，长度不超过8192个字符。

更多信息，请参见下文“TimeoutConfig定义”。
RolloutConfig Json 否 {"maximumPerMinute": 1000}

任务下作业推送速率配置，数据格式为JSON，长度不超过8192个字符。

更多信息，请参见下文“RolloutConfig定义”。
ScheduledTime Long 否 1557062301656

任务调度时间的毫秒数。取值范围：当前时间的10分钟后到7天之间。

  • 不传入此参数：任务创建后，立即初始化并调度执行。
  • 传入此参数：任务创建后，先初始化，等到设置的调度时间后，才开始调度执行。
TargetConfig定义

名称

类型

描述

TargetType

String

目标设备的配置类型，可选值：

DEVICE_LIST，表示设备列表。

GROUP_ID，表示设备分组ID。

PRODUCT_KEY，表示设备所属产品的ProductKey。

TargetDevices

List

设备任务的目标设备。仅TargetType为DEVICE_LIST时，传入此参数。

此参数最多传入200个设备。

更多信息，请参见下文“TargetDevice定义”。

TargetGroup

String

设备任务的目标设备，所属设备分组的标识符（GroupID）。仅TargetType为GROUP_ID时，传入此参数。

不支持设置为设备动态分组的ID。

此设备分组中最多包含10万个设备。

TargetProduct

String

设备任务的目标设备，所属产品的ProductKey。仅TargetType为PRODUCT_KEY时，传入此参数。

此产品下最多包含10万个设备。
TargetDevice定义

名称

类型

描述

IotId

String

目标设备的设备ID。

ProductKey

String

目标设备所属产品的ProductKey。

如果传入该参数，需同时传入DeviceName。

DeviceName

String

目标设备名称。

如果传入该参数，需同时传入ProductKey。

示例1


{
	"TargetDevices":
	[
		{
			"IotId":"OPx***00101",
			"ProductKey":"a1A***n",
			"DeviceName":"devicenew"
		}
	],
	"TargetType":"DEVICE_LIST"
}

示例2


{
	"targetGroup":"rY2***01",
	"targetType":"GROUP_ID"
}

示例3


{
	"targetType":"PRODUCT_KEY",
	"targetProduct":"a1j***3d"
}
RolloutConfig定义

名称

类型

描述

maximumPerMinute

Integer

任务下每分钟推送的作业数量。默认值是1000。取值范围为50~1000。

messageQoS

String

发送消息类型，仅对自定义任务和Pub批量消息推送任务生效。可取值：

QoS0，表示最多发送一次。

QoS1，表示最少发送一次。如果QoS1消息未接收到PUBACK消息，会在设备重连时，重新推送给设备。

示例


{
  "maximumPerMinute": 1000,
  "messageQoS":"QoS1"
}
TimeoutConfig定义

名称

类型

描述

inProgressTimeoutInMinutes

Integer

任务下作业执行的超时时间，单位为分钟。

该参数仅对自定义任务生效。

从任务开始执行（状态更新为IN_PROGRESS）时计算，如果超过了超时时间，任务下作业仍未执行完成，将被自动设置为TIMED_OUT状态。

取值范围：

INVOKE_SERVICE类型任务：最大值为5，最小值为1，默认值为1。

SET_PROPERTY类型任务：最大值为5，最小值为1，默认值为1。

CUSTOM_JOB类型任务：最大值为3600，最小值为1，默认值为60。

示例


{
  "inProgressTimeoutInMinutes": 60
}
JobDocument定义

INVOKE_SERVICE类型的任务用于批量调用设备服务，功能与InvokeThingsService相似。

名称

类型

描述

serviceIdentifier

String

服务的标识符Identifier。

您可在物联网平台控制台对应实例下，单击设备管理 > 产品，找到设备所属产品，在产品详情的功能定义中查看。

params

Object

要调用服务的入参信息。更多信息，请参见下文“params定义”。
params定义

名称

类型

描述

key

String

输入参数的标识符。您在创建该服务时，设置的输入参数的标识符。

您可在物联网平台控制台，设备所属产品的功能定义页面，从该产品的物模型，或单击该服务对应的编辑按钮，查看您设置的输入参数。

value

String

指定参数值。该值需在您设置的输入参数的取值范围内。

示例


{
	"serviceIdentifier": "test_service",
	"params": {
		"key1": "value1",
		"key2": "value2"
	}
}

SET_PROPERTY类型的Job用于批量设置设备属性值，功能与SetDevicesProperty相似。

名称

类型

描述

params

Object

要设置的属性信息，组成为key:value。更多信息，请参见下文“params定义”。
params定义

名称

类型

描述

key

String

要设置属性的标识符identifier。您可在物联网平台控制台中，设备所属产品的功能定义中查看。

设置的属性必需是读写型。如果您指定了一个只读型的属性，设置将会失败。

value

String

属性值。取值需和您定义属性的数据类型和取值范围保持一致。

 

{
	"params": {
			"key1": "value1",
			"key2": "value2"
	 }
}

CUSTOM_JOB为自定义任务。

名称

类型

描述

key

String

自定义属性。

value

String

自定义属性值。

 

{
  "key":"value"
}
JobFile定义

名称

类型

描述

fileKey

String

使用GenerateFileUploadURL接口生成的文件Key。

创建任务前，必须先上传文件。具体操作，请参见GenerateFileUploadURL的“使用说明”。

创建任务时会校验文件是否已经上传。

signMethod

String

签名方法，可取值MD5和SHA256。

sign

String

签名，通过URL上传的文件的根据相应的签名方法生成的签名参数。

示例


{
  "fileKey":"5cc34***/tazJff***",
  "signMethod":"",
  "sign":""
}

调用API时，除了本文介绍的该API的特有请求参数，还需传入公共请求参数。公共请求参数说明，请参见公共参数文档。

返回数据

名称 类型 示例值 描述
Code String iot.system.SystemException

调用失败时，返回的错误码。更多信息，请参见错误码。

ErrorMessage String 系统异常

调用失败时，返回的出错信息。
JobId String XUbmsMHmkqv0PiAG****010001

任务ID。任务的全局唯一标识符。
RequestId String E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565

阿里云为该请求生成的唯一标识符。
Success Boolean true

表示是否调用成功。

  • true：调用成功。
  • false：调用失败。

示例

请求示例

https://iot.cn-shanghai.aliyuncs.com/?Action=CreateJob
&JobDocument={ "serviceIdentifier": "test_service", "params": { "key1": "value1", "key2": "value2" } } 
&JobName=oneJob
&TargetConfig={"targetType":"PRODUCT_KEY","targetProduct":"a1j***L3d"}
&Type=INVOKE_SERVICE
&RolloutConfig={"maximumPerMinute": 1000}
&TimeoutConfig={"inProgressTimeoutInMinutes": 60}
&<公共请求参数>

正常返回示例

XML格式 

<CreateJobResponse>
  <RequestId>E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565</RequestId>
  <JobId>XUbmsMHmkqv0PiAG****010001</JobId>
  <Success>true</Success>
</CreateJobResponse>

JSON格式 

{
    "RequestId": "E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565",
    "JobId": "XUbmsMHmkqv0PiAG****010001",
    "Success": true
}

错误码

访问错误中心查看更多错误码。