ListDeviceDistributeJob - IoT Platform

Usage notes

If you use an Enterprise Edition instance, you must specify the IotInstanceId parameter when you call this operation. Otherwise, the call fails.

QPS limits

You can call this API operation up to five times per second per account.

Note The 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	ListDeviceDistributeJob	The operation that you want to perform. Set the value to ListDeviceDistributeJob.
PageSize	Integer	Yes	10	The number of entries to return on each page. Valid values: 1 to 200.
TargetUid	String	No	198***	The ID of the Alibaba Cloud account to which the devices are distributed.
CurrentPage	Integer	No	1	The number of the page to return. Default value: 1. The NextToken or CurrentPage parameter specifies a condition for displaying the results. You can specify one of the two parameters. If you specify both parameters at the same time, the NextToken parameter is used. For information about the NextToken parameter, see the description of the NextToken parameter.
Status	Integer	No	1	The status of the device distribution task. 0: The task is being initialized. 1: The task is running. 2: The task is completed. The status indicates that the distribution task is complete but does not indicate that all products and devices are distributed. To obtain distribution results, call the QueryDeviceDistributeDetail operation. 3: The task is unexpectedly interrupted.
JobId	String	No	UbmsMHmkqv0PiAG****010001	The ID of the distribution task. The ID is globally unique.
NextToken	String	No	TGlzdFJlc291***	The token that is used to retrieve subsequent pages of the query results. The first time you perform a query operation, you do not need to specify this parameter. The NextToken or CurrentPage parameter specifies a condition for displaying the results. You can specify one of the two parameters. If you specify both parameters at the same time, the NextToken parameter is used. Important The offset in the number of results is obtained by using the following formula: PageSize × (CurrentPage - 1). If the offset is greater than 10,000, you must use the token that is returned in the previous query as the value of the NextToken parameter to obtain the value of the Data parameter. Otherwise, the current request is terminated and the value of the Data parameter cannot be returned.
ProductKey	String	No	aw3zse****	The ProductKey of the product to which the device belongs.

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

Response parameters


Parameter	Type	Example	Description
Code	String	iot.system.SystemException	The error code that is returned if the call fails. For more information, see Error codes.
Data	Struct		The distribution tasks that are returned if the call is successful. For more information, see the JobInfo parameter.
JobInfo	Array of items		The information about the task.
items
GmtCreate	Long	1581595942000	The time when the task was created.
JobId	String	UbmsMHmkqv0PiAG****010001	The ID of the task.
ProductKey	String	a1BwAGV****	The ProductKey of the product to which the device belongs.
SourceInstanceId	String	iot-cn-6ja***	The ID of the source instance.
SourceInstanceName	String	Instance Debug 1	The name of the source instance.
SourceRegion	String	cn-shanghai	The region where the source instance resides.
SourceUid	String	198***	The ID of the source Alibaba Cloud account.
Status	Integer	1	The status of the task. 0: The task is being initialized. 1: The task is running. 2: The task is completed. The status indicates that the distribution task is complete but does not indicate that all products and devices are distributed. To obtain distribution results, call the QueryDeviceDistributeDetail operation. 3: The task is unexpectedly interrupted.
Strategy	Integer	0	The distribution policy. 0: distributes devices to specified instances in a specified region. This is the default value. 1: configures instance IDs in multiple regions and distributes devices to the nearest regions based on the IP addresses of the devices.
TargetInstanceConfigs	Array of targetInstanceConfigs		The IDs of the destination instances. If the value of the Strategy parameter is 1, multiple instance IDs exist. If the value of the Strategy parameter is 0, only one instance ID exists.
targetInstanceConfigs
TargetInstanceId	String	iot-cn-6ja***	The ID of the destination instance.
TargetInstanceName	String	Instance Debug 2	The name of the destination instance.
TargetRegion	String	cn-shanghai	The region where the destination instance resides.
TargetUid	String	198***	The ID of the destination Alibaba Cloud account.
Total	Integer	5	The total number of devices in the distribution task.
NextToken	String	TGlzdFJlc291***	The token that is used to retrieve the subsequent pages of the query results. The value of this parameter can be used in the next query to obtain the subsequent pages of results. If the return value is empty, no subsequent page exists.
Total	Integer	10	The total number of device distribution tasks.
ErrorMessage	String	A system exception occurred.	The error message that is returned if the call fails.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	The ID of the request.
Success	Boolean	true	Indicates whether the call was successful. Valid values: true: The call was successful. false: The call failed.

Examples

Sample requests

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=ListDeviceDistributeJob
&CurrentPage=1
&PageSize=10
&TargetUid=198***
&<Common request parameters>

Sample success responses

XML format

<ListDeviceDistributeJobResponse>
  <RequestId>E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565</RequestId>
  <Data>
        <NextToken>TGlzdFJlc291***</NextToken>
        <Total>10</Total>
        <JobInfo>
              <items>
                    <Status>1</Status>
                    <SourceInstanceName> Instance Debug 1</SourceInstanceName>
                    <GmtCreate>1581595942000</GmtCreate>
                    <SourceUid>198***</SourceUid>
                    <Total>5</Total>
                    <Strategy>0</Strategy>
                    <TargetUid>198***</TargetUid>
                    <SourceRegion>cn-shanghai</SourceRegion>
                    <SourceInstanceId>iot-cn-6ja***</SourceInstanceId>
                    <ProductKey>a1BwAGV****</ProductKey>
                    <JobId>UbmsMHmkqv0PiAG****010001</JobId>
                    <TargetInstanceConfigs>
                          <targetInstanceConfigs>
                                <TargetRegion>cn-shanghai</TargetRegion>
                                <TargetInstanceName> Instance Debug 2</TargetInstanceName>
                                <TargetInstanceId>iot-cn-6ja***</TargetInstanceId>
                          </targetInstanceConfigs>
                    </TargetInstanceConfigs>
              </items>
        </JobInfo>
  </Data>
  <Success>true</Success>
</ListDeviceDistributeJobResponse>

JSON format

{
    "RequestId": "E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565",
    "Data": {
        "NextToken":"TGlzdFJlc291***",
        "Total": 10,
        "JobInfo": {
            "items": {
                "Status": 1,
                "SourceInstanceName": "Instance Debug 1",
                "GmtCreate": 1581595942000,
                "SourceUid": "198***",
                "Total": 5,
                "Strategy": 0,
                "TargetUid": "198***",
                "SourceRegion": "cn-shanghai",
                "SourceInstanceId": "iot-cn-6ja***",
                "ProductKey": "a1BwAGV****",
                "JobId": "UbmsMHmkqv0PiAG****010001",
                "TargetInstanceConfigs": {
                    "targetInstanceConfigs": {
                        "TargetRegion": "cn-shanghai",
                        "TargetInstanceName": "Instance Debug 2",
                        "TargetInstanceId": "iot-cn-6ja***"
                    }
                }
            }
        }
    },
    "Success": true
}

Error codes

For a list of error codes, see Service error codes.