文档首页/ 设备发放 IoTDP/ API参考/ API/ 设备管理/ 注册设备
更新时间：2024-07-01 GMT+08:00
查看PDF
分享

注册设备

功能介绍

应用服务器可调用此接口在物联网平台注册一个设备，仅在注册后设备才可以接入物联网平台。

URI

POST /v5/iotps/{project_id}/devices

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

项目ID。

最小长度：1

最大长度：32

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

用户Token。

通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。
表3 请求Body参数

参数

是否必选

参数类型

描述

device_id

否

String

设备ID，用于唯一标识一个设备。如果携带该参数，平台将设备ID设置为该参数值；如果不携带该参数，设备ID由物联网平台分配获得，生成规则为"product_id" + "_" + "node_id"拼接而成。

node_id

是

String

设备标识码，通常使用IMEI、MAC地址或Serial No作为node_id。（注意:NB设备由于模组烧录信息后无法配置，所以NB设备会校验node_id全局唯一。）

device_name

否

String

设备名称。

最小长度：1

最大长度：256

product_id

是

String

设备关联的产品ID，用于唯一标识一个产品模型，在管理门户导入产品模型后由平台分配获得。

access_point_id

是

String

产品关联的接入点ID。

最小长度：1

最大长度：64

region_id

是

String

接入点所属区域ID。

最小长度：1

最大长度：64

auth_info

否

AuthInfo object

设备的接入认证信息。

description

否

String

设备的描述信息。

最大长度：2048

gateway_id

否

String

网关ID，用于标识一个网关设备。当设备是直连设备时，gatewayId与设备的deviceId一致。当设备是非直连设备时，gatewayId为设备所关联的直连设备（即网关）的deviceId。

provision_info

否

ProvisionInfoReq object

设备的发放信息。
表4 AuthInfo

参数

是否必选

参数类型

描述

auth_type

否

String

鉴权类型。支持秘钥认证接入(SECRET)和证书认证接入(CERTIFICATES)。使用秘钥认证接入方式(SECRET)填写secret字段，使用证书认证接入方式(CERTIFICATE)填写fingerprint字段，如果CA证书选择云证书管理服务的CA证书，不需要填写fingerprint字段，需要填写设备证书名称字段，不填写auth_type默认为秘钥认证接入方式(SECRET)

secret

否

String

设备秘钥，认证类型使用秘钥认证接入(SECRET)可填写该字段。注意：NB设备秘钥由于协议特殊性，只支持十六进制秘钥接入。

最小长度：8

最大长度：32

fingerprint

否

String

证书指纹，认证类型使用证书认证接入(CERTIFICATES)可填写该字段，注册设备时不填写该字段则取第一次设备接入时的证书指纹。注意：指纹只能为40位十六进制字符串或者64位十六进制字符串。

device_cert_name

否

String

设备证书名称，CA证书选择云证书管理服务的CA证书接入需要填写该字段。此名称会也即设备证书使用者的CommanName

device_cert_validity

否

Integer

生成设备证书的有效期。CA证书选择云证书管理服务的CA证书可填写该字段。

最小值：1

最大值：10

device_cert_id

否

String

设备证书id，设备采用云证书管理服务的CA注册，云证书管理服务生成的设备证书的唯一实例ID

secure_access

否

Boolean

指设备是否通过安全协议方式接入，默认值为true。

  • true：通过安全协议方式接入。

  • false：通过非安全协议方式接入。

缺省值：true

timeout

否

Integer

设备验证码的有效时间，单位：秒，默认值：0 若设备在有效时间内未接入物联网平台并激活，则平台会删除该设备的注册信息。若设置为“0”，则表示设备验证码不会失效（建议填写为“0”）。

缺省值：0
表5 ProvisionInfoReq

参数

是否必选

参数类型

描述

allocation_strategy_type

否

String

策略类型。

取值如下：

  • base：静态策略；

  • certificates：证书策略；

  • functions：自定义策略；

  • nearby：就近策略。

缺省值：base

certificate_id

否

String

证书ID。证书模式必填该字段，如果CA证书是用户自定义并在设备发放服务上传的，填写设备发放服务生成的证书ID。如果CA证书是在云证书管理服务生成的，证书ID为云证书管理服务生成的证书ID。

最小长度：0

最大长度：256

func_urn

否

String

函数的URN（Uniform Resource Name），唯一标识函数。自定义策略下必填该字段。

最小长度：1

最大长度：360

bs_secret

否

String

引导服务端PSK。

最小长度：8

最大长度：32

life_time

否

Integer

LWM2M设备导入的默认生命周期。

取值范围：0-604800。

最小值：0

最大值：604800

init_config

否

String

设备的初始化配置。必须为json字符串

最小长度：1

最大长度：65535

响应参数

状态码： 200

表6 响应Body参数

参数

参数类型

描述

device_id

String

设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。（生成规则为"product_id" + "_" + "node_id"拼接而成）

最小长度：0

最大长度：256

node_id

String

