函數

您可以在 SQL 表達式的 SELECT 或 WHERE 子句中使用下列內建函數。

abs(Decimal)

傳回某個數字的絕對值。受 SQL 版本 2015-10-08 和更新版本支援。

範例：abs(-5) 傳回 5。

引數類型	結果
Int	Int，引數的絕對值。
Decimal	Decimal，引數的絕對值。
Boolean	Undefined.
String	Decimal。結果為引數的絕對值。如果字串無法轉換，則結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

accountid()

將擁有此規則的帳戶 ID 傳回為 String。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

accountid() = "123456789012"

acos(Decimal)

以弧度傳回數字的反餘弦值。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：acos(0) = 1.5707963267948966

引數類型	結果
Int	Decimal (使用雙精度)，引數的反向餘弦值。傳回的虛數結果為 Undefined。
Decimal	Decimal (使用雙精度)，引數的反向餘弦值。傳回的虛數結果為 Undefined。
Boolean	Undefined.
String	Decimal，引數的反向餘弦值。如果字串無法轉換，則結果為 Undefined。傳回的虛數結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

asin(Decimal)

以弧度傳回數字的反正弦值。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：asin(0) = 0.0

引數類型	結果
Int	Decimal (使用雙精度)，引數的反向正弦值。傳回的虛數結果為 Undefined。
Decimal	Decimal (使用雙精度)，引數的反向正弦值。傳回的虛數結果為 Undefined。
Boolean	Undefined.
String	Decimal (使用雙精度)，引數的反向正弦值。如果字串無法轉換，則結果為 Undefined。傳回的虛數結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

atan(Decimal)

以弧度傳回數字的反正切值。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：atan(0) = 0.0

引數類型	結果
Int	Decimal (使用雙精度)，引數的反向正切值。傳回的虛數結果為 Undefined。
Decimal	Decimal (使用雙精度)，引數的反向正切值。傳回的虛數結果為 Undefined。
Boolean	Undefined.
String	Decimal，引數的反向正切值。如果字串無法轉換，則結果為 Undefined。傳回的虛數結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

atan2(Decimal, Decimal)

以弧度傳回 x 軸正軸和兩個引數所定義的 (x, y) 點之間的角度。 逆時針角度為正值 (上半象限，y > 0)，順時鐘的角度為負值 (下半象限 y < 0)。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：atan2(1, 0) = 1.5707963267948966

引數類型	引數類型	結果
Int/Decimal	Int/Decimal	Decimal (使用雙精度)，x 軸與指定的 (x, y) 點之間的角度。
Int/Decimal/String	Int/Decimal/String	Decimal，所述之點的反向正切值。如果字串無法轉換，則結果為 Undefined。
其他值	其他值	Undefined.

aws_lambda (functionArn、inputJson)

呼叫指定的 Lambda 函數，其會將 inputJson 傳送至 Lambda 函數，並傳回 Lambda 函數產生的 JSON。

引數

引數	描述
functionArn	Lambda 函數呼叫的 ARN。Lambda 函數必須傳回 JSON 資料。
inputJson	傳遞到 Lambda 函數的 JSON 輸入。若要傳遞巢狀物件查詢和文字，您必須使用 SQL 版本 2016-03-23。

您必須授予 AWS IoT lambda:InvokeFunction叫用指定 Lambda 函數的許可。下列範例顯示了如何使用 AWS CLI授與 lambda:InvokeFunction 的許可：

aws lambda add-permission --function-name "function_name"
--region "region"
--principal iot.amazonaws.com 
--source-arn arn:aws:iot:us-east-1:account_id:rule/rule_name
--source-account "account_id"
--statement-id "unique_id" 
--action "lambda:InvokeFunction"

以下為 add-permission 命令的引數：

--function-name

Lambda 函數的名稱。您可以新增許可來更新函數的資源政策。

--region

AWS 區域 您帳戶的 。

--principal

取得許可的委託人。這應該iot.amazonaws.com允許呼叫 Lambda 函數的 AWS IoT 許可。

--source-arn

該項規則的 ARN。您可以使用 get-topic-rule AWS CLI 命令來取得規則的 ARN。

--source-account

定義規則 AWS 帳戶 的 。

--statement-id

專屬的陳述式識別符。

--action

您想要在此陳述式中允許的 Lambda 動作。若要允許 AWS IoT 叫用 Lambda 函數，請指定 lambda:InvokeFunction。

重要

如果您在未提供 source-arn或 的情況下新增 AWS IoT 委託人的許可source-account，則任何 AWS 帳戶 使用 Lambda 動作建立規則的 都可以觸發規則來叫用您的 Lambda 函數 AWS IoT。如需詳細資訊，請參閱 Lambda 許可模型。

指定的 JSON 訊息承載，如以下所示：

{
    "attribute1": 21,
    "attribute2": "value"
}

aws_lambda 函數可用於呼叫 Lambda 函數，如下所示：

SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", {"payload":attribute1}) as output FROM 'topic-filter'

如果您想要傳遞完整的 MQTT 訊息承載，您可以使用「*」來指定 JSON 承載，如下列範例所示。

SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", *) as output FROM 'topic-filter'

payload.inner.element 會從發佈在「主題/子主題」主題上的訊息選取資料。

some.value 會從 Lambda 函數產生的輸出結果中選取資料。

注意

該規則引擎會限制 Lambda 函數的執行期間。規則的 Lambda 函數呼叫應該會在 2000 毫秒內完成。

bitand (Int、Int)

在兩個 Int (已轉換) 引數的位元表現上執行按位元的 AND 運算。受 SQL 版本 2015-10-08 和更新版本支援。

範例：bitand(13, 5) = 5

引數類型	引數類型	結果
Int	Int	Int，兩個引數按位元的 AND 運算。
Int/Decimal	Int/Decimal	Int，兩個引數按位元的 AND 運算。所有非 Int 的數字會無條件捨去至最接近的 Int。如果任何引數無法轉換至 Int，結果會為 Undefined。
Int/Decimal/String	Int/Decimal/String	Int，兩個引數按位元的 AND 運算。所有字串都會轉換為小數，並會無條件捨去至最接近的 Int (整數)。如果轉換失敗，則結果為 Undefined。
其他值	其他值	Undefined.

bitor(Int, Int)

在兩個引數的位元表現上執行按位元的 OR 運算。受 SQL 版本 2015-10-08 和更新版本支援。

範例：bitor(8, 5) = 13

引數類型	引數類型	結果
Int	Int	Int，兩個引數按位元的 OR 運算。
Int/Decimal	Int/Decimal	Int，兩個引數按位元的 OR 運算。所有非 Int 的數字會無條件捨去至最接近的 Int。如果轉換失敗，則結果為 Undefined。
Int/Decimal/String	Int/Decimal/String	Int，兩個引數按位元的 OR 運算。所有字串都會轉換為小數，並會無條件捨去至最接近的 Int (整數)。如果轉換失敗，則結果為 Undefined。
其他值	其他值	Undefined.

bitxor(Int, Int)

在兩個 Int (已轉換) 引數的位元表現上執行按位元的 XOR 運算。受 SQL 版本 2015-10-08 和更新版本支援。

範例：bitor(13, 5) = 8

引數類型	引數類型	結果
Int	Int	Int，兩個引數按位元的 XOR 運算。
Int/Decimal	Int/Decimal	Int，兩個引數按位元的 XOR 運算。非 Int 的數字會無條件捨去至最接近的 Int。
Int/Decimal/String	Int/Decimal/String	Int 是在兩個引數上的位元 XOR。字串會轉換為小數，並無條件捨去至最接近的 Int。如果任何轉換失敗，則結果為 Undefined。
其他值	其他值	Undefined.

bitnot(Int)

在 Int (已轉換) 引數的位元表現上執行按位元的 NOT 運算。受 SQL 版本 2015-10-08 和更新版本支援。

範例：bitnot(13) = 2

引數類型	結果
Int	Int，引數按位元的 NOT 運算。
Decimal	Int，引數按位元的 NOT 運算。Decimal值會無條件捨去至最接近 Int 的值。
String	Int，引數按位元的 NOT 運算。字串會轉換為小數，並會無條件捨去至最接近的 Int (整數)。如果任何轉換失敗，則結果為 Undefined。
其他值	其他值。

