因子数据

因子数据是设备各个数据点采集的历史记录，通过因子数据API，您可以查询设备的历史数据。

获取因子数据

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

接口说明

获取指定设备指定因子的历史数据，支持分页和时间范围过滤。

请求参数

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

响应

返回数据 (200 OK)

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

响应参数

字段	类型	说明
total	integer	符合条件的记录总数
data	array	数据记录列表
data[].agri_id	string	因子内部ID
data[].v	number	数据值
data[].t	integer	UTC时间戳（秒）

代码示例

Python

def get_factor_data(device_id, factor_id, page=1, page_size=50, min_timestamp=None):
    """获取因子历史数据
    
    Args:
        device_id: 设备ID
        factor_id: 因子ID
        page: 页码，从1开始，默认1
        page_size: 每页数量，默认50
        min_timestamp: 最小时间戳（秒），只返回该时间戳之后的数据
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }
    
    params = {
        "page": page,
        "page_size": page_size
    }
    
    if min_timestamp:
        params["min_timestamp"] = min_timestamp
    
    url = f"{API_BASE}/devices/{device_id}/factors/{factor_id}/data/"
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# 使用示例
device_id = 1
factor_id = 2
min_timestamp = 1704758400  # 2024-01-09 00:00:00 UTC
data = get_factor_data(device_id, factor_id, min_timestamp=min_timestamp)
print(f"获取到 {data['data']['total']} 条数据记录")

cURL

curl -X GET "https://ums.holdingbyte.com/api/v2/devices/1/factors/2/data/?page=1&page_size=50&min_timestamp=1704758400" \
     -H "Authorization: Bearer your_access_token"

说明

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

提示

t字段为UTC时间戳（秒），可根据需要自行转换为本地时间显示。

通过因子内部ID获取数据

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

接口说明

通过因子的内部ID（agri_id）直接获取因子的历史数据，适用于已知因子内部ID的场景。

请求参数

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

响应

返回数据 (200 OK)

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

响应参数

字段	类型	说明
total	integer	符合条件的记录总数
data	array	数据记录列表
data[].agri_id	string	因子内部ID
data[].v	number	数据值
data[].t	integer	UTC时间戳（秒）

代码示例

Python

def get_factor_data_by_agri_id(factor_agri_id, page=1, page_size=50, min_timestamp=None):
    """通过因子内部ID获取历史数据
    
    Args:
        factor_agri_id: 因子内部ID
        page: 页码，从1开始，默认1
        page_size: 每页数量，默认50
        min_timestamp: 最小时间戳（秒），只返回该时间戳之后的数据
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }
    
    params = {
        "page": page,
        "page_size": page_size
    }
    
    if min_timestamp:
        params["min_timestamp"] = min_timestamp
    
    url = f"{API_BASE}/factors/{factor_agri_id}/data/"
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# 使用示例
factor_agri_id = "DEVICE001-1-00"
min_timestamp = 1704758400  # 2024-01-09 00:00:00 UTC
data = get_factor_data_by_agri_id(factor_agri_id, min_timestamp=min_timestamp)
print(f"获取到 {data['data']['total']} 条数据记录")

cURL

curl -X GET "https://ums.holdingbyte.com/api/v2/factors/DEVICE001-1-00/data/?page=1&page_size=50&min_timestamp=1704758400" \
     -H "Authorization: Bearer your_access_token"

说明

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

错误响应

错误响应

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

错误响应示例

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