Establishes multiple topological relationships at a time.

Usage notes

  • You can attach up to 10 sub-devices to a gateway in a single call.
  • The API operation caller must be the gateway owner.
  • If you specify a sub-device that is already attached to a gateway, the original gateway is replaced with the specified gateway.
  • If one of the specified sub-devices fails to establish a topological relationship with the gateway, the system rolls back and all sub-devices fail to establish topological relationships with the gateway.
  • After you call this operation to establish a topological relationship between a sub-device and the gateway, IoT Platform uses the /sys/${productKey}/${deviceName}/thing/topo/change topic to push information that includes the result of this operation to the gateway. For more information, see Notify gateways of changes of topological relationships.

QPS limits

Each Alibaba Cloud account can run up to 10 queries per second (QPS).

Note The RAM users of an Alibaba Cloud account share the quota of the Alibaba Cloud 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 DeviceName of the gateway device.

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.

Set the Sign parameter to the result of the SignMethod(deviceSecret,content) function.

To obtain the content parameter, sort all sub-device parameters 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, timestamp=1646277090411, and deviceSecret=1234 for a sub-device, the signature function is hmacmd5(1234, clientId868575026974305deviceName868575026974305productKeya1PB5fpX1234timestamp1646277090411). The calculation result is 3BA0DFA4C477B40C007D84D30D6466CC.

Note In the preceding example, ClientId specifies the client ID of the device. You can specify a custom client ID.

For more information about how to obtain the signature parameters, see How do I obtain signature parameters for authentication?

TopoAddItem.N.SignMethod String Yes hmacMd5

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

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

The ID of the instance. You can view the ID of the instance on the Instance Overview page in the IoT Platform console.

Notice
  • If your instance has an ID, you must specify the ID for this parameter. Otherwise, the call fails.
  • If no Instance Overview page or ID is generated for your instance, you do not need to configure this parameter.

For more information, see Overview.

TopoAddItem.N.Timestamp String No 1579335899000

The timestamp in the UTC format. This parameter is optional. If you specify a value for this parameter, you must use the 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 a value for this parameter, you must use the value to calculate the signature.

In addition to the preceding operation-specific request parameters, you must configure 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.

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

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
}