CreateJob_物联网平台_API文档-阿里云OpenAPI开发者门户

接口说明

QPS 限制

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

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

流控信息

请求速率为5/1(s)。更多流控信息，请前往配额中心查看

授权信息

当前云产品暂无权限信息透出。

请求参数

字段名称	字段详情
IotInstanceIdstring	实例 ID。您可在物联网平台控制台的实例概览页面，查看当前实例的 ID。展开详情示例值:iot-cn-0pp1n8t****
Descriptionstring	任务的描述信息。长度不超过 100 个字符。示例值:jobDescription
JobDocumentstring	下发给设备的任务执行规则文件。数据格式为 JSON，长度不超过 65536 个字符。展开详情示例值:{ "serviceIdentifier": "test_service", "params": { "key1": "value1", "key2": "value2" } } 参考取值来源: QueryJob
Typestring	任务类型。取值：展开详情示例值:INVOKE_SERVICE
JobFileobject	自定义任务中下发给设备的文件。展开详情示例值:{ "fileKey":"5cc34*f9/tazJs", "signMethod":"Sha256", "sign":"**" }参考取值来源: QueryJob
JobNamestring	任务名称。支持中文、英文字母、数字和下划线（_），长度范围为 4~30 个字符。示例值:oneJob参考取值来源: QueryJob ListJob
TimeoutConfigobject	任务下作业执行的超时配置，数据格式为 JSON，长度不超过 8192 个字符。展开详情示例值:{"inProgressTimeoutInMinutes": 60}
RolloutConfigobject	任务下作业推送速率配置，数据格式为 JSON，长度不超过 8192 个字符。展开详情示例值:{"maximumPerMinute": 1000}
TargetConfigobject	设备任务的目标设备配置。展开详情示例值:{"targetType":"PRODUCT_KEY","targetProduct":"a1j***3d"}
ScheduledTimeinteger<int64>	任务调度时间的毫秒数。取值范围：当前时间的 10 分钟后到 7 天之间。展开详情注意该字段类型为 Long，在序列化/反序列化的过程中可能导致精度丢失，请注意数值不得大于 9007199254740991。示例值:1557062301656

请求说明

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 的特有请求参数，还需传入公共请求参数。公共请求参数说明，请参见公共参数文档。

返回参数

字段名称	字段详情
Codestring	调用失败时，返回的错误码。更多信息，请参见错误码。示例值:iot.system.SystemException
ErrorMessagestring	调用失败时，返回的出错信息。示例值:系统异常
RequestIdstring	阿里云为该请求生成的唯一标识符。示例值:E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565
Successboolean	表示是否调用成功。展开详情示例值:true
JobIdstring	任务 ID。任务的全局唯一标识符。示例值:XUbmsMHmkqv0PiAG****010001

返回示例

变更历史

暂无变更历史