智联云 - ZhiLian.Yun

Appearance

设备 HTTP 接入 ​

对于一些非常单一的应用场景，比如只需要定期采集上报数据，不论是快速开发原型，还是小规模的应用，设备使用 HTTP 接入云平台也是不错的选择。

HTTP 协议工作在 TCP/IP 协议栈上，具有很好的易用性和强大的基础库支持，对开发者来说很容易快速上手。设备如果有丰富的资源，还可以使用更加安全的 HTTPS 实现传输层加密。

事实上，将 HTTP 协议的简单易用发挥到极致，便是 CoAP 协议，对于低功耗设备的单一数据上报，使用 CoAP 更加符合要求，这在相关章节会有介绍。

准备工作 ​

获取 HTTP 接入点 ​

在 ZhiLian.Yun 控制台中，进入设备详情页的 连接 页面，可以找到设备的 HTTP 接入点地址，包括 HTTP 和 HTTPS 两种类型。

不同区域的接入点地址可能不同，请以控制台获取的地址为准。下文中的 <endpoint> 均代表该接入点地址。

通用请求头 ​

设备端 HTTP API 通常需要在请求头中携带项目密钥：

Header值说明
Project-KeyProjectKey项目密钥，在设备详情页 > 连接 中获取
Content-Typeapplication/json请求正文为 JSON 格式时设置

部分接口也支持将 projectKey 作为 URL 查询参数或请求正文字段传递，与 Project-Key 请求头二选一即可。

通用响应格式 ​

所有接口均返回统一的 JSON 响应结构：

json
{
  "code": 200,
  "message": "OK",
  "data": {}
}
字段类型说明
codeinteger状态码，200 表示成功
messagestring响应消息
dataobject业务数据，具体结构见各接口说明

设备 HTTP 接口 ​

服务信息 ​

查询当前接入服务的版本信息，可用于设备端健康检查或版本确认。

Request Syntax

GET /api/v1/info HTTP/1.1

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json
json
{
  "code": 200,
  "message": "OK",
  "data": {
    "type": "string",
    "name": "string",
    "title": "string",
    "description": "string",
    "version": "string",
    "build": "string",
    "commit": "string",
    "data": {}
  }
}

Response Body

字段类型说明
typestring服务类型
namestring服务名称
titlestring服务标题
descriptionstring服务描述
versionstring版本号
buildstring构建号
commitstring代码提交标识
dataobject附加信息

设备证书获取（设备注册） ​

设备通过该接口动态获取 accessToken 和 deviceCode，实现一型一密接入。支持 GET 和 POST 两种请求方式。

关于设备证书和一型一密的详细说明，请参阅 设备证书。

Request Syntax

POST /device/v1/certificate HTTP/1.1
Project-Key: <ProjectKey>
Content-Type: application/json
json
{
  "deviceKey": "DEVICE_KEY",
  "typeKey": "TYPE_KEY",
  "productKey": "PRODUCT_KEY",
  "projectKey": "PROJECT_KEY",
  "data": {
    "key1": "value1",
    "key2": "value2"
  }
}

或使用 GET 方式，将参数放在 URL 查询字符串中：

GET /device/v1/certificate?deviceKey=DEVICE_KEY&typeKey=TYPE_KEY HTTP/1.1
Project-Key: <ProjectKey>

Request Body / Query Parameters

字段类型必填说明
deviceKeystring是设备端唯一标识。由设备端生成，应确保在一个项目中的唯一性。通常使用芯片内置的唯一标识，例如模组的 IMEI、MAC、UUID 等
typeKeystring否平台端设备类型标识。当使用该字段时，如果设备 deviceKey 不存在，平台会自动创建新设备并关联到该设备类型
productKeystring否设备端产品识别码。与 typeKey 二选一，平台会在项目中自动查找或创建对应的设备类型
projectKeystring否项目密钥。也可通过 Project-Key 请求头传递
dataobject否设备端附加数据，键值均为字符串

TIP

typeKey 和 productKey 必须填写其中一项，才能实现设备自动注册。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json
json
{
  "code": 200,
  "message": "Device found",
  "data": {
    "id": "DEVICE_ID",
    "name": "DEVICE_NAME",
    "deviceCode": "deviceCode",
    "accessToken": "accessToken"
  }
}

Response Body

字段类型说明
idstring设备 ID
namestring设备名称
deviceCodestring设备编码，后续接口中会用到
accessTokenstring设备访问令牌，用于数据上报和 MQTT 连接

cURL 示例

shell
curl -X POST "https://<endpoint>/device/v1/certificate" \
  -H "Project-Key: <ProjectKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceKey": "DEVICE_KEY",
    "typeKey": "TYPE_KEY"
  }'

设备版本检查 ​

设备通过该接口检查 OTA 固件和配置文件是否有新版本可用，适用于设备开机自检或定时轮询升级。

Request Syntax

GET /device/v1/check_version?deviceCode=<deviceCode>&otaModule=main&otaVersion=1.0.0 HTTP/1.1
Project-Key: <ProjectKey>

Query Parameters

