ThingsCloud HTTP API 入门：用 cURL 和 Postman 完成第一次调用

HTTP API 是第三方系统连接 ThingsCloud 最直接的方式之一。企业管理系统、数据分析脚本、移动 App 后端和低代码应用，都可以通过标准的 HTTP 请求读取设备数据或向设备发送控制指令。

对于第一次接触 API 的开发者，真正需要先掌握的并不是全部接口，而是一条最短可验证链路：

1. 获取项目的 API 接入点和应用凭证。
2. 用应用凭证换取 AccessToken。
3. 携带 AccessToken 读取项目信息。
4. 获取设备列表，从中找到设备 ID。
5. 读取该设备的当前属性。
6. 确认设备和属性配置无误后，再尝试控制设备。

本文将分别使用命令行工具 cURL 和图形化工具 Postman 完成这条链路。即使暂时不会编程，也可以按照步骤验证接口是否可用。

开始前需要准备什么？

使用项目 HTTP API 前，需要准备以下信息：

项目 HTTP API 面向付费用户开放。不同项目的 API 接入点可能不同，请以控制台显示的地址为准，并始终使用 https。

AppID、AccessKey 和 SecretKey 属于项目应用凭证，不要与设备连接平台时使用的设备证书或设备 AccessToken 混淆。它们名称相似，但服务对象和用途完全不同。

SecretKey 应只保存在可信的服务器、开发机密钥库或本地测试环境中，不要写进网页代码、公开仓库、截图或可共享的 Postman Collection。若凭证疑似泄露，应及时更换。

先理解一次 API 请求的四个部分

一条 HTTP API 请求通常由四部分组成：

• Method：要执行的动作，例如 GET 用于读取，POST 用于创建或发送。
• URL：API 接入点、资源路径和查询参数组成的完整地址。
• Headers：请求的附加信息，例如 JSON 内容类型和身份令牌。
• Body：提交给接口的 JSON 数据。GET 请求通常不需要 Body。

在 ThingsCloud 中，除了获取 AccessToken 的身份验证接口外，本文后续请求都需要携带：

Authorization: Bearer <AccessToken>
Content-Type: application/json

可以把 AccessToken 理解为一张有有效期的临时通行证。服务器端方式获取的令牌有效期为 86400 秒，也就是 1 天。令牌过期后，应重新调用身份验证接口，而不是长期硬编码旧令牌。

方法一：使用 cURL 完成第一次调用

cURL 适合快速验证接口、排查网络问题，也便于把成功请求复制到脚本或后端代码中。macOS 和多数 Linux 系统一般已预装 cURL；Windows 用户可在 PowerShell 或 Windows Terminal 中先执行 curl --version 检查。

为了减少重复输入，先把 API 接入点保存为环境变量。请去掉地址末尾多余的 /：

export API_ENDPOINT="https://<你的应用端 API 接入点>"

第 1 步：获取 AccessToken

执行以下请求，并替换 JSON 中的 3 个凭证值：

curl --request POST "$API_ENDPOINT/api/v1/access_token" \
  --header "Content-Type: application/json" \
  --data '{
    "app_id": "<你的 AppID>",
    "access_key": "<你的 AccessKey>",
    "secret_key": "<你的 SecretKey>"
  }'

验证成功后，响应结构类似：

{
  "result": true,
  "info": {
    "access_token": "eyJ...",
    "expires_in": 86400
  }
}

复制 info.access_token 的值，将其保存为环境变量：

export ACCESS_TOKEN="<刚刚获得的 access_token>"

环境变量只对当前终端会话或其子进程有效。关闭终端后通常需要重新设置，这对于临时测试反而更安全。

第 2 步：读取项目信息

先调用一个不需要额外参数的接口，验证接入点和令牌都正确：

curl --request GET "$API_ENDPOINT/api/v1/project" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

当响应中的 result 为 true，并且 info 中返回了项目的 id 和 name，说明基础鉴权链路已经打通。

第 3 步：获取设备列表

设备列表接口支持分页。下面的请求读取第 1 页，每页最多返回 20 台设备：

curl --request GET "$API_ENDPOINT/api/v1/devices?page=1&page_records=20" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

