文档中心

Appearance

设备因子 ​

设备因子是设备的数据点配置，用于定义设备的数据采集和控制点。

获取因子列表 ​

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

参数 ​

无

响应 ​

json
{
    "success": true,
    "data": [
        {
            "pk": 1,
            "device": 1,
            "unit": 1,             // slave id
            "address": 0,          // 地址
            "the_type": "temp",    // 设备类型
            "the_type_detail": {   // 设备类型详细信息
                "name": "温度",
                "unit": "℃",
                "icon": "https://ums.holdingbyte.com/media/icon/temp.png"
            },
            "data_endian": "big",          // 大小端
            "data_endian_display": "大端",  // 大小端显示值
            "data_type": "int16",          // 数据值类型
            "data_type_display": "16位整数", // 数据值类型显示值
            "data_index": 0,               // 数据读取索引
            "modbus_type": "holding",      // 数据源类型
            "modbus_type_display": "保持寄存器", // 数据源类型显示值
            "data_factor": 0.1,    // 数据因子
            "data_delta": 0,       // 数据差值
            "info": "温度传感器",   // 备注
            "enabled": true,       // 是否启用
            "agri_id": "DEVICE001-1-00"  // 因子完整ID
        }
    ],
    "error": null
}

获取因子详情 ​

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

参数 ​

无

响应 ​

json
{
    "success": true,
    "data": {
        "pk": 1,
        "device": 1,
        "unit": 1,
        "address": 0,
        "the_type": "temp",
        "the_type_detail": {
            "name": "温度",
            "unit": "℃",
            "icon": "https://ums.holdingbyte.com/media/icon/temp.png"
        },
        "data_endian": "big",
        "data_endian_display": "大端",
        "data_type": "int16",
        "data_type_display": "16位整数",
        "data_index": 0,
        "modbus_type": "holding",
        "modbus_type_display": "保持寄存器",
        "data_factor": 0.1,
        "data_delta": 0,
        "info": "温度传感器",
        "enabled": true,
        "agri_id": "DEVICE001-1-00"
    },
    "error": null
}

创建因子 ​

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

请求参数 ​

参数类型必填说明
unitinteger是Modbus 从站地址
addressinteger是寄存器地址
the_typestring是设备类型
data_endianstring是数据大小端（big/little）
data_typestring是数据类型（如：int16/uint16/float等）
data_indexinteger是数据读取索引
modbus_typestring是Modbus寄存器类型（holding/input/coil/discrete）
data_factorfloat否数据因子，用于数据转换
data_deltafloat否数据差值
infostring否备注信息
enabledboolean否是否启用，默认true

响应 ​

json
{
    "success": true,
    "data": {
        // 返回新创建的因子信息
    },
    "error": null
}

更新因子 ​

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

请求参数 ​

同创建因子

响应 ​

json
{
    "success": true,
    "data": {
        // 返回更新后的因子信息
    },
    "error": null
}

删除因子 ​

http
DELETE /api/v2/devices/{device_id}/factors/{factor_id}/

参数 ​

无

响应 ​

json
{
    "success": true,
    "data": null,
    "error": null
}

控制因子 ​

因子为开关类型时，比如IO控制器、智能配电箱，可以控制该因子的开启、关闭。

开启 ​

http
POST /api/v2/devices/{device_id}/factors/{factor_id}/on/

响应 ​

json
{
    "success": true,
    "data": {
        "message": "操作成功",
        "token": "command_token"
    },
    "error": null
}

示例 ​

Python ​

python
import requests

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

def control_factor(device_id, factor_id, action):
    """控制因子开关
    
    Args:
        device_id: 设备主键ID（整数）
        factor_id: 因子主键ID（整数）
        action: 动作，'on' 或 'off'
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/factors/{factor_id}/{action}/"
    
    response = requests.post(url, headers=headers)
    return response.json()

# 使用示例
device_id = 1  # 设备主键ID
factor_id = 1  # 因子主键ID

# 开启因子
result = control_factor(device_id, factor_id, "on")
print(f"开启结果: {result}")

# 关闭因子
result = control_factor(device_id, factor_id, "off")
print(f"关闭结果: {result}")

cURL ​

bash
# 开启因子
curl -X POST "https://ums.holdingbyte.com/api/v2/devices/1/factors/1/on/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json"

# 关闭因子
curl -X POST "https://ums.holdingbyte.com/api/v2/devices/1/factors/1/off/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json"

关闭 ​

http
POST /api/v2/devices/{device_id}/factors/{factor_id}/off/

响应 ​

json
{
    "success": true,
    "data": {
        "message": "操作成功",
        "token": "command_token"
    },
    "error": null
}

复制因子 ​

http
POST /api/v2/devices/{device_id}/factors/{factor_id}/copy/

参数 ​

无

响应 ​

json
{
    "success": true,
    "data": {
        // 返回复制后的新因子信息，新因子的名称会在原因子名称后添加"_copy"后缀，
        // data_index会自动递增
    },
    "error": null
}

获取因子数据 ​

http
GET /api/v2/devices/{device_id}/factors/{factor_id}/data/

参数 ​

参数类型必填说明
device_idinteger是设备ID
factor_idinteger是因子ID
pageinteger否页码，从1开始，默认1
page_sizeinteger否每页数量，默认50
min_timestampinteger否最小时间戳（秒），只返回该时间戳之后的数据，默认使用数据保留期限制

示例 ​

http
GET /api/v2/devices/1/factors/2/data/?page=1&page_size=50&min_timestamp=1704758400

响应 ​

json
{
    "success": true,
    "data": {
        "total": 100,           // 总记录数
        "data": [
            {
                "agri_id": "DEVICE001-1-00",  // 因子ID
                "v": 25.6,                    // 数值
                "t": 1641715200              // UTC时间戳（秒）
            },
            // ...更多数据
        ]
    },
    "error": null
}

说明 ​

  • 返回指定因子的历史数据，按时间倒序排列
  • 数据保留期为90天
  • 接口有缓存，缓存时间为5分钟

通过因子ID获取数据 ​

http
GET /api/v2/factors/{factor_agri_id}/data/

参数 ​

参数类型必填说明
factor_agri_idstring是因子完整ID，如 "xxxxx-1-00"
pageinteger否页码，从1开始，默认1
page_sizeinteger否每页数量，默认50
min_timestampinteger否最小时间戳（UTC时间，秒），只返回该时间戳之后的数据，默认使用数据保留期限制

示例 ​

http
GET /api/v2/factors/xxxxx-1-00/data/?page=1&page_size=50&min_timestamp=1704758400

响应 ​

json
{
    "success": true,
    "data": {
        "total": 100,           // 总记录数
        "data": [
            {
                "agri_id": "DEVICE001-1-00",  // 因子ID
                "v": 25.6,                    // 数值
                "t": 1641715200              // UTC时间戳（秒）
            },
            // ...更多数据
        ]
    },
    "error": null
}

说明 ​

  • 返回指定因子的历史数据，按时间倒序排列
  • 数据保留期为90天
  • 接口有缓存，缓存时间为5分钟