研几科技

Appearance

设备管理 ​

重要提示

设备只能通过 bind & unbind 接口添加到组织，不支持直接创建。

获取设备列表 ​

http
GET /api/v2/devices/

接口说明

获取当前组织的所有设备。

请求参数 ​

参数类型必填说明
searchstring否搜索设备 ID 或描述
groupstring否按分组过滤，使用分组 ID，'none' 表示未分组

响应 ​

返回数据 (200 OK)

json
{
    "success": true,
    "data": [
        {
            "pk": 16872,
            "device_name": "电力监测配电箱",
            "device_id": "xxxx",
            "agri_id": "d-1000-xxxx",
            "group": {
                "pk": 117,
                "name": "对外测试设备"
            },
            "base_device": {
                "pk": 16,
                "name": "智能配电箱",
                "model": "Y101",
                "image": "https://agri-static.holdingbyte.com/media/upload/basedevice/d2d8cab4-30e8-4ee4-8249-992565f5871b.png?x-oss-process=style/thumbnail",
                "property": 0
            },
            "is_debug": false,
            "info": "测试",
            "status": 100,
            "bind_time": "2025-02-13 07:42:50",
            "connect_time": "2025-03-03 06:42:20",
            "create_time": "2024-01-13 12:14:40",
            "uart_info": null,
            "is_online": true,
            "safe_code_check": "6ae6e2a7052d3b0fba43f600da6f3227"
        }
    ]
}

响应参数 ​

字段类型说明
pkinteger设备主键
device_namestring设备名称
device_idstring设备ID
agri_idstring内部ID
groupobject设备分组信息
base_deviceobject基础设备信息
statusinteger设备状态
infostring设备描述
is_debugboolean是否已开启调试模式
is_onlineboolean设备是否在线
bind_timestring设备绑定时间
connect_timestring设备连接时间
create_timestring设备创建时间

代码示例 ​

Python
python
import requests

# 配置
API_BASE = "https://ums.holdingbyte.com/api/v2"
ACCESS_TOKEN = "your_access_token"

def list_devices(search=None, group=None):
    """获取设备列表
    
    Args:
        search: 搜索关键字
        group: 分组ID，'none' 表示未分组
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }
    
    params = {}
    if search:
        params["search"] = search
    if group:
        params["group"] = group
    
    url = f"{API_BASE}/devices/"
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# 使用示例
devices = list_devices(search="配电箱", group="117")
print(f"获取到 {len(devices['data'])} 个设备")
cURL
bash
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/?search=配电箱&group=117" \
     -H "Authorization: Bearer your_access_token"

获取设备详情 ​

http
GET /api/v2/devices/{device_id}/

接口说明

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

响应 ​

返回数据 (200 OK)

json
{
    "success": true,
    "data": {
        "pk": 16872,
        "device_name": "电力监测配电箱",
        "device_id": "xxxx",
        "agri_id": "d-1000-xxxx",
        "group": {
            "pk": 117,
            "name": "对外测试设备"
        },
        "base_device": {
            "pk": 16,
            "name": "智能配电箱",
            "model": "Y101",
            "image": "https://agri-static.holdingbyte.com/media/upload/basedevice/d2d8cab4-30e8-4ee4-8249-992565f5871b.png?x-oss-process=style/thumbnail",
            "property": 0
        },
        "is_debug": false,
        "info": "测试",
        "status": 100,
        "bind_time": "2025-02-13 07:42:50",
        "connect_time": "2025-03-03 06:42:20",
        "create_time": "2024-01-13 12:14:40",
        "uart_info": null,
        "is_online": true,
        "safe_code_check": "6ae6e2a7052d3b0fba43f600da6f3227"
    }
}

代码示例 ​

Python
python
def get_device_detail(device_id):
    """获取设备详情
    
    Args:
        device_id: 设备ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }
    
    url = f"{API_BASE}/devices/{device_id}/"
    response = requests.get(url, headers=headers)
    return response.json()

# 使用示例
device_id = "xxxx"
device = get_device_detail(device_id)
if "data" in device:
    print(f"设备名称: {device['data']['device_name']}")
    print(f"在线状态: {'在线' if device['data']['is_online'] else '离线'}")
cURL
bash
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/xxxx/" \
     -H "Authorization: Bearer your_access_token"

更新设备 ​

http
PUT /api/v2/devices/{device_id}/

接口说明

更新设备的基本信息。

请求参数 ​

参数类型必填说明
device_namestring否设备名称
infostring否设备描述
groupinteger否设备分组ID，0表示取消分组

请求示例 ​

请求数据

json
{
    "device_name": "新的设备名称",
    "info": "新的设备描述",
    "group": 117
}

响应 ​

返回数据 (200 OK)

返回更新后的设备信息，格式同列表项。

代码示例 ​

Python
python
def update_device(device_id, device_name=None, info=None, group=None):
    """更新设备信息
    
    Args:
        device_id: 设备ID
        device_name: 设备名称
        info: 设备描述
        group: 设备分组ID，0表示取消分组
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {}
    if device_name is not None:
        data["device_name"] = device_name
    if info is not None:
        data["info"] = info
    if group is not None:
        data["group"] = group
    
    url = f"{API_BASE}/devices/{device_id}/"
    response = requests.put(url, headers=headers, json=data)
    return response.json()

# 使用示例
device_id = "xxxx"
result = update_device(
    device_id=device_id,
    device_name="新的设备名称",
    info="新的设备描述",
    group=117
)
print(f"设备更新{'成功' if 'data' in result else '失败'}")
cURL
bash
curl -X PUT "https://ums.holdingbyte.com/api/v2/devices/xxxx/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "device_name": "新的设备名称",
         "info": "新的设备描述",
         "group": 117
     }'