设备标识码，通常使用IMEI、MAC地址或Serial No作为nodeId。

最小长度：0

最大长度：64

gateway_id

String

网关ID，用于标识一个网关设备。当设备是直连设备时，gatewayId与设备的deviceId一致。当设备是非直连设备时，gatewayId为设备所关联的直连设备（即网关）的deviceId。

最小长度：0

最大长度：256

device_name

String

设备名称。

最小长度：0

最大长度：256

node_type

String

设备节点类型。

  • ENDPOINT：非直连设备。

  • GATEWAY：直连设备或网关。

  • UNKNOWN：未知。

description

String

设备的描述信息。

最小长度：0

最大长度：2048

auth_info

AuthInfo object

设备的接入认证信息。

product_id

String

设备关联的产品ID，用于唯一标识一个产品模型。

product_name

String

设备关联的产品名称。

最小长度：1

最大长度：255

protocol_type

String

设备关联的产品协议类型。

create_time

String

在物联网平台注册设备的时间。

最小长度：0

最大长度：128

provision_info

ProvisionInfoBaseResp object

设备的发放信息。
表7 AuthInfo

参数

参数类型

描述

auth_type

String

鉴权类型。支持秘钥认证接入(SECRET)和证书认证接入(CERTIFICATES)。使用秘钥认证接入方式(SECRET)填写secret字段，使用证书认证接入方式(CERTIFICATE)填写fingerprint字段，如果CA证书选择云证书管理服务的CA证书，不需要填写fingerprint字段，需要填写设备证书名称字段，不填写auth_type默认为秘钥认证接入方式(SECRET)

secret

String

设备秘钥，认证类型使用秘钥认证接入(SECRET)可填写该字段。注意：NB设备秘钥由于协议特殊性，只支持十六进制秘钥接入。

最小长度：8

最大长度：32

fingerprint

String

证书指纹，认证类型使用证书认证接入(CERTIFICATES)可填写该字段，注册设备时不填写该字段则取第一次设备接入时的证书指纹。注意：指纹只能为40位十六进制字符串或者64位十六进制字符串。

device_cert_name

String

设备证书名称，CA证书选择云证书管理服务的CA证书接入需要填写该字段。此名称会也即设备证书使用者的CommanName

device_cert_validity

Integer

生成设备证书的有效期。CA证书选择云证书管理服务的CA证书可填写该字段。

最小值：1

最大值：10

device_cert_id

String

设备证书id，设备采用云证书管理服务的CA注册，云证书管理服务生成的设备证书的唯一实例ID

secure_access

Boolean

指设备是否通过安全协议方式接入，默认值为true。

  • true：通过安全协议方式接入。

  • false：通过非安全协议方式接入。

缺省值：true

timeout

Integer

设备验证码的有效时间，单位：秒，默认值：0 若设备在有效时间内未接入物联网平台并激活，则平台会删除该设备的注册信息。若设置为“0”，则表示设备验证码不会失效（建议填写为“0”）。

缺省值：0
表8 ProvisionInfoBaseResp

参数

参数类型

描述

access_point

AccessPointResp object

发放区域。

app_info

ApplicationResp object

所属应用。

cert_name

String

CA证书名称。设备认证类型为证书认证时返回。

最小长度：0

最大长度：256

allocation_status

Integer

设备发放状态。

取值如下：

  • 0：成功；

  • 1：失败；

  • 2：发放中；

  • 3：未发放（默认）。

最小值：0

最大值：3

allocation_strategy_type

String

策略类型。

取值如下：

  • base：静态策略；

  • certificates：证书策略；

  • functions：自定义策略；

  • nearby：就近策略；

  • migrations: 指定迁移策略。

缺省值：base

life_time

Integer

LWM2M设备导入的默认生命周期。

最小值：0

最大值：864000

init_config

String

设备的初始化配置。

最小长度：1

最大长度：65535
表9 AccessPointResp

参数

参数类型

描述

access_point_id

String

接入点id。

最小长度：1

最大长度：256

access_point_name

String

接入点名称。

最小长度：1

最大长度：256

region_id

String

华为云终端节点ID。节选自https://developer.huaweicloud.com/endpoint。

最小长度：1

最大长度：128
表10 ApplicationResp

参数

参数类型

描述

app_id

String

应用id。

最小长度：1

最大长度：64

app_name

String

应用名称。

最小长度：1

最大长度：256

请求示例

  • 创建设备(静态策略)请求示例

    POST https://{endpoint}/v5/iotps/{project_id}/devices

{
  "device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f",
  "node_id" : "ABC123456789",
  "device_name" : "dianadevice",
  "product_id" : "b640f4c203b7910fc3cbd446ed437cbd",
  "access_point_id" : "dc0f1016f495157344ac5f1296335cff725ef22f",
  "region_id" : "cn-north-4",
  "auth_info" : {
    "auth_type" : "SECRET",
    "secret" : "3b935a250c50dc2c6d481d048cefdc3c",
    "fingerprint" : "dc0f1016f495157344ac5f1296335cff725ef22f",
    "secure_access" : true,
    "timeout" : 300
  },
  "description" : "watermeter device",
  "gateway_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f",
  "provision_info" : {
    "allocation_strategy_type" : "base",
    "life_time" : 84600
  }
}

  • 创建设备(证书策略)请求示例

    POST https://{endpoint}/v5/iotps/{project_id}/devices

