在公式表达式中使用时间函数 - AWS IoT SiteWise
在指标中使用时间函数在变换中使用时间函数

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

在公式表达式中使用时间函数

使用时间函数根据数据点的时间戳返回值。

在指标中使用时间函数

仅在指标中，您可以使用以下函数，这些函数根据数据点的时间戳返回值。

时态函数参数必须是来自本地资产模型或嵌套表达式的属性。这意味着您不能在时态函数中使用子资源模型中的属性。

可以在时态函数中使用嵌套表达式。当您使用嵌套表达式时，以下规则将适用：

  • 每个参数都只能有一个变量。

    例如，支持 latest( t*9/5 + 32 )。

  • 参数不能是聚合函数。

    例如，不支持 first( sum(x) )。

函数 描述

first(x)

返回给定变量在当前时间间隔内具有最早时间戳的值。

last(x)

返回给定变量在当前时间间隔内具有最晚时间戳的值。

earliest(x)

返回给定变量在当前时间间隔开始之前的最后一个值。

如果输入属性在其历史记录中具有至少一个数据点，则此函数将计算每个时间间隔的数据点。有关详细信息，请参阅 time-range-defintion。

latest(x)

返回给定变量的最后一个值，其中包含当前时间间隔结束前的最新时间戳。

如果输入属性在其历史记录中具有至少一个数据点，则此函数将计算每个时间间隔的数据点。有关详细信息，请参阅 time-range-defintion。

statetime(x)

返回给定变量在当前时间间隔内为正值的时间（以秒为单位）。您可以使用比较函数创建转换属性，以供 statetime 函数使用。

例如，如果 Idle 属性为 0 或 1，您可以使用以下表达式计算每个时间间隔的闲置时间：IdleTime = statetime(Idle)。有关更多信息，请参阅 statetime 使用情景示例。

此函数不支持将指标属性作为输入变量。

如果输入属性在其历史记录中具有至少一个数据点，则此函数将计算每个时间间隔的数据点。

TimeWeightedAvg(x, [interpolation])

返回输入数据的平均值，使用点之间的时间间隔进行加权。

有关计算和间隔的详细信息，请参阅时间加权函数参数。

可选参数 interpolaton 必须是字符串常量：

  • locf – 这是默认值。该计算使用上次观测到的向前结转计算算法计算数据点之间的间隔。在这种方法中，数据点是作为最后一个观测值计算的，直到下一个输入数据点的时间戳。

    将一个好的数据点之后的值外推为其值，直到下一个数据点的时间戳。

  • linear – 计算使用线性插值计算算法计算数据点之间的间隔。

    两个良好数据点之间的值是通过这些数据点的值之间的线性插值推断出来的。

    良好数据点和不良数据点之间的值或最后一个良好数据点之后的值，将被推断为一个良好数据点。

TimeWeightedStDev(x, [algo])

返回输入数据的标准差，使用点之间的时间间隔进行加权。

有关计算和间隔的详细信息，请参阅时间加权函数参数。

该计算使用上次观测到的向前结转计算算法计算数据点之间的间隔。在这种方法中，数据点是作为最后一个观测值计算的，直到下一个输入数据点的时间戳。权重计算为数据点或窗口边界之间的时间间隔（以秒为单位）。

可选参数 algo 必须是字符串常量：

  • f – 这是默认值。它返回带有频率权重的无偏加权样本方差，其中以秒 TimeWeight 为单位计算。这种算法通常是在标准差下假设的，被称为加权样本的贝塞尔标准差校正。

  • p – 返回有偏差的加权样本方差，也称为总体方差。

以下公式用于计算，其中：

  • Sp = 总体标准差

  • Sf = 频率标准差

  • Xi = 传入数据

  • ωi = 等于以秒为单位的时间间隔的权重

  • μ* = 传入数据的加权平均值

总体标准差方程：

总体标准差方程。

频率标准差方程：

频率标准差方程。

下图显示了如何相对于当前时间间隔 AWS IoT SiteWise 计算时间函数firstlastearliestlatest、、和。

