CreateDeviceDistributeJob - IoT Platform

Usage notes

To distribute devices, perform the following steps:

1. Asynchronously call this operation to create a device distribution task and obtain the JobId parameter.

2. Use JobId as a request parameter and repeatedly call the QueryDeviceDistributeJob operation to obtain the Status parameter.

Note You must control the frequency of calls based on the QPS limit of the QueryDeviceDistributeJob operation.

If either of the following values is returned for the Status parameter, the distribution task ends:

2: The device distribution task is completed. This return value does not indicate that the devices are distributed. To obtain the distribution result of each device, perform the next step.
3: The distribution is unexpectedly interrupted. After you process the error, you can initiate a device distribution task again.

3. Use JobId that is returned in Step 1 as a request parameter and call the QueryDeviceDistributeDetail operation to obtain the File parameter. The File parameter indicates the file URL of the distribution result.

Note The file URL is valid for 10 minutes.

4. Obtain the distribution result by using the file URL. The Code parameter indicates whether a device is distributed. If the value of the Code parameter is 200, the device is distributed.

If the distribution fails, you can perform the preceding steps to distribute devices again.

Limits

This operation can be called only by using the following endpoint: iot.cn-shanghai.aliyuncs.com.
You cannot call this operation to distribute devices across accounts.
Each Alibaba Cloud account can create a maximum of 10 tasks to distribute products or devices. For more information about how to create a product distribution task, see CreateProductDistributeJob.
Each Alibaba Cloud account can run a maximum of 2 queries per second (QPS).

Note RAM users of an Alibaba Cloud account share the quota of the account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	CreateDeviceDistributeJob	The operation that you want to perform. Set the value to CreateDeviceDistributeJob.
DeviceName.N	RepeatList	Yes	RepeatList	The names of the devices to be distributed. You can specify a maximum of 10,000 device names.
ProductKey	String	Yes	a1BwAGV****	The ProductKey of the product to which the device belongs.
SourceInstanceId	String	Yes	iot-060***	The ID of the source instance to which the device belongs. The IDs of public instances in different regions: China (Shanghai): iotx-oxssharez200. Japan (Tokyo): iotx-oxssharez300. Singapore (Singapore): iotx-oxssharez400. US (Silicon Valley): iotx-oxssharez500. US (Virginia): iotx-oxssharez600. Germany (Frankfurt): iotx-oxssharez700. The IDs of Enterprise Edition instances: 1. Log on to the IoT Platform console. Select a region from the drop-down list in the upper-left corner of the top navigation bar. 2. On the Overview page, click the instance name. On the Instance Details page, view the instance ID in the Basic Information section.
Strategy	Integer	Yes	0	The distribution policy. Default value: 0. 0: distributes devices to instances in a specified region. 1: configures instance IDs in multiple regions and distributes devices to the nearest regions based on the IP addresses of the devices.
TargetInstanceConfig.N.TargetInstanceId	String	Yes	iot-cn-6ja***	The configurations of the destination instance to which the device is distributed. For more information about instance IDs, see the description of the SourceInstanceId parameter. If the value of the Strategy parameter is 1, you can specify multiple instance IDs. If the value of the Strategy parameter is 0, you can specify only one instance ID.
TargetUid	String	No	198***	The ID of the Alibaba Cloud account to which the device belongs. You can log on to the IoT Platform console, click the profile picture, and then view the account ID on the Security Settings page. The TargetUid and TargetAliyunId parameters cannot be left empty at the same time.
TargetAliyunId	String	No	io****@example.com	The Alibaba Cloud account to which the device belongs. You can log on to the IoT Platform console, click the profile picture, and then view the account ID on the Security Settings page. The TargetUid and TargetAliyunId parameters cannot be left empty at the same time.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this operation. For more information, see Common request parameters.

Response parameters


Parameter	Type	Example	Description
Code	String	iot.system.SystemException	The error code returned if the call fails. For more information, see Error codes.
ErrorMessage	String	A system exception occurred.	The error message returned if the call fails.
JobId	String	UbmsMHmkqv0PiAG****010001	The task ID returned if the call is successful. The ID globally identifies the task.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	The ID of the request.
Success	Boolean	true	Indicates whether the call was successful. true: The call was successful. false: The call failed.

Examples

Sample requests

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=CreateDeviceDistributeJob
&DeviceName.1=RepeatList
&ProductKey=a1BwAGV****
&SourceInstanceId=iot-060***
&Strategy=0
&TargetInstanceConfig.1.TargetInstanceId=iot-cn-6ja***
&TargetAliyunId=io****@example.com
&<Common request parameters>

Sample success responses

XML format

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

JSON format

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