All Products
Search
Document Center

IoT Platform:BatchCheckDeviceNames

Last Updated:Aug 29, 2023

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.

Note

The 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

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
  • If your instance has an ID, you must specify the ID for this parameter. If you do not specify the ID for this parameter, the call fails.

  • If the Overview page is not displayed or your instance does not have an ID, you do not need to specify this parameter.

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:

  • true

  • false

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.