cast()

將一個值從某個資料類型轉換至另一個類型。除了增加了將數字和布林值相互轉換的能力外，轉換行為大致如同標準轉換。如果 AWS IoT 無法判斷如何將一種類型轉換為另一種類型，則結果為 Undefined。受 SQL 版本 2015-10-08 和更新版本支援。格式：cast (value as type)。

範例：

cast(true as Int) = 1

在呼叫 cast 時，以下關鍵字可能出現在「as」之後：

對於 SQL 版本 2015-10-08 與 2016-03-23

關鍵字	結果
String	將值轉換為 String。
Nvarchar	將值轉換為 String。
文字	將值轉換為 String。
Ntext	將值轉換為 String。
varchar	將值轉換為 String。
Int	將值轉換為 Int。
Integer	將值轉換為 Int。
Double	將值轉換為 Decimal (使用雙精度)。

此外，對於 SQL 版本 2016-03-23

關鍵字	結果
Decimal	將值轉換為 Decimal。
Bool	將值轉換為 Boolean。
Boolean	將值轉換為 Boolean。

轉換規則：

轉換為小數

引數類型	結果
Int	無小數點的 Decimal。
Decimal	來源值。 注意 使用 SQL V2 (2016-03-23) 時，數值若為整數 (例如 10.0) 會傳回 Int 值 (10)，而不是預期的 Decimal 值 (10.0)。若要可靠地將整數數值當成 Decimal 值處理，請針對規則查詢陳述式使用 SQL V1 (2015-10-08)。
Boolean	true = 1.0、false = 0.0。
String	嘗試將字串剖析為 Decimal。 AWS IoT 會嘗試剖析字串以符合正規表示式：^-?\d+(\.\d+)?((?i)E-?\d+)?$。「0」、「-1.2」、「5E-12」均為自動轉換為 Decimal 的範例字串。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

轉換為 Int

引數類型	結果
Int	來源值。
Decimal	無條件捨去至最接近 Int 的來源值。
Boolean	true = 1.0、false = 0.0。
String	嘗試將字串剖析為 Decimal。 AWS IoT 會嘗試剖析字串以符合正規表示式：^-?\d+(\.\d+)?((?i)E-?\d+)?$。「0」、「-1.2」、「5E-12」均為自動轉換為 Decimal 的範例字串。 AWS IoT 會嘗試將字串轉換為 Decimal，並無條件捨去至最接近的 Int。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

轉換到 Boolean

引數類型	結果
Int	0 = False，any_nonzero_value = True。
Decimal	0 = False，any_nonzero_value = True。
Boolean	來源值。
String	「true」= True 而「false」= False (不區分大小寫)。其他字串值 = Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

轉換為字串

引數類型	結果
Int	以標準表示法表示的 Int 的字串顯示方式。
Decimal	代表 Decimal 值的字串，可能是採取科學表示法。
Boolean	「true」或「false」，均為小寫。
String	來源值。
陣列	序列化為 JSON 的陣列。結果字串是以方括號括住，並以逗號分隔的清單。String 在括號中。Decimal、Int 和 Boolean 則不是。
物件	序列化為 JSON 的物件。JSON 字串是首尾以大括號括住，並以逗號分隔的鍵值組清單。String 在括號中。Decimal、Int、Boolean 和 Null 則不是。
Null	Undefined.
未定義	Undefined.

ceil(Decimal)

將指定的 Decimal 無條件進位至最近的 Int。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

ceil(1.2) = 2

ceil(-1.2) = -1

引數類型	結果
Int	Int，引數值。
Decimal	Int，無條件進位至最接近的 Decimal 的 Int 值。
String	Int。此字串會轉換成 Decimal 並四捨五入至最接近 Int。如果字串無法轉換為 Decimal，則結果為 Undefined。
其他值	Undefined.

chr(String)

傳回指定的 Int 引數對應到的 ASCII 字元。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

chr(65) = "A"。

chr(49) = "1"。

引數類型	結果
Int	對應到指定的 ASCII 值的字元。如果引數並非有效的 ASCII 值，結果會為 Undefined。
Decimal	對應到指定的 ASCII 值的字元。Decimal 的引數值會無條件捨去至最接近 Int 的值。如果引數並非有效的 ASCII 值，結果會為 Undefined。
Boolean	Undefined.
String	如果 String 可以轉換為 Decimal，要無條件捨去到最接近的 Int。如果引數並非有效的 ASCII 值，結果會為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
其他值	Undefined.

clientid()

傳回傳送訊息的 MQTT 用戶端的 ID，如果訊息不是透過 MQTT 傳送，則為 n/a。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

clientid() = "123456789012"

concat()

連接陣列或字串。此函數會接受任意數量的引數，並傳回 String 或 Array。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

concat() = Undefined.

concat(1) = "1"。

concat([1, 2, 3], 4) = [1, 2, 3, 4]。

concat([1, 2, 3], "hello") = [1, 2, 3, "hello"]

concat("con", "cat") = "concat"

concat(1, "hello") = "1hello"

concat("he","is","man") = "heisman"

concat([1, 2, 3], "hello", [4, 5, 6]) = [1, 2, 3, "hello", 4, 5, 6]

引數數量	結果
0	Undefined.
1	傳回的引數未經修改。
2+	如果任一引數為 Array，則結果會是包含所有引數的單一陣列。若沒有列出引數，且至少有一個引數是 String，則結果為所有引數 String 表示法的串聯。使用之前列出的標準轉換將引數轉換為字串。

cos(Decimal)

以弧度傳回數字的餘弦值。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

cos(0) = 1。

引數類型	結果
Int	Decimal (使用雙精度)，引數的餘弦值。傳回的虛數結果為 Undefined。
Decimal	Decimal (使用雙精度)，引數的餘弦值。傳回的虛數結果為 Undefined。
Boolean	Undefined.
String	Decimal (使用雙精度)，引數的餘弦值。如果字串無法轉換為 Decimal，則結果為 Undefined。傳回的虛數結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

cosh(Decimal)

以弧度傳回數字的雙曲餘弦值。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：cosh(2.3) = 5.037220649268761。

引數類型	結果
Int	Decimal (使用雙精度)，引數的雙曲餘弦值。傳回的虛數結果為 Undefined。
Decimal	Decimal (使用雙精度)，引數的雙曲餘弦值。傳回的虛數結果為 Undefined。
Boolean	Undefined.
String	Decimal (使用雙精度)，引數的雙曲餘弦值。如果字串無法轉換為 Decimal，則結果為 Undefined。傳回的虛數結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

decode(value, decodingScheme)

使用 decode 函數來解碼已編碼值。如果解碼字串為 JSON 文件，則會傳回可定址物件。否則，解碼字串會當成字串傳回。如果字串無法解碼，函數會傳回 NULL。此功能支援解碼 base64 編碼字串及協定緩衝區 (protobuf) 訊息格式。

受 SQL 版本 2016-03-23 和更新版本支援。

value

字串值或任何有效的表達式 (如 AWS IoT SQL 參考 所定義)，其會傳回字串。

decodingScheme

代表用來解碼值之結構描述的文字字串。目前僅支援 'base64' 和 'proto'。

對 base64 編碼字串進行解碼

在此範例中，訊息承載包含編碼值。

{
    encoded_temp: "eyAidGVtcGVyYXR1cmUiOiAzMyB9Cg=="
}

SQL 陳述式中的 decode 函數會解碼訊息承載中的值。

SELECT decode(encoded_temp,"base64").temperature AS temp from 'topic/subtopic'

解碼 encoded_temp 值會產生下列有效的 JSON 文件，允許 SELECT 陳述式讀取溫度值。

{ "temperature": 33 }

這裡顯示此範例中 SELECT 陳述式的結果。

{ "temp": 33 }

如果解碼值不是有效的 JSON 文件，解碼值將以字串形式傳回。

對 protobuf 訊息承載進行解碼

您可以使用解碼 SQL 函數來設定可對 protobuf 訊息承載進行解碼的規則。如需詳細資訊，請參閱對 protobuf 訊息承載進行解碼。

