项目 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
:可选,页码,默认为 1type
:可选,指定设备类型 IDgroup
:可选,指定设备组 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
:设备 IDidentifier
:属性标识符
Request Query
page
:可选。页码,默认为 1page_records
:可选。每页记录数,数值范围为 1-100,默认为 20start_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
}