AWS iot documentation change
Summary
Fixed URL formatting in substitution template and DynamoDB action links
Security assessment
URL corrections for documentation links have no security implications.
Diff
diff --git a/iot/latest/developerguide/iot-sql-functions.md b/iot/latest/developerguide/iot-sql-functions.md index dff9bc341..ed8d64b7f 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_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_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) @@ -727,0 +728,90 @@ The following example Rules SQL references any of the following MQTT5 headers: ` +## get_or_default(expression, defaultValue) + +Returns the default value in the second parameter if specified or else returns undefined, when the expression in the first parameter returns null, undefined, or fails. Supported by SQL version 2016-03-23 and later. + +###### Important + +`get_or_default` does not support non-JSON payloads directly as is. If you are using a non-JSON payload, use the `encode` or `decode` functions. + +`get_or_default()` takes the following parameters: + +expression + + +Any valid expression containing [Data types](./iot-sql-data-types.html), [Functions](./iot-sql-functions.html), [Literals](./iot-sql-literals.html), [Variables](./iot-sql-set.html#iot-sql-set-usage) [Nested object queries](./iot-sql-nested-queries.html), or [JSON extensions](./iot-sql-json.html). + +defaultValue + + +(Optional) Any valid expression containing [Data types](./iot-sql-data-types.html), [Functions](./iot-sql-functions.html), [Literals](./iot-sql-literals.html), [Variables](./iot-sql-set.html#iot-sql-set-usage) [Nested object queries](./iot-sql-nested-queries.html), or [JSON extensions](./iot-sql-json.html). This is the value to be returned whenever the first argument returns null, undefined, or fails. + +###### Note + +Functions that fetch data from customer owned resources, such as get_secret, get_dynamodb, aws_lambda, get_thing_shadow, decode-protobuf, and machinelearning_predict, are not allowed for the defaultValue parameter. + +The following table shows acceptable function arguments for each argument and their associated outputs: + +First argument | Second argument | Output +---|---|--- +Successful evaluation | Any value or not specified | The first argument value. +Undefined, Null, or failure | Any value including Undefined or Null | The second argument value. +Undefined, Null, or failure | not specified | `Undefined` + +**Examples:** + +Example 1: + +The following example provides a defaultValue value if a DynamoDB table or query fails: + + + SELECT + device_id, + get_or_default( + get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME"), + {"mode": "standard", "timeout": 30, "enabled": true } + ) as config + FROM 'device/telemetry' + + +Example 2: + +The following example provides a safe default value "UNKNOWN" if status is undefined: + + + SELECT + get_or_default( CASE status + WHEN 'active' THEN 'GOOD' + WHEN 'inactive' THEN 'BAD'/ + ELSE 'UNKNOWN' + END, 'UNKNOWN') as status_category + FROM 'topic/subtopic' + +Example 3: + +The following example shows how you can also use get_or_default with a single parameter. This is useful in scenarios where you may not have a clear default value, but you do not want your rule execution to fail. + + + SELECT + get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME") as config + FROM 'device/telemetry' + +If the DynamoDB lookup fails, the rule execution will fail, and no actions will be executed. If the following SQL is used instead: + + + SELECT + get_or_default(get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME")) as config + FROM 'device/telemetry' + +The get_or_default statement will evaluate to `Undefined`,so in this example the SELECT statement overall will evaluate to `{}` and any rule actions will be attempted. + +###### Important + +We recommend following these best practices to maintain security when using this function: + + * Avoid using hardcoded secrets in rule definitions including default values + + * Use AWS Secrets Manager for managing sensitive information + + + + @@ -1527 +1617 @@ Examples of how to use the sourceip() function in AWS IoT Core rule actions: -The following example shows how to call the () function as a [substitution template](https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html) in a [DynamoDB action](https://docs.aws.amazon.com/iot/latest/developerguide/dynamodb-rule-action.html). +The following example shows how to call the () function as a [substitution template](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) in a [DynamoDB action](https://docs.aws.amazon.com//iot/latest/developerguide/dynamodb-rule-action.html). @@ -1552 +1642 @@ The following example shows how to call the () function as a [substitution templ -The following example shows how to add the sourceip() function as an MQTT user property using [substitution templates](https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html). +The following example shows how to add the sourceip() function as an MQTT user property using [substitution templates](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html). @@ -1586 +1676 @@ The following example shows how to add the sourceip() function as an MQTT user p -You can retrieve the source IP address from messages passing to AWS IoT Core rules from both Message Broker and [Basic Ingest](https://docs.aws.amazon.com/iot/latest/developerguide/iot-basic-ingest.html) pathways. You can also retrieve the source IP for both IPv4 and IPv6 messages. The source IP will be displayed like the following: +You can retrieve the source IP address from messages passing to AWS IoT Core rules from both Message Broker and [Basic Ingest](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html) pathways. You can also retrieve the source IP for both IPv4 and IPv6 messages. The source IP will be displayed like the following: