函数 - Amazon IoT Core
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

函数

您可以使用 SQL 表达式的 SELECT 或 WHERE 子句中的以下内置函数。

abs(Decimal)

返回数字的绝对值。SQL 版本 2015-10-08 及更高版本支持。

示例:abs(-5) 返回 5。

参数类型 结果
Int Int,参数的绝对值。
Decimal Decimal,参数的绝对值。
Boolean Undefined.
String Decimal。结果是参数的绝对值。如果字符串无法转换,则结果为 Undefined
数组 Undefined.
对象 Undefined.
Null Undefined.
未定义 Undefined.

accountid()

String 形式返回拥有该规则的账户的 ID。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
数组 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
数组 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
数组 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。

您必须授予调用指定的 Lambda 函数的 Amazon IoT lambda:InvokeFunction权限。以下示例说明如何使用 Amazon 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

您的账户的。 Amazon Web Services 区域

--principal

获取权限的委托人。这应该是iot.amazonaws.com为了 Amazon IoT 允许调用 Lambda 函数。

--source-arn

规则的 ARN。您可以使用get-topic-rule Amazon CLI 命令获取规则的 ARN。

--source-account

规则 Amazon Web Services 账户 的定义位置。

--statement-id

唯一的语句标识符。

--action

要在此声明中允许的 Lambda 操作。要允许 Amazon IoT 调用 Lambda 函数,请指定 lambda:InvokeFunction

重要

如果您在不提供source-arn或的情况下为 Amazon IoT 委托人添加权限source-account,则任何 Amazon Web Services 账户 使用您的 Lambda 操作创建规则的人都可以触发规则,从中调用您的 Lambda 函数。 Amazon 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 从在主题“topic/subtopic”上发布的消息中选择数据。

some.value 从 Lambda 函数生成的输出中选择数据。

注意

规则引擎限制 Lambda 函数的执行持续时间。从规则执行的 Lambda 函数调用应在 2000 毫秒内完成。

bitand(Int, Int)

在两个 Int (转换成的) 参数的位表示之间逐位执行与运算。SQL 版本 2015-10-08 及更高版本支持。

示例:bitand(13, 5) = 5

参数类型 参数类型 结果
Int Int Int,对两个参数逐位执行与运算。
Int/Decimal Int/Decimal Int,对两个参数逐位执行与运算。所有非 Int 数字向下舍入至最近的 Int。如果任意参数不能转换为 Int,则结果为 Undefined
Int/Decimal/String Int/Decimal/String Int,对两个参数逐位执行与运算。所有字符串转换为小数并向下舍入至最近的 Int。如果转换失败,结果为 Undefined
其它值 其它值 Undefined.

bitor(Int, Int)

在两个参数的位表示之间逐位执行或运算。SQL 版本 2015-10-08 及更高版本支持。

示例:bitor(8, 5) = 13

参数类型 参数类型 结果
Int Int Int,对两个参数逐位执行或运算。
Int/Decimal Int/Decimal Int,对两个参数逐位执行或运算。所有非 Int 数字向下舍入至最近的 Int。如果转换失败,结果为 Undefined
Int/Decimal/String Int/Decimal/String Int,对两个参数逐位执行或运算。所有字符串转换为小数并向下舍入至最近的 Int。如果转换失败,结果为 Undefined
其它值 其它值 Undefined.

bitxor(Int, Int)

在两个 Int (转换成的) 参数的位表示之间逐位执行异或运算。SQL 版本 2015-10-08 及更高版本支持。

示例:bitor(13, 5) = 8

参数类型 参数类型 结果
Int Int Int,对两个参数逐位执行异或运算。
Int/Decimal Int/Decimal Int,对两个参数逐位执行异或运算。非 Int 数字向下舍入至最近的 Int
Int/Decimal/String Int/Decimal/String Int,对两个参数逐位执行异或运算。字符串转换为小数并向下舍入到最近的 Int。如果任何转换失败,结果为 Undefined
其它值 其它值 Undefined.

bitnot(Int)

Int (转换成的) 参数的位表示逐位执行非运算。SQL 版本 2015-10-08 及更高版本支持。

示例:bitnot(13) = 2