AWS IoT SiteWise 时态函数根据数据点的时间戳返回数据点。
注意

  • 的时间first(x)范围last(x)是（当前窗口开始，当前窗口结束]。

  • 的时间范围latest(x)是（时间开始，当前窗口结束）。

  • 的时间范围earliest(x)是（时间开始，上一个窗口结束）。

时间加权函数参数

为聚合窗口计算的时间加权函数会考虑以下因素：

  • 窗口内的数据点

  • 数据点之间的时间间隔

  • 窗口前的最后一个数据点

  • 窗口之后的第一个数据点（对于某些算法）

术语：

  • 不良数据点 - 任何质量不佳或非数字值的数据点。在窗口结果计算中不考虑这一点。

  • 不良间隔 - 不良数据点之后的间隔。第一个已知数据点之前的间隔也被视为不良间隔。

  • 良好数据点 - 任何具有良好质量和数值的数据点。

注意

  • AWS IoT SiteWise 仅在计算变换和指标时才消耗GOOD质量数据。它会忽略 UNCERTAIN 和 BAD 数据点。

  • 第一个已知数据点之前的间隔被视为不良间隔。请参阅公式表达式教程了解更多信息。

最后一个已知数据点之后的间隔无限期地持续下去，影响所有后续窗口。当新的数据点到达时，该函数会重新计算间隔。

按照上述规则，将计算聚合窗口结果并仅限于窗口边界。默认情况下，只有当整个窗口都是良好间隔时，该函数才会发送窗口结果。

如果窗口良好间隔小于窗口长度，则该函数不会发送窗口。

当影响窗口结果的数据点发生变化时，即使数据点在窗口之外，该函数也会重新计算窗口。

如果输入属性的历史记录中至少有一个数据点，并且计算已启动，则该函数计算每个时间间隔的时间加权聚合函数。

例
statetime 使用情景示例

考虑这样一个使用情景示例，您有一个具有以下属性的资产：

  • Idle – 一个为 0 或 1 的测量值。当该值为时 1，机器处于空闲状态。

  • Idle Time – 一个指标，该指标使用 statetime(Idle) 公式计算机器在每分钟内处于空闲状态的时间（以秒为单位）。

Idle 属性具有以下数据点。

Timestamp 2:00:00 PM 2:00:30 PM 2:01:15 PM 2:02:45 PM 2:04:00 PM
Idle 0 1 1 0 0

AWS IoT SiteWise 根据的值每分钟计算一次Idle Time属性Idle。此计算完成后，Idle Time 属性将具有以下数据点。

Timestamp 2:00:00 PM 2:01:00 PM 2:02:00 PM 2:03:00 PM 2:04:00 PM
Idle Time 不适用 30 60 45 0

AWS IoT SiteWise 在每分钟结束Idle Time时执行以下计算。

  • At 2:00 PM (for 1:59 PM to 2:00 PM)

    • 在 2:00 PM 之前没有 Idle 数据，因此计算不会得出任何数据点。

  • At 2:01 PM (for 2:00 PM to 2:01 PM)

    • 在 2:00:00 PM，机器处于活动状态（Idle 为 0）。

    • 在 2:00:30 PM，机器处于空闲状态（Idle 为 1）。

    • Idle 在 2:01:00 PM 的时间间隔结束之前没有再次变化，因此 Idle Time 是 30 秒。

  • At 2:02 PM (for 2:01 PM to 2:02 PM)

    • 在 2:01:00 PM，机器处于空闲状态（基于 2:00:30 PM 的上一个数据点）。

    • 在 2:01:15 PM，机器仍处于空闲状态。

    • Idle 在 2:02:00 PM 的时间间隔结束之前没有再次变化，因此 Idle Time 是 60 秒。

  • At 2:03 PM (for 2:02 PM to 2:03 PM)

    • 在 2:02:00 PM，机器处于空闲状态（基于 2:01:15 PM 的上一个数据点）。

    • 在 2:02:45 PM，机器处于活动状态。

    • Idle 在 2:03:00 PM 的时间间隔结束之前没有再次变化，因此 Idle Time 是 45 秒。

  • At 2:04 PM (for 2:03 PM to 2:04 PM)

    • 在 2:03:00 PM，机器处于活动状态（基于 2:02:45 PM 的上一个数据点）。

    • Idle 在 2:04:00 PM 的时间间隔结束之前没有再次变化，因此 Idle Time 是 0 秒。

