V2.4 Create Device¶

Create a device.

This API is only available if 2.4 Cumulative Update 1 has been applied to your environment.

Operation Permissions¶

Before invoking this API, ensure that the service account has been authorized the policy that includes the following service(s) and action permission(s). For how to authorize the service account, see Managing Service Accounts.

Required Service	Required Operation Permission
Device Management Service	Full Access

Prerequisite¶

The product to create this device under exists.
You have learnt the Limitations about devices.

Prerequisite¶

Ensure the product to create this device under exists.

Request Format¶

POST https://{apigw-address}/connect-service/v2.4/devices?action=create

Request Parameters (URI)¶

Name	Location (Path/Query)	Mandatory/Optional	Data Type	Description
orgId	Query	Mandatory	String	The organization ID which the asset belongs to. How to get orgId>>

Request Parameters (Body)¶

Name	Mandatory/Optional	Data Type	Description
productKey	Mandatory	String	The product key.
deviceName	Mandatory	StringI18n	The device name. For more details on the structure and locales supported, see Internationalized name struct.
timezone	Mandatory	String	Timezone of the device’s location. For details, see Timezone representation.
requireSecret	Optional	Boolean	`true`: `deviceSecret` and `sessionKey` will be returned. Ensure that the RSA key pair has been created for the service account. Creating RSA Key Pairs >> `false` (default): `deviceSecret` and `sessionKey` will not be returned.
deviceAttributes	Optional	Map	The device attributes.
deviceKey	Optional	String	The device key.
deviceDesc	Optional	String	The device description.
deviceTags	Optional	Map	The device tags. (The Key and Value are of String type.) For details, see How to use tags.

Response Parameters¶

Name	Data Type	Description
data	DeviceCreateResult Struct	The returned results of the device creation. For details, see DeviceCreateResult Struct.

DeviceCreateResult Struct ¶

Name	Data Type	Description
productKey	String	The product key.
deviceKey	String	The device key.
deviceSecret	String	The device secret, returned only when the value of `requireSecret` is `true`. The returned value will be encrypted. How to Decrypt >>
sessionKey	String	The key for encrypting and decrypting the value of `deviceSecret`, returned only when the value of `requireSecret` is `true`. The returned value will be encrypted. How to Decrypt >>
assetId	String	The asset ID.

Error Codes¶

Code	Message	Description
11702	DeviceKey existed	The `deviceKey` already exists in the database (when `deviceKey` is provided).
11714	Generate deviceKey failed	The key of the device cannot be assigned temporarily (when the `deviceKey` is not provided). Please try again.
11739	Exceed max device size	A product can have a max of 10,000 devices under it. This operation will exceed the limit.
11858	Unable to find public key	Unable to find public key for `requireSecret` due to there is no RSA key pair for the service account. Creating RSA Key Pairs >>.
99400	Invalid arguments	One or multiple parameters are invalid.

Samples¶

Request Sample¶

url: https://{apigw-address}/connect-service/v2.4/devices?action=create&orgId=yourOrgId
method: POST
requestBody:
{
    "productKey":"yourProductKey",
    "deviceName":{
        "defaultValue":"Device Name",
        "i18nValue":{
      "zh_CN": "设备名称",
      "en_US": "Device Name"
        }
    },
    "timezone":"+08:00",
    "deviceAttributes":{
        "serial":111111
    },
    "deviceDesc":"Device description",
    "deviceTags":{
        "tag1":"tag value"
    },
    "requireSecret": true
}

Return Sample¶

{
    "code":0,
    "msg":"OK",
    "requestId":"fd79d0f5-69c5-4fa8-add4-69f5ca1b635f",
    "data":{
        "assetId":"Uvmm5AXU",
        "productKey":"yourProductKey",
        "deviceKey":"yourDeviceKey",
        "deviceSecret":"EncryptedDeviceSecret",
        "sessionKey":"EncryptedSessionKey"
    }
}

SDK Samples¶

You can access the SDK samples for Connection Service on GitHub:

Java
Python