字段类型必填说明
deviceCodestring是设备编码，通过证书获取接口获得
projectKeystring否项目密钥。也可通过 Project-Key 请求头传递
otaModulestring否OTA 固件模块名称，默认 main
otaVersionstring否OTA 固件模块当前版本，示例 1.0.0
otaModule2string否OTA 固件模块 2 名称，示例 mcu
otaVersion2string否OTA 固件模块 2 当前版本
otaModule3string否OTA 固件模块 3 名称，示例 zigbee
otaVersion3string否OTA 固件模块 3 当前版本
otaModule4string否OTA 固件模块 4 名称
otaVersion4string否OTA 固件模块 4 当前版本
configIdinteger否配置文件 ID
configVersioninteger否配置文件当前版本
deviceKeystring否设备唯一标识，用于校验，防止下位机程序拷贝

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json
json
{
  "code": 200,
  "message": "OK",
  "data": {
    "device_code": "deviceCode",
    "config": {
      "id": 134,
      "version": 1,
      "url": "https://config.example.com/device/config/1.json",
      "md5": "74ea6d75f6487049b61a2aa24da2",
      "size": 223
    },
    "ota": [
      {
        "module": "main",
        "enable": 1,
        "version": "1.0.1",
        "url": "https://ota.example.com/device/ota/main.bin",
        "md5": "82ea6675a64a7049b6142aa242a4",
        "size": 223
      },
      {
        "module": "mcu",
        "enable": 1,
        "version": "1.0.1",
        "url": "https://ota.example.com/device/ota/mcu.bin",
        "md5": "82ea6675a64a7049b6142aa242a4",
        "size": 223
      }
    ]
  }
}

Response Body

字段类型说明
device_codestring设备编码
configobject配置文件版本信息，无更新时为 null
config.idinteger配置 ID
config.versioninteger配置版本号
config.urlstring配置文件下载地址
config.md5string配置文件 MD5 校验值
config.sizeinteger配置文件大小（字节）
otaarrayOTA 固件版本信息列表
ota[].modulestring固件模块名称
ota[].enableinteger是否可以升级，0 禁止升级，1 可以升级
ota[].versionstring目标版本号，采用 xx.yy.zz 点分格式，范围 0.0.0 ~ 99.99.99
ota[].urlstring固件下载地址
ota[].md5string固件 MD5 校验值
ota[].sizeinteger固件大小（字节）

cURL 示例

shell
curl -X GET "https://<endpoint>/device/v1/check_version?deviceCode=<deviceCode>&otaModule=main&otaVersion=1.0.0&configId=1&configVersion=1" \
  -H "Project-Key: <ProjectKey>"

申请文件上传凭证 ​

设备上传文件前，需先调用该接口申请上传凭证，获取上传 URL。

Request Syntax

POST /api/v1/upload/apply HTTP/1.1
Project-Key: <ProjectKey>
Content-Type: application/json
json
{
  "tenantId": "000000",
  "deviceCode": "deviceCode",
  "fileName": "tmp.txt",
  "fileSize": 1024,
  "fileType": "text/plain",
  "relatedId": "",
  "remark": ""
}

Request Body

字段类型必填说明
tenantIdstring是租户 ID
deviceCodestring是设备编号
fileNamestring是文件名
fileSizeinteger否文件大小（字节）
fileTypestring否文件类型
relatedIdstring否关联 ID
remarkstring否备注

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json
json
{
  "code": 200,
  "message": "OK",
  "data": {
    "uploadUrl": "https://<endpoint>/api/v1/upload/execute?Token=UPLOAD_TOKEN"
  }
}

Response Body

字段类型说明
uploadUrlstring上传 URL，包含上传凭证 Token，用于下一步执行文件上传

执行文件上传 ​

使用申请凭证接口返回的 uploadUrl，以 multipart/form-data 方式上传文件。

Request Syntax

POST /api/v1/upload/execute?Token=<Token> HTTP/1.1
Content-Type: multipart/form-data
表单字段类型必填说明
filefile是上传的文件数据

上传凭证 Token 通过 URL 查询参数传递，参数名区分大小写。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json
json
{
  "code": 200,
  "message": "OK",
  "data": {
    "fileId": 11,
    "fileUrl": "resource/upload/000000/iot/device/10000023/tmp.txt",
    "fileName": "tmp.txt"
  }
}

Response Body

字段类型说明
fileIdintegerOSS 文件 ID
fileUrlstring文件访问 URL
fileNamestring文件名

cURL 示例

shell
# 第一步：申请上传凭证
curl -X POST "https://<endpoint>/api/v1/upload/apply" \
  -H "Project-Key: <ProjectKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "000000",
    "deviceCode": "<deviceCode>",
    "fileName": "tmp.txt"
  }'

# 第二步：使用返回的 uploadUrl 上传文件
curl -X POST "https://<endpoint>/api/v1/upload/execute?Token=<Token>" \
  -F "file=@/path/to/tmp.txt"

设备数据上报 ​

除上述管理类接口外，设备还可通过 HTTP 协议上报属性数据。获取 accessToken 后，使用如下 URL 提交数据：

POST https://<endpoint>/device/v1/<AccessToken>/attributes

请求头需携带 Project-Key，请求正文为 JSON 格式的属性数据：

json
{
  "temperature": 34.2
}

详细的上报示例请参阅 设备上报数据。

接口一览 ​

接口方法路径说明
服务信息GET/api/v1/info查询接入服务版本信息
设备证书获取GET / POST/device/v1/certificate动态获取设备证书，支持自动注册
设备版本检查GET/device/v1/check_version检查 OTA 固件和配置文件更新
申请文件上传凭证POST/api/v1/upload/apply申请文件上传 URL
执行文件上传POST/api/v1/upload/execute上传文件到云端
属性上报POST/device/v1/<AccessToken>/attributes上报设备属性数据