重要

如果您在設定 AWS IoT 委託人的許可source‐account時省略 source‐arn或 ，任何 AWS 帳戶 都可以透過其他 AWS IoT 規則叫用您的解碼函數。若要保護您的函數，請參閱《Amazon Simple Storage Service 使用者指南》中的儲存貯體政策。

功能簽章外觀如下：

decode(<ENCODED DATA>, 'proto', '<S3 BUCKET NAME>', '<S3 OBJECT KEY>', '<PROTO NAME>', '<MESSAGE TYPE>')            

ENCODED DATA

指定要解碼的 protobuf 編碼資料。如果傳送到規則的整個訊息是 protobuf 編碼資料，則可以使用 * 參考原始二進位傳入承載。否則，此欄位必須是 base-64 編碼的 JSON 字串，而且可以直接傳入字串的參考。

1) 要解碼原始二進位 protobuf 傳入承載：

decode(*, 'proto', ...)

2）要解碼由 base64 編碼字串 'a.b'表示的 protobuf 編碼訊息：

decode(a.b, 'proto', ...)

proto

指定要以 protobuf 訊息格式解碼的資料。如果您指定 base64 而不是 proto，此函數會將 base64 編碼字串解碼為 JSON。

S3 BUCKET NAME

您用來上傳 FileDescriptorSet 檔案的 Amazon S3 儲存貯體名稱。

S3 OBJECT KEY

用來在 Amazon S3 儲存貯體中指定 FileDescriptorSet 檔案的物件索引鍵。

PROTO NAME

從中產生 FileDescriptorSet 檔案的 .proto 檔案名稱 (不含副檔名)。

MESSAGE TYPE

待解碼資料在 FileDescriptorSet 檔案中所應符合的 Protobuf 訊息結構名稱。

使用解碼 SQL 函數的 SQL 運算式可能顯示如下：

SELECT VALUE decode(*, 'proto', 's3-bucket', 'messageformat.desc', 'myproto', 'messagetype') FROM 'some/topic'

• *

  表示二進位傳入承載，符合名為 mymessagetype 的 Protobuf 訊息類型。

• messageformat.desc

  存放在名為 s3-bucket 的 Amazon S3 儲存貯體中的 FileDescriptorSet 檔案。

• myproto

  此原始 .proto 檔案的用途是產生名為 myproto.proto 的 FileDescriptorSet 檔案。

• messagetype

  如 myproto.proto 中所定義名為 messagetype 的訊息類型(以及任何匯入的相依性)。

encode(value, encodingScheme)

根據編碼機制，使用 encode 函數將承載 (可能並非 JSON 資料) 編碼為字串表現形式。受 SQL 版本 2016-03-23 和更新版本支援。

value

任何有效的表達式，如 AWS IoT SQL 參考 的定義。無論承載是否為 JSON 格式，您都可以指定 * 以編碼整個承載。若您提供了運算式，則在編碼之前，評估結果將轉換為字串。

encodingScheme

代表您想要使用的編碼機制的文字字串。目前僅支援 'base64'。

endswith(String, String)

傳回 Boolean，指出第一個 String 引數是否以第二個 String 引數結尾。如果引數為 Null 或 Undefined，則結果為 Undefined。受 SQL 版本 2015-10-08 和更新版本支援。

範例：endswith("cat","at") = true。

引數類型 1	引數類型 2	結果
String	String	如果第一個引數以第二個引數結尾，則為 true。否則為 false。
其他值	其他值	所有引數都將使用標準轉換規則轉換為字串。如果第一個引數以第二個引數結尾，則為 true。否則為 false。如果引數為 Null 或 Undefined，則結果為 Undefined。

exp(Decimal)

傳回 e 次方的 Decimal 引數。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：exp(1) = e。

引數類型	結果
Int	Decimal (使用雙精度)，e ^ 引數。
Decimal	Decimal (使用雙精度)，e ^ 引數。
String	Decimal (使用雙精度)，e ^ 引數。如果 String 無法轉換為 Decimal，則結果為 Undefined。
其他值	Undefined.

floor(Decimal)

將指定的 Decimal 無條件進位至最接近的 Int。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

floor(1.2) = 1

floor(-1.2) = -2

引數類型	結果
Int	Int，引數值。
Decimal	Int，Decimal 值會無條件捨去至最接近的 Int。
String	Int。此字串會轉換成 Decimal，並無條件捨去至最接近的 Int。如果字串無法轉換為 Decimal，則結果為 Undefined。
其他值	Undefined.

get

從集合類型 (陣列、字串、物件) 擷取值。第一個引數不會套用任何轉換。轉換會按表格中的記錄套用至第二個引數。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

get(["a", "b", "c"], 1) = "b"

get({"a":"b"}, "a") = "b"

get("abc", 0) = "a"

引數類型 1	引數類型 2	結果
陣列	任何類型 (轉換為 Int)	第二個引數 (轉換為 Array) 所提供的 Int 從零開始的索引的項目。如果轉換不成功，則結果為 Undefined。如果索引在 Array的邊界之外 (負值或 >= array.length)，則結果為 Undefined。
字串	任何類型 (轉換為 Int)	第二個引數 (轉換為 Int) 所提供的字串從零開始的索引的字元。如果轉換不成功，則結果為 Undefined。如果索引在字串的邊界之外 (負值或 >= string.length)，則結果為 Undefined。
物件	String (未套用轉換)	對應至第二個引數所提供的字串鍵的第一個引數物件所儲存的值。
其他值	任何值	Undefined.

get_dynamodb(tableName, partitionKeyName, partitionKeyValue, sortKeyName, sortKeyValue, roleArn)

從 DynamoDB 資料表擷取資料。get_dynamodb() 允許您在評估規則時查詢 DynamoDB 資料表。您可以使用從 DynamoDB 中擷取的資料來篩選或增強訊息承載。受 SQL 版本 2016-03-23 和更新版本支援。

get_dynamodb() 接受下列參數：

tableName

所要查詢 DynamoDB 資料表的名稱。

partitionKeyName

分割區索引鍵的名稱。如需詳細資訊，請參閱 DynamoDB 索引鍵。

partitionKeyValue

用來識別記錄的分割區索引鍵值。如需詳細資訊，請參閱 DynamoDB 索引鍵。

sortKeyName

(選用) 排序索引鍵的名稱。只有在查詢的 DynamoDB 資料表使用複合索引鍵時，才需要此參數。如需詳細資訊，請參閱 DynamoDB 索引鍵。

sortKeyValue

(選用) 排序索引鍵的值。只有在查詢的 DynamoDB 資料表使用複合索引鍵時，才需要此參數。如需詳細資訊，請參閱 DynamoDB 索引鍵。

roleArn

授予 DynamoDB 資料表存取權限的 IAM 角色 ARN。規則引擎會假設此角色代表您存取 DynamoDB 資料表。請避免使用過多許可的角色。僅授與角色規則所需的許可。以下是授與一個 DynamoDB 資料表存取權的範例政策。

JSON

{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "dynamodb:GetItem",
            "Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/table-name"
        }
    ]
}

舉例說明如何使用 get_dynamodb()，假設您有一個 DynamoDB 資料表，其中包含所有連接至 AWS IoT之裝置的裝置 ID 和位置資訊。下列 SELECT 陳述式使用 get_dynamodb() 函數來擷取指定裝置 ID 的位置：

SELECT *, get_dynamodb("InServiceDevices", "deviceId", id, "arn:aws:iam::12345678910:role/getdynamo").location AS location FROM 'some/topic'

注意

• 每個 SQL 陳述式最多可以呼叫一次 get_dynamodb()。在單一 SQL 陳述式中多次呼叫 get_dynamodb() 會導致規則終止，而不會呼叫任何動作。

• 如果 get_dynamodb() 傳回的資料超過 8 KB，則可能不會叫用規則的動作。

get_mqtt_property(名稱)

參考下列任一 MQTT5 標頭：contentType、payLoadFormatIndicator、responseTopic、和 correlationData。此函數會接受下列任何常值字串做為引數：content_type、format_indicator、response_topic 和 correlation_data。如需詳細資訊，請參閱下列函數引數表。

