V2.4 Replace Device¶
在资产 ID(assetId
)不改变的情况下更换一个设备。该接口将注销已注册设备的原始 Device Key 及 Device Secret,为其重新分配 Device Key,生成新的 Device Secret,并重置设备为未激活状态。新设备可以通过更换后的 Device Key 连接 EnOS,新旧设备的数据将通过资产ID进行关联。
使用此 API 前,确保已安装 EnOS 2.4 CU1 或更新版本。
操作权限¶
确保已获取调用该 API 的权限。更多信息,参见 获取 API 调用权限。
前提条件¶
确保已创建所需设备。
确保已阅读设备相关的 使用限制。
请求格式¶
POST https://{apigw-address}/connect-service/v2.4/devices?action=replaceDevice
请求参数(URI)¶
备注
以下非必需字段中,必须提供 assetId
或 productKey
+ deviceKey
的组合,用于指定设备。
名称 |
位置(Path/Query) |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|---|
orgId |
Query |
必需 |
String |
资产所属的组织 ID。如何获取 orgId 信息>> |
assetId |
Query |
可选(见上述注解) |
String |
资产 ID。如何获取 assetId 信息>> |
productKey |
Query |
可选(见上述注解) |
String |
设备的 product key,需与 |
deviceKey |
Query |
可选(见上述注解) |
String |
设备的 device key,需与 |
请求参数(Body)¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
newDeviceKey |
必需 |
String |
新设备的 device key。支持英文字母、数字、连字符(-)、下划线(_)及圆点(.),长度限制 4~64 个字符。 |
requireSecret |
可选 |
Boolean |
|
响应参数¶
名称 |
数据类型 |
描述 |
---|---|---|
data |
DeviceReplaceResult 结构体 |
设备替换结果信息,参见 DeviceReplaceResult 结构体。 |
DeviceReplaceResult 结构体 ¶
名称 |
数据类型 |
描述 |
---|---|---|
assetId |
String |
资产 ID。 |
productKey |
String |
设备的 Product Key. |
deviceKey |
String |
设备的 Device Key. |
deviceSecret |
String |
设备连接密钥,仅当 |
sessionKey |
String |
配合解密 deviceSecret 的参数,仅当 |
错误码¶
代码 |
错误信息 |
描述 |
---|---|---|
11702 |
DeviceKey existed |
新的 Device Key 在数据库中已存在。 |
11704 |
DeviceKey is repetitive |
新旧 Device Key 相同。 |
99400 |
Invalid arguments |
参数错误。 |
11858 |
Unable to find public key |
由于应用的服务帐号未创建 RSA 密钥对,无法获取 RSA 公钥,因此无法请求 |
示例¶
请求示例¶
POST https://{apigw-address}/connect-service/v2.4/devices?action=replaceDevice&orgId=yourOrgId&assetId=yourAssetId
{
"newDeviceKey":"yourNewDeviceKey",
"requireSecret":true
}
返回示例¶
{
"code":0,
"msg":"OK",
"requestId":"fa377585-8240-4d1e-ad9d-a8d820873142",
"data":{
"assetId":"yourAssetId",
"productKey":"yourProductKey",
"deviceKey":"yourNewDeviceKey",
"deviceSecret":"EncryptedDeviceSecret",
"sessionKey":"EncryptedSessionKey"
}
}
SDK 示例¶
你可以在 Github 上获取接入服务的 SDK 示例: