Get Device Connection Info¶

Get Device Connection Info API 用于设备端获取设备自身、子设备或支路设备的 EnOS 三元组信息，以及 EnOS MQTT/HTTP 协议公网地址。设备端通过当前 API 获取三元组信息后，将使用 EnOS 提供的设备 SDK 尝试连接 EnOS。

Get Device Connection Info API 与 Bootstrap Device API 完全兼容，区别在于：

API 名称	功能	场景示例
Get Device Connection Info	获取已注册设备的三元组信息，包括单路设备、多路设备、网关设备和子设备。	设备获取自身、支路设备或子设备的三元组信息。
Bootstrap Device	直连设备获取设备自身的三元组信息，若该设备未注册，将同时完成设备注册。	直连设备获取自身的三元组信息，完成自身注册。

前提条件¶

确保该设备已完成分配和激活。如有需要，可使用 Allocate DPS Device API 分配和激活设备。

请求格式¶

POST http(s)://{dps-address}/preview/get/conn

具体说明，参见有关设备 API。

请求参数（Body）¶

名称	必需/可选	数据类型	描述
self	必需	DeviceAuth 结构体	设备自身的认证信息。
signMethod	可选	String	指定签名算法，目前仅支持 `sha256`。
sub	可选	SubDeviceAuth 结构体	子设备或支路设备的认证信息。当 `sub` 不为空时，`self` 必须是一个网关设备。常见场景示例，参见场景示例。

DeviceAuth 结构体 ¶

名称	必需/可选	数据类型	描述
sn	必需	String	设备 SN 号，系统自动生成。
timestamp	必需	Long	时间戳，用于生成 `sign` 校验值。
sign	必需	String	将注册组密码、`sn` 和 `timestamp` 作为输入，使用 SHA256 算法进行哈希运算后生成的校验值。注册组密码可以在 EnOS 管理控制台 > 设备预配置 > 注册组管理中的注册组详情中查看。

SubDeviceAuth 结构体 ¶

名称	必需/可选	数据类型	描述
branch	取决于使用场景，参见场景示例。	Integer	通道支路编号，用于指定连接通道。
sn	取决于使用场景，参见场景示例。	String	系统自动生成的设备 SN 号。
timestamp	取决于使用场景，参见场景示例。	Long	时间戳，用于生成 `sign` 校验值。
sign	取决于使用场景，参见场景示例。	String	将注册组密码、`sn` 和 `timestamp` 作为输入，使用 SHA256 算法进行哈希运算后生成的校验值。注册组密码可以在 EnOS 管理控制台 > 设备预配置 > 注册组管理中的注册组详情中查看。
createSubSnFromGw	取决于不同场景，参见场景示例。	Boolean	当传入支路编号时，是否从网关注册组生成一个虚拟的子设备 SN 号。默认为 `true`。

下表列举常见场景下 SubDeviceAuth 结构体参数的使用方法。

场景描述	参数用法
单路设备或网关设备直连上云，需获取设备本身的三元组信息。	SubDeviceAuth 结构体所有参数为空。参见示例 1。
多路设备直连上云，需获取某一支路设备的三元组信息。	需要指定 `branch` 支路编号，此时 `sn`、`timestamp` 和 `sign` 为空，`createSubSnFromGw` 为默认状态。参见示例 2。
网关设备下单路子设备上云，需获取子设备的三元组信息。	`branch` 为空，需要指定 `sn`、`timestamp` 和 `sign` 作为子设备的验证信息。此时 `createSubSnFromGw` 为默认状态。参见示例 3。
网关设备下多路子设备上云，需获取某一支路子设备的三元组信息。	需要指定 `branch` 支路编号，`sn`、`timestamp` 和 `sign` 为支路子设备的验证信息。此时 `createSubSnFromGw` 为默认状态。参见示例 4。

响应参数¶

名称	数据类型	描述
murl	String	设备所在环境的 EnOS MQTT 协议公网地址，当 SubDeviceAuth 结构体为空时返回。
hurl	String	设备所在环境的 EnOS HTTP 协议公网地址，当 SubDeviceAuth 结构体为空时返回。
pk	String	设备三元组中的 product key。
dk	String	设备三元组中的 device key。
ds	String	设备三元组中的 device secret。

错误码¶

代码	错误信息	描述
10000	[{sn}] not allocated	当设备未分配，且注册组的“自动激活”开关未打开时，无法取得三元组，会返回设备未分配的错误信息。

示例¶

下面列出 SubDeviceAuth 结构体场景示例中 4 种场景下的请求示例和返回示例。

示例 1¶

单路设备或网关设备直连上云，需获取设备本身的三元组信息时，参考以下示例。

请求示例¶

url: http://{dps-address}/preview/get/conn
method: POST
requestBody:
{
    "self": {
        "sn": "selfsn",
        "timestamp": 1607073024438,
        "sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
    }
}

返回示例¶

{
    "murl": "tcp://mqtt-{address}:21883",
    "hurl": "http://http-{address}",
    "pk": "selfProductKey",
    "dk": "selfDeviceKey",
    "ds": "selfDeviceSecret"
}

示例 2¶

多路设备直连上云，需获取某一支路设备的三元组信息时，参考以下示例。

请求示例¶

url: http://{dps-address}/preview/get/conn
method: POST
requestBody:
{
    "signMethod":"sha256",
    "self": {
        "sn": "selfsn",
        "timestamp": 1607073024438,
        "sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
    },
    "sub": {
        "branch": 2
    }
}

返回示例¶

{
    "pk": "branchProductKey",
    "dk": "branchDeviceKey",
    "ds": "branchDeviceSecret"
}

示例 3¶

网关设备下单路子设备上云，需获取子设备的三元组信息时，参考以下示例。

请求示例¶

url: http://{dps-address}/preview/get/conn
method: POST
requestBody:
{
    "signMethod":"sha256",
    "self": {
        "sn": "selfsn",
        "timestamp": 1607073024438,
        "sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
    },
    "sub": {
        "sn": "subsn",
        "timestamp": 1607073024438,
        "sign": "7197763f578fdb703134a2f9ae0145cbd865a3a60ea7742b541b5bb0db793aca"
    }
}

返回示例¶

{
    "pk": "subProductKey",
    "dk": "subDeviceKey",
    "ds": "subDeviceSecret"
}

示例 4¶

网关设备下多路子设备上云，需获取某一支路子设备的三元组信息时，参考以下示例。

请求示例¶

url: http://{apigw-address}/preview/get/conn
method: POST
requestBody:
{
    "signMethod":"sha256",
    "self": {
        "sn": "selfsn",
        "timestamp": 1607073024438,
        "sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
    },
    "sub": {
        "branch": 2,
        "sn": "subsn",
        "timestamp": 1607073024438,
        "sign": "7197763f578fdb703134a2f9ae0145cbd865a3a60ea7742b541b5bb0db793aca"
    }
}

返回示例¶

{
    "pk": "subProductKey",
    "dk": "subDeviceKey",
    "ds": "subDeviceSecret"
}