参数类型 结果
Int Int,对参数逐位执行非运算。
Decimal Int,对参数逐位执行非运算。Decimal 值会向下舍入至最近的 Int
String Int,对参数逐位执行非运算。字符串转换为小数值并向下舍入至最近的 Int。如果任何转换失败,结果为 Undefined
其它值 其它值。

cast()

将值从一个数据类型转换为另一个数据类型。强制转换与标准转换大体相同,但是增加了在数字与布尔值之间进行强制转换的能力。如果 Amazon IoT 无法确定如何将一种类型转换为另一种类型,则结果为Undefined。SQL 版本 2015-10-08 及更高版本支持。格式:cast( as 类型)。

例如:

cast(true as Int) = 1

在调用 cast 时,“as”后面可能出现以下关键字:

对于 SQL 版本 2015-10-08 和 2016-03-23
Keyword 结果
String 将值强制转换为 String
Nvarchar 将值强制转换为 String
文本 将值强制转换为 String
Ntext 将值强制转换为 String
varchar 将值强制转换为 String
Int 将值强制转换为 Int
整数 将值强制转换为 Int
Double 将值强制转换为 Decimal(双精度)。
此外,对于 SQL 版本 2016-03-23
Keyword 结果
Decimal 将值强制转换为 Decimal
布尔型 将值强制转换为 Boolean
Boolean 将值强制转换为 Boolean

强制转换规则:

强制转换为 decimal
参数类型 结果
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。 Amazon IoT 会尝试解析与正则表达式相匹配的字符串:^-?\d+(\.\d+)?((?i)E-?\d+)?$。可自动转换为小数的字符串示例包括 "0"、"-1.2"、"5E-12"。
数组 Undefined.
对象 Undefined.
Null Undefined.
未定义 Undefined.
强制转换为 int
参数类型 结果
Int 源值。
Decimal 源值,向下舍入到最近的 Int
Boolean true = 1.0,false = 0.0。
String 尝试将字符串解析为 Decimal。 Amazon IoT 会尝试解析与正则表达式相匹配的字符串:^-?\d+(\.\d+)?((?i)E-?\d+)?$。可自动转换为小数的字符串示例包括 "0"、"-1.2"、"5E-12"。Int 尝试将字符串转换为 Amazon IoT ,然后向下舍入到最近的 Decimal
数组 Undefined.
对象 Undefined.
Null Undefined.
未定义 Undefined.
强制转换为 Boolean
参数类型 结果
Int 0 = False,任何非零值 = True。
Decimal 0 = False,任何非零值 = True。
Boolean 源值。
String "true" = True 和 "false" = False(不区分大小写)。其它字符串值 = Undefined
数组 Undefined.
对象 Undefined.
Null Undefined.
未定义 Undefined.
强制转换为 string
参数类型 结果
Int 标准表示法中 Int 的字符串表示形式。
Decimal 科学表示法中 Decimal 值的字符串表示。
Boolean "true" 或 "false",全小写。
String "true"=True 和 "false"=False (不区分大小写)。其它字符串值 = Undefined
数组 数组序列化为 JSON。结果字符串为逗号分隔的列表,括在方括号中。 String 带引号。 DecimalIntBoolean 不带引号。
对象 序列化为 JSON 的对象。JSON 字符串为键值对的逗号分隔列表,以大括号开头和结束。String 带引号。DecimalIntBooleanNull 不带引号。
Null Undefined.
未定义 Undefined.

ceil(Decimal)

将给定的 Decimal 向上舍入到最近的 Int。SQL 版本 2015-10-08 及更高版本支持。

示例:

ceil(1.2) = 2

ceil(-1.2) = -1

参数类型 结果
Int Int,参数值。
Decimal IntDecimal 值向上舍入到最近的 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
数组 Undefined.
对象 Undefined.
Null Undefined.
其它值 Undefined.

clientid()

返回发送消息的 MQTT 客户端的 ID,如果未通过 MQTT 发送消息,则返回 n/a。SQL 版本 2015-10-08 及更高版本支持。

例如:

clientid() = "123456789012"

concat()

联接数组或字符串。该函数可接受任意数量的参数,并返回 StringArray。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
数组 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
数组 Undefined.
对象 Undefined.
Null Undefined.
未定义 Undefined.

