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

# 在公式表达式中使用时间函数
<a name="expression-temporal-functions"></a>

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

## 在指标中使用时间函数
<a name="temporal-functions-in-metrics"></a>

仅在[指标](metrics.md)中，您可以使用以下函数，这些函数根据数据点的时间戳返回值。

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

可以在时态函数中使用嵌套表达式。当您使用嵌套表达式时，以下规则将适用：
+ 每个参数都只能有一个变量。

  例如，支持 `latest( t*9/5 + 32 )`。
+ 参数不能是聚合函数。

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


| 函数 | 说明 | 
| --- | --- | 
|  `first(x)`  |  返回给定变量在当前时间间隔内具有最早时间戳的值。  | 
|   `last(x)` |  返回给定变量在当前时间间隔内具有最晚时间戳的值。  | 
|  `earliest(x)`  |  返回给定变量在当前时间间隔开始之前的最后一个值。 如果输入属性在其历史记录中具有至少一个数据点，则此函数将计算每个时间间隔的数据点。有关详细信息，请参阅 [time-range-defintion](#time-range-def)。  | 
|   `latest(x)` |  返回给定变量在当前时间间隔结束之前具有最晚时间戳的最后一个值。 如果输入属性在其历史记录中具有至少一个数据点，则此函数将计算每个时间间隔的数据点。有关详细信息，请参阅 [time-range-defintion](#time-range-def)。  | 
|   `statetime(x)`  |  返回给定变量在当前时间间隔内为正值的时间（以秒为单位）。您可以使用[比较函数](expression-comparison-functions.md)创建转换属性，以供 `statetime` 函数使用。 例如，如果 `Idle` 属性为 `0` 或 `1`，您可以使用以下表达式计算每个时间间隔的闲置时间：`IdleTime = statetime(Idle)`。有关更多信息，请参阅 [statetime 使用情景示例](#statetime-example)。 此函数不支持将指标属性作为输入变量。 如果输入属性在其历史记录中具有至少一个数据点，则此函数将计算每个时间间隔的数据点。  | 
|   `TimeWeightedAvg(x, [interpolation])`  | 返回输入数据的平均值，使用点之间的时间间隔进行加权。有关计算和间隔的详细信息，请参阅[时间加权函数参数](#timeweighted-parameter)。可选参数 `interpolaton` 必须是字符串常量：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/expression-temporal-functions.html) | 
|   `TimeWeightedStDev(x, [algo])`  |  返回输入数据的标准差，使用点之间的时间间隔进行加权。 有关计算和间隔的详细信息，请参阅[时间加权函数参数](#timeweighted-parameter)。  该计算使用上次观测到的向前结转计算算法计算数据点之间的间隔。在这种方法中，数据点是作为最后一个观测值计算的，直到下一个输入数据点的时间戳。权重计算为数据点或窗口边界之间的时间间隔（以秒为单位）。 可选参数 `algo` 必须是字符串常量： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/expression-temporal-functions.html) 以下公式用于计算，其中： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/expression-temporal-functions.html) 总体标准差方程： ![\[总体标准差方程。\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/images/timeweightedstdev1.png) 频率标准差方程： ![\[频率标准差方程。\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/images/timeweighted-frequency-stdev.png)  | 

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

![\[AWS IoT SiteWise 时间函数根据数据点的时间戳返回数据点。\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/images/sitewise-temporal-functions.png)
<a name="time-range-def"></a>

**注意**  
`first(x)`, `last(x)` 的时间范围是 (当前窗口开始, 当前窗口结束]。
`latest(x)` 的时间范围是 (起始时间, 当前窗口结束]。
`earliest(x)` 的时间范围是 (起始时间, 上一窗口结束]。

** 时间加权函数参数**

为聚合窗口计算的时间加权函数会考虑以下因素：
+ 窗口内的数据点
+ 数据点之间的时间间隔
+ 窗口前的最后一个数据点
+ 窗口之后的第一个数据点（对于某些算法）

**术语：**
+ **不良数据点** - 任何质量不佳或非数字值的数据点。在窗口结果计算中不考虑这一点。
+ **不良间隔** - 不良数据点之后的间隔。第一个已知数据点之前的间隔也被视为不良间隔。
+ **良好数据点** - 任何具有良好质量和数值的数据点。

**注意**  
AWS IoT SiteWise 仅在计算变换和指标时才消耗`GOOD`质量数据。它会忽略 `UNCERTAIN` 和 `BAD` 数据点。
第一个已知数据点之前的间隔被视为**不良间隔**。请参阅[公式表达式教程](expression-tutorials.md)了解更多信息。

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

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

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

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

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

**Example 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 秒。

**Example 示例 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 | 

## 在转换中使用时间函数
<a name="temporal-functions-in-transforms"></a>

仅在[转换](transforms.md)中，您可以使用 `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 纪元格式返回机器处于清洁状态的时间（以秒为单位）。有关更多信息，请参阅 [在公式表达式中使用条件函数](expression-conditional-functions.md) [时间戳（）](expression-date-and-time-functions.md) 函数。

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

您也可以在多变量转换中使用 `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 \$1 2 \$1 1 `pretrigger(y)` 等于 1。  |  25 = 20 \$1 3 \$1 2 `x` 没有收到新的数据点。`pretrigger(y)` 等于 2。  |  36 = 30 \$1 3 \$1 3 `y` 没有收到新的数据点。因此，在上午 09:15 `pretrigger(y)` 等于 3。  |