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