文档首页/ 设备接入 IoTDA/ API参考（联盟区域）/ 应用侧API参考/ API/ 设备隧道管理/ 创建设备隧道
更新时间：2026-06-29 GMT+08:00
查看PDF
分享

创建设备隧道

功能介绍

用户可以通过该接口创建隧道（WebSocket协议），应用服务器和设备可以通过该隧道进行数据传输。

  • 该API调用后平台会向对应的MQTT/MQTTS设备下发隧道地址及密钥，同时给应用服务器也返回隧道地址及密钥，设备可以通过该地址及密钥创建WebSocket协议连接。

  • 一个设备无法创建多个隧道。

  • 具体应用可见“设备远程登录”功能，请参见设备远程登录。

URI

POST /v5/iot/{project_id}/tunnels

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数说明 ：项目ID。获取方法请参见 获取项目ID。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

Instance-Id

否

String

参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情。
表3 请求Body参数

参数

是否必选

参数类型

描述

device_id

是

String

参数说明：设备ID

响应参数

状态码：201

表4 响应Body参数

参数

参数类型

描述

tunnel_id

String

隧道ID

tunnel_access_token

String

鉴权信息

expires_in

Integer

鉴权信息的过期时间, 单位：秒

tunnel_uri

String

websocket接入地址

请求示例

创建设备隧道，设备id为b64b7a625b84c1334befb648b_test。

POST https://{endpoint}/v5/iot/{project_id}/tunnels

{
  "device_id" : "b64b7a625b84c1334befb648b_test"
}

响应示例

状态码：201

创建设备隧道成功

{
  "tunnel_id" : "d144a524-1997-4b99-94bf-f27128da8a34",
  "tunnel_access_token" : "MIIDkgYJKoZIhvcNAQcCoIIDgzCCXXXXX",
  "expires_in" : 86400,
  "tunnel_uri" : "wss://tunnel.st1.iotda-app.cn-XXX.XXXXX.com/v5/iot/tunnels/XXX/source-connect"
}

状态码

状态码

描述

201

创建设备隧道成功

400

输入参数不正确

401

Unauthorized

403

鉴权认证失败

500

Internal Server Error

错误码

请参见错误码。

父主题： 设备隧道管理