Queries device distribution tasks.

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.