支援終止通知：2026 年 5 月 20 日， AWS 將終止對 的支援 AWS IoT Events。2026 年 5 月 20 日之後，您將無法再存取 AWS IoT Events 主控台或 AWS IoT Events 資源。如需詳細資訊，請參閱[AWS IoT Events 終止支援](https://docs.aws.amazon.com/iotevents/latest/developerguide/iotevents-end-of-support.html)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 篩選、轉換和處理事件資料的表達式
運算式用於評估傳入資料、執行計算，以及判斷應發生特定動作或狀態轉換的條件。當您建立和更新偵測器模型時， AWS IoT Events 提供多種方式來指定值。您可以使用表達式來指定常值，也可以在指定特定值之前 AWS IoT Events 評估表達式。
**Topics**
+ [在 中篩選裝置資料和定義動作的語法 AWS IoT Events](#expression-syntax)
+ [的表達式範例和用量 AWS IoT Events](expression-usage.md)
## 在 中篩選裝置資料和定義動作的語法 AWS IoT Events
運算式提供用於篩選裝置資料和定義動作的語法。您可以在表達式中使用 AWS IoT Events 常值、運算子、函數、參考和替換範本。透過結合這些元件，您可以建立強大且靈活的表達式來處理 IoT 資料、執行計算、操作字串，以及在偵測器模型中做出邏輯決策。
### 文字
+ Integer
+ Decimal (小數)
+ String
+ Boolean
### 運算子
Unary
+ 非 （布林值）： `!`
+ 非 （位元）： `~`
+ 最小值 （算術）： `-`
String
+ 串連： **`+`**
兩個運算元都必須是字串。字串常值必須以單引號 (') 括住。
例如：`'my' + 'string'`> `'mystring'`
算術
+ 新增： **`+`**
兩個運算元都必須是數值。
+ 減法： **`-`**
+ 部門： **`/`**
除非至少一個運算元 （除數或除數） 是十進位值，否則分割的結果是四捨五入整數值。
+ 乘法： **`*`**
位元 （整數）
+ OR： **`|`**
例如：`13 | 5`> `13`
+ AND： **`&`**
例如：`13 & 5`> `5`
+ XOR： **`^`**
例如：`13 ^ 5`> `8`
+ 不適用： **`~`**
例如：`~13`> `-14`
Boolean
+ 小於： **`<`**
+ 小於或等於： **`<=`**
+ 等於： **`==`**
+ 不等於： **`!=`**
+ 大於或等於： **`>=`**
+ 大於： **`>`**
+ AND： **`&&`**
+ OR： **`||`**
**注意**
當 的子表達式`||`包含未定義的資料時，該子表達式會視為 `false`。
括號
您可以使用括號來分組表達式中的詞彙。
### 要在 AWS IoT Events 表達式中使用的函數
AWS IoT Events 提供一組內建函數，以增強偵測器模型表達式的功能。這些函數可啟用計時器管理、類型轉換、Null 檢查、觸發類型識別、輸入驗證、字串操作和位元操作。透過利用這些函數，您可以建立回應式 AWS IoT Events 處理邏輯，改善 IoT 應用程式的整體效率。
內建函數
`timeout("timer-name")`
`true` 如果指定的計時器已過，則評估 為 。將 "**timer-name**" 取代為您定義的計時器名稱，以引號表示。在事件動作中，您可以定義計時器，然後啟動計時器、重設計時器，或清除先前定義的計時器。請參閱 欄位 `detectorModelDefinition.states.onInput|onEnter|onExit.events.actions.setTimer.timerName`。
您可以在不同狀態中參考處於某個狀態的計時器集。您必須先造訪您建立計時器的狀態，才能進入參考計時器的狀態。
例如，偵測器模型有兩個狀態 `TemperatureChecked`和 `RecordUpdated`。您已在 `TemperatureChecked` 狀態建立計時器。您必須先造訪 `TemperatureChecked` 狀態，才能使用 `RecordUpdated` 狀態的計時器。
為了確保準確性，應設定計時器的最短時間為 60 秒。
`timeout()` `true`只會在實際計時器過期後第一次檢查時傳回 ，並在`false`之後傳回 。
`convert(type, expression)`
評估為轉換為指定類型的表達式值。*類型*值必須為 `String`、 `Boolean`或 `Decimal`。使用其中一個關鍵字或評估為包含關鍵字之字串的表達式。只有下列轉換成功並傳回有效值：
+ 布林值 -> 字串
傳回字串 `"true"`或 `"false"`。
+ 小數 -> 字串
+ 字串 -> 布林值
+ 字串 -> 小數
指定的字串必須是小數的有效表示法，否則`convert()`會失敗。
如果 `convert()`未傳回有效的值，則其所屬的表達式也會無效。此結果等同於 `false` ，且不會觸發 `actions`或 轉換為`nextState`指定為發生表達式之事件的一部分。
`isNull(expression)`
`true` 如果表達式傳回 null，則評估為 。例如，如果輸入`MyInput`收到訊息 `{ "a": null }`，則以下內容會評估為 `true`，但`isUndefined($input.MyInput.a)`評估為 `false`。
```
isNull($input.MyInput.a)
```
`isUndefined(expression)`
`true` 如果未定義表達式，則評估為 。例如，如果輸入`MyInput`收到訊息 `{ "a": null }`，則下列項目會評估為 `false`，但`isNull($input.MyInput.a)`評估為 `true`。
```
isUndefined($input.MyInput.a)
```
`triggerType("type")`
*類型*值可以是 `"Message"`或 `"Timer"`。評估 `true` 是否因為計時器過期而顯示的事件條件正在評估，如下列範例所示。
```
triggerType("Timer")
```
或者收到輸入訊息。
```
triggerType("Message")
```
`currentInput("input")`
評估 `true`是否因為收到指定的輸入訊息而評估其出現的事件條件。例如，如果輸入`Command`收到訊息 `{ "value": "Abort" }`，則以下內容會評估為 `true`。
```
currentInput("Command")
```
使用此函數來驗證正在評估條件，因為已收到特定輸入且計時器尚未過期，如下列表達式所示。
```
currentInput("Command") && $input.Command.value == "Abort"
```
字串比對函數
`startsWith(expression1, expression2)`
評估第一個字串表達式`true`是否以第二個字串表達式開頭。例如，如果輸入`MyInput`收到訊息 `{ "status": "offline"}`，則以下內容會評估為 `true`。
```
startsWith($input.MyInput.status, "off")
```
兩個表達式都必須評估為字串值。如果任一表達式未評估為字串值，則函數的結果為未定義。不會執行轉換。
`endsWith(expression1, expression2)`
`true` 如果第一個字串表達式以第二個字串表達式結尾，則評估為 。例如，如果輸入`MyInput`收到訊息 `{ "status": "offline" }`，則以下內容會評估為 `true`。
```
endsWith($input.MyInput.status, "line")
```
兩個表達式都必須評估為字串值。如果任一表達式未評估為字串值，則函數的結果為未定義。不會執行轉換。
`contains(expression1, expression2)`
評估第一個字串表達式`true`是否包含第二個字串表達式。例如，如果輸入`MyInput`收到訊息 `{ "status": "offline" }`，則以下內容會評估為 `true`。
```
contains($input.MyInput.value, "fli")
```
兩個表達式都必須評估為字串值。如果任一表達式未評估為字串值，則函數的結果為未定義。不會執行轉換。
Bitwise 整數控制函數
`bitor(expression1, expression2)`
評估整數表達式的位元 OR （二進位 OR 操作會在整數的對應位元上執行）。例如，如果輸入`MyInput`收到訊息 `{ "value1": 13, "value2": 5 }`，則以下內容會評估為 `13`。
```
bitor($input.MyInput.value1, $input.MyInput.value2)
```
兩個表達式都必須評估為整數值。如果任一表達式未評估為整數值，則函數的結果為未定義。不會執行轉換。
`bitand(expression1, expression2)`
評估整數表達式的位元 AND （二進位 AND 操作會在整數的對應位元上執行）。例如，如果輸入`MyInput`收到訊息 `{ "value1": 13, "value2": 5 }`，則以下內容會評估為 `5`。
```
bitand($input.MyInput.value1, $input.MyInput.value2)
```
兩個表達式都必須評估為整數值。如果任一表達式未評估為整數值，則函數的結果為未定義。不會執行轉換。
`bitxor(expression1, expression2)`
評估整數表達式的位元 XOR （二進位 XOR 操作會在整數的對應位元上執行）。例如，如果輸入`MyInput`收到訊息 `{ "value1": 13, "value2": 5 }`，則以下內容會評估為 `8`。
```
bitxor($input.MyInput.value1, $input.MyInput.value2)
```
兩個表達式都必須評估為整數值。如果任一表達式未評估為整數值，則函數的結果為未定義。不會執行轉換。
`bitnot(expression)`
評估整數表達式的位元 NOT （二進位 NOT 操作是在整數的位元上執行）。例如，如果輸入`MyInput`收到訊息 `{ "value": 13 }`，則以下內容會評估為 `-14`。
```
bitnot($input.MyInput.value)
```
兩個表達式都必須評估為整數值。如果任一表達式未評估為整數值，則函數的結果為未定義。不會執行轉換。
### AWS IoT Events 運算式中輸入和變數的參考
輸入
`$input.input-name.path-to-data`
`input-name` 是您使用 [CreateInput](https://docs.aws.amazon.com/iotevents/latest/apireference/API_CreateInput.html) 動作建立的輸入。
例如，如果您有名為 的輸入`TemperatureInput`來定義`inputDefinition.attributes.jsonPath`項目，則值可能會出現在下列可用欄位中。
```
{
"temperature": 78.5,
"date": "2018-10-03T16:09:09Z"
}
```
若要參考 `temperature` 欄位的值，請使用下列命令。
```
$input.TemperatureInput.temperature
```
對於值為陣列的欄位，您可以使用 來參考陣列的成員`[n]`。例如，指定下列值：
```
{
"temperatures": [
78.4,
77.9,
78.8
],
"date": "2018-10-03T16:09:09Z"
}
```
您可以使用下列命令`78.8`參考 值。
```
$input.TemperatureInput.temperatures[2]
```
Variables
`$variable.variable-name`
`variable-name` 是您使用 [CreateDetectorModel](https://docs.aws.amazon.com/iotevents/latest/apireference/API_CreateDetectorModel.html) 動作定義的變數。
例如，如果您有使用 `TechnicianID` 定義的名為 的變數`detectorDefinition.states.onInputEvents.actions.setVariable.variableName`，您可以使用下列命令參考最近提供給變數的 （字串） 值。
```
$variable.TechnicianID
```
您只能使用 `setVariable`動作來設定變數的值。您無法為表達式中的變數指派值。變數無法取消設定。例如，您無法為其指派值 `null`。
**注意**
在使用不遵循 （規則表達式） 模式的識別符的參考中`[a-zA-Z][a-zA-Z0-9_]*`，您必須在反引號 () 中括住這些識別符```。例如，對於名為 `MyInput`且具有名為 欄位的輸入參考`_value`，必須將此欄位指定為 `$input.MyInput.`_value``。
當您在表達式中使用參考時，請檢查下列項目：
+ 當您使用參考做為具有一或多個運算子的運算元時，請確定您參考的所有資料類型都相容。
例如，在以下表達式中，整數`2`是 `==`和 `&&`運算子的運算元。為了確保運算元相容，`$variable.testVariable + 1`且`$variable.testVariable`必須參考整數或小數。
此外，整數`1`是`+`運算子的運算元。因此， `$variable.testVariable` 必須參考整數或小數。
```
‘$variable.testVariable + 1 == 2 && $variable.testVariable’
```
+ 當您使用參考做為傳遞給函數的引數時，請確定該函數支援您參考的資料類型。
例如，下列`timeout("time-name")`函數需要具有雙引號的字串做為引數。如果您使用*計時器名稱*值的參考，則必須參考具有雙引號的字串。
```
timeout("timer-name")
```
**注意**
對於 `convert(type, expression)`函數，如果您使用*類型*值的參考，則參考的評估結果必須是 `String`、 `Decimal`或 `Boolean`。
AWS IoT Events 運算式支援整數、小數、字串和布林資料類型。下表提供不相容的類型對清單。
| 類型配對不相容 |
| --- |
| 整數、字串 |
| 整數，布林值 |
| 小數，字串 |
| 小數，布林值 |
| 字串，布林值 |
### AWS IoT Events 表達式的替代範本
****
`'${expression}'`
會將字串`${}`識別為插入字串。`expression` 可以是任何 AWS IoT Events 表達式。這包括運算子、函數和參考。
例如，您使用 [SetVariableAction](https://docs.aws.amazon.com/iotevents/latest/apireference/API_SetVariableAction.html) 動作來定義變數。`variableName` 即為 `SensorID`，而 `value` 即為 `10`。您可以建立下列替代範本。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iotevents/latest/developerguide/iotevents-expressions.html)
# 的表達式範例和用量 AWS IoT Events
您可以透過下列方式在偵測器模型中指定值：
+ 在 AWS IoT Events 主控台中輸入支援的表達式。
+ 將表達式傳遞至 AWS IoT Events APIs做為參數。
運算式支援常值、運算子、函數、參考和替代範本。
**重要**
您的表達式必須參考整數、小數、字串或布林值。
## 撰寫 AWS IoT Events 表達式
請參閱下列範例，協助您撰寫 AWS IoT Events 表達式：
**常值**
對於文字值，表達式必須包含單引號。布林值必須為 `true`或 `false`。
```
'123' # Integer
'123.12' # Decimal
'hello' # String
'true' # Boolean
```
**參考資料**
對於參考，您必須指定變數或輸入值。
+ 下列輸入參考十進位數字 `10.01`。
```
$input.GreenhouseInput.temperature
```
+ 下列變數參考字串 `Greenhouse Temperature Table`。
```
$variable.TableName
```
**替代範本**
對於替代範本，您必須使用 `${}`，且範本必須以單引號括起來。替代範本也可以包含文字、運算子、函數、參考和替代範本的組合。
+ 下列表達式的評估結果是字串 `50.018 in Fahrenheit`。
```
'${$input.GreenhouseInput.temperature * 9 / 5 + 32} in Fahrenheit'
```
+ 下列表達式的評估結果是字串 `{\"sensor_id\":\"Sensor_1\",\"temperature\":\"50.018\"}`。
```
'{\"sensor_id\":\"${$input.GreenhouseInput.sensors[0].sensor1}\",\"temperature\":\"${$input.GreenhouseInput.temperature*9/5+32}\"}'
```
**字串串連**
對於字串串連，您必須使用 `+`。字串串連也可以包含文字、運算子、函數、參考和替代範本的組合。
+ 下列表達式的評估結果是字串 `Greenhouse Temperature Table 2000-01-01`。
```
'Greenhouse Temperature Table ' + $input.GreenhouseInput.date
```