设备数据统计服务

更新时间：2025-11-28 06:37:45下载pdf

概述

服务提供获取四种不同时间粒度的设备数据统计接口，可用于设备数据图表可视化，设备数据分析等业务展示：

能耗图表：展示设备能耗、温湿度等。
趋势分析：分析数据变化趋势。
使用统计：统计设备使用时长、次数。
数据对比：对比不同时间段的数据。

使用统计能力需要提交工单开通产品数据统计，请在使用前提交快速工单。

使用方式

在 Podfile 文件中添加依赖，如下所示：

source 'https://github.com/tuya/tuya-pod-specs.git'
platform :ios, '11.0'

target 'Your_Project_Name' do
    # 从涂鸦开发者平台（https://platform.tuya.com）构建和获取 ThingSmartCryption
    # 购买正式版后，需重新在涂鸦开发者平台构建 SDK 并重新集成
    # ./ 代表将 ios_core_sdk.tar.gz 解压之后所在目录与 podfile 同级
    # 若自定义存放目录，可以修改 path 为自定义目录层级
    pod 'ThingSmartCryption', :path =>'./'
    pod 'ThingSmartHomeKit'
    // 扩展 API 
    pod 'ThingSmartBusinessApiExtensionKit'
end

在项目根目录下，执行 pod update 命令。

核心优势

四种时间粒度：15 分钟、小时、天、月，满足各类图表需求。
灵活统计方式：支持求和、最大值、最小值、平均值等 7 种统计类型。
智能数据补全：自动填充空缺数据，保证图表连续性。
开箱即用：极简设计，无需初始化直接调用。

功能概述

四大时间维度数据统计

时间粒度	典型应用	数据点数
15 分钟	实时监控、精细化分析	96 点/天
小时	日内趋势、小时对比	24 点/天
天	周报表、月报表	自定义范围
月	年度报表、长期趋势	自定义范围

七种统计类型（StatType 枚举）

统计类型	枚举值	说明	适用场景
SUM	sum	求和	能耗累计、用量统计
MAX	max	最大值	峰值分析、最高温度
MIN	min	最小值	谷值分析、最低温度
AVG	avg	平均值	平均功率、平均温度
MINUX	minux	差值	增量计算
COUNT	count	次数	开关次数、触发次数
RECENT	recent	最近值	实时状态（仅小时）

接口说明

15 分钟粒度统计获取

功能说明

获取 单日内以 15 分钟为间隔 的设备数据统计，适合 实时监控图表 和 精细化数据分析。

数据特点

每天 96 个数据点（24 小时 × 4）
时间格式：YYYYMMDDhhmm（如：202411130000、202411130015）
适合绘制：折线图、柱状图

/**
 Get 15-minute DP statistics for device

 @param devId Device ID
 @param dpId DP point ID
 @param date Date time, format: 20210601
 @param correction Data correction mode: 0=fill with 0 for missing data, 1=use previous time point data for missing data, 2=fill with # for missing data
 @param type Statistical type, e.g., sum, max, min (lowercase letters)
 @param keepScalaPoint Whether to keep decimal places according to DP point scaling factor, e.g., if scaled by 1000, choosing true will keep 3 decimal places
 @param success Success callback
 @param failure Failure callback
 */
+ (void)get15minDpStatisticWithDevId:(NSString *)devId
                                dpId:(NSString *)dpId
                                date:(NSString *)date
                          correction:(NSUInteger)correction
                                type:(NSString *)type
                      keepScalaPoint:(BOOL)keepScalaPoint
                             success:(void(^)(NSDictionary *retData))success
                             failure:(void(^)(NSError *error))failure;

参数说明

参数	类型	必填	默认值	说明
devId	String	Yes	-	设备 ID（从设备对象获取）
dpId	String	Yes	-	功能点 ID
date	String	Yes	-	查询日期，格式：20241113
type	String	No	“sum”	统计类型，建议使用 StatType 枚举
correction	NSUInteger	No	0	`0` = 补 `0`，`1` = 补前值，`2` = 补 `#`
keepScalaPoint	Boolean	No	false	是否保留小数点
success	successBlock	-	-	成功回调
failure	failureBlock	-	-	失败回调

使用示例

场景：绘制今日用电量 15 分钟级别折线图。

// 获取今日日期
let formatter = DateFormatter()
formatter.dateFormat = "yyyyMMdd"
let today = formatter.string(from: Date())

// 调用 15 分钟粒度统计接口
ThingSmartBusinessRequest.get15minDpStatistic(
    withDevId: deviceId,
    dpId: "101",  // 假设 101 是电量 DP
    date: today,
    correction: 0,  // 无数据时补 0
    type: "sum",
    keepScalaPoint: true,  // 保留小数位
    success: { retData in
        // 解析数据点
        guard let result = retData?["result"] as? [String: String] else { return }
        
        // 绘制图表
        self.drawLineChart(with: result)
    },
    failure: { error in
        print("加载失败: \(error?.localizedDescription ?? "")")
    }
)