例
示例 TimeWeightedAvg 和 TimeWeightedStDev 场景

下表提供了这些一分钟窗口指标的示例输入和输出：Avg(x), TimeWeightedAvg(x), TimeWeightedAvg(x, "linear"), stDev(x), timeWeightedStDev(x), timeWeightedStDev(x, 'p')。

一分钟聚合窗口的示例输入：

注意

这些数据点都有GOOD质量。

03:00:00 4.0
03:01:00 2.0
03:01:10 8.0
03:01:50 20.0
03:02:00 14.0
03:02:05 10.0
03:02:10 3.0
03:02:30 20.0
03:03:30 0.0

汇总结果输出：

注意

无 – 未生成此窗口的结果。

时间 Avg(x) TimeWeightedAvg(x) TimeWeightedAvg(X, "linear") stDev(X) timeWeightedStDev(x) timeWeightedStDev(x, 'p')
3:00:00 4 无 无 0 无 无
3:01:00 2 4 3 0 0 0
3:02:00 14 9 13 6 5.430610041581775 5.385164807134504
3:03:00 11 13 12.875 8.54400374531753 7.724054437220943 7.659416862050705
3:04:00 0 10 2.5 0 10.084389681792215 10
3:05:00 无 0 0 无 0 0

在变换中使用时间函数

仅在转换中，您可以使用 pretrigger() 函数在启动当前转换计算的属性更新之前，检索变量的 GOOD 质量值。

以一个制造商 AWS IoT SiteWise 用来监控机器状态的例子为例。制造商使用以下测量值和转换来表示过程：

  • 测量值，current_state，可以是 0 或 1。

    • 如果本机处于清洁状态，则 current_state 等于 1。

    • 如果计算机处于制造状态，则 current_state 等于 0。

  • 转换，cleaning_state_duration，等于 if(pretrigger(current_state) == 1, timestamp(current_state) - timestamp(pretrigger(current_state)), none)。此转换以 Unix 纪元格式返回机器处于清洁状态的时间（以秒为单位）。有关更多信息，请参阅 在公式表达式中使用条件函数 时间戳（） 函数。

如果机器处于清洁状态的时间超过预期，制造商可能会对机器进行调查。

您也可以在多变量转换中使用 pretrigger() 函数。例如，您有两个名为 x 和 y 的测量值和一个等于 x + y + pretrigger(y) 的转换 z。下表显示了 x、y 和 z 从上午 9:00 到 9:15 的值。

注意

  • 此示例假设测量值按时间顺序到达。例如，上午 09:00 x 的值在上午 09:05 x 的值之前到达。

  • 如果上午 9:05 的数据点在上午 9:00 的数据点之前到达，则 z 不会在上午 9:05 进行计算。

  • 如果上午 9:05 x 的值在上午 09:00 x 的值之前到达，并且 y 的值按时间顺序到达，则 z 在上午 9:05 等于 22 = 20 + 1 + 1。

09:00 AM 09:05 AM 09:10 AM 09:15 AM

x

10

20

30

y

1

2

3

z = x + y + pretrigger(y)

y 在上午 09:00 之前没有收到任何数据点。因此，z 不是在上午 09:00 计算的。

23 = 20 + 2 + 1

pretrigger(y) 等于 1。

25 = 20 + 3 + 2

x 没有收到新的数据点。pretrigger(y) 等于 2。

36 = 30 + 3 + 3

y 没有收到新的数据点。因此，在上午 09:15 pretrigger(y) 等于 3。