解码(值,decodingScheme)

使用 decode 函数来解码一个编码的值。如果解码字符串为 JSON 文档,则返回可寻址对象。否则,解码字符串会返回为字符串。如果字符串无法解码,则函数返回 NULL。此函数支持解码 base64 编码的字符串和协议缓冲区 (protobuf) 消息格式。

SQL 版本 2016-03-23 及更高版本支持。

value

字符串值或任何有效的表达式,如 Amazon 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 消息有效负载

此函数签名类似以下内容:

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

    FileDescriptorSet 文件存储在名为 s3-bucket 的 Amazon S3 存储桶中。

  • myproto

    用于生成名为 myproto.protoFileDescriptorSet 文件的原始 .proto 文件。

  • messagetype

    myproto.proto 中定义的名为 messagetype 的消息类型(以及任何导入的依赖项)。

encode(value, encodingScheme)

根据编码方案,使用 encode 函数将负载(可能是非 JSON 数据)编码为字符串表示形式。SQL 版本 2016-03-23 及更高版本支持。

value

Amazon IoT SQL 参考 中所定义的任何有效的表达式。您可以指定 * 以对整个负载进行编码,无论它是否为 JSON 格式。如果您提供了表达式,评估的结果将在编码之前转换为字符串。

encodingScheme

代表您要使用的编码方案的文字字符串。目前仅支持 'base64'

endswith(String, String)

返回 Boolean 来表示第一个 String 参数是否以第二个 String 参数结尾。如果任一参数为 NullUndefined,则结果为 Undefined。SQL 版本 2015-10-08 及更高版本支持。

示例:endswith("cat","at") = true。

参数类型 1 参数类型 2 结果
String String 如果第一个参数以第二个参数结尾,则为 true。否则为 false。
其它值 其它值 两个参数都使用标准转换规则转换为字符串。如果第一个参数以第二个参数结尾,则为 true。否则为 false。如果任一参数为 NullUndefined,则结果为 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 IntDecimal 值会向下舍入至最接近的 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 的范围 (负值或大于等于数组长度),则结果为 Undefined
字符串 任何类型 (转换为 Int) 在第二个参数 (已经转换为 Int) 提供的字符串中,从零开始索引得到的字符。如果转换已不成功,结果为 Undefined。如果索引超出字符串的范围 (负值或大于等于字符串长度),则结果为 Undefined
对象 String (不进行转换) 第一个参数对象中存储的值与作为第二个参数提供的字符串键相对应。
其它值 任意值 Undefined.

get_dynamodb(tableName、、、、、roLearn partitionKeyName) partitionKeyValue sortKeyName sortKeyValue

从 DynamoDB 表中检索数据。get_dynamodb() 可让您在计算规则时查询 DynamoDB 表。您可以使用从 DynamoDB 中检索到的数据筛选或增加消息负载。SQL 版本 2016-03-23 及更高版本支持。

get_dynamodb() 接受以下参数:

tableName

要查询的 DynamoDB 表的名称。

partitionKeyName

分区键的名称。有关更多信息,请参阅 DynamoDB Keys

partitionKeyValue

用于标识记录的分区键的值。有关更多信息,请参阅 DynamoDB Keys

sortKeyName

(可选)排序键的名称。仅当查询的 DynamoDB 表使用复合键时需要此参数。有关更多信息,请参阅 DynamoDB Keys

sortKeyValue

(可选)排序键的值。仅当查询的 DynamoDB 表使用复合键时需要此参数。有关更多信息,请参阅 DynamoDB Keys

roleArn

授予对 DynamoDB 表的访问权限的 IAM 角色的 ARN。规则引擎将承担此角色以代表您访问 DynamoDB 表。避免使用过于宽容的角色。仅向角色授予规则所需的那些权限。以下是授予对一个 DynamoDB 表的访问权限的示例策略。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "dynamodb:GetItem", "Resource": "arn:aws:dynamodb:aws-region:account-id:table/table-name" } ] }}

举例说明您如何使用 get_dynamodb(),例如您有一个 DynamoDB 表,其中包含连接到 Amazon 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(name)