返回数据示例

{
  "result": {
    "202411130000": "12.34",
    "202411130015": "11.89",
    "202411130030": "13.45",
    "202411130045": "12.01",
    "202411130100": "14.23",
    "202411130115": "13.67",
    ...
    "202411132345": "10.12"
  },
  "t": 1699862400000,
  "success": true,
  "status": "ok"
}

数据说明

共 96 个时间点（15 分钟 × 96 = 24 小时）
Key：时间戳（YYYYMMDDhhmm）
Value：统计值（字符串格式）

小时粒度统计获取

功能说明

获取 单日内以小时为间隔 的设备数据统计，最常用的图表数据接口。

数据特点

每天 24 个数据点。
时间格式：YYYYMMDDhh（如：2024111300、2024111301）
适合绘制：日内趋势图、柱状对比图

/**
 Get hourly DP statistics for device

 @param devId Device ID
 @param dpId DP point ID
 @param date Date time, format: 20210601
 @param correction Data correction mode: 0=fill with 0 for missing data, 1=use previous time point data for missing data, 2=fill with # for missing data
 @param type Statistical type, e.g., sum, max, min (lowercase letters)
 @param keepScalaPoint Whether to keep decimal places according to DP point scaling factor, e.g., if scaled by 1000, choosing true will keep 3 decimal places
 @param success Success callback
 @param failure Failure callback
 */
+ (void)getHourDpStatisticWithDevId:(NSString *)devId
                               dpId:(NSString *)dpId
                               date:(NSString *)date
                         correction:(NSUInteger)correction
                               type:(NSString *)type
                     keepScalaPoint:(BOOL)keepScalaPoint
                            success:(void(^)(NSDictionary *retData))success
                            failure:(void(^)(NSError *error))failure;

参数说明

参数	类型	必填	默认值	说明
devId	String	Yes	-	设备 ID（从设备对象获取）
dpId	String	Yes	-	功能点 ID
date	String	Yes	-	查询日期，格式：20241113
type	String	No	“sum”	统计类型，建议使用 StatType 枚举
correction	NSUInteger	No	0	`0` = 补 `0`，`1` = 补前值，`2` = 补 `#`
keepScalaPoint	Boolean	No	false	是否保留小数点
success	successBlock	-	-	成功回调
failure	failureBlock	-	-	失败回调

使用示例

场景：绘制今日 24 小时温度曲线。

// 调用小时粒度统计接口
ThingSmartBusinessRequest.getHourDpStatistic(
    withDevId: deviceId,
    dpId: "102",
    date: "20241113",
    correction: 1,  // 用前一个值填充空缺
    type: "avg",  // 温度用平均值
    keepScalaPoint: true,
    success: { retData in
        // 解析并绘制温度曲线
        guard let result = retData?["result"] as? [String: String] else { return }
        
        self.drawTemperatureChart(with: result)
    },
    failure: { error in
        print("加载失败: \(error?.localizedDescription ?? "")")
    }
)

返回数据示例

{
  "result": {
    "2024111300": "22.5",
    "2024111301": "22.3",
    "2024111302": "22.1",
    ...
    "2024111323": "21.8"
  },
  "t": 1699862400000,
  "success": true,
  "status": "ok"
}

天粒度统计数据获取

功能说明

获取 指定日期范围内以天为间隔 的设备数据统计，适合 周报表、月报表。

数据特点

可查询任意天数范围
时间格式：YYYYMMDD（如：20241101、20241102）
适合绘制：周趋势图、月对比图

/**
 Get daily DP statistics for device

 @param devId Device ID
 @param dpId DP point ID
 @param startDay Start date, format: 20210601
 @param endDay End date, format: 20210605
 @param correction Data correction mode: 0=fill with 0 for missing data, 1=use previous time point data for missing data, 2=fill with # for missing data
 @param type Statistical type, e.g., sum, max, min (lowercase letters)
 @param keepScalaPoint Whether to keep decimal places according to DP point scaling factor, e.g., if scaled by 1000, choosing true will keep 3 decimal places
 @param success Success callback
 @param failure Failure callback
 */
+ (void)getDayDpStatisticWithDevId:(NSString *)devId
                              dpId:(NSString *)dpId
                          startDay:(NSString *)startDay
                            endDay:(NSString *)endDay
                        correction:(NSUInteger)correction
                              type:(NSString *)type
                    keepScalaPoint:(BOOL)keepScalaPoint
                           success:(void(^)(NSDictionary *retData))success
                           failure:(void(^)(NSError *error))failure;

参数说明

参数	类型	必填	默认值	说明
devId	String	Yes	-	设备 ID（从设备对象获取）
dpId	String	Yes	-	功能点 ID
startDay	String	Yes	-	格式：YYYYMMDD
endDay	String	Yes	-	格式：YYYYMMDD
type	String	No	“sum”	统计类型，建议使用 StatType 枚举
correction	NSUInteger	No	0	`0` = 补 `0`，`1` = 补前值，`2` = 补 `#`
keepScalaPoint	Boolean	No	false	是否保留小数点
success	successBlock	-	-	成功回调
failure	failureBlock	-	-	失败回调

