设备管理

设备是数据采集和控制的核心单元。每个设备可以配置多个因子（数据点），用于采集传感器数据或控制执行器。

重要提示

设备不支持通过 API 直接创建，只能通过绑定接口将已有设备添加到项目中。

接口概览

方法	端点	描述
`GET`	`/api/v2/projects/{project_id}/devices/`	获取项目下的设备列表
`GET`	`/api/v2/projects/{project_id}/devices/{id}/`	获取设备详情
`PUT`	`/api/v2/projects/{project_id}/devices/{id}/`	更新设备信息
`POST`	`/api/v2/projects/{project_id}/devices/bind/`	绑定设备
`POST`	`/api/v2/projects/{project_id}/devices/{id}/unbind/`	解绑设备
`POST`	`/api/v2/projects/{project_id}/devices/{id}/set-project/`	移动设备到其他项目
`GET`	`/api/v2/projects/{project_id}/devices/{id}/data/`	获取设备实时数据
`POST`	`/api/v2/projects/{project_id}/devices/{id}/reboot/`	重启设备

设备对象

字段	类型	描述
`id`	integer	设备主键（内部 ID）
`serial_number`	string	设备序列号（唯一值）
`device_name`	string	设备名称
`agri_id`	string	设备内部标识符
`info`	string	设备描述
`status`	integer	设备状态码
`is_online`	boolean	是否在线
`is_debug`	boolean	是否开启调试模式
`has_thresholds`	boolean	是否配置了阈值告警
`bind_time`	string	绑定时间
`connect_time`	string	最后连接时间
`create_time`	string	创建时间
`project`	object	所属项目信息
`base_device`	object	设备型号信息

base_device 对象

字段	类型	描述
`name`	string	型号名称
`model`	string	型号编号
`image`	string	型号图片 URL
`property`	integer	设备属性位标志

获取设备列表

获取指定项目下的所有设备。

GET /api/v2/projects/{project_id}/devices/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符

响应示例

json

[
    {
        "id": 16872,
        "serial_number": "ABCD1234",
        "device_name": "温湿度采集器",
        "agri_id": "d-1000-abcd1234",
        "info": "1号温室",
        "status": 100,
        "is_online": true,
        "is_debug": false,
        "has_thresholds": true,
        "bind_time": "2025-02-13T07:42:50Z",
        "connect_time": "2025-03-21T06:42:20Z",
        "create_time": "2024-01-13T12:14:40Z",
        "project": {
            "name": "智慧农业项目",
            "project_id": "proj_abcdefghij"
        },
        "base_device": {
            "id": 16,
            "name": "4G数据采集器",
            "model": "Y201",
            "image": "https://example.com/y201.png",
            "property": 63
        }
    }
]

代码示例

PythoncURL

python

import requests

API_BASE = "https://dl.yengear.com/api/v2"
ACCESS_TOKEN = "your_access_token"

def get_devices(project_id):
    """获取项目下的设备列表"""
    response = requests.get(
        f"{API_BASE}/projects/{project_id}/devices/",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    )
    return response.json()

# 调用示例
devices = get_devices("proj_abcdefghij")
for device in devices:
    status = "在线" if device["is_online"] else "离线"
    print(f"{device['device_name']}: {status}")

bash

curl -X GET "https://dl.yengear.com/api/v2/projects/proj_abcdefghij/devices/" \
     -H "Authorization: Bearer your_access_token"

获取设备详情

获取指定设备的详细信息。

GET /api/v2/projects/{project_id}/devices/{id}/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符
`id`	integer/string	是	设备主键或设备 ID

提示

id 参数支持设备主键（整数）或设备 ID（字符串）两种格式。

响应示例

json

{
    "id": 16872,
    "serial_number": "ABCD1234",
    "device_name": "温湿度采集器",
    "agri_id": "d-1000-abcd1234",
    "info": "1号温室",
    "status": 100,
    "is_online": true,
    "is_debug": false,
    "has_thresholds": true,
    "device_config": {},
    "bind_time": "2025-02-13T07:42:50Z",
    "connect_time": "2025-03-21T06:42:20Z",
    "create_time": "2024-01-13T12:14:40Z",
    "project": {
        "name": "智慧农业项目",
        "project_id": "proj_abcdefghij"
    },
    "base_device": {
        "id": 16,
        "name": "4G数据采集器",
        "model": "Y201",
        "image": "https://example.com/y201.png",
        "property": 63
    }
}

错误响应

状态码	描述
`404`	设备不存在

更新设备

更新设备的基本信息。

PUT /api/v2/projects/{project_id}/devices/{id}/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符
`id`	integer/string	是	设备主键或设备 ID

请求参数

参数	类型	必填	描述
`device_name`	string	否	设备名称
`info`	string	否	设备描述
`is_debug`	boolean	否	是否开启调试模式

请求示例

json

{
    "device_name": "1号温室采集器",
    "info": "位于温室东侧"
}

响应示例

返回更新后的完整设备对象。

代码示例

PythoncURL

python

def update_device(project_id, device_id, **kwargs):
    """更新设备信息"""
    response = requests.put(
        f"{API_BASE}/projects/{project_id}/devices/{device_id}/",
        headers={
            "Authorization": f"Bearer {ACCESS_TOKEN}",
            "Content-Type": "application/json"
        },
        json=kwargs
    )
    return response.json()

# 调用示例
updated = update_device(
    "proj_abcdefghij", 
    16872, 
    device_name="新名称",
    info="新描述"
)

bash

curl -X PUT "https://dl.yengear.com/api/v2/projects/proj_abcdefghij/devices/16872/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"device_name": "新名称", "info": "新描述"}'

绑定设备

将设备绑定到指定项目。绑定时需要提供设备 ID 和安全码。

POST /api/v2/projects/{project_id}/devices/bind/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符

请求参数

参数	类型	必填	描述
`serial_number`	string	是	设备序列号
`safe_code`	string	是	设备安全码

请求示例

json

{
    "serial_number": "ABCD1234",
    "safe_code": "123456"
}

响应示例

成功绑定后返回设备对象。

错误响应

状态码	错误信息	描述
`400`	设备已添加至其他项目	设备已被其他项目绑定
`404`	设备不存在或安全码错误	设备 ID 或安全码不正确

代码示例

PythoncURL

python

def bind_device(project_id, serial_number, safe_code):
    """绑定设备到项目"""
    response = requests.post(
        f"{API_BASE}/projects/{project_id}/devices/bind/",
        headers={
            "Authorization": f"Bearer {ACCESS_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "serial_number": serial_number,
            "safe_code": safe_code
        }
    )
    return response.json()

# 调用示例
device = bind_device("proj_abcdefghij", "ABCD1234", "123456")
print(f"设备绑定成功: {device['device_name']}")

bash

curl -X POST "https://dl.yengear.com/api/v2/projects/proj_abcdefghij/devices/bind/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"serial_number": "ABCD1234", "safe_code": "123456"}'

解绑设备

将设备从项目中解绑。解绑后设备将不再属于任何项目。

POST /api/v2/projects/{project_id}/devices/{id}/unbind/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符
`id`	integer/string	是	设备主键或设备 ID

响应

成功解绑返回 HTTP 状态码 204 No Content。

代码示例

PythoncURL

python

def unbind_device(project_id, device_id):
    """解绑设备"""
    response = requests.post(
        f"{API_BASE}/projects/{project_id}/devices/{device_id}/unbind/",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    )
    return response.status_code == 204

# 调用示例
if unbind_device("proj_abcdefghij", 16872):
    print("设备已解绑")

bash

curl -X POST "https://dl.yengear.com/api/v2/projects/proj_abcdefghij/devices/16872/unbind/" \
     -H "Authorization: Bearer your_access_token"

移动设备到其他项目

将设备移动到同一组织下的其他项目。

POST /api/v2/projects/{project_id}/devices/{id}/set-project/

路径参数

参数	类型	必填	描述
`project_id`	string	是	当前项目唯一标识符
`id`	integer/string	是	设备主键或设备 ID

请求参数

参数	类型	必填	描述
`project_id`	string	是	目标项目的唯一标识符

请求示例

json

{
    "project_id": "proj_newproject"
}

响应示例

