跳至主要內容

API 常见问题

约 2064 字大约 7 分钟

API 常见问题

API 概览

ThingsCloud 支持 API 吗？有哪些类型？

是的，ThingsCloud 支持多种开放的 API，可以满足不同场景的集成需求。

API 类型详解

ThingsCloud 提供以下 API 类型：

  • HTTP RESTful API - 项目级别的资源访问接口
  • HTTP Webhook - 告警通知和数据流转推送
  • MQTT@WebSocket - 实时消息订阅服务

详细说明请浏览 ThingsCloud API 概述。

ThingsCloud API 支持哪些开发平台？

ThingsCloud API 几乎可以用于任何应用开发平台，支持多种编程语言和平台。

开发语言示例

项目 HTTP API 提供了多种编程语言的调用示例，包括：

  • Node.js、Python、PHP、Go、Java、C# 等

您可以基于 ThingsCloud API 开发：

  • Web 浏览器 SaaS 软件
  • 桌面客户端软件
  • 手机 App
  • 工业平板可视化应用
  • 电视大屏应用

详细代码示例请浏览 项目 HTTP API - 请求代码示例。

身份认证

如何开始使用项目 HTTP API？需要哪些准备工作？

在使用项目 HTTP API 之前，需要完成以下准备工作：

  1. 获取 API 接入地址：进入控制台设备详情页的 连接 页面，获取应用端 API 接入点
  2. 创建 API 应用：在控制台 项目应用 中创建 API 类型的应用，获得 AppID、AccessKey 和 SecretKey
  3. 获取 AccessToken：调用身份验证 API 获取访问令牌

身份认证方式

项目 HTTP API 支持两种身份验证方式：

  • 服务器获取 AccessToken：有效期 1 天，适合服务器端调用
  • 浏览器获取 AccessToken：有效期 7 天，适合网页端调用

详细说明请浏览 项目 HTTP API - 准备工作 和 获取 API AccessToken。

API 调用时如何进行身份认证？AccessToken 有效期多久？

项目 HTTP API 使用 Bearer Token 方式进行身份认证，需要在 HTTP 请求头中携带：

Authorization: Bearer <AccessToken>

AccessToken 有效期

不同方式获取的 AccessToken 有效期不同：

  • 服务器获取：有效期 1 天，过期后需重新获取
  • 浏览器获取：有效期 7 天，过期后需重新获取

请注意，项目 HTTP API 中的 AccessToken 与设备证书中的 AccessToken 只是名字相同，没有任何关系，请勿混用。

详细说明请浏览 项目 HTTP API - 获取 API AccessToken。

如何在网页前端直接调用 ThingsCloud API？

在网页前端调用 API 时，推荐使用管理员账号密码方式获取 AccessToken：

浏览器端身份认证

POST /api/v1/admin_login
{
  "app_id": "string",
  "account": "string",
  "password": "string"
}

获取的 AccessToken 有效期为 7 天，可保存到 Cookies 中使用。这种方式适用于浏览器网页中由浏览者输入账号和密码的场景。

详细说明请浏览 项目 HTTP API - 浏览器获取 AccessToken。

设备数据

如何获取设备的历史数据？

项目 HTTP API 提供了读取设备属性历史数据的接口：

历史数据查询

读取设备属性历史数据 API 支持以下功能：

  • 查询指定时间范围内的历史数据
  • 支持分页查询
  • 默认查询最近 30 天的数据
  • 可通过 start_time 和 end_time 参数自定义时间范围
GET /api/v1/device/<device_id>/attribute/<identifier>/series

详细说明请浏览 项目 HTTP API - 读取设备属性历史数据。

如何获取设备数据的聚合统计（如最大值、最小值、平均值）？

项目 HTTP API 提供了属性聚合统计接口，支持多种聚合计算方式：

聚合统计功能

读取设备属性聚合统计数据 API 支持：

  • 时间范围：最近 5 分钟到 1 年，或自定义时间范围
  • 聚合时间窗口：1 分钟到 1 个月
  • 聚合计算方法：平均值、最大值、最小值、中位数、求和、次数统计等
