跳到主要内容

时间序列数据

某些设备参数支持获取时间序列数据。可以通过检查其 properties 数组中是否包含 "time_series" 或 "simple_ts" 来识别这些参数。当某个设备参数具有这些属性时，表示该参数为时间序列参数，可通过专用方法访问历史数据。

如何识别时间序列参数​

要检查某个参数是否支持时间序列数据，请查看其 properties 数组：

try {
  const response = await userInstance.getUserNodes();
  const node = response.nodes[0];
  const nodeConfig = node.nodeConfig || await node.getNodeConfig();
  
  // 检查设备参数是否支持时间序列
  nodeConfig.devices.forEach((device) => {
    device.params?.forEach((param) => {
      if (param.properties && (
        param.properties.includes("time_series") || 
        param.properties.includes("simple_ts")
      )) {
        console.log(`Device parameter ${param.name} supports time series data`);
        // 此参数可使用 getRawTSData、getSimpleTSData 或 getTSData
      }
    });
  });
} catch (error) {
  console.error("Error checking time series parameters:", error);
}

获取时间序列数据​

时间序列参数支持三种获取历史数据的方法：

  1. getRawTSData - 以分页形式获取未聚合的原始时间序列数据。
  2. getSimpleTSData - 以基础分页方式获取简单时间序列数据。
  3. getTSData - 获取具备高级聚合选项的时间序列数据。

例程：使用 getRawTSData​

getRawTSData 方法以分页格式返回原始时间序列数据。该方法在内部使用带原始聚合的 getTSData。

try {
  const response = await userInstance.getUserNodes();
  const node = response.nodes[0];
  const nodeConfig = node.nodeConfig || await node.getNodeConfig();
  
  // 找到一个支持时间序列的设备参数
  const device = nodeConfig.devices[0];
  const timeSeriesParam = device.params.find(
    param => param.properties && (
      param.properties.includes("time_series") || 
      param.properties.includes("simple_ts")
    )
  );
  
  if (timeSeriesParam) {
    const request = {
      startTime: Date.now() - 7 * 24 * 60 * 60 * 1000, // 7 天前
      endTime: Date.now(),
      resultCount: 100,
      descOrder: false,
      timezone: "America/Los_Angeles"
    };
    
    let tsResponse = await timeSeriesParam.getRawTSData(request);
    console.log("Time series data:", tsResponse.tsData);
    
    // 处理分页
    while (tsResponse.hasNext) {
      tsResponse = await tsResponse.fetchNext();
      console.log("Next page of data:", tsResponse.tsData);
    }
  }
} catch (error) {
  console.error("Error fetching raw time series data:", error);
}

例程：使用 getSimpleTSData​

getSimpleTSData 方法以基础分页方式获取简单时间序列数据，适合简单直接的时间序列查询。

try {
  const response = await userInstance.getUserNodes();
  const node = response.nodes[0];
  const nodeConfig = node.nodeConfig || await node.getNodeConfig();
  
  const device = nodeConfig.devices[0];
  const timeSeriesParam = device.params.find(
    param => param.properties && param.properties.includes("simple_ts")
  );
  
  if (timeSeriesParam) {
    const request = {
      startTime: Date.now() - 24 * 60 * 60 * 1000, // 24 小时前
      endTime: Date.now(),
      resultCount: 50
    };
    
    let tsResponse = await timeSeriesParam.getSimpleTSData(request);
    
    // 处理时间序列数据点
    tsResponse.tsData.forEach((dataPoint) => {
      console.log(`Timestamp: ${new Date(dataPoint.timestamp)}, Value: ${dataPoint.value}`);
    });
    
    // 如果有更多数据则继续获取
    while (tsResponse.hasNext) {
      tsResponse = await tsResponse.fetchNext();
      tsResponse.tsData.forEach((dataPoint) => {
        console.log(`Timestamp: ${new Date(dataPoint.timestamp)}, Value: ${dataPoint.value}`);
      });
    }
  }
} catch (error) {
  console.error("Error fetching simple time series data:", error);
}

例程：结合聚合使用 getTSData​

