V2.1 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 available in EnOS 2.1.0 and above. Version 2.4 has been added and it is recommended to use V2.4 Replace Device.
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¶
You have learnt the Limitations about devices.
Request Format¶
POST https://{apigw-address}/connect-service/v2.1/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. |
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 new device secret assigned by the system. |
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. |
Samples¶
Request Sample¶
url: https://{apigw-address}/connect-service/v2.1/devices?action=replaceDevice&orgId=yourOrgId&assetId=yourAssetId
method: POST
requestBody:
{
"newDeviceKey":"yourNewDeviceKey"
}
Return Sample¶
{
"code":0,
"msg":"OK",
"requestId":"fa377585-8240-4d1e-ad9d-a8d820873142",
"data":{
"assetId":"yourAssetId",
"productKey":"yourProductKey",
"deviceKey":"yourNewDeviceKey",
"deviceSecret":"yourDeviceSecret"
}
}
SDK Samples¶
You can access the SDK samples for Connection Service on GitHub: