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.
# 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]
```