研几科技·文档中心

Appearance

设备因子 ​

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

获取因子列表 ​

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

参数 ​

无

响应 ​

json
{
    "success": true,
    "data": [
        {
            "pk": 5855,
            "device": 17644,
            "name": "fe",
            "unit": 1,
            "address": 0,
            "the_type": 200,
            "the_type_detail": {
                "name": "远程开关",
                "unit": "",
                "icon": "https://agri-static.holdingbyte.com/media/icon/200.png"
            },
            "data_endian": ">",
            "data_endian_display": "Big-Endian (ABCD)",
            "data_type": "int8",
            "data_type_display": "8-bit Integer",
            "data_index": 0,
            "modbus_type": 1,
            "modbus_type_display": "Coil",
            "data_factor": 1.0,
            "data_delta": 0.0,
            "info": "",
            "enabled": true,
            "agri_id": "d-1000-qyjngeufmfqf-1-00"
        }
    ],
    "error": null
}

字段说明

字段类型说明
pkinteger因子主键ID
agri_idstring因子内部ID
namestring因子名称
unitintegerModbus 从站地址
addressinteger寄存器地址
the_typeinteger因子类型，请参考 因子类型定义
data_endianstring数据大小端（big/little）
data_typestring数据类型（如：int8/int16/float等）
data_indexinteger数据读取索引
modbus_typeintegerModbus寄存器类型
data_factorfloat数据因子，用于数据转换
data_deltafloat数据差值
infostring备注信息
enabledboolean是否启用

获取因子详情 ​

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分钟