设备因子

设备因子是设备的数据点配置，用于定义设备的数据采集和控制点。通过因子API，您可以创建、查询、更新和删除设备的因子配置。

获取因子列表

http

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

接口说明

获取指定设备的所有因子配置。

请求参数

参数	类型	必填	说明
`device_id`	integer	是	设备ID

响应

返回数据 (200 OK)

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
}

响应参数

字段	类型	说明
`pk`	integer	因子主键ID
`device`	integer	设备ID
`name`	string	因子名称
`unit`	integer	Modbus 从站地址
`address`	integer	寄存器地址
`the_type`	integer	因子类型，请参考因子类型定义
`the_type_detail`	object	因子类型详情
`data_endian`	string	数据大小端（big/little）
`data_endian_display`	string	数据大小端显示名称
`data_type`	string	数据类型（如：int8/int16/float等）
`data_type_display`	string	数据类型显示名称
`data_index`	integer	数据读取索引
`modbus_type`	integer	Modbus寄存器类型
`modbus_type_display`	string	Modbus寄存器类型显示名称
`data_factor`	float	数据因子，用于数据转换
`data_delta`	float	数据差值
`info`	string	备注信息
`enabled`	boolean	是否启用
`agri_id`	string	因子内部ID

代码示例

Python

python

def get_device_factors(device_id):
    """获取设备的所有因子
    
    Args:
        device_id: 设备ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }
    
    url = f"{API_BASE}/devices/{device_id}/factors/"
    response = requests.get(url, headers=headers)
    return response.json()

# 使用示例
device_id = 1
factors = get_device_factors(device_id)
print(f"设备有 {len(factors['data'])} 个因子")

cURL

bash

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

获取因子详情

http

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

接口说明

获取指定设备的指定因子详细配置。

请求参数

参数	类型	必填	说明
`device_id`	integer	是	设备ID
`factor_id`	integer	是	因子ID

响应

返回数据 (200 OK)

json

{
    "success": true,
    "data": {
        "pk": 1,
        "device": 1,
        "name": "温度",
        "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
}

代码示例

Python

python

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

# 使用示例
device_id = 1
factor_id = 1
factor = get_factor_detail(device_id, factor_id)
print(f"因子名称: {factor['data']['name']}")

cURL

bash

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

创建因子

http

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

接口说明

为指定设备创建新的因子配置。

请求参数

参数	类型	必填	说明
`name`	string	是	因子名称
`unit`	integer	是	Modbus 从站地址
`address`	integer	是	寄存器地址
`the_type`	string	是	设备类型
`data_endian`	string	是	数据大小端（big/little）
`data_type`	string	是	数据类型（如：int16/uint16/float等）
`data_index`	integer	是	数据读取索引
`modbus_type`	string	是	Modbus寄存器类型（holding/input/coil/discrete）
`data_factor`	float	否	数据因子，用于数据转换，默认为1.0
`data_delta`	float	否	数据差值，默认为0.0
`info`	string	否	备注信息
`enabled`	boolean	否	是否启用，默认true

请求示例

请求数据

json

{
    "name": "温度传感器",
    "unit": 1,
    "address": 0,
    "the_type": "temp",
    "data_endian": "big",
    "data_type": "int16",
    "data_index": 0,
    "modbus_type": "holding",
    "data_factor": 0.1,
    "data_delta": 0,
    "info": "温度传感器",
    "enabled": true
}

响应

返回数据 (200 OK)

json

{
    "success": true,
    "data": {
        "pk": 1,
        "device": 1,
        "name": "温度传感器",
        "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
}

代码示例

Python

python

def create_factor(device_id, factor_data):
    """创建新因子
    
    Args:
        device_id: 设备ID
        factor_data: 因子配置数据
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/factors/"
    response = requests.post(url, headers=headers, json=factor_data)
    return response.json()

# 使用示例
device_id = 1
factor_data = {
    "name": "温度传感器",
    "unit": 1,
    "address": 0,
    "the_type": "temp",
    "data_endian": "big",
    "data_type": "int16",
    "data_index": 0,
    "modbus_type": "holding",
    "data_factor": 0.1,
    "data_delta": 0,
    "info": "温度传感器",
    "enabled": True
}
result = create_factor(device_id, factor_data)
print(f"创建的因子ID: {result['data']['pk']}")

cURL

bash

