Registers a device in a product.

Description

If you call the operation to register a device in a product, the device is added to the product in the IoT Platform console. After a device is registered in a product, Alibaba Cloud IoT Platform issues a globally unique identifier (GUID) for the device. The device ID is included in the IotId parameter. When you perform device-specific operations, you can provide a device ID. You can also provide a combination of the ProductKey and DeviceName parameters to identify a device. A product key is issued by IoT Platform to a product when you create the product. A device name is specified or randomly generated when you create a device. The IotId parameter has a higher precedence than a combination of the ProductKey and DeviceName parameters.

  • If you need to register multiple devices in a product at a time and generate random device names, you can call the BatchRegisterDevice operation.
  • If you need to register multiple devices in a product at a time and specify names for each device, you can call the BatchCheckDeviceNames operation. If the call succeeds, the operation returns an application ID (ApplyId). Then, you can call the BatchRegisterDeviceWithApplyId operation to register multiple devices.

Limits

Each Alibaba Cloud account can run a maximum of 30 queries per second (QPS).

Note Resource Access Management (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 RegisterDevice

The operation that you want to perform. Set the value to RegisterDevice.

ProductKey String Yes a1BwAGV****

The key of the product to which the device belongs. A product key is issued by IoT Platform to a product. The product key is the GUID for the product.

You can use the IoT Platform console or call the QueryProductList operation to view the information of all products in the current account.

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

The instance ID. This parameter is not required for public instances. However, the parameter is required for the instances that you have purchased.

DeviceName String No light

The name of the device. The name must be 4 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:).

You can use a combination of the DeviceName and ProductKey parameters to identify a device.

Note If you do not specify this parameter, the system randomly generates a device name.
DevEui String No e8SDdgeIlk3nED****

The DevEUI of a LoRaWAN device.

This parameter is required when you create a LoRaWAN device.

PinCode String No DIe80dfeg*****

The PIN code of the LoRaWAN device. This parameter is used to verify the validity of the DevEUI.

This parameter is required when you create a LoRaWAN device.

Nickname String No Campus light

The alias of the device. The alias must be 4 to 64 characters in length, and can contain letters, digits, and underscores (_).

Note If you do not specify this parameter, the system does not generate an alias for the device.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this API 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 device information returned if the call succeeds.

DevEui String e8SDdgeIlk3nED****

The DevEUI of the LoRaWAN device. This parameter is returned only when you create a LoRaWAN device.

DeviceName String light

The name of the device.

Note Keep the information confidential.
DeviceSecret String mz2Canp4GB7qRVf1OYPNtRqB2anu****

The secret of the device.

Note Keep the information confidential.
IotId String 1O4YPNtRqB2anumz2Canp4GB7q****

The ID of the device. The ID is the unique identifier that is issued by IoT Platform to the device.

Note Keep the information confidential.
JoinEui String Ede4tde8erth****

The JoinEUI of the LoRaWAN device. This parameter is returned only when you create a LoRaWAN device.

Nickname String Campus light

The alias of the device.

If you do not specify an alias for the device, this parameter is empty.

ProductKey String a1BwAGV****

The key of the product to which the device belongs.

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

  • true: The call succeeded.
  • false: The call failed.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=RegisterDevice
&ProductKey=a1rYuVF****
&DeviceName=device1
&Nickname=detectors_in_beijing
&<Common request parameters>

Sample success responses

XML format

<RegisterDeviceResponse>
  <RequestId>57b144cf-09fc-4916-a272-a62902d5b207</RequestId>
  <Success>true</Success>
  <Data>
        <DeviceName>device1</DeviceName>
        <ProductKey>a1rYuVF****</ProductKey>
        <DeviceSecret>tXHf4ezGEHcwdyMwoCDHGBmk9avi****</DeviceSecret>
        <IotId>CqXL5h5ysRTA4NxjABjj0010fa****</IotId>
        <Nickname>detectors_in_beijing</Nickname>
  </Data>
</RegisterDeviceResponse>

JSON format

{
    "RequestId": "57b144cf-09fc-4916-a272-a62902d5b207", 
    "Success": true, 
    "Data": {
        "DeviceName": "device1", 
        "ProductKey": "a1rYuVF****", 
        "DeviceSecret": "tXHf4ezGEHcwdyMwoCDHGBmk9avi****", 
        "IotId": "CqXL5h5ysRTA4NxjABjj0010fa****", 
        "Nickname": "detectors_in_beijing"
    }
}

Error codes

For a list of error codes, visit the API Error Center.