ThingsCloud 使用文档

项目 HTTP API

项目 HTTP API

准备工作

获得项目 API 接入地址

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

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

创建 API 应用

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

API 请求代码示例

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

获取 AccessToken

通过身份验证 API，获得 AccessToken，用于所有 API 请求的身份标识。

提示

请注意，API 的 AccessToken 和设备证书中的 AccessToken 没有任何关系，请不要混用。

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

服务器获取 AccessToken

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

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

Request Syntax

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

Request Body

{
	"app_id": "string",
	"access_key": "string",
	"secret_key": "string"
}
  • app_id：在控制台项目应用中获取。
  • access_key：在控制台项目应用中获取。
  • secret_key：在控制台项目应用中获取。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "access_token": "string"
    }
}

浏览器获取 AccessToken

通过管理账号和密码，获取 AccessToken。该方式适用于在浏览器网页中由用户输入账号和密码，通过浏览器发起请求，并将成功获取的 AccessToken 保存到 Cookies 中，请求其它 API 时使用。

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

Request Syntax

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

Request Body

{
	"app_id": "string",
	"account": "string",
	"password": "string"
}
  • app_id：在控制台项目应用中获取。
  • account：在控制台创建管理员时填写账号名称。
  • password：在控制台创建管理员时填写密码。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "access_token": "string"
    }
}

项目信息

读取项目信息

读取当前项目的信息。

Request Syntax

GET /api/v1/project HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string",
        "descr": "string",
        "tags": {}
    }
}

读取设备状态统计

读取项目中所有设备基本状态的统计。

Request Syntax

GET /api/v1/devices_stat HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "device_total": number,
        "online_device_total": number,
        "offline_device_total": number,
        "active_device_total": number,
        "inactive_device_total": number,
        "alarm_device_total": number
    }
}
  • device_total：总设备数
  • online_device_total：在线设备数
  • offline_device_total：离线设备数
  • active_device_total：活跃设备数
  • inactive_device_total：非活跃设备数
  • alarm_device_total：告警设备数

读取设备告警状态统计

读取项目中所有设备告警状态的统计。

Request Syntax

GET /api/v1/devices_alarm_stat HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "device_total": number,
        "alarm_1_total": number,
        "alarm_2_total": number,
        "alarm_3_total": number,
        "normal_total": number,
    }
}
  • device_total：总设备数
  • alarm_1_total：普通告警设备数
  • alarm_2_total：严重告警设备数
  • alarm_3_total：紧急告警设备数
  • normal_total：正常设备数

设备类型

读取设备类型列表

读取所有设备类型列表。

Request Syntax

GET /api/v1/device_types HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "name": "string",
                "descr": "string",
                "tags": {
                    "key1": "string",
                    "key2": "string"
                },
                "create_time": number,
                "device_count": number,
                "conn_protocol": "string",
                "conn_type": "string"
            },
            ...
        ]
    }
}
  • items：设备类型信息结构体数组

读取设备类型下的设备列表

请见 读取设备列表

设备组

读取设备组树形列表

读取所有设备组的树形列表，包含子组。

Request Syntax

GET /api/v1/device_groups_tree HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "name": "string",
                "descr": "string",
                "tags": {
                    "key1": "string",
                    "key2": "string"
                },
                "create_time": number,
                "children": [
                    {
                        "id": "string",
                        "name": "string",
                        "descr": "string",
                        "tags": {
                            "key1": "string",
                            "key2": "string"
                        },
                    }
                    ...
                ]
            },
            ...
        ]
    }
}
  • items：设备组信息结构体数组

读取设备组下的设备列表

请见 读取设备列表

设备管理

读取设备列表

读取所有设备列表。

Request Syntax

GET /api/v1/devices HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Query

  • page：可选，页码，默认为 1
  • type：可选，指定设备类型 ID
  • group：可选，指定设备组 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "name": "string",
                "descr": "string",
                "device_key": "string",
                "tags": {
                    "key1": "string",
                    "key2": "string"
                },
                "create_time": number,
                "alarm": {},
                "active": {},
                "online": boolean,
                "type": "string",
                "type_info": {
                    "id": "string",
                    "name": "string",
                    "conn_type": "string",
                    "conn_protocol": "string"
                }
            },
            ...
        ],
        "total": number,
        "page_total": number,
    }
}
  • total：设备总数
  • page_total：总页数
  • items：设备信息结构体数组