ContentType

字串：描述發佈訊息內容的 UTF-8 編碼字串。

payLoadFormatIndicator

字串：列舉字串值，用於表示承載是否已格式化為 UTF-8。有效值為 UNSPECIFIED_BYTES 和 UTF8_DATA。

responseTopic

字串：UTF-8 編碼字串，用來當作回應訊息的主題名稱。回應主題是用來描述要在請求-回應流程中作為接收者發佈目標的主題。主題不得包含萬用字元。

correlationData

字串：請求訊息的傳送者使用 base64 編碼的二進位資料，用以在收到回應訊息時識別其所對應的請求。

下表列出可接受的函數引數及其相關聯的 get_mqtt_property 函數傳回類型：

函數引數

SQL	傳回資料類型 (如果存在)	傳回資料類型 (如果不存在)
get_mqtt_property("format_indicator")	字串 (UNSPECIFIED_BYTES 或 UTF8_DATA)	字串 (NSPECIFIED_BYTES)
get_mqtt_property("content_type")	字串	未定義
get_mqtt_property("response_topic")	字串	未定義
get_mqtt_property("correlation_data")	base64 編碼字串	未定義
get_mqtt_property("some_invalid_name")	未定義	未定義

下列範例規則 SQL 會參考下列任一 MQTT5 標頭：contentType、payLoadFormatIndicator、responseTopic、和correlationData。

SELECT *, get_mqtt_property('content_type') as contentType,
          get_mqtt_property('format_indicator') as payloadFormatIndicator,
          get_mqtt_property('response_topic') as responseTopic,
          get_mqtt_property('correlation_data') as correlationData
FROM 'some/topic'

get_secret(secretId, secretType, key, roleArn)

擷取所加密 SecretString 或 SecretBinary 欄位的值，此欄位是 AWS Secrets Manager 中目前秘密版本的欄位。如需建立和維護秘密的詳細資訊，請參閱 CreateSecret、UpdateSecret 和 PutSecretValue。

get_secret() 接受下列參數：

secretId

字串：要擷取之秘密的 Amazon 資源名稱 (ARN) 或易記名稱。

secretType

字串：秘密類型。有效值：SecretString | SecretBinary。

SecretString

• 對於您使用 APIs AWS CLI、 或 AWS Secrets Manager 主控台建立為 JSON 物件的秘密：

  • 如果您指定 key 參數的值，此函數會傳回所指定金鑰的值。

  • 如果未指定 key 參數的值，此函數會傳回整個 JSON 物件。

• 對於您使用 API 或 AWS CLI建立為非 JSON 物件的秘密：

  • 如果您指定 key 參數的值，此函數會失敗並顯示例外狀況。

  • 如果未指定 key 參數的值，此函數會傳回秘密的內容。

SecretBinary

• 如果您指定 key 參數的值，此函數會失敗並顯示例外狀況。

• 如果未指定 key 參數的值，此函數會以 Base64 編碼的 UTF-8 字串形式傳回秘密值。

key

(選用) 字串：JSON 物件內的金鑰名稱，此物件存放在秘密的 SecretString 欄位中。當您只想要擷取存放在秘密中的秘密值，而不是整個 JSON 物件時，請使用此值。

如果您指定此參數的值，而且秘密並未在其 SecretString 欄位內包含 JSON 物件，此函數會失敗並顯示例外狀況。

roleArn

字串：擁有 secretsmanager:GetSecretValue 和 secretsmanager:DescribeSecret 許可的角色 ARN。

注意

此函數一律傳回目前版本的秘密 (標籤為 AWSCURRENT 的版本)。 AWS IoT 規則引擎快取每個秘密最多 15 分鐘。因此，規則引擎最多可能需要 15 分鐘來更新秘密。這表示如果您在使用 更新後最多 15 分鐘內擷取秘密 AWS Secrets Manager，此函數可能會傳回先前的版本。

此函數不會計量，但會 AWS Secrets Manager 收取費用。由於秘密快取機制，規則引擎偶爾會呼叫 AWS Secrets Manager。因為規則引擎是完全分散式服務，您可能會在 15 分鐘快取時間範圍期間，看到多個來自規則引擎的 Secrets Manager API 呼叫。

範例：

您可以在 HTTPS 規則動作的身分驗證標題中使用 get_secret 函式，如下列 API 金鑰身分驗證範例所示。

"API_KEY": "${get_secret('API_KEY', 'SecretString', 'API_KEY_VALUE', 'arn:aws:iam::12345678910:role/getsecret')}"
            

如需 HTTPS 規則動作的詳細資訊，請參閱 HTTP。

get_thing_shadow(thingName, shadowName, roleARN)

傳回指定物件的影子。受 SQL 版本 2016-03-23 和更新版本支援。

thingName

字串：想要擷取影子的物件名稱。

shadowName

(選用) 字串：影子的名稱。只有在參考已命名的影子時，才需要此參數。

roleArn

字串：擁有 iot:GetThingShadow 許可的角色 ARN。

範例：

與已命名的影子搭配使用時，請提供 shadowName 參數。