URL 必须使用引号包裹，否则某些 Shell 会把查询参数中的 & 当作后台运行符号。

成功响应中的关键字段包括：

• info.items：当前页的设备数组。
• info.total：符合条件的设备总数。
• info.page_total：总页数。
• info.items[].id：后续接口要使用的设备 ID。
• info.items[].name：设备名称。
• info.items[].online：设备当前是否在线。
• info.items[].device_key：设备唯一标识 DeviceKey。

每页记录数 page_records 的范围是 1–100。设备较多时，不要只处理第 1 页，应根据 page_total 逐页读取。还可以使用 type 按设备类型过滤，或使用 groups 按设备组过滤。例如：

/api/v1/devices?page=1&page_records=50&type=<设备类型 ID>
/api/v1/devices?page=1&page_records=50&groups=<设备组 ID>&include_sub_groups=1

第 4 步：读取设备当前属性

从设备列表中复制一台设备的 id，保存为变量：

export DEVICE_ID="<设备 ID>"

读取这台设备的所有当前属性值：

curl --request GET "$API_ENDPOINT/api/v1/device/$DEVICE_ID/attributes_raw" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

attributes_raw 返回简洁的“属性标识符—属性值”结构，很适合新手验证数据。例如：

{
  "result": true,
  "info": {
    "temperature": 24.1,
    "humidity": 56.8,
    "relay1": true
  }
}

如果只关心部分属性，可以用英文逗号分隔多个属性标识符：

curl --request GET "$API_ENDPOINT/api/v1/device/$DEVICE_ID/attributes_raw?keys=temperature,humidity" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

这里使用的是物模型中的属性标识符，不一定等于界面上显示的中文属性名称。若返回结果中没有预期字段，请先到设备类型的物模型配置中核对标识符。

方法二：用 Postman 图形化测试

Postman 可以保存请求、切换测试环境并直观看到请求头和响应，适合刚接触 HTTP 的开发者。建议先新建一个 Environment，并添加以下变量：

选择刚创建的环境后，Postman 会把 {{变量名}} 替换成对应的值。敏感变量应设置为 Secret 类型；不要导出、同步或分享包含真实密钥的环境。

在 Postman 中获取令牌

1. 新建请求，Method 选择 POST。
2. URL 填写 {{api_endpoint}}/api/v1/access_token。
3. 在 Headers 中设置 Content-Type: application/json。
4. 在 Body 中选择 raw 和 JSON，输入：

{
  "app_id": "{{app_id}}",
  "access_key": "{{access_key}}",
  "secret_key": "{{secret_key}}"
}

点击 Send 后，先确认 HTTP 状态码，再查看 JSON 中的 result。成功时可以手动复制令牌到 access_token 环境变量，也可以在请求的 Tests 或 Post-response 脚本区域加入：

const data = pm.response.json();

if (data.result === true && data.info && data.info.access_token) {
  pm.environment.set("access_token", data.info.access_token);
}

这样每次重新获取令牌后，后续请求都会自动使用新值。

在 Postman 中读取设备列表

再新建一个 GET 请求：

{{api_endpoint}}/api/v1/devices?page=1&page_records=20

在 Authorization 中选择 Bearer Token，并填入：

{{access_token}}

也可以直接在 Headers 中添加 Authorization: Bearer {{access_token}}，两种方式选择一种即可，不必重复设置。请求成功后，从 info.items 中找一台设备，将其 id 保存到 device_id 环境变量，再请求：

{{api_endpoint}}/api/v1/device/{{device_id}}/attributes_raw

至此，cURL 和 Postman 已经完成了同一条读取链路。若 Postman 能成功而程序请求失败，可以使用 Postman 的代码片段功能生成 cURL 示例，对照检查 Method、URL、Headers 和 Body。

可选：谨慎尝试向设备下发属性

确认设备在线、属性标识符正确，而且该属性支持云端下发后，可以调用属性下发接口。下面以打开 relay1 为例：

curl --request POST "$API_ENDPOINT/api/v1/control/device/$DEVICE_ID/attributes" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "relay1": true
  }'

这条请求可能操作真实设备。请先在测试设备和安全环境中验证，确认继电器、阀门、电机等执行器不会造成设备损坏、生产中断或人身风险。

