AWS iot documentation change
Summary
Added get_registry_data function documentation and updated security notes
Security assessment
Documents a new function with IAM role requirements but does not address vulnerabilities. The security documentation focuses on proper permission configuration.
Diff
diff --git a/iot/latest/developerguide/iot-sql-functions.md b/iot/latest/developerguide/iot-sql-functions.md index ed8d64b7f..648be2de7 100644 --- a//iot/latest/developerguide/iot-sql-functions.md +++ b//iot/latest/developerguide/iot-sql-functions.md @@ -5 +5 @@ -abs(Decimal)accountid()acos(Decimal)asin(Decimal)atan(Decimal)atan2(Decimal, Decimal)aws_lambda(functionArn, inputJson)bitand(Int, Int)bitor(Int, Int)bitxor(Int, Int)bitnot(Int)cast()ceil(Decimal)chr(String)clientid()concat()cos(Decimal)cosh(Decimal)decode(value, decodingScheme)encode(value, encodingScheme)endswith(String, String)exp(Decimal)floor(Decimal)getget_dynamodb(tableName, partitionKeyName, partitionKeyValue, sortKeyName, sortKeyValue, roleArn)get_mqtt_property(name)get_or_default(expression, defaultValue)get_secret(secretId, secretType, key, roleArn)get_thing_shadow(thingName, shadowName, roleARN)get_user_properties(userPropertyKey)Hashing functionsindexof(String, String)isNull()isUndefined()length(String)ln(Decimal)log(Decimal)lower(String)lpad(String, Int)ltrim(String)machinelearning_predict(modelId, roleArn, record)mod(Decimal, Decimal)nanvl(AnyValue, AnyValue)newuuid()numbytes(String)parse_time(String, Long[, String])power(Decimal, Decimal)principal()rand()regexp_matches(String, String)regexp_replace(String, String, String)regexp_substr(String, String)remainder(Decimal, Decimal)replace(String, String, String)rpad(String, Int)round(Decimal)rtrim(String)sign(Decimal)sin(Decimal)sinh(Decimal)sourceip()substring(String, Int[, Int])sql_version()sqrt(Decimal)startswith(String, String)tan(Decimal)tanh(Decimal)time_to_epoch(String, String)timestamp()topic(Decimal)traceid()transform(String, Object, Array)trim(String)trunc(Decimal, Int)upper(String) +abs(Decimal)accountid()acos(Decimal)asin(Decimal)atan(Decimal)atan2(Decimal, Decimal)aws_lambda(functionArn, inputJson)bitand(Int, Int)bitor(Int, Int)bitxor(Int, Int)bitnot(Int)cast()ceil(Decimal)chr(String)clientid()concat()cos(Decimal)cosh(Decimal)decode(value, decodingScheme)encode(value, encodingScheme)endswith(String, String)exp(Decimal)floor(Decimal)getget_dynamodb(tableName, partitionKeyName, partitionKeyValue, sortKeyName, sortKeyValue, roleArn)get_mqtt_property(name)get_or_default(expression, defaultValue)get_registry_data(registryAPI, thingName, roleArn)get_secret(secretId, secretType, key, roleArn)get_thing_shadow(thingName, shadowName, roleArn)get_user_properties(userPropertyKey)Hashing functionsindexof(String, String)isNull()isUndefined()length(String)ln(Decimal)log(Decimal)lower(String)lpad(String, Int)ltrim(String)machinelearning_predict(modelId, roleArn, record)mod(Decimal, Decimal)nanvl(AnyValue, AnyValue)newuuid()numbytes(String)parse_time(String, Long[, String])power(Decimal, Decimal)principal()rand()regexp_matches(String, String)regexp_replace(String, String, String)regexp_substr(String, String)remainder(Decimal, Decimal)replace(String, String, String)rpad(String, Int)round(Decimal)rtrim(String)sign(Decimal)sin(Decimal)sinh(Decimal)sourceip()substring(String, Int[, Int])sql_version()sqrt(Decimal)startswith(String, String)tan(Decimal)tanh(Decimal)time_to_epoch(String, String)timestamp()topic(Decimal)traceid()transform(String, Object, Array)trim(String)trunc(Decimal, Int)upper(String) @@ -10,0 +11,2 @@ You can use the following built-in functions in the SELECT or WHERE clauses of y +The following external functions are billed equivalent to that of a rule action: [`aws_lambda`](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda), [`get_dynamodb()`](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb), [`get_registry_data()`](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data), and [`get_thing_shadow()`](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow). You also get billed for the [`decode()`](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64) function only when you are [decoding a Protobuf message to JSON](https://docs.aws.amazon.com//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf). For more details, refer to the [AWS IoT Core pricing page](https://aws.amazon.com/iot-core/pricing/). + @@ -817,0 +820,48 @@ We recommend following these best practices to maintain security when using this +## get_registry_data(registryAPI, thingName, roleArn) + +Retrieves AWS IoT thing registry data in an AWS IoT rule. You can read registry data (such as attributes, thing type, and thing groups a device belongs to) and use this information to filter, enrich, or dynamically route messages. Supported by SQL version 2016-03-23 and later. + +`get_registry_data()` takes the following parameters: + +registryAPI + + +The registry API being called. Valid values are `DescribeThing` and `ListThingGroupsForThing`. These values must be constant strings. + +thingName + + +String: The name of the thing whose registry data you want to retrieve. + +roleArn + + +String: A role ARN with `iot:DescribeThing` permission and/or `iot:ListThingGroupsForThing` permission based on the API being called. + +The response format of the `get_registry_data` function is the same as the registry API called. For more information, see the [DescribeThing](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeThing.html) and [ListThingGroupsForThing](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingGroupsForThing.html) APIs. + +Example: + +You can retrieve thing type information to allow filtering the AWS IoT Core lifecycle event messages for things (with the thing name matching the MQTT client id) where thing type is `testenv`. + + + SELECT * + FROM '$aws/events/lifecycle/+' + WHERE + get_registry_data("DescribeThing",clientId,[roleArn]).thingTypeName='testenv' + +Example: + +You can retrieve thing attributes for a device with thing name `sensor1` for all messages sent by its gateway device `gateway1`. + + + SELECT *, get_registry_data("DescribeThing","sensor1",[roleArn]).attributes.temperature_threhold AS device1_tempthreshold + FROM home1/gateway1/sensor1/# + +###### Note + + * You can call `get_registry_data()` a maximum of one time per SQL statement and substitution templates for actions and error actions. + + + + @@ -890 +940 @@ For more information about the HTTPS rule action, see [HTTP](./https-rule-action -## get_thing_shadow(thingName, shadowName, roleARN) +## get_thing_shadow(thingName, shadowName, roleArn)