SELECT * from 'topic/subtopic'
WHERE
    get_thing_shadow("MyThing","MyThingShadow","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
    .state.reported.alarm = 'ON'

與未命名影子搭配使用時，請省略 shadowName 參數。

SELECT * from 'topic/subtopic'
WHERE
    get_thing_shadow("MyThing","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
    .state.reported.alarm = 'ON'

get_user_properties(userPropertyKey)

參考使用者屬性，這是 MQTT5 支援的一種屬性標題類型。

userProperty

字串：使用者屬性是索引鍵/值對。此函數將索引鍵當作參數，並傳回所有符合關聯索引鍵的值陣列。

函數引數

對於下列位於訊息標頭中的使用者屬性：

金鑰	值
部分索引鍵	部分值
不同的索引鍵	不同的值
部分索引鍵	具有重複索引鍵的值

下表顯示預期的 SQL 行為：

SQL	傳回資料類型。	傳回資料類型。
get_user_properties(「部分索引鍵」)	字串陣列	['some value', 'value with duplicate key']
get_user_properties(「其他索引鍵」)	字串陣列	['a different value']
get_user_properties( )	索引鍵/值對物件的陣列	[{'"some key": "some value"'}, {"other key": "a different value"}, {"some key": "value with duplicate key"}]
get_user_properties(「不存在的索引鍵」)	未定義

下列範例規則 SQL 會將使用者屬性 (MQTT5 屬性標頭類型) 參考到承載中：

SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'

雜湊函數

AWS IoT 提供下列雜湊函數：

• md2

• md5

• sha1

• sha224

• sha256

• sha384

• sha512

所有雜湊函數都預期有一個字串引數。結果為該字串的雜湊值。標準字串轉換會套用至非字串的引數。SQL 版本 2015-10-08 和更新版本可支援所有雜湊函數。

範例：

md2("hello") = "a9046c73e00331af68917d3804f70655"

md5("hello") = "5d41402abc4b2a76b9719d911017c592"

indexof(String, String)

傳回第二個引數的第一個索引 (從 0 開始)，作為第一個引數的子字串。預期兩個引數均為字串。非字串的引數需遵守標準字串轉換規則。此函數不能套用在陣列上，僅可套用到字串上。受 SQL 版本 2016-03-23 和更新版本支援。

範例：

indexof("abcd", "bc") = 1

isNull()

如果引數是 Null 值，則傳回 true 受 SQL 版本 2015-10-08 和更新版本支援。

範例：

isNull(5) = false。

isNull(Null) = true。

引數類型	結果
Int	false
Decimal	false
Boolean	false
String	false
Array	false
Object	false
Null	true
Undefined	false

isUndefined()

如果引數是 Undefined，則傳回 true。受 SQL 版本 2016-03-23 和更新版本支援。

範例：

isUndefined(5) = false。

isUndefined(floor([1,2,3]))) = true。

引數類型	結果
Int	false
Decimal	false
Boolean	false
String	false
Array	false
Object	false
Null	false
Undefined	true

length(String)

傳回所提供的字串內的字元數。標準轉換規則會套用至非 String 的引數。受 SQL 版本 2016-03-23 和更新版本支援。

範例：

length("hi") = 2

length(false) = 5

ln(Decimal)

傳回引數的自然對數。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：ln(e) = 1。

引數類型	結果
Int	Decimal (使用雙精度)，引數的自然對數。
Decimal	Decimal (使用雙精度)，引數的自然對數。
Boolean	Undefined.
String	Decimal (使用雙精度)，引數的自然對數。如果字串無法轉換為 Decimal，則結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

log(Decimal)

傳回引數以 10 為底的對數。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：log(100) = 2.0。

引數類型	結果
Int	Decimal (使用雙精度)，引數以 10 為底的對數。
Decimal	Decimal (使用雙精度)，引數以 10 為底的對數。
Boolean	Undefined.
String	Decimal (使用雙精度)，引數以 10 為底的對數。如果 String 無法轉換為 Decimal，則結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

lower(String)

傳回小寫版本的特定 String。使用標準轉換規則將非字串引數轉換為字串。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

lower("HELLO") =「hello」。

lower(["HELLO"]) = "[\"hello\"]".

lpad(String, Int)

傳回 String 引數，左側填入第二個引數所指定的空格數。Int 引數必須介於 0 到 1000 之間。如果提供的值超出此有效範圍，則引數將設為最接近的有效值 (0 或 1000)。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

lpad("hello", 2) = "  hello".

lpad(1, 3) = "   1"

引數類型 1	引數類型 2	結果
String	Int	String，所給的 String 左側填入等同所給的 Int 的數量的空格。
String	Decimal	Decimal 引數將無條件捨去至最接近的 Int，而 String 會在左側填充指定的空格數。
String	String	第二個引數會轉換為 Decimal 並無條件捨去至最接近的 Int，而 String 會在左側填入指定的空格數。如果第二個引數無法轉換為 Int，則結果為 Undefined。
其他值	Int/Decimal/String	第一個值會使用標準轉換轉為 String，然後 LPAD 函數會套用至該 String。如果其無法轉換，則結果為 Undefined。
任何值	其他值	Undefined.

ltrim(String)

移除所給的 String 前方所有空格 (tab 與空格)。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

Ltrim(" h i ") = "hi "。

引數類型	結果
Int	移除 Int 前方所有空格的 String 顯示方式。
Decimal	移除 Decimal 前方所有空格的 String 顯示方式。
Boolean	移除布林值 (「true」或「false」) 前方所有空格的 String 顯示方式。
String	移除前方所有空格的引數。
陣列	String (使用標準轉換規則) 的 Array 顯示方式，且移除所有前置空格。
物件	Object (使用標準轉換規則) 的 String 顯示方式，且移除所有前置空格。
Null	Undefined.
未定義	Undefined.

machinelearning_predict(modelId, roleArn, record)

使用 machinelearning_predict函數，根據 Amazon SageMaker AI 模型使用來自 MQTT 訊息的資料進行預測。受 SQL 版本 2015-10-08 和更新版本支援。machinelearning_predict 函數的引數如下：

modelId

要對其執行預測的模型 ID。必須啟用該模型的即時端點。

roleArn

IAM 角色具有擁有 machinelearning:Predict 和 machinelearning:GetMLModel 許可的政策，且允許存取要對其執行預測的模型。

record

要傳遞至 SageMaker AI 預測 API 的資料。此應顯示為單層 JSON 物件。若該記錄為多層級 JSON 物件，則記錄會透過值的序列化來扁平化。例如，以下 JSON：

{ "key1": {"innerKey1": "value1"}, "key2": 0}

會變成：

{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}

該函數會傳回具有以下欄位的 JSON 物件：

predictedLabel

根據模型的輸入分類。

詳細資訊

包含下列屬性：

PredictiveModelType

模型類型。有效值為 REGRESSION、BINARY、MULTICLASS。

演算法

SageMaker AI 用來進行預測的演算法。該值必須為 SGD。

predictedScores

包含對應至每個標籤的原始分類分數。

predictedValue

SageMaker AI 預測的值。

mod(Decimal, Decimal)

傳回第一個引數除以第二的引數的餘數。等同於 remainder(Decimal, Decimal)。也可以使用「%」當做同樣的模除功能的 infix 運算子。受 SQL 版本 2015-10-08 和更新版本支援。

範例：mod(8, 3) = 2。

左運算元	右運算元	輸出
Int	Int	Int，第一個引數模除第二個引數。
Int/Decimal	Int/Decimal	Decimal，第一個引數模除第二個運算元。
String/Int/Decimal	String/Int/Decimal	如果所有的字串都轉換為小數，該結果是第一個引數以第二個引數為模。否則為 Undefined。
其他值	其他值	Undefined.

nanvl(AnyValue, AnyValue)

若第一個引數為有效的 Decimal，即傳回。否則便傳回第二個引數。受 SQL 版本 2015-10-08 和更新版本支援。

範例：Nanvl(8, 3) = 8。

引數類型 1	引數類型 2	輸出
未定義	任何值	第二個參數。
Null	任何值	第二個參數。
Decimal (NaN)	任何值	第二個參數。
Decimal (非 NaN)	任何值	第一個參數。
其他值	任何值	第一個參數。

newuuid()

傳回隨機的 16 位元組 UUID。受 SQL 版本 2015-10-08 和更新版本支援。

範例：newuuid() = 123a4567-b89c-12d3-e456-789012345000

numbytes(String)

傳回所給字串 UTF-8 編碼中的位元組數。標準轉換規則會套用至非 String 的引數。受 SQL 版本 2016-03-23 和更新版本支援。

範例：

numbytes("hi") = 2

numbytes("€") = 3

parse_time(String, Long[, String])

使用 parse_time 函數來設定時間戳記格式，變成人類易懂的日期/時間格式。受 SQL 版本 2016-03-23 和更新版本支援。若要將時間戳記字串轉換為毫秒，請參閱 time_to_epoch(String, String)。

parse_time 函數預期下列引數：

pattern

(字串) 遵循 Joda-Time 格式的日期/時間模式。

timestamp

(Long) 自 Unix epoch 起以毫秒單位設定格式的時間。請參閱函數 timestamp()。

timezone

(字串) 設定好格式的日期/時間的時區。預設值為「UTC」。該函數支援 Joda-Time 時區。此為選用引數。

範例：

在此訊息發佈至主題「A/B」時，承載 {"ts": "1970.01.01 AD at 21:46:40 CST"} 會傳送至 S3 儲存貯體：

{
    "ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
    "topicRulePayload": {
        "sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", 100000000, 'America/Belize' ) as ts FROM 'A/B'",

        "ruleDisabled": false,
        "awsIotSqlVersion": "2016-03-23",
        "actions": [
            {
                "s3": {
                    "roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
                    "bucketName": "BUCKET_NAME",
                    "key": "KEY_NAME"
                }
            }
        ],
        "ruleName": "RULE_NAME"
    }
} 

在此訊息發佈至主題「A/B」時，與 {"ts": "2017.06.09 AD at 17:19:46 UTC"} 相似，但包含目前日期/時間的承載會傳送至 S3 儲存貯體：

{
    "ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
    "topicRulePayload": {
        "sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", timestamp() ) as ts FROM 'A/B'",
        "awsIotSqlVersion": "2016-03-23",
        "ruleDisabled": false,
        "actions": [
            {
                "s3": {
                    "roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
                    "bucketName": "BUCKET_NAME",
                    "key": "KEY_NAME"
                }
            }
        ],
        "ruleName": "RULE_NAME"
    }
} 

parse_time() 也可以用作替代範本。例如，當此訊息發佈至主題「A/B」時，該承載會傳送至金鑰 =「2017」的 S3 儲存貯體：

{
    "ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
    "topicRulePayload": {
        "sql": "SELECT * FROM 'A/B'",
        "awsIotSqlVersion": "2016-03-23",
        "ruleDisabled": false,
        "actions": [{
            "s3": {
                "roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
                "bucketName": "BUCKET_NAME",
                "key": "${parse_time('yyyy', timestamp(), 'UTC')}"
            }
        }],
        "ruleName": "RULE_NAME"
    }
}

