Skip to content

开放接口文档

开放接口提供了为设备、因子、数据的 RESTful 接口,方便你快速搭建物联网应用。

你也可以直接进入设备管理平台,管理你的设备、因子等。

API 基础信息

  • 基础域名:https://ums.holdingbyte.com
  • API 版本:v2
  • 基础路径:/api/v2/

例如,完整的设备列表接口地址为:https://ums.holdingbyte.com/api/v2/devices/

请求格式

所有请求都应该是 JSON 格式,请在请求头中设置:

Content-Type: application/json

Token 认证

API 支持 token 认证方式,适用于第三方应用或自动化脚本访问 API。需要在请求头中添加 Token:

http
Authorization: Bearer YOUR_ACCESS_TOKEN

注意事项:

  • Token 必须是有效的且未过期
  • Token 必须属于激活状态(is_active=true
  • Token 关联的组织必须有效
  • 如果 Token 设置了过期时间(expires_at),则必须在有效期内

您可以在设备管理平台中管理 Token。

请求示例

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"

响应格式

所有响应都是 JSON 格式,采用统一的响应结构:

成功响应

当请求成功时(HTTP 状态码 200),返回格式如下:

json
{
    "success": true,
    "data": {
        // 响应数据
    },
    "error": null
}

对于列表数据,返回格式如下:

json
{
    "success": true,
    "data": {
        "count": 100,
        "next": "https://ums.holdingbyte.com/api/v2/devices/?page=2",
        "previous": null,
        "results": [
            // 数据列表
        ]
    },
    "error": null
}

错误响应

当请求失败时(HTTP 状态码非 200),返回格式如下:

json
{
    "success": false,
    "data": null,
    "error": {
        "code": "ERROR_CODE",
        "message": "错误信息"
    }
}

常见状态码:

  • 200:请求成功
  • 400:请求参数错误
  • 401:未认证
  • 403:无权限
  • 404:资源不存在
  • 500:服务器内部错误

分页

列表接口支持分页,分页参数:

  • page: 页码,默认为 1
  • page_size: 每页数量,默认为 20

过滤和排序

大部分列表接口支持过滤和排序:

  • 过滤:使用相应的查询参数
  • 排序:使用 ordering 参数,例如 ?ordering=-created_at

请求限制

  • API 采用限流机制,请合理控制请求频率
  • 单个请求体大小限制为 10MB
  • 文件上传大小限制为 50MB