Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Reglas para AWS IoT
Las reglas permiten que tus dispositivos interactúen con ellas Servicios de AWS. Las reglas se analizan y las acciones se ejecutan en función del flujo de temas MQTT. Puede utilizar reglas para realizar las siguientes tareas:
+ Incrementar o filtrar los datos recibidos desde un dispositivo.
+ Escribir los datos recibidos de un dispositivo en una base de datos de Amazon DynamoDB.
+ Guardar un archivo en Amazon S3.
+ Enviar una notificación push a todos los usuarios que utilicen Amazon SNS.
+ Publicar datos en una cola de Amazon SQS.
+ Invocar una función de Lambda para extraer datos.
+ Procese mensajes de un gran número de dispositivos utilizando Amazon Kinesis.
+ Envía datos a Amazon OpenSearch Service.
+ Captura una CloudWatch métrica.
+ Cambia una CloudWatch alarma.
+ Envíe los datos de un mensaje MQTT a Amazon SageMaker AI para realizar predicciones basadas en un modelo de aprendizaje automático (ML).
+ Enviar un mensaje a un flujo de entrada de Salesforce IoT
+ Iniciar un proceso de una máquina de estado de funciones escalonadas.
+ Envíe los datos del mensaje a una AWS IoT Events entrada.
+ Enviar datos de mensaje de una propiedad de recurso de AWS IoT SiteWise.
+ Envíe datos de mensaje a una aplicación o servicio web.
Sus reglas pueden usar mensajes MQTT que pasen por el publish/subscribe [Protocolos de comunicación de dispositivos](protocols.md) protocolo compatible con. [También puede utilizar la función de [ingesta básica](iot-basic-ingest.md) para enviar de forma segura los datos del dispositivo a los Servicios de AWS listados anteriormente, sin incurrir en gastos de mensajería.](https://aws.amazon.com/iot-core/pricing/) La función [de ingesta básica](iot-basic-ingest.md) optimiza el flujo de datos al eliminar el agente de publish/subscribe mensajes de la ruta de ingesta. Esto hace que sea rentable y, al mismo tiempo, mantenga las funciones de seguridad y procesamiento de datos de. AWS IoT
Antes de AWS IoT poder realizar estas acciones, debes concederle permiso para acceder a tus AWS recursos en tu nombre. Cuando se realicen las acciones, incurrirá en los cargos estándar por las Servicios de AWS que utilice.
**Topics**
+ [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md)
+ [Transmisión de los permisos de rol](pass-role.md)
+ [Crear una AWS IoT regla](iot-create-rule.md)
+ [Administrar una regla AWS IoT](iot-managae-rule.md)
+ [AWS IoT acciones de reglas](iot-rule-actions.md)
+ [Solución de problemas de las reglas](#iot-troubleshoot-rule)
+ [Acceder a los recursos de varias cuentas mediante reglas AWS IoT](accessing-cross-account-resources-using-rules.md)
+ [Control de errores (acción de error)](rule-error-handling.md)
+ [Reducción de los costes de mensajería con Basic Ingest](iot-basic-ingest.md)
+ [AWS IoT Referencia SQL](iot-sql-reference.md)
# Otorgar a una AWS IoT regla el acceso que requiere
Utilice las funciones de IAM para controlar los AWS recursos a los que tiene acceso cada regla. Antes de crear una regla, debe crear un rol de IAM con una política que permita el acceso a los recursos necesarios AWS . AWS IoT asume esta función al implementar una regla.
**Complete los siguientes pasos para crear la función y la AWS IoT política de IAM que concedan a una AWS IoT regla el acceso que necesita (AWS CLI).**
1. Guarde el siguiente documento de política de confianza, que otorga el AWS IoT permiso para asumir el rol, en un archivo denominado`iot-role-trust.json`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:iot:us-east-1:123456789012:rule/rulename"
}
}
}
]
}
```
Utilice el comando [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) para crear un rol de IAM especificando el archivo `iot-role-trust.json`:
```
aws iam create-role --role-name my-iot-role --assume-role-policy-document file://iot-role-trust.json
```
El resultado de este comando tendrá un aspecto similar al siguiente.
```
{
"Role": {
"AssumeRolePolicyDocument": "url-encoded-json",
"RoleId": "AKIAIOSFODNN7EXAMPLE",
"CreateDate": "2015-09-30T18:43:32.821Z",
"RoleName": "my-iot-role",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
```
1. Copie el siguiente JSON en un archivo denominado `my-iot-policy.json`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "*"
}
]
}
```
Este JSON es un ejemplo de documento de política que otorga acceso de AWS IoT administrador a DynamoDB.
Use el comando [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) para conceder AWS IoT acceso a sus AWS recursos al asumir el rol, transfiriendo el archivo: `my-iot-policy.json`
```
aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy.json
```
Para obtener más información sobre cómo conceder acceso a las políticas Servicios de AWS internas AWS IoT, consulte. [Crear una AWS IoT regla](iot-create-rule.md)
La salida del comando [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) contendrá el ARN de la política. Asociar la política a un rol.
```
{
"Policy": {
"PolicyName": "my-iot-policy",
"CreateDate": "2015-09-30T19:31:18.620Z",
"AttachmentCount": 0,
"IsAttachable": true,
"PolicyId": "ZXR6A36LTYANPAI7NJ5UV",
"DefaultVersionId": "v1",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:policy/my-iot-policy",
"UpdateDate": "2015-09-30T19:31:18.620Z"
}
}
```
1. Utilice el [attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html)comando para adjuntar la política a su función:
```
aws iam attach-role-policy --role-name my-iot-role --policy-arn "arn:aws:iam::123456789012:policy/my-iot-policy"
```
## Revocación del acceso al motor de reglas
Para revocar inmediatamente el acceso al motor de reglas, realice lo siguiente:
1. Eliminar iot.amazonaws.com de la [política de confianza](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)
1. Seguir los pasos para [revocar las sesiones de roles de iot](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html)
# Transmisión de los permisos de rol
La definición de una regla implica que un rol de IAM; conceda permiso para tener acceso a los recursos especificados en la acción de la regla. El motor de reglas asume dicho rol cuando se activa la acción de la regla. El rol debe definirse de la misma manera Cuenta de AWS que la regla.
De hecho, cuando crea o sustituye una regla, está transfiriendo un rol al motor de reglas. El permiso `iam:PassRole` es necesario para realizar esta operación. Para comprobar que dispone de este permiso, cree una política que conceda a `iam:PassRole` el permiso y adjúntela a su usuario de IAM. La política siguiente muestra cómo conceder un permiso `iam:PassRole` para un rol.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::123456789012:role/myRole"
]
}
]
}
```
En este ejemplo de política, se concede el permiso `iam:PassRole` para el rol `myRole`. El rol se especifica mediante el ARN del rol. Adjunte esta política a su usuario de IAM o al rol al que pertenece su usuario. Para obtener más información, consulte [Uso de políticas administradas](https://docs.aws.amazon.com/service-authorization/latest/reference/access_policies_managed-using.html).
**nota**
Las funciones de Lambda utilizan una política basada en recursos. Esta política está directamente asociada a la función de Lambda en sí. Cuando se crea una regla que invoca una función de Lambda, no se pasa un rol, por lo que el usuario que crea la regla no necesita el permiso `iam:PassRole`. Para obtener más información sobre la autorización de funciones de Lambda, consulte [Concesión de permisos mediante una política de recursos](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy).
# Crear una AWS IoT regla
Puedes crear AWS IoT reglas para enrutar los datos de tus dispositivos conectados para que interactúen con otros AWS servicios. Una AWS IoT regla consta de los siguientes componentes:
**Componentes de una regla**
| Componente | Description (Descripción) | Obligatoria u opcional |
| --- | --- | --- |
| Nombre de la regla | El nombre de la regla. No se recomienda utilizar información personal identificable en los nombres de las reglas. | Obligatorio. |
| Descripción de la regla | Descripción textual de la regla. No se recomienda utilizar información personal identificable en las descripciones de las reglas. | Opcional. |
| Instrucción de SQL | Sintaxis de SQL simplificada para filtrar los mensajes recibidos sobre un tema de MQTT e insertar los datos en otro punto. Para obtener más información, consulte [AWS IoT Referencia SQL](iot-sql-reference.md). | Obligatorio. |
| Versión de SQL | Versión del motor de reglas SQL que debe utilizarse al evaluar la regla. Aunque esta propiedad es opcional, recomendamos encarecidamente que especifique la versión de SQL. La AWS IoT Core consola establece esta propiedad en de forma `2016-03-23` predeterminada. Si no se establece esta propiedad, por ejemplo, en un AWS CLI comando o una CloudFormation plantilla, `2015-10-08` se utiliza. Para obtener más información, consulte [Versiones de SQL](iot-rule-sql-version.md). | Obligatorio. |
| Una o varias acciones | Las acciones se AWS IoT realizan al promulgar la regla. Por ejemplo, puede insertar datos en una tabla de DynamoDB, escribir datos en un bucket de Amazon S3, publicar en un tema de Amazon SNS o invocar una función de Lambda. | Obligatorio. |
| Una acción de error | La acción se AWS IoT ejecuta cuando no puede realizar la acción de una regla. | Opcional. |
Antes de crear una AWS IoT regla, debe crear un rol de IAM con una política que permita el acceso a los AWS recursos necesarios. AWS IoT asume esta función al implementar una regla. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html) y [Transferir permisos de rol](https://docs.aws.amazon.com//iot/latest/developerguide/pass-role.html).
Cuando cree una regla, debe tener en cuenta la cantidad de datos que publica en los temas. Si crea reglas que incluyen un patrón de tema comodín, es posible que coincidan con un gran porcentaje de sus mensajes. Si este es el caso, es posible que necesite aumentar la capacidad de los recursos AWS que utilizan las acciones objetivo. Recomendamos evitar los patrones de temas comodín en las reglas de republicación para evitar el procesamiento duplicado y reducir los costos.
**nota**
La creación y la actualización de reglas son acciones de administrador. Todo usuario que tenga permiso para crear o actualizar reglas podrá tener acceso a los datos procesados por las reglas.
## Creación de una regla (consola)
**Para crear una regla (Consola de administración de AWS)**
Utilice el comando [Consola de administración de AWS](https://console.aws.amazon.com//iot/home#/home) para crear una regla:
1. Abra la [consola de AWS IoT](https://console.aws.amazon.com//iot/home#/home).
1. En el menú de navegación de la izquierda, seleccione **Enrutamiento de mensajes** en la sección **Administrar**. A continuación, elija **Reglas**.
1. En la página **Reglas**, seleccione **Crear una regla**.
1. En la página **Especificar las propiedades de la regla**, escriba un nombre para la regla. Los campos **Descripción de la regla** y **Etiquetas** son opcionales. Elija **Siguiente**.
1. En la página **Configurar la instrucción SQL**, elija una versión de SQL e introduzca una instrucción SQL. Un ejemplo de instrucción SQL puede ser `SELECT temperature FROM 'iot/topic' WHERE temperature > 50`. Para obtener más información, consulte [SQL versions](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-sql-version.html) y [AWS IoT SQL reference](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-reference.html).
1. En la página **Adjuntar acciones de regla**, añada acciones de regla para enrutar los datos a otros AWS servicios.
1. En **Acciones de la regla**, seleccione una acción de la regla de la lista desplegable. Por ejemplo, puede elegir **Kinesis Stream**. Para obtener más información sobre las acciones de las reglas, consulte [AWS IoT rule actions](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-actions.html).
1. En función de la acción de la regla que elija, introduzca los detalles de configuración relacionados. Por ejemplo, si elige **Kinesis Stream**, tendrá que elegir o crear un recurso de flujo de datos y, si lo desea, introducir detalles de configuración, como **Clave de partición**, que se utiliza para agrupar los datos por particiones en un flujo.
1. En el **rol de IAM**, elija o cree un rol para conceder el AWS IoT acceso a su punto final. Tenga en cuenta que se AWS IoT creará automáticamente una política con el prefijo correspondiente a la función de `aws-iot-rule` IAM que haya seleccionado. Puede seleccionar **Ver** para ver su rol de IAM y la política desde la consola de IAM. El campo **Acción de error** es opcional. Encontrará más información en [Error handling (error action)](https://docs.aws.amazon.com//iot/latest/developerguide/rule-error-handling.html). Para obtener más información sobre la creación de un rol de IAM para su regla, consulte [Grant a rule the access it requires](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html). Elija **Siguiente**.
1. En la página **Revisar y crear**, revise toda la configuración y realice las modificaciones necesarias. Seleccione **Crear**.
Después de crear una regla correctamente, la verá en la página **Reglas**. Puede seleccionar una regla para abrir la página **Detalles**, donde puede ver una regla, editarla, desactivarla y eliminarla.
## Creación de una regla (CLI)
**Para crear una regla (AWS CLI)**
Utilice el comando [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) para crear una regla:
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
Ejemplo de archivo de carga con una regla que inserta todos los mensajes enviados al tema `iot/test` en la tabla de DynamoDB especificada. La sentencia SQL filtra los mensajes y el ARN del rol concede AWS IoT permiso para escribir en la tabla de DynamoDB.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my-dynamodb-table",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"hashKeyField": "topic",
"hashKeyValue": "${topic(2)}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}"
}
}
]
}
```
A continuación, se muestra un ejemplo de archivo de carga con una regla que inserta todos los mensajes enviados al tema `iot/test` en el bucket de S3 especificado. La sentencia SQL filtra los mensajes y el ARN del rol concede AWS IoT permiso para escribir en el bucket de Amazon S3.
```
{
"awsIotSqlVersion": "2016-03-23",
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName": "amzn-s3-demo-bucket",
"key": "myS3Key"
}
}
]
}
```
El siguiente es un ejemplo de archivo de carga útil con una regla que envía datos a Amazon OpenSearch Service:
```
{
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"OpenSearch": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es",
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}"
}
}
]
}
```
Ejemplo de archivo de carga con una regla que invoca una función de Lambda:
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"
}
}
]
}
```
Ejemplo de archivo de carga con una regla que publica en un tema de Amazon SNS:
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-west-2:123456789012:my-sns-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
Ejemplo de archivo de carga con una regla que vuelve a publicar en otro tema MQTT:
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
Ejemplo de archivo de carga útil con una regla que inserta datos en un flujo de Amazon Kinesis Data Firehose:
```
{
"sql": "SELECT * FROM 'my-topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"deliveryStreamName": "my-stream-name"
}
}
]
}
```
A continuación se muestra un ejemplo de archivo de carga útil con una regla que utiliza la `machinelearning_predict` función Amazon SageMaker AI para volver a publicar en un tema si los datos de la carga útil de MQTT están clasificados como 1.
```
{
"sql": "SELECT * FROM 'iot/test' where machinelearning_predict('my-model', 'arn:aws:iam::123456789012:role/my-iot-aml-role', *).predictedLabel=1",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"topic": "my-mqtt-topic"
}
}
]
}
```
A continuación se incluye un archivo de carga de ejemplo con una regla que publica mensajes en un flujo de entrada de Salesforce IoT Cloud.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"salesforce": {
"token": "ABCDEFGHI123456789abcdefghi123456789",
"url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event"
}
}
]
}
```
Ejemplo de archivo de carga con una regla que inicia la ejecución de una máquina de estado de Step Functions.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myCoolStateMachine",
"executionNamePrefix": "coolRunning",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
# Administrar una regla AWS IoT
Puede utilizar las siguientes acciones para gestionar AWS IoT las reglas.
**Topics**
+ [Etiquetado de una regla](#iot-create-rule-tagging)
+ [Visualización de una regla](#iot-view-rules)
+ [Eliminación de una regla](#iot-delete-rule)
## Etiquetado de una regla
Para añadir otro nivel de especificidad a sus reglas nuevas o existentes, puede aplicar el etiquetado. El etiquetado aprovecha los pares clave-valor de sus reglas para proporcionarle un mayor control sobre cómo y dónde se aplican las reglas a sus AWS IoT recursos y servicios. Por ejemplo, puede limitar el alcance de la regla para que solo se aplique en su entorno beta para las pruebas previas al lanzamiento (`Key=environment, Value=beta`) o para capturar todos los mensajes enviados al `iot/test` tema únicamente desde un punto de conexión específico y almacenarlos en un bucket de Amazon S3.
### Ejemplo de política de IAM
Para ver un ejemplo que muestre cómo conceder permisos de etiquetado a una regla, piense en un usuario que ejecute el siguiente comando para crear una regla y etiquetarla para aplicarla únicamente a su entorno beta.
En el ejemplo, sustituya:
+ *MyTopicRuleName*con el nombre de la regla.
+ *myrule.json*con el nombre del documento de política.
```
aws iot create-topic-rule
--rule-name MyTopicRuleName
--topic-rule-payload file://myrule.json
--tags "environment=beta"
```
Para este ejemplo, debe utilizar la siguiente política de IAM:
****
```
{
"Version":"2012-10-17",
"Statement":
{
"Action": [ "iot:CreateTopicRule", "iot:TagResource" ],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:rule/MyTopicRuleName"
]
}
}
```
El ejemplo anterior muestra una regla recién creada llamada `MyTopicRuleName` que solo se aplica a su entorno beta. El `iot:TagResource` en la declaración de política con `MyTopicRuleName` específicamente llamado permite el etiquetado al crear o actualizar `MyTopicRuleName`. El parámetro `--tags "environment=beta"` utilizado al crear la regla limita el alcance de `MyTopicRuleName` únicamente a su entorno beta. Si elimina el parámetro`--tags "environment=beta"`, `MyTopicRuleName` se aplicará a todos los entornos.
Para obtener más información sobre la creación de funciones y políticas de IAM específicas para una regla AWS IoT , consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md)
Para obtener información general sobre el etiquetado de recursos, consulte [Etiquetar sus recursos AWS IoT](tagging-iot.md).
## Visualización de una regla
Usa el [list-topic-rules](https://docs.aws.amazon.com/cli/latest/reference/iot/list-topic-rules.html)comando para enumerar tus reglas:
```
aws iot list-topic-rules
```
Usa el [get-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/get-topic-rule.html)comando para obtener información sobre una regla:
```
aws iot get-topic-rule --rule-name myrule
```
## Eliminación de una regla
Cuando ya no necesite una regla, puede eliminarla.
**Para eliminar una regla (AWS CLI)**
Usa el [delete-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-topic-rule.html)comando para eliminar una regla:
```
aws iot delete-topic-rule --rule-name myrule
```
# AWS IoT acciones de reglas
AWS IoT las acciones de regla especifican qué hacer cuando se invoca una regla. Puede definir acciones para enviar datos a una base de datos de Amazon DynamoDB, enviar datos a Amazon Kinesis Data Streams, AWS Lambda invocar una función, etc. AWS IoT admite las siguientes acciones Regiones de AWS cuando el servicio de la acción está disponible.
| Acción de regla | Description (Descripción) | Nombre en la API |
| --- | --- | --- |
| [Apache Kafka](apache-kafka-rule-action.md) | Envía un mensaje a un clúster de Apache Kafka. | kafka |
| [CloudWatch alarmas](cloudwatch-alarms-rule-action.md) | Cambia el estado de una CloudWatch alarma de Amazon. | cloudwatchAlarm |
| [CloudWatch Registros](cloudwatch-logs-rule-action.md) | Envía un mensaje a Amazon CloudWatch Logs. | cloudwatchLogs |
| [CloudWatch métricas](cloudwatch-metrics-rule-action.md) | Envía un mensaje a una CloudWatch métrica. | cloudwatchMetric |
| [DynamoDB](dynamodb-rule-action.md) | Envía un mensaje a una tabla DynamoDB. | dynamoDB |
| [Dinamo DBv2](dynamodb-v2-rule-action.md) | Envía los datos de los mensajes a varias columnas de una tabla de DynamoDB. | dynamoDBv2 |
| [Elasticsearch](elasticsearch-rule-action.md) | Envía un mensaje a un OpenSearch punto final. | OpenSearch |
| [HTTP](https-rule-action.md) | Publica un mensaje en un punto de conexión HTTPS. | http |
| [AWS IoT Events](iotevents-rule-action.md) | Envía un mensaje a una AWS IoT Events entrada. | iotEvents |
| [AWS IoT SiteWise](iotsitewise-rule-action.md) | Envía los datos del mensaje a las propiedades AWS IoT SiteWise de los activos. | iotSiteWise |
| [Firehose](kinesis-firehose-rule-action.md) | Envía un mensaje a un flujo de entrega de Firehose. | firehose |
| [Kinesis Data Streams](kinesis-rule-action.md) | Envía un mensaje a un flujo de datos Kinesis. | kinesis |
| [Lambda](lambda-rule-action.md) | Invoca una función de Lambda con datos de mensaje como entrada. | lambda |
| [Ubicación](location-rule-action.md) | Envía los datos de ubicación a Amazon Location Service. | location |
| [OpenSearch](opensearch-rule-action.md) | Envía un mensaje a un punto final OpenSearch de Amazon Service. | OpenSearch |
| [Volver a publicar](republish-rule-action.md) | Vuelve a publicar un mensaje en otro tema MQTT. | republish |
| [S3](s3-rule-action.md) | Almacena un mensaje en un bucket de Amazon Simple Storage Service (Amazon S3). | s3 |
| [IoT de Salesforce](salesforce-iot-rule-action.md) | Envía un mensaje a un flujo de entrada de Salesforce IoT. | salesforce |
| [SNS](sns-rule-action.md) | Publica un mensaje como notificación push de Amazon Simple Notification Service (Amazon SNS). | sns |
| [SQS](sqs-rule-action.md) | Envía un mensaje a una cola de Amazon Simple Queue Service (Amazon SQS). | sqs |
| [Step Functions](stepfunctions-rule-action.md) | Inicia una máquina de AWS Step Functions estados. | stepFunctions |
| [Timestream](timestream-rule-action.md) | Envía un mensaje a una tabla de base de datos de Amazon Timestream. | timestream |
**Notas**
Defina la regla al Región de AWS igual que el recurso de otro servicio para que la acción de la regla pueda interactuar con ese recurso.
El motor de AWS IoT reglas puede realizar varios intentos para realizar una acción si se producen errores intermitentes. Si todos los intentos fallan, el mensaje se descarta y el error aparece en tus CloudWatch registros. Es posible especificar una acción de error para cada regla que se invoca cuando se produce un error. Para obtener más información, consulte [Control de errores (acción de error)](rule-error-handling.md).
Algunas acciones de regla desencadenan acciones en servicios que se integran con AWS Key Management Service (AWS KMS) para admitir el cifrado de datos en reposo. Si utilizas una clave KMS administrada por el cliente AWS KMS key para cifrar los datos en reposo, el servicio debe tener permiso para usar la clave KMS en nombre de la persona que llama. Para saber cómo gestionar los permisos de su clave KMS gestionada por el cliente, consulte los temas de cifrado de datos en la guía de servicio correspondiente. Para obtener más información sobre las claves KMS gestionadas por el cliente, consulte los [conceptos de AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) en la *Guía del desarrollador de AWS Key Management Service *.
Puede utilizar cualquier [función](iot-sql-functions.md) o [plantilla de sustitución](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) en la sentencia SQL de una acción de error, incluidas las funciones externas: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda),, [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret)y. [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning) Si una acción de error requiere llamar a una función externa, la invocación de la acción de error puede generar una factura adicional por la función externa.
# Apache Kafka
La acción de Apache Kafka (Kafka) envía mensajes directamente a [Amazon Managed Streaming para Apache Kafka](https://docs.aws.amazon.com//msk/latest/developerguide/what-is-msk.html) (Amazon MSK), a clústeres de Apache Kafka autoadministrados por proveedores externos, como [Confluent Cloud](https://www.confluent.io/) o a clústeres de Apache Kafka autoadministrados. Con la acción de reglas de Kafka, puede enrutar sus datos de IoT a los clústeres de Kafka. Esto le permite crear canalizaciones de datos de alto rendimiento para diversos fines, como el análisis de flujos, la integración de datos, la visualización y las aplicaciones empresariales esenciales.
**nota**
En este tema se presupone estar familiarizado con la plataforma Apache Kafka y los conceptos relacionados. Para obtener más información sobre Apache Kafka, consulte [Apache Kafka](https://kafka.apache.org/). No se admite [MSK sin servidor](https://docs.aws.amazon.com//msk/latest/developerguide/serverless.html). Los clústeres de MSK sin servidor solo se pueden crear mediante la autenticación de IAM, que la acción de la regla de Apache Kafka no admite actualmente. Para obtener más información sobre cómo configurar AWS IoT Core con Confluent, consulte [Aprovechar Confluent y AWS resolver los desafíos de la administración de datos y dispositivos de IoT](https://aws.amazon.com/blogs/apn/leveraging-confluent-and-aws-to-solve-iot-device-and-data-management-challenges/).
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar las `ec2:CreateNetworkInterface` operaciones`ec2:DescribeNetworkInterfaces`,,`ec2:CreateNetworkInterfacePermission`, `ec2:DeleteNetworkInterface` `ec2:DescribeSubnets``ec2:DescribeVpcs`, `ec2:DescribeVpcAttribute` y. `ec2:DescribeSecurityGroups` Este rol crea y administra interfaces de red elásticas para su Amazon Virtual Private Cloud para comunicarse con su agente de Kafka. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT Core realizar esta acción de regla.
A fin de obtener más información sobre las interfaces de red, consulte [Interfaces de red elástica](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) en la *Guía del usuario de Amazon EC2*.
La política asociada al rol especificado debería verse de manera similar al siguiente ejemplo.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
}
]
}
```
+ Si lo utiliza AWS Secrets Manager para almacenar las credenciales necesarias para conectarse a su agente de Kafka, debe crear un rol de IAM que AWS IoT Core pueda asumir para realizar las operaciones `secretsmanager:GetSecretValue` y`secretsmanager:DescribeSecret`.
La política asociada al rol especificado debería verse de manera similar al siguiente ejemplo.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_client_truststore-*",
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_keytab-*"
]
}
]
}
```
+ Puede ejecutar sus clústeres de Apache Kafka dentro de Amazon Virtual Private Cloud (Amazon VPC). Debe crear un destino de nube privada virtual (VPC) de Apache Kafka y utilizar una puerta de enlace NAT en las subredes para reenviar los mensajes desde AWS IoT un clúster público de Kafka. El motor de AWS IoT reglas crea una interfaz de red en cada una de las subredes enumeradas en el destino para enrutar el tráfico directamente a la VPC. Cuando llegue a su destino, el motor de AWS IoT reglas crea automáticamente una acción de regla de VPC. Para obtener más información sobre las acciones de las reglas, consulte [Destinos de Apache Kafka Virtual Private Cloud (VPC)](kafka-vpc-destination.md).
+ Si utilizas una clave KMS gestionada AWS KMS key por el cliente para cifrar los datos en reposo, el servicio debe tener permiso para utilizar la clave KMS en nombre de la persona que llama. Para obtener más información, consulte el [cifrado de Amazon MSK](https://docs.aws.amazon.com/msk/latest/developerguide/msk-encryption.html) en la *guía para desarrolladores Amazon Managed Streaming for Apache Kafka.*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
destinationArn
El nombre del recurso de Amazon (ARN) del destino de la Nube Privada Virtual (VPC) de Apache Kafka. Para obtener información sobre la creación de un destino, consulte. [Destinos de Apache Kafka Virtual Private Cloud (VPC)](kafka-vpc-destination.md)
tema
Tema de Kafka para que los mensajes se envíen al agente de Kafka.
Puede sustituir este campo mediante una plantilla de sustitución. Para obtener más información, consulte [Plantillas de sustitución](iot-substitution-templates.md).
clave (opcional)
Clave de mensajes de Kafka.
Puede sustituir este campo mediante una plantilla de sustitución. Para obtener más información, consulte [Plantillas de sustitución](iot-substitution-templates.md).
encabezados (opcional)
La lista de cabeceras de Kafka que usted especifique. Cada encabezado es un par clave-valor que puede especificar al crear una acción de Kafka. Puede usar estos encabezados para enrutar los datos de los clientes de IoT a los clústeres de Kafka descendentes sin modificar la carga útil de los mensajes.
Puede sustituir este campo mediante una plantilla de sustitución. [Para saber cómo pasar una función de regla en línea como plantilla de sustitución en el encabezado de la acción Kafka, consulte los ejemplos.](#apache-kafka-rule-action-examples) Para obtener más información, consulte [Plantillas de sustitución](iot-substitution-templates.md).
Los encabezados en formato binario no son compatibles.
partición (opcional)
Partición de mensajes de Kafka.
Puede sustituir este campo mediante una plantilla de sustitución. Para obtener más información, consulte [Plantillas de sustitución](iot-substitution-templates.md).
clientProperties
Un objeto que define las propiedades del cliente productor de Apache Kafka.
acks (opcional)
El número de reconocimientos que el productor requiere que el servidor haya recibido antes de considerar completa una solicitud.
Si especifica 0 como valor, el productor no esperará ningún acuse de recibo del servidor. Si el servidor no recibe el mensaje, el productor no volverá a intentar enviarlo.
Valores válidos: `-1`, `0`, `1`, `all`. El valor predeterminado es `1`.
bootstrap.servers
Una lista de pares de host y puerto (por ejemplo `host1:port1`, `host2:port2`) que se utilizan para establecer la conexión inicial con el clúster de Kafka.
compression.type (opcional)
El tipo de compresión de todos los datos generados por el productor.
Valores válidos: `none`, `gzip`, `snappy`, `lz4`, `zstd`. El valor predeterminado es `none`.
security.protocol
El protocolo de seguridad utilizado para conectarse a su agente de Kafka.
Valores válidos: `SSL`, `SASL_SSL`. El valor predeterminado es `SSL`.
key.serializer
Especifica cómo convertir los objetos clave que usted proporciona con el `ProducerRecord` en bytes.
Valor válido: `StringSerializer`.
value.serializer
Especifica cómo convertir los objetos de valor que proporcione con el `ProducerRecord` en bytes.
Valor válido: `ByteBufferSerializer`.
ssl.truststore
El archivo truststore en formato base64 o la ubicación del archivo truststore en [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) Este valor no es necesario si su almacén de confianza cuenta con la confianza de las autoridades de certificación (CA) de Amazon.
Este campo admite plantillas de sustitución. Si usa Secrets Manager para almacenar las credenciales necesarias para conectarse a su agente de Kafka, puede usar la función SQL `get_secret` para recuperar el valor de este campo. Para obtener más información sobre las plantillas de sustitución, consulte [Plantillas de sustitución](iot-substitution-templates.md). Para obtener más información sobre la función `get_secret`, consulte [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Si el almacén de confianza tiene la forma de un archivo, utilice el parámetro `SecretBinary`. Si el almacén de confianza tiene la forma de una cadena, utilice el parámetro `SecretString`.
El valor máximo de este recuento es 65 KB.
ssl.truststore.password
La contraseña del almacén de confianza. Este valor solo es obligatorio si ha creado una contraseña para el almacén de confianza.
ssl.keystore
El archivo del almacén de claves. Este valor es obligatorio cuando se especifica `SSL` como valor para `security.protocol`.
Este campo admite plantillas de sustitución. Utilice Secrets Manager para almacenar las credenciales necesarias para conectarse a su agente de Kafka. Para recuperar el valor de este campo, utilice la función SQL `get_secret`. Para obtener más información sobre las plantillas de sustitución, consulte [Plantillas de sustitución](iot-substitution-templates.md). Para obtener más información sobre la función `get_secret`, consulte [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilice el parámetro `SecretBinary`.
ssl.keystore.password
La contraseña del almacén para el archivo keystore. Este valor es necesario si especifica un valor para `ssl.keystore`.
El valor de este campo puede ser texto sin formato. Este campo también admite plantillas de sustitución. Utilice Secrets Manager para almacenar las credenciales necesarias para conectarse a su agente de Kafka. Para recuperar el valor de este campo, utilice la función SQL `get_secret`. Para obtener más información sobre las plantillas de sustitución, consulte [Plantillas de sustitución](iot-substitution-templates.md). Para obtener más información sobre la función `get_secret`, consulte [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilice el parámetro `SecretString`.
ssl.key.password
La contraseña de la clave privada del archivo del almacén de claves.
Este campo admite plantillas de sustitución. Utilice Secrets Manager para almacenar las credenciales necesarias para conectarse a su agente de Kafka. Para recuperar el valor de este campo, utilice la función SQL `get_secret`. Para obtener más información sobre las plantillas de sustitución, consulte [Plantillas de sustitución](iot-substitution-templates.md). Para obtener más información sobre la función `get_secret`, consulte [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilice el parámetro `SecretString`.
sasl.mechanism
El mecanismo de seguridad utilizado para conectarse a su agente de Kafka. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol`.
Valores válidos: `PLAIN`, `SCRAM-SHA-512`, `GSSAPI`.
`SCRAM-SHA-512`es el único mecanismo de seguridad compatible en las regiones cn-north-1, cn-northwest-1, -1 y -1. us-gov-east us-gov-west
sasl.plain.username
El nombre de usuario utilizado para recuperar la cadena secreta de Secrets Manager. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol` y `PLAIN` para `sasl.mechanism`.
sasl.plain.password
La contraseña utilizada para recuperar la cadena secreta de Secrets Manager. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol` y `PLAIN` para `sasl.mechanism`.
sasl.scram.username
El nombre de usuario utilizado para recuperar la cadena secreta de Secrets Manager. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol` y `SCRAM-SHA-512` para `sasl.mechanism`.
sasl.scram.password
La contraseña utilizada para recuperar la cadena secreta de Secrets Manager. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol` y `SCRAM-SHA-512` para `sasl.mechanism`.
sasl.kerberos.keytab
El archivo keytab para la autenticación de Kerberos en Secrets Manager. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol` y `GSSAPI` para `sasl.mechanism`.
Este campo admite plantillas de sustitución. Utilice Secrets Manager para almacenar las credenciales necesarias para conectarse a su agente de Kafka. Para recuperar el valor de este campo, utilice la función SQL `get_secret`. Para obtener más información sobre las plantillas de sustitución, consulte [Plantillas de sustitución](iot-substitution-templates.md). Para obtener más información sobre la función `get_secret`, consulte [get\$1secret(secretId, secretType, key, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilice el parámetro `SecretBinary`.
sasl.kerberos.service.name
El nombre principal de Kerberos con el que se ejecuta Apache Kafka. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol` y `GSSAPI` para `sasl.mechanism`.
sasl.kerberos.krb5.kdc
El nombre de host del centro de distribución de claves (KDC) al que se conecta su cliente productor de Apache Kafka. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol` y `GSSAPI` para `sasl.mechanism`.
sasl.kerberos.krb5.realm
El ámbito al que se conecta su cliente productor de Apache Kafka. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol` y `GSSAPI` para `sasl.mechanism`.
sasl.kerberos.principal
La identidad única de Kerberos a la que Kerberos puede asignar tickets para acceder a los servicios compatibles con Kerberos. Este valor es obligatorio cuando se especifica `SASL_SSL` para `security.protocol` y `GSSAPI` para `sasl.mechanism`.
## Ejemplos
El siguiente ejemplo de JSON define una acción de Apache Kafka en una regla. AWS IoT El siguiente ejemplo pasa la función en línea [ sourceIP ()](iot-sql-functions.md#iot-function-sourceip) como [plantilla de sustitución](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) en el encabezado Kafka Action.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kafka": {
"destinationArn": "arn:aws:iot:region:123456789012:ruledestination/vpc/VPCDestinationARN",
"topic": "TopicName",
"clientProperties": {
"bootstrap.servers": "kafka.com:9092",
"security.protocol": "SASL_SSL",
"ssl.truststore": "${get_secret('kafka_client_truststore', 'SecretBinary','arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"ssl.truststore.password": "kafka password",
"sasl.mechanism": "GSSAPI",
"sasl.kerberos.service.name": "kafka",
"sasl.kerberos.krb5.kdc": "kerberosdns.com",
"sasl.kerberos.keytab": "${get_secret('kafka_keytab','SecretBinary', 'arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"sasl.kerberos.krb5.realm": "KERBEROSREALM",
"sasl.kerberos.principal": "kafka-keytab/kafka-keytab.com"
},
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
},
{
"key": "source_ip",
"value": "${sourceIp()}"
}
]
}
}
]
}
}
```
**Notas importantes sobre la configuración de Kerberos**
+ Su centro de distribución de claves (KDC) debe poder resolverse mediante un sistema de nombres de dominio (DNS) privado dentro de la VPC de destino. Un enfoque posible consiste en añadir la entrada DNS del KDC a una zona alojada privada. Para más información sobre este enfoque, consulte [Trabajar con zonas alojadas privadas](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html).
+ Cada VPC debe tener habilitada la resolución DNS. Para obtener más información, consulte [Utilización de DNS con su VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html).
+ Los grupos de seguridad de la interfaz de red y los grupos de seguridad a nivel de instancia del destino de la VPC deben permitir el tráfico desde dentro de la VPC en los siguientes puertos.
+ El tráfico TCP en el puerto oyente intermediario bootstrap (normalmente 9092, pero debe estar dentro del rango de 9000 a 9100)
+ Tráfico TCP y UDP en el puerto 88 del KDC
+ `SCRAM-SHA-512`es el único mecanismo de seguridad compatible en las regiones cn-north-1, cn-northwest-1, -1 y -1. us-gov-east us-gov-west
# Destinos de Apache Kafka Virtual Private Cloud (VPC)
La acción de regla de Apache Kafka enruta los datos a un clúster de Apache Kafka en una Amazon Virtual Private Cloud (Amazon VPC). La configuración de la VPC utilizada por la acción de regla de Apache Kafka se habilita automáticamente cuando se especifica el destino de la VPC para la acción de regla.
Un destino de nube privada virtual (VPC) de Apache Kafka contiene una lista de subredes dentro de la VPC. El motor de reglas crea una interfaz de red elástica en cada subred especificada en esta lista. A fin de obtener más información sobre las interfaces de red, consulte [Interfaces de red elástica](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) en la Guía del usuario de Amazon EC2.
## Requisitos y consideraciones
+ Si utiliza un clúster de Apache Kafka autogestionado al que se accederá mediante un punto de conexión público a través de Internet:
+ Cree una puerta de enlace NAT para las instancias de sus subredes. La puerta de enlace NAT tiene una dirección IP pública que puede conectarse a Internet, lo que permite al motor de reglas reenviar sus mensajes al clúster público de Kafka.
+ Asigne una dirección IP elástica con las interfaces de red elásticas (ENIs) que crea el destino de la Nube Privada Virtual (VPC) de Apache Kafka. Los grupos de seguridad que utilice deben estar configurados para bloquear el tráfico entrante.
**nota**
Si el destino de la Nube Privada Virtual (VPC) de Apache Kafka está deshabilitado y, a continuación, se vuelve a activar, debe volver a asociar el elástico al nuevo. IPs ENIs
+ Si un destino de la Nube Privada Virtual (VPC) de Apache Kafka no recibe tráfico durante 30 días seguidos, se deshabilitará.
+ Si algún recurso utilizado por el destino de la Nube Privada Virtual (VPC) de Apache Kafka cambia, el destino se deshabilitará y no se podrá utilizar.
+ Algunos cambios que pueden deshabilitar un destino de nube privada virtual (VPC) de Apache Kafka incluyen:
+ Eliminar la VPC, las subredes, los grupos de seguridad o el rol utilizado.
+ Modificar el rol para que deje de tener los permisos necesarios.
+ Alcanzar casi la capacidad de la subred, lo que nos impide aplicar los parches de [FedRAMP.](https://aws.amazon.com/compliance/fedramp/)
+ Deshabilitar el destino.
## Precios
A efectos de fijación de precios, se mide una acción de regla de VPC además de la acción que envía un mensaje a un recurso cuando el recurso está en su VPC. Para obtener información sobre precios, consulte [Precios de AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
## Creación de destinos de nube privada virtual (VPC) de Apache Kafka
Para crear un destino de nube privada virtual (VPC) de Apache Kafka, utilice la API o la [CreateTopicRuleDestination](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRuleDestination.html)consola. AWS IoT Core
Al crear un destino, debe especificar la siguiente información.
vpcId
El identificador único de Amazon VPC.
subnetIds
Una lista de subredes en las que el motor de reglas crea interfaces de red elásticas. El motor de reglas asigna una única interfaz de red para cada subred de la lista.
securityGroups (opcional)
Lista de grupos de seguridad que se aplicarán a las interfaces de red.
roleArn
El nombre de recurso de Amazon (ARN) de un rol que tiene permiso para crear interfaces de red en su nombre.
Este ARN debería tener asociada una política similar al siguiente ejemplo.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeVpcs",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:CreateNetworkInterfacePermission",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/VPCDestinationENI": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface",
"aws:RequestTag/VPCDestinationENI": "true"
}
}
}
]
}
```
### Creación de un destino de nube privada virtual (VPC) de Apache Kafka mediante AWS CLI
El siguiente ejemplo muestra cómo crear un destino mediante. AWS CLI
```
aws --region regions iot create-topic-rule-destination --destination-configuration 'vpcConfiguration={subnetIds=["subnet-123456789101230456"],securityGroups=[],vpcId="vpc-123456789101230456",roleArn="arn:aws:iam::123456789012:role/role-name"}'
```
Tras ejecutar este comando, el estado del destino será`IN_PROGRESS`. Transcurridos unos minutos, su estado cambiará a `ERROR` (si el comando no se ejecuta correctamente) o `ENABLED`. Cuando el estado de destino es `ENABLED`, está lista para su uso.
Puede usar el siguiente comando para obtener el estado de su destino de Apache Kafka Virtual Private Cloud (VPC).
```
aws --region region iot get-topic-rule-destination --arn "VPCDestinationARN"
```
### Creación de un destino de nube privada virtual (VPC) de Apache Kafka mediante la consola AWS IoT Core
Los siguientes pasos describen cómo crear un destino mediante la AWS IoT Core consola.
1. Navegue hasta la AWS IoT Core consola. En el panel izquierdo, en la pestaña **Actuar**, seleccione **Destinos**.
1. Escriba valores en los siguientes campos:
+ **ID de VPC**
+ **Subred IDs**
+ **Security Group**
1. Seleccione un rol que tenga los permisos necesarios para crear interfaces de red. El ejemplo anterior de política contiene estos permisos.
Cuando el estado de destino de la Nube Privada Virtual (VPC) de Apache Kafka esté **HABILITADO**, estará listo para usarse.
# CloudWatch alarmas
La acción CloudWatch alarm (`cloudWatchAlarm`) cambia el estado de una CloudWatch alarma de Amazon. Puede especificar el motivo del cambio de estado y el valor de esta llamada.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar la `cloudwatch:SetAlarmState` operación. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`alarmName`
El nombre CloudWatch de la alarma.
Soporta [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`stateReason`
El motivo del cambio de alarma.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`stateValue`
El valor del estado de alarma. Valores válidos: `OK`, `ALARM`, `INSUFFICIENT_DATA`.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleArn`
La función de IAM que permite el acceso a la CloudWatch alarma. Para obtener más información, consulte [Requisitos](#cloudwatch-alarms-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción CloudWatch de alarma en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "IotAlarm",
"stateReason": "Temperature stabilized.",
"stateValue": "OK",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## Véase también
+ [¿Qué es Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) en la *Guía del CloudWatch usuario de Amazon*
+ [Uso de CloudWatch las alarmas de Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) en la *Guía del CloudWatch usuario de Amazon*
# CloudWatch Registros
La acción CloudWatch Logs (`cloudwatchLogs`) envía datos a Amazon CloudWatch Logs. Puede utilizar `batchMode` para cargar y marcar la hora de varios registros de dispositivos en un solo mensaje. También puede especificar el grupo de registro al que la acción envía los datos.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir la responsabilidad de realizar `logs:CreateLogStream` las `logs:DescribeLogStreams` `logs:PutLogEvents` operaciones y. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utilizas una clave KMS administrada AWS KMS key por el cliente para cifrar los datos de registro en CloudWatch Logs, el servicio debe tener permiso para usar la clave KMS en nombre de la persona que llama. Para obtener más información, consulte [Cifrar datos de registro en CloudWatch Logs utilizando AWS KMS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html) la *Guía del usuario de Amazon CloudWatch Logs*.
## Requisitos de formato de mensaje MQTT para `batchMode`
Si utilizas la acción de la regla de CloudWatch registros `batchMode` desactivada, no hay requisitos de formato de mensajes en MQTT. (Nota: el valor por defecto del parámetro `batchMode` es `false`.) Sin embargo, si utiliza la acción de la regla CloudWatch Registros con la opción `batchMode` activada (el valor del parámetro es`true`), los mensajes MQTT que contienen registros del dispositivo deben formatearse de forma que contengan una marca de tiempo y una carga útil de mensajes. **Nota:** `timestamp` representa la hora en que se produjo el suceso y se expresa como un número de milisegundos después del 1 de enero de 1970 00:00:00 UTC.
A continuación se muestra un ejemplo del formato de publicación:
```
[
{"timestamp": 1673520691093, "message": "Test message 1"},
{"timestamp": 1673520692879, "message": "Test message 2"},
{"timestamp": 1673520693442, "message": "Test message 3"}
]
```
Según cómo se generen los registros del dispositivo, es posible que sea necesario filtrarlos y reformatearlos antes de enviarlos para cumplir con este requisito. Para obtener más información, consulte [Carga de mensajes MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/topicdata.html).
Independientemente del `batchMode` parámetro, el `message` contenido debe cumplir con las limitaciones de tamaño de los mensajes. AWS IoT Para obtener más información, consulte [Puntos de conexión y cuotas de AWS IoT Core](https://docs.aws.amazon.com/general/latest/gr/iot-core.html).
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`logGroupName`
El grupo de CloudWatch registros al que la acción envía los datos.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`roleArn`
La función de IAM que permite el acceso al grupo de CloudWatch registros. Para obtener más información, consulte [Requisitos](#cloudwatch-logs-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
(opcional) `batchMode`
Indica si los lotes de registros se van a extraer y cargar en CloudWatch ellos. Los valores incluyen `true` o `false` (predeterminado). Para obtener más información, consulte [Requisitos](#cloudwatch-logs-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción de CloudWatch registros en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchLogs": {
"logGroupName": "IotLogs",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw",
"batchMode": false
}
}
]
}
}
```
## Véase también
+ [¿Qué es Amazon CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/) en la *Guía del usuario CloudWatch de Amazon Logs*
# CloudWatch métricas
La acción CloudWatch metric (`cloudwatchMetric`) captura una CloudWatch métrica de Amazon. Puede especificar el espacio de nombres, el nombre, el valor, la unidad y la marca de tiempo de la métrica.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar la `cloudwatch:PutMetricData` operación. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`metricName`
El nombre de la CloudWatch métrica.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`metricNamespace`
El nombre del espacio de nombres de la CloudWatch métrica.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`metricUnit`
La unidad métrica admitida por. CloudWatch
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`metricValue`
Cadena que contiene el valor CloudWatch métrico.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`metricTimestamp`
(Opcional) Una cadena que contiene la marca de tiempo, expresada en segundos en tiempo de época Unix. El valor predeterminado es la época actual de Unix.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleArn`
La función de IAM que permite el acceso a la CloudWatch métrica. Para obtener más información, consulte [Requisitos](#cloudwatch-metrics-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción CloudWatch métrica en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "IotMetric",
"metricNamespace": "IotNamespace",
"metricUnit": "Count",
"metricValue": "1",
"metricTimestamp": "1456821314",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción CloudWatch métrica con plantillas de sustitución en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "${topic()}",
"metricNamespace": "${namespace}",
"metricUnit": "${unit}",
"metricValue": "${value}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## Véase también
+ [¿Qué es Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) en la *Guía del CloudWatch usuario de Amazon*
+ [Uso de CloudWatch las métricas de Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) en la *Guía del CloudWatch usuario de Amazon*
# DynamoDB
La acción DynamoDB (`dynamoDB`) escribe la totalidad o parte de un mensaje MQTT en una tabla de Amazon DynamoDB.
Puede seguir un tutorial que muestra cómo crear y probar una regla con una acción de DynamoDB. Para obtener más información, consulte [Tutorial: Almacenamiento de datos de dispositivos en una tabla de DynamoDB](iot-ddb-rule.md).
**nota**
Esta regla escribe datos no JSON en DynamoDB como datos binarios. La consola de DynamoDB mostrará los datos como texto codificado en Base64.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Un rol de IAM que AWS IoT puede asumir para realizar la operación. `dynamodb:PutItem` Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utiliza una clave KMS gestionada AWS KMS key por el cliente para cifrar los datos en reposo en DynamoDB, el servicio debe tener permiso para utilizar la clave KMS en nombre de la persona que llama. Para obtener más información, consulte la [clave de KMS gestionada por el cliente](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed) en la *Guía de introducción de Amazon DynamoDB*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`tableName`
El nombre de la tabla de DynamoDB.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`hashKeyField`
El nombre de la clave hash (también denominada clave de partición).
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`hashKeyType`
(Opcional) El tipo de datos de la clave hash (también denominado clave de partición). Valores válidos: `STRING`, `NUMBER`.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`hashKeyValue`
El valor de la clave hash. Considere la posibilidad de utilizar una plantilla de sustitución como `${topic()}` o `${timestamp()}`.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`rangeKeyField`
(Opcional) El nombre de la clave de rango (también denominada clave de clasificación).
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`rangeKeyType`
(Opcional) El tipo de datos de la clave de rango (también denominada clave de clasificación). Valores válidos: `STRING`, `NUMBER`.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`rangeKeyValue`
(Opcional) El valor de la clave de rango. Considere la posibilidad de utilizar una plantilla de sustitución como `${topic()}` o `${timestamp()}`.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`payloadField`
(Opcional) El nombre de la columna donde se escribe la carga útil. Si omite este valor, la carga útil se escribe en la columna denominada `payload`.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`operation`
(Opcional) El tipo de operación que se va a realizar. Valores válidos: `INSERT`, `UPDATE`, `DELETE`.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleARN`
El rol de IAM que permite tener acceso a la tabla de DynamoDB. Para obtener más información, consulte [Requisitos](#dynamodb-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
Los datos que se escriben en la tabla de DynamoDB son el resultado de la instrucción SQL de la regla.
## Ejemplos
El siguiente ejemplo de JSON define una acción de DynamoDB en una regla. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${topic()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
## Véase también
+ [¿Qué es Amazon DynamoDB?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) en la *Guía para desarrolladores de Amazon DynamoDB.*
+ [Introducción a DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) en la *Guía para desarrolladores de Amazon DynamoDB*
+ [Tutorial: Almacenamiento de datos de dispositivos en una tabla de DynamoDB](iot-ddb-rule.md)
# Dinamo DBv2
La acción Dynamo DBv2 (`dynamoDBv2`) escribe todo o parte de un mensaje MQTT en una tabla de Amazon DynamoDB. Cada atributo de la carga útil se escribe en una columna independiente de la base de datos de DynamoDB.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar la operación. `dynamodb:PutItem` Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ La carga del mensaje MQTT debe contener una clave de nivel de raíz que coincida con la clave de partición principal de la tabla y una clave de nivel de raíz que coincida con la clave de clasificación principal de la tabla, si hay una definida.
+ Si utiliza una clave KMS gestionada AWS KMS key por el cliente para cifrar los datos en reposo en DynamoDB, el servicio debe tener permiso para utilizar la clave KMS en nombre de la persona que llama. Para obtener más información, consulte la [clave de KMS gestionada por el cliente](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed) en la *Guía de introducción de Amazon DynamoDB*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`putItem`
Un objeto que especifica la tabla de DynamoDB en la que se escribirán los datos del mensaje. Este objeto debe contener la siguiente información:
`tableName`
El nombre de la tabla de DynamoDB.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`roleARN`
El rol de IAM que permite tener acceso a la tabla de DynamoDB. Para obtener más información, consulte [Requisitos](#dynamodb-v2-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
Los datos que se escriben en la tabla de DynamoDB son el resultado de la instrucción SQL de la regla.
## Ejemplos
El siguiente ejemplo de JSON define una DBv2 acción de Dynamo en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "my_ddb_table"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2",
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción de DynamoDB con plantillas de sustitución en una regla. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2015-10-08",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "${topic()}"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2"
}
}
]
}
}
```
## Véase también
+ [¿Qué es Amazon DynamoDB?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) en la *Guía para desarrolladores de Amazon DynamoDB.*
+ [Introducción a DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) en la *Guía para desarrolladores de Amazon DynamoDB*
# Elasticsearch
La acción Elasticsearch (`elasticsearch`) escribe los datos de los mensajes MQTT en un dominio de Amazon OpenSearch Service. A continuación, puede utilizar herramientas como los OpenSearch paneles de control para consultar y visualizar los datos en Service. OpenSearch
**aviso**
La acción `Elasticsearch` solo puede ser utilizado por acciones de reglas existentes. Para crear una nueva acción de regla o actualizar una acción de regla existente, use la acción de la regla `OpenSearch` en su lugar. Para obtener más información, consulte [OpenSearch](opensearch-rule-action.md).
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar la `es:ESHttpPut` operación. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utilizas una clave KMS gestionada AWS KMS key por el cliente para cifrar los datos en reposo OpenSearch, el servicio debe tener permiso para utilizar la clave KMS en nombre de la persona que llama. Para obtener más información, consulta [Cifrado de datos en reposo para Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html) en la *Guía para desarrolladores de Amazon OpenSearch Service*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`endpoint`
El punto de conexión de su dominio de servicio.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`index`
Índice de donde se van a almacenar los datos.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`type`
Tipo de documento que está almacenando.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`id`
Identificador único de cada documento.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleARN`
La función de IAM que permite el acceso al dominio del OpenSearch servicio. Para obtener más información, consulte [Requisitos](#elasticsearch-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción de Elasticsearch en una AWS IoT regla y cómo se pueden especificar los campos de la acción. `elasticsearch` Para obtener más información, consulte [ElasticsearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_ElasticsearchAction.html).
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción de Elasticsearch con plantillas de sustitución en una regla. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
## Véase también
+ [OpenSearch](opensearch-rule-action.md)
+ [¿Qué es Amazon OpenSearch Service?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)
# HTTP
La acción HTTPS (`http`) envía los datos de un mensaje MQTT a un punto final HTTPS, que puede apuntar a una aplicación o servicio web.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Debe confirmar y habilitar los puntos de conexión HTTPS antes de que el motor de reglas pueda usarlos. Para obtener más información, consulte [Destinos de acciones HTTP](http-action-destination.md).
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`url`
El punto de conexión HTTPS al que se envía el mensaje mediante el método HTTP POST. Si utiliza una dirección IP en lugar de un nombre de host, debe ser una IPv4 dirección. IPv6 no se admiten direcciones.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`confirmationUrl`
(Opcional) Si se especifica, AWS IoT utiliza la URL de confirmación para crear un destino de regla temática coincidente. Debe habilitar el destino de la acción HTTP antes de usarlo en una acción HTTP. Para obtener más información, consulte [Destinos de acciones HTTP](http-action-destination.md). Si utiliza plantillas de sustitución, debe crear manualmente un destino de acción HTTP antes de poder utilizar la `http` acción. `confirmationUrl`debe ser un prefijo de`url`.
La relación entre `url` y `confirmationUrl` se describe de la siguiente manera:
+ Si `url` está codificado y no `confirmationUrl` se proporciona, tratamos implícitamente el `url` campo como. `confirmationUrl` AWS IoT crea un tema de destino para la regla. `url`
+ Si `url` y `confirmationUrl` están codificados, `url` deben empezar `confirmationUrl` por. AWS IoT crea un tema de destino para `confirmationUrl` la regla.
+ Si `url` contiene una plantilla de sustitución, debe especificar `confirmationUrl` y `url` debe comenzar por `confirmationUrl`. Si `confirmationUrl` contiene plantillas de sustitución, debe crear manualmente un destino de acción HTTP antes de poder utilizar la `http` acción. Si `confirmationUrl` no contiene plantillas de sustitución, AWS IoT crea un tema de destino para la regla`confirmationUrl`.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`headers`
(Opcional) La lista de encabezados que se van a incluir en las solicitudes HTTP al punto de conexión. Cada encabezado debe contener la siguiente información:
`key`
La clave del encabezado.
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`value`
El valor del encabezado.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
El tipo de contenido predeterminado es application/json cuando la carga útil está en formato JSON. De lo contrario, es application/octet-stream. Puede sobrescribirlo especificando el tipo de contenido exacto en el encabezado con el tipo de contenido de la clave (sin distinción entre mayúsculas y minúsculas).
`auth`
(Opcional) Autenticación utilizada por el motor de reglas para conectarse a la dirección URL del punto de conexión especificada en el argumento `url`. Actualmente, Signature Version 4 es el único tipo de autenticación admitido. Para obtener más información, consulte [Autorización HTTP](https://docs.aws.amazon.com/iot/latest/apireference/API_HttpAuthorization.html).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`enableBatching`
(Opcional) Si se deben procesar los mensajes de acción HTTP en una sola solicitud para una URL determinada. El valor puede ser verdadero o falso. Para obtener más información sobre el procesamiento por lotes, consulte Procesamiento por [lotes de mensajes de acción HTTP](http_batching.md).
Valor booleano
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`batchConfig`
(Opcional) Ajustes de configuración para el procesamiento por lotes. Una vez habilitados, se deben especificar `batchConfig` los parámetros. Si no se especifican los `batchConfig` parámetros, se utilizarán los valores predeterminados.
`maxBatchOpenMs`
El tiempo máximo (en milisegundos) que un mensaje saliente espera a que otros mensajes creen el lote. Cuanto más alta sea la configuración, mayor será la latencia de la acción HTTP agrupada en lotes.
Valor mínimo: 5 ms. Valor máximo: 200 ms.
Valor predeterminado: 20 ms
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`maxBatchSize`
El número máximo de mensajes que se agrupan en lotes en la ejecución de una sola acción.
Admite [plantillas de sustitución](iot-substitution-templates.md): No
Valor mínimo: 2 mensajes. Valor máximo: 10 mensajes
Valor predeterminado: 10 mensajes
`maxBatchSizeBytes`
Tamaño máximo de un lote de mensajes, en bytes.
Valor mínimo: 100 bytes. Valor máximo: 131.072 bytes
Valor predeterminado: 5.120 bytes
Admite [plantillas de sustitución](iot-substitution-templates.md): No
El tipo de contenido predeterminado es application/json cuando la carga útil está en formato JSON. De lo contrario, es application/octet-stream. Puede sobrescribirlo especificando el tipo de contenido exacto en el encabezado con el tipo de contenido de la clave (sin distinción entre mayúsculas y minúsculas).
## Ejemplos
El siguiente ejemplo de JSON define una AWS IoT regla con una acción HTTP.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
]
}
}
]
}
}
```
```
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 123,
"maxBatchSize": 5,
"maxBatchSizeBytes": 131072,
}
},
"errorAction": {
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com"
// batchConfig is not allowed here
}
}
```
## Lógica de reintento de acciones HTTP
El motor de AWS IoT reglas vuelve a intentar la acción HTTP de acuerdo con estas reglas:
+ El motor de reglas intenta enviar un mensaje al menos una vez.
+ El motor de reglas realiza como máximo dos reintentos. El número máximo de intentos es tres.
+ El motor de reglas no realiza un reintento si:
+ El intento anterior proporcionó una respuesta mayor de 16.384 bytes.
+ El servicio o la aplicación web de salida cierra la conexión TCP después del intento.
+ El tiempo total para completar una solicitud con reintentos superó el límite de tiempo de espera de la solicitud.
+ La solicitud devuelve un código de estado HTTP distinto de 429, 500-599.
**nota**
Se aplican [costos estándar de transferencia de datos](https://aws.amazon.com/ec2/pricing/on-demand/) a los reintentos.
## Véase también
+ [Procesamiento por lotes de mensajes de acción HTTP](http_batching.md)
+ [Destinos de acciones HTTP](http-action-destination.md)
+ [Enrute los datos directamente desde AWS IoT Core sus servicios web](https://aws.amazon.com/blogs/iot/route-data-directly-from-iot-core-to-your-web-services/) en el blog *de Internet de las AWS cosas*
# Procesamiento por lotes de mensajes de acción HTTP
Puedes usar el procesamiento por lotes para enviar varios mensajes de acción HTTP en una sola solicitud.
## Descripción general de
El procesamiento por lotes le permite enviar mensajes desde AWS IoT Core Rules Engine a sus puntos de enlace HTTP por lotes. Esta funcionalidad puede ayudarle a reducir los costes al reducir el número de ejecuciones de acciones HTTP, así como a mejorar la eficiencia al reducir la sobrecarga asociada al establecimiento de nuevas conexiones.
**nota**
La acción HTTP por lotes se mide como una acción única. Se mide en incrementos de 5 KiB, en función del tamaño de la carga útil saliente por lotes emitida por el motor de reglas al AWS IoT Core servicio descendente. Para obtener más información, consulte la [página de precios de AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
Cuando habilita el procesamiento por lotes en la definición de su acción de regla de IoT, los siguientes parámetros estarán disponibles para la configuración:
`maxBatchOpenMs`
El tiempo máximo (en milisegundos) que un mensaje saliente espera a que otros mensajes creen el lote. Cuanto más alta sea la configuración, mayor será la latencia de la acción HTTP agrupada en lotes.
Valor mínimo: 5 ms. Valor máximo: 200 ms.
Valor predeterminado: 20 ms
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`maxBatchSize`
La cantidad máxima de mensajes que se agrupan por lotes en una sola ejecución de acción de regla de IoT.
Valor mínimo: 2 mensajes. Valor máximo: 10 mensajes
Valor predeterminado: 10 mensajes
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`maxBatchSizeBytes`
Tamaño máximo de un lote de mensajes, en bytes.
Valor mínimo: 100 bytes. Valor máximo: 131.072 bytes
Valor predeterminado: 5120 bytes
Admite [plantillas de sustitución](iot-substitution-templates.md): No
**importante**
Al especificar varios parámetros de lote, el procesamiento por lotes finaliza cuando se alcanza el primer límite. Por ejemplo, si especifica 100 ms como el tiempo máximo de apertura del lote y 5 KiB como el tamaño máximo del lote, y Rules Engine solo graba 2 KiB en 100 ms, se creará y enviará un lote de 2 KiB.
## Uso de encabezados HTTP en un lote
Cuando utilizas encabezados en tu acción HTTP, la solicitud agrupada usa el valor del encabezado del último mensaje que se agregó al lote (no necesariamente el último mensaje que publicaste). Te recomendamos usar valores de encabezado que sean:
+ Idénticos en todos los mensajes del lote
+ Aplicable a todos los mensajes (por ejemplo, las credenciales de autenticación)
Los encabezados se envían con la solicitud HTTP y no forman parte del cuerpo del mensaje.
**nota**
Cuando el procesamiento por lotes está habilitado:
La solicitud agrupada incluye automáticamente el `Content-Type: application/json` encabezado, ya que el lote se envía como una matriz JSON.
No podemos garantizar que el último mensaje del lote sea el último mensaje que hayas publicado. Es el último mensaje que se incluyó en el lote.
## Ejemplo de carga útil
El siguiente ejemplo muestra la estructura de la carga útil de un mensaje por lotes que se envía a tu punto final HTTP:
```
[
{
"user_id": "user1",
"steps_today": 1000
},
{
"user_id": "user2",
"steps_today": 21000
},
{
"user_id": "user8",
"steps_today": 1500
},
...
]
```
## Limitaciones
Las siguientes son las limitaciones del procesamiento por lotes:
+ AWS IoT Core no garantiza el orden general de los mensajes. El procesamiento por lotes se realiza localmente en cada host, lo que puede provocar que los mensajes de un lote se procesen en un orden diferente al que se recibieron.
+ AWS IoT Core no proporciona soporte para el procesamiento de mensajes en el lado del receptor. Usted es responsable de garantizar que su servicio descendente esté configurado para aceptar y procesar los datos en lotes.
+ No se admite el procesamiento por lotes entre cuentas, incluso si los mensajes están destinados al mismo identificador de recurso (URL HTTP o ARN del recurso).
+ AWS IoT Core no garantiza que el tamaño del lote cumpla con la configuración que especificó. Los lotes pueden ser más pequeños que los límites configurados en función del tiempo y el flujo de mensajes.
+ Cuando el procesamiento por lotes está activado, no se admiten las cargas útiles binarias (datos que no sean UTF-8). Solo se aceptan cargas útiles de texto en UTF-8 (como JSON). Para enviar datos binarios, base64 los codifica antes de enviarlos a la acción HTTP y, a continuación, los decodifica en el punto final receptor. Por ejemplo, puede usar la [función](iot-sql-functions.html#iot-function-encode) de codificación en las reglas de IoT para codificar la carga útil binaria. Como alternativa, puedes codificar la carga binaria en tu dispositivo IoT y publicarla en. AWS IoT Core
## Acciones de error al procesar por lotes
No podrá definir una lógica de procesamiento por lotes independiente en la definición de la acción de error. Sin embargo, su acción de error admitirá el procesamiento por lotes si ha definido la lógica de procesamiento por lotes en su acción principal.
Cuando se produce un error en una solicitud por lotes, el motor de AWS IoT Core reglas seguirá la lógica de [reintento de una acción HTTP](https-rule-action.md#https-rule-action-retry-logic). Tras el último intento, se ejecutará una acción de error para todo el lote fallido.
El siguiente es un ejemplo de un mensaje de acción de error con el procesamiento por lotes activado:
```
{
"ruleName": "FailedTopicRule",
"topic": "topic/rulesengine",
"payloadsWithMetadata": [
{
"id": 1,
"cloudwatchTraceId": "bebd6d93-6d4a-899e-9e40-56e82252d2be",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 2,
"cloudwatchTraceId": "af94d3b8-0b18-1dbf-2c7d-513f5cb9e2e1",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 3,
"cloudwatchTraceId": "ca441266-c2ce-c916-6aee-b9e5c7831675",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
}
],
"failures": [
{
"affectedIds": [
1,
2,
3
],
"failedAction": "HttpAction",
"failedResource": "https://example.foobar.com/HttpAction",
"errorMessage": "HttpAction failed to make a request to the specified endpoint. StatusCode: 500. Reason: Internal Server Error."
},
{
"affectedIds": [
3
],
"failedAction": "S3Action",
"failedResource": "amzn-s3-demo-bucket",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist"
},
{
"affectedIds": [
3
],
"failedAction": "LambdaAction",
"failedResource": "arn:aws:lambda:us-west-2:123456789012:function:dummy",
"errorMessage": "Failed to invoke lambda function. Received Server error from Lambda. The error code is 403"
}
]
}
```
**nota**
Los errores de las acciones por lotes también generan una mayor carga útil de las acciones de error, lo que, debido al tamaño, puede aumentar la probabilidad de que se produzcan errores en las acciones de error. Puede supervisar los fallos en las acciones de error mediante la `ErrorActionFailure` métrica. Para obtener más información, consulte [Métricas de acciones de reglas](metrics_dimensions.md#rule-action-metrics).
## Agrupar por lotes los mensajes de acción HTTP con AWS CLI
### Crear o actualizar una acción de regla con procesamiento por lotes
1. Utilice el AWS CLI comando correspondiente para crear o actualizar una regla:
+ Para crear una regla nueva, utilice el [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)comando:
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
+ Para actualizar una regla existente, utilice el [replace-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/replace-topic-rule.html)comando:
```
aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
1. Habilite las capacidades de procesamiento por lotes configurando el parámetro enableBatching en true en la carga útil de la regla temática:
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 100,
"maxBatchSize": 5,
"maxBatchSizeBytes": 1024
}
}
}
]
}
```
1. Configure los parámetros de procesamiento por lotes. No es necesario especificar todos los parámetros del lote. Puede elegir especificar 1, 2 o los 3 parámetros del lote. Si no especifica un parámetro de lote, Rules Engine actualizará ese parámetro con los valores predeterminados. Para obtener más información sobre los parámetros de procesamiento por lotes y sus valores predeterminados, consulte [Parámetros HTTP](https-rule-action.md#https-rule-action-parameters).
# Destinos de acciones HTTP
Un destino de acción HTTP es un servicio web al que el motor de reglas puede enrutar los datos de una regla temática. Un AWS IoT Core recurso describe el servicio web para AWS IoT. Los recursos de destino se pueden compartir mediante diferentes reglas.
Antes de AWS IoT Core poder enviar datos a otro servicio web, debe confirmar que puede acceder al punto final del servicio.
## Descripción general de
El destino de una acción HTTP hace referencia a un servicio web que admite una URL de confirmación y una o varias recopilaciones de datos URLs. El recurso de destino contiene la URL de confirmación de su servicio web. Al configurar una acción HTTP, se especifica la URL real del punto final que debe recibir los datos junto con la URL de confirmación del servicio web. Una vez confirmado el destino, la regla temática envía el resultado de la sentencia SQL al punto de conexión HTTPS (y no a la URL de confirmación).
El destino de una acción HTTP puede estar en uno de los siguientes estados:
ENABLED
El destino se ha confirmado y se puede utilizar mediante una acción de regla. Un destino debe tener el estado `ENABLED` para que se utilice en una regla. Solo puede habilitar destinos con el estado DISABLED.
DISABLED
El destino se ha confirmado y se puede utilizar mediante una acción de regla. Esto es útil si desea impedir temporalmente el tráfico a su punto de conexión sin tener que pasar de nuevo por el proceso de confirmación. Solo puede deshabilitar un destino con el estado ENABLED.
IN\$1PROGRESS
La confirmación del destino se está realizando.
ERROR
Se ha agotado el tiempo de espera de confirmación del destino.
Una vez que se haya confirmado y habilitado el destino de una acción HTTP, se puede usar con cualquier regla de tu cuenta.
## Administrar los destinos de acciones HTTP
Puede utilizar las siguientes operaciones para gestionar los destinos de sus acciones HTTP.
### Crear destinos de acción HTTP
Para crear un destino de acción HTTP, llame a la `CreateTopicRuleDestination` operación o utilice la AWS IoT consola.
Tras crear un destino, AWS IoT envía una solicitud de confirmación a la URL de confirmación. La solicitud de confirmación tiene el siguiente formato:
```
HTTP POST {confirmationUrl}/?confirmationToken={confirmationToken}
Headers:
x-amz-rules-engine-message-type: DestinationConfirmation
x-amz-rules-engine-destination-arn:"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4"
Content-Type: application/json
Body:
{
"arn":"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4",
"confirmationToken": "AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"enableUrl": "https://iot.us-east-1.amazonaws.com/confirmdestination/AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"messageType": "DestinationConfirmation"
}
```
El contenido de la solicitud de confirmación incluye la siguiente información:
arn
El nombre del recurso de Amazon (ARN) del destino de la acción HTTP a confirmar.
confirmationToken
El token de confirmación enviado por AWS IoT Core. El token del ejemplo está truncado. Su token será mayor. Necesitará este token para confirmar su destino con AWS IoT Core.
enableUrl
La dirección URL a la que se desplaza para confirmar el destino de una regla del tema.
messageType
Tipo de mensaje.
### Confirmar los destinos de las acciones HTTP
Para completar el proceso de confirmación del punto de conexión, si utiliza la AWS CLI, debe realizar uno de los siguientes pasos después de que su URL de confirmación reciba la solicitud de confirmación.
1.
**Confirme que el destino está listo para recibir mensajes**
Para confirmar que el destino de la acción HTTP está listo para recibir mensajes de IoT, llama a la que `enableUrl` aparece en la solicitud de confirmación o realiza la operación de `ConfirmTopicRuleDestination` API y pasa la `confirmationToken` de la solicitud de confirmación.
1.
**Definición del estado de la regla temática como activado**
Después de confirmar que el destino puede recibir mensajes, debe ejecutar la operación de la API `UpdateTopicRuleDestination` para establecer el estado de la regla temática en `ENABLED`.
Si utilizas la AWS IoT consola, cópiala `confirmationToken` y pégala en el cuadro de diálogo de confirmación del destino en la AWS IoT consola. A continuación, ya podrá activar la regla temática.
### Enviar una nueva solicitud de confirmación
Para activar un nuevo mensaje de confirmación para un destino, llame a `UpdateTopicRuleDestination` y establezca el estado del destino de la regla del tema en `IN_PROGRESS`.
Repita el proceso de confirmación después de enviar una nueva solicitud de confirmación.
### Deshabilitar y eliminar un destino de acción HTTP
Para deshabilitar un destino, llame a `UpdateTopicRuleDestination` y establezca el estado del destino de la regla del tema en `DISABLED`. Una regla temática en estado DESACTIVADO se puede volver a activar sin necesidad de enviar una nueva solicitud de confirmación.
Para eliminar un destino de acción HTTP, llama`DeleteTopicRuleDestination`.
## Certificate Authority Support
**nota**
No se admiten los certificados autofirmados.
Los puntos de enlace HTTPS de un destino de acción HTTP admiten certificados emitidos tanto por [AWS Private Certificate Authority](https://www.amazontrust.com/repository/) como por [Lets](https://letsencrypt.org/certificates/) Encrypt.
# AWS IoT Events
La acción AWS IoT Events (`iotEvents`) envía los datos de un mensaje MQTT a una AWS IoT Events entrada.
**importante**
Si la carga útil se envía AWS IoT Core sin la`Input attribute Key`, o si la clave no está en la misma ruta JSON especificada en la clave, se producirá un error `Failed to send message to Iot Events` en la regla de IoT.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Un rol de IAM que AWS IoT puede asumir para realizar la `iotevents:BatchPutMessage` operación. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`batchMode`
(Opcional) Si se procesan las acciones de evento como un lote. El valor predeterminado es `false`.
Cuando `batchMode` es `true` y la sentencia SQL de la regla se evalúa como una matriz, cada elemento de la matriz se trata como un mensaje independiente cuando se envía a AWS IoT Events mediante una llamada [https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html](https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html). La matriz resultante no puede tener más de 10 mensajes.
Cuando `batchMode` es `true`, no puede especificar un `messageId`.
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`inputName`
El nombre de la AWS IoT Events entrada.
Soporta [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`messageId`
(Opcional) Use esto para verificar que un AWS IoT Events detector procese solo una entrada (mensaje) con un dato determinado`messageId`. Puede utilizar la plantilla de sustitución `${newuuid()}` para generar un identificador único para cada solicitud.
Cuando `batchMode` es `true`, no puede especificar un `messageId`. Se asignará un nuevo valor UUID.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleArn`
La función de IAM que permite AWS IoT enviar una entrada a un AWS IoT Events detector. Para obtener más información, consulte [Requisitos](#iotevents-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo JSON define una acción de Eventos IoT en una regla AWS IoT .
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotEvents": {
"inputName": "MyIoTEventsInput",
"messageId": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_events"
}
}
]
}
}
```
## Véase también
+ [¿Qué es? AWS IoT Events](https://docs.aws.amazon.com/iotevents/latest/developerguide/) en la *Guía AWS IoT Events para desarrolladores*
# AWS IoT SiteWise
La acción AWS IoT SiteWise (`iotSiteWise`) envía los datos de un mensaje MQTT a las propiedades del activo. AWS IoT SiteWise
Puedes seguir un tutorial que te muestra cómo ingerir datos de AWS IoT cosas. *Para obtener más información, consulta el tutorial sobre cómo [ingerir datos AWS IoT SiteWise desde AWS IoT cosas](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) o la sección Cómo [ingerir datos mediante las reglas AWS IoT básicas](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html) de la Guía del AWS IoT SiteWise usuario.*
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar la operación. `iotsitewise:BatchPutAssetPropertyValue` Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
Puede asociar el siguiente ejemplo de política de confianza al rol.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*"
}
]
}
```
Para mejorar la seguridad, puede especificar una ruta jerárquica de AWS IoT SiteWise activos en la `Condition` propiedad. El siguiente ejemplo es una política de confianza que especifica una ruta jerárquica de activos.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
+ Al enviar datos a AWS IoT SiteWise mediante esta acción, estos deben cumplir los requisitos de la `BatchPutAssetPropertyValue` operación. Para obtener más información, consulta [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) en la *AWS IoT SiteWise Referencia de la API de *.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`putAssetPropertyValueEntries`
Una lista de entradas de valor de propiedad de recurso, en la que cada entrada contiene la siguiente información:
`propertyAlias`
(Opcional) El alias de propiedad asociado a su propiedad de activo. Debe especificar un `propertyAlias` o tanto un `assetId` como un `propertyId`. Para obtener más información acerca de los alias de propiedades, consulte [Mapeo de flujos de datos industriales a propiedades de recursos](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/connect-data-streams.html) en la *Guía del usuario de AWS IoT SiteWise *.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`assetId`
(Opcional) El ID del AWS IoT SiteWise activo. Debe especificar un `propertyAlias` o tanto un `assetId` como un `propertyId`.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`propertyId`
(Opcional) El ID de la propiedad de activo. Debe especificar un `propertyAlias` o tanto un `assetId` como un `propertyId`.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`entryId`
(Opcional) Un identificador único para esta entrada. Defina el `entryId` para rastrear mejor qué mensaje causó un error si se produce un fallo. El valor predeterminado es un nuevo UUID.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`propertyValues`
Una lista de valores de propiedad que se van a insertar, en la que cada valor contiene una marca temporal, la calidad y el valor (TQV) en el formato siguiente:
`timestamp`
Una estructura de marca temporal que contiene la siguiente información:
`timeInSeconds`
Una cadena que contiene el tiempo en segundos en formato de tiempo Unix. Si su carga de mensajes no tiene una marca temporal, puede usar [timestamp()](iot-sql-functions.md#iot-function-timestamp), que devuelve la hora actual en milisegundos. Para convertir ese tiempo en segundos, puede utilizar la siguiente plantilla de sustitución: **\$1\$1floor(timestamp() / 1E3)\$1**.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`offsetInNanos`
(Opcional) Una cadena que contiene el desfase de tiempo en nanosegundos a partir del tiempo en segundos. Si su carga de mensajes no tiene una marca temporal, puede usar [timestamp()](iot-sql-functions.md#iot-function-timestamp), que devuelve la hora actual en milisegundos. Para calcular el desfase en nanosegundos a partir de ese tiempo, puede utilizar la siguiente plantilla de sustitución: **\$1\$1(timestamp() % 1E3) \$1 1E6\$1**.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
Con respecto a la época de Unix, solo AWS IoT SiteWise acepta entradas que tengan una marca de tiempo de hasta 7 días en el pasado y hasta 5 minutos en el futuro.
`quality`
(Opcional) Una cadena que describe la calidad del valor. Valores válidos: `GOOD`, `BAD`, `UNCERTAIN`.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`value`
Una estructura de valores que contiene uno de los siguientes campos de valor, en función del tipo de datos de la propiedad del recurso:
`booleanValue`
(Opcional) Una cadena que contiene el valor booleano de la entrada del valor.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`doubleValue`
(Opcional) Una cadena que contiene el valor “double” (doble) de la entrada del valor.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`integerValue`
(Opcional) Una cadena que contiene el valor entero de la entrada del valor.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`stringValue`
(Opcional) El valor de cadena de la entrada del valor.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleArn`
El ARN de la función de IAM que concede el AWS IoT permiso para enviar el valor de una propiedad de un activo a. AWS IoT SiteWise Para obtener más información, consulte [Requisitos](#iotsitewise-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una SiteWise acción básica de IoT en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "/some/property/alias",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${my.payload.timeInSeconds}"
},
"value": {
"integerValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una SiteWise acción de IoT en una AWS IoT regla. En este ejemplo se utiliza el tema como alias de propiedad y función `timestamp()`. Por ejemplo, si publica datos en `/company/windfarm/3/turbine/7/rpm`, esta acción envía los datos a la propiedad del recurso con un alias de propiedad que es el mismo que el tema especificado.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM '/company/windfarm/+/turbine/+/+'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "${topic()}",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${floor(timestamp() / 1E3)}",
"offsetInNanos": "${(timestamp() % 1E3) * 1E6}"
},
"value": {
"doubleValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
## Véase también
+ ¿[Qué es AWS IoT SiteWise?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) en la * Guía del usuario de AWS IoT SiteWise *
+ [Ingerir datos mediante AWS IoT Core las reglas](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html) de la Guía del *AWS IoT SiteWise usuario*
+ [Ingerir datos a AWS IoT SiteWise partir de AWS IoT elementos de](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) *la Guía del usuario AWS IoT SiteWise *
+ [Solución de problemas de una AWS IoT SiteWise acción regulada](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/troubleshoot-rule.html) en la Guía del *AWS IoT SiteWise usuario*
# Firehose
La acción de Firehose (`firehose`) envía datos de un mensaje MQTT a un flujo de Amazon Data Firehose.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Un rol de IAM que AWS IoT puede asumir para realizar la operación. `firehose:PutRecord` Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utilizas Firehose para enviar datos a un bucket de Amazon S3 y utilizas un AWS KMS cliente gestionado AWS KMS key para cifrar los datos en reposo en Amazon S3, Firehose debe tener acceso a tu bucket y permiso para usarlo AWS KMS key en nombre de la persona que llama. Para obtener más información, consulte [Grant Firehose access to an Amazon S3 destination](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-s3) en la *Guía para desarrolladores de Amazon Data Firehose*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`batchMode`
(Opcional) Si entregar o no el flujo de Firehose como lote con [https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html). El valor predeterminado es `false`.
Cuando `batchMode` es `true` y la instrucción de SQL de la regla se evalúa como una matriz, cada elemento de la matriz forma un registro en la solicitud `PutRecordBatch`. La matriz resultante no puede tener más de 500 registros.
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`deliveryStreamName`
El flujo de Firehose en el que deben escribirse los datos del mensaje.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`separator`
(Opcional) Un separador de caracteres que se utilizará para separar registros escritos en el flujo de Firehose. Si omite este parámetro, el flujo no utiliza ningún separador. Valores válidos: `,` (coma), `\t` (tabulador), (nueva línea), `\n` (nueva línea de Windows). `\r\n`
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`roleArn`
El rol de IAM que permite acceder al flujo de Firehose. Para obtener más información, consulte [Requisitos](#kinesis-firehose-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción Firehose en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "my_firehose_stream",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción Firehose con plantillas de sustitución en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
## Véase también
+ [¿What is Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/) en la *Guía para desarrolladores de Amazon Data Firehose*
# Kinesis Data Streams
La acción Kinesis Data Streams (`kinesis`) escribe datos de un mensaje MQTT en Amazon Kinesis Data Streams.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar la operación. `kinesis:PutRecord` Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utiliza una clave KMS AWS KMS administrada por el cliente AWS KMS key para cifrar los datos en reposo en Kinesis Data Streams, el servicio debe tener permiso para utilizarla en nombre de AWS KMS key la persona que llama. Para obtener más información, consulte [Permisos de uso generados por el usuario AWS KMS keys](https://docs.aws.amazon.com/streams/latest/dev/permissions-user-key-KMS.html) en la *guía para desarrolladores de Amazon Kinesis Data Streams*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`stream`
El flujo de datos Kinesis en el que escribir los datos.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`partitionKey`
La clave de partición utilizada para determinar en qué fragmento se escriben los datos. La clave de partición suele estar compuesta por una expresión (por ejemplo, `${topic()}` o `${timestamp()}`).
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleArn`
El ARN del rol de IAM que concede el AWS IoT permiso para acceder a la transmisión de datos de Kinesis. Para obtener más información, consulte [Requisitos](#kinesis-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción de Kinesis Data Streams en AWS IoT una regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "my_kinesis_stream",
"partitionKey": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción de Kinesis con plantillas de sustitución en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "${topic()}",
"partitionKey": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
## Véase también
+ [¿Qué es Amazon Kinesis Data Streams?](https://docs.aws.amazon.com/streams/latest/dev/) en la *Guía para desarrolladores de Amazon Kinesis Data Streams*.
# Lambda
Una acción Lambda (`lambda`) invoca una AWS Lambda función y pasa un mensaje MQTT. AWS IoT invoca funciones Lambda de forma asíncrona.
Puede seguir un tutorial que muestra cómo crear y probar una regla con una acción de Lambda. Para obtener más información, consulte [Tutorial: Formatear una notificación mediante una AWS Lambda función](iot-lambda-rule.md).
## Requisitos
Esta regla tiene los siguientes requisitos:
+ AWS IoT Para invocar una función Lambda, debe configurar una política que conceda `lambda:InvokeFunction` el permiso a. AWS IoT Solo puede invocar una función de Lambda definida en el Región de AWS mismo lugar donde existe su política de Lambda. Las funciones de Lambda utilizan políticas basadas en recursos, por lo que debe asociar la política a la función de Lambda en sí.
Utilice el siguiente AWS CLI comando para adjuntar una política que conceda el permiso. `lambda:InvokeFunction` En este comando, sustituya:
+ *function\$1name*con el nombre de la función Lambda. Agrega un nuevo permiso para actualizar la política de recursos de la función.
+ *region*con el Región de AWS de la función.
+ *account-id*con el Cuenta de AWS número en el que se define la regla.
+ *rule-name*con el nombre de la AWS IoT regla para la que está definiendo la acción Lambda.
+ *unique\$1id*con un identificador de declaración único.
**importante**
Si agrega un permiso para un AWS IoT principal sin proporcionar el `source-arn` o`source-account`, cualquiera Cuenta de AWS que cree una regla con su acción de Lambda puede activar reglas desde las que invocar la función de Lambda. AWS IoT
Para obtener más información, consulte [Permisos de AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).
```
aws lambda add-permission \
--function-name function_name \
--region region \
--principal iot.amazonaws.com \
--source-arn arn:aws:iot:region:account-id:rule/rule_name \
--source-account account-id
--statement-id unique_id
--action "lambda:InvokeFunction"
```
+ Si utiliza la AWS IoT consola para crear una regla para la acción de la regla Lambda, la función Lambda se activa automáticamente. Si la usa AWS CloudFormation en su lugar con [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html), debe agregar un [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)recurso. A continuación, el recurso le concede permiso para desencadenar la función de Lambda.
En el siguiente código se muestra un ejemplo de cómo agregar este recurso. En este ejemplo, sustituya:
+ *function\$1name*con el nombre de la función Lambda.
+ *region*con el Región de AWS de la función.
+ *account-id*con el Cuenta de AWS número en el que se define la regla.
+ *rule-name*con el nombre de la AWS IoT regla para la que está definiendo la acción Lambda.
```
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName: !Ref function_name
Principal: "iot.amazonaws.com"
SourceAccount: account-id
SourceArn: arn:aws:iot:region:account-id:rule/rule_name
```
+ Si utiliza un AWS KMS cliente gestionado AWS KMS key para cifrar datos en reposo en Lambda, el servicio debe tener permiso para utilizarlos en nombre de AWS KMS key la persona que llama. Para obtener más información, consulte [Encryption at rest](https://docs.aws.amazon.com/lambda/latest/dg/security-dataprotection.html#security-privacy-atrest) (Cifrado en reposo) en la *Guía para desarrolladores de AWS Lambda *.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`functionArn`
El ARN de la función Lambda que se va a invocar. AWS IoT debe tener permiso para invocar la función. Para obtener más información, consulte [Requisitos](#lambda-rule-action-requirements).
Si no especifica una versión o un alias para su función de Lambda, se cerrará la versión más reciente de la función. Puede especificar una versión o un alias si desea cerrar una versión específica de su función de Lambda. Para especificar una versión o alias, añada la versión o el alias en el ARN de la función de Lambda.
```
arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias
```
Para obtener más información acerca del control de versiones y los alias, consulte [Control de versiones y alias de las funciones de AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html).
Admite [plantillas de sustitución](iot-substitution-templates.md): API y únicamente AWS CLI
## Ejemplos
El siguiente ejemplo de JSON define una acción Lambda en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción Lambda con plantillas de sustitución en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:${topic()}"
}
}
]
}
}
```
## Véase también
+ [¿Qué es? AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/) en la *Guía AWS Lambda para desarrolladores*
+ [Tutorial: Formatear una notificación mediante una AWS Lambda función](iot-lambda-rule.md)
# Ubicación
La acción Ubicación (`location`) envía sus datos de ubicación geográfica a [Amazon Location Service](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html).
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar la `geo:BatchUpdateDevicePosition` operación. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`deviceId`
El identificador único del dispositivo que proporciona los datos de ubicación. Para obtener más información, consulte la [https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html](https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html) de la *Referencia de la API de Amazon Location Service*.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`latitude`
Una cadena que se evalúa como un valor doble que representa la latitud de la ubicación del dispositivo.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`longitude`
Una cadena que se evalúa como un valor doble que representa la longitud de la ubicación del dispositivo.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleArn`
El rol de IAM que permite el acceso al dominio de Amazon Location Service. Para obtener más información, consulte [Requisitos](#location-rule-action-requirements).
`timestamp`
La hora en que se muestrearon los datos de ubicación. El valor predeterminado es la hora en que se procesó el mensaje MQTT.
El valor `timestamp` se compone de los siguientes dos valores:
+ `value`: Una expresión que devuelve un valor de tiempo de época larga. Puede utilizar la función [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) para crear una marca de tiempo válida a partir de un valor de fecha u hora incluido en la carga útil del mensaje. Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
+ `unit`: (Opcional) La precisión del valor de marca de tiempo que resulta de la expresión que se describe en `value`. Valores válidos: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS` El valor predeterminado es `MILLISECONDS`. Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente.
`trackerName`
El nombre del recurso de seguimiento de Amazon Location en el que se actualiza la ubicación. Para obtener más información, consulte [Rastreador](https://docs.aws.amazon.com//location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview) en la *Guía para desarrolladores de Amazon Location Service*.
Soporta [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
## Ejemplos
El siguiente ejemplo de JSON define una acción de ubicación en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123454962127:role/service-role/ExampleRole",
"trackerName": "MyTracker",
"deviceId": "001",
"sampleTime": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "-12.3456",
"longitude": "65.4321"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción de ubicación con plantillas de sustitución en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/ExampleRole",
"trackerName": "${TrackerName}",
"deviceId": "${DeviceID}",
"timestamp": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "${get(position, 0)}",
"longitude": "${get(position, 1)}"
}
}
]
}
}
```
El siguiente ejemplo de carga útil de MQTT muestra cómo las plantillas de sustitución del ejemplo anterior acceden a los datos. Puede usar el comando CLS [https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html](https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html) para verificar que los datos de carga útil MQTT se entreguen en su rastreador de ubicación.
```
{
"TrackerName": "mytracker",
"DeviceID": "001",
"position": [
"-12.3456",
"65.4321"
]
}
```
```
aws location get-device-position-history --device-id 001 --tracker-name mytracker
```
```
{
"DevicePositions": [
{
"DeviceId": "001",
"Position": [
-12.3456,
65.4321
],
"ReceivedTime": "2022-11-11T01:31:54.464000+00:00",
"SampleTime": "2022-11-11T01:31:54.308000+00:00"
}
]
}
```
## Véase también
+ [¿Qué es Amazon Location Service?](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html) en la *Guía para desarrolladores de Amazon Location Service*.
# OpenSearch
La acción OpenSearch (`openSearch`) escribe los datos de los mensajes MQTT en un dominio de Amazon OpenSearch Service. A continuación, puede utilizar herramientas como los OpenSearch paneles de control para consultar y visualizar los datos en OpenSearch Service.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar la `es:ESHttpPut` operación. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utilizas un servicio gestionado por un cliente AWS KMS key para cifrar los datos en reposo, el OpenSearch servicio debe tener permiso para utilizar la clave KMS en nombre de la persona que llama. Para obtener más información, consulta [Cifrado de datos en reposo para Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html) en la *Guía para desarrolladores de Amazon OpenSearch Service*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`endpoint`
El punto final de tu dominio OpenSearch de Amazon Service.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`index`
El OpenSearch índice en el que desea almacenar sus datos.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`type`
Tipo de documento que está almacenando.
Para OpenSearch las versiones posteriores a la 1.0, el valor del `type` parámetro debe ser`_doc`. Para obtener más información, consulte la [Documentación de OpenSearch ](https://opensearch.org/docs/1.0/opensearch/rest-api/document-apis/index-document/#response-body-fields).
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`id`
Identificador único de cada documento.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleARN`
La función de IAM que permite el acceso al dominio del OpenSearch servicio. Para obtener más información, consulte [Requisitos](#opensearch-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Limitaciones
La acción OpenSearch (`openSearch`) no se puede usar para entregar datos a los clústeres de Elasticsearch de VPC.
## Ejemplos
El siguiente ejemplo de JSON define una OpenSearch acción en una AWS IoT regla y cómo se pueden especificar los campos de la acción. `OpenSearch` Para obtener más información, consulte [OpenSearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_OpenSearchAction.html).
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "_doc",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una OpenSearch acción con plantillas de sustitución en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
**nota**
El `type` campo sustituido funciona en la OpenSearch versión 1.0. Para cualquier versión posterior a la 1.0, el valor de `type` debe ser `_doc`.
## Véase también
[¿Qué es Amazon OpenSearch Service?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/) en la *Guía para desarrolladores OpenSearch de Amazon Service*
# Volver a publicar
La acción republish (`republish`) vuelve a publicar un mensaje MQTT en otro tema MQTT.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Un rol de IAM que AWS IoT puede asumir para realizar la operación. `iot:Publish` Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`headers`
Información acerca de los encabezados de la versión 5.0 de MQTT.
Para obtener más información consulte [RepublishAction](https://docs.aws.amazon.com//iot/latest/apireference/API_RepublishAction.html) y [MqttHeaders](https://docs.aws.amazon.com//iot/latest/apireference/API_MqttHeaders.html) en la *Referencia de la API de AWS *.
`topic`
El tema MQTT en el que se va a volver a publicar el mensaje.
Para volver a publicar en un tema reservado, que comience por `$` , utilice `$$` en su lugar. Por ejemplo, para volver a publicar en el tema sombra del dispositivo `$aws/things/MyThing/shadow/update`, especifique el tema como `$$aws/things/MyThing/shadow/update`.
No se permite volver a publicar en [temas de trabajo reservados](reserved-topics.md#reserved-topics-job).
AWS IoT Device Defender los temas de reserva no admiten la publicación en HTTP.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`qos`
(Opcional) El nivel de calidad de servicio (QoS) que se utiliza para volver a publicar mensajes. Valores válidos: `0`, `1`. El valor predeterminado es `0`. Para obtener más información acerca de MQTT QoS, consulte [MQTT](mqtt.md).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`roleArn`
La función de IAM que permite AWS IoT publicar en el tema MQTT. Para obtener más información, consulte [Requisitos](#republish-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción de republicación en una regla. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "another/topic",
"qos": 1,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción de republicación con plantillas de sustitución en una AWS IoT regla.
```
{
"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"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción de republicación dentro de una `headers` AWS IoT regla.
```
{
"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": "ruleKey2",
"value": "ruleValue2"
}
]
}
}
}
]
}
}
```
**nota**
La IP de origen original no se transferirá a través de la [acción Republicar](#republish-rule-action).
# S3
La acción S3 (`s3`) escribe los datos de un mensaje MQTT en un bucket de Amazon Simple Storage Service (Amazon S3).
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Un rol de IAM que AWS IoT puede asumir para realizar la `s3:PutObject` operación. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utiliza un servicio AWS KMS gestionado por el cliente AWS KMS key para cifrar los datos en reposo en Amazon S3, el servicio debe tener permiso para utilizarlos AWS KMS key en nombre de la persona que llama. Para obtener más información, consulte [AWS Gestionado AWS KMS keys y gestionado por el cliente AWS KMS keys](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-cmks) en la *Guía para desarrolladores de Amazon Simple Storage Service*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`bucket`
El bucket de Amazon S3 en el que se escribirán los datos.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`cannedacl`
(Opcional) La lista de control de acceso (ACL) predefinida de Amazon S3 que controla el acceso al objeto identificado mediante la clave de objeto. Para obtener más información, incluidos los valores permitidos, consulte [ACL predefinidas](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`key`
La ruta al archivo en el que se escriben los datos.
Considere un ejemplo en el que se encuentra este parámetro `${topic()}/${timestamp()}` y la regla recibe un mensaje donde se encuentra el tema `some/topic`. Si la marca de tiempo actual es `1460685389`, esta acción escribe los datos en un archivo llamado `1460685389` en la carpeta `some/topic` del bucket de S3
Si usa una clave estática, AWS IoT sobrescribe un solo archivo cada vez que se invoque la regla. Le recomendamos que utilice la marca de tiempo del mensaje u otro identificador de mensaje único para que se guarde un nuevo archivo en Amazon S3 por cada mensaje recibido.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleArn`
El rol de IAM que permite el acceso al bucket de Amazon S3. Para obtener más información, consulte [Requisitos](#s3-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción de S3 en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"cannedacl": "public-read",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3"
}
}
]
}
}
```
## Véase también
+ [¿Qué es Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/) en la *Guía del usuario de Amazon Simple Storage Service*
# IoT de Salesforce
La acción Salesforce IoT (`salesforce`) envía los datos del mensaje MQTT que activó la regla a un flujo de entrada de Salesforce IoT.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`url`
La dirección URL expuesta por el flujo de entrada de Salesforce IoT. La dirección URL está disponible en la plataforma de Salesforce IoT cuando crea un flujo de entrada. Para obtener más información, consulte la documentación de Salesforce IoT.
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`token`
El token que se utiliza para autenticar el acceso al flujo de entrada de Salesforce IoT especificado. El token está disponible en la plataforma de Salesforce IoT cuando se crea un flujo de entrada. Para obtener más información, consulte la documentación de Salesforce IoT.
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo JSON define una acción de Salesforce IoT en una regla AWS IoT .
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"salesforce": {
"token": "ABCDEFGHI123456789abcdefghi123456789",
"url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event"
}
}
]
}
}
```
# SNS
La acción SNS (`sns`) envía los datos de un mensaje MQTT como una notificación push de Amazon Simple Notification Service (Amazon SNS).
Puede seguir un tutorial que le muestra cómo crear y probar una regla con una acción SNS. Para obtener más información, consulte [Tutorial: Envío de una notificación de Amazon SNS](iot-sns-rule.md).
**nota**
La acción SNS no es compatible con los [temas FIFO (First-In-First-Out) de Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html). Dado que el motor de reglas es un servicio totalmente distribuido, no se garantiza el orden de los mensajes cuando se invoca la acción SNS.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Un rol de IAM que AWS IoT puede asumir para realizar la operación. `sns:Publish` Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utilizas un AWS KMS servicio gestionado por el cliente AWS KMS key para cifrar los datos en reposo en Amazon SNS, el servicio debe tener permiso para utilizarlos AWS KMS key en nombre de la persona que llama. Para obtener más información, consulte [Gestión de claves](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html) en la *Guía para desarrolladores de Amazon Simple Notification Service*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`targetArn`
El tema de SNS o el dispositivo individual al que se enviará la notificación de inserción.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`messageFormat`
(Opcional) El formato del mensaje. Amazon SNS utiliza esta configuración para determinar si la carga debe analizarse y las partes pertinentes de la carga específicas de la plataforma deben extraerse. Valores válidos: `JSON`, `RAW`. El valor predeterminado es `RAW`.
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`roleArn`
El rol de IAM que permite obtener acceso a SNS. Para obtener más información, consulte [Requisitos](#sns-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción de SNS en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-2:123456789012:my_sns_topic",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción de SNS con plantillas de sustitución en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-1:123456789012:${topic()}",
"messageFormat": "JSON",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
## Véase también
+ [¿Qué es Amazon Simple Notification Service?](https://docs.aws.amazon.com/sns/latest/dg/) en la *Guía para desarrolladores de Amazon Simple Notification Service*
+ [Tutorial: Envío de una notificación de Amazon SNS](iot-sns-rule.md)
# SQS
La acción SQS (`sqs`) envía datos de un mensaje MQTT a una cola de Amazon Simple Queue Service (Amazon SQS).
**nota**
La acción SQS no es compatible con las [colas FIFO (First-In-First-Out) de Amazon SQS.](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html). Dado que el motor de reglas es un servicio totalmente distribuido, no se garantiza el orden de los mensajes cuando se activa la acción de SQS.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Un rol de IAM que AWS IoT puede asumir para realizar la operación. `sqs:SendMessage` Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utiliza un sistema gestionado por el AWS KMS cliente AWS KMS key para cifrar datos en reposo en Amazon SQS, el servicio debe tener permiso para utilizarlos en nombre de AWS KMS key la persona que llama. Para obtener más información, consulte [Gestión de claves](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html) en la *Guía para desarrolladores de Amazon Simple Queue Service*.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`queueUrl`
La dirección URL de la cola Amazon SQS en la que se escriben los datos. La región de esta URL no tiene por qué ser la Región de AWS misma que la [AWS IoT regla](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html).
Puede haber cargos adicionales por la transferencia de datos entre Regiones de AWS si se utiliza la acción de la regla de SQS. Para obtener más información, consulte [precios de Amazon SQS](https://aws.amazon.com/sqs/pricing/).
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`useBase64`
Establezca este parámetro en `true` para configurar la acción de la regla para codificar en base64 los datos del mensaje antes de escribirlos en la cola de Amazon SQS. El valor predeterminado es `false`.
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`roleArn`
El rol de &IAM que permite tener acceso a la cola Amazon SQS. Para obtener más información, consulte [Requisitos](#sqs-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción de SQS en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/my_sqs_queue",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
El siguiente ejemplo de JSON define una acción de SQS con plantillas de sustitución en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/${topic()}",
"useBase64": true,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
## Véase también
+ [¿Qué es Amazon Simple Queue Service?](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/) en la *Guía para desarrolladores de Amazon Simple Queue Service*
# Step Functions
La acción Step Functions (`stepFunctions`) inicia una máquina de AWS Step Functions estados.
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar la `states:StartExecution` operación. Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir o crear un rol que permita AWS IoT realizar esta acción de regla.
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`stateMachineName`
El nombre de la máquina de estado de Step Functions a iniciar.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`executionNamePrefix`
(Opcional) El nombre dado a la ejecución de la máquina de estado consiste en este prefijo seguido de un UUID. Si no se facilita uno, Step Functions crea automáticamente un nombre exclusivo para cada ejecución de la máquina de estado.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleArn`
El ARN del rol que concede el AWS IoT permiso para iniciar la máquina de estados. Para obtener más información, consulte [Requisitos](#stepfunctions-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
## Ejemplos
El siguiente ejemplo de JSON define una acción de Step Functions en una AWS IoT regla.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myStateMachine",
"executionNamePrefix": "myExecution",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_step_functions"
}
}
]
}
}
```
## Véase también
+ [¿Qué es AWS Step Functions?](https://docs.aws.amazon.com/step-functions/latest/dg/) en la *Guía AWS Step Functions para desarrolladores*
# Timestream
La acción de regla Timestream escribe atributos (medidas) de un mensaje MQTT en una tabla de Amazon Timestream. Para obtener información completa sobre Amazon Timestream, consulte [¿Qué es Amazon Timestream?](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html)
**nota**
Amazon Timestream no está disponible en todos los s. Región de AWS Si Amazon Timestream no está disponible en su región, no aparecerá en la lista de acciones de reglas.
Los atributos que esta regla almacena en la base de datos de Timestream son los que resultan de la declaración de consulta de la regla. El valor de cada atributo del resultado de la declaración de consulta se analiza para deducir su tipo de datos (como en una acción [Dinamo DBv2](dynamodb-v2-rule-action.md)). El valor de cada atributo se escribe en su propio registro de la tabla Timestream. Para especificar o cambiar el tipo de datos de un atributo, utilice la función [`cast()`](iot-sql-functions.md#iot-sql-function-cast) en la sentencia de consulta. Para obtener más información acerca del contenido de cada registro de Timestream, consulte [Contenido de los registros de Timestream](#timestream-rule-action-data).
**nota**
Con SQL V2 (2016-03-23), los valores numéricos que son números enteros, como `10.0`, se convierten su representación Entera (`10`). Convertirlos explícitamente en un valor `Decimal`, por ejemplo utilizando la función [cast](iot-sql-functions.md#iot-sql-function-cast) (), no evita este comportamiento: el resultado sigue siendo un valor `Integer`. Esto puede provocar errores de discordancia de tipos que impidan que los datos se registren en la base de datos de Timestream. Para procesar los valores numéricos de números enteros como valores `Decimal`, utilice SQL V1 (2015-10-08) como instrucción de consulta de regla.
**nota**
El número máximo de valores que una acción de regla Timestream puede escribir en una tabla de Amazon Timestream es 100. Para obtener más información, consulte la [Referencia de Cuotas de Amazon Timestream](https://docs.aws.amazon.com//timestream/latest/developerguide/ts-limits.html#limits.default).
## Requisitos
Esta regla tiene los siguientes requisitos:
+ Una función de IAM que AWS IoT puede asumir para realizar las `timestream:DescribeEndpoints` operaciones y. `timestream:WriteRecords` Para obtener más información, consulte [Otorgar a una AWS IoT regla el acceso que requiere](iot-create-role.md).
En la AWS IoT consola, puede elegir, actualizar o crear un rol que permita AWS IoT realizar esta acción de regla.
+ Si utilizas un cliente AWS KMS para cifrar los datos en reposo en Timestream, el servicio debe tener permiso para utilizarlos AWS KMS key en nombre de la persona que llama. Para obtener más información, consulte [Cómo AWS](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html) utilizan los servicios KMS. AWS
## Parameters
Al crear una AWS IoT regla con esta acción, debe especificar la siguiente información:
`databaseName`
Nombre de una base de datos de Amazon Timestream que contiene la tabla para recibir los registros que crea esta acción. Véase también `tableName`.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`dimensions`
Atributos de metadatos de las series de tiempo que se escriben en cada registro de medida. Por ejemplo, el nombre y la zona de disponibilidad de una instancia EC2 o el nombre del fabricante de un aerogenerador son dimensiones.
`name`
El nombre de la dimensión de metadatos. Es el nombre de la columna en el registro de tabla de la base de datos.
Las dimensiones no se pueden denominar:`measure_name`, `measure_value` o `time`. Estos nombres están reservados. Los nombres de las dimensiones no pueden empezar por `ts_` o ni `measure_value` pueden contener el carácter de dos puntos (`:`).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`value`
El valor que se va a escribir en esta columna del registro de la base de datos.
Admite [plantillas de sustitución](iot-substitution-templates.md): Sí
`roleArn`
El nombre de recurso de Amazon (ARN) del rol que concede permiso a AWS IoT para escribir en la tabla de base de datos Timestream. Para obtener más información, consulte [Requisitos](#timestream-rule-action-requirements).
Admite [plantillas de sustitución](iot-substitution-templates.md): No
`tableName`
El nombre de la tabla de la base de datos en la que escribir los registros de la medida. Véase también `databaseName`.
Admite [plantillas de sustitución](iot-substitution-templates.md): API y AWS CLI únicamente
`timestamp`
El valor que se va a utilizar para la marca de tiempo de la entrada. Si está en blanco, se utiliza la hora en que se procesó la entrada.
`unit`
La precisión del valor de marca de tiempo que resulta de la expresión que se describe en `value`.
Valores válidos: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS` El valor predeterminado es `MILLISECONDS`.
`value`
Una expresión que devuelve un valor de tiempo de época larga.
Puede utilizar la función [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) para crear una marca de tiempo válida a partir de un valor de fecha u hora incluido en la carga útil del mensaje.
## Contenido de los registros de Timestream
Los datos que esta acción escribe en la tabla Amazon Timestream incluyen una marca de tiempo, los metadatos de la acción de la regla Timestream y el resultado de la declaración de consulta de la regla.
Para cada atributo (medida) del resultado de la declaración de consulta, esta acción de regla escribe un registro en la tabla Timestream especificada con estas columnas.
| Nombre de la columna | Tipo de atributo | Valor | Comentarios |
| --- | --- | --- | --- |
| *dimension-name* | DIMENSION | El valor especificado en la entrada de acción de la regla Timestream. | Cada **dimensión** especificada en la entrada de acción de la regla crea una columna en la base de datos de Timestream con el nombre de la dimensión. |
| measure\$1name | MEASURE\$1NAME | Nombre del atributo | El nombre del atributo en el resultado de la declaración de consulta cuyo valor se especifica en la columna `measure_value::data-type`. |
| valor\$1medida: *data-type* | MEASURE\$1VALUE | El valor del atributo en el resultado de la sentencia de consulta. El nombre del atributo está en la columna `measure_name`. | El valor se interpreta\$1 y se emite como la coincidencia más adecuada de: `bigint`, `boolean`, `double` o `varchar`. Amazon Timestream crea una columna independiente para cada tipo de datos. El valor del mensaje se puede convertir en otro tipo de datos mediante la función [`cast()`](iot-sql-functions.md#iot-sql-function-cast) de la declaración de consulta de la regla. |
| tiempo | TIMESTAMP | Congela la fecha y la hora de la base de datos. | Este valor lo asigna el motor de reglas o la propiedad `timestamp`, si está definido. |
\$1 El valor del atributo leído en la carga útil del mensaje se interpreta de la siguiente manera. Consulte la [Ejemplos](#timestream-rule-action-examples) para ver una ilustración de cada uno de estos casos.
+ Un valor sin comillas de `true` o `false` se interpreta como un tipo `boolean`.
+ Un número decimal se interpreta como un tipo `double`.
+ Un valor numérico sin punto decimal se interpreta como un tipo `bigint`.
+ Una cadena entre comillas se interpreta como un tipo `varchar`.
+ Los objetos y los valores de la matriz se convierten en cadenas JSON y se almacenan como un tipo `varchar`.
## Ejemplos
El siguiente ejemplo de JSON define una acción de regla Timestream con una plantilla de sustitución en una regla. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'iot/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"timestream": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_timestream",
"tableName": "devices_metrics",
"dimensions": [
{
"name": "device_id",
"value": "${clientId()}"
},
{
"name": "device_firmware_sku",
"value": "My Static Metadata"
}
],
"databaseName": "record_devices"
}
}
]
}
}
```
Si se utiliza la acción de regla del tema Timestream definida en el ejemplo anterior con la carga útil del mensaje siguiente, se obtienen los registros de Amazon Timestream escritos en la tabla siguiente.
```
{
"boolean_value": true,
"integer_value": 123456789012,
"double_value": 123.456789012,
"string_value": "String value",
"boolean_value_as_string": "true",
"integer_value_as_string": "123456789012",
"double_value_as_string": "123.456789012",
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"],
"complex_value": {
"simple_element": 42,
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"]
}
}
```
En la siguiente tabla se muestran las columnas y los registros de la base de datos que se crean al utilizar la acción de regla temática especificada para procesar la carga útil del mensaje anterior. Las columnas `device_firmware_sku` y `device_id` son las DIMENSIONES definidas en la acción de la regla temática. La acción de regla temática Timestream crea la columna `time` y las columnas `measure_name` y `measure_value::*`, que rellena con los valores del resultado de la declaración de consulta de la acción de regla temática.
| device\$1firmware\$1sku | device\$1id | measure\$1name | measure\$1value::bigint | measure\$1value::varchar | measure\$1value::double | measure\$1value::boolean | hora |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Mis metadatos estáticos | iotconsole-159 -0 EXAMPLE738 | complex\$1value | - | \$1"simple\$1element":42,"array\$1of\$1integers":[23,36,56,72],"array of strings":["red","green","blue"]\$1 | - | - | 2020-08-26 22:42:16.423000000 |
| Mis metadatos estáticos | consola iot-159 -0 EXAMPLE738 | integer\$1value\$1as\$1string | - | 123456789012 | - | - | 2020-08-26 22:42:16.423000000 |
| Mis metadatos estáticos | consola iot-159 -0 EXAMPLE738 | boolean\$1value | - | - | - | TRUE | 2020-08-26 22:42:16.423000000 |
| Mis metadatos estáticos | consola iot-159 -0 EXAMPLE738 | integer\$1value | 123456789012 | - | - | - | 2020-08-26 22:42:16.423000000 |
| Mis metadatos estáticos | consola iot-159 -0 EXAMPLE738 | string\$1value | - | Valor de cadena | - | - | 2020-08-26 22:42:16.423000000 |
| Mis metadatos estáticos | consola iot-159 -0 EXAMPLE738 | matriz\$1de\$1enteros | - | [23,36,56,72] | - | - | 2020-08-26 22:42:16.423000000 |
| Mis metadatos estáticos | consola iot-159 -0 EXAMPLE738 | matriz de cadenas | - | ["red","green","blue"] | - | - | 2020-08-26 22:42:16.423000000 |
| Mis metadatos estáticos | consola iot-159 -0 EXAMPLE738 | boolean\$1value\$1as\$1string | - | TRUE | - | - | 2020-08-26 22:42:16.423000000 |
| Mis metadatos estáticos | consola iot-159 -0 EXAMPLE738 | double\$1value | - | - | 123.456789012 | - | 2020-08-26 22:42:16.423000000 |
| Mis metadatos estáticos | consola IoT - 159 - 0 EXAMPLE738 | double\$1value\$1as\$1string | - | 123.45679 | - | - | 2020-08-26 22:42:16.423000000 |
## Solución de problemas de las reglas
Si tiene algún problema con sus reglas, le recomendamos que active CloudWatch los registros. Puede analizar sus registros para determinar si el problema es de autorización o si, por ejemplo, la condición de una cláusula WHERE no coincidía. Para obtener más información, consulta [Cómo configurar CloudWatch los registros](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html).
# Acceder a los recursos de varias cuentas mediante reglas AWS IoT
Puede configurar AWS IoT reglas para el acceso entre cuentas para que los datos ingeridos en los temas de MQTT de una cuenta puedan enrutarse a los AWS servicios, como Amazon SQS y Lambda, de otra cuenta. A continuación, se explica cómo configurar AWS IoT reglas para la ingesta de datos entre cuentas, desde un tema de MQTT de una cuenta hasta un destino de otra cuenta.
Las reglas multicuenta se pueden configurar mediante [permisos basados en recursos](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#TypesPermissions) en el recurso de destino. Por lo tanto, solo los destinos que admiten permisos basados en recursos pueden habilitarse para el acceso entre cuentas mediante reglas. AWS IoT Entre los destinos admitidos se incluyen Amazon SQS, Amazon S3 y AWS Lambda.
**nota**
Para los destinos admitidos, excepto Amazon SQS, debe definir la regla al Región de AWS igual que el recurso de otro servicio para que la acción de la regla pueda interactuar con ese recurso. Para obtener más información sobre las acciones de las AWS IoT reglas, consulte las acciones de [las AWS IoT reglas](iot-rule-actions.md). Para obtener más información sobre la acción de SQS de una regla, consulte [SQS](sqs-rule-action.md).
## Requisitos previos
+ Familiaridad con las [reglas AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)
+ Comprensión de los [usuarios](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html), [roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) y [permisos de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions.html#TypesPermissions) basados en recursos de IAM
+ Después de haber instalado [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
## Configuración de varias cuentas para Amazon SQS
Escenario: la cuenta A envía datos de un mensaje MQTT a la cola de Amazon SQS de la cuenta B.
| Cuenta de AWS | Cuenta denominada | Description (Descripción) |
| --- | --- | --- |
| 1111-1111-1111 | Cuenta A | Acción de la regla: sqs:SendMessage |
| 2222-2222-2222 | Cuenta B | Cola de Amazon SQS [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/accessing-cross-account-resources-using-rules.html) |
**nota**
[La cola de Amazon SQS de destino no tiene por qué coincidir con la Región de AWS regla.AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) Para obtener más información sobre la acción de SQS de una regla, consulte [SQS](sqs-rule-action.md).
**Realizar las tareas de la cuenta A**
**Nota**
Para ejecutar los siguientes comandos, el usuario de IAM debe tener permisos para `iot:CreateTopicRule` con el nombre de recurso de Amazon (ARN) de la regla como recurso y permisos para `iam:PassRole` con un recurso como ARN del rol.
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) con el usuario de IAM de la cuenta A.
1. Cree un rol de IAM que confíe en el motor de AWS IoT reglas y adjunte una política que permita el acceso a la cola Amazon SQS de la cuenta B. Consulte ejemplos de comandos y documentos de política en [Concesión AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html) del acceso requerido.
1. Para crear una regla adjunta a un tema, ejecute el [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html).
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
A continuación se muestra un archivo de carga útil de ejemplo con una regla que inserta todos los mensajes enviados al tema `iot/test` en la cola de Amazon SQS especificada. La sentencia SQL filtra los mensajes y el rol ARN concede los permisos AWS IoT para añadir el mensaje a la cola de Amazon SQS.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role",
"useBase64": false
}
}
]
}
```
Para obtener más información sobre cómo definir una acción de Amazon SQS en una AWS IoT regla, consulte AWS IoT Rule [actions: Amazon SQS.](https://docs.aws.amazon.com/iot/latest/developerguide/sqs-rule-action.html)
**Realizar las tareas de la cuenta B**
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) con el usuario de IAM de la cuenta B.
1. [Para conceder permisos para el recurso de cola de Amazon SQS a la cuenta A, ejecute el comando add-permission.](https://docs.aws.amazon.com/cli/latest/reference/sqs/add-permission.html)
```
aws sqs add-permission --queue-url https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue --label SendMessagesToMyQueue --aws-account-ids 1111-1111-1111 --actions SendMessage
```
## Configuración de varias cuentas para Amazon SNS
Escenario: La cuenta A envía datos de un mensaje MQTT a un tema de Amazon SNS de la cuenta B.
| Cuenta de AWS | Cuenta denominada | Description (Descripción) |
| --- | --- | --- |
| 1111-1111-1111 | Cuenta A | Acción de la regla: sns:Publish |
| 2222-2222-2222 | Cuenta B | ARN del tema de Amazon SNS: arn:aws:sns:region:2222-2222-2222:ExampleTopic |
**Realizar las tareas de la cuenta A**
**Notas**
Para ejecutar los siguientes comandos, su usuario de IAM debe tener permisos para `iot:CreateTopicRule` con la regla ARN como recurso y permisos para la acción `iam:PassRole` con un recurso como rol ARN.
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) con el usuario de IAM de la cuenta A.
1. Cree un rol de IAM que confíe en el motor de AWS IoT reglas y adjunte una política que permita el acceso al tema Amazon SNS de la cuenta B. Para ver ejemplos de comandos y documentos de políticas, consulte [Concesión AWS IoT del acceso requerido](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. Para crear una regla adjunta a un tema, ejecute el [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html).
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
A continuación se muestra un archivo de carga útil de ejemplo con una regla que inserta todos los mensajes enviados al tema `iot/test` en el tema de Amazon SNS especificado. La sentencia SQL filtra los mensajes y el rol ARN concede los permisos AWS IoT para enviar el mensaje al tema de Amazon SNS.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:region:2222-2222-2222:ExampleTopic",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
Para obtener más información sobre cómo definir una acción de Amazon SNS en una AWS IoT regla, consulte AWS IoT Rule [actions: Amazon SNS](https://docs.aws.amazon.com/iot/latest/developerguide/sns-rule-action.html).
**Realizar las tareas de la cuenta B**
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) con el usuario de IAM de la cuenta B.
1. Para dar permiso sobre el recurso de temas de Amazon SNS a la cuenta A, ejecute el [comando add-permission](https://docs.aws.amazon.com/cli/latest/reference/sns/add-permission.html).
```
aws sns add-permission --topic-arn arn:aws:sns:region:2222-2222-2222:ExampleTopic --label Publish-Permission --aws-account-id 1111-1111-1111 --action-name Publish
```
## Configuración de varias cuentas para Amazon S3
Escenario: La cuenta A envía datos de un mensaje MQTT a un bucket de Amazon S3 de la cuenta B.
| Cuenta de AWS | Cuenta denominada | Description (Descripción) |
| --- | --- | --- |
| 1111-1111-1111 | Cuenta A | Acción de la regla: s3:PutObject |
| 2222-2222-2222 | Cuenta B | ARN del bucket de Amazon S3: arn:aws:s3:::amzn-s3-demo-bucket |
**Realizar las tareas de la cuenta A**
**Nota**
Para ejecutar los siguientes comandos, su usuario de IAM debe tener permisos para `iot:CreateTopicRule` con la regla ARN como recurso y permisos para la acción `iam:PassRole` con un recurso como rol ARN.
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) con el usuario de IAM de la cuenta A.
1. Cree un rol de IAM que confíe en el motor de AWS IoT reglas y adjunte una política que permita el acceso al bucket de Amazon S3 de la cuenta B. Para ver ejemplos de comandos y documentos de políticas, consulte [Otorgar AWS IoT el acceso requerido.](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)
1. Para crear una regla que se adjunte al bucket S3 de destino, ejecuta el [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html).
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
A continuación, se muestra un ejemplo de archivo de carga con una regla que inserta todos los mensajes enviados al tema `iot/test` en el bucket de Amazon S3 especificado. La sentencia SQL filtra los mensajes y el rol ARN concede los permisos AWS IoT para añadir el mensaje al bucket de Amazon S3.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
Para obtener más información sobre cómo definir una acción de Amazon S3 en una AWS IoT regla, consulte [AWS IoT Rule actions: Amazon S3](https://docs.aws.amazon.com/iot/latest/developerguide/s3-rule-action.html).
**Realizar las tareas de la cuenta B**
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) con el usuario de IAM de la cuenta B.
1. Cree una política de bucket que confíe en la entidad principal de la cuenta A.
El siguiente es un ejemplo de archivo de carga útil que define una política de bucket que confía en la entidad principal de otra cuenta.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AddCannedAcl",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::123456789012:root"
]
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
Para obtener más información, consulte [Ejemplos de política de bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-use-case-1).
1. Para adjuntar la política de bucket al bucket especificado, ejecute el [put-bucket-policy comando](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-policy.html).
```
aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://./amzn-s3-demo-bucket-policy.json
```
1. Para que el acceso entre cuentas funcione, asegúrese de que tiene la configuración correcta de **Bloquear todo acceso público**. Para obtener más información, consulte [Prácticas recomendadas de seguridad para Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html).
## Configuración multicuenta para AWS Lambda
Escenario: la cuenta A invoca una AWS Lambda función de la cuenta B y envía un mensaje MQTT.
| Cuenta de AWS | Cuenta denominada | Description (Descripción) |
| --- | --- | --- |
| 1111-1111-1111 | Cuenta A | Acción de la regla: lambda:InvokeFunction |
| 2222-2222-2222 | Cuenta B | ARN de la función de Lambda: arn:aws:lambda:region:2222-2222-2222:function:example-function |
**Realizar las tareas de la cuenta A**
**Notas**
Para ejecutar los siguientes comandos, su usuario de IAM debe tener permisos para `iot:CreateTopicRule` con la regla ARN como recurso y permisos para la acción `iam:PassRole` con un recurso como rol ARN.
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) con el usuario de IAM de la cuenta A.
1. Ejecute el [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) para crear una regla que defina el acceso entre cuentas a la función Lambda de la cuenta B.
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
A continuación se muestra un archivo de carga útil de ejemplo con una regla que inserta todos los mensajes enviados al tema `iot/test` en la función de Lambda especificada. La sentencia SQL filtra los mensajes y el ARN de rol concede permiso AWS IoT para pasar los datos a la función de Lambda.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:region:2222-2222-2222:function:example-function"
}
}
]
}
```
Para obtener más información sobre cómo definir una AWS Lambda acción en una AWS IoT regla, lee [Acciones de la AWS IoT regla: Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/lambda-rule-action.html).
**Realizar las tareas de la cuenta B**
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) con el usuario de IAM de la cuenta B.
1. Ejecute el [comando add-permission de Lambda para dar permiso](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) a AWS IoT las reglas para activar la función Lambda. Para ejecutar el siguiente comando, su usuario de IAM debe tener permiso para una acción `lambda:AddPermission`.
```
aws lambda add-permission --function-name example-function --region us-east-1 --principal iot.amazonaws.com --source-arn arn:aws:iot:region:1111-1111-1111:rule/example-rule --source-account 1111-1111-1111 --statement-id "unique_id" --action "lambda:InvokeFunction"
```
**Opciones:**
**--entidad principal**
Este campo da permiso a AWS IoT (representado por`iot.amazonaws.com`) para llamar a la función Lambda.
**--source-arn**
Este campo confirma que solo `arn:aws:iot:region:1111-1111-1111:rule/example-rule` en AWS IoT activa esta función de Lambda y que ninguna otra regla de la misma cuenta o de otra diferente puede activar esta función de Lambda.
**--source-account**
Este campo confirma que AWS IoT activa esta función Lambda solo en nombre de la `1111-1111-1111` cuenta.
**Notas**
Si aparece el mensaje de error “No se ha encontrado la regla” en la consola de la función AWS Lambda , en la sección **Configuración**, ignore el mensaje de error y proceda a probar la conexión.
# Control de errores (acción de error)
Cuando AWS IoT recibe un mensaje de un dispositivo, el motor de reglas comprueba si el mensaje coincide con una regla. Si es así, se evalúa la sentencia de consulta de la regla y se activan las acciones de la regla, pasando el resultado de la sentencia de consulta.
Si se produce un problema al activar una acción, el motor de reglas activa una acción de error, si se ha especificado una para la regla. Esto podría ocurrir cuando:
+ Una regla no dispone de permiso para acceder al bucket de Amazon S3.
+ Un error de usuario provoca que se supere el rendimiento aprovisionado de DynamoDB.
**nota**
El tratamiento de errores que se trata en este tema se refiere a las [acciones de las reglas](iot-rule-actions.md). Para depurar problemas de SQL, incluidas las funciones externas, puede configurar el AWS IoT registro. Para obtener más información, consulte [Configure el AWS IoT registro](configure-logging.md).
## Formato de mensaje de acción de error
Se genera un único mensaje por regla y mensaje. Por ejemplo, si se produce un error en dos acciones de regla en la misma regla, la acción de error recibe un mensaje con los dos errores.
El mensaje de acción de error se parece al siguiente ejemplo.
```
{
"ruleName": "TestAction",
"topic": "testme/action",
"cloudwatchTraceId": "7e146a2c-95b5-6caf-98b9-50e3969734c7",
"clientId": "iotconsole-1511213971966-0",
"base64OriginalPayload": "ewogICJtZXNzYWdlIjogIkhlbGxvIHZyb20gQVdTIElvVCBjb25zb2xlIgp9",
"failures": [
{
"failedAction": "S3Action",
"failedResource": "us-east-1-s3-verify-user",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist (Service: Amazon S3; Status Code: 404; Error Code: NoSuchBucket; Request ID: 9DF5416B9B47B9AF; S3 Extended Request ID: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y=). Message arrived on: error/action, Action: s3, Bucket: us-east-1-s3-verify-user, Key: \"aaa\". Value of x-amz-id-2: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y="
}
]
}
```
ruleName
El nombre de la regla que activó la acción de error.
tema
El tema en el que se recibió el mensaje original.
cloudwatchTraceId
Inicia sesión con una identidad única que hace referencia al error. CloudWatch
clientId
El ID de cliente del publicador de mensajes.
base64 OriginalPayload
La carga del mensaje original codificada en Base64.
failures
failedAction
El nombre de la acción que no se pudo completar (por ejemplo "S3Action").
failedResource
El nombre del recurso (por ejemplo el nombre de un bucket de S3).
errorMessage
La descripción y explicación del error.
## Ejemplo de acción de error
A continuación se muestra un ejemplo de una regla con una acción de error añadida. La siguiente regla tiene una acción que escribe datos de mensajes en una tabla de y una acción de error que escribe datos en un bucket de Amazon S3:
```
{
"sql" : "SELECT * FROM ..."
"actions" : [{
"dynamoDB" : {
"table" : "PoorlyConfiguredTable",
"hashKeyField" : "AConstantString",
"hashKeyValue" : "AHashKey"}}
],
"errorAction" : {
"s3" : {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName" : "message-processing-errors",
"key" : "${replace(topic(), '/', '-') + '-' + timestamp() + '-' + newuuid()}"
}
}
}
```
Puede utilizar cualquier [función](iot-sql-functions.md) o [plantilla de sustitución](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) en la sentencia SQL de una acción de error, incluidas las funciones externas: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret), y [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64). Si una acción de error requiere llamar a una función externa, la invocación de la acción de error puede generar una factura adicional por la función externa.
Para obtener más información sobre las reglas y cómo especificar una acción de error, consulte [Creación de una AWS IoT regla](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html).
Para obtener más información sobre el uso CloudWatch para supervisar el éxito o el fracaso de las reglas, consulte[AWS IoT métricas y dimensiones](metrics_dimensions.md).
# Reducción de los costes de mensajería con Basic Ingest
Basic Ingest le permite enviar de forma segura datos de los dispositivos a los Servicios de AWS compatibles con [AWS IoT acciones de reglas](iot-rule-actions.md) sin incurrir en [costes de mensajería](https://aws.amazon.com/iot-core/pricing/). Basic Ingest optimiza el flujo de datos eliminando el agente de mensajes de publicación/suscripción de la ruta de adquisición.
Basic Ingest puede enviar mensajes desde sus dispositivos o aplicaciones. Los mensajes tienen nombres de temas que comienzan por `$aws/rules/rule_name` en sus tres primeros niveles, y donde `rule_name` es el nombre de la regla de AWS IoT que quiere invocar.
Puede utilizar una regla existente con Basic Ingest agregando el prefijo de Basic Ingest (`$aws/rules/rule_name`) al tema del mensaje que utilizaría para invocar la regla. Por ejemplo, si tiene una regla llamada `BuildingManager` que se invoca mediante mensajes con temas como `Buildings/Building5/Floor2/Room201/Lights` (`"sql": "SELECT * FROM 'Buildings/#'"`), podrá invocar la misma regla con Basic Ingest enviando un mensaje con el tema `$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`.
**nota**
Sus dispositivos y sus reglas no pueden suscribirse a temas reservados para Basic Ingest. Por ejemplo, las métricas `num-messages-received` de la métrica AWS IoT Device Defender no se emiten porque no admite la suscripción a temas. Para obtener más información, consulte [Temas reservados](reserved-topics.md).
Si necesita un agente de publicación/suscripción para distribuir mensajes a varios suscriptores (por ejemplo para entregar mensajes a otros dispositivos y al motor de reglas), debe seguir utilizando el agente de mensajes de AWS IoT para gestionar la distribución de los mensajes. No obstante, debe publicar sus mensajes en temas que no sean temas de Basic Ingest.
## Uso de Basic Ingest
Antes de usar Basic Ingest, compruebe que su dispositivo o aplicación utilice una [política](iot-policies.md) que tenga permisos de publicación en `$aws/rules/*`. También puede especificar permisos para reglas individuales que incluyan `$aws/rules/rule_name/*` en la política. De lo contrario, los dispositivos y las aplicaciones podrán seguir utilizando las conexiones existentes con AWS IoT Core.
Cuando el mensaje llega al motor de reglas, no existe diferencia alguna en la implementación o en la gestión de los errores entre reglas invocadas desde Basic Ingest y las invocadas a través suscripciones al agente de mensajes.
Puede crear reglas para usarlas con Basic Ingest. Tenga en cuenta lo siguiente:
+ El prefijo inicial de un tema de Basic Ingest (`$aws/rules/rule_name`) no está disponible a la función [topic(Decimal)](iot-sql-functions.md#iot-function-topic).
+ Si define una regla que se invoca solo con Basic Ingest, la cláusula `FROM` es opcional en el campo `sql` de la definición `rule`. Seguirá siendo necesaria si la regla también se invoca a través de otros mensajes que deben enviarse por medio del agente de mensajes (por ejemplo, porque esos otros mensajes deban distribuirse a varios suscriptores). Para obtener más información, consulte [AWS IoT Referencia SQL](iot-sql-reference.md).
+ Los primeros tres niveles del tema de Basic Ingest (`$aws/rules/rule_name`) no se cuentan en cuanto al límite de longitud de 8 segmentos o en cuanto al límite de caracteres total de 256 de un tema. De lo contrario, se aplican las mismas restricciones que se documentan en la sección sobre [límites de AWS IoT](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#limits_iot).
+ Si se recibe un mensaje con un tema de Basic Ingest que especifica una regla no activa o una regla que no existe, se crea un registro del error en un registro de Amazon CloudWatch que le ayudará con la tarea de depuración. Para obtener más información, consulte [Entradas del registro del motor de reglas](cwl-format.md#rule-engine-logs). Se muestra una métrica `RuleNotFound`, en la cual podrá crear alarmas. Para obtener más información, consulte Métricas de la regla en [Métricas de reglas](metrics_dimensions.md#rulemetrics).
+ Seguirá pudiendo publicar con QoS 1 en temas de Basic Ingest. Recibirá PUBACK después de que el mensaje se entregue correctamente al motor de reglas. Recibir PUBACK no significa que las acciones asociadas a la regla se hayan realizado correctamente. Puede configurar una acción de error para gestionar los errores durante el proceso de ejecución. Para obtener más información, consulte [Control de errores (acción de error)](rule-error-handling.md).
# AWS IoT Referencia SQL
En AWS IoT, las reglas se definen mediante una sintaxis similar a la de SQL. Las instrucciones de SQL se componen de tres tipos de cláusulas:
**SET**
(Opcional) Define las variables que se pueden reutilizar en las sentencias SQL y las plantillas de sustitución. Asigne valores a las variables mediante expresiones. Haga referencia a estas variables en las cláusulas SELECT y WHERE y en las plantillas de sustitución de acciones.
La cláusula SET admite[Tipos de datos](iot-sql-data-types.md), [Operadores](iot-sql-operators.md)[Funciones](iot-sql-functions.md),[Literales](iot-sql-literals.md),[Instrucciones case](iot-sql-case.md),[Extensiones JSON](iot-sql-json.md), [Variables](iot-sql-set.md#iot-sql-set-usage) y[Consultas de objetos anidados](iot-sql-nested-queries.md).
**SELECT**
(Obligatorio) Extrae información de la carga de un mensaje de entrada y realiza transformaciones en la información. Los mensajes que se van a utilizar se identifican mediante el [filtro de tema](topics.md#topicfilters) especificado en la cláusula FROM.
La cláusula SELECT admite [Tipos de datos](iot-sql-data-types.md) [Operadores](iot-sql-operators.md)[Funciones](iot-sql-functions.md),[Literales](iot-sql-literals.md),[Instrucciones case](iot-sql-case.md),[Extensiones JSON](iot-sql-json.md), [Plantillas de sustitución](iot-substitution-templates.md)[Consultas de objetos anidados](iot-sql-nested-queries.md), [Variables](iot-sql-set.md#iot-sql-set-usage) y[Cargas binarias](binary-payloads.md).
**FROM**
El [filtro de tema](topics.md#topicfilters) de mensajes MQTT que identifica los mensajes de los que se van a extraer datos. La regla se activa para cada mensaje enviado a un tema de MQTT que coincide con el filtro de temas especificado aquí. Obligatorio para reglas que se activan mediante mensajes que pasan por el agente de mensajes. Opcional para reglas que solo se activan mediante la característica [Basic Ingest](iot-basic-ingest.md).
**WHERE**
(Opcional) Agrega lógica condicional que determina si se llevan a cabo las acciones especificadas por una regla.
La cláusula WHERE admite [Tipos de datos](iot-sql-data-types.md) [Operadores](iot-sql-operators.md)[Funciones](iot-sql-functions.md),,[Literales](iot-sql-literals.md),[Instrucciones case](iot-sql-case.md),[Extensiones JSON](iot-sql-json.md), [Variables](iot-sql-set.md#iot-sql-set-usage) y[Consultas de objetos anidados](iot-sql-nested-queries.md).
Un ejemplo de instrucción SQL tiene este aspecto:
```
SELECT color AS rgb FROM 'topic/subtopic' WHERE temperature > 50
```
Un mensaje MQTT de ejemplo (también denominado carga de entrada) tiene este aspecto:
```
{
"color":"red",
"temperature":100
}
```
Si este mensaje se publica en el tema `'topic/subtopic'`, la regla se activa y se evalúa la instrucción SQL. La instrucción SQL extrae el valor de la propiedad `color` si la propiedad `"temperature"` es superior a 50. La cláusula WHERE especifica la condición `temperature > 50`. La palabra clave `AS` cambia el nombre de la propiedad `"color"` a `"rgb"`. El resultado (también denominado *carga de salida*) tiene este aspecto:
```
{
"rgb":"red"
}
```
Estos datos se reenvían después a la acción de la regla, que envía los datos para seguirlos procesando. Para obtener más información sobre las acciones de las reglas, consulte [AWS IoT acciones de reglas](iot-rule-actions.md).
**nota**
Los comentarios no se admiten actualmente en la sintaxis de AWS IoT SQL.
Los nombres de atributos con espacios no se pueden usar como nombres de campo en la instrucción SQL. Si bien la carga entrante puede tener nombres de atributos con espacios, dichos nombres no se pueden usar en la instrucción SQL. Sin embargo, se transferirán a la carga saliente si utiliza una especificación de nombre de campo comodín (\$1).
# Cláusula SELECT
La cláusula AWS IoT SELECT es básicamente la misma que la cláusula SELECT de ANSI SQL, con algunas pequeñas diferencias.
La cláusula SELECT admite [Tipos de datos](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funciones](iot-sql-functions.md),[Literales](iot-sql-literals.md),[Instrucciones case](iot-sql-case.md), [Extensiones JSON](iot-sql-json.md)[Consultas de objetos anidados](iot-sql-nested-queries.md), [Variables](iot-sql-set.md#iot-sql-set-usage) y[Cargas binarias](binary-payloads.md).
Puede utilizar la cláusula SELECT para extraer información de los mensajes MQTT de entrada. También puede utilizar `SELECT *` para recuperar toda la carga del mensaje de entrada. Por ejemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT * FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50}
```
Si la carga es un objeto JSON, puede hacer referencia a claves en el objeto. La carga de salida contiene el par clave-valor. Por ejemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT color FROM 'topic/subtopic'
Outgoing payload: {"color":"red"}
```
Puede utilizar la palabra clave AS para cambiar el nombre de las claves. Por ejemplo:
```
Incoming payload published on topic 'topic/subtopic':{"color":"red", "temperature":50}
SQL:SELECT color AS my_color FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red"}
```
Puede seleccionar varios elementos separándolos con una coma. Por ejemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT color as my_color, temperature as fahrenheit FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red","fahrenheit":50}
```
Puede seleccionar varios elementos incluido '\$1' para agregar elementos a la carga de entrada. Por ejemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT *, 15 as speed FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50, "speed":15}
```
Puede utilizar la palabra clave `"VALUE"` para generar cargas de salida que no sean objetos JSON. Con la versión `2015-10-08` de SQL, solo se puede seleccionar un elemento. Con la versión SQL `2016-03-23` o posterior, también puede seleccionar una matriz para generar como objeto de nivel superior.
**Example**
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT VALUE color FROM 'topic/subtopic'
Outgoing payload: "red"
```
Puede utilizar la sintaxis `'.'` para explorar objetos JSON anidados en la carga de entrada. Por ejemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":{"red":255,"green":0,"blue":0}, "temperature":50}
SQL: SELECT color.red as red_value FROM 'topic/subtopic'
Outgoing payload: {"red_value":255}
```
Para obtener información sobre cómo utilizar nombres de objetos y propiedades JSON que incluyen caracteres reservados, como números o el carácter de guion (signo negativo), consulte [Extensiones JSON](iot-sql-json.md)
Puede utilizar funciones (consulte [Funciones](iot-sql-functions.md)) para transformar la carga de entrada. Puede utilizar paréntesis para realizar agrupaciones. Por ejemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT (temperature - 32) * 5 / 9 AS celsius, upper(color) as my_color FROM 'topic/subtopic'
Outgoing payload: {"celsius":10,"my_color":"RED"}
```
# Cláusula FROM
La cláusula FROM suscribe a su regla a un [tema](topics.md#topicnames) o un [filtro de temas](topics.md#topicfilters). Incluya el tema o el filtro de temas entre comillas simples ('). La regla se activa para cada mensaje enviado a un tema de MQTT que coincide con el filtro de temas especificado aquí. Mediante un filtro de temas, puede suscribirse a un grupo de temas similares.
**Ejemplo:**
Carga de entrada publicada en el tema `'topic/subtopic'`: `{temperature: 50}`
Carga de entrada publicada en el tema `'topic/subtopic-2'`: `{temperature: 50}`
SQL: `"SELECT temperature AS t FROM 'topic/subtopic'"`.
La regla se suscribe a `'topic/subtopic'`, por lo que la carga de entrada se pasa a la regla. La carga de salida, que se pasa a las acciones de regla, es: `{t: 50}`. La regla no está suscrita a `'topic/subtopic-2'`, por lo que la regla no se activa para el mensaje publicado en `'topic/subtopic-2'`.
**Ejemplo de comodín \$1:**
Puede utilizar el carácter comodín '\$1' (multinivel) para buscar coincidencias con uno o varios elementos de ruta en particular:
Carga de entrada publicada en el tema `'topic/subtopic'`: `{temperature: 50}`.
Carga de entrada publicada en el tema `'topic/subtopic-2'`: `{temperature: 60}`.
Carga de entrada publicada en el tema `'topic/subtopic-3/details'`: `{temperature: 70}`.
Carga de entrada publicada en el tema `'topic-2/subtopic-x'`: `{temperature: 80}`.
SQL: `"SELECT temperature AS t FROM 'topic/#'"`.
La regla se suscribe a cualquier tema que comience por`'topic'`, por lo que se ejecuta tres veces y envía cargas útiles salientes de `{t: 50}` (para el tema/subtema), (para el tema/subtema 2) y `{t: 60}` (para) a sus acciones. `{t: 70}` topic/subtopic-3/details No está suscrita a `'topic-2/subtopic-x'`, por lo que la regla no se activa para el mensaje `{temperature: 80}`.
**Ejemplo de comodín \$1:**
Puede utilizar el carácter comodín '\$1' (nivel único) para buscar coincidencias con cualquier elemento de ruta en particular:
Carga de entrada publicada en el tema `'topic/subtopic'`: `{temperature: 50}`.
Carga de entrada publicada en el tema `'topic/subtopic-2'`: `{temperature: 60}`.
Carga de entrada publicada en el tema `'topic/subtopic-3/details'`: `{temperature: 70}`.
Carga de entrada publicada en el tema `'topic-2/subtopic-x'`: `{temperature: 80}`.
SQL: `"SELECT temperature AS t FROM 'topic/+'"`.
La regla está suscrita a todos los temas que tengan dos elementos de ruta donde el primer elemento sea `'topic'`. La regla se ejecuta para los mensajes enviados a `'topic/subtopic'` y `'topic/subtopic-2'`, pero no `'topic/subtopic-3/details'` (tiene más niveles que el filtro de tema) o `'topic-2/subtopic-x'` (no empieza por `topic`).
# Cláusula SET
Utilice la cláusula SET para definir las variables que almacenan los resultados de las expresiones. Puede reutilizar estas variables en las cláusulas SELECT y WHERE y en las plantillas de sustitución. Esto le ayuda a evitar la duplicación de expresiones complejas y a reducir el número de llamadas a funciones en su sentencia SQL.
La cláusula SET admite[Tipos de datos](iot-sql-data-types.md),[Operadores](iot-sql-operators.md),[Funciones](iot-sql-functions.md),[Literales](iot-sql-literals.md), [Instrucciones case](iot-sql-case.md)[Extensiones JSON](iot-sql-json.md), [Variables](#iot-sql-set-usage) y[Consultas de objetos anidados](iot-sql-nested-queries.md).
## Sintaxis de la cláusula SET
La cláusula SET debe aparecer antes que la cláusula SELECT en la sentencia SQL. Utilice la siguiente sintaxis:
```
SET @variable_name = expression [, @variable_name2 = expression2]
```
Reglas de sintaxis:
+ Comience los nombres de las variables con `@`
+ Los nombres de las variables pueden contener letras, números y guiones bajos
+ Los nombres de las variables pueden tener hasta 64 caracteres
+ Se pueden establecer varias variables en una sola cláusula SET, separadas por comas
+ Cada variable solo se puede asignar una vez (las variables son inmutables)
+ La palabra clave SET solo se puede usar una vez por sentencia SQL
## Uso de variables
Después de definir las variables, puede usarlas en:
+ cláusulas SELECT
+ cláusulas WHERE
+ Otras asignaciones de variables SET
+ Plantillas de sustitución de acciones
+ Plantillas de sustitución de acciones de error
+ Consultas SELECT anidadas
+ Parámetros de función (algunos parámetros, como los parámetros de RoLearn y los parámetros que cambian el modo de una función de forma similar, `transform("enrichArray", attributes, values)` no admiten variables)
Se hace referencia a las variables con la misma `@variable_name` sintaxis utilizada en la cláusula SET. También puede usar la sintaxis de la extensión JSON para acceder a las propiedades de las variables que contienen objetos, como`@variable_name.property`.
## Ejemplos de cláusulas SET
**Uso básico de variables**
El siguiente ejemplo muestra una carga útil publicada sobre el tema: `device/data` `{"temp_fahrenheit": 75, "humidity": 60}`
Instrucción SQL:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Carga útil saliente: `{"celsius": 23.89, "humidity": 60}`
**Accede a los miembros en objetos JSON incrustados**
En el siguiente ejemplo, se muestra una carga útil publicada sobre un tema: `device/data` `{"device1": {"deviceId":"weather_sensor", "deviceData": {"sensors": {"temp_fahrenheit": 75, "humidity": 60}, "location": [47.606,-122.332]}}}`
Instrucción SQL:
```
SET @device_sensor_data = device1.deviceData.sensors
SELECT @device_sensor_data.temp_fahrenheit AS temp_fahrenheit, @device_sensor_data.humidity as humidity, device1.deviceId as deviceId FROM 'device/data'
```
Carga útil saliente: `{"temp_fahrenheit":75,"humidity":60,"deviceId":"weather_sensor"}`
para obtener más información sobre cómo trabajar con extensiones JSON, consulte [Extensiones JSON](iot-sql-json.md)
**Evitar la duplicación de llamadas a funciones**
Las variables SET ayudan a evitar la duplicación de operaciones de decodificación complejas:
```
SET @decoded_data = decode(encode(*, 'base64'), 'proto', 'schema', 'schema.desc', 'message.proto', 'Message')
SELECT @decoded_data.sensor_id, @decoded_data.reading FROM 'device/protobuf'
WHERE @decoded_data.reading > 100
```
Sin las variables SET, tendría que repetir la función de decodificación tres veces, lo que supera los límites de llamadas a la función.
**Variables múltiples**
Puede definir varias variables en una sola cláusula SET separándolas con comas:
```
SET @user_data = get_user_properties(device_id), @threshold = 50
SELECT @user_data.name, temp_fahrenheit FROM 'sensors/+'
WHERE temp_fahrenheit > @threshold AND @user_data.active = true
```
**Uso de variables en plantillas de sustitución**
Las variables también se pueden utilizar en las plantillas de sustitución de acciones, lo que permite reutilizar los valores calculados tanto en las acciones de la sentencia SQL como en las de las reglas.
Instrucción SQL:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Configuración de acciones:
```
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/testRuleRole",
"bucketName": "bucket",
"key": "temperature-data/${device_id}/temp-${@temp_celsius}C.json"
}
}
```
En este ejemplo, la variable SET `@temp_celsius` se utiliza en una plantilla de sustitución para construir el campo clave de la acción de S3.
**Uso de cargas que no son de JSON**
Las variables SET no admiten directamente cargas útiles que no sean de JSON, por lo que la carga útil debe codificarse o decodificarse primero:
```
SET @encoded_payload = encode(*, 'base64')
SELECT @encoded_payload AS raw_data FROM 'device/binary'
```
para obtener más información sobre cómo trabajar con cargas útiles que no son de JSON, consulte [Uso de las cargas binarias](binary-payloads.md)
## LÍMITES DE CLÁUSULAS SET
Los siguientes límites se aplican a las variables SET:
+ Máximo de 10 variables únicas por sentencia SQL
+ Tamaño máximo de valor variable de 128 KiB (cadena JSON UTF-8 minificada)
+ Tamaño máximo del valor total de 128 KiB para todas las variables
+ Los nombres de las variables están limitados a 64 caracteres
+ Las variables pueden aceptar cargas útiles de JSON directamente tal cual (las cargas que no son de JSON deben codificarse o decodificarse primero)
# Cláusula WHERE
La cláusula WHERE determina si se llevan a cabo las acciones especificadas por una regla. Si la cláusula WHERE se evalúa en true, se llevan a cabo las acciones de la regla. De lo contrario, las acciones de la regla no se llevan a cabo.
La cláusula WHERE admite [Tipos de datos](iot-sql-data-types.md) [Operadores](iot-sql-operators.md)[Funciones](iot-sql-functions.md),,[Literales](iot-sql-literals.md),[Instrucciones case](iot-sql-case.md),[Extensiones JSON](iot-sql-json.md), [Variables](iot-sql-set.md#iot-sql-set-usage) y[Consultas de objetos anidados](iot-sql-nested-queries.md).
**Ejemplo:**
Carga de entrada publicada en `topic/subtopic`: `{"color":"red", "temperature":40}`.
SQL: `SELECT color AS my_color FROM 'topic/subtopic' WHERE temperature > 50 AND color <> 'red'`.
En este caso, la regla se activará, pero las acciones especificadas por la regla no se llevarán a cabo. No habrá carga de salida.
Puede utilizar funciones y operadores en la cláusula WHERE. Sin embargo, no puede hacer referencia a ningún alias creado con la palabra clave AS en la cláusula SELECT. La cláusula WHERE se evalúa en primer lugar para determinar si SELECT debe evaluarse.
**Ejemplo con una carga que no es JSON:**
Carga entrante no JSON publicada en el `tema/subtema`: `80`
SQL: ``SELECT decode(encode(*, 'base64'), 'base64') AS value FROM 'topic/subtopic' WHERE decode(encode(*, 'base64'), 'base64') > 50`
En este caso, la regla se activará y las acciones especificadas por la regla se llevarán a cabo. La cláusula SELECT transformará la carga saliente en una carga `{"value":80}` JSON.
# Tipos de datos
El motor de AWS IoT reglas admite todos los tipos de datos JSON.
**Tipos de datos compatibles**
| Tipo | Significado |
| --- | --- |
| Int | Un discreto Int. 34 dígitos como máximo. |
| Decimal | Un valor `Decimal` con una precisión de 34 dígitos, con una magnitud no nula mínima de 1E-999 y una magnitud máxima de 9.999... E999. Algunas funciones devuelven valores `Decimal` con doble precisión (en lugar de una precisión de 34 dígitos). Con SQL V2 (2016-03-23), los valores numéricos que son números enteros, como `10.0`, se procesan como un valor `Int` (`10`) en lugar del valor `Decimal` esperado (`10.0`). Para procesar de forma fiable los valores numéricos de números enteros como valores `Decimal`, utilice SQL V1 (2015-10-08) como instrucción de consulta de regla. |
| Boolean | True o bien False. |
| String | Una cadena UTF-8. |
| Array | Una serie de valores que no han de tener obligatoriamente el mismo tipo. |
| Object | Un valor JSON compuesto de una clave y un valor. Las claves deben ser cadenas. Los valores pueden ser de cualquier tipo. |
| Null | Valor Null, tal como lo define JSON. Es un valor real que representa la ausencia de valor. El usuario puede crear explícitamente un valor Null especificando la palabra clave Null en la instrucción SQL. Por ejemplo: "SELECT NULL AS n FROM 'topic/subtopic'" |
| Undefined | No es un valor. No se representa explícitamente en JSON, salvo que se omita el valor. Por ejemplo, en el objeto `{"foo": null}`, la clave "foo" devuelve NULL, pero la clave "bar" devuelve `Undefined`. Internamente, el lenguaje SQL trata a `Undefined` como un valor, pero este no se puede representar en JSON, por lo que cuando se serializa en JSON, los resultados son `Undefined`. {"foo":null, "bar":undefined} se serializa en JSON como: {"foo":null} Del mismo modo, `Undefined` se convierte en una cadena vacía cuando se serializa por sí mismo. Las funciones a las que se llama con argumentos no válidos (por ejemplo, tipos erróneos, número de argumentos erróneo, etc.) devuelven `Undefined`. |
## Conversiones
En la tabla siguiente se muestra una lista de los resultados que se producen cuando un valor de un tipo se convierte en otro tipo (cuando se da un valor de tipo incorrecto a una función). Por ejemplo, si a la función de valor absoluto "abs" (que espera un valor `Int` o `Decimal`) se le da un valor `String`, esta función intentará convertir el valor `String` en un valor `Decimal`, de acuerdo con estas reglas. En este caso, 'abs ("-5.123")' se trata como 'abs(-5.123)'.
**nota**
No hay ningún intento de conversión en `Array`, `Object`, `Null` o `Undefined`.
**En valor decimal**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Valor Decimal sin separador decimal. |
| Decimal | El valor de origen. |
| Boolean | Undefined. (Puede utilizar de forma explícita la función cast para transformar true = 1.0, false = 0.0.) |
| String | El motor SQL intenta analizar la cadena como unDecimal. AWS IoT intenta analizar las cadenas que coinciden con la expresión regular:^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1.2", "5E-12" son ejemplos de cadenas que se convierten automáticamente en valores de tipo Decimal. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Null. |
| Sin definir | Undefined. |
**En valor entero**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | El valor de origen. |
| Decimal | El valor de origen redondeado al valor Int más cercano. |
| Boolean | Undefined. (Puede utilizar de forma explícita la función cast para transformar true = 1.0, false = 0.0.) |
| String | El motor SQL intenta analizar la cadena como unDecimal. AWS IoT intenta analizar las cadenas que coinciden con la expresión regular:^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. «0", «-1.2", «5E-12" son ejemplos de cadenas que se convierten automáticamente en Decimal s. AWS IoT Intenta convertir el en a yDecimal, String a continuación, trunca sus decimales para formar un. Decimal Int |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Null. |
| Sin definir | Undefined. |
**En valor booleano**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Undefined. (Puede utilizar de forma explícita la función cast para transformar 0 = False, any\$1nonzero\$1value = True.) |
| Decimal | Undefined. (Puede utilizar de forma explícita la función cast para transformar 0 = False, any\$1nonzero\$1value = True.) |
| Boolean | El valor original. |
| String | "true"= True y "false" = False (no distingue entre mayúsculas y minúsculas). Otros valores de string son Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
**En cadena**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Una representación de cadena del valor Int en notación estándar. |
| Decimal | Una cadena que representa el valor Decimal, posiblemente en notación científica. |
| Boolean | "true" o "false". Todos en minúscula. |
| String | El valor original. |
| Matriz | El valor Array serializado en formato JSON. La cadena obtenida es una lista separada por comas, entre corchetes. Los valores de tipo String se indican entre comillas. No así los valores de tipo Decimal, Int, Boolean y Null. |
| Objeto | El objeto serializado al formato JSON. La cadena obtenida es una lista separada por comas de pares clave-valor que comienza y termina con llaves. Los valores de tipo String se indican entre comillas. No así los valores de tipo Decimal, Int, Boolean y Null. |
| Nulo | Undefined. |
| Sin definir | Sin definir. |
# Operadores
Los operadores siguientes se pueden utilizar en las cláusulas SELECT y WHERE.
## Operador AND
Devuelve un resultado `Boolean`. Realiza una operación AND lógica. Devuelve el valor true si los operandos izquierdo y derecho son true. De lo contrario, devuelve el valor false. Se necesitan operandos de tipo `Boolean` u operandos de cadena "true" o "false" que no distingan entre mayúsculas y minúsculas.
*Sintaxis:* ` expression AND expression`.
**Operador AND**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. True si ambos operandos son true. De lo contrario, devuelve false. |
| String/Boolean | String/Boolean | Si todas las cadenas son "true" o "false" (no se distingue entre mayúsculas y minúsculas), se convierten en valores de tipo Boolean y se procesan normalmente como boolean AND boolean. |
| Otro valor | Otro valor | Undefined. |
## Operador OR
Devuelve un resultado `Boolean`. Realiza una operación OR lógica. Devuelve el valor true si el operando izquierdo o el operando derecho es true. De lo contrario, devuelve el valor false. Se necesitan operandos de tipo `Boolean` u operandos de cadena "true" o "false" que no distingan entre mayúsculas y minúsculas.
*Sintaxis:* ` expression OR expression`.
**Operador OR**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. True si uno de los operandos es true. De lo contrario, devuelve false. |
| String/Boolean | String/Boolean | Si todas las cadenas son "true" o "false" (no se distingue entre mayúsculas y minúsculas), se convierten en valores booleanos y se procesan normalmente como boolean OR boolean. |
| Otro valor | Otro valor | Undefined. |
## Operador NOT
Devuelve un resultado `Boolean`. Realiza una operación NOT lógica. Devuelve true si el operado es false. De lo contrario, devuelve true. Se necesita un operando `Boolean` o un operando de cadena "true" o "false" que no distinga entre mayúsculas y minúsculas.
*Sintaxis:* `NOT expression`.
**Operador NOT**
| Operando | Output |
| --- | --- |
| Boolean | Boolean. True si el operando es false. De lo contrario, devuelve true. |
| String | Si la cadena es “true” o “false” (no distingue entre mayúsculas y minúsculas), se convierte en el valor booleano correspondiente y se devuelve el valor opuesto. |
| Otro valor | Undefined. |
## Operador IN
Devuelve un resultado `Boolean`. Puede usar el operador IN en una cláusula WHERE para comprobar si un valor coincide con algún valor de una matriz. Devuelve true si hay coincidencia y false en caso contrario.
*Sintaxis:* ` expression IN expression`.
**Operador IN**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int/Decimal/String/Array/Object | Array | Verdadero si el elemento Integer/Decimal/String/Array/Object está en la raíz. De lo contrario, devuelve false. |
*Ejemplo:*
```
SQL: "select * from 'a/b' where 3 in arr"
JSON: {"arr":[1, 2, 3, "three", 5.7, null]}
```
En este ejemplo, la cláusula de condición `where 3 in arr` se evaluará como verdadera porque el número 3 está presente en la matriz denominada `arr`. Por lo tanto, en la instrucción SQL, se ejecutará `select * from 'a/b'`. Este ejemplo también muestra que la matriz puede ser heterogénea.
## Operador EXISTS
Devuelve un resultado `Boolean`. Puede usar el operador EXISTS en una cláusula condicional para comprobar la existencia de elementos en una subconsulta. Devuelve verdadero si la subconsulta devuelve uno o más elementos y falso si no devuelve ningún elemento.
*Sintaxis:* ` expression`.
*Ejemplo:*
```
SQL: "select * from 'a/b' where exists (select * from arr as a where a = 3)"
JSON: {"arr":[1, 2, 3]}
```
En este ejemplo, la cláusula de condición `where exists (select * from arr as a where a = 3)` se evaluará como verdadera porque el número 3 está presente en la matriz denominada `arr`. Por lo tanto, en la instrucción SQL, se ejecutará `select * from 'a/b'`.
*Ejemplo:*
```
SQL: select * from 'a/b' where exists (select * from e as e where foo = 2)
JSON: {"foo":4,"bar":5,"e":[{"foo":1},{"foo":2}]}
```
En este ejemplo, la cláusula de condición `where exists (select * from e as e where foo = 2)` se evaluará como verdadera porque la matriz `e` del objeto JSON contiene el objeto `{"foo":2}`. Por lo tanto, en la instrucción SQL, se ejecutará `select * from 'a/b'`.
## > operador
Devuelve un resultado `Boolean`. Devuelve el valor true si el operando izquierdo es superior al operando derecho. Los dos operandos se convierten en un valor `Decimal` y, a continuación, se comparan.
*Sintaxis:* `expression > expression`.
**> operador**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Devuelve el valor true si el operando izquierdo es superior al operando derecho. De lo contrario, devuelve false. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se pueden convertir en un valor Decimal y, a continuación, en un valor Boolean. Devuelve el valor true si el operando izquierdo es superior al operando derecho. De lo contrario, devuelve false. |
| Otro valor | Undefined. | Undefined. |
## >= operador
Devuelve un resultado `Boolean`. Devuelve el valor true si el operando izquierdo es superior o igual al operando derecho. Los dos operandos se convierten en un valor `Decimal` y, a continuación, se comparan.
*Sintaxis:* `expression >= expression`.
**>= operador**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Devuelve el valor true si el operando izquierdo es superior o igual al operando derecho. De lo contrario, devuelve false. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se pueden convertir en un valor Decimal y, a continuación, en un valor Boolean. Devuelve el valor true si el operando izquierdo es superior o igual al operando derecho. De lo contrario, devuelve false. |
| Otro valor | Undefined. | Undefined. |
## Operador <
Devuelve un resultado `Boolean`. Devuelve el valor true si el operando izquierdo es inferior al operando derecho. Los dos operandos se convierten en un valor `Decimal` y, a continuación, se comparan.
*Sintaxis:* `expression < expression`.
**Operador <**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Devuelve el valor true si el operando izquierdo es inferior al operando derecho. De lo contrario, devuelve false. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se pueden convertir en un valor Decimal y, a continuación, en un valor Boolean. Devuelve el valor true si el operando izquierdo es inferior al operando derecho. De lo contrario, devuelve false. |
| Otro valor | Undefined | Undefined |
## Operador <=
Devuelve un resultado `Boolean`. Devuelve el valor true si el operando izquierdo es inferior o igual al operando derecho. Los dos operandos se convierten en un valor `Decimal` y, a continuación, se comparan.
*Sintaxis:* `expression <= expression`.
**Operador <=**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Devuelve el valor true si el operando izquierdo es inferior o igual al operando derecho. De lo contrario, devuelve false. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se pueden convertir en un valor Decimal y, a continuación, en un valor Boolean. Devuelve el valor true si el operando izquierdo es inferior o igual al operando derecho. De lo contrario, devuelve false. |
| Otro valor | Undefined | Undefined |
## Operador <>
Devuelve un resultado `Boolean`. Devuelve el valor true si los operandos izquierdo y derecho no son iguales. De lo contrario, devuelve el valor false.
*Sintaxis:* ` expression <> expression`.
**Operador <>**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int | Int | True si el operando izquierdo no es igual al operando derecho. De lo contrario, devuelve false. |
| Decimal | Decimal | True si el operando izquierdo no es igual al operando derecho. De lo contrario, devuelve false. Int se convierte en un valor Decimal antes de la comparación. |
| String | String | True si el operando izquierdo no es igual al operando derecho. De lo contrario, devuelve false. |
| Matriz | Matriz | True si los elementos de cada operando no son iguales y no están en el mismo orden. De lo contrario, devuelve false. |
| Objeto | Objeto | True si las claves y los valores de cada operando no son iguales. De lo contrario, devuelve false. El orden de no keys/values es importante. |
| Nulo | Nulo | False. |
| Cualquier valor | Undefined | Sin definir. |
| Undefined | Cualquier valor | Sin definir. |
| Tipo no coincidente | Tipo no coincidente | True. |
## Operador =
Devuelve un resultado `Boolean`. Devuelve el valor true si los operandos izquierdo y derecho son iguales. De lo contrario, devuelve el valor false.
*Sintaxis:* ` expression = expression`.
**Operador =**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int | Int | True si el operando izquierdo es igual al operando derecho. De lo contrario, devuelve false. |
| Decimal | Decimal | True si el operando izquierdo es igual al operando derecho. De lo contrario, devuelve false. Int se convierte en un valor Decimal antes de la comparación. |
| String | String | True si el operando izquierdo es igual al operando derecho. De lo contrario, devuelve false. |
| Matriz | Matriz | True si los elementos de cada operando son iguales y están en el mismo orden. De lo contrario, devuelve false. |
| Objeto | Objeto | True si las claves y los valores de cada operando son iguales. De lo contrario, devuelve false. El orden de no keys/values es importante. |
| Cualquier valor | Undefined | Undefined. |
| Undefined | Cualquier valor | Undefined. |
| Tipo no coincidente | Tipo no coincidente | False. |
## Operador \$1
El símbolo "\$1" es un operador sobrecargado. Se puede utilizar para la concatenación o la adición de cadenas.
*Sintaxis:* ` expression + expression`.
**Operador \$1**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| String | Cualquier valor | Convierte el operando derecho en una cadena que concatena al final del operando izquierdo. |
| Cualquier valor | String | Convierte el operando izquierdo en una cadena y concatena el operando derecho al final del operando izquierdo convertido. |
| Int | Int | valor de Int. Agrega ambos operandos. |
| Int/Decimal | Int/Decimal | valor de Decimal. Agrega ambos operandos. |
| Otro valor | Otro valor | Undefined. |
## Operador -
Resta el operando derecho del operando izquierdo.
*Sintaxis:* ` expression - expression`.
**Operador -**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int | Int | valor de Int. Resta el operando derecho del operando izquierdo. |
| Int/Decimal | Int/Decimal | valor de Decimal. Resta el operando derecho del operando izquierdo. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se convierten en decimales correctamente, se devuelve un valor Decimal. Resta el operando derecho del operando izquierdo. De lo contrario, devuelve Undefined. |
| Otro valor | Otro valor | Undefined. |
| Otro valor | Otro valor | Undefined. |
## Operador \$1
Multiplica el operando izquierdo por el operando derecho.
*Sintaxis:* ` expression * expression`.
**Operador \$1**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int | Int | valor de Int. Multiplica el operando izquierdo por el operando derecho. |
| Int/Decimal | Int/Decimal | valor de Decimal. Multiplica el operando izquierdo por el operando derecho. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se convierten en decimales correctamente, se devuelve un valor Decimal. Multiplica el operando izquierdo por el operando derecho. De lo contrario, devuelve Undefined. |
| Otro valor | Otro valor | Undefined. |
## Operador /
Divide el operando izquierdo por el operando derecho.
*Sintaxis:* ` expression / expression`.
**Operador /**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int | Int | valor de Int. Divide el operando izquierdo por el operando derecho. |
| Int/Decimal | Int/Decimal | valor de Decimal. Divide el operando izquierdo por el operando derecho. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se convierten en decimales correctamente, se devuelve un valor Decimal. Divide el operando izquierdo por el operando derecho. De lo contrario, devuelve Undefined. |
| Otro valor | Otro valor | Undefined. |
## Operador %
Devuelve el resto de la división del operando izquierdo por el operando derecho.
*Sintaxis:* ` expression % expression`.
**Operador %**
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int | Int | valor de Int. Devuelve el resto de la división del operando izquierdo por el operando derecho. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se convierten en decimales correctamente, se devuelve un valor Decimal. Devuelve el resto de la división del operando izquierdo por el operando derecho. De lo contrario, Undefined. |
| Otro valor | Otro valor | Undefined. |
# Funciones
Puede utilizar las funciones integradas siguientes en las cláusulas SELECT o WHERE de sus expresiones SQL.
Las siguientes funciones externas se facturan de forma equivalente a la de una acción de regla: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb), y. [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow) Además, solo se le facturará por la función [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64) cuando [descodifique un mensaje de Protobuf en JSON](https://docs.aws.amazon.com//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf). Para obtener más detalles, consulte la [página de precios de AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
## abs(Decimal)
Devuelve el valor absoluto de un número. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `abs(-5)` devuelve 5.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, el valor absoluto del argumento. |
| Decimal | Decimal, el valor absoluto del argumento. |
| Boolean | Undefined. |
| String | Decimal. El resultado es el valor absoluto del argumento. Si la cadena no se puede convertir, el resultado es Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## accountid()
Devuelve el ID de la cuenta que posee esta regla como un valor de tipo `String`. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`accountid() ` = "123456789012"
## acos(Decimal)
Devuelve el coseno inverso de un número en radianes. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `acos(0)` = 1.5707963267948966
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), el coseno inverso del argumento. Se devuelven resultados imaginarios como Undefined. |
| Decimal | Decimal (con doble precisión), el coseno inverso del argumento. Se devuelven resultados imaginarios como Undefined. |
| Boolean | Undefined. |
| String | Decimal, el coseno inverso del argumento. Si la cadena no se puede convertir, el resultado es Undefined. Se devuelven resultados imaginarios como Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## asin(Decimal)
Devuelve el seno inverso de un número en radianes. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `asin(0)` = 0.0
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), el seno inverso del argumento. Se devuelven resultados imaginarios como Undefined. |
| Decimal | Decimal (con doble precisión), el seno inverso del argumento. Se devuelven resultados imaginarios como Undefined. |
| Boolean | Undefined. |
| String | Decimal (con doble precisión), el seno inverso del argumento. Si la cadena no se puede convertir, el resultado es Undefined. Se devuelven resultados imaginarios como Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## atan(Decimal)
Devuelve la tangente inversa de un número en radianes. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `atan(0)` = 0.0
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), la tangente inversa del argumento. Se devuelven resultados imaginarios como Undefined. |
| Decimal | Decimal (con doble precisión), la tangente inversa del argumento. Se devuelven resultados imaginarios como Undefined. |
| Boolean | Undefined. |
| String | Decimal, la tangente inversa del argumento. Si la cadena no se puede convertir, el resultado es Undefined. Se devuelven resultados imaginarios como Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## atan2(Decimal, Decimal)
Devuelve el ángulo, en radianes, entre el eje x positivo y el punto (x, y) definido en los dos argumentos. El ángulo es positivo para los ángulos en sentido contrario a las agujas del reloj (plano medio superior y > 0) y es negativo para los ángulos que siguen el sentido de las agujas del reloj (plano medio inferior y < 0). Los argumentos `Decimal` se redondean con doble precisión antes de aplicar la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `atan2(1, 0)` = 1.5707963267948966
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal (con doble precisión), el ángulo entre el eje x y el punto (x, y) especificado. |
| Int/Decimal/String | Int/Decimal/String | Decimal, la tangente inversa del punto descrito. Si una cadena no se puede convertir, el resultado es Undefined. |
| Otro valor | Otro valor | Undefined. |
## aws\$1lambda(functionArn, inputJson)
Llama a la función de Lambda especificada que pasa `inputJson` a la función de Lambda y devuelve el JSON generado por la función de Lambda.
**Argumentos**
| Argumento | Description (Descripción) |
| --- | --- |
| functionArn | El ARN de la función de Lambda; a la que se llamará. La función de Lambda debe devolver datos JSON. |
| inputJson | La entrada de JSON trasladada a la función de Lambda. Para pasar literales y consultas de objetos anidados, debe usar la versión 2016-03-23 de SQL. |
Debe conceder AWS IoT `lambda:InvokeFunction` permisos para invocar la función Lambda especificada. En el siguiente ejemplo, se muestra cómo se puede conceder el permiso `lambda:InvokeFunction` utilizando AWS CLI:
```
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"
```
A continuación, se indican los argumentos del comando **add-permission**:
--function-name
Nombre de la función de Lambda. Agrega un nuevo permiso para actualizar la política de recursos de la función.
--region
El Región de AWS de su cuenta.
-- entidad principal
La entidad principal que obtiene el permiso. Esto debería ser `iot.amazonaws.com` para permitir el AWS IoT permiso de llamar a una función Lambda.
--source-arn
El ARN de la regla. Puede usar el **get-topic-rule** AWS CLI comando para obtener el ARN de una regla.
--source-account
El Cuenta de AWS lugar donde se define la regla.
--statement-id
Un identificador de instrucción único.
--action
La acción Lambda que desea permitir en esta instrucción. Para permitir que AWS IoT invoque una función de Lambda, especifique `lambda:InvokeFunction`.
**importante**
Si añade un permiso para un AWS IoT principal sin proporcionar el `source-arn` o`source-account`, cualquier permiso Cuenta de AWS que cree una regla con su acción de Lambda puede activar reglas desde las que invocar la función de Lambda. AWS IoT Para obtener más información, consulte [Lambda Permission Model](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).
Dada una carga de mensaje JSON como:
```
{
"attribute1": 21,
"attribute2": "value"
}
```
La función `aws_lambda` se puede utilizar para llamar a la función de Lambda de la siguiente manera:
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", {"payload":attribute1}) as output FROM 'topic-filter'
```
Si desea pasar la carga del mensaje MQTT completa, puede especificar la carga JSON mediante '\$1', como en el ejemplo siguiente.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", *) as output FROM 'topic-filter'
```
`payload.inner.element` selecciona datos de mensajes publicados en el tema 'tema/subtema'.
`some.value` selecciona datos de la salida generada por la función de Lambda.
**nota**
El motor de reglas limita la duración de la ejecución de las funciones de Lambda. Las llamadas a funciones de Lambda desde las reglas deben completarse en 2000 milisegundos.
## bitand(Int, Int)
Ejecuta una operación AND bit a bit en las representaciones de bits de los dos argumentos `Int`(-convertidos). Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `bitand(13, 5)` = 5
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int | Int | Int, una operación AND bit a bit de los dos argumentos. |
| Int/Decimal | Int/Decimal | Int, una operación AND bit a bit de los dos argumentos. Todos los números que no son de tipo Int se redondean al valor Int inferior más cercano. Si alguno de los argumentos no se puede convertir en un valor Int, el resultado es Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, una operación AND bit a bit de los dos argumentos. Todas las cadenas se convierten en decimales y se redondean al valor Int inferior más cercano. Si se produce un error en la conversión, el resultado obtenido es Undefined. |
| Otro valor | Otro valor | Undefined. |
## bitor(Int, Int)
Realiza una operación OR bit a bit de las representaciones de bit de los dos argumentos. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `bitor(8, 5)` = 13
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int | Int | Int, la operación OR bit a bit de los dos argumentos. |
| Int/Decimal | Int/Decimal | Int, la operación OR bit a bit de los dos argumentos. Todos los números que no son de tipo Int se redondean al valor Int inferior más cercano. Si se produce un error en la conversión, el resultado obtenido es Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, la operación OR bit a bit en los dos argumentos. Todas las cadenas se convierten en decimales y se redondean al valor Int inferior más cercano. Si se produce un error en la conversión, el resultado obtenido es Undefined. |
| Otro valor | Otro valor | Undefined. |
## bitxor(Int, Int)
Ejecuta una operación XOR bit a bit en las representaciones de bits de los dos argumentos `Int`(-convertidos). Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:`bitor(13, 5)` = 8
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int | Int | Int, una operación XOR bit a bit en los dos argumentos. |
| Int/Decimal | Int/Decimal | Int, una operación XOR bit a bit en los dos argumentos. Los números que no son Int se redondean al valor Int inferior más cercano. |
| Int/Decimal/String | Int/Decimal/String | Int, una operación XOR bit a bit en los dos argumentos. Las cadenas se convierten en decimales y se redondean al valor Int más cercano. Si se produce un error en la conversión, el resultado obtenido es Undefined. |
| Otro valor | Otro valor | Undefined. |
## bitnot(Int)
Ejecuta una operación NOT bit a bit en las representaciones de bits del argumento `Int` (convertido). Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `bitnot(13)` = 2
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, una operación NOT bit a bit del argumento. |
| Decimal | Int, una operación NOT bit a bit del argumento. El valor Decimal se redondea al valor Int inferior más cercano. |
| String | Int, una operación NOT bit a bit del argumento. Las cadenas se convierten en decimales y se redondean al valor Int inferior más cercano. Si se produce un error en la conversión, el resultado obtenido es Undefined. |
| Otro valor | Otro valor. |
## cast()
Convierte un valor de un tipo de datos a otro tipo. Cast se comporta básicamente como las conversiones estándar, salvo que puede convertir números en valores booleanos o viceversa. Si AWS IoT no puede determinar cómo convertir un tipo en otro, el resultado es. `Undefined` Es compatible con la versión 2015-10-08 de SQL y versiones posteriores. Formato: fundido (*value*as*type*).
Ejemplo:
`cast(true as Int) ` = 1
Las siguientes palabras clave pueden aparecer después de "as" cuando se llama a `cast`:
**Para las versiones 2015-10-08 y 2016-03-23 de SQL**
| Palabra clave | Resultado |
| --- | --- |
| String | Convierte un valor en String. |
| Nvarchar | Convierte un valor en String. |
| Texto | Convierte un valor en String. |
| Ntext | Convierte un valor en String. |
| varchar | Convierte un valor en String. |
| Int | Convierte un valor en Int. |
| Entero | Convierte un valor en Int. |
| Double | Convierte un valor en Decimal (con double precision). |
**Además, para SQL versión 2016-03-23**
| Palabra clave | Resultado |
| --- | --- |
| Decimal | Convierte un valor en Decimal. |
| Bool | Convierte un valor en Boolean. |
| Boolean | Convierte un valor en Boolean. |
Reglas de conversión:
**Conversión en decimal**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Valor Decimal sin separador decimal. |
| Decimal | El valor de origen. Con SQL V2 (2016-03-23), los valores numéricos que son números enteros, como `10.0`, devuelven un valor `Int` (`10`) en lugar del valor `Decimal` esperado (`10.0`). Para convertir de forma fiable los valores numéricos de números enteros como valores `Decimal`, utilice SQL V1 (2015-10-08) como instrucción de consulta de regla. |
| Boolean | true = 1.0, false = 0.0. |
| String | Intenta analizar la cadena como un valor Decimal. AWS IoT intenta analizar las cadenas que coincidan con la expresión regular: ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1.2", "5E-12" son ejemplos de cadenas que se convierten automáticamente en valores de tipo Decimal. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
**Conversión en entero**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | El valor de origen. |
| Decimal | El valor de origen redondeado al valor Int inferior más cercano. |
| Boolean | true = 1.0, false = 0.0. |
| String | Intenta analizar la cadena como un valor Decimal. AWS IoT intenta analizar las cadenas que coincidan con la expresión regular: ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1.2", "5E-12" son ejemplos de cadenas que se convierten automáticamente en valores de tipo Decimal. AWS IoT intenta convertir la cadena en un valor de tipo Decimal y redondearlo al valor de tipo Int inferior más cercano. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
**Conversión a valor `Boolean`**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | 0 = False, any\$1nonzero\$1value = True. |
| Decimal | 0 = False, any\$1nonzero\$1value = True. |
| Boolean | El valor de origen. |
| String | "true" = True y "false" = False (no distingue entre mayúsculas y minúsculas). Otros valores de cadena = Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
**Conversión en cadenas**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Una representación de cadena del valor Int, en notación estándar. |
| Decimal | Una cadena que representa el valor Decimal, posiblemente en notación científica. |
| Boolean | "true" o "false", todo en minúsculas. |
| String | El valor de origen. |
| Matriz | La matriz serializada en formato JSON. La cadena obtenida es una lista separada por comas, entre corchetes. Los valores String se indican entre comillas. Los valores Decimal, Int y Boolean no se indican entre comillas. |
| Objeto | El objeto serializado al formato JSON. La cadena JSON es una lista separada por comas de pares clave-valor que comienza y termina con llaves. Los valores String se indican entre comillas. Los valores Decimal, Int, Boolean y Null no se indican entre comillas. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## ceil(Decimal)
Redondea el valor `Decimal` indicado al valor `Int` superior más cercano. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`ceil(1.2)` = 2
`ceil(-1.2)` = -1
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, el valor del argumento. |
| Decimal | Int, el valor de Decimal redondeado al valor de tipo Int superior más cercano. |
| String | Int. La cadena se convierte en un valor Decimal y se redondea al valor de tipo Int superior más cercano. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Otro valor | Undefined. |
## chr(String)
Devuelve el carácter ASCII que corresponde al argumento `Int` determinado. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`chr(65)` = "A".
`chr(49)` = "1".
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | El carácter correspondiente al valor ASCII especificado. Si el argumento no es un valor ASCII válido, el resultado es Undefined. |
| Decimal | El carácter correspondiente al valor ASCII especificado. El argumento Decimal se redondea al valor Int inferior más cercano. Si el argumento no es un valor ASCII válido, el resultado es Undefined. |
| Boolean | Undefined. |
| String | Si el valor String puede convertirse en un valor Decimal, se redondea al valor Int inferior más cercano. Si el argumento no es un valor ASCII válido, el resultado es Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Otro valor | Undefined. |
## clientid()
Devuelve el ID del cliente MQTT que envía el mensaje o `n/a` si el mensaje no se ha enviado por MQTT. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`clientid() ` = "123456789012"
## concat()
Concatena matrices o cadenas. Esta función acepta cualquier cantidad de argumentos y devuelve un valor `String` o un valor `Array`. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`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]
****
| Número de argumentos | Resultado |
| --- | --- |
| 0 | Undefined. |
| 1 | El argumento se devuelve sin modificar. |
| 2\$1 | Si alguno de los argumentos es un valor `Array`, el resultado es una matriz única que contiene todos los argumentos. Si no hay argumentos de tipo Array y al menos un argumento es un valor `String`, el resultado es la concatenación de las representaciones de `String` de todos los argumentos. Los argumentos se convierten en cadenas mediante las conversiones estándar indicadas arriba. |
## cos(Decimal)
Devuelve el coseno de un número en radianes. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`cos(0)` = 1.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), el coseno del argumento. Se devuelven resultados imaginarios como Undefined. |
| Decimal | Decimal (con doble precisión), el coseno del argumento. Se devuelven resultados imaginarios como Undefined. |
| Boolean | Undefined. |
| String | Decimal (con doble precisión), el coseno del argumento. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. Se devuelven resultados imaginarios como Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## cosh(Decimal)
Devuelve el coseno hiperbólico de un número en radianes. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `cosh(2.3)` = 5.037220649268761.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), el coseno hiperbólico del argumento. Se devuelven resultados imaginarios como Undefined. |
| Decimal | Decimal (con doble precisión), el coseno hiperbólico del argumento. Se devuelven resultados imaginarios como Undefined. |
| Boolean | Undefined. |
| String | Decimal (con doble precisión), el coseno hiperbólico del argumento. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. Se devuelven resultados imaginarios como Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## decode(value, decodingScheme)
Utilice la función `decode` para descodificar un valor codificado. Si la cadena descodificada es un documento JSON, se devuelve un objeto direccionable. De lo contrario, la cadena descodificada se devuelve como una cadena. La función devuelve NULL si la cadena no se puede descodificar. Esta función admite la descodificación de cadenas codificadas en base64 y el formato de mensaje de búferes de protocolo (protobuf).
Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
valor
Un valor de cadena o cualquiera de las expresiones válidas, tal como se define en [AWS IoT Referencia SQL](iot-sql-reference.md), que devuelven una cadena.
decodingScheme
Una cadena literal que representa el esquema utilizado para descodificar el valor. Actualmente solo se admiten `'base64'` y `'proto'`.
### Descodificar cadenas codificadas en base64
En este ejemplo, la carga del mensaje incluye un valor codificado.
```
{
encoded_temp: "eyAidGVtcGVyYXR1cmUiOiAzMyB9Cg=="
}
```
La función `decode` de esta instrucción SQL descodifica el valor de la carga del mensaje.
```
SELECT decode(encoded_temp,"base64").temperature AS temp from 'topic/subtopic'
```
Al descodificar el valor `encoded_temp`, se obtiene el siguiente documento JSON válido, que permite que la instrucción SELECT lea el valor de temperatura.
```
{ "temperature": 33 }
```
El resultado de la instrucción SELECT de este ejemplo se muestra aquí.
```
{ "temp": 33 }
```
Si el valor descodificado no era un documento JSON válido, el valor descodificado se devolvería en forma de cadena.
### Descodificación de la carga de un mensaje de protobuf
Puede utilizar la función de decodificación de SQL para configurar una regla que pueda descodificar la carga de sus mensajes de protobuf. Para obtener más información, consulte [Descodificar cargas de mensajes de protobuf](binary-payloads.md#binary-payloads-protobuf).
**importante**
Si omites `source‐arn` o `source‐account` al configurar los permisos para un AWS IoT director, cualquiera Cuenta de AWS puede invocar tu función de decodificación mediante otras reglas. AWS IoT Para proteger la función, consulte [Políticas de bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html) en la *Guía del usuario de Amazon Simple Storage Service*.
La firma de la clase tiene el siguiente aspecto:
```
decode(, 'proto', '', '', '', '')
```
`ENCODED DATA`
Especifica los datos codificados por protobuf que se van a descodificar. Si todo el mensaje enviado a la regla son datos codificados por protobuf, puede hacer referencia a la carga binaria entrante sin procesar utilizando `*`. De lo contrario, este campo debe ser una cadena JSON codificada en base64 y se puede transferir directamente una referencia a la cadena.
1) Para descodificar una carga binaria entrante de protobuf sin procesar:
```
decode(*, 'proto', ...)
```
2) Para descodificar un mensaje codificado en protobuf representado por una cadena codificada en base64 'a.b':
```
decode(a.b, 'proto', ...)
```
`proto`
Especifica los datos que se van a descodificar en un formato de mensaje protobuf. Si especifica `base64` en lugar de `proto`, esta función descodificará las cadenas codificadas en base64 como JSON.
`S3 BUCKET NAME`
El nombre del bucket de Amazon S3 donde cargó el archivo `FileDescriptorSet`.
`S3 OBJECT KEY`
La clave de objeto que especifica el archivo `FileDescriptorSet` dentro del bucket de Amazon S3.
`PROTO NAME`
El nombre del archivo `.proto` (excluida la extensión) a partir del cual se generó el archivo `FileDescriptorSet`.
`MESSAGE TYPE`
El nombre de la estructura de mensajes protobuf del archivo `FileDescriptorSet`, a la que deben ajustarse los datos que se van a descodificar.
Un ejemplo de expresión SQL que utilice la función de descodificación de SQL puede tener el siguiente aspecto:
```
SELECT VALUE decode(*, 'proto', 's3-bucket', 'messageformat.desc', 'myproto', 'messagetype') FROM 'some/topic'
```
+ `*`
Representa una carga binaria entrante, que se ajusta al tipo de mensaje protobuf llamado `mymessagetype`.
+ `messageformat.desc`
El archivo `FileDescriptorSet` almacenado en un bucket de Amazon S3 llamado `s3-bucket`.
+ `myproto`
El archivo `.proto` original utilizado para generar el archivo `FileDescriptorSet` llamado `myproto.proto`.
+ `messagetype`
El tipo de mensaje llamado `messagetype` (junto con cualquier dependencia importada) tal y como se define en `myproto.proto`.
## encode(value, encodingScheme)
Utilice la función `encode` para codificar la carga, que puede estar constituida por datos que no son JSON, en su representación de cadena basada en el esquema de codificación. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
valor
Cualquiera de las expresiones válidas, tal y como se define en [AWS IoT Referencia SQL](iot-sql-reference.md). Puede especificar \$1 para codificar toda la carga, con independencia de si está en formato JSON o no. Si suministra una expresión, el resultado de la evaluación se convierte en una cadena antes de codificarla.
encodingScheme
Una cadena literal que representa el esquema de codificación que desea utilizar. En la actualidad, solo se admite `'base64'`.
## endswith(String, String)
Devuelve un valor `Boolean` que indica si el primer argumento `String` termina con el segundo argumento `String`. Si alguno de los argumentos es `Null` o `Undefined`, el resultado es `Undefined`. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `endswith("cat","at")` = true.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | String | True si el primer argumento termina en el segundo argumento. De lo contrario, devuelve false. |
| Otro valor | Otro valor | Ambos argumentos se convierten en cadenas con las reglas de conversión estándar. True si el primer argumento termina en el segundo argumento. De lo contrario, devuelve false. Si alguno de los argumentos es Null o Undefined, el resultado es Undefined. |
## exp(Decimal)
Devuelve e elevado al argumento `Decimal`. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `exp(1)` = e.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), argumento potencia e. |
| Decimal | Decimal (con doble precisión), argumento potencia e. |
| String | Decimal (con doble precisión), argumento potencia e. Si el valor String no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Otro valor | Undefined. |
## floor(Decimal)
Redondea a la baja el valor `Decimal` indicado al valor `Int` más cercano. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`floor(1.2)` = 1
`floor(-1.2)` = -2
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, el valor del argumento. |
| Decimal | Int, valor Decimal redondeado a la baja al valor Int más próximo. |
| String | Int. La cadena se convierte en un valor Decimal y se redondea a la baja al valor Int más cercano. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Otro valor | Undefined. |
## introducción
Extrae un valor de un tipo de recopilación (matriz, cadena, objeto). No se aplica ninguna conversión al primer argumento. La conversión se aplica tal y como se documenta en la tabla del segundo argumento. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`get(["a", "b", "c"], 1) ` = "b"
`get({"a":"b"}, "a")` = "b"
`get("abc", 0)` = “a”
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| Matriz | Cualquier tipo (convertido en Int) | El elemento en el índice basado en 0 del valor Array proporcionado por el segundo argumento (convertido en Int). Si la conversión es incorrecta, el resultado obtenido es Undefined. Si el índice está fuera de los límites del valor Array (negativo o >= array.length), el resultado es Undefined. |
| Cadena | Cualquier tipo (convertido en Int) | El carácter en el índice basado en 0 de la cadena proporcionada por el segundo argumento (convertido en un valor Int). Si la conversión es incorrecta, el resultado obtenido es Undefined. Si el índice se encuentra fuera de los límites de la cadena (negativo o >= string.length), el resultado es Undefined. |
| Objeto | String (no se aplica conversión) | El valor almacenado en el objeto de primer argumento correspondiente a la clave de la cadena proporcionada como segundo argumento. |
| Otro valor | Cualquier valor | Undefined. |
## get\$1dynamodb (Nombre de tabla,,,,, ROLearn partitionKeyName) partitionKeyValue sortKeyName sortKeyValue
Recupera datos de una tabla DymanoDB. `get_dynamodb()` permite consultar una tabla DynamoDB mientras se evalúa una regla. Puede filtrar o aumentar las cargas útiles de mensajes utilizando los datos recuperados de DynamoDB. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
`get_dynamodb()` utiliza los parámetros siguientes:
tableName
Nombre de la tabla de DynamoDB donde efectuar la consulta.
partitionKeyName
Nombre de la tabla de particiones. Para obtener más información, consulte [Claves de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
partitionKeyValue
Valor de la clave de partición utilizada para identificar un registro. Para obtener más información, consulte [Claves de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyName
(Opcional) Nombre de la clave de clasificación. Este parámetro solo es necesario si la tabla DynamoDB consultada utiliza una clave compuesta. Para obtener más información, consulte [Claves de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyValue
(Opcional) Valor de la clave de clasificación. Este parámetro solo es necesario si la tabla DynamoDB consultada utiliza una clave compuesta. Para obtener más información, consulte [Claves de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
roleArn
El ARN de un rol de IAM que concede acceso a la tabla DynamoDB. El motor de reglas asume este rol para acceder a la tabla DynamoDB en su nombre. Evite usar un rol excesivamente permisivo. Otorgue al rol solo los permisos requeridos por la regla. A continuación se muestra un ejemplo de política que concede acceso a una tabla DynamoDB.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:GetItem",
"Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/table-name"
}
]
}
```
Como ejemplo de cómo usar `get_dynamodb()`, supongamos que tiene una tabla DynamoDB que contiene el ID de dispositivo e información de ubicación para todos los dispositivos conectados a AWS IoT. La siguiente instrucción SELECT utiliza la función `get_dynamodb()` para recuperar la ubicación del ID de dispositivo especificado:
`SELECT *, get_dynamodb("InServiceDevices", "deviceId", id, "arn:aws:iam::12345678910:role/getdynamo").location AS location FROM 'some/topic' `
**nota**
Puede llamar a `get_dynamodb()` un máximo de una vez por instrucción SQL. Llamar a `get_dynamodb()` varias veces en una sola instrucción SQL hace que la regla termine sin invocar ninguna acción.
## get\$1mqtt\$1property(name)
Hace referencia a cualquiera de los siguientes MQTT5 encabezados:,, y. `contentType` `payLoadFormatIndicator` `responseTopic` `correlationData` Esta función toma como argumento cualquiera de las siguientes cadenas literales: `content_type`, `format_indicator`, `response_topic` y `correlation_data`. Para obtener más información, consulte la siguiente table de **argumentos de la función**.
contentType
Cadena: una cadena codificada en UTF-8 que describe el contenido del mensaje de publicación.
payLoadFormatIndicador
Cadena: un valor de cadena Enum que indica si la carga tiene formato UTF-8. Los valores válidos son `UNSPECIFIED_BYTES` y `UTF8_DATA`.
responseTopic
Cadena: una cadena codificada en UTF-8 que se utiliza como nombre de tema para un mensaje de respuesta. El tema de respuesta se utiliza para describir el tema en el que el receptor debe publicar como parte del flujo de solicitud-respuesta. El tema no debe contener caracteres comodín.
correlationData
Cadena: los datos binarios codificados en base64 que utiliza el remitente del mensaje de solicitud para identificar a qué solicitud corresponde el mensaje de respuesta cuando se recibe.
En la siguiente tabla se muestran los argumentos de la función aceptables y los tipos de retorno asociados a la función `get_mqtt_property`:
**Argumentos de la función**
| SQL | Tipo de datos devuelto (si están presentes) | Tipo de datos devuelto (si no están presentes) |
| --- | --- | --- |
| get\$1mqtt\$1property("format\$1indicator") | Cadena (UNSPECIFIED\$1BYTES o \$1DATA) UTF8 | Cadena (UNSPECIFIED\$1BYTES) |
| get\$1mqtt\$1property("content\$1type") | Cadena | Sin definir |
| get\$1mqtt\$1property("response\$1topic") | Cadena | Sin definir |
| get\$1mqtt\$1property("correlation\$1data") | Cadena codificada en base64 | Sin definir |
| get\$1mqtt\$1property("some\$1invalid\$1name") | Sin definir | Sin definir |
El siguiente ejemplo de Rules SQL hace referencia a cualquiera de los siguientes MQTT5 encabezados:,, y. `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\$1or\$1default (expresión, DefaultValue)
Devuelve el valor predeterminado del segundo parámetro si se especifica o, si no, devuelve un valor indefinido cuando la expresión del primer parámetro devuelve un valor nulo, indefinido o produce un error. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
**importante**
`get_or_default`no admite cargas útiles que no sean de JSON directamente tal cual. Si utilizas una carga útil que no es de JSON, usa las funciones o. `encode` `decode`
`get_or_default()` utiliza los parámetros siguientes:
expresión
Cualquier expresión válida que contenga[Tipos de datos](iot-sql-data-types.md), [Funciones](#iot-sql-functions) [Literales](iot-sql-literals.md)[Consultas de objetos anidados](iot-sql-nested-queries.md), [Variables](iot-sql-set.md#iot-sql-set-usage) o. [Extensiones JSON](iot-sql-json.md)
defaultValue
(Opcional) Cualquier expresión válida que contenga [Tipos de datos](iot-sql-data-types.md)[Funciones](#iot-sql-functions),[Literales](iot-sql-literals.md),[Consultas de objetos anidados](iot-sql-nested-queries.md), [Variables](iot-sql-set.md#iot-sql-set-usage) o[Extensiones JSON](iot-sql-json.md). Este es el valor que se devolverá siempre que el primer argumento devuelva un valor nulo, indefinido o falle.
Las funciones que obtienen datos de los recursos propiedad del cliente, como get\$1secret, get\$1dynamodb, aws\$1lambda, get\$1thing\$1shadow, decode-protobuf y machinelearning\$1predict, no están permitidas para el parámetro DefaultValue.
En la siguiente tabla se muestran los argumentos de función aceptables para cada argumento y sus resultados asociados:
| Primer argumento | Segundo argumento | Output |
| --- | --- | --- |
| Evaluación exitosa | Cualquier valor o no especificado | El valor del primer argumento. |
| Indefinido, nulo o erróneo | Cualquier valor, incluidos indefinido o nulo | El valor del segundo argumento. |
| Indefinido, nulo o erróneo | no especificada | Undefined |
**Ejemplos**:
Ejemplo 1:
El siguiente ejemplo proporciona un valor DefaultValue si se produce un error en una tabla o consulta de DynamoDB:
```
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'
```
Ejemplo 2:
El siguiente ejemplo proporciona el valor predeterminado seguro «UNKNOWN» si el estado no está definido:
```
SELECT
get_or_default( CASE status
WHEN 'active' THEN 'GOOD'
WHEN 'inactive' THEN 'BAD'/
ELSE 'UNKNOWN'
END, 'UNKNOWN') as status_category
FROM 'topic/subtopic'
```
Ejemplo 3:
En el siguiente ejemplo, se muestra cómo se puede utilizar también get\$1or\$1default con un único parámetro. Esto resulta útil en situaciones en las que es posible que no tenga un valor predeterminado claro, pero no desee que se produzca un error en la ejecución de la regla.
```
SELECT
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME") as config
FROM 'device/telemetry'
```
Si se produce un error en la búsqueda de DynamoDB, se producirá un error en la ejecución de la regla y no se ejecutará ninguna acción. Si en su lugar se utiliza el siguiente SQL:
```
SELECT
get_or_default(get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME")) as config
FROM 'device/telemetry'
```
La sentencia get\$1or\$1default se evaluará como`Undefined`, por lo que en este ejemplo, la sentencia SELECT en general se evaluará como resultado `{}` y se intentará realizar cualquier acción de regla.
**importante**
Recomendamos seguir estas prácticas recomendadas para mantener la seguridad al utilizar esta función:
Evite el uso de secretos codificados de forma rígida en las definiciones de reglas, incluidos los valores predeterminados
Úselo AWS Secrets Manager para administrar información confidencial
## get\$1registry\$1data (API de registro, ThingName, ROLearn)
Recupera los datos AWS IoT de registro de cosas de una AWS IoT regla. Puede leer los datos del registro (como los atributos, el tipo de cosa y los grupos de cosas a los que pertenece un dispositivo) y usar esta información para filtrar, enriquecer o enrutar los mensajes de forma dinámica. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
`get_registry_data()` utiliza los parámetros siguientes:
API de registro
La API de registro a la que se está llamando. Los valores válidos son `DescribeThing` y `ListThingGroupsForThing`. Estos valores deben ser cadenas constantes.
thingName
Cadena: el nombre de la cosa cuyos datos de registro desea recuperar.
roleArn
Cadena: un ARN de rol con `iot:DescribeThing` permiso de and/or `iot:ListThingGroupsForThing` permiso basado en la API a la que se llama.
El formato de respuesta de la `get_registry_data` función es el mismo que el de la API de registro a la que se ha llamado. Para obtener más información, consulte [DescribeThing](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeThing.html) y [ListThingGroupsForThing](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingGroupsForThing.html) APIs.
Ejemplo:
Puede recuperar la información del tipo de cosa para poder filtrar los mensajes de eventos AWS IoT Core del ciclo de vida de las cosas (cuyo nombre coincida con el identificador del cliente de MQTT) donde esté `testenv` el tipo de cosa.
```
SELECT *
FROM '$aws/events/lifecycle/+'
WHERE
get_registry_data("DescribeThing",clientId,[roleArn]).thingTypeName='testenv'
```
Ejemplo:
Puede recuperar los atributos de un dispositivo con el nombre de la cosa `sensor1` para todos los mensajes enviados por su dispositivo `gateway1` de puerta de enlace.
```
SELECT *, get_registry_data("DescribeThing","sensor1",[roleArn]).attributes.temperature_threhold AS device1_tempthreshold
FROM home1/gateway1/sensor1/#
```
**nota**
Puede llamar `get_registry_data()` como máximo una vez por sentencia SQL y plantillas de sustitución para las acciones y las acciones de error.
## get\$1secret(secretId, secretType, key, roleArn)
Recupera el valor del campo `SecretString` o `SecretBinary` cifrado de la versión actual de un secreto en [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/). Para obtener más información sobre la creación y el mantenimiento de secretos [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html), consulte [UpdateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html), y [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html).
`get_secret()` utiliza los parámetros siguientes:
secretId
Cadena: el nombre de recurso de Amazon (ARN) o el nombre fácil de recordar del secreto que se va a recuperar.
secretType
Cadena: el tipo de secreto. Valores válidos: `SecretString` \$1 `SecretBinary`.
SecretString
+ Para ver los secretos que se crean como objetos JSON mediante la APIs AWS CLI, la o la AWS Secrets Manager consola:
+ Si especifica un valor para el parámetro `key`, esta función devuelve el valor de la clave especificada.
+ Si no especifica un valor para el parámetro `key`, esta función devuelve el objeto JSON completo.
+ Para los secretos que se crean como objetos que no son de JSON mediante el uso de APIs o el AWS CLI:
+ Si especifica un valor para el parámetro `key`, esta función produce una excepción.
+ Si no especifica un valor para el parámetro `key`, esta función devuelve el contenido del secreto.
SecretBinary
+ Si especifica un valor para el parámetro `key`, esta función produce una excepción.
+ Si no especificas un valor para el parámetro `key`, esta función devuelve el valor secreto como una cadena UTF-8 codificada en base64.
clave
(Opcional) Cadena: el nombre de la clave dentro de un objeto JSON almacenado en el campo `SecretString` de un secreto. Use este valor cuando desee recuperar solo el valor de una clave almacenada en un secreto en lugar de recuperar todo el objeto JSON.
Si especifica un valor para este parámetro y el secreto no contiene un objeto JSON dentro de su campo `SecretString`, esta función produce una excepción.
roleArn
Cadena: un ARN de rol con permisos `secretsmanager:GetSecretValue` y `secretsmanager:DescribeSecret`.
**nota**
Esta función siempre devuelve la versión actual del secreto (la versión con la etiqueta `AWSCURRENT`). El motor de AWS IoT reglas guarda en caché cada secreto durante un máximo de 15 minutos. Como resultado, el motor de reglas puede tardar hasta 15 minutos en actualizar un secreto. Esto significa que si recuperas un secreto hasta 15 minutos después de una actualización AWS Secrets Manager, es posible que esta función devuelva la versión anterior.
Esta función no está sujeta a taxímetro, pero se aplican AWS Secrets Manager cargos. Debido al mecanismo de almacenamiento en caché de secretos, el motor de reglas llama en ocasiones a AWS Secrets Manager. Como el motor de reglas es un servicio totalmente distribuido, es posible que vea varias llamadas a la API de Secrets Manager desde el motor de reglas durante el período de almacenamiento en caché de 15 minutos.
Ejemplos:
Puede usar la función `get_secret` en un encabezado de autenticación en una acción de regla HTTPS, como en el siguiente ejemplo de autenticación con clave de API.
```
"API_KEY": "${get_secret('API_KEY', 'SecretString', 'API_KEY_VALUE', 'arn:aws:iam::12345678910:role/getsecret')}"
```
Para obtener más información sobre la acción de regla HTTPS, consulte [HTTP](https-rule-action.md).
## get\$1thing\$1shadow (ThingName, ShadowName, ROLearn)
Devuelve la sombra especificada de la cosa especificado. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
thingName
String: el nombre del elemento cuya sombra desea recuperar.
shadowName
(Opcional) Cadena: el nombre de la sombra. Este parámetro solo es necesario cuando se hace referencia a sombras con nombre.
roleArn
String: un ARN de rol con permiso `iot:GetThingShadow`.
Ejemplos:
Cuando se utilice con una sombra con nombre, proporcione el parámetro `shadowName`.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","MyThingShadow","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
Cuando se utiliza con una sombra sin nombre, omita el parámetro `shadowName`.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
## get\$1user\$1properties () userPropertyKey
Hace referencia a las propiedades del usuario, que es un tipo de encabezados de propiedades que se admiten. MQTT5
userProperty
Cadena: una propiedad de usuario es un par clave-valor. Esta función toma la clave como argumento y devuelve una matriz de todos los valores que coinciden con la clave asociada.
**Argumentos de la función**
Para las siguientes propiedades de usuario en los encabezados de mensaje:
| Clave | Valor |
| --- | --- |
| alguna clave | algún valor |
| una clave diferente | un valor diferente |
| alguna clave | valor con clave duplicada |
La siguiente table muestra el comportamiento de SQL esperado:
| SQL | Tipo de datos devueltos | Valor de datos devueltos |
| --- | --- | --- |
| get\$1user\$1properties('some key') | Matriz de cadena | ['some value', 'value with duplicate key'] |
| get\$1user\$1properties('other key') | Matriz de cadena | ['a different value'] |
| get\$1user\$1properties( ) | Matriz de objetos de par clave-valor | [\$1'"some key": "some value"'\$1, \$1"other key": "a different value"\$1, \$1"some key": "value with duplicate key"\$1] |
| get\$1user\$1properties('non-existent key') | Sin definir | |
El siguiente ejemplo de reglas SQL hace referencia a las propiedades del usuario (un tipo de encabezado de MQTT5 propiedad) en la carga útil:
```
SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'
```
## Funciones de hash
AWS IoT proporciona las siguientes funciones de hash:
+ md2
+ md5
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Todas las funciones de hash esperan un argumento de cadena. El resultado es el valor con hash de dicha cadena. Las conversiones de cadena estándar se aplican a los argumentos que no son cadenas. Todas las funciones de hash son compatibles con la versión 2015-10-08 de SQL y con versiones posteriores.
Ejemplos:
`md2("hello")` = "a9046c73e00331af68917d3804f70655"
`md5("hello")` = "5d41402abc4b2a76b9719d911017c592"
## indexof(String, String)
Devuelve el primer índice (basado en 0) del segundo argumento como subcadena del primer argumento. Se espera que ambos argumentos sean cadenas. Los argumentos que no sean cadenas están sujetos a las reglas de conversión estándar de cadenas. Esta función no se aplica a matrices, únicamente a cadenas. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
Ejemplos:
`indexof("abcd", "bc") ` = 1
## isNull()
Devuelve verdadero si el argumento es el valor `Null`. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
Ejemplos:
`isNull(5) ` = false.
`isNull(Null) ` = true.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | true |
| Undefined | false |
## isUndefined()
Devuelve verdadero si el argumento tiene el valor `Undefined`. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
Ejemplos:
`isUndefined(5) ` = false.
`isUndefined(floor([1,2,3]))) ` = true.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | false |
| Undefined | true |
## length(String)
Devuelve el número de caracteres de la cadena suministrada. Se aplican las reglas de conversión estándar a los argumentos que no sean `String`. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
Ejemplos:
`length("hi")` = 2
`length(false)` = 5
## ln(Decimal)
Devuelve el logaritmo natural del argumento. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `ln(e)` = 1.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), el log natural del argumento. |
| Decimal | Decimal (con doble precisión), el log natural del argumento. |
| Boolean | Undefined. |
| String | Decimal (con doble precisión), el log natural del argumento. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## log(Decimal)
Devuelve el logaritmo decimal del argumento. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `log(100)` = 2.0.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), el log de base 10 del argumento. |
| Decimal | Decimal (con doble precisión), el log de base 10 del argumento. |
| Boolean | Undefined. |
| String | Decimal (con doble precisión), el log de base 10 del argumento. Si el valor String no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## lower(String)
Muestra la versión en minúsculas del valor `String` indicado. Los argumentos que no son cadenas se convierten en cadenas con las reglas de conversión estándar. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`lower("HELLO")` = "hello".
`lower(["HELLO"])` = "[\$1"hello\$1"]".
## lpad(String, Int)
Devuelve el argumento `String`, rellenado en el lado izquierdo con el número de espacios especificado por el segundo argumento. El argumento `Int` debe estar comprendido entre 0 y 1000. Si el valor proporcionado se encuentra fuera de este rango válido, el argumento se establece en el valor válido más cercano (0 o 1000). Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`lpad("hello", 2)` = "` hello`".
`lpad(1, 3)` = "` 1`"
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | Int | String, el valor String proporcionado rellenado en el lado izquierdo con un número de espacios igual al valor Int proporcionado. |
| String | Decimal | El argumento Decimal se redondea al valor Int inferior más cercano y el valor String se rellena en el lado izquierdo con el número de espacios especificado. |
| String | String | El segundo argumento se convierte en un valor Decimal, que se redondea al valor Int inferior más cercano, y el valor String se rellena con el número de espacios especificado en la izquierda. Si el segundo argumento no se puede convertir en un valor Int, el resultado es Undefined. |
| Otro valor | Int/Decimal/String | El primer valor se convierte en un valor de tipo String mediante las conversiones estándar y, a continuación, se aplica la función LPAD a dicho valor String. Si no se puede convertir, el resultado es Undefined. |
| Cualquier valor | Otro valor | Undefined. |
## ltrim(String)
Elimina todos los espacios en blanco del principio (tabuladores y espacios) del valor `String` proporcionado. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`Ltrim(" h i ")` = "hi ".
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | La representación String de Int con todos los espacios en blanco del principio suprimidos. |
| Decimal | La representación String de Decimal con todos los espacios en blanco del principio suprimidos. |
| Boolean | La representación String del valor booleano (“true” o “false”) con todos los espacios en blanco del principio suprimidos. |
| String | El argumento con todos los espacios en blanco del principio suprimidos. |
| Matriz | La representación String de Array (mediante las reglas de conversión estándar) con todos los espacios en blanco del principio suprimidos. |
| Objeto | La representación String de la cosa (mediante las reglas de conversión estándar) con todos los espacios en blanco del principio suprimidos. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## machinelearning\$1predict(modelId, roleArn, record)
Utilice la `machinelearning_predict` función para realizar predicciones con los datos de un mensaje MQTT basado en un modelo de Amazon SageMaker AI. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores. Los argumentos de la función `machinelearning_predict` son:
modelId
El ID del modelo en el que se ejecutará la predicción. El punto de conexión en tiempo real del modelo debe estar activado.
roleArn
El rol de IAM que tiene una política con permisos `machinelearning:Predict` y `machinelearning:GetMLModel`, y permite tener acceso al modelo en el que se ejecuta la predicción.
record
Los datos que se van a transferir a la API SageMaker AI Predict. Debe representarse como un objeto JSON de capa única. Si el registro es un objeto JSON de varias capas, el registro se aplana serializando sus valores. Por ejemplo, el JSON siguiente:
```
{ "key1": {"innerKey1": "value1"}, "key2": 0}
```
se convertiría en:
```
{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}
```
La función devuelve un objeto JSON con los campos siguientes:
predictedLabel
La clasificación de la entrada en función del modelo.
Detalles
Contiene los atributos siguientes:
PredictiveModelType
El tipo de modelo. Los valores válidos son REGRESSION, BINARY, MULTICLASS.
Algoritmo
El algoritmo utilizado por la SageMaker IA para hacer predicciones. El valor debe ser SGD.
predictedScores
Contiene la puntuación de clasificación bruta correspondiente a cada etiqueta.
predictedValue
El valor pronosticado por la SageMaker IA.
## mod(Decimal, Decimal)
Devuelve el resto de la división del primer argumento por el segundo argumento. Es igual que [remainder(Decimal, Decimal)](#iot-func-remainder). También puede utilizar "%" como un operador infijo para la misma funcionalidad modulo. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `mod(8, 3)` = 2.
****
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int | Int | Int, el primer y el segundo argumento en los que quiere ejecutar la función modulo. |
| Int/Decimal | Int/Decimal | Decimal, el primer argumento y el segundo operando para los que quiere ejecutar la función modulo. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se convierten en decimales, la función modulo se ejecuta en el primer y el segundo argumento. De lo contrario, Undefined. |
| Otro valor | Otro valor | Undefined. |
## nanval (,) AnyValue AnyValue
Devuelve el primer argumento si es un `Decimal` válido. De lo contrario, se devuelve el segundo argumento. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `Nanvl(8, 3)` = 8.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Output |
| --- | --- | --- |
| Sin definir | Cualquier valor | El segundo argumento. |
| Nulo | Cualquier valor | El segundo argumento. |
| Decimal (NaN) | Cualquier valor | El segundo argumento. |
| Decimal (no NaN) | Cualquier valor | El primer argumento. |
| Otro valor | Cualquier valor | El primer argumento. |
## newuuid()
Devuelve un UUID aleatorio de 16 bytes. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `newuuid()` = `123a4567-b89c-12d3-e456-789012345000`
## numbytes(String)
Devuelve el número de bytes de la codificación UTF-8 de la cadena proporcionada. Se aplican las reglas de conversión estándar a los argumentos que no sean `String`. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
Ejemplos:
`numbytes("hi")` = 2
`numbytes("€") ` = 3
## parse\$1time(String, Long[, String])
Use la `parse_time` función para formatear una marca de tiempo en un formato legible por humanos. date/time Es compatible con la versión SQL 2016-03-23 y versiones posteriores. Para convertir una cadena de marca temporal en milisegundos, consulte [time\$1to\$1epoch(String, String)](#iot-sql-function-time-to-epoch).
La función `parse_time` espera los argumentos siguientes:
pattern
[(Cadena) date/time Patrón que sigue los formatos Joda-Time.](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html)
timestamp
(Long) La hora que se va a formatear en milisegundos a partir del formato de hora Unix. Consulte la función [timestamp()](#iot-function-timestamp).
timezone
(String) La zona horaria de la fecha/hora formateada. El valor predeterminado es "UTC". La función admite [zonas horarias Joda-Time](http://joda-time.sourceforge.net/timezones.html) Este argumento es opcional.
Ejemplos:
Cuando este mensaje se publica en el tema "A/B", la carga `{"ts": "1970.01.01 AD at 21:46:40 CST"}` se envía al bucket de 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"
}
}
```
Cuando este mensaje se publica en el tema "A/B", una carga similar a `{"ts": "2017.06.09 AD at 17:19:46 UTC"}` (pero con la fecha y hora actuales) se envía al bucket de 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()` se puede usar también como una plantilla de sustitución. Por ejemplo, cuando este mensaje se publica en el tema "A/B", la carga se envía al bucket de S3 con la clave = "2017":
```
{
"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)
Devuelve el primer argumento elevado al segundo argumento. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `power(2, 5)` = 32.0.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Un Decimal (con doble precisión), el primer argumento elevado a la potencia del segundo argumento. |
| Int/Decimal/String | Int/Decimal/String | Un Decimal (con doble precisión), el primer argumento elevado a la potencia del segundo argumento. Todas las cadenas se convierten en decimales. Si cualquier String no se convierte en un valor Decimal, el resultado es Undefined. |
| Otro valor | Otro valor | Undefined. |
## principal()
Devuelve la entidad principal que el dispositivo utiliza para la autenticación, en función de cómo se publicó el mensaje de activación. En la siguiente tabla se describe la entidad principal devuelta para cada método y protocolo de publicación.
****
| Cómo se publica el mensaje | Protocolo | Tipo de credenciales | Principal |
| --- | --- | --- | --- |
| Cliente MQTT | MQTT | Certificado de dispositivo X.509 | Huella digital del certificado X.509 |
| AWS IoT cliente MQTT de consola | MQTT | Usuario o rol de IAM | iam-role-id:session-name |
| AWS CLI | HTTP | Usuario o rol de IAM | userid |
| AWS IoT SDK de dispositivo | MQTT | Certificado de dispositivo X.509 | Huella digital del certificado X.509 |
| AWS IoT SDK de dispositivo | MQTT ha terminado WebSocket | Usuario o rol de IAM | userid |
En los siguientes ejemplos se muestran los distintos tipos de valores que `principal()` puede devolver:
+ Huella digital del certificado X.509: `ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373`
+ ID de rol de IAM y nombre de sesión: `ABCD1EFG3HIJK2LMNOP5:my-session-name`
+ Devuelve un ID de usuario: `ABCD1EFG3HIJK2LMNOP5`
## rand()
Devuelve un valor pseudoaleatorio, distribuido de forma uniforme entre 0,0 y 1,0. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`rand()` = 0.8231909191640703
## regexp\$1matches(String, String)
Devuelve verdadero si la cadena (primer argumento) contiene una coincidencia para la expresión regular (segundo argumento). Si usa `|` en la expresión regular, úselo con `()`.
Ejemplos:
`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.
**Primer argumento:**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | La representación String del valor Int. |
| Decimal | La representación String del valor Decimal. |
| Boolean | La representación String del valor booleano (“true” o “false”). |
| String | La String. |
| Matriz | La representación String del valor Array (mediante reglas de conversión estándar). |
| Objeto | La representación String de la cosa (mediante reglas de conversión estándar). |
| Nulo | Undefined. |
| Sin definir | Undefined. |
*Segundo argumento:*
Tiene que ser una expresión regex válida. Los tipos que no son cadenas se convierten en valores de tipo `String` mediante reglas de conversión estándar. En función del tipo, es posible que la cadena obtenida no sea una expresión regular válida. Si el argumento (convertido) no es un regex válido, el resultado es `Undefined`.
## regexp\$1replace(String, String, String)
Sustituye todos los segundos argumentos (expresiones regulares) que hay en el primer argumento por el tercer argumento. Hace referencia a los grupos de captura con "\$1". Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`regexp_replace("abcd", "bc", "x")` = "axd".
`regexp_replace("abcd", "b(.*)d", "$1")` = "ac".
**Primer argumento:**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | La representación String del valor Int. |
| Decimal | La representación String del valor Decimal. |
| Boolean | La representación String del valor booleano (“true” o “false”). |
| String | El valor de origen. |
| Matriz | La representación String del valor Array (mediante reglas de conversión estándar). |
| Objeto | La representación String de la cosa (mediante reglas de conversión estándar). |
| Nulo | Undefined. |
| Sin definir | Undefined. |
*Segundo argumento:*
Tiene que ser una expresión regex válida. Los tipos que no son cadenas se convierten en valores de tipo `String` mediante reglas de conversión estándar. En función del tipo, es posible que la cadena obtenida no sea una expresión regular válida. Si el argumento (convertido) no es una expresión regex válida, el resultado es `Undefined`.
*Tercer argumento:*
Debe ser una cadena de sustitución de regex válida. (Puede hacer referencia a grupos de capturas). Los tipos que no son cadenas se convierten en valores de tipo `String` mediante reglas de conversión estándar. Si el argumento (convertido) no es una cadena de sustitución de regex válida, el resultado es `Undefined`.
## regexp\$1substr(String, String)
Busca la primera coincidencia del segundo parámetro (regex) en el primer parámetro. Hace referencia a los grupos de captura con "\$1". Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`regexp_substr("hihihello", "hi")` = "hi"
`regexp_substr("hihihello", "(hi)*")` = "hihi"
**Primer argumento:**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | La representación String del valor Int. |
| Decimal | La representación String del valor Decimal. |
| Boolean | La representación String del valor booleano (“true” o “false”). |
| String | El argumento String. |
| Matriz | La representación String del valor Array (mediante reglas de conversión estándar). |
| Objeto | La representación String de la cosa (mediante reglas de conversión estándar). |
| Nulo | Undefined. |
| Sin definir | Undefined. |
*Segundo argumento:*
Tiene que ser una expresión regex válida. Los tipos que no son cadenas se convierten en valores de tipo `String` mediante reglas de conversión estándar. En función del tipo, es posible que la cadena obtenida no sea una expresión regular válida. Si el argumento (convertido) no es una expresión regex válida, el resultado es `Undefined`.
## remainder(Decimal, Decimal)
Devuelve el resto de la división del primer argumento por el segundo argumento. Es igual que [mod(Decimal, Decimal)](#iot-func-mod). También puede utilizar "%" como un operador infijo para la misma funcionalidad modulo. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `remainder(8, 3)` = 2.
****
| Operando izquierdo | Operando derecho | Output |
| --- | --- | --- |
| Int | Int | Int, el primer y el segundo argumento en los que quiere ejecutar la función modulo. |
| Int/Decimal | Int/Decimal | Decimal, el primer argumento y el segundo operando para los que quiere ejecutar la función modulo. |
| String/Int/Decimal | String/Int/Decimal | Si todas las cadenas se convierten en decimales, la función modulo se ejecuta en el primer y el segundo argumento. De lo contrario, Undefined. |
| Otro valor | Otro valor | Undefined. |
## replace(Cadena, Cadena, Cadena)
Reemplaza todas las instancias del segundo argumento que hay en el primer argumento por el tercer argumento. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`replace("abcd", "bc", "x")` = `"axd"`.
`replace("abcdabcd", "b", "x")` = `"axcdaxcd"`.
**Todos los argumentos**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | La representación String del valor Int. |
| Decimal | La representación String del valor Decimal. |
| Boolean | La representación String del valor booleano (“true” o “false”). |
| String | El valor de origen. |
| Matriz | La representación String del valor Array (mediante reglas de conversión estándar). |
| Objeto | La representación String de la cosa (mediante reglas de conversión estándar). |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## rpad(String, Int)
Devuelve el argumento de cadena, rellenado en el lado derecho con el número de espacios especificado en el segundo argumento. El argumento `Int` debe estar comprendido entre 0 y 1000. Si el valor proporcionado se encuentra fuera de este rango válido, el argumento se establece en el valor válido más cercano (0 o 1000). Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`rpad("hello", 2)` = "`hello `".
`rpad(1, 3)` = "`1 `".
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | Int | El valor String se rellena en el lado derecho con un número de espacios igual al valor Int proporcionado. |
| String | Decimal | El argumento Decimal se redondea al valor Int inferior más cercano y la cadena se rellena en el lado derecho con una serie de espacios igual al valor Int proporcionado. |
| String | String | El segundo argumento se convierte en un valor Decimal que se redondea al valor Int inferior más cercano. El valor String se rellena en el lado derecho con un número de espacios igual al valor Int. |
| Otro valor | Int/Decimal/String | El primer valor se convierte en un valor de tipo String mediante las conversiones estándar y, a continuación, se aplica la función rpad a dicho valor String. Si no se puede convertir, el resultado es Undefined. |
| Cualquier valor | Otro valor | Undefined. |
## round(Decimal)
Redondea el valor `Decimal` indicado al valor `Int` más cercano. Si el valor `Decimal` está a la misma distancia de dos valores `Int`, (p. ej., 0.5), el valor `Decimal` se redondea al valor superior. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `Round(1.2)` = 1.
`Round(1.5)` = 2.
`Round(1.7)` = 2.
`Round(-1.1)` = -1.
`Round(-1.5)` = -2.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | El argumento. |
| Decimal | El valor Decimal se redondea al valor Int inferior más cercano. |
| String | El valor Decimal se redondea al valor Int inferior más cercano. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Otro valor | Undefined. |
## rtrim(String)
Elimina todos los espacios en blanco del final (tabuladores y espacios) del valor `String` proporcionado. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`rtrim(" h i ")` = " h i"
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | La representación String del valor Int. |
| Decimal | La representación String del valor Decimal. |
| Boolean | La representación String del valor booleano (“true” o “false”). |
| Matriz | La representación String del valor Array (mediante reglas de conversión estándar). |
| Objeto | La representación String de la cosa (mediante reglas de conversión estándar). |
| Nulo | Undefined. |
| Sin definir | Undefined |
## sign(Decimal)
Devuelve el signo del número especificado. Cuando el signo del argumento es positivo, se devuelve 1. Cuando el signo del argumento es negativo, se devuelve -1. Si el argumento es 0, se devuelve 0. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`sign(-7)` = -1.
`sign(0)` = 0.
`sign(13)` = 1.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, el signo del valor Int. |
| Decimal | Int, el signo del valor Decimal. |
| String | Int, el signo del valor Decimal. La cadena se convierte en un valor Decimal y se devuelve el signo del valor Decimal. Si el valor String no se puede convertir en un valor Decimal, el resultado es Undefined. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores. |
| Otro valor | Undefined. |
## sin(Decimal)
Devuelve el seno de un número en radianes. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `sin(0)` = 0.0
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), el seno del argumento. |
| Decimal | Decimal (con doble precisión), el seno del argumento. |
| Boolean | Undefined. |
| String | Decimal (con doble precisión), el seno del argumento. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Undefined | Undefined. |
## sinh(Decimal)
Devuelve el seno hiperbólico de un número. Los valores `Decimal` se redondean con doble precisión antes de la aplicación de la función. El resultado es un valor `Decimal` de doble precisión. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `sinh(2.3)` = 4.936961805545957
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión); el seno hiperbólico del argumento. |
| Decimal | Decimal (con doble precisión); el seno hiperbólico del argumento. |
| Boolean | Undefined. |
| String | Decimal (con doble precisión); el seno hiperbólico del argumento. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## sourceip()
Recupera la dirección IP de un dispositivo o del enrutador que se conecta a él. Si el dispositivo está conectado directamente a internet, la función devolverá la dirección IP de origen del dispositivo. Si el dispositivo está conectado a un enrutador que se conecta a internet, la función devolverá la dirección IP de origen del enrutador. Es compatible con la versión SQL 2016-03-23. `sourceip()` no toma ningún parámetro.
**importante**
La dirección IP de origen público de un dispositivo suele ser la dirección IP de la última puerta de enlace de traducción de direcciones de red (NAT), como el enrutador o el módem de cable del proveedor de servicios de internet.
Ejemplos:
`sourceip()="192.158.1.38"`
`sourceip()="1.102.103.104"`
`sourceip()="2001:db8:ff00::12ab:34cd"`
Ejemplo de SQL:
`SELECT *, sourceip() as deviceIp FROM 'some/topic'`
Ejemplos de cómo utilizar la función sourceip () en las acciones de las AWS IoT Core reglas:
**Ejemplo 1**
El siguiente ejemplo muestra cómo llamar a la función () como [plantilla de sustitución](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) en una acción de [DynamoDB](https://docs.aws.amazon.com//iot/latest/developerguide/dynamodb-rule-action.html).
```
{
"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"
}
}
]
}
}
```
**Ejemplo 2**
El siguiente ejemplo muestra cómo añadir la función sourceip() como propiedad de usuario de MQTT mediante [plantillas de sustitución](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html).
```
{
"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()}"
}
]
}
}
}
]
}
}
```
Puede recuperar la dirección IP de origen de los mensajes que se transmiten a AWS IoT Core las reglas desde las rutas Message Broker y [Basic Ingest](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html). También puede recuperar la IP de origen de ambos IPv4 IPv6 mensajes. La IP de origen se mostrará de la siguiente manera:
IPv6: `yyyy:yyyy:yyyy::yyyy:yyyy`
IPv4: `xxx.xxx.xxx.xxx`
**nota**
La IP de origen original no se transferirá a través de la [acción Republicar](republish-rule-action.md).
## substring(String, Int[, Int])
Espera un valor `String` seguido de uno o dos valores `Int`. Para un argumento `String` y un único argumento `Int`, esta función devuelve la subcadena del argumento `String` proporcionado que proviene del índice `Int` (de base 0 incluido) suministrado al final del argumento `String`. Para un argumento `String` y dos argumentos `Int`, esta función devuelve la subcadena del argumento `String` proporcionado que proviene del primer argumento de índice `Int` (de base 0 incluido) en el segundo argumento de índice `Int` (de base 0 no incluido). Los índices inferiores a cero se establecen en cero. Los índices superiores a la longitud de `String` se establecen en la longitud de `String`. Para la versión de tres argumentos, si el primer índice es superior (o igual) al segundo índice, el resultado es el valor `String` vacío.
Si los argumentos proporcionados no son (*String*,*Int*) o (*String*,*Int*,*Int*), las conversiones estándar se aplican a los argumentos para intentar convertirlos en los tipos correctos. Si no es posible convertirlos, el resultado de la función será `Undefined`. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`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\$1version()
Devuelve la versión de SQL especificada en esta regla. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`sql_version()` = "2016-03-23"
## sqrt(Decimal)
Devuelve la raíz cuadrada de un número. Los argumentos `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `sqrt(9)` = 3,0.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | La raíz cuadrada del argumento. |
| Decimal | La raíz cuadrada del argumento. |
| Boolean | Undefined. |
| String | La raíz cuadrada del argumento. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## startswith(String, String)
Devuelve `Boolean`, si el primer argumento de cadena comienza con el segundo argumento de cadena. Si alguno de los argumentos es `Null` o `Undefined`, el resultado es `Undefined`. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`startswith("ranger","ran")` = true
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | String | Si la primera cadena comienza con la segunda cadena. |
| Otro valor | Otro valor | Ambos argumentos se convierten en cadenas con las reglas de conversión estándar. Devuelve verdadero si la primera cadena comienza con la segunda cadena. Si alguno de los argumentos es Null o Undefined, el resultado es Undefined. |
## tan(Decimal)
Devuelve la tangente de un número en radianes. Los valores `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `tan(3)` = -0.1425465430742778
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), la tangente del argumento. |
| Decimal | Decimal (con doble precisión), la tangente del argumento. |
| Boolean | Undefined. |
| String | Decimal (con doble precisión), la tangente del argumento. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## tanh(Decimal)
Devuelve la tangente hiperbólica de un número en radianes. Los valores `Decimal` se redondean con doble precisión antes de la aplicación de la función. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `tanh(2.3)` = 0.9800963962661914
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (con doble precisión), la tangente hiperbólica del argumento. |
| Decimal | Decimal (con doble precisión), la tangente hiperbólica del argumento. |
| Boolean | Undefined. |
| String | Decimal (con doble precisión), la tangente hiperbólica del argumento. Si la cadena no se puede convertir en un valor Decimal, el resultado es Undefined. |
| Matriz | Undefined. |
| Objeto | Undefined. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## time\$1to\$1epoch(String, String)
Utilice la función `time_to_epoch` para convertir una cadena de marca temporal en un número de milisegundos en el formato de tiempo Unix. Es compatible con la versión SQL 2016-03-23 y versiones posteriores. Para convertir milisegundos en una cadena de marca temporal formateada, consulte [parse\$1time(String, Long[, String])](#iot-sql-function-parse-time).
La función `time_to_epoch` espera los argumentos siguientes:
timestamp
(String) La cadena de marca temporal que se va a convertir a milisegundos desde tiempo Unix. Si la cadena de marca temporal no especifica una zona horaria, la función utiliza la zona horaria UTC.
pattern
(Cadena) Un date/time patrón que sigue los [formatos de JDK11 tiempo](http://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
Ejemplos:
`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()
Devuelve la marca de tiempo actual en milisegundos a partir de las 00:00:00 (hora universal coordinada) del jueves 1 de enero de 1970, según lo observado por el motor de reglas. AWS IoT Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo: `timestamp()` = `1481825251155`
## topic(Decimal)
Devuelve el tema al que se ha enviado el mensaje que activó la regla. Si no se especifica ningún parámetro, se devuelve todo el tema. El parámetro `Decimal` se utiliza para especificar un segmento de tema concreto. 1 designa el primer segmento. Para el tema `foo/bar/baz`, topic(1) devuelve `foo`, topic(2) devuelve `bar` y así sucesivamente. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`topic()` = "things/myThings/thingOne"
`topic(1)` = "things"
Cuando se usa [Basic Ingest](iot-basic-ingest.md), el prefijo inicial del tema (`$aws/rules/rule-name`) no está disponible para la función topic(). Por ejemplo, con el tema:
`$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`
`topic()` = "Buildings/Building5/Floor2/Room201/Lights"
`topic(3)` = "Floor2"
## traceid()
Devuelve el ID de seguimiento (UUID) del mensaje MQTT o `Undefined` si el mensaje no se ha enviado por MQTT. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`traceid() ` = "12345678-1234-1234-1234-123456789012"
## transform(String, Object, Array)
Devuelve una matriz de objetos que contiene el resultado de la transformación especificada del parámetro `Object` en el parámetro `Array`.
Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
Cadena
El modo de transformación que se debe utilizar. Consulte la siguiente tabla para ver los modos de transformación compatibles y cómo crean el `Result` a partir de los parámetros `Object` y `Array`.
Objeto
Un objeto que contiene los atributos que se van a aplicar a cada elemento de la `Array`.
Matriz
Una matriz de objetos a los que se aplican los atributos de `Object`.
Cada objeto de esta matriz corresponde a un objeto de la respuesta de la función. Cada objeto de la respuesta de la función contiene los atributos presentes en el objeto original y los atributos proporcionados por `Object` con arreglo al modo de transformación especificado en `String`.
| Parámetro `String` | Parámetro `Object` | Parámetro `Array` | Resultado |
| --- | --- | --- | --- |
| `enrichArray` | Objeto | Matriz de objetos | Una matriz de objetos en la que cada objeto contiene los atributos de un elemento del parámetro `Array` y los atributos del parámetro `Object`. |
| Cualquier otro valor | Cualquier valor | Cualquier valor | Sin definir |
**nota**
La matriz devuelta por esta función está limitada a 128 KiB.
### Ejemplo 1 de la función de transformación
En este ejemplo se muestra cómo la función **transform()** produce una matriz única de objetos a partir de un objeto de datos y una matriz.
En este ejemplo, se publica el siguiente mensaje en el tema `A/B` de MQTT.
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Esta instrucción SQL para una acción de regla temática utiliza la función **transform()** con un valor de `String` de `enrichArray`. En este ejemplo, `Object` es la propiedad `attributes` de la carga del mensaje y `Array` es la matriz `values`, que contiene tres objetos.
```
select value transform("enrichArray", attributes, values) from 'A/B'
```
Al recibir la carga del mensaje, la instrucción SQL se evalúa en la siguiente respuesta.
```
[
{
"a": 3,
"data1": 1,
"data2": 2
},
{
"b": 4,
"data1": 1,
"data2": 2
},
{
"c": 5,
"data1": 1,
"data2": 2
}
]
```
### Ejemplo 2 de la función de transformación
En este ejemplo se muestra cómo la función **transform()** puede usar valores literales para incluir y cambiar el nombre de los atributos individuales de la carga del mensaje.
En este ejemplo, se publica el siguiente mensaje en el tema `A/B` de MQTT. Es el mismo mensaje que se usó en [Ejemplo 1 de la función de transformación](#iot-func-transform-example1).
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Esta instrucción SQL para una acción de regla temática utiliza la función **transform()** con un valor de `String` de `enrichArray`. El `Object` de la función **transform()** tiene un único atributo llamado `key` con el valor de `attributes.data1` en la carga del mensaje y `Array` es la matriz `values`, que contiene los mismos tres objetos utilizados en el ejemplo anterior.
```
select value transform("enrichArray", {"key": attributes.data1}, values) from 'A/B'
```
Al recibir la carga del mensaje, esta instrucción SQL se evalúa en la siguiente respuesta. Observe cómo la propiedad `data1` se nombra `key` en la respuesta.
```
[
{
"a": 3,
"key": 1
},
{
"b": 4,
"key": 1
},
{
"c": 5,
"key": 1
}
]
```
### Ejemplo 3 de la función de transformación
En este ejemplo se muestra cómo se puede utilizar la función **transform()** en las cláusulas SELECT anidadas para seleccionar varios atributos y crear nuevos objetos para su posterior procesamiento.
En este ejemplo, se publica el siguiente mensaje en el tema `A/B` de MQTT.
```
{
"data1": "example",
"data2": {
"a": "first attribute",
"b": "second attribute",
"c": [
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false
}
]
}
}
```
El `Object` para esta función de transformación es el objeto devuelto por la instrucción SELECT, que contiene los elementos `a` y `b` de la cosa `data2` del mensaje. El parámetro `Array` consta de los dos objetos de la matriz `data2.c` del mensaje original.
```
select value transform('enrichArray', (select a, b from data2), (select value c from data2)) from 'A/B'
```
Con el mensaje anterior, la instrucción SQL se evalúa en la siguiente respuesta.
```
[
{
"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"
}
]
```
La matriz devuelta en esta respuesta podría usarse con las acciones de la regla temática compatibles con `batchMode`.
## trim(String)
Elimina todos los espacios en blanco del principio y del final del valor `String` proporcionado. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplo:
`Trim(" hi ") ` = "hi"
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | La representación String de Int con todos los espacios en blanco del principio y del final suprimidos. |
| Decimal | La representación String de Decimal con todos los espacios en blanco del principio y del final suprimidos. |
| Boolean | La representación String de Boolean ("true" o "false") con todos los espacios en blanco del principio y del final suprimidos. |
| String | El argumento String con todos los espacios en blanco del principio y del final suprimidos. |
| Matriz | La representación String del valor Array mediante reglas de conversión estándar. |
| Objeto | La representación String de la cosa mediante reglas de conversión estándar. |
| Nulo | Undefined. |
| Sin definir | Undefined. |
## trunc(Decimal, Int)
Trunca el primer argumento según el número del valor `Decimal` especificado por el segundo argumento. Si el segundo argumento es inferior a cero, se establece en cero. Si el segundo argumento es superior a 34, se establece en 34. Los ceros del final se eliminan del resultado. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`trunc(2.3, 0)` = 2.
`trunc(2.3123, 2)` = 2.31.
`trunc(2.888, 2)` = 2,88.
`trunc(2.00, 5)` = 2.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| Int | Int | El valor de origen. |
| Int/Decimal | Int/Decimal | El primer argumento se trunca en la longitud indicada por el segundo argumento. Si el segundo argumento no es un valor Int, se redondea al valor Int inferior más cercano. |
| Int/Decimal/String | Int/Decimal | El primer argumento se trunca en la longitud indicada por el segundo argumento. Si el segundo argumento no es un valor Int, se redondea al valor Int inferior más cercano. Los valores de tipo String se convierten en valores de tipo Decimal. Si se produce un error en la conversión de cadena, el resultado obtenido es Undefined. |
| Otro valor | | Undefined. |
## upper(String)
Muestra la versión en mayúsculas del valor `String` indicado. Los argumentos que no sean `String` se convierten en `String` mediante las reglas de conversión estándar. Es compatible con la versión 2015-10-08 de SQL y versiones posteriores.
Ejemplos:
`upper("hello")` = "HELLO"
`upper(["hello"])` = "[\$1"HELLO\$1"]"
# Literales
Puede especificar directamente objetos literales en las cláusulas SELECT y WHERE de su regla SQL, lo que puede ser útil para pasar información.
**nota**
Los literales solo están disponibles cuando se utiliza SQL versión 2016-03-23 o versiones posteriores.
Se utiliza una sintaxis de objeto JSON (pares clave-valor separados con comas, donde las claves son cadenas y los valores son de tipo JSON escritos entre llaves \$1\$1). Por ejemplo:
Carga de entrada publicada en el tema `topic/subtopic`: `{"lat_long": [47.606,-122.332]}`
Instrucción SQL: `SELECT {'latitude': get(lat_long, 0),'longitude':get(lat_long, 1)} as lat_long FROM 'topic/subtopic'`
La carga de salida obtenida sería: `{"lat_long":{"latitude":47.606,"longitude":-122.332}}`.
También puede especificar directamente matrices en las cláusulas SELECT y WHERE de su regla SQL, lo que le permite agrupar información. Se utiliza una sintaxis JSON (elementos separados con comas entre corchetes [] para crear un literal de Array). Por ejemplo:
Carga de entrada publicada en el tema `topic/subtopic`: `{"lat": 47.696, "long": -122.332}`
Instrucción SQL: `SELECT [lat,long] as lat_long FROM 'topic/subtopic'`
La carga de salida obtenida sería: `{"lat_long": [47.606,-122.332]}`.
# Instrucciones case
Las instrucciones case se pueden utilizar para ejecutar bifurcaciones, como una instrucción switch.
Sintaxis:
```
CASE v WHEN t[1] THEN r[1]
WHEN t[2] THEN r[2] ...
WHEN t[n] THEN r[n]
ELSE r[e] END
```
La expresión *`v`* se evalúa y se compara con el valor *`t[i]`* de todas las cláusulas `WHEN`. Si se encuentra una coincidencia, la expresión *`r[i]`* correspondiente se convierte en el resultado de la instrucción `CASE`. Las cláusulas `WHEN` se evalúan en orden, de modo que si hay más de una cláusula coincidente, el resultado de la primera cláusula coincidente se convierte en el resultado de la instrucción `CASE`. Si no hay coincidencias, el resultado es *`r[e]`* de la cláusula `ELSE`. Si no hay ninguna coincidencia ni cláusula `ELSE`, el resultado es `Undefined`.
Las instrucciones `CASE` necesitan como mínimo una cláusula `WHEN`. Una cláusula `ELSE` es opcional.
Por ejemplo:
Carga de entrada publicada en el tema `topic/subtopic`:
```
{
"color":"yellow"
}
```
Instrucción SQL:
```
SELECT CASE color
WHEN 'green' THEN 'go'
WHEN 'yellow' THEN 'caution'
WHEN 'red' THEN 'stop'
ELSE 'you are not at a stop light' END as instructions
FROM 'topic/subtopic'
```
La carga de salida obtenida sería:
```
{
"instructions":"caution"
}
```
**nota**
Si *`v`* es `Undefined`, el resultado de la instrucción case es `Undefined`.
# Extensiones JSON
Puede utilizar las extensiones siguientes de la sintaxis ANSI SQL para facilitar el trabajo con objetos JSON anidados.
Operador “.”
Este operador accede a los miembros de los objetos JSON incrustados y funciona de forma idéntica a ANSI SQL y. JavaScript Por ejemplo:
```
SELECT foo.bar AS bar.baz FROM 'topic/subtopic'
```
selecciona el valor de la propiedad `bar` de la cosa `foo` de la carga del siguiente mensaje enviado al tema `topic/subtopic`.
```
{
"foo": {
"bar": "RED",
"bar1": "GREEN",
"bar2": "BLUE"
}
}
```
Si el nombre de una propiedad JSON incluye un guion o caracteres numéricos, la notación “punto” no funcionará. En su lugar, debe utilizar la [función get](iot-sql-functions.md#iot-sql-function-get) para extraer el valor de la propiedad.
En este ejemplo, se envía el siguiente mensaje al tema `iot/rules`.
```
{
"mydata": {
"item2": {
"0": {
"my-key": "myValue"
}
}
}
}
```
Normalmente, el valor de `my-key` se identificaría como en esta consulta.
```
SELECT * from iot/rules WHERE mydata.item2.0.my-key= "myValue"
```
Sin embargo, dado que el nombre de la propiedad `my-key` contiene un guion y `item2` un carácter numérico, se debe utilizar la [función get](iot-sql-functions.md#iot-sql-function-get), tal como se muestra en la siguiente consulta.
```
SELECT * from 'iot/rules' WHERE get(get(get(mydata,"item2"),"0"),"my-key") = "myValue"
```
Operador `*`
Funciona igual que el comodín `*` en ANSI SQL. Solo se utiliza en la cláusula SELECT y crea un objeto JSON nuevo que contiene los datos del mensaje. Si la carga del mensaje no tiene el formato JSON, `*` devuelve toda la carga del mensaje como bytes sin procesar. Por ejemplo:
```
SELECT * FROM 'topic/subtopic'
```
**Aplicación de una función a un valor de atributo**
A continuación, se muestra un ejemplo de carga JSON que podría publicar un dispositivo:
```
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
```
En el ejemplo siguiente se aplica una función a un valor de atributo de una carga JSON:
```
SELECT temp, md5(deviceid) AS hashed_id FROM topic/#
```
El resultado de esta consulta es el objeto JSON siguiente:
```
{
"temp": 54.98,
"hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"
}
```
# Plantillas de sustitución
Puedes usar una plantilla de sustitución para aumentar los datos JSON devueltos cuando se activa una regla y AWS IoT realiza una acción. La sintaxis de una plantilla de sustitución es `${` *expresión*`}`, donde *expresión* puede ser cualquier expresión admitida AWS IoT en las cláusulas SELECT, WHERE y[AWS IoT acciones de reglas](iot-rule-actions.md). Esta expresión se puede conectar a un campo de acción de una regla, lo que le permite configurar dinámicamente una acción. En efecto, esta función sustituye a una parte de información de una acción. Esto incluye funciones, operadores e información presente en la carga del mensaje original.
**importante**
Dado que las expresiones en plantillas de sustitución se evalúan por separado de la declaración “SELECT...”, no se puede hacer referencia a un alias creado con la cláusula AS. Solo puede hacer referencia a la información presente en la carga, las [funciones](iot-sql-functions.md) y los [operadores](iot-sql-operators.md) originales.
Para obtener más información acerca de las expresiones admitidas, consulte [AWS IoT Referencia SQL](iot-sql-reference.md).
Las siguientes acciones de las reglas admiten plantillas de sustitución. Cada acción admite diferentes campos que se pueden sustituir.
+ [Apache Kafka](apache-kafka-rule-action.md)
+ [CloudWatch alarmas](cloudwatch-alarms-rule-action.md)
+ [CloudWatch Registros](cloudwatch-logs-rule-action.md)
+ [CloudWatch métricas](cloudwatch-metrics-rule-action.md)
+ [DynamoDB](dynamodb-rule-action.md)
+ [Dinamo DBv2](dynamodb-v2-rule-action.md)
+ [Elasticsearch](elasticsearch-rule-action.md)
+ [HTTP](https-rule-action.md)
+ [AWS IoT Events](iotevents-rule-action.md)
+ [AWS IoT SiteWise](iotsitewise-rule-action.md)
+ [Kinesis Data Streams](kinesis-rule-action.md)
+ [Firehose](kinesis-firehose-rule-action.md)
+ [Lambda](lambda-rule-action.md)
+ [Ubicación](location-rule-action.md)
+ [OpenSearch](opensearch-rule-action.md)
+ [Volver a publicar](republish-rule-action.md)
+ [S3](s3-rule-action.md)
+ [SNS](sns-rule-action.md)
+ [SQS](sqs-rule-action.md)
+ [Step Functions](stepfunctions-rule-action.md)
+ [Timestream](timestream-rule-action.md)
Las plantillas de sustitución aparecen en los parámetros de acción dentro de una regla:
```
{
"sql": "SELECT *, timestamp() AS timestamp FROM 'my/iot/topic'",
"ruleDisabled": false,
"actions": [{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
```
Si esta regla se activa mediante el siguiente JSON publicado en `my/iot/topic`:
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
}
}
```
A continuación, esta regla publica el siguiente JSON en`my/iot/topic/republish`, que AWS IoT sustituye a`${topic()}/republish`:
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
},
"timestamp": 1579637878451
}
```
# Consultas de objetos anidados
Puede utilizar cláusulas SELECT anidadas para consultar atributos dentro de matrices y objetos JSON internos. Es compatible con la versión SQL 2016-03-23 y versiones posteriores.
Considere el siguiente mensaje MQTT:
```
{
"e": [
{ "n": "temperature", "u": "Cel", "t": 1234, "v": 22.5 },
{ "n": "light", "u": "lm", "t": 1235, "v": 135 },
{ "n": "acidity", "u": "pH", "t": 1235, "v": 7 }
]
}
```
**Example**
Puede convertir valores en una nueva matriz con la siguiente regla.
```
SELECT (SELECT VALUE n FROM e) as sensors FROM 'my/topic'
```
La regla generará la salida siguiente.
```
{
"sensors": [
"temperature",
"light",
"acidity"
]
}
```
**Example**
Usando el mismo mensaje MQTT, también puede consultar un valor específico dentro de un objeto anidado con la siguiente regla.
```
SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'
```
La regla generará la salida siguiente.
```
{
"temperature": [
{
"v": 22.5
}
]
}
```
**Example**
También puede aplanar la salida con una regla más complicada.
```
SELECT get((SELECT v FROM e WHERE n = 'temperature'), 0).v as temperature FROM 'topic'
```
La regla generará la salida siguiente.
```
{
"temperature": 22.5
}
```
# Uso de las cargas binarias
Para tratar la carga del mensaje como datos binarios sin procesar (en lugar de como un objeto JSON), puede utilizar el operador \$1 para hacer referencia a ella en una cláusula SELECT.
**Topics**
+ [Ejemplos de carga binaria](#binary-payloads-examples)
+ [Descodificación de cargas de mensajes de protobuf](#binary-payloads-protobuf)
## Ejemplos de carga binaria
Si utiliza \$1 para hacer referencia a la carga del mensaje como datos binarios sin procesar, puede añadir datos a la regla. Si tiene una carga vacía o JSON, a la carga resultante se le pueden agregar datos mediante la regla. A continuación se muestran ejemplos de cláusulas `SELECT` admitidas.
+ Puede usar las siguientes cláusulas `SELECT` con solo un \$1 para cargas binarias.
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ También puede agregar datos y utilizar las siguientes cláusulas `SELECT`.
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ También puede usar estas cláusulas `SELECT` con cargas binarias.
+ Lo siguiente hace referencia a `device_type` en la cláusula WHERE.
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ También se admite lo siguiente.
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
Las siguientes acciones de regla no admiten cargas binarias, por lo que debe descodificarlas.
+ Algunas acciones de regla no admiten la entrada de carga binaria, como la [acción Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule), por lo que debe descodificar las cargas binarias. La acción de regla Lambda puede recibir datos binarios si está codificada en base64 y en una carga JSON. Puede hacer esto cambiando la regla a lo siguiente.
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ La instrucción SQL no admite cadenas como entrada. Para convertir una entrada de cadena en JSON, puede ejecutar el siguiente comando.
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## Descodificación de cargas de mensajes de protobuf
Los [búferes de protocolo (protobuf)](https://developers.google.com/protocol-buffers) son un formato de datos de código abierto que se utiliza para serializar datos estructurados en un formato binario compacto. Se utiliza para transmitir datos a través de redes o para almacenarlos en archivos. Protobuf le permite enviar datos en paquetes pequeños y a un ritmo más rápido que otros formatos de mensajería. AWS IoT Core Las reglas admiten protobuf al proporcionar la función SQL [decode (value, decodingScheme),](iot-sql-functions.md#iot-sql-decode-base64) que permite decodificar las cargas útiles de mensajes codificadas por protobuf en formato JSON y enrutarlas a los servicios descendentes. En esta sección se detalla el proceso de configuración de la decodificación protobuf en Rules. step-by-step AWS IoT Core
**Topics**
+ [Requisitos previos](#binary-payloads-protobuf-prerequisites)
+ [Crear archivos descriptores](#binary-payloads-protobuf-descriptor-steps)
+ [Cargar los archivos descriptores en un bucket de S3](#binary-payloads-protobuf-s3-steps)
+ [Configurar la descodificación protobuf en las reglas](#binary-payloads-protobuf-steps)
+ [Limitaciones](#binary-payloads-protobuf-limitations)
+ [Prácticas recomendadas](#binary-payloads-protobuf-bestpractices)
### Requisitos previos
+ Conocimientos básicos de los [búferes de protocolo (protobuf)](https://developers.google.com/protocol-buffers)
+ Los [archivos `.proto`](https://developers.google.com/protocol-buffers/docs/proto3) que definen los tipos de mensajes y las dependencias relacionadas
+ Instalación del [compilador Protobuf (protoc)](https://github.com/protocolbuffers/protobuf/releases) en su sistema
### Crear archivos descriptores
Si ya dispone de los archivos descriptores, puede omitir este paso. Un archivo descriptor (`.desc`) es una versión compilada de un archivo `.proto`, que es un archivo de texto que define las estructuras de datos y los tipos de mensajes que se utilizarán en una serialización de protobuf. Para generar un archivo descriptor, debe definir un archivo `.proto` y usar el compilador [protoc](https://github.com/protocolbuffers/protobuf/releases) para compilarlo.
1. Crear archivos `.proto` que definan los tipos de mensajes. Un ejemplo de archivo `.proto` sería el siguiente:
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
En este archivo `.proto` de ejemplo, se utiliza la sintaxis proto3 y se define el tipo de mensaje `Person`. La definición del mensaje `Person` especifica tres campos (nombre, identificador y correo electrónico). Para obtener más información sobre los formatos de los mensajes de los archivos `.proto`, consulte la [Guía de lenguaje (proto3)](https://developers.google.com/protocol-buffers/docs/proto3).
1. Utilice el compilador [protoc](https://github.com/protocolbuffers/protobuf/releases) para compilar los archivos `.proto` y generar un archivo descriptor. Un ejemplo de comando para crear un archivo descriptor (`.desc`) puede ser el siguiente:
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
Este comando de ejemplo genera un archivo `.desc` descriptor que AWS IoT Core Rules puede usar para decodificar las cargas útiles de protobuf que se ajusten a la estructura de datos definida en. `.proto`
+ `--descriptor_set_out`
Especifica el nombre del archivo descriptor (`.desc`) que se debe generar.
+ `--proto_path`
Especifica las ubicaciones de los archivos `.proto` importados a los que hace referencia el archivo que se está compilando. Puede especificar la marca varias veces si tiene varios archivos `.proto` importados con ubicaciones diferentes.
+ `--include_imports`
Especifica que todos los archivos `.proto` importados también se deben compilar e incluir en el archivo descriptor `.desc`.
+ `.proto`
Especifica el nombre del archivo `.proto` que desea compilar.
Para obtener más información sobre la referencia protoc, consulte la [Referencia de la API](https://developers.google.com/protocol-buffers/docs/reference/overview).
### Cargar los archivos descriptores en un bucket de S3
Tras crear los archivos descriptores`.desc`, cárguelos en un bucket de Amazon S3 mediante la AWS API, el AWS SDK o el. `.desc` Consola de administración de AWS
**Consideraciones importantes**
+ Asegúrese de cargar los archivos descriptores en un bucket de Amazon S3 en el mismo Región de AWS lugar Cuenta de AWS en el que pretende configurar sus reglas.
+ Asegúrese de conceder AWS IoT Core acceso para leer el contenido `FileDescriptorSet` de S3. Si su bucket de S3 tiene el cifrado del servidor (SSE) desactivado o si el bucket de S3 está cifrado con claves administradas por Amazon S3 (SSE-S3), no se requieren configuraciones de políticas adicionales. Esto se puede lograr con la política de bucket de ejemplo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ Si su bucket de S3 está cifrado con una AWS Key Management Service clave (SSE-KMS), asegúrese de conceder AWS IoT Core permiso para usar la clave al acceder a su bucket de S3. Para ello, agregue esta instrucción a su política de claves:
```
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
### Configurar la descodificación protobuf en las reglas
Tras cargar los archivos descriptores en su bucket de Amazon S3, configure una [regla](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html) que pueda descodificar el formato de carga del mensaje protobuf mediante la función [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) de SQL. Puede encontrar una firma y un ejemplo detallados de la función en la función [decode(value, DecodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) de SQL de la *referencia de la SQL de AWS IoT *.
A continuación se muestra un ejemplo de expresión SQL que utiliza la función [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64):
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
En este ejemplo de expresión:
+ Utiliza la función [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) de SQL para descodificar la carga del mensaje binario a la que hace referencia `*`. Puede ser una carga binaria codificada por protobuf o una cadena JSON que representa una carga protobuf codificada en base64.
+ La carga del mensaje proporcionada se codifica con el tipo de mensaje `Person` definido en `PROTO_FILENAME.proto`.
+ El bucket de Amazon S3 llamado `BUCKET NAME` contiene el `FILENAME.desc` generado desde `PROTO_FILENAME.proto`.
Tras completar la configuración, publique un mensaje AWS IoT Core sobre el tema al que está suscrita la regla.
### Limitaciones
AWS IoT Core Las reglas admiten protobuf con las siguientes limitaciones:
+ No se admite la descodificación de cargas de mensajes de protobuf en [plantillas de sustitución](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html).
+ Al descodificar las cargas de los mensajes de protobuf, puede utilizar la [función de descodificación de SQL](iot-sql-functions.md#iot-sql-decode-base64) en una sola expresión SQL hasta dos veces.
+ El tamaño máximo de la carga de entrada es de 128 KiB (1 KiB = 1024 bytes), el tamaño máximo de la carga de salida es de 128 KiB y el tamaño máximo de un objeto `FileDescriptorSet` almacenado en un bucket de Amazon S3 es de 32 KiB.
+ No se admiten los buckets de Amazon S3 cifrados con cifrado SSE-C.
### Prácticas recomendadas
Estas son algunas prácticas recomendadas y consejos de solución de problemas.
+ Haga una copia de seguridad de sus archivos proto en el bucket de Amazon S3.
Se recomienda hacer copias de seguridad de los archivos proto en caso de que algo salga mal. Por ejemplo, si modifica incorrectamente los archivos proto sin copias de seguridad al ejecutar protoc, esto puede provocar problemas en su pila de producción. Existen varias formas de hacer copias de seguridad de los archivos en un bucket de Amazon S3. Por ejemplo, puede [utilizar el control de versiones en buckets de S3](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html). Para obtener más información sobre cómo hacer copias de seguridad de los archivos en los buckets de Amazon S3, consulte la *[Guía para desarrolladores de Amazon S3](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*.
+ Configure el AWS IoT registro para ver las entradas del registro.
Se recomienda configurar el AWS IoT registro para que puedas comprobar AWS IoT los registros de tu cuenta CloudWatch. Cuando la consulta SQL de una regla llama a una función externa, AWS IoT Core Rules genera una entrada de registro con un `eventType` de`FunctionExecution`, que contiene el campo del motivo, que le ayudará a solucionar errores. Los posibles errores incluyen un objeto de Amazon S3 no encontrado o un descriptor de archivo protobuf no válido. Para obtener más información sobre cómo configurar el registro de AWS IoT y ver las entradas de registro, consulte [Configurar el registro de AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html) y [Entradas del registro del motor de reglas](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec).
+ Actualice `FileDescriptorSet` con una clave de objeto nueva y actualice la clave de objeto en su regla.
Puede actualizar `FileDescriptorSet` cargando un archivo descriptor actualizado en su bucket de Amazon S3. Las actualizaciones de `FileDescriptorSet` pueden tardar hasta 15 minutos en reflejarse. Para evitar este retraso, se recomienda cargar las actualizaciones de `FileDescriptorSet` con una clave de objeto nueva y actualizar la clave de objeto en la regla.
# Versiones de SQL
El motor de AWS IoT reglas utiliza una sintaxis similar a la de SQL para seleccionar los datos de los mensajes MQTT. Las instrucciones SQL se interpretan según la versión de SQL especificada en la propiedad `awsIotSqlVersion` de un documento JSON que describe la regla. Para obtener más información acerca de la estructura de los documentos de reglas JSON, consulte [Creación de una regla](iot-create-rule.md). La `awsIotSqlVersion` propiedad le permite especificar qué versión del motor de reglas AWS IoT SQL desea utilizar. Cuando se implementa una nueva versión, puede continuar utilizando una versión anterior o cambiar la regla para utilizar la nueva versión. Las reglas actuales seguirán utilizando la versión con la que se crearon.
En el siguiente ejemplo de JSON se muestra cómo especificar la versión de SQL mediante la propiedad `awsIotSqlVersion`:
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
```
AWS IoT actualmente admite las siguientes versiones de SQL:
+ `2016-03-23`: la versión de SQL creada el 23/03/2016 (recomendada).
+ `2015-10-08`: la versión de SQL original creada el 08/10/2015.
+ `beta`: la versión beta de SQL más reciente. Esta versión podría introducir cambios bruscos en sus reglas.
## Novedades de la versión del motor de reglas SQL del 23/03/2016
+ Soluciones para seleccionar objetos JSON anidados.
+ Soluciones para consultas de matriz.
+ Compatibilidad con consultas dentro de objetos. Para obtener más información, consulte [Consultas de objetos anidados](iot-sql-nested-queries.md).
+ Compatibilidad con la generación de una matriz como objeto de nivel superior.
+ Adición de la función `encode(value, encodingScheme)`, que se puede aplicar en datos con formato JSON y no JSON. Para obtener más información, consulte la [función de codificación](iot-sql-functions.md#iot-sql-encode-payload).
### Generación de `Array` como objeto de nivel superior
Esta característica permite que una regla devuelva una matriz como objeto de nivel superior. Por ejemplo, si se recibe el mensaje MQTT siguiente:
```
{
"a": {"b":"c"},
"arr":[1,2,3,4]
}
```
Y la regla siguiente:
```
SELECT VALUE arr FROM 'topic'
```
La regla generará la salida siguiente.
```
[1,2,3,4]
```