引用以下任何 MQTT5 标头:contentTypepayLoadFormatIndicatorresponseTopiccorrelationData。此函数将以下任何文字字符串作为参数:content_typeformat_indicatorresponse_topiccorrelation_data。有关更多信息,请参阅以下函数参数表。

contentType

字符串:一个 UTF-8 编码的字符串,用于描述发布消息的内容。

payLoadFormat指示器

字符串:一个枚举字符串值,指示有效负载是否格式化为 UTF-8。有效值为 UNSPECIFIED_BYTESUTF8_DATA

responseTopic

字符串:一个 UTF-8 编码的字符串,用作响应消息的主题名称。响应主题用于描述接收方应作为请求/响应流程的一部分发布到的主题。主题不得包含通配符。

correlationData

字符串:请求消息的发送方使用 base64 编码的二进制数据来识别收到响应消息时响应消息的请求。

下表显示了可接受的函数参数,及其与 get_mqtt_property 函数相关的返回类型:

函数参数
SQL 返回的数据类型(如果存在) 返回的数据类型(如果不存在)
get_mqtt_property("format_indicator") 字符串(UNSPECIFIED_BYTES 或 UTF8_DATA) 字符串 (UNSPECIFIED_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 标头:contentTypepayLoadFormatIndicatorresponseTopiccorrelationData

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)

Amazon Secrets Manager 中检索密钥当前版本的加密 SecretString 或者 SecretBinary字段中的值。有关创建和维护密钥的更多信息,请参阅CreateSecretUpdateSecret、和PutSecretValue

get_secret() 接受以下参数:

secretId

字符串:要检索的密钥的 Amazon Resource Name (ARN) 或友好名称。

secretType

字符串:密钥类型。有效值:SecretString | SecretBinary

SecretString
  • 对于您使用 API、或 Amazon Secrets Manager 控制台创建为 JSON 对象的密钥: Amazon CLI

    • 如果为 key 参数指定值,则函数返回指定键的值。

    • 如果您没有为 key 参数指定值,则函数将返回整个 JSON 对象。

  • 对于通过使用 API 或 Amazon CLI 创建的非 JSON 对象:

    • 如果为 key 参数指定值,则函数失败并出现异常。

    • 如果您没有为 key 参数指定值,则函数返回密钥的内容。

SecretBinary
  • 如果为 key 参数指定值,则函数失败并出现异常。

  • 如果您没有为 key 参数指定值,则函数将密钥值作为 base64 编码 UTF-8 字符串返回。

key

(可选)字符串:存储在密钥的 SecretString 字段中的 JSON 对象里的键名称。如果您希望仅检索存储在密钥中而不是整个 JSON 对象中的键值,请使用此值。

如果您为此参数指定了一个值,而密钥的 SecretString 字段中不包含 JSON 对象,此函数将失败并出现异常。

roleArn

String:具有 secretsmanager:GetSecretValuesecretsmanager:DescribeSecret 权限的角色 ARN。

注意

此函数始终返回密钥的当前版本(带有 AWSCURRENT 标签的版本)。 Amazon IoT 规则引擎将每个密钥缓存最多 15 分钟。因此,规则引擎最多可能需要 15 分钟才能更新密钥。这意味着,如果您在更新后最多 15 分钟内检索到密钥 Amazon Secrets Manager,则此函数可能会返回之前的版本。

此功能不是按流量计费的,但会 Amazon Secrets Manager 收费。由于密钥缓存机制,规则引擎偶尔会调用 Amazon 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

String:您要检索其影子的事物的名称。

shadowName

(可选)字符串:影子的名称。只有在引用命名的影子时,才需要使用该参数。

roleArn

String:具有 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'

获取用户属性 () userPropertyKey

引用用户属性,这是 MQTT5 中支持的一种类型的属性标头。

userProperty

字符串:用户属性是一个键-值对。此函数将键作为参数,并返回与关联的键匹配的所有值的数组。

函数参数

对于邮件标题中的以下用户属性:

某个键 某个值
其他键 其他值
某个键 带有重复键的值

下表显示了预期的 SQL 行为:

SQL 返回的数据类型 返回的数据值
get_user_properties('some key') 字符串数组 ['some value', 'value with duplicate key']
get_user_properties('other key') 字符串数组 ['a different value']
get_user_properties( ) 键值对对象的数组 [{'"some key": "some value"'}, {"other key": "a different value"}, {"some key": "value with duplicate key"}]
get_user_properties('non-existent key') 未定义

以下示例规则 SQL 将用户属性(一种类型的 MQTT5 属性标头)引用到有效负载中:

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

哈希函数

Amazon IoT 提供以下哈希函数:

  • md2

  • md5

  • sha1

  • sha224

  • sha256

  • sha384

  • sha512

所有哈希函数都可以输入一个字符串参数。结果为该字符串的哈希值。对非字符串参数进行标准字符串转换。所有哈希函数在 SQL 版本 2015-10-08 及更高版本中均受支持。

示例:

md2("hello") = "a9046c73e00331af68917d3804f70655"

md5("hello") = "5d41402abc4b2a76b9719d911017c592"

indexof(String, String)

返回第二个参数的第一个索引 (从零开始) 作为第一个参数的子字符串。两个参数均为字符串。如果参数数据类型不是字符串,则应用标准字符串转换规则进行转换。此函数只对字符串有效,不适用于数组。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
数组 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
数组 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,然后对该 String 应用 LPAD 函数。如果它无法转换,则结果为 Undefined
任意值 其它值 Undefined.

ltrim(String)

从提供的 String 中删除所有前导空白(制表符和空格)。SQL 版本 2015-10-08 及更高版本支持。

例如:

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

参数类型 结果
Int 删除了所有前导空白的 IntString 表示形式。
Decimal 删除了所有前导空白的 DecimalString 表示形式。
Boolean 布尔值(“true”或“false”)在删除所有前导空格之后的 String 表示形式。
String 删除所有前导空白之后的参数。
数组 Array(使用标准转换规则)在删除所有前导空白之后的 String 表示形式。
对象 对象(使用标准转换规则)在删除所有前导空白之后的 String 表示形式。
Null Undefined.
未定义 Undefined.

machinelearning_predict(modelId, roleArn, record)

使用该machinelearning_predict函数使用基于 Amazon SageMaker 模型的 MQTT 消息中的数据进行预测。SQL 版本 2015-10-08 及更高版本支持。machinelearning_predict 函数的参数如下:

modelId

对其运行预测的模型的 ID。必须启用模型的实时终端节点。

roleArn

IAM 角色,拥有具备 machinelearning:Predictmachinelearning:GetMLModel 权限的策略并允许访问运行预测所针对的模型。

记录

要传递到 Pred SageMaker ict API 的数据。该参数应表示为单层 JSON 对象。如果记录是多级 JSON 对象,该记录将通过序列化其值来进行平展。例如,以下 JSON:

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

会变为:

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

该函数返回具有以下字段的 JSON 对象:

predictedLabel

基于模型的输入分类。

details

包含以下属性:

PredictiveModelType

模型类型。有效值为 REGRESSION、BINARY、MULTICLASS。

算法

用于进行预测 SageMaker 的算法。该值必须为 SGD。

predictedScores

包含与每个标签对应的原始分类分数。

predictedValue

预测的值 SageMaker。

mod(Decimal, Decimal)

返回第一个参数除以第二个参数的余数。等效于 remainder(Decimal, Decimal)。您还可以使用“%”作为相同取模功能的插入运算符。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 函数采用下列参数:

模式

(字符串)遵循 Joda 时间格式的日期/时间模式。

时间戳

(Long) 要采用自 Unix 纪元时间以来的毫秒数格式表示的时间。请参阅函数 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()

返回设备用于身份验证的委托人,取决于触发消息的发布方式。下表介绍了为每个发布方法和协议返回的委托人。

消息的发布方式 协议 凭证类型 主体
MQTT 客户端 MQTT X.509 设备证书 X.509 证书指纹
Amazon IoT 控制台 MQTT 客户端 MQTT IAM 用户或角色 iam-role-id: 会话名称
Amazon CLI HTTP IAM 用户或角色 userid
Amazon IoT 设备软件开发工具包 MQTT X.509 设备证书 X.509 证书指纹
Amazon IoT 设备软件开发工具包 MQTT 结束了 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 StringInt 表示形式。
Decimal StringDecimal 表示形式。
Boolean 布尔值(“true”或“false”)的 String 表示形式。
String String
数组 Array (使用标准转换规则) 的 String 表示形式。
对象 对象 (使用标准转换规则) 的 String 表示形式。
Null Undefined.
未定义 Undefined.