{
  "device_id": "d4922d8a-6c8e-4396-852c-164aefa6638f",
  "node_id": "ABC123456789",
  "device_name": "dianadevice",
  "product_id": "b640f4c203b7910fc3cbd446ed437cbd",
  "access_point_id": "dc0f1016f495157344ac5f1296335cff725ef22f",
  "region_id": "cn-north-4",
  "auth_info": {
    "auth_type": "SECRET",
    "secret": "3b935a250c50dc2c6d481d048cefdc3c",
    "fingerprint": "dc0f1016f495157344ac5f1296335cff725ef22f",
    "secure_access": true,
    "timeout": 300
  },
  "description": "watermeter device",
  "gateway_id": "d4922d8a-6c8e-4396-852c-164aefa6638f",
  "provision_info": {
    "allocation_strategy_type": "certificates"
    "certificate_id": "d4922d8a-6c8e-4396-852c-164aefa6638f",
    "life_time": 84600
  }
}

  • 创建设备(自定义策略)请求示例

    POST https://{endpoint}/v5/iotps/{project_id}/devices

{
  "device_id": "d4922d8a-6c8e-4396-852c-164aefa6638f",
  "node_id": "ABC123456789",
  "device_name": "dianadevice",
  "product_id": "b640f4c203b7910fc3cbd446ed437cbd",
  "access_point_id": "dc0f1016f495157344ac5f1296335cff725ef22f",
  "region_id": "cn-north-4",
  "auth_info": {
    "auth_type": "SECRET",
    "secret": "3b935a250c50dc2c6d481d048cefdc3c",
    "fingerprint": "dc0f1016f495157344ac5f1296335cff725ef22f",
    "secure_access": true,
    "timeout": 300
  },
  "description": "watermeter device",
  "gateway_id": "d4922d8a-6c8e-4396-852c-164aefa6638f",
  "provision_info": {
    "allocation_strategy_type": "functions"
    "func_urn": "urn:fss:xxxxxxxxx:7aad83af3e8d42e99ac194e8419e2c9b:function:default:test",
    "life_time": 84600
  }
}

响应示例

状态码： 200

OK

  • 示例 1

    {
  "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",
  "auth_info" : {
    "auth_type" : "SECRET",
    "secret" : "3b935a250c50dc2c6d481d048cefdc3c",
    "fingerprint" : "dc0f1016f495157344ac5f1296335cff725ef22f",
    "secure_access" : true,
    "timeout" : 300
  },
  "product_id" : "b640f4c203b7910fc3cbd446ed437cbd",
  "create_time" : "20190303T081011Z",
  "provision_info" : {
    "access_point" : {
      "access_point_id" : "cn-north-4",
      "access_point_name" : "cn-north-4",
      "region_id" : "cn-north-4"
    },
    "allocation_status" : 0,
    "allocation_strategy_type" : "base",
    "life_time" : 84600
  }
}

  • 示例 2

    {
  "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",
  "auth_info" : {
    "auth_type" : "SECRET",
    "secret" : "3b935a250c50dc2c6d481d048cefdc3c",
    "fingerprint" : "dc0f1016f495157344ac5f1296335cff725ef22f",
    "secure_access" : true,
    "timeout" : 300
  },
  "product_id" : "b640f4c203b7910fc3cbd446ed437cbd",
  "create_time" : "20190303T081011Z",
  "provision_info" : {
    "access_point" : {
      "access_point_id" : "cn-north-4",
      "access_point_name" : "cn-north-4",
      "region_id" : "cn-north-4"
    },
    "allocation_status" : 0,
    "allocation_strategy_type" : "certificates",
    "life_time" : 84600
  }
}

  • 示例 3

    {
  "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",
  "auth_info" : {
    "auth_type" : "SECRET",
    "secret" : "3b935a250c50dc2c6d481d048cefdc3c",
    "fingerprint" : "dc0f1016f495157344ac5f1296335cff725ef22f",
    "secure_access" : true,
    "timeout" : 300
  },
  "product_id" : "b640f4c203b7910fc3cbd446ed437cbd",
  "create_time" : "20190303T081011Z",
  "provision_info" : {
    "access_point" : {
      "access_point_id" : "cn-north-4",
      "access_point_name" : "cn-north-4",
      "region_id" : "cn-north-4"
    },
    "allocation_status" : 0,
    "allocation_strategy_type" : "functions",
    "life_time" : 84600
  }
}

状态码

状态码

描述

200

OK

400

Bad Request

403

Forbidden

500

Internal Server Error

错误码

请参见错误码。

父主题： 设备管理

相关文档