联犀开发者文档

HTTP协议接入

约 773 字大约 3 分钟

2025-03-03

简述

联犀在支持MQTT协议接入的基础上，同样支持HTTP协议的接入，限制为只支持设备上行的消息，如属性控制下发这种是不支持的。

认证

HTTP协议采用 Basic Auth 的方式进行认证，需要填写的参数对应如下：

  • userName：MQTT协议认证方式中计算出的userName
  • password：MQTT协议认证方式中计算出的password

在 Header 中添加参数 Authorization，其值为在 Basic 之后拼接空格，以及经过 Base64 编码的 {{Username}}:{{Password}}

示例： Authorization: Basic YWRtaW46MTIzNDU2

API接口地址： https://unitedrhino.apifox.cn/api-233401356

请求方式

基本信息

  • 域名与端口：请求的端口和默认web访问的一致
  • URL：/api/v1/things/device/edge/send/{handle}/{type}

请求参数

参数位置必选说明
handlepath是对应MQTT topic的第一个：thing、ota、config等
typepath是操作类型，从topic中提取：物模型下就是property属性、event事件、action行为
productIDheader否产品ID，默认为userName中的设备，如果网关操作子设备，则可以填写子设备的产品ID
deviceNameheader否设备ID，默认为userName中的设备，如果网关操作子设备，则可以填写子设备的设备ID

请求体

Body直接填写MQTT协议中的payload。

cURL示例

curl --location --request POST 'http://localhost:7777/api/v1/things/device/edge/send/gateway/thing' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MDBqJjVDNTMxMDRBNkMzNTsxMjAxMDEyNjtXNk1QTTsxODg5MDc2Mjc2NDE3OjhkNGI3MTMzMzUxNTdmYTNhOTMwNzAwYjM1MGVjMjEzYTU5MWJlNmI7aG1hY3NoYTE=' \
--data-raw '{
  "method": "report",
  "msgToken": "123",
  "params": {
    "ble_key": "123"
  }
}'

响应

响应以JSON格式返回，示例如下：

{
  "code": 200,
  "msg": "success",
  "data": {
    "code": 200,
    "method": "reportReply",
    "msgToken": "123"
  }
}

响应参数说明

参数说明
code200表示成功
msgcode的描述
datadata返回MQTT协议订阅后应该返回的报文

设备文件上传

设备可通过HTTP协议直传文件到云端，同样采用Basic Auth认证。

基本信息

  • URL：/api/v1/things/device/edge/upload-file
  • 请求方式：POST
  • Content-Type：multipart/form-data

请求参数

参数位置必选说明
Authorizationheader是Basic Auth，使用MQTT格式生成的账号密码
fileform-data是上传的文件

cURL示例

curl --location --request POST 'http://localhost:7777/api/v1/things/device/edge/upload-file' \
--header 'Authorization: Basic MDBqJjVDNTMxMDRBNkMzNTsxMjAxMDEyNjtXNk1QTTsxODg5MDc2Mjc2NDE3OjhkNGI3MTMzMzUxNTdmYTNhOTMwNzAwYjM1MGVjMjEzYTU5MWJlNmI7aG1hY3NoYTE=' \
--form 'file=@"/path/to/your/file.jpg"'

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "filePath": "edge/productID/deviceName/250225/125609/file.jpg",
    "fileUri": "https://xxx.oss.com/edge/productID/deviceName/250225/125609/file.jpg"
  }
}

响应参数说明

参数说明
filePath文件存储路径，格式为 edge/{productID}/{deviceName}/{yymmdd}/{HHmmss}/{filename}
fileUri文件访问URI

说明

  • 文件上传到临时存储，路径由设备的productID和deviceName自动组成
  • 禁止上传html、php、jsp等危险文件类型

属性质量扩展（saas 新版支持）

适用版本：saas 新版。

质量报文与 物模型协议 中“属性质量扩展”一致。属性上报地址为 /api/v1/things/device/edge/send/thing/property，Body 保留 report / packReport 原结构，增加按属性对应的 quality；批量质量放在每条 properties[] 中，子设备同理。

{
  "method": "report",
  "msgToken": "1001",
  "timestamp": 1789516800000,
  "params": { "temperature": 26.5 },
  "quality": { "temperature": "GOOD" }
}

允许值为 GOOD、UNCERTAIN、BAD，省略时按 GOOD 处理，非法值校验失败；采集失败使用 null + BAD。认证方式和响应外层不变，也不因此新增 HTTP 下行能力。

更新日志

2026/9/16 14:54
查看所有更新日志
  • 5b100-Merge #40 into master from codex/task-124-quality-protocol于
  • 7e927-文档站全面重构：目录重排、首页重写、案例独立成站、应用市场下线于
  • 74397-docs: 更新OTA升级文档添加OssCustomHost环境变量说明，更新数据权限和http协议接入文档于
  • bddea-docs: 更新文档结构、添加新内容并优化现有文档于
  • 6fa0c-doc于
  • d4fa0-doc: 更换皮肤到最新版于
  • 82830-doc于
  • a74fc-doc: 完善文档于
  • 4066c-doc: 完善文档于
  • d0452-doc: 完善文档于
  • e70a1-doc: 完善文档于
  • 65a22-doc: 完善文档于