curl -X POST "https://ums.holdingbyte.com/api/v2/devices/1/factors/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "name": "温度传感器",
         "unit": 1,
         "address": 0,
         "the_type": "temp",
         "data_endian": "big",
         "data_type": "int16",
         "data_index": 0,
         "modbus_type": "holding",
         "data_factor": 0.1,
         "data_delta": 0,
         "info": "温度传感器",
         "enabled": true
     }'

更新因子

http

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

接口说明

更新指定设备的指定因子配置。

请求参数

参数	类型	必填	说明
`name`	string	否	因子名称
`unit`	integer	否	Modbus 从站地址
`address`	integer	否	寄存器地址
`the_type`	string	否	设备类型
`data_endian`	string	否	数据大小端（big/little）
`data_type`	string	否	数据类型（如：int16/uint16/float等）
`data_index`	integer	否	数据读取索引
`modbus_type`	string	否	Modbus寄存器类型（holding/input/coil/discrete）
`data_factor`	float	否	数据因子，用于数据转换
`data_delta`	float	否	数据差值
`info`	string	否	备注信息
`enabled`	boolean	否	是否启用

请求示例

请求数据

json

{
    "name": "更新后的温度传感器",
    "info": "更新后的备注信息"
}

响应

返回数据 (200 OK)

json

{
    "success": true,
    "data": {
        "pk": 1,
        "device": 1,
        "name": "更新后的温度传感器",
        // 其他字段...
        "info": "更新后的备注信息",
        "enabled": true,
        "agri_id": "DEVICE001-1-00"
    },
    "error": null
}

代码示例

Python

python

def update_factor(device_id, factor_id, factor_data):
    """更新因子
    
    Args:
        device_id: 设备ID
        factor_id: 因子ID
        factor_data: 要更新的因子数据
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/factors/{factor_id}/"
    response = requests.put(url, headers=headers, json=factor_data)
    return response.json()

# 使用示例
device_id = 1
factor_id = 1
update_data = {
    "name": "更新后的温度传感器",
    "info": "更新后的备注信息"
}
result = update_factor(device_id, factor_id, update_data)
print(f"更新结果: {result['success']}")

cURL

bash

curl -X PUT "https://ums.holdingbyte.com/api/v2/devices/1/factors/1/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "name": "更新后的温度传感器",
         "info": "更新后的备注信息"
     }'

删除因子

http

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

接口说明

删除指定设备的指定因子配置。

请求参数

参数	类型	必填	说明
`device_id`	integer	是	设备ID
`factor_id`	integer	是	因子ID

响应

返回数据 (200 OK)

json

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

代码示例

Python

python

def delete_factor(device_id, factor_id):
    """删除因子
    
    Args:
        device_id: 设备ID
        factor_id: 因子ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }
    
    url = f"{API_BASE}/devices/{device_id}/factors/{factor_id}/"
    response = requests.delete(url, headers=headers)
    return response.json()

# 使用示例
device_id = 1
factor_id = 1
result = delete_factor(device_id, factor_id)
print(f"删除结果: {result['success']}")

cURL

bash

curl -X DELETE "https://ums.holdingbyte.com/api/v2/devices/1/factors/1/" \
     -H "Authorization: Bearer your_access_token"

控制因子

因子为开关类型时，比如IO控制器、智能配电箱，可以控制该因子的开启、关闭。详细信息请参阅控制因子文档。

获取因子数据

获取因子的历史数据记录，详细信息请参阅因子数据文档。

错误响应

因子API可能返回的错误响应遵循统一的格式。有关详细的错误码和处理方法，请参阅API错误响应文档。

错误响应示例

json

{
    "success": false,
    "data": null,
    "error": {
        "code": 404,
        "message": "因子不存在"
    }
}

设备因子 ​

获取因子列表 ​

请求参数 ​

响应 ​

响应参数 ​

代码示例 ​

获取因子详情 ​

请求参数 ​

响应 ​

代码示例 ​

创建因子 ​

请求参数 ​

请求示例 ​

响应 ​

代码示例 ​

更新因子 ​

请求参数 ​

请求示例 ​

响应 ​

代码示例 ​

删除因子 ​

请求参数 ​

响应 ​

代码示例 ​

控制因子 ​

获取因子数据 ​

错误响应 ​

设备因子

获取因子列表

请求参数

响应

响应参数

代码示例

获取因子详情

请求参数

响应

代码示例

创建因子

请求参数

请求示例

响应

代码示例

更新因子

请求参数

请求示例

响应

代码示例

删除因子

请求参数

响应

代码示例

控制因子

获取因子数据

错误响应