第二个参数:

必须是有效的正则表达式。非字符串类型使用标准转换规则转换为 String。根据类型,生成的字符串可能不是有效的正则表达式。如果(转换后的)参数不是有效的正则表达式,则结果为 Undefined

regexp_replace(String, String, String)

用第三个参数替换在第一个参数中出现的所有第二个参数 (正则表达式)。用“$”引用捕获组。SQL 版本 2015-10-08 及更高版本支持。

例如:

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

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

第一个参数:
参数类型 结果
Int StringInt 表示形式。
Decimal StringDecimal 表示形式。
Boolean 布尔值(“true”或“false”)的 String 表示形式。
String 源值。
数组 Array (使用标准转换规则) 的 String 表示形式。
对象 对象 (使用标准转换规则) 的 String 表示形式。
Null Undefined.
未定义 Undefined.

第二个参数:

必须是有效的正则表达式。非字符串类型使用标准转换规则转换为 String。根据类型,生成的字符串可能不是有效的正则表达式。如果(转换后的)参数不是有效的正则表达式,则结果为 Undefined

第三个参数:

必须是有效的正则表达式替代字符串。(可以引用捕获组。) 非字符串类型使用标准转换规则转换为 String。如果(转换后的)参数不是有效的正则表达式替代字符串,则结果为 Undefined

regexp_substr(String, String)

在第一个参数中查找第二个参数(正则表达式)的第一个匹配项。用“$”引用捕获组。SQL 版本 2015-10-08 及更高版本支持。

例如:

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

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

第一个参数:
参数类型 结果
Int StringInt 表示形式。
Decimal StringDecimal 表示形式。
Boolean 布尔值(“true”或“false”)的 String 表示形式。
String String 参数。
数组 Array (使用标准转换规则) 的 String 表示形式。
对象 对象 (使用标准转换规则) 的 String 表示形式。
Null Undefined.
未定义 Undefined.

第二个参数:

必须是有效的正则表达式。非字符串类型使用标准转换规则转换为 String。根据类型,生成的字符串可能不是有效的正则表达式。如果(转换后的)参数不是有效的正则表达式,则结果为 Undefined

remainder(Decimal, Decimal)

返回第一个参数除以第二个参数的余数。等效于 mod(Decimal, Decimal)。您还可以使用“%”作为相同取模功能的插入运算符。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 StringInt 表示形式。
Decimal StringDecimal 表示形式。
Boolean 布尔值(“true”或“false”)的 String 表示形式。
String 源值。
数组 Array (使用标准转换规则) 的 String 表示形式。
对象 对象 (使用标准转换规则) 的 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,然后对该 String 应用 rpad 函数。如果它无法转换,则结果为 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 中删除所有尾随空白(制表符和空格)。SQL 版本 2015-10-08 及更高版本支持。

示例:

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

参数类型 结果
Int StringInt 表示形式。
Decimal StringDecimal 表示形式。
Boolean 布尔值(“true”或“false”)的 String 表示形式。
数组 Array (使用标准转换规则) 的 String 表示形式。
对象 对象 (使用标准转换规则) 的 String 表示形式。
Null Undefined.
未定义 Undefined

sign(Decimal)

返回给定数字的符号。当参数的符号为正时,将返回 1。当参数的符号为负时,将返回 -1。如果参数为 0,则返回 0。SQL 版本 2015-10-08 及更高版本支持。

示例:

sign(-7) = -1。

sign(0) = 0。

sign(13) = 1。

参数类型 结果
Int IntInt 值的符号。
Decimal IntDecimal 值的符号。
String IntDecimal 值的符号。字符串将转换为 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
数组 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
数组 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'

如何在 Amazon 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()}" } ] } } } ] } }