power(Decimal, Decimal)

傳回第一個引數次方的第二個引數值。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。受 SQL 版本 2015-10-08 和更新版本支援。

範例：power(2, 5) = 32.0。

引數類型 1	引數類型 2	輸出
Int/Decimal	Int/Decimal	Decimal (使用雙精度)，第一個引數次方的第二個引數值。
Int/Decimal/String	Int/Decimal/String	Decimal (使用雙精度)，第一個引數次方的第二個引數值。任何轉換為小數的字串。如果任何 String 無法轉換為 Decimal，則結果為 Undefined。
其他值	其他值	Undefined.

principal()

根據發佈觸發訊息的方式，傳回裝置用於身分驗證的委託人。下表說明為各發佈方法和通訊協定傳回的委託人。

訊息發佈方式	通訊協定	憑證類型	Principal
MQTT 用戶端	MQTT	X.509 裝置憑證	X.509 憑證指紋
AWS IoT 主控台 MQTT 用戶端	MQTT	IAM 使用者或角色	iam-role-id:session-name
AWS CLI	HTTP	IAM 使用者或角色	userid
AWS IoT 裝置 SDK	MQTT	X.509 裝置憑證	X.509 憑證指紋
AWS IoT 裝置 SDK	MQTT over WebSocket	IAM 使用者或角色	userid

以下範例顯示 principal() 可以傳回哪些不同類型的值：

• X.509 憑證指紋：ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373

• IAM 角色 ID 和工作階段名稱：ABCD1EFG3HIJK2LMNOP5:my-session-name

• 傳回使用者 ID：ABCD1EFG3HIJK2LMNOP5

rand()

傳回虛擬亂數，平均分散在 0.0 和 1.0。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

rand() = 0.8231909191640703

regexp_matches(String, String)

如果字串 (第一個引數) 包含規則表達式的相符項目 (第二個引數)，則傳回 true。如果您在規則表達式|中使用 ，請搭配 使用()。

範例：

regexp_matches("aaaa", "a{2,}") = true。

regexp_matches("aaaa", "b") = false。

regexp_matches("aaa", "(aaa|bbb)") = true。

regexp_matches("bbb", "(aaa|bbb)") = true。

regexp_matches("ccc", "(aaa|bbb)") = false。

第一個引數：

引數類型	結果
Int	Int 的 String 顯示方式。
Decimal	Decimal 的 String 顯示方式。
Boolean	布林值 (「true」或「false」) 的 String 顯示方式。
String	String。
陣列	Array (使用標準轉換規則) 的 String 顯示方式。
物件	Object (使用標準轉換規則) 的 String 顯示方式。
Null	Undefined.
未定義	Undefined.

第二個引數：

必須為有效的 regex 表達式。非字串類型都會使用標準轉換規則轉換為 String。根據類型，結果字串可能不是有效的正規運算式。如果 (轉換的) 引數並非有效的 regex 值，結果會為 Undefined。

regexp_replace(String, String, String)

以第三個引數取代所有在第一個引數中出現的第二個參數 (一般表達式)。請以「$」參考擷取群組。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

regexp_replace("abcd", "bc", "x") = "axd"。

regexp_replace("abcd", "b(.*)d", "$1") = "ac"。

第一個引數：

引數類型	結果
Int	Int 的 String 顯示方式。
Decimal	Decimal 的 String 顯示方式。
Boolean	布林值 (「true」或「false」) 的 String 顯示方式。
String	來源值。
陣列	Array (使用標準轉換規則) 的 String 顯示方式。
物件	Object (使用標準轉換規則) 的 String 顯示方式。
Null	Undefined.
未定義	Undefined.

第二個引數：

必須為有效的 regex 表達式。非字串類型都會使用標準轉換規則轉換為 String。根據類型，結果字串可能不是有效的正規運算式。如果 (轉換的) 引數並非有效的 regex 表達式，則結果為 Undefined。

第三個引數：

必須為有效的 regex 替換字串。(可以參考擷取群組)。非字串類型都會使用標準轉換規則轉換為 String。如果 (轉換的) 引數並非有效的 regex 替換字串，則結果為 Undefined。

regexp_substr(String, String)

在第一個參數中尋找第一個符合第二個參數 (regex) 的值。請以「$」參考擷取群組。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

regexp_substr("hihihello", "hi") = "hi"

regexp_substr("hihihello", "(hi)*") = "hihi"

第一個引數：

引數類型	結果
Int	Int 的 String 顯示方式。
Decimal	Decimal 的 String 顯示方式。
Boolean	布林值 (「true」或「false」) 的 String 顯示方式。
String	String 引數。
陣列	Array (使用標準轉換規則) 的 String 顯示方式。
物件	Object (使用標準轉換規則) 的 String 顯示方式。
Null	Undefined.
未定義	Undefined.

第二個引數：

必須為有效的 regex 表達式。非字串類型都會使用標準轉換規則轉換為 String。根據類型，結果字串可能不是有效的正規運算式。如果 (轉換的) 引數並非有效的 regex 表達式，則結果為 Undefined。

remainder(Decimal, Decimal)

傳回第一個引數除以第二的引數的餘數。等同於 mod(Decimal, Decimal)。也可以使用「%」當做同樣的模除功能的 infix 運算子。受 SQL 版本 2015-10-08 和更新版本支援。

範例：remainder(8, 3) = 2。

左運算元	右運算元	輸出
Int	Int	Int，第一個引數模除第二個引數。
Int/Decimal	Int/Decimal	Decimal，第一個引數模除第二個運算元。
String/Int/Decimal	String/Int/Decimal	如果所有的字串都轉換為小數，該結果是第一個引數以第二個引數為模。否則為 Undefined。
其他值	其他值	Undefined.

replace(String, String, String)

以第三個引數取代所有在第一個引數中出現的第二個引數。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

replace("abcd", "bc", "x") = "axd".

replace("abcdabcd", "b", "x") = "axcdaxcd".

所有引數

引數類型	結果
Int	Int 的 String 顯示方式。
Decimal	Decimal 的 String 顯示方式。
Boolean	布林值 (「true」或「false」) 的 String 顯示方式。
String	來源值。
陣列	Array (使用標準轉換規則) 的 String 顯示方式。
物件	Object (使用標準轉換規則) 的 String 顯示方式。
Null	Undefined.
未定義	Undefined.

rpad(String, Int)

傳回字串引數，右側填入第二個引數所指定的空格數。Int 引數必須介於 0 到 1000 之間。如果提供的值超出此有效範圍，則引數將設為最接近的有效值 (0 或 1000)。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

rpad("hello", 2) = "hello  ".

rpad(1, 3) = "1   ".

引數類型 1	引數類型 2	結果
String	Int	String 在右側填入，且空格數量等同所給的 Int。
String	Decimal	Decimal 引數會無條件捨去至最接近的 Int，並且該字串將以提供的 Int 相同的空格數填入右側。
String	String	第二個引數將轉換為 Decimal，並無條件捨去至最接近的 Int。String 在右側填入，且空格數量等同 Int 的值。
其他值	Int/Decimal/String	第一個值會使用標準轉換來轉換為 String，而 rpad 函數將套用到該 String 上。如果其無法轉換，則結果為 Undefined。
任何值	其他值	Undefined.

round(Decimal)

將指定的 Decimal 無條件進位至最接近的 Int。如果 Decimal 與兩個 Int 值 (例如，0.5) 等距，則 Decimal 會無條件進位。受 SQL 版本 2015-10-08 和更新版本支援。

範例：Round(1.2) = 1。

Round(1.5) = 2。

Round(1.7) = 2。

Round(-1.1) = -1。

Round(-1.5) = -2。

引數類型	結果
Int	引數。
Decimal	Decimal 是要向下捨入到最接近的 Int。
String	Decimal 是要向下捨入到最接近的 Int。如果字串無法轉換為 Decimal，則結果為 Undefined。
其他值	Undefined.

rtrim(String)

移除所給的 String 後方所有空格 (tab 與空格)。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

rtrim(" h i ") = " h i"