getTSData 方法提供用于时间序列数据分析的高级聚合选项。

try {
  const response = await userInstance.getUserNodes();
  const node = response.nodes[0];
  const nodeConfig = node.nodeConfig || await node.getNodeConfig();
  
  const device = nodeConfig.devices[0];
  const timeSeriesParam = device.params.find(
    param => param.properties && param.properties.includes("time_series")
  );
  
  if (timeSeriesParam) {
    const request = {
      startTime: Date.now() - 30 * 24 * 60 * 60 * 1000, // 30 天前
      endTime: Date.now(),
      aggregate: "avg", // 聚合方式：avg、sum、min、max、count
      aggregationInterval: "day", // 时间粒度：hour、day、week、month
      numIntervals: 30,
      resultCount: 100,
      timezone: "America/Los_Angeles",
      descOrder: false
    };
    
    let tsResponse = await timeSeriesParam.getTSData(request);
    console.log("Aggregated time series data:", tsResponse.tsData);
    
    // 处理聚合数据
    tsResponse.tsData.forEach((dataPoint) => {
      const date = new Date(dataPoint.timestamp);
      console.log(`Date: ${date.toLocaleDateString()}, Average Value: ${dataPoint.value}`);
    });
  }
} catch (error) {
  console.error("Error fetching aggregated time series data:", error);
}

时间序列数据请求接口​

ESPRawTSDataRequest​

原始时间序列数据请求参数的接口。

参数类型说明
startTime数字时间序列数据查询的起始时间戳（以毫秒为单位的 Unix 时间戳）。
endTime数字时间序列数据查询的结束时间戳（以毫秒为单位的 Unix 时间戳）。
resultCount?数字每页返回的结果数量。
descOrder?布尔值是否按降序返回结果（最新数据在前）。
differential?布尔值是否返回差分值。
resetOnNegative?布尔值是否在出现负值时重置。
timezone?字符串查询的时区（例如 “America/Los_Angeles”）。

ESPSimpleTSDataRequest​

简单时间序列数据请求参数的接口。

参数类型说明
startTime*数字时间序列数据查询的起始时间戳（以毫秒为单位的 Unix 时间戳）。
endTime*数字时间序列数据查询的结束时间戳（以毫秒为单位的 Unix 时间戳）。
resultCount?数字每页返回的结果数量。

ESPTSDataRequest​

带聚合选项的时间序列数据请求参数接口。扩展自 ESPRawTSDataRequest。

参数类型说明
startTime?数字时间序列数据查询的起始时间戳（以毫秒为单位的 Unix 时间戳）。
endTime?数字时间序列数据查询的结束时间戳（以毫秒为单位的 Unix 时间戳）。
resultCount?数字每页返回的结果数量。
aggregate?ESPAggregationMethod聚合方式："avg"、"sum"、"min"、"max"、"count"。
aggregationInterval?ESPAggregationInterval聚合间隔："hour"、"day"、"week"、"month"。
numIntervals?数字聚合的区间数量。
descOrder?布尔值是否按降序返回结果。
differential?布尔值是否返回差分值。
resetOnNegative?布尔值是否在出现负值时重置。
timezone?字符串查询的时区。
weekStart?ESPWeekStart用于每周聚合的周起始日。

时间序列数据响应​

所有时间序列数据方法都会返回一个 ESPSimpleTSDataResponse 对象：

属性类型说明
tsDataESPTSData[]时间序列数据点数组。
hasNextboolean指示是否还有更多数据可用。
fetchNext?() => Promise<ESPSimpleTSDataResponse>获取下一页数据的函数。

每个 ESPTSData 对象包含：

属性类型说明
timestampnumber以毫秒为单位的 Unix 时间戳。
valuestring | number | boolean此时间点对应的值。
备注
  • 时间序列数据方法仅适用于 properties 数组中包含 "time_series" 或 "simple_ts" 的设备参数（ESPRMDeviceParam）。
  • 所有时间序列数据方法均通过 hasNext 和 fetchNext() 支持分页。
  • 时间戳为 Unix 毫秒格式。

On this page