本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在公式表達式中使用暫時函數
<a name="expression-temporal-functions"></a>

使用暫時函數，根據資料點的時間戳記傳回值。

## 在指標中使用暫時函數
<a name="temporal-functions-in-metrics"></a>

僅在 [指標](metrics.md)中，您可以使用下列函數，根據資料點的時間戳記傳回值。

暫時函數引數必須是來自本機資產模型或巢狀運算式的屬性。這表示您無法在暫時函數中使用子資產模型的屬性。

您可以在時間函數中使用巢狀運算式。當您使用巢狀運算式時，適用下列規則：
+ 每個引數只能有一個變數。

  例如，支援 `latest( t*9/5 + 32 )` 。
+ 引數不能是彙總函數。

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


| 函式 | Description | 
| --- | --- | 
|  `first(x)`  |  傳回目前時間間隔指定變數值中時間戳記最早的值。  | 
|   `last(x)` |  傳回目前時間間隔指定變數值中時間戳記最晚的值。  | 
|  `earliest(x)`  |  傳回指定變數在目前時間間隔開始前的最後一個值。 如果輸入屬性在其歷史記錄中至少有一個資料點，此函數會計算每個時間間隔的資料點。如需詳細資訊，請參閱 [time-range-defintion](#time-range-def)。  | 
|   `latest(x)` |  傳回指定變數的最後一個值，並在目前時間間隔結束前加上最新的時間戳記。 如果輸入屬性在其歷史記錄中至少有一個資料點，此函數會計算每個時間間隔的資料點。如需詳細資訊，請參閱 [time-range-defintion](#time-range-def)。  | 
|   `statetime(x)`  |  傳回目前時間間隔中指定變數為正 (positive) 的秒數。您可以使用[比較函數](expression-comparison-functions.md)來建立轉換屬性，以供`statetime`函數使用。 例如，如果您有一個為 `0` 或 `1` 的 `Idle` 屬性，您可以使用此表達式來計算每個時間間隔的閒置時間：`IdleTime = statetime(Idle)`。如需詳細資訊，請參閱 [example statetime scenario](#statetime-example) (狀態時間案例範例)。 此函數不支援使用指標屬性做為輸入變數。 如果輸入屬性在其歷史記錄中至少有一個資料點，此函數會計算每個時間間隔的資料點。  | 
|   `TimeWeightedAvg(x, [interpolation])`  | 傳回以點之間的時間間隔加權的輸入資料平均值。如需運算和間隔詳細資訊，請參閱[時間加權函數參數](#timeweighted-parameter)。選用引數`interpolaton`必須是字串常數：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/iot-sitewise/latest/userguide/expression-temporal-functions.html) 下列公式用於運算，其中： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-temporal-functions.html) 母群體標準差的方程式： ![\[母群體標準差的方程式。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/timeweightedstdev1.png) 頻率標準差的方程式： ![\[頻率標準差的方程式。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/timeweighted-frequency-stdev.png)  | 

下圖顯示 如何計算 AWS IoT SiteWise 相對於目前時間間隔的時間函數 `latest`、、 `first` `last``earliest`和 。

![\[AWS IoT SiteWise 暫時函數會根據其時間戳記傳回資料點。\]](http://docs.aws.amazon.com/zh_tw/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 狀態時間案例範例**  
假設您具有以下屬性的資產：  
+ `Idle` – 為 `0`或 的測量`1`。值為 `1` 時，機器處於閒置狀態。
+ `Idle Time` – 使用公式`statetime(Idle)`計算機器閒置時間的指標，以秒為單位，每隔 1 分鐘間隔。
該 `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 | N/A | 30 | 60 | 45 | 0 | 
AWS IoT SiteWise 會在每分鐘`Idle Time`結束時對 執行下列計算。  
+ 下午 2:00 (下午 1:59 至下午 2:00)
  + 下午 2:00 之前 `Idle` 沒有資料，因此不會計算任何資料點。
+ 下午 2:01 (下午 2:00 至下午 2:01)
  + 下午 2:00:00，機器處於作用中狀態 (`Idle` 為 `0`)。
  + 下午 2:00:30，機器處於閒置狀態 (`Idle` 為 `1`)。
  + 在下午 2:01:00 的間隔結束之前 `Idle` 不會再次改變，所以 `Idle Time` 是 30 秒。
+ 下午 2:02 (下午 2:01 至下午 2:02)
  + 下午 2:01:00，機器處於閒置狀態 (即最後一個資料點位於下午 2:00:30)。
  + 下午 2:01:15，機器仍處於閒置狀態。
  + 在下午 2:02:00 的間隔結束之前 `Idle` 不會再次改變，所以 `Idle Time` 是 60 秒。
+ 下午 2:03 (下午 2:02至下午 2:03)
  + 下午 2:02:00，機器處於閒置狀態 (即最後一個資料點位於下午 2:01:15)。
  + 下午 2:02:45，機器處於作用中狀態。
  + 在下午 2:03:00 的間隔結束之前 `Idle` 不會再次改變，所以 `Idle Time` 是 45 秒。
+ 下午 2:04 (下午 2:03 至下午 2:04 )
  + 下午 2:03:00，機器處於作用中狀態 (即最後一個資料點位於下午 2:02:45)。
  + 在下午 2:04:00 的間隔結束之前 `Idle` 不會再次改變，所以 `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 epoch。如需詳細資訊，請參閱 [在公式表達式中使用條件式函數](expression-conditional-functions.md)和 [timestamp()](expression-date-and-time-functions.md) 函數。

如果機器停留在清除狀態的時間超過預期，製造商可能會調查機器。

您也可以在多變量轉換中使用 `pretrigger()`函數。例如，您有兩個名為 `x`和 `z`的測量`y`，以及一個等於 的轉換 `x + y + pretrigger(y)`。下表顯示 `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`等於上午 `22 = 20 + 1 + 1` 9：05。


|  | 上午 09：00 | 上午 09：05 | 上午 09：10 | 上午 09：15 | 
| --- | --- | --- | --- | --- | 
|  `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` 不會收到新的資料點。因此， `pretrigger(y)`等於上午 09：15 的 3。  |