研几科技

Appearance

因子管理 ​

因子是设备的数据采集点或控制点。每个因子定义了如何读取传感器数据或控制执行器。

接口概览 ​

方法端点描述
GET/projects/{project_id}/devices/{device_id}/factors/获取因子列表
GET/projects/{project_id}/devices/{device_id}/factors/{id}/获取因子详情
POST/projects/{project_id}/devices/{device_id}/factors/创建因子
PUT/projects/{project_id}/devices/{device_id}/factors/{id}/更新因子
DELETE/projects/{project_id}/devices/{device_id}/factors/{id}/删除因子
POST.../factors/{id}/set-threshold/设置阈值
GET.../factors/{id}/current-data/获取实时数据

因子对象 ​

字段类型描述
idinteger因子 ID
agri_idstring因子内部标识符
namestring因子名称
unitintegerModbus 从站地址
addressinteger寄存器地址
data_indexinteger数据索引
the_typeinteger因子类型，参见因子类型
modbus_typeintegerModbus 功能码
data_typestring数据类型
data_endianstring字节序
data_factorfloat缩放系数
data_deltafloat偏移量
min_valuefloat最小阈值
max_valuefloat最大阈值
enabledboolean是否启用

获取因子列表 ​

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

响应示例 ​

json
{
    "success": true,
    "data": [
        {
            "id": 5853,
            "agri_id": "d-1000-qyjngeufmfqf-100-00",
            "device_id": 17644,
            "name": "Temperature",
            "unit": 100,
            "address": 0,
            "the_type": 100,
            "the_type_detail": {
                "the_type": 100,
                "name": "温度传感器",
                "unit": "℃"
            },
            "data_endian": ">",
            "data_type": "int16",
            "data_index": 0,
            "modbus_type": 3,
            "data_factor": 0.1,
            "data_delta": 0.0,
            "min_value": null,
            "max_value": null,
            "enabled": true
        }
    ],
    "error": null
}
bash
curl https://dl.yengear.com/api/v2/projects/proj_abc/devices/123/factors/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-Slug: your-org-slug"
python
response = requests.get(
    f"{API_BASE}/projects/{project_id}/devices/{device_id}/factors/",
    headers=headers  # 包含 Authorization 和 X-Organization-Slug
)

创建因子 ​

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

请求参数 ​

参数类型必填描述
namestring是因子名称
unitinteger是Modbus 从站地址
addressinteger是寄存器地址
data_indexinteger是数据索引
the_typeinteger是因子类型
modbus_typeinteger是Modbus 功能码
data_typestring是数据类型
data_endianstring是字节序
data_factorfloat否缩放系数，默认 1.0
data_deltafloat否偏移量，默认 0
enabledboolean否是否启用，默认 true

请求示例 ​

json
{
    "name": "温度",
    "unit": 1,
    "address": 0,
    "data_index": 0,
    "the_type": 2001,
    "modbus_type": 3,
    "data_type": "int16",
    "data_endian": ">",
    "data_factor": 0.1
}

成功返回 201 Created 和因子对象。

注意

只有支持自定义因子的设备才能创建因子。

更新因子 ​

PUT /api/v2/projects/{project_id}/devices/{device_id}/factors/{id}/

支持部分更新，只需提供要修改的字段。

json
{
    "name": "室内温度",
    "data_factor": 0.01
}

删除因子 ​

DELETE /api/v2/projects/{project_id}/devices/{device_id}/factors/{id}/

成功返回 204 No Content。

设置阈值 ​

为因子设置告警阈值。数据超出范围时触发告警。

POST /api/v2/projects/{project_id}/devices/{device_id}/factors/{id}/set-threshold/

请求参数 ​

参数类型必填描述
min_valuefloat否最小阈值
max_valuefloat否最大阈值
json
{
    "min_value": 10.0,
    "max_value": 35.0
}

提示

设置为 null 可清除阈值。

获取实时数据 ​

GET /api/v2/projects/{project_id}/devices/{device_id}/factors/{id}/current-data/

响应示例 ​

json
{
    "agri_id": "d-1000-abc123-1-00",
    "value": 25.6,
    "t": 1711008140
}

相关文档 ​