项目 HTTP API

约 7051 字大约 24 分钟

项目 HTTP API

项目 HTTP API 为您提供了项目级别的 API 接口，包括对项目、设备类型、设备组、设备信息、设备扩展信息、设备数据、设备通信、设备告警、用户等全面的资源访问，采用 HTTP RESTful API 风格。

准备工作

如何获得项目 API 接入地址？

在 ThingsCloud 控制台的项目中，进入任意一个设备详情页，在连接页面中可以找到 应用端 API 接入点，请使用 https 加密访问，确保数据安全性。

不同项目的 API 接入点地址可能不同，请您以控制台获取的地址为准。

创建 API 应用

在正式使用 API 之前，您还需要进入 ThingsCloud 控制台 > 项目应用，创建 API 类型的项目应用，获得 AppID 和 API Key，用于请求 API 时的身份验证。

API 请求代码示例

以获取 API AccessToken 为例，以下是常用编程语言请求 API 的示例代码，仅供参考：

NodeJS

const axios = require('axios');

const postData = {
  app_id: '<app_id>',
  access_key: '<access_key>',
  secret_key: '<secret_key>'
};

axios.post('https://<api-endpoint>/api/v1/access_token', postData, {
  headers: {
    'Content-Type': 'application/json'
  }
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error);
  });

Python

import requests
import json

url = 'https://<api-endpoint>/api/v1/access_token'
data = {
    'app_id': '<app_id>',
    'access_key': '<access_key>',
    'secret_key': '<secret_key>'
}
headers = {
    'Content-Type': 'application/json'
}
response = requests.post(url, data=json.dumps(data), headers=headers)

print(response.text)

PHP

<?php
$api_url = 'https://<api-endpoint>/api/v1/access_token';

$data = array(
    'app_id' => '<app_id>',
    'access_key' => '<access_key>',
    'secret_key' => '<secret_key>'
);
$payload = json_encode($data);

$ch = curl_init($api_url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json'
));

$result = curl_exec($ch);

curl_close($ch);

echo $result;

?>

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    url := "https://<api-endpoint>/api/v1/access_token"
    data := map[string]string{"app_id": "<app_id>", "access_key": "<access_key>", "secret_key": "<secret_key>"}
    payload, _ := json.Marshal(data)
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Java

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class APICallExample {
    public static void main(String[] args) {
        try {
            // 设置 API 地址
            URL url = new URL("https://<api-endpoint>/api/v1/access_token");

            // 打开连接
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setDoOutput(true);
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");

            // 设置请求正文
            JSONObject jsonInput = new JSONObject();
            jsonInput.put("app_id", "<app_id>");
            jsonInput.put("access_key", "<access_key>");
            jsonInput.put("secret_key", "<secret_key>");
            String input = jsonInput.toString();
            OutputStream os = conn.getOutputStream();
            os.write(input.getBytes());
            os.flush();

            // 处理返回结果
            BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream())));
            String output;
            while ((output = br.readLine()) != null) {
                System.out.println(output);
            }

            // 关闭连接
            conn.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C-Sharp

using System;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json;

class APICallExample
{
    static void Main(string[] args)
    {
        var request = (HttpWebRequest)WebRequest.Create("https://<api-endpoint>/api/v1/access_token");
        request.Method = "POST";
        request.ContentType = "application/json";

        var payload = new
        {
            app_id = "<app_id>",
            access_key = "<access_key>",
            secret_key = "<secret_key>"
        };
        var jsonPayload = JsonConvert.SerializeObject(payload);

        using (var streamWriter = new StreamWriter(request.GetRequestStream()))
        {
            streamWriter.Write(jsonPayload);
            streamWriter.Flush();
            streamWriter.Close();
        }

        var response = (HttpWebResponse)request.GetResponse();
        var responseStream = response.GetResponseStream();
        var streamReader = new StreamReader(responseStream);
        var responseText = streamReader.ReadToEnd();

        Console.WriteLine(responseText);
    }
}

获取 API AccessToken

在使用下边的 API 之前，需要先调用身份验证 API，获得 AccessToken，用于所有 API 请求中的身份标识。

提示

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

身份验证 API 支持以下两种方式：

服务器获取 AccessToken

通过服务器发起请求，获取 AccessToken。这种方式，API 密钥保存在服务器，可有效防止泄露。

AccessToken 获取后的有效期为 1 天，过期后请重新获取。

Request Syntax

POST /api/v1/access_token HTTP/1.1
Content-Type: application/json

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

Request Body

Field	Type	Required	Description
`app_id`	string	Yes	在控制台项目应用中获取
`access_key`	string	Yes	在控制台项目应用中获取
`secret_key`	string	Yes	在控制台项目应用中获取

Field	Type	Required	Description
`app_id`	string	Yes	项目应用 AppID，在控制台项目应用中获得
`account`	string	Yes	管理员登录名
`password`	string	Yes	管理员密码

Parameter	Required	Description
`groups`	No	设备组ID，可查询指定设备组下所有设备的状态统计。支持多个设备组ID，以逗号分隔。
`include_sub_groups`	No	若指定设备组ID，可设置是否包含子设备组。`1` 表示包含子设备组，默认为不包含。

Field	Type	Description
`device_total`	number	总设备数
`online_device_total`	number	在线设备数
`offline_device_total`	number	离线设备数
`active_device_total`	number	活跃设备数
`inactive_device_total`	number	非活跃设备数
`alarm_device_total`	number	告警设备数

