Holdingbyte

Appearance

设备管理 ​

设备管理 API 提供设备的查询、更新、删除和分组管理功能。注意，设备只能通过 bind 接口添加到组织，不支持直接创建。

获取设备列表 ​

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

请求 ​

http
GET /api/v2/devices/

查询参数 ​

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

响应 ​

json
[
    {
        "id": "device_id",
        "device_id": "设备ID",
        "info": "设备描述",
        "group": {
            "id": "group_id",
            "name": "分组名称"
        },
        "allow": true,
        "bind_time": "2024-01-08T10:00:00Z",
        "create_time": "2024-01-08T10:00:00Z"
    }
]

示例 ​

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}",
        "Content-Type": "application/json"
    }
    
    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()
print("所有设备:", devices)

# 搜索设备
devices = list_devices(search="温度")
print("搜索结果:", devices)

# 获取指定分组的设备
devices = list_devices(group="group_1")
print("分组设备:", devices)

cURL ​

bash
# 获取所有设备
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/" \
     -H "Authorization: Bearer your_access_token"

# 搜索设备
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/?search=温度" \
     -H "Authorization: Bearer your_access_token"

# 获取指定分组的设备
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/?group=group_1" \
     -H "Authorization: Bearer your_access_token"

获取设备详情 ​

获取单个设备的详细信息。

请求 ​

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

响应 ​

返回单个设备信息，格式同列表项。

示例 ​

Python ​

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

# 使用示例
device_id = "device_1"
device = get_device(device_id)
print(f"设备详情: {device}")

cURL ​

bash
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/device_1/" \
     -H "Authorization: Bearer your_access_token"

更新设备信息 ​

更新设备的基本信息。

请求 ​

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

请求参数 ​

字段类型必填说明
infostring否设备描述
groupstring否设备分组ID
allowboolean否是否允许接入

请求示例 ​

json
{
    "info": "新的设备描述",
    "group": "group_id",
    "allow": true
}

响应 ​

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

示例 ​

Python ​

python
def update_device(device_id, info=None, group=None, allow=None):
    """更新设备信息
    
    Args:
        device_id: 设备ID
        info: 设备描述
        group: 分组ID
        allow: 是否允许接入
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {}
    if info is not None:
        data['info'] = info
    if group is not None:
        data['group'] = group
    if allow is not None:
        data['allow'] = allow
    
    url = f"{API_BASE}/devices/{device_id}/"
    response = requests.put(url, headers=headers, json=data)
    return response.json()

# 使用示例
device_id = "device_1"
result = update_device(
    device_id,
    info="温度传感器 #1",
    group="group_1",
    allow=True
)
print(f"更新结果: {result}")

cURL ​

bash
curl -X PUT "https://ums.holdingbyte.com/api/v2/devices/device_1/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"info": "温度传感器 #1", "group": "group_1", "allow": true}'

绑定设备 ​

将设备绑定到当前组织。

请求 ​

http
POST /api/v2/devices/bind/

请求参数 ​

字段类型必填说明
device_idstring是设备ID
safe_codestring是设备安全码

请求示例 ​

json
{
    "device_id": "device_id",
    "safe_code": "safe_code"
}

响应 ​

绑定成功后返回设备信息，格式同列表项。

示例 ​

Python ​

python
def bind_device(device_id, safe_code):
    """绑定设备
    
    Args:
        device_id: 设备ID
        safe_code: 设备安全码
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {
        "device_id": device_id,
        "safe_code": safe_code
    }
    
    url = f"{API_BASE}/devices/bind/"
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# 使用示例
device_id = "device_1"
safe_code = "1234567890"
result = bind_device(device_id, safe_code)
print(f"绑定结果: {result}")

cURL ​

bash
curl -X POST "https://ums.holdingbyte.com/api/v2/devices/bind/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"device_id": "device_1", "safe_code": "1234567890"}'

解绑设备 ​

解除设备与当前组织的绑定关系。

请求 ​

http
POST /api/v2/devices/{device_id}/unbind/

响应 ​

成功解绑返回 204 状态码，无响应内容。

示例 ​

Python ​

python
def unbind_device(device_id):
    """解绑设备
    
    Args:
        device_id: 设备ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/unbind/"
    response = requests.post(url, headers=headers)
    return response.status_code == 204

# 使用示例
device_id = "device_1"
success = unbind_device(device_id)
print(f"解绑{'成功' if success else '失败'}")

cURL ​

bash
curl -X POST "https://ums.holdingbyte.com/api/v2/devices/device_1/unbind/" \
     -H "Authorization: Bearer your_access_token"