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 specified sub-devices fail to establish topological relationships with the gateway.
  • After you call this operation to establish topological relationships between sub-devices 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

You can call this API operation up to 10 times per second per Alibaba Cloud account.

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.

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

To obtain the content parameter, sort all sub-device parameters that are submitted to the server, except the Sign and SignMethod parameters, in alphabetical order. Then, concatenate the parameters and values in sequence. No concatenation symbol is required to separate these parameters and values.

For example, you want to specify the following parameters for a sub-device: ClientId=868575026974305, DeviceName=868575026974305, ProductKey=a1PB5fp1234, SignMethod=hmacmd5, timestamp=1646277090411, and deviceSecret=1234. In this case, the signature function is hmacmd5(1234, clientId868575026974305deviceName868575026974305productKeya1PB5fp1234timestamp1646277090411), and the calculation result is 3BA0DFA4C477B40C007D84D30D6466CC.

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

For more information about how to calculate the signature value, see How do I obtain MQTT parameters for authentication?. The signature value is the calculated value of the passwd parameter.

TopoAddItem.N.SignMethod String Yes hmacMd5

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

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

The ID of the instance. On the Overview page in the IoT Platform console, you can view the ID of the instance.

Notice
  • If your instance has an ID, you must specify this parameter. Otherwise, the call fails.
  • If no Overview page or instance ID appears in the IoT Platform console, ignore this parameter.

For more information, see Overview.

TopoAddItem.N.Timestamp String No 1579335899000

The timestamp in UTC. This parameter is optional.

Notice If this parameter is included in the value of the TopoAddItem.N.Sign parameter, you must specify this parameter.
TopoAddItem.N.ClientId String No a1BwAGV****device1

The client ID of the sub-device. The ID can be the serial number (SN) or media access control (MAC) address of the device. This parameter is optional.

Notice If this parameter is included in the value of the TopoAddItem.N.Sign parameter, you must specify this parameter.

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 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
}