Creates multiple custom DeviceNames under a specified product. IoT Platform checks the validity of these DeviceNames.

API usage

You can call this operation with the BatchRegisterDeviceWithApplyId operation to register multiple devices under a product. Each device carries a unique DeviceName.

Procedure:

1. Call this operation to specify the DeviceNames of the devices to be registered. IoT Platform returns an application ID (ApplyId). A successful response indicates that the request to verify the DeviceNames is submitted. The actual registration process is asynchronously implemented and takes some minutes.

2. Call the QueryBatchRegisterDeviceStatus operation to query the name setting result.

3. Call the BatchRegisterDeviceWithApplyId operation to register multiple devices.

4. Optional. Call the QueryBatchRegisterDeviceStatus operation to view the registration result.

5. Call the QueryPageByApplyId operation to query the information about the registered devices.

Limits

  • You can specify a maximum of 10,000 DeviceNames in a single call.
  • Each Alibaba Cloud account can run a maximum of 10 queries per second (QPS).
    Note RAM users of an Alibaba Cloud account share the quota of the account.

Debugging

Alibaba Cloud provides OpenAPI Explorer to simplify API usage. 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 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 devices belong.

IotInstanceId String No iot-cn-0pp1n8t****

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

Notice
  • If your instance has an ID, you must configure this parameter. If you do not set this parameter, the call fails.
  • If your instance has no Overview page or ID, you do not need to set this parameter.

For more information, see Overview.

DeviceName.N RepeatList No light

The DeviceName of the device. The DeviceName must be unique within the product. The name must be 4 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), periods (.), at signs (@), 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 DeviceNameList.N.DeviceName parameter is used by default.

Note You can specify up to 10,000 DeviceNames in a single call. If the size of a message exceeds this limit, the message is discarded.
DeviceNameList.N.DeviceName String No light1

The DeviceName of the device. The DeviceName must be unique within the product. The name must be 4 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), periods (.), at signs (@), 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, this parameter is used by default.

Note You can specify up to 10,000 DeviceNames in a single call. If the size of a message exceeds this limit, the message is 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 (_).

If this parameter is specified, 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, 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.

Data Struct

The returned data.

ApplyId Long 1295006

The application ID (ApplyId) returned if the call is successful. When you call the BatchRegisterDeviceWithApplyId operation to register the devices, this parameter is required.

InvalidDeviceNameList List { "InvalidDeviceName": [ "APT$", "aw" ] }

The list of invalid DeviceNames returned if the call fails.

InvalidDeviceNicknameList List { "InvalidDeviceNickname": [ "APT$", "aw" ] }

The list of invalid device aliases returned if the call fails.

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=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, visit the API Error Center.