HTTP 设备接入指南

本文档介绍如何通过 HTTP/HTTPS 协议 将设备安全接入到 Xlink 物联网平台，实现数据上报功能。
HTTP（Hypertext Transfer Protocol）是一种应用层协议，基于请求-响应模式，简单易用，适用于具备网络能力的各类智能设备。
Xlink 平台提供标准 RESTful API 接口，支持 JSON 数据格式，设备通过 HTTP POST 请求上报数据，无需维护长连接。

⚠️ 重要说明：HTTP 协议是单向上报模式，平台无法主动下发命令给设备。若需要实时命令下发功能，请使用 MQTT 协议接入。

接入准备

1. 创建产品
   在云智易物联网平台中创建一个 产品（Product），这里以温湿度传感器为例。

产品创建流程可参考《X-Link物联平台使用引导》

1. 定义物模型
   进入产品管理页面，定义设备的物模型。平台提供大量标准物模型模板，也可自定义属性、事件与服务。
   

2. 选择 HTTP 协议接入方式
   创建完成后，进入产品详情->设备接入页面，选择 HTTP 直连接入方式。可查看连接信息。

3. 注册设备并获取 Token
   点击设备列表页面注册设备，填写设备 Mac 地址等信息。注册成功后，点击查看凭证->获取凭证，复制 Token，用于 HTTP 请求认证。

💡 重要：每个设备的 Token 与设备 Mac 地址一一对应，平台通过 Token 自动识别设备身份，无需在请求数据中传递设备标识。

1. 配置自定义 Topic
   在设备接入配置页面，点击"自定义 Topic"配置数据上报的端点路径。

💡 技术说明：平台 HTTP 接口底层基于 MQTT 实现，请求路径固定前缀为 /v1/topic，配置的 Topic 会添加在后面。
例如：配置 Topic 为 /test，则完整请求地址为 https://http-cm.xlink.cn:6800/v1/topic/test

1. API 接入信息

参数	说明	示例
API 域名	接入服务器地址	http://http-cm.xlink.cn 或 https://http-cm.xlink.cn
端口	服务端口	HTTP: 5800 / HTTPS: 6800
请求路径	/v1/topic + 自定义 Topic	/v1/topic/test
完整端点	域名:端口 + 请求路径	http://http-cm.xlink.cn:5800/v1/topic/test https://http-cm.xlink.cn:6800/v1/topic/test
认证方式	设备认证方式	1p0MHaU3kKfopWjKIHk8V4
数据格式	支持的数据格式	JSON

⚠️ 推荐使用 HTTPS 加密传输确保数据安全。

HTTP API 数据格式

项目	说明
编码	UTF-8
数据格式	JSON
Content-Type	application/json
认证方式	HTTP Header: X-Token
请求方法	POST

API 端点说明

属性上报

端点: /v1/topic/{custom_topic}（固定前缀 + 自定义 Topic）

示例: POST /v1/topic/test

💡 说明：

• 必须先在平台设备接入配置页面完成 Topic 配置
• 请求路径固定前缀为 /v1/topic，配置的 Topic 添加在后面
• HTTP 使用端口 5800，HTTPS 使用端口 6800
• 例如：配置 Topic 为 /test，则 HTTPS 请求地址为 https://http-cm.xlink.cn:6800/v1/topic/test

请求头:

Content-Type: application/json
X-Token: 1p0MHaU3kKfopWjKIHk8V4

请求体示例:

// 示例：直接上报数据（推荐）
{
  "battery_voltage": 30,
  "signal_strength": 23.2,
  "hum": 34.43,
  "electricity": 90,
  "temp": 46.4
}

💡 数据结构说明：请求体的 JSON 数据结构完全没有限制，可以根据业务需要自由定义，无需特定字段包裹。

自定义数据格式解析

如果需要将设备上报的自定义数据格式转换为平台物模型，可以添加解析脚本：

// HTTP 设备上报数据解析
function up(topic, topicParams, payload) {
  // 1. 解析 JSON
  var data = {};
  try {
    data = JSON.parse(payload);
  } catch (e) {
    return [];
  }

  // 2. 组装物模型属性
  return [
    {
      time: Date.now(), // 使用平台接收时间
      attributes: {
        battery_voltage: data.battery_voltage,
        signal_strength: data.signal_strength,
        humidity: data.hum,
        electricity: data.electricity,
        temperature: data.temp
      }
    }
  ];
}

💡 提示：

• 请求体的 JSON 数据结构完全灵活，可直接上报数据，也可使用 attribute 等字段包裹
• HTTP 协议仅支持设备主动上报数据，无需配置命令下发解析脚本

接入配置示例

使用 curl 命令行

上报设备属性:

