V2.4 Replace Device¶
Replace the deviceKey
of a device without changing its assetId
. The system will override the original deviceKey
and deviceSecret
of the registered device, re-assign a deviceKey
, generate a new deviceSecret
, and reset the device to non-activated status. The new device can be connected to EnOSTM with the replaced deviceKey
, and the data of the old and new devices can be linked through the assetID
.
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 required device exists.
You have learnt the Limitations about devices.
Request Format¶
POST https://{apigw-address}/connect-service/v2.4/devices?action=replaceDevice
Request Parameters (URI)¶
Note
Use one of the following methods to specify the device to be replaced:
Include
assetId
in the requestInclude
productKey
+deviceKey
in the request
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>> |
assetId |
Query |
Optional (See Note above) |
String |
The asset ID. How to get assetId>> |
productKey |
Query |
Optional (See Note above) |
String |
The product key. To be used with |
deviceKey |
Query |
Optional (See Note above) |
String |
The device key. To be used with |
Request Parameters (Body)¶
Name |
Mandatory/Optional |
Data Type |
Description |
---|---|---|---|
newDeviceKey |
Mandatory |
String |
The new device key of the device. Supports English letters, numbers, hyphens (-), underline (_), and dot (.). The range is 4-64 characters. |
requireSecret |
Optional |
Boolean |
|
Response Parameters¶
Name |
Data Type |
Description |
---|---|---|
data |
DeviceReplaceResult Struct |
The returned results of the device replacement. For details, see DeviceReplaceResult Struct>> |
DeviceReplaceResult Struct ¶
Name |
Data Type |
Description |
---|---|---|
assetId |
String |
The asset ID. |
productKey |
String |
The product key. |
deviceKey |
String |
The device Key. |
deviceSecret |
String |
The device secret, returned only when the value of |
sessionKey |
String |
The key for encrypting and decrypting the value of |
Error Codes¶
Code |
Message |
Description |
---|---|---|
11702 |
DeviceKey existed |
The new device key already exists in the database. |
11704 |
DeviceKey is repetitive |
The new and old device keys are the same. |
99400 |
Invalid arguments |
One or multiple parameters are invalid. |
11858 |
Unable to find public key |
Unable to find public key for |
Samples¶
Request Sample¶
url: https://{apigw-address}/connect-service/v2.4/devices?action=replaceDevice&orgId=yourOrgId&assetId=yourAssetId
method: POST
requestBody:
{
"newDeviceKey":"yourNewDeviceKey",
"requireSecret":true
}
Return Sample¶
{
"code":0,
"msg":"OK",
"requestId":"fa377585-8240-4d1e-ad9d-a8d820873142",
"data":{
"assetId":"yourAssetId",
"productKey":"yourProductKey",
"deviceKey":"yourNewDeviceKey",
"deviceSecret":"EncryptedDeviceSecret",
"sessionKey":"EncryptedSessionKey"
}
}
SDK Samples¶
You can access the SDK samples for Connection Service on GitHub: