研几科技

Appearance

控制因子 ​

控制因子是指支持远程控制的设备数据点，如开关、继电器等。通过控制因子API，您可以远程控制设备的状态。

开启因子 ​

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

接口说明

将指定设备的指定因子设置为开启状态。

请求参数 ​

参数类型必填说明
device_idinteger是设备ID
factor_idinteger是因子ID

响应 ​

返回数据 (200 OK)

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

响应参数 ​

字段类型说明
messagestring操作结果描述
tokenstring命令令牌，可用于追踪命令执行状态

代码示例 ​

Python
python
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
factor_id = 1

# 开启因子
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"

关闭因子 ​

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

接口说明

将指定设备的指定因子设置为关闭状态。

请求参数 ​

参数类型必填说明
device_idinteger是设备ID
factor_idinteger是因子ID

响应 ​

返回数据 (200 OK)

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

响应参数 ​

字段类型说明
messagestring操作结果描述
tokenstring命令令牌，可用于追踪命令执行状态

代码示例 ​

Python
python
# 关闭因子
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/off/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json"

复制因子 ​

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

接口说明

复制指定的因子配置，创建一个新的因子。新因子的名称会在原因子名称后添加"_copy"后缀，data_index会自动递增。

请求参数 ​

参数类型必填说明
device_idinteger是设备ID
factor_idinteger是要复制的因子ID

响应 ​

返回数据 (200 OK)

json
{
    "success": true,
    "data": {
        "pk": 5856,
        "device": 17644,
        "name": "fe_copy",
        "unit": 1,
        "address": 0,
        "the_type": 200,
        "data_index": 1,
        // 其他因子属性...
        "agri_id": "d-1000-qyjngeufmfqf-1-01"
    },
    "error": null
}

代码示例 ​

Python
python
def copy_factor(device_id, factor_id):
    """复制因子
    
    Args:
        device_id: 设备ID
        factor_id: 要复制的因子ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/factors/{factor_id}/copy/"
    
    response = requests.post(url, headers=headers)
    return response.json()

# 使用示例
device_id = 1
factor_id = 1
result = copy_factor(device_id, factor_id)
print(f"复制的新因子ID: {result['data']['pk']}")
cURL
bash
curl -X POST "https://ums.holdingbyte.com/api/v2/devices/1/factors/1/copy/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json"

错误响应 ​

错误响应

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

错误响应示例

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

注意事项 ​

  1. 只有支持控制的因子（如开关类型）才能使用开启/关闭接口
  2. 控制命令会异步发送到设备，命令执行可能需要一定时间
  3. 可以通过返回的 token 查询命令执行状态