curl -X POST https://http-cm.xlink.cn:6800/v1/topic/test \
  -H "Content-Type: application/json" \
  -H "X-Token: 1p0MHaU3kKfopWjKIHk8V4" \
  -d '{
    "battery_voltage": 30,
    "signal_strength": 23.2,
    "hum": 34.43,
    "electricity": 90,
    "temp": 46.4
}'

使用 Postman 测试

1. 下载 Postman
   访问 Postman 官网 下载对应系统版本。

2. 配置请求

• 方法: POST
• URL: https://http-cm.xlink.cn:6800/v1/topic/test
• Headers:
  • Content-Type: application/json
  • X-Token: 1p0MHaU3kKfopWjKIHk8V4
• Body (raw JSON):

{
  "battery_voltage": 30,
  "signal_strength": 23.2,
  "hum": 34.43,
  "electricity": 90,
  "temp": 46.4
}

3. 平台查看数据
   在平台设备详情页可以看到最新上报的属性值。

总结

通过本文档，您已掌握如何将基于 HTTP/HTTPS 协议的设备安全接入 Xlink 物联网平台。
HTTP 接入方式具有简单易用、无需维护长连接、开发调试方便等优点，适用于数据上报场景。设备可使用标准 HTTP 客户端库快速集成，无需额外的协议适配工作。

适用场景：

• 定期上报传感器数据（温度、湿度、位置等）
• 状态监控与日志上报
• 无需实时命令下发的应用

不适用场景：

• 需要平台主动下发命令（如远程控制开关）
• 需要实时双向通信
• 上述场景请使用 MQTT 协议

常见问题 FAQ

Q1：HTTP 请求返回 401 Unauthorized？
A1：请确认以下几点：

• 设备是否已在平台注册（必须先在平台注册设备并指定 Mac 地址，才能获取 Token）；
• HTTP Header 中是否正确添加了 X-Token；
• Token 是否正确（从平台设备详情页获取）；
• Token 是否有效且未过期；
• 检查 Token 是否被禁用或删除。

💡 设备注册流程：

1. 在设备列表页面点击"注册设备"
2. 填写设备 Mac 地址等信息
3. 注册成功后，点击"查看凭证"
4. 点击"获取凭证"
5. 复制 Token 用于 HTTP 请求认证

Q2：数据上报成功但平台未显示？
A2：常见原因包括：

• 未配置 Topic：必须在平台设备接入页面配置自定义 Topic；
• Topic 配置错误：检查配置的 Topic 路径与请求 URL 是否一致；
• JSON 数据格式错误或字段类型不匹配；
• 物模型中未定义相关属性（需先在平台创建对应属性定义）；
• 解析脚本配置错误（若使用自定义格式，检查脚本逻辑）。

Q3：HTTP 协议能否实现命令下发？
A3：不能。HTTP 是基于请求-响应模式的协议，服务器无法主动推送数据给设备。若需要平台主动下发命令给设备，必须使用支持服务器推送的协议：

• MQTT：支持订阅/发布，平台可主动推送命令（推荐）
• WebSocket：支持全双工通信
• CoAP：轻量级的物联网协议，支持观察者模式
  HTTP 协议仅适用于设备主动上报数据的场景。

Q4：HTTP 和 HTTPS 有什么区别？
A4：

• HTTP: 明文传输，适用于内网或测试环境；
• HTTPS: SSL/TLS 加密传输，推荐生产环境使用，确保数据安全；
• 平台同时支持两种方式，仅需更改 URL scheme（http:// 或 https://）。

Q5：请求超时如何处理？
A5：

• 检查网络连接是否正常（可使用 ping 或 traceroute 测试）；
• 确认 DNS 解析是否成功（http-cm.xlink.cn 能否正确解析）；
• 增加 HTTP 客户端超时时间（建议 15-30 秒）；
• 平台接口响应时间通常 < 500ms，若持续超时请联系技术支持。

Q6：支持批量上报数据吗？
A6：支持。可在一次请求中上报多个属性：

{
  "battery_voltage": 30,
  "signal_strength": 23.2,
  "hum": 34.43,
  "electricity": 90,
  "temp": 46.4
}

JSON 数据结构完全灵活，无任何字段限制，但建议单次请求体大小不超过 100KB。

Q7：HTTP 协议的局限性是什么？
A7：HTTP 协议的主要局限性包括：

• 单向通信：只能设备主动上报，平台无法主动下发
• 无状态连接：每次请求都需要重新建立连接
• 不适合高频上报：频繁请求会增加网络开销和服务器压力
• 延迟较高：相比 MQTT 等长连接协议，响应延迟更高

若项目需要双向通信或实时性要求高，建议使用 MQTT 协议。