设备信息结构体主要字段说明：

  • alarm：设备告警状态信息结构
  • active：设备各类消息最新时间戳
  • online：设备在线状态

读取设备信息

读取指定设备的信息。

Request Syntax

GET /api/v1/device/<device_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string",
        "descr": "string",
        "device_key": "string",
        "tags": {
            "key1": "string",
            "key2": "string"
        },
        "create_time": number,
        "alarm": {},
        "active": {},
        "online": boolean,
        "type": "string",
        "type_info": {
            "id": "string",
            "name": "string",
            "conn_type": "string",
            "conn_protocol": "string"
        },
        "view_token": "string",
        "device_code": "string"
    }
}

读取设备证书

读取指定设备的连接证书。

Request Syntax

GET /api/v1/device/<device_id>/certificate HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string",
        "access_token": "string",
        "project_key": "string"
    }
}

修改设备基本信息

修改指定设备的基本信息。

Request Syntax

PUT /api/v1/device/<device_id>/info HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Request Body

{
    "name": "string",
    "descr": "string",
    "device_key": "string"
}

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

修改设备标签

修改设备的标签。

Request Syntax

PUT /api/v1/device/<device_id>/tags HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Request Body

{
    "tags": {
        "key1": "string",
        "key2": "string",
        ...
    }
}
  • tags：要更新或增加的标签集合

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

移除设备标签

移除设备的标签。

Request Syntax

POST /api/v1/device/<device_id>/tags_remove HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Request Body

{
    "keys": [
        "string",
        "string",
        ...
    ]
}
  • keys：要移除的标签 Key 数组，可同时移除一个或多个标签。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

移除设备

移除指定设备。

Request Syntax

DELETE /api/v1/device/<device_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

创建设备

创建新设备。

Request Syntax

POST /api/v1/device HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Body

{
    "name": "string",
    "descr": "string",
    "type": "string",
    "tags": {},
    "device_key": "string"
}
  • name：必填，设备名称。
  • descr：选填，备注信息。
  • type：选填，设备类型 ID。
  • tags：选填，标签键值对。
  • device_key：选填，设备唯一标识。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string"
    }
}

设备数据

读取设备属性列表

读取设备的所有属性列表及当前值。

Request Syntax

GET /api/v1/device/<device_id>/attributes HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": [
        {
            "identifier": "string",
            "value": value,
            "attr_type": "string",
            "data_type": "string",
            "ts": number,
            "model": {
                "name": "string",
                "attr_type": "string",
                "data_type": "string",
                "data_options": {
                    
                }
            }
        },
    ]
}

读取设备属性历史数据

读取设备指定属性的历史数据。

Request Syntax

GET /api/v1/device/<device_id>/attribute/<identifier>/series HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID
  • identifier：属性标识符

Request Query

  • page：可选。页码，默认为 1
  • page_records：可选。每页记录数，数值范围为 1-100，默认为 20
  • start_time：可选。指定历史数据的开始时间，单位是 ms。
  • end_time：可选。指定历史数据的结束时间，单位是 ms。

start_time 和 end_time 同时指定时可查询指定时间范围的历史数据，否则默认查询从当前时间往前的历史数据。指定的时间范围最长不能超过 30 天。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": [
        {
            "ts": number,
            "name": "string",
            "value": value,
            "type": "string"
        },
        ...
    ]
}

移除设备属性

移除设备的指定属性，可同时移除一个或多个属性。

Request Syntax

POST /api/v1/device/<device_id>/attributes_remove HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Request Body

{
    "keys": [
        "string",
        "string",
        ...
    ]
}
  • keys：要移除的属性标识符数组，可包含多个属性标识符。例如
{
    "keys": [
        "temperature",
        "humitidy"
    ]
}

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

设备通信

下发属性到设备

向设备下发属性数据。

Request Syntax

POST /api/v1/control/device/<device_id>/attributes HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Request Body

{
    "key1": value,
    "key2": value,
    ...
}

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

更新云端属性

更新设备的云端属性。

Request Syntax

PUT /api/v1/control/device/<device_id>/attributes HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Request Body

{
    "key1": value,
    "key2": value,
    ...
}

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

下发命令到设备

向设备下发命令消息。

Request Syntax