Field	Type	Description
`id`	string	ID
`name`	string	名称
`descr`	string	描述
`tags`	object	标签
`create_time`	number	创建时间
`device_count`	number	关联的设备数量
`conn_protocol`	string	设备通信方式
`conn_type`	string	设备接入方式

Field	Type	Description
`id`	string	设备组ID
`name`	string	名称
`descr`	string	描述
`tags`	object	标签
`create_time`	number	创建时间，Unix 时间戳（毫秒）
`device_count`	number	分组中的设备数
`children`	array	子组数组

Parameter	Required	Description
`page`	No	页码，默认为1
`type`	No	指定设备类型ID
`groups`	No	指定设备组ID，支持多个设备组ID，用逗号分隔。`groups=` 空值表示查询未分组的设备。
`include_sub_groups`	No	若指定设备组ID，可设置是否包含子设备组。`1` 表示包含子设备组，默认为不包含。

Field	Type	Description
`items`	array	设备数组
`total`	number	设备总数
`page_total`	number	总页数

Field	Type	Description
`id`	string	设备ID
`name`	string	设备名称
`descr`	string	设备描述
`device_key`	string	设备唯一标识 `DeviceKey`
`tags`	object	标签
`create_time`	number	设备创建时间
`alarm`	object	设备告警状态
`active`	object	设备各类消息最新时间
`online`	boolean	设备在线状态
`type`	string	设备类型ID
`type_info`	object	设备类型信息
`groups`	array	设备组ID
`device_code`	string	设备码

Field	Type	Required	Description
`info_type`	string	Yes	扩展信息类型
`value`	object	Yes	扩展信息取值

Field	Type	Description
`identifier`	string	属性标识符
`value`	any	属性值
`attr_type`	string	属性类型。`report`：属性上报， `push`：云端下发，`cloud`：云端私有
`data_type`	string	数据类型
`ts`	string	最后更新时间，Unix 时间戳（毫秒）格式
`model`	object	属性定义信息。若该属性无属性定义，则无该字段。

Field	Type	Description
`name`	string	属性名称
`attr_type`	string	属性类型。属性类型。`report`：属性上报， `push`：云端下发， `share`：设备云端共享，`cloud`：云端私有
`data_type`	string	属性定义中的数据类型
`data_options`	object	属性定义选项

Field	Type	Description
`type`	string	属性类型
`data_type`	string	数据类型
`ts`	number	最后更新时间，Unix 时间戳（毫秒）格式

Parameter	Required	Description
`page`	No	页码，默认为1
`page_records`	No	每页记录数，数值范围为 1-500，默认为 20
`start_time`	No	指定历史数据的开始时间，Unix 时间戳（毫秒）格式
`end_time`	No	指定历史数据的结束时间，Unix 时间戳（毫秒）格式

Field	Type	Description
`timestamp`	string	数据更新时间，ISO 8601 格式
`ts`	string	数据更新时间，Unix 时间戳（毫秒）格式
`name`	string	属性标识符
`value`	string	属性值
`type`	string	属性类型。`report`：属性上报， `push`：云端下发，`cloud`：云端私有

Parameter	Description
`device_id`	设备 ID
`identifier`	属性标识符，仅支持数值类型的属性。

Parameter	Required	Description
`time_range`	No	数据时间范围，默认为`last_1h`（最近1小时）。取值包括：`last_5m`（最近5分钟）、`last_15m`（最近15分钟）、`last_30m`（最近30分钟）、`last_1h`（最近1小时）、`last_3h`（最近3小时）、`last_6h`（最近6小时）、`last_12h`（最近12小时）、`last_1d`（最近1天）、`last_3d`（最近3天）、`last_7d`（最近7天）、`last_15d`（最近15天）、`last_30d`（最近30天）、`last_60d`（最近60天）、`last_90d`（最近90天）、`last_6mo`（最近6个月）、`last_1y`（最近1年）、`today`（今天）、`yday`（昨天）、`this_week`（本周）、`prev_week`（上周）、`this_month`（本月）、`prev_month`（上个月）、`this_year`（今年）、`custom`（自定义时间范围）
`start_time`	No	当`time_range`等于`custom`时，指定数据的开始时间，Unix 时间戳（毫秒）格式
`end_time`	No	当`time_range`等于`custom`时，指定数据的结束时间，Unix 时间戳（毫秒）格式
`window`	No	聚合计算时间，默认为`1h`（1小时）。取值包括：`1m`（1分钟）、`2m`（2分钟）、`5m`（5分钟）、`10m`（10分钟）、`30m`（30分钟）、`1h`（1小时）、`3h`（3小时）、`6h`（6小时）、`1d`（1天）、`7d`（7天）、`1mo`（1个月）
`function`	No	聚合计算方法，默认为`avg`。取值包括：`avg`（平均值）、`max`（最大值）、`min`（最小值）、`median`（中位数）、`first`（首位数）、`last`（末尾数）、`count`（次数统计）、`spread`（首尾差值）、`sum`（求和）

Field	Type	Description
`time_range`	object	实际读取的数据时间范围
`window_duration`	number	聚合计算时间长度（秒数）
`function`	string	聚合计算方法
`data`	array	聚合数据

Field	Type	Description
`timestamp`	string	数据时间，ISO 8601 格式
`ts`	string	数据时间，Unix 时间戳（毫秒）格式
`value`	string	数据值

Field	Type	Required	Description
`name`	string	Yes	用户名称
`account`	string	Yes	用户登录名
`password`	string	Yes	用户登录密码
`descr`	string	No	用户备注信息
`email`	string	No	用户邮箱
`mobile`	string	No	用户手机号
`tags`	object	No	用户标签键值对