Creates multiple custom DeviceNames under a product. IoT Platform checks the validity of the DeviceNames.
Usage notes
You must use this operation together with the BatchRegisterDeviceWithApplyId operation to register multiple devices that have unique names under a product.
Procedure:
1. Call the BatchCheckDeviceNames operation to specify names for the devices that you want to register. IoT Platform returns the application ID that is indicated by the ApplyId parameter. If the call is successful, a request to verify the DeviceNames is submitted. The actual verification is performed in an asynchronous manner.
2. Call the QueryBatchRegisterDeviceStatus operation to query the name setting result.
3. Call the BatchRegisterDeviceWithApplyId operation to register the devices.
4. Optional. Call the QueryBatchRegisterDeviceStatus operation to query the device registration result.
5. Call the QueryPageByApplyId operation to view the details of devices that are registered at the same time.
Limits
You can specify up to 10,000 DeviceNames in a call.
QPS limits
You can call this API operation up to 10 times per second per account.
The RAM users of an Alibaba Cloud account share the quota of the account.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
Action | String | Yes | BatchCheckDeviceNames | The operation that you want to perform. Set the value to BatchCheckDeviceNames. |
ProductKey | String | Yes | a1BwAGV**** | The ProductKey of the product to which the device belongs. |
IotInstanceId | String | No | iot-cn-0pp1n8t**** | The ID of the IoT instance. You can view the ID of the instance on the Overview page in the IoT Platform console. Important
For more information, see the Overview topic of IoT instances. |
DeviceName.N | RepeatList | No | light | The name of the device. The DeviceName must be unique within the product. The DeviceName must be 4 to 32 characters in length and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:). You must specify this parameter or the DeviceNameList.N.DeviceName parameter. If you specify this parameter and the DeviceNameList.N.DeviceName parameter at the same time, the value of the DeviceNameList.N.DeviceName parameter takes precedence. Note You can specify up to 10,000 DeviceNames in a call. If the number of DeviceNames exceed the limit, the excess DeviceNames are discarded. |
DeviceNameList.N.DeviceName | String | No | light1 | The name of the device. The DeviceName must be unique within the product. The DeviceName must be 4 to 32 characters in length and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:). You must specify this parameter or the DeviceName.N parameter. If you specify this parameter and the DeviceName.N parameter at the same time, the value of this parameter takes precedence. Note You can specify up to 10,000 DeviceNames in a call. If the number of DeviceNames exceed the limit, the excess DeviceNames are discarded. |
DeviceNameList.N.DeviceNickname | String | No | Smart light 1 | The alias of the device. The alias must be 4 to 64 characters in length and can contain letters, digits, and underscores (_). Important If you specify this parameter, you must specify the DeviceNameList.N.DeviceName parameter. |
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 failed. For more information, see Error codes. |
Data | Struct | The data that is returned if the call was successful. | |
ApplyId | Long | 1295006 | The application ID (ApplyId) that is returned if the call was successful. When you call the BatchRegisterDeviceWithApplyId operation to register devices, you must specify the ApplyId parameter. |
InvalidDetailList | Array of InvalidDetailList | The details of invalid DeviceNames of devices that failed to be registered. | |
InvalidDetailList | |||
DeviceName | String | light | The DeviceName. |
ErrorMsg | String | The device name is illegal. | The error messages that are returned when the devices failed to be registered. Note Multiple error messages are separated by vertical bars (|). |
NickName | String | Smart Light 1 | The alias of the device. |
InvalidDeviceNameList | List | { "InvalidDeviceName": [ "APT$", "aw" ] } | The invalid DeviceNames that failed to be registered. |
InvalidDeviceNicknameList | List | { "InvalidDeviceNickname": [ "APT$", "aw" ] } | The invalid device aliases that failed to be registered. |
RepeatedDeviceNameList | List | { "RepeatedDeviceName": [ "APT$", "aw" ] } | The duplicate DeviceNames that failed to be registered. |
ErrorMessage | String | A system exception occurred. | The error message returned if the call fails. |
RequestId | String | E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565 | The request ID. |
Success | Boolean | true | Indicates whether the request was successful. Valid values:
|
Examples
Sample requests
https://iot.cn-shanghai.aliyuncs.com/?Action=BatchCheckDeviceNames
&productKey=a1BwAGV****
&DeviceNameList.1.DeviceName=light1
&DeviceNameList.2.DeviceName=light2
&DeviceNameList.3.DeviceName=light3
&DeviceNameList.3.DeviceNickname=Smart light 3
&<Common request parameters>Sample success responses
XML format
<BatchCheckDeviceNamesResponse>
<Data>
<ApplyId>1234567</ApplyId>
</Data>
<RequestId>E976E36B-6874-4FA4-8BC0-55F9BEC5E2EF</RequestId>
<Success>true</Success>
</BatchCheckDeviceNamesResponse>JSON format
{
"Data": {
"ApplyId": 1234567
},
"RequestId": "E976E36B-6874-4FA4-8BC0-55F9BEC5E2EF",
"Success": true
}Error codes
For a list of error codes, see Service error codes.