GET /api/v1/device/<device_id>/attribute/<identifier>/aggregate

例如：查询最近 30 天每小时的温度最大值，可使用以下参数：

time_range=last_30d&window=1h&function=max

详细说明请浏览 项目 HTTP API - 读取设备属性聚合统计数据。

设备控制

如何通过 API 向设备下发控制命令？

项目 HTTP API 提供了多种设备控制接口：

设备控制方式

ThingsCloud API 支持以下设备控制方式：

  1. 下发属性到设备

    POST /api/v1/control/device/<device_id>/attributes

  2. 下发命令到设备

    POST /api/v1/control/device/<device_id>/command

  3. 下发自定义数据流到设备

    POST /api/v1/control/device/<device_id>/data/<identifier>/set

对于简单的属性下发（如开关控制），使用应用端设备访问 API 更为便捷：

POST /app/device/v1/<AccessToken>/attributes

详细说明请浏览：

实时消息

如何实现大屏实时显示设备数据？

实现大屏实时显示设备数据，推荐使用 MQTT 应用端订阅服务：

MQTT 实时消息订阅

MQTT 应用端订阅 允许应用通过 MQTT 协议实时订阅设备消息，支持：

  • 设备属性变化
  • 设备事件上报
  • 设备命令回复
  • 设备自定义数据上报
  • 设备告警/恢复
  • 设备上线/断开

连接方式：使用 wss:// 协议，支持服务器端或网页端使用 订阅主题：<ProjectViewKey>/<DeviceViewToken>/attributes

前端开发者可以使用 JavaScript 和 MQTT over WebSocket 直接订阅设备实时消息，实现大屏数据的实时更新。

详细说明请浏览 MQTT 应用端订阅。

API 限速

API 请求频率有限制吗？如何应对限速？

为了确保所有用户都能获得高质量和可靠的服务，项目 HTTP API 采用了动态限速规则。

API 限速规则

当 HTTP 请求频率达到限速标准时，会收到 HTTP 429 Too Many Requests 状态码。

响应头中包含以下信息帮助您管理请求频率：

  • X-RateLimit-Limit - 当前时间窗口内允许的最大请求次数
  • X-RateLimit-Remaining - 当前时间窗口内剩余的可用请求次数
  • X-RateLimit-Reset - 当前时间窗口结束的时间
  • Retry-After - 需要等待多少秒才能进行下一次请求

具体限速规则是动态调整的，以确保系统的稳定性和安全性。

详细说明请浏览 项目 HTTP API - API 限速规则。

工具和集成

是否有现成的工具可以帮助批量操作设备？

ThingsCloud 提供了开源的 Python 工具集，可用于数据导入导出、自动化、数据处理等：

Python 工具集功能

ThingsCloud API Python 工具集 已实现：

  • 批量创建设备
  • 批量导出设备信息及生成设备二维码
  • 批量导出设备属性历史数据
  • 批量导出设备证书

计划实现：

  • 批量创建用户
  • 实时接收设备数据/状态/告警
  • 批量移除设备
  • 批量导出属性聚合统计

工具集开源代码：https://github.com/IoT-ThingsCloud/thingscloud-api-python-tools

详细说明请浏览 ThingsCloud API Python 工具集。

除了 HTTP API，还有哪些方式可以接收设备实时消息？

除了使用 HTTP API 轮询获取设备状态，ThingsCloud 还提供了多种实时消息接收方式：

实时消息接收方式

1. MQTT 应用端订阅 实时性最好，支持设备属性、事件、告警等各类消息的实时推送。

2. 消息规则的数据流转 通过消息规则将设备数据流转到外部系统：

  • 转发到 MQTT Broker
  • 转发到 URL（Webhook）

3. 告警通知 Webhook 通过 HTTP 协议向第三方应用发送告警通知。

详细说明请浏览：

ThingsCloud
Copyright © 2026 ThingsCloud