POST /api/v1/control/device/<device_id>/command HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Request Body

{
    "method": "string",
    "params": {},
    "id": number
}

下发命令消息的详细介绍，请浏览 设备接收云端下发命令

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

设备告警

读取所有告警消息

读取项目中的所有告警消息历史。

Request Syntax

GET /api/v1/alarm_logs HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            "id": "string",
            "device_id": "string",
            "alarm_status": number,
            "alarm_level": number,
            "alarm_info": {},
            "create_time": number,
            "notify_logs": [],
            "device": {
                "id": "string",
                "name": "device2"
            }
        ]
    }
}

读取设备告警消息

读取指定设备的告警消息历史。

Request Syntax

GET /api/v1/device/<device_id>/alarm_logs HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id：设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            "id": "string",
            "device_id": "string",
            "alarm_status": number,
            "alarm_level": number,
            "alarm_info": {},
            "create_time": number,
            "notify_logs": [],
            "device": {
                "id": "string",
                "name": "device2"
            }
        ]
    }
}

用户管理

读取用户列表

读取项目中的所有用户列表。

Request Syntax

GET /api/v1/customers HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            "id": "string",
            "account": "string",
            "name": "string",
            "descr": "string",
            "email": "string",
            "mobile": "string",
            "tags": {},
            "locale": "string",
            "create_time": number,
            "count": {
                "device_count": number
            }
        ]
    }
}

读取用户信息

读取指定用户的信息。

Request Syntax

GET /api/v1/customer/{customer_id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id：用户 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "account": "string",
        "name": "string",
        "descr": "string",
        "email": "string",
        "mobile": "string",
        "tags": {},
        "locale": "string",
        "create_time": number,
        "count": {
            "device_count": number
        }
    }
}

创建用户

为项目创建新用户。

Request Syntax

POST /api/v1/customer HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Body

{
    "name": "string",
    "account": "string",
    "password": "string",
    "descr": "string",
    "email": "string",
    "mobile": "string",
    "tags": {}
}
  • name：必填，用户名称。
  • account：必填，用户登录名。
  • password：必填，用户登录密码。
  • descr：选填，备注信息。
  • email：选填，用户邮箱。
  • mobile：选填，用户手机号。
  • tags：选填，标签键值对。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string"
    }
}

修改用户信息

修改指定用户的基本信息。

Request Syntax

PUT /api/v1/customer/<customer_id>/info HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id：用户 ID

Request Body

{
    "name": "string",
    "descr": "string",
    "email": "string",
    "mobile": "string"
}
  • name：选填，用户名称。
  • descr：选填，备注信息。
  • email：选填，用户邮箱。
  • mobile：选填，用户手机号。

以上字段至少填写一个，可修改一个或多个字段。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

修改用户密码

修改指定用户的登录信息。

Request Syntax

PUT /api/v1/customer/<customer_id>/pwd HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id：用户 ID

Request Body

{
    "password": "string",
}
  • password：必填，用户登录密码。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

修改用户标签

修改指定用户的标签。

Request Syntax

PUT /api/v1/customer/<customer_id>/tags HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id：用户 ID

Request Body

{
    "tags": {
        "key1": "string",
        "key2": "string",
        ...
    }
}
  • tags：要更新或增加的标签集合

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

移除用户

移除指定的用户账号。

Request Syntax

DELETE /api/v1/customer/<customer_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id：用户 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

管理员管理

读取当前登录的管理员信息

读取当前登录的管理员信息，仅在通过管理员账号获取 AccessToken 时可用。

Request Syntax

GET /api/v1/admin HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "account": "string",
        "name": "string",
        "email": "string",
        "tags": {}
    }
}

全局定义

Response Syntax

请求功能处理成功

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        ...
    }
}

请求功能处理失败

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": false,
    "errcode": number,
    "message": "string",
    "errors": [],
}

请求资源错误

当请求的 API 资源路径不存在时，返回如下：

HTTP/1.1 404 Not Found
Content-type: application/json

{
    "message": "Request invalid"
}

请求 JSON 格式错误

当请求正文的 JSON 格式错误时，返回如下：

HTTP/1.1 404 Not Found
Content-type: application/json

{
    "result": false,
    "message": "Invalid JSON message",
    "errcode": 400
}
ThingsCloud
Copyright © 2023 ThingsCloud