使用示例

场景：绘制本周 7 天用电量柱状图。

// 计算日期范围
let formatter = DateFormatter()
formatter.dateFormat = "yyyyMMdd"

let today = Date()
let endDay = formatter.string(from: today)

let weekAgo = today.addingTimeInterval(-6 * 24 * 60 * 60)
let startDay = formatter.string(from: weekAgo)

// 调用天粒度统计接口
ThingSmartBusinessRequest.getDayDpStatistic(
    withDevId: deviceId,
    dpId: "101",
    startDay: startDay,  // 7 天前
    endDay: endDay,  // 今天
    correction: 0,
    type: "sum",
    keepScalaPoint: true,
    success: { retData in
        // 解析周数据
        guard let resultDict = retData?["result"] as? [String: Any],
              let result = resultDict["result"] as? [String: String] else { return }
        
        self.drawWeeklyBarChart(with: result)
    },
    failure: { error in
        print("加载周数据失败: \(error?.localizedDescription ?? "")")
    }
)

返回数据示例

{
  "result": {
    "result": {
      "20241107": "45.67",
      "20241108": "52.34",
      "20241109": "48.90",
      "20241110": "51.23",
      "20241111": "49.56",
      "20241112": "53.78",
      "20241113": "47.89"
    },
    "min": "20241113"
  },
  "t": 1699862400000,
  "success": true,
  "status": "ok"
}

月粒度统计数据获取

功能说明

获取 指定月份范围内以月为间隔 的设备数据统计，适合 年度报表、长期趋势分析。

数据特点

可查询任意月份范围
时间格式：YYYYMM（如：202401、202402）
适合绘制：年度趋势图、月度对比图

/**
 Get monthly DP statistics for device

 @param devId Device ID
 @param dpId DP point ID
 @param startMonth Start month, format: 202105
 @param endMonth End month, format: 202107
 @param correction Data correction mode: 0=fill with 0 for missing data, 1=use previous time point data for missing data, 2=fill with # for missing data
 @param type Statistical type, e.g., sum, max, min (lowercase letters)
 @param keepScalaPoint Whether to keep decimal places according to DP point scaling factor, e.g., if scaled by 1000, choosing true will keep 3 decimal places
 @param success Success callback
 @param failure Failure callback
 */
+ (void)getMonthDpStatisticWithDevId:(NSString *)devId
                                dpId:(NSString *)dpId
                          startMonth:(NSString *)startMonth
                            endMonth:(NSString *)endMonth
                          correction:(NSUInteger)correction
                                type:(NSString *)type
                      keepScalaPoint:(BOOL)keepScalaPoint
                             success:(void(^)(NSDictionary *retData))success
                             failure:(void(^)(NSError *error))failure;

参数说明

参数	类型	必填	默认值	说明
devId	String	Yes	-	设备 ID（从设备对象获取）
dpId	String	Yes	-	功能点 ID
startMonth	String	Yes	-	格式：YYYYMM
endMonth	String	Yes	-	格式：YYYYMM
type	String	No	“sum”	统计类型，建议使用 StatType 枚举
correction	NSUInteger	No	0	`0` = 补 `0`，`1` = 补前值，`2` = 补 `#`
keepScalaPoint	Boolean	No	false	是否保留小数点
success	successBlock	-	-	成功回调
failure	failureBlock	-	-	失败回调

使用示例

场景：绘制今年 12 个月用电量对比图。

// 获取当前年份
let calendar = Calendar.current
let currentYear = calendar.component(.year, from: Date())

let startMonth = String(format: "%d01", currentYear)
let endMonth = String(format: "%d12", currentYear)

// 调用月粒度统计接口
ThingSmartBusinessRequest.getMonthDpStatistic(
    withDevId: deviceId,
    dpId: "101",
    startMonth: startMonth,
    endMonth: endMonth,
    correction: 0,
    type: "sum",
    keepScalaPoint: true,
    success: { retData in
        // 解析年度数据
        guard let resultDict = retData?["result"] as? [String: Any],
              let result = resultDict["result"] as? [String: String] else { return }
        
        self.drawYearlyChart(with: result)
    },
    failure: { error in
        print("加载年度数据失败: \(error?.localizedDescription ?? "")")
    }
)

返回数据示例

{
  "result": {
    "result": {
      "202401": "1234.56",
      "202402": "1156.78",
      "202403": "1289.90",
      "202404": "1345.67",
      "202405": "1298.45",
      "202406": "1423.89",
      "202407": "1567.23",
      "202408": "1489.01",
      "202409": "1376.54",
      "202410": "1298.76",
      "202411": "1234.00",
      "202412": "0"
    },
    "min": "202412"
  },
  "t": 1699862400000,
  "success": true,
  "status": "ok"
}

上一篇业务 API 扩展

下一篇UI 业务包