引數類型	結果
Int	Int 的 String 顯示方式。
Decimal	Decimal 的 String 顯示方式。
Boolean	布林值 (「true」或「false」) 的 String 顯示方式。
陣列	Array (使用標準轉換規則) 的 String 顯示方式。
物件	Object (使用標準轉換規則) 的 String 顯示方式。
Null	Undefined.
未定義	Undefined

sign(Decimal)

傳回所給數字的符號。當引數的符號為正值時，傳回 1。當引數的符號為負值時，傳回 -1。如果引數為 0，傳回 0。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

sign(-7) = -1。

sign(0) = 0。

sign(13) = 1。

引數類型	結果
Int	Int，Int 值的符號。
Decimal	Int，Decimal 值的符號。
String	Int，Decimal 值的符號。此字串會轉換為 Decimal 值，並傳回 Decimal 值的符號。如果 String 無法轉換為 Decimal，則結果為 Undefined。受 SQL 版本 2015-10-08 和更新版本支援。
其他值	Undefined.

sin(Decimal)

以弧度傳回數字的正弦值。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：sin(0) = 0.0

引數類型	結果
Int	Decimal (使用雙精度)，引數的正弦值。
Decimal	Decimal (使用雙精度)，引數的正弦值。
Boolean	Undefined.
String	Decimal (使用雙精度)，引數的正弦值。如果字串無法轉換為 Decimal，則結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
Undefined	Undefined.

sinh(Decimal)

以弧度傳回數字的雙曲正弦值。Decimal 值在套用函數前會四捨五入至雙精度。結果為雙精度的 Decimal 值。受 SQL 版本 2015-10-08 和更新版本支援。

範例：sinh(2.3) = 4.936961805545957

引數類型	結果
Int	Decimal (使用雙精度)，引數的雙曲正弦值。
Decimal	Decimal (使用雙精度)，引數的雙曲正弦值。
Boolean	Undefined.
String	Decimal (使用雙精度)，引數的雙曲正弦值。如果字串無法轉換為 Decimal，則結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

sourceip()

擷取裝置或與其連線之路由器的 IP 地址。如果您的裝置直接連線至網際網路，則此函數會傳回裝置的來源 IP 地址。如果您的裝置是連線到連線網際網路的路由器，則此函數會傳回路由器的來源 IP 地址。SQL 2016-03-23 版可支援。sourceip() 不會採用任何參數。

重要

裝置的公有來源 IP 地址通常是最後一個網路位址轉譯 (NAT) 閘道的 IP 地址，例如，您的網際網路服務供應商的路由器或有線數據機。

範例：

sourceip()="192.158.1.38"

sourceip()="1.102.103.104"

sourceip()="2001:db8:ff00::12ab:34cd"

SQL 範例：

SELECT *, sourceip() as deviceIp FROM 'some/topic'

如何在 AWS IoT Core 規則動作中使用 sourceip() 函數的範例：

範例 1

下列範例顯示如何在 DynamoDB 動作中呼叫 () 函數作為替換範本。

{
	"topicRulePayload": {
		"sql": "SELECT * AS message FROM 'some/topic'",
		"ruleDisabled": false,
		"awsIotSqlVersion": "2016-03-23",
		"actions": [
			{
				"dynamoDB": {
					"tableName": "my_ddb_table",
					"hashKeyField": "key",
					"hashKeyValue": "${sourceip()}",
					"rangeKeyField": "timestamp",
					"rangeKeyValue": "${timestamp()}",
					"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
				}
			}
		]
	}
}

範例 2

下列範例顯示如何使用替換範本新增 sourceip() 函數作為 MQTT 使用者屬性。

{
	"topicRulePayload": {
		"sql": "SELECT * FROM 'some/topic'",
		"ruleDisabled": false,
		"awsIotSqlVersion": "2016-03-23",
		"actions": [
			{
				"republish": {
					"topic": "${topic()}/republish",
					"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
					"headers": {
						"payloadFormatIndicator": "UTF8_DATA",
						"contentType": "rule/contentType",
						"correlationData": "cnVsZSBjb3JyZWxhdGlvbiBkYXRh",
						"userProperties": [
							{
								"key": "ruleKey1",
								"value": "ruleValue1"
							},
							{
								"key": "sourceip",
								"value": "${sourceip()}"
							}
						]
					}
				}
			}
		]
	}
}            

您可以從訊息中介裝置和基本擷取路徑傳遞至 AWS IoT Core 規則的訊息中擷取來源 IP 地址。您也可以擷取 IPv4 和 IPv6 訊息的來源 IP。來源 IP 顯示如下：

IPv6：yyyy:yyyy:yyyy::yyyy:yyyy

IPv4：xxx.xxx.xxx.xxx

注意

原始來源 IP 不會透過重新發布動作傳遞。

substring(String, Int[, Int])

預期 String 後有一或兩個 Int 值。若為 String 和單個 Int 引數，此函數會從所給的 String 索引 (從 0 開始，包含 0) 到 Int 的結尾傳回所給的 String 的子字串。若為 String 和兩個 Int 引數，該函數會傳回從第一個 String 索引引數 (從 0 開始，包含 0) 到第二個 Int 索引引數 (從 0 開始，不含 0) 所提供的所給 Int 的子字串。少於零的索引將設為零。比 String 長度還長的索引會設為 String 長度。至於第三個引數版本，如果第一個索引大於 (或等於) 第二個索引，則結果為空的 String。

 如果提供的引數不是 (字串、整數) 或 (字串、整數、整數)，則標準轉換會套用至該引數，以嘗試將那些引數轉換為正確類型。如果類型無法轉換，函數的結果即為 Undefined。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

substring("012345", 0) = "012345"。

substring("012345", 2) = "2345"。

substring("012345", 2.745) = "2345"。

substring(123, 2) = "3"。

substring("012345", -1) = "012345"。

substring(true, 1.2) = "true"。

substring(false, -2.411E247) = "false"。

substring("012345", 1, 3) = "12"。

substring("012345", -50, 50) = "012345"。

substring("012345", 3, 1) = "".

sql_version()

傳回此規則中指定的 SQL 版本。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

sql_version() = "2016-03-23"

sqrt(Decimal)

傳回數字的平方根。Decimal 引數在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：sqrt(9) = 3.0。

引數類型	結果
Int	引數的平方根。
Decimal	引數的平方根。
Boolean	Undefined.
String	引數的平方根。如果字串無法轉換為 Decimal，則結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

startswith(String, String)

傳回 Boolean，無論第一個字串引數的開頭是否為第二個引數。如果引數為 Null 或 Undefined，則結果為 Undefined。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

startswith("ranger","ran") = true

引數類型 1	引數類型 2	結果
String	String	無論第一個字串的開頭是否為第二個字串。
其他值	其他值	所有引數都將使用標準轉換規則轉換為字串。如果第一個字串的開頭是第二個字串，則傳回 true。如果引數為 Null 或 Undefined，則結果為 Undefined。

tan(Decimal)

以弧度傳回數字的正切值。Decimal 值在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：tan(3) = -0.1425465430742778

引數類型	結果
Int	Decimal (使用雙精度)，引數的正切值。
Decimal	Decimal (使用雙精度)，引數的正切值。
Boolean	Undefined.
String	Decimal (使用雙精度)，引數的正切值。如果字串無法轉換為 Decimal，則結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

tanh(Decimal)

以弧度傳回數字的雙曲正切值。Decimal 值在套用函數前會四捨五入至雙精度。受 SQL 版本 2015-10-08 和更新版本支援。

範例：tanh(2.3) = 0.9800963962661914

引數類型	結果
Int	Decimal (使用雙精度)，引數的雙曲正切值。
Decimal	Decimal (使用雙精度)，引數的雙曲正切值。
Boolean	Undefined.
String	Decimal (使用雙精度)，引數的雙曲正切值。如果字串無法轉換為 Decimal，則結果為 Undefined。
Array	Undefined.
物件	Undefined.
Null	Undefined.
未定義	Undefined.

time_to_epoch(String, String)

使用 time_to_epoch 函數將時間戳字串轉換為 Unix epoch 時間中的毫秒數。受 SQL 版本 2016-03-23 和更新版本支援。若要將毫秒轉換為格式化的時間戳記字串，請參閱 parse_time(String, Long[, String])。

