Adds device topologies in batches.

Limits

  • You can attach a maximum of 10 sub-devices to a gateway in a single call.
  • The API operation caller must be the gateway owner.
  • Each Alibaba Cloud account can run a maximum of 5 queries per second (QPS).
  • If you specify a sub-device that is attached to a gateway, the gateway is replaced with the specified gateway.
  • If one of the sub-devices fails to establish the topology with a gateway, the system rolls back and all sub-devices fail to establish topologies with the gateway.
  • Each Alibaba Cloud account can run a maximum of 10 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 BatchAddThingTopo

The operation that you want to perform. Set the value to BatchAddThingTopo.
GwDeviceName String Yes gateway

The name of the gateway.
GwProductKey String Yes a1vL7cp****

The key of the product to which the gateway belongs.
TopoAddItem.N.DeviceName String Yes light

The name of each sub-device.
TopoAddItem.N.ProductKey String Yes a1BwAGV****

The key of the product to which the sub-device belongs.
TopoAddItem.N.Sign String Yes C1C1606D61884C5F16C9EA6622E5****

The signature of the sub-device.

Use the result that is calculated by using the SignMethod(deviceSecret,content) function as the value of the Sign parameter.

In the preceding function, the content parameter includes the result after the system performs the following steps: Sort all sub-device parameters that are submitted to the server (excluding the Sign and SignMethod parameters) in alphabetical order, and splice the parameters and values in sequence. No splicing symbol is required to separate these parameters and values.

For example, if you specify ClientId=868575026974305, DeviceName=868575026974305, ProductKey=a1PB5fp1234, SignMethod=hmacmd5, and deviceSecret=1234 for a sub-device, the signature function is hmacmd5(1234, clientId868575026974305deviceName868575026974305productKeya1PB5fpX1234). The calculation result is C1C1606D61884C5F16C9EA6622E5****.

Note In the preceding example, ClientId indicates the client ID of the device. You can specify a custom client ID.
TopoAddItem.N.SignMethod String Yes hmacMd5

The signature method. Valid values: hmacSha1, hmacSha256, hmacMd5, and Sha256. The value is case-insensitive.

IotInstanceId String No iot_instc_pu****_c*-v64********

The instance ID. This parameter is not required for public instances. However, this parameter is required for Enterprise Edition instances.

TopoAddItem.N.Timestamp String No 1579335899000

The timestamp. The timestamp is in the UTC format. This parameter is optional. If you specify this parameter, you must use its value to calculate the signature.

TopoAddItem.N.ClientId String No a1BwAGV****device1

The ID of the device. The ID can be the serial number (SN) or MAC address of the device. This parameter is optional. If you specify this parameter, you must use its value to calculate the signature.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this API 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 returned if the call fails. For more information, see Error codes.

ErrorMessage String A system exception has 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 succeeds.

  • true: The call succeeded.
  • false: The call failed.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=BatchAddThingTopo
&GwProductKey=a1duisa****
&GwDeviceName=tydhnay16shc6
&TopoAddItem.1.ProductKey=a1rYuVF****
&TopoAddItem.1.DeviceName=SR8FiTu1R9tlUR2V1bmi
&TopoAddItem.1.Sign=dgj1609rD6IUGFCRkJKKdNKAE67h8****
&TopoAddItem.1.SignMethod=hmacMd5
&TopoAddItem.2.ProductKey=a1yrZMH****
&TopoAddItem.2.DeviceName=RkQ8CFtNpDok4BEunymt
&TopoAddItem.2.Sign=C1C1606D61884C5F16C9EA6622E5****
&TopoAddItem.2.SignMethod=hmacMd5
&<Common request parameters>

Sample success responses

XML format 

<BatchAddThingTopoResponse>
  <RequestId>2E19BDAF-0FD0-4608-9F41-82D230CFEE38</RequestId>
  <Success>true</Success>
</BatchAddThingTopoResponse>

JSON format 

{
  "RequestId": "2E19BDAF-0FD0-4608-9F41-82D230CFEE38",
  "Success": true
}

Error codes

For a list of error codes, visit the API Error Center.