Queries device distribution tasks.

Usage notes

Each Alibaba Cloud account can run a maximum of 5 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 a 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 No 10

The number of entries to return on each page. Maximum value: 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 based on which the results are displayed. You can specify one of these two parameters. If you specify these two parameters at the same time, the NextToken parameter is used.

For more information about the NextToken parameter, see the description of this parameter.

Status Integer No 1

The status of the device distribution task.

  • 0: The task is being initialized.
  • 1: The task is being implemented.
  • 2: The task is completed. This status only indicates that the distribution task is completed. This status 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 globally identifies the task.

NextToken String No TGlzdFJlc291***

The token that is used to retrieve the next page of results. You do not need to specify this parameter for the first query.

The NextToken or CurrentPage parameter specifies a condition based on which the results are displayed. You can specify one of these two parameters. If you specify these two parameters at the same time, the NextToken parameter is used.

Notice

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 returned in the last query as the value of the NextToken parameter to obtain the Data parameter. Otherwise, the current request is terminated and the Data parameter cannot be returned.

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.

Data Struct

The distribution tasks returned if the call is successful. For more information, see JobInfo.

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 in which 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 being implemented.
  • 2: The task is completed. This status only indicates that the distribution task is completed. This status 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 instances in a specified region. This policy is used by default.
  • 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 in which 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 next page of results. You can specify this parameter in the next query to obtain the next page of results.

If the return value is empty, no next page exists.

Total Integer 10

The total number of device distribution tasks.

ErrorMessage String A system exception occurred.

The error message 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.

  • 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 response

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, visit the API Error Center.