返回更新后的设备对象。

错误响应

状态码	错误信息	描述
`400`	项目ID不能为空	未提供目标项目 ID
`400`	项目不存在或不属于当前组织	目标项目无效

获取设备实时数据

获取设备下所有因子的最新数据。

GET /api/v2/projects/{project_id}/devices/{id}/data/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符
`id`	integer/string	是	设备主键或设备 ID

响应示例

json

[
    {
        "agri_id": "d-1000-abcd1234-1-00",
        "value": 25.6,
        "the_type": 100,
        "unit": "℃",
        "t": 1711008140
    },
    {
        "agri_id": "d-1000-abcd1234-1-01",
        "value": 65.2,
        "the_type": 101,
        "unit": "%RH",
        "t": 1711008140
    }
]

响应字段

字段	类型	描述
`agri_id`	string	因子内部标识符
`value`	number	当前数值
`the_type`	integer	因子类型
`unit`	string	数据单位
`t`	integer	数据时间戳（Unix 时间戳，秒）

代码示例

PythoncURL

python

def get_device_data(project_id, device_id):
    """获取设备实时数据"""
    response = requests.get(
        f"{API_BASE}/projects/{project_id}/devices/{device_id}/data/",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    )
    return response.json()

# 调用示例
data = get_device_data("proj_abcdefghij", 16872)
for item in data:
    print(f"{item['agri_id']}: {item['value']} {item.get('unit', '')}")

bash

curl -X GET "https://dl.yengear.com/api/v2/projects/proj_abcdefghij/devices/16872/data/" \
     -H "Authorization: Bearer your_access_token"

重启设备

向设备发送重启命令。

POST /api/v2/projects/{project_id}/devices/{id}/reboot/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符
`id`	integer/string	是	设备主键或设备 ID

响应示例

json

{
    "message": "重启命令已发送"
}

错误响应

状态码	错误信息	描述
`400`	设备不支持重启功能	该设备型号不支持远程重启
`503`	设备离线或网关连接失败	无法连接到设备

注意

重启命令为异步操作，返回成功仅表示命令已发送，不代表设备已完成重启。

代码示例

PythoncURL

python

def reboot_device(project_id, device_id):
    """重启设备"""
    response = requests.post(
        f"{API_BASE}/projects/{project_id}/devices/{device_id}/reboot/",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    )
    return response.json()

# 调用示例
result = reboot_device("proj_abcdefghij", 16872)
print(result["message"])

bash

curl -X POST "https://dl.yengear.com/api/v2/projects/proj_abcdefghij/devices/16872/reboot/" \
     -H "Authorization: Bearer your_access_token"

设备管理 ​

接口概览 ​

设备对象 ​

base_device 对象 ​

获取设备列表 ​

路径参数 ​

响应示例 ​

代码示例 ​

获取设备详情 ​

路径参数 ​

响应示例 ​

错误响应 ​

更新设备 ​

路径参数 ​

请求参数 ​

请求示例 ​

响应示例 ​

代码示例 ​

绑定设备 ​

路径参数 ​

请求参数 ​

请求示例 ​

响应示例 ​

错误响应 ​

代码示例 ​

解绑设备 ​

路径参数 ​

响应 ​

代码示例 ​

移动设备到其他项目 ​

路径参数 ​

请求参数 ​

请求示例 ​

响应示例 ​

错误响应 ​

获取设备实时数据 ​

路径参数 ​

响应示例 ​

响应字段 ​

代码示例 ​

重启设备 ​

路径参数 ​

响应示例 ​

错误响应 ​

代码示例 ​

设备管理

接口概览

设备对象

base_device 对象

获取设备列表

路径参数

响应示例

代码示例

获取设备详情

路径参数

响应示例

错误响应

更新设备

路径参数

请求参数

请求示例

响应示例

代码示例

绑定设备

路径参数

请求参数

请求示例

响应示例

错误响应

代码示例

解绑设备

路径参数

响应

代码示例

移动设备到其他项目

路径参数

请求参数

请求示例

响应示例

错误响应

获取设备实时数据

路径参数

响应示例

响应字段

代码示例

重启设备

路径参数

响应示例

错误响应

代码示例