这里有一个容易混淆但很重要的区别：

• POST /api/v1/control/device/<device_id>/attributes：向设备下发属性。
• PUT /api/v1/control/device/<device_id>/attributes：只更新云端属性。

两者路径相同但 Method 不同，产生的业务效果也不同。开发控制功能时，不能只核对 URL。

再进一步：查询属性历史数据

当前值读取成功后，可以继续查询指定属性的历史记录：

curl --request GET "$API_ENDPOINT/api/v1/device/$DEVICE_ID/attribute/temperature/series?page=1&page_records=50" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

把 temperature 替换为实际属性标识符。page_records 的范围是 1–500。若不提供 start_time 和 end_time，接口默认查询最近 30 天；指定时间范围时，两者应使用 Unix 毫秒时间戳。

HTTP API 适合按需查询和控制。如果应用需要持续接收大量设备的实时消息，频繁轮询并不是最合适的方案，可以进一步使用 ThingsCloud 的 MQTT 应用端订阅、HTTP Webhook 或消息规则转发。

新手最常遇到的错误

1. URL 拼接错误

常见问题包括重复 /、漏写 /api/v1、仍使用示例中的 <api-endpoint>，或误把控制台网址当成 API 接入点。建议先完整复制控制台中的“应用端 API 接入点”，再拼接接口路径。

2. 把设备证书当成项目 API 凭证

设备 AccessToken 用于设备连接平台，不能替代 API 应用的 AppID、AccessKey 和 SecretKey。第三方业务系统访问项目资源，应先通过项目应用凭证换取项目 API 的 AccessToken。

3. Authorization 格式不完整

正确格式是 Bearer、一个半角空格、再加令牌：

Authorization: Bearer eyJ...

缺少 Bearer、缺少空格、复制了引号或使用过期令牌，都会导致鉴权失败。

4. 只看 HTTP 状态码

ThingsCloud API 的业务处理失败可能仍返回 HTTP 200。因此程序应同时判断：

1. HTTP 状态码是否符合预期。
2. JSON 响应中的 result 是否为 true。
3. 失败时记录 errcode、message 和 errors，但不要在日志中输出 SecretKey 或完整令牌。

5. JSON 格式或数据类型错误

JSON 的键名和字符串必须使用双引号，布尔值应写成 true 或 false，不能写成字符串 "true"。下发属性时，属性标识符和数据类型必须与物模型定义一致。

6. 请求过快触发限速

当请求达到动态限速标准时，接口会返回 HTTP 429 Too Many Requests。可结合响应头 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 和 Retry-After 调整请求频率。生产程序应遵循 Retry-After，并采用带随机抖动的退避重试，避免多个任务同时重试。

排查问题时，可以给 cURL 增加 --include 查看响应头，或使用 --verbose 查看更完整的连接过程。--verbose 可能输出鉴权头，分享日志前务必脱敏。

从测试走向正式应用的检查清单

• 凭证只保存在服务器端或安全的密钥管理系统中，不提交到 Git。
• 缓存 AccessToken 并在过期前刷新，避免每个业务请求都重新获取。
• 为请求设置合理的连接和读取超时。
• 设备列表和历史数据按分页完整读取，不假设一页包含全部结果。
• 同时处理 HTTP 状态码和 JSON result，记录可定位问题的脱敏日志。
• 对 429 和临时网络故障使用有限次数的退避重试，不无限重放控制请求。
• 控制接口增加用户权限、参数校验、操作审计和防重复提交机制。
• 高频实时数据改用 MQTT 订阅、Webhook 或消息转发，不用高频 HTTP 轮询替代消息流。

小结

第一次使用 ThingsCloud HTTP API，可以把整个过程理解为“凭证换令牌，令牌访问资源”：先用 API 应用的 AppID、AccessKey 和 SecretKey 获取短期 AccessToken，再通过 Bearer 鉴权读取项目、设备和属性。

cURL 适合验证最小请求和排查问题，Postman 适合保存请求、管理变量并逐步探索接口。完成本文的 5 个基础调用后，就已经具备了继续接入设备历史数据、告警、用户管理和设备通信接口的基础。

完整字段、更多过滤参数和其他接口，请以 ThingsCloud 项目 HTTP API 文档 为准。