# 修改设备 - UpdateDevice #### 功能介绍 应用服务器可调用此接口修改物联网平台中指定设备的基本信息。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-iothub/iot_06_v5_0004.html)。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-iothub/iot_06_v5_0201.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | iotda:devices:modify | Write | app \* | - | - | - | | iotda:devices:modify | Write | - | g:EnterpriseProjectId | - | - | #### URI PUT /v5/iot/{project_id}/devices/{device_id} 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数说明** ：项目ID。获取方法请参见 [获取项目ID](https://support.huaweicloud.com/api-iothub/iot_06_v5_1001.html)。 | | device_id | 是 | String | **参数说明**：设备ID，用于唯一标识一个设备。在注册设备时直接指定，或者由物联网平台分配获得。 **取值范围**：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Instance-Id | 否 | String | **参数说明** ：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏"总览"页签查看当前实例的ID，具体获取方式请参考[查看实例详情](https://support.huaweicloud.com/usermanual-iothub/iot_01_0079.html#section1)。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | device_name | 否 | String | **参数说明**：设备名称，资源空间下唯一，用于资源空间下唯一标识一个设备。 **取值范围**：长度不超过256，只允许中文、字母、数字、以及_?'#().,\&%@!-等字符的组合，建议不少于4个字符。 | | description | 否 | String | **参数说明**：设备的描述信息。 **取值范围**：长度不超过2048，只允许中文、字母、数字、以及_?'#().,\&%@!-等字符的组合 | | extension_info | 否 | Object | **参数说明**：设备扩展信息。用户可以自定义任何想要的扩展信息，修改子设备信息时不会下发给网关。 | | auth_info | 否 | [AuthInfoWithoutSecret] object | **参数说明**：设备的接入认证信息。 | 表4AuthInfoWithoutSecret | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | secure_access | 否 | Boolean | **参数说明**：指设备是否通过安全协议方式接入。 **取值范围**： - true：通过安全协议方式接入。 - false：通过非安全协议方式接入。非安全接入的设备存在被仿冒等安全风险，请谨慎使用。 | | timeout | 否 | Integer | **参数说明**：设备接入的有效时间，单位：秒，默认值：0。若设备在有效时间内未接入物联网平台并激活，则平台会删除该设备的注册信息。若设置为"0"，则表示平台不会删除该设备的注册信息（建议填写为"0"）。 注意：该参数只对直连设备生效 | #### 响应参数 **状态码：200** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | app_id | String | 资源空间ID。 | | app_name | String | 资源空间名称。 | | device_id | String | 设备ID，用于唯一标识一个设备。在注册设备时直接指定，或者由物联网平台分配获得。由物联网平台分配时，生成规则为"product_id" + "_" + "node_id"拼接而成。 | | node_id | String | 设备标识码，通常使用IMEI、MAC地址或Serial No作为node_id。 | | gateway_id | String | 网关ID，用于标识设备所属的父设备，即父设备的设备ID。当设备是直连设备时，gateway_id与设备的device_id一致。当设备是非直连设备时，gateway_id为设备所关联的父设备的device_id。 | | device_name | String | 设备名称。 | | node_type | String | 设备节点类型。 - ENDPOINT：非直连设备。 - GATEWAY：直连设备或网关。 - UNKNOWN：未知。 | | description | String | 设备的描述信息。 | | fw_version | String | 设备的固件版本。 | | sw_version | String | 设备的软件版本。 | | device_sdk_version | String | 设备的sdk信息。 | | auth_info | [AuthInfoRes] object | 设备的接入认证信息。 | | product_id | String | 设备关联的产品ID，用于唯一标识一个产品模型。 | | product_name | String | 设备关联的产品名称。 | | status | String | 设备的状态。 - ONLINE：设备在线。 - OFFLINE：设备离线。 - ABNORMAL：设备异常。 - INACTIVE：设备未激活。 - FROZEN：设备冻结。 | | create_time | String | 在物联网平台注册设备的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 | | connection_status_update_time | String | 设备最近一次连接状态(ONLINE:在线，OFFLINE：离线，ABNORMAL：异常)变化时间。格式：yyyy-MM-dd'T'HH:mm:ss.SSS'Z' ，如2015-12-12T12:12:122Z。 | | active_time | String | 设备激活时间。格式：yyyy-MM-dd'T'HH:mm:ss.SSS'Z' ，如2015-12-12T12:12:122Z。 | | tags | Array of [TagV5DTO] objects | 设备的标签列表。 | | modules | Array of [ModuleDTO] objects | 设备的OTA模块列表。 | | extension_info | Object | 设备扩展信息。用户可以自定义任何想要的扩展信息，如果在创建设备时为子设备指定该字段，将会通过MQTT接口"平台通知网关子设备新增"将该信息通知给网关。 | 表6AuthInfoRes | 参数 | 参数类型 | 描述 | |:---|:---|:---| | auth_type | String | **参数说明**：鉴权类型。注意：不填写auth_type默认为密钥认证接入方式(SECRET)。 **取值范围**： - SECRET:使用密钥认证接入方式。 - CERTIFICATES:使用证书认证接入方式。 | | secret | String | **参数说明**：设备密钥，认证类型使用密钥认证接入(SECRET)可填写该字段。注意：NB设备密钥由于协议特殊性，只支持十六进制密钥接入；查询设备列表接口不返回该参数。 **取值范围**：长度不低于8不超过32，只允许字母、数字、下划线（_）、连接符（-）的组合。 | | secondary_secret | String | **参数说明**：设备备用密钥，认证类型使用密钥认证接入(SECRET)该字段有效，当主密钥校验不通过时，会启用辅密钥校验，辅密钥与主密钥有相同的效力；辅密钥对coap协议接入的设备不生效。注意：NB设备密钥由于协议特殊性，只支持十六进制密钥接入；查询设备列表接口不返回该参数。 **取值范围**：长度不低于8不超过32，只允许字母、数字、下划线（_）、连接符（-）的组合。 | | fingerprint | String | **参数说明**：证书指纹，认证类型使用证书认证接入(CERTIFICATES)该字段有效，注册设备时不填写该字段则取第一次设备接入时的证书指纹。 **取值范围**：长度为40的十六进制字符串或者长度为64的十六进制字符串。 | | secondary_fingerprint | String | **参数说明**：证书备用指纹，认证类型使用证书认证接入(CERTIFICATES)该字段有效，当主指纹校验不通过时，会启用辅指纹校验，辅指纹与主指纹有相同的效力。 **取值范围**：长度为40的十六进制字符串或者长度为64的十六进制字符串。 | | secure_access | Boolean | **参数说明**：指设备是否通过安全协议方式接入。 **取值范围**： - true：通过安全协议方式接入。 - false：通过非安全协议方式接入。非安全接入的设备存在被仿冒等安全风险，请谨慎使用。 | | timeout | Integer | **参数说明**：设备接入的有效时间，单位：秒，默认值：0 若设备在有效时间内未接入物联网平台并激活，则平台会删除该设备的注册信息。若设置为"0"，则表示平台不会删除该设备的注册信息（建议填写为"0"）。 注意：该参数只对直连设备生效。 | 表7TagV5DTO | 参数 | 参数类型 | 描述 | |:---|:---|:---| | tag_key | String | **参数说明**：标签键，在同一资源下标签键唯一。绑定资源时，如果设置的键已存在，则将覆盖之前的标签值。如果设置的键值不存在，则新增标签。 **取值范围**：长度不超过64，只允许中文、字母、数字、以及_.-等字符的组合。 | | tag_value | String | **参数说明**：标签值。 **取值范围**：长度不超过128，只允许中文、字母、数字、以及_.-等字符的组合。 | 表8ModuleDTO | 参数 | 参数类型 | 描述 | |:---|:---|:---| | module_name | String | 模块名称。 | | module_version | String | 模块版本号。 | #### 请求示例 修改设备，修改设备的名为device，接入类型为安全接入。 ``` PUT https://{endpoint}/v5/iot/{project_id}/devices/{device_id} { "device_name" : "device", "description" : "watermeter device", "extension_info" : { "aaa" : "xxx", "bbb" : 0 }, "auth_info" : { "secure_access" : true } } ``` #### 响应示例 **状态码：200** OK ``` { "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka", "app_name" : "testAPP01", "device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "node_id" : "ABC123456789", "gateway_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "device_name" : "dianadevice", "node_type" : "ENDPOINT", "description" : "watermeter device", "fw_version" : "1.1.0", "sw_version" : "1.1.0", "auth_info" : { "auth_type" : "SECRET", "secret" : "3b935a250c50dc2c6d481d048cefdc3c", "fingerprint" : "dc0f1016f495157344ac5f1296335cff725ef22f", "secure_access" : true, "timeout" : 0 }, "product_id" : "b640f4c203b7910fc3cbd446ed437cbd", "product_name" : "Thermometer", "status" : "ONLINE", "create_time" : "20190303T081011Z", "connection_status_update_time" : "2019-03-03T08:10:111.122Z", "active_time" : "2019-03-03T08:10:111.122Z", "tags" : [ { "tag_key" : "testTagName", "tag_value" : "testTagValue" } ], "extension_info" : { "aaa" : "xxx", "bbb" : 0 }, "modules" : [ { "module_name" : "testModuleName" }, { "module_version" : "v1.0" } ] } ``` #### SDK代码示例 SDK代码示例如下。 - [Java] 修改设备，修改设备的名为device，接入类型为安全接入。 ``` package com.huaweicloud.sdk.test; import com.huaweicloud.sdk.core.auth.ICredential; import com.huaweicloud.sdk.core.auth.AbstractCredentials; import com.huaweicloud.sdk.core.auth.BasicCredentials; import com.huaweicloud.sdk.core.exception.ConnectionException; import com.huaweicloud.sdk.core.exception.RequestTimeoutException; import com.huaweicloud.sdk.core.exception.ServiceResponseException; import com.huaweicloud.sdk.core.region.Region; import com.huaweicloud.sdk.iotda.v5.*; import com.huaweicloud.sdk.iotda.v5.model.*; public class UpdateDeviceSolution { public static void main(String[] args) { // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment String ak = System.getenv("CLOUD_SDK_AK"); String sk = System.getenv("CLOUD_SDK_SK"); // ENDPOINT：请在控制台的"总览"界面的"平台接入地址"中查看“应用侧”的https接入地址。 String iotdaEndpoint = ""; String projectId = "{project_id}"; ICredential auth = new BasicCredentials() .withProjectId(projectId) // 标准版/企业版需要使用衍生算法，基础版请删除配置"withDerivedPredicate"; .withDerivedPredicate(AbstractCredentials.DEFAULT_DERIVED_PREDICATE) // Used in derivative ak/sk authentication scenarios .withAk(ak) .withSk(sk); IoTDAClient client = IoTDAClient.newBuilder() .withCredential(auth) // 标准版/企业版：需自行创建Region对象，基础版：请使用IoTDARegion的region对象，如"withRegion(IoTDARegion.CN_NORTH_4)" .withRegion(new Region("cn-north-4", iotdaEndpoint)) .build(); UpdateDeviceRequest request = new UpdateDeviceRequest(); request.withDeviceId("{device_id}"); UpdateDevice body = new UpdateDevice(); AuthInfoWithoutSecret authInfobody = new AuthInfoWithoutSecret(); authInfobody.withSecureAccess(true); body.withAuthInfo(authInfobody); body.withExtensionInfo("{\"aaa\":\"xxx\",\"bbb\":0}"); body.withDescription("watermeter device"); body.withDeviceName("device"); request.withBody(body); try { UpdateDeviceResponse response = client.updateDevice(request); System.out.println(response.toString()); } catch (ConnectionException e) { e.printStackTrace(); } catch (RequestTimeoutException e) { e.printStackTrace(); } catch (ServiceResponseException e) { e.printStackTrace(); System.out.println(e.getHttpStatusCode()); System.out.println(e.getRequestId()); System.out.println(e.getErrorCode()); System.out.println(e.getErrorMsg()); } } } ``` - [Python] 修改设备，修改设备的名为device，接入类型为安全接入。 ``` # coding: utf-8 import os from huaweicloudsdkcore.auth.credentials import BasicCredentials from huaweicloudsdkcore.auth.credentials import DerivedCredentials from huaweicloudsdkcore.region.region import Region as coreRegion from huaweicloudsdkcore.exceptions import exceptions from huaweicloudsdkiotda.v5 import * if __name__ == "__main__": # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment ak = os.environ["CLOUD_SDK_AK"] sk = os.environ["CLOUD_SDK_SK"] # ENDPOINT：请在控制台的"总览"界面的"平台接入地址"中查看“应用侧”的https接入地址，下面创建Client时需要使用自行创建的Region对象，基础版：请选择IoTDAClient中的Region对象 如： IoTDAClient.new_builder().with_region(IoTDARegion.CN_NORTH_4) endpoint = ""; projectId = "{project_id}" credentials = BasicCredentials(ak, sk, projectId).with_derived_predicate(DerivedCredentials.get_default_derived_predicate()) client = IoTDAClient.new_builder() \ .with_credentials(credentials) \ .with_region(coreRegion(id="cn-north-4", endpoint=endpoint)) \ .build() try: request = UpdateDeviceRequest() request.device_id = "{device_id}" authInfobody = AuthInfoWithoutSecret( secure_access=True ) request.body = UpdateDevice( auth_info=authInfobody, extension_info="{\"aaa\":\"xxx\",\"bbb\":0}", description="watermeter device", device_name="device" ) response = client.update_device(request) print(response) except exceptions.ClientRequestException as e: print(e.status_code) print(e.request_id) print(e.error_code) print(e.error_msg) ``` - [Go] 修改设备，修改设备的名为device，接入类型为安全接入。 ``` package main import ( "fmt" "github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic" iotda "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/iotda/v5" "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/iotda/v5/model" region "github.com/huaweicloud/huaweicloud-sdk-go-v3/core/region" core_auth "github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth" ) func main() { // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment ak := os.Getenv("CLOUD_SDK_AK") sk := os.Getenv("CLOUD_SDK_SK") // endpoint：请在控制台的"总览"界面的"平台接入地址"中查看"应用侧"的https接入地址 endpoint := "" projectId := "{project_id}" auth, err := basic.NewCredentialsBuilder(). WithAk(ak). WithSk(sk). WithProjectId(projectId). // 企业版/标准版需要使用衍生算法，基础版请删除该配置"WithDerivedPredicate" WithDerivedPredicate(core_auth.GetDefaultDerivedPredicate()). // Used in derivative ak/sk authentication scenarios SafeBuild() if err != nil { fmt.Println(err) return } hcClient, err := iotda.IoTDAClientBuilder(). // 标准版/企业版需要自行创建region，基础版使用IoTDARegion中的region对象 WithRegion(region.NewRegion("cn-north-4", endpoint)). WithCredential(auth). SafeBuild() if err != nil { fmt.Println(err) return } client := iotda.NewIoTDAClient(hcClient) request := &model.UpdateDeviceRequest{} request.DeviceId = "{device_id}" secureAccessAuthInfo:= true authInfobody := &model.AuthInfoWithoutSecret{ SecureAccess: &secureAccessAuthInfo, } var extensionInfoUpdateDevice interface{} = "{\"aaa\":\"xxx\",\"bbb\":0}" descriptionUpdateDevice:= "watermeter device" deviceNameUpdateDevice:= "device" request.Body = &model.UpdateDevice{ AuthInfo: authInfobody, ExtensionInfo: &extensionInfoUpdateDevice, Description: &descriptionUpdateDevice, DeviceName: &deviceNameUpdateDevice, } response, err := client.UpdateDevice(request) if err == nil { fmt.Printf("%+v\n", response) } else { fmt.Println(err) } } ``` - [更多] 更多编程语言的SDK代码示例，请参见[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/IoTDA/sdk?api=UpdateDevice)的代码示例页签，可生成自动对应的SDK代码示例。 #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 500 | Internal Server Error | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-iothub/ErrorCode.html)。