time_to_epoch 函數預期下列引數：

timestamp

(字串) 自 Unix epoch 起要轉換為毫秒的時間戳記字串。如果時間戳記字串未指定時區，函數會使用 UTC 時區。

pattern

(字串) 遵循 JDK11 時間格式的日期/時間模式。

範例：

time_to_epoch("2020-04-03 09:45:18 UTC+01:00", "yyyy-MM-dd HH:mm:ss VV") = 1585903518000

time_to_epoch("18 December 2015", "dd MMMM yyyy") = 1450396800000

time_to_epoch("2007-12-03 10:15:30.592 America/Los_Angeles", "yyyy-MM-dd HH:mm:ss.SSS z") = 1196705730592

timestamp()

傳回從 1970 年 1 月 1 日星期四 00：00：00 國際標準時間 (UTC) 開始的目前時間戳記，如 AWS IoT 規則引擎所觀察。受 SQL 版本 2015-10-08 和更新版本支援。

範例：timestamp() = 1481825251155

topic(Decimal)

傳回觸發該規則的訊息要傳送至的主題。如果未指定參數，則傳回整個主題。Decimal 參數用於指定特定主題區段，並會使用 1 指定第一個區段。對於 topic foo/bar/baz，topic(1) 會傳回 foo，topic(2) 會傳回 bar，依此類推。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

topic() = "things/myThings/thingOne"

topic(1) = "things"

使用基本擷取時，topic() 函數無法使用主題的初始字首 ($aws/rules/rule-name)。例如，假定主題為：

$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights

topic() = "Buildings/Building5/Floor2/Room201/Lights"

topic(3) = "Floor2"

traceid()

傳回 MQTT 的追蹤 ID (UUID)，如果訊息不是透過 MQTT 傳送，則為 Undefined。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

traceid() = "12345678-1234-1234-1234-123456789012"

transform(String, Object, Array)

傳回物件的陣列，其中包含 Array 參數上 Object 參數的所指定轉換結果。

受 SQL 版本 2016-03-23 和更新版本支援。

字串

要使用的轉換模式。請參閱下表以取得支援的轉換模式，以及了解它們如何從 Object 和 Array 參數建立 Result。

物件

包含要套用至每個 Array 元素之屬性的物件。

陣列

Object 屬性套用至其中的物件陣列。

此陣列中的每個物件都對應於函數回應中的物件。函數回應中的每個物件都包含存在於原始物件的屬性，以及 Object 所提供的屬性，這是由 String 中指定的轉換模式所決定。

String 參數	Object 參數	Array 參數	結果
enrichArray	物件	物件的陣列	物件的陣列，其中每個物件都包含來自 Array 參數的元素屬性，以及 Object 參數的屬性。
任何其他值	任何值	任何值	未定義

注意

此函數傳回的陣列限制為 128 KiB。

轉換函數範例 1

此範例顯示 transform() 函數如何從一個資料物件和一個陣列產生單一物件陣列。

在此範例中，下列訊息會發佈至 MQTT 主題 A/B。

{
    "attributes": {
        "data1": 1,
        "data2": 2
    },
    "values": [
        {
            "a": 3
        },
        {
            "b": 4
        },
        {
            "c": 5
        }
    ]
}

主題規則動作的這個 SQL 陳述式會使用 transform() 函數與 enrichArray 的 String 值搭配。在此範例中，Object 是來自訊息承載的 attributes 屬性，而 Array 是 values 陣列，其中包含三個物件。

select value transform("enrichArray", attributes, values) from 'A/B'

在收到訊息承載時，SQL 陳述式會評估為下列回應。

[
  {
    "a": 3,
    "data1": 1,
    "data2": 2
  },
  {
    "b": 4,
    "data1": 1,
    "data2": 2
  },
  {
    "c": 5,
    "data1": 1,
    "data2": 2
  }
]

轉換函數範例 2

此範例顯示 transform() 函數如何使用文字值，以包含並重新命名來自訊息承載的個別屬性。

在此範例中，下列訊息會發佈至 MQTT 主題 A/B。這是用於 轉換函數範例 1 的同一則訊息。

{
    "attributes": {
        "data1": 1,
        "data2": 2
    },
    "values": [
        {
            "a": 3
        },
        {
            "b": 4
        },
        {
            "c": 5
        }
    ]
}

主題規則動作的這個 SQL 陳述式會使用 transform() 函數與 enrichArray 的 String 值搭配。transform() 函數中的 Object 在訊息承載中有一個名為 key 且值為 attributes.data1 的單一屬性，而 Array 是 values 陣列，其中包含上述範例中使用的三個物件。

select value transform("enrichArray", {"key": attributes.data1}, values) from 'A/B'

在收到訊息承載時，此 SQL 陳述式會評估為下列回應。請注意，data1 屬性在回應中名為 key。

[
  {
    "a": 3,
    "key": 1
  },
  {
    "b": 4,
    "key": 1
  },
  {
    "c": 5,
    "key": 1
  }
]

轉換函數範例 3

此範例顯示 transform() 函數如何用於巢狀 SELECT 子句中，以選取多個屬性並建立新的物件，以供後續處理。

在此範例中，下列訊息會發佈至 MQTT 主題 A/B。

{
  "data1": "example",
  "data2": {
    "a": "first attribute",
    "b": "second attribute",
    "c": [
      {
        "x": {
          "someInt": 5,
          "someString": "hello"
        },
        "y": true
      },
      {
        "x": {
          "someInt": 10,
          "someString": "world"
        },
        "y": false
      }
    ]
  }
}

此轉換函數的 Object 是 SELECT 陳述式傳回的物件，其中包含訊息 data2 物件的 a 和 b 元素。Array 參數由來自原始訊息中 data2.c 陣列的兩個物件組成。

select value transform('enrichArray', (select a, b from data2), (select value c from data2)) from 'A/B'

在收到上述訊息時，SQL 陳述式會評估為下列回應。

[
  {
    "x": {
      "someInt": 5,
      "someString": "hello"
    },
    "y": true,
    "a": "first attribute",
    "b": "second attribute"
  },
  {
    "x": {
      "someInt": 10,
      "someString": "world"
    },
    "y": false,
    "a": "first attribute",
    "b": "second attribute"
  }
]

此回應中傳回的陣列可與支援 batchMode 的主題規則動作搭配使用。

trim(String)

移除所給的 String 前方和後方所有空格。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

Trim(" hi ") = "hi"

引數類型	結果
Int	移除 Int 前方和後方所有空格的 String 顯示方式。
Decimal	移除 Decimal 前方和後方所有空格的 String 顯示方式。
Boolean	移除 Boolean (「true」或「false」) 前方和後方所有空格的 String 顯示方式。
String	移除前方和後方所有空格的 String。
陣列	Array (使用標準轉換規則) 的 String 顯示方式。
物件	Object (使用標準轉換規則) 的 String 顯示方式。
Null	Undefined.
未定義	Undefined.

trunc(Decimal, Int)

將第一個引數截為第二的引數所指定的 Decimal 位數。若第二個引數少於零，則它會設為零。若第二個引數大於 34，則它會設為 34。結果的結尾去掉了零。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

trunc(2.3, 0) = 2。

trunc(2.3123, 2) = 2.31。

trunc(2.888, 2) = 2.88。

trunc(2.00, 5) = 2。

引數類型 1	引數類型 2	結果
Int	Int	來源值。
Int/Decimal	Int/Decimal	第一個引數會截短為第二個引數所指定的長度。第二個引數如果不是 Int，則會無條件捨去至最接近的 Int。
Int/Decimal/String	Int/Decimal	第一個引數會截短為第二個引數所指定的長度。第二個引數如果不是 Int，則會無條件捨去至最接近的 Int。String 會轉換為 Decimal 值。如果字串轉換失敗，則結果為 Undefined。
其他值		Undefined.

upper(String)

傳回大寫版本的特定 String。非 String 引數都會使用標準轉換規則轉換為 String。受 SQL 版本 2015-10-08 和更新版本支援。

範例：

upper("hello") = "HELLO"

upper(["hello"]) = "[\"HELLO\"]"