您可以从消息代理和基本收录路径中传递给 Amazon 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 中从指定的 Int 索引 (从零开始,包括零) 到 String 结束提取子字符串并返回。对于 String 和两个 Int 参数,此函数在输入的 String 中从第一个 Int 索引参数 (从零开始,包括零) 到第二个 Int 索引参数 (从零开始,包括零) 提取子字符串并返回。索引小于零时将设置为零。大于 String 长度的索引设置为 String 长度。在三个参数的版本中,如果第一个索引大于等于第二个索引,那么结果为空 String

 如果提供的参数不是 (StringInt) 或 (StringIntInt),则系统会对参数进行标准转换,尽量将其转换为正确的类型。如果无法转换类型,函数的结果为 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) = "rue"。

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
数组 Undefined.
对象 Undefined.
Null Undefined.
未定义 Undefined.

startswith(String, String)

返回显示第一个字符串参数是否以第二个字符串参数开头的 Boolean。如果任一参数为 NullUndefined,则结果为 Undefined。SQL 版本 2015-10-08 及更高版本支持。

例如:

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

参数类型 1 参数类型 2 结果
String String 第一个字符串是否以第二个字符串开头。
其它值 其它值 两个参数都使用标准转换规则转换为字符串。如果第一个字符串以第二个字符串开头,则返回 true。如果任一参数为 NullUndefined,则结果为 Undefined

tan(Decimal)

以弧度为单位返回数字的正切值。在代入函数之前,Decimal 值舍入到双精度。SQL 版本 2015-10-08 及更高版本支持。

示例:tan(3) = -0.1425465430742778

参数类型 结果
Int Decimal (双精度),参数的正切值。
Decimal Decimal (双精度),参数的正切值。
Boolean Undefined.
String Decimal (双精度),参数的正切值。如果字符串无法转换为 Decimal,则结果为 Undefined
数组 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
数组 Undefined.
对象 Undefined.
Null Undefined.
未定义 Undefined.

time_to_epoch(String, String)

使用 time_to_epoch 函数将时间戳字符串转换为 Unix 纪元时间的毫秒数。SQL 版本 2016-03-23 及更高版本支持。要将毫秒转换为格式化的时间戳字符串,请参阅 parse_time(String, Long[, String])

time_to_epoch 函数采用下列参数:

时间戳

(字符串)要转换为自 Unix 纪元以来毫秒数的时间戳字符串。如果时间戳字符串未指定时区,则函数将使用 UTC 时区。

模式

(字符串)遵循 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 日星期四协调世界时 (UTC) 00:00:00 开始的当前时间戳(以毫秒为单位)。 Amazon IoT SQL 版本 2015-10-08 及更高版本支持。

示例:timestamp() = 1481825251155

topic(Decimal)

返回已向其发送触发规则的消息的主题。如果未指定参数,则返回整个主题。Decimal 参数用于指定特定主题段,使用 1 指定第一个段。对于主题 foo/bar/baz,主题 (1) 将返回 foo,主题 (2) 将返回 bar,以此类推。SQL 版本 2015-10-08 及更高版本支持。

示例:

topic() = "things/myThings/thingOne"

topic(1) = "things"

在使用基本提取功能时,主题的初始前缀 ($aws/rules/rule-name) 对 topic() 函数不可用。例如,给定以下主题:

$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)

返回对象数组,其中包含 Object 参数对 Array 参数的指定转换结果。

SQL 版本 2016-03-23 及更高版本支持。

字符串

要使用的转换模式。有关支持的转换模式以及这些模式如何利用 ObjectArray 参数创建 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 语句使用 String 值为 enrichArraytransform() 函数。在本例中,Object 是来自消息负载的 attributes 属性,而 Arrayvalues 数组,其中包含三个对象。

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 语句使用 String 值为 enrichArraytransform() 函数。transform() 函数中的 Object 在消息负载中具有一个名为 key 的单一属性,该属性的值为 attributes.data1,而 Arrayvalues 数组,其中包含与上一个示例中使用的三个相同对象。

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 对象的 ab 元素。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 表示形式。
对象 对象使用标准转换规则进行转换后的 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,将向下舍入至最近的 IntString 转换为 Decimal 值。如果字符串转换失败,则结果为 Undefined
其它值 Undefined.

upper(String)

返回给定 String 的大写版本。非 String 参数将使用标准转换规则转换为 String。SQL 版本 2015-10-08 及更高版本支持。

示例:

upper("hello") = "HELLO"

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