As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# AWS IoT Referência SQL
Em AWS IoT, as regras são definidas usando uma sintaxe semelhante a SQL. As declarações do SQL são compostas por três tipos de cláusulas:
**SET**
(Opcional) Define variáveis que você pode reutilizar em todas as instruções SQL e modelos de substituição. Atribua valores às variáveis usando expressões. Faça referência a essas variáveis nas cláusulas SELECT e WHERE e nos modelos de substituição de ações.
A cláusula SET suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),,[Extensões JSON](iot-sql-json.md), [Variáveis](iot-sql-set.md#iot-sql-set-usage) e. [Consultas de objeto aninhado](iot-sql-nested-queries.md)
**SELECT**
(Obrigatório) Extrai informações da carga útil da mensagem de entrada e executa transformações nas informações. As mensagens a serem usadas são identificadas pelo [filtro de tópico](topics.md#topicfilters) especificado na cláusula FROM.
A cláusula SELECT oferece suporte a [Tipos de dados](iot-sql-data-types.md) [Operadores](iot-sql-operators.md) [Funções](iot-sql-functions.md)[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),,[Extensões JSON](iot-sql-json.md),[Modelos de substituição](iot-substitution-templates.md),, [Variáveis](iot-sql-set.md#iot-sql-set-usage)[Consultas de objeto aninhado](iot-sql-nested-queries.md), e. [Cargas binárias](binary-payloads.md)
**FROM**
O [filtro de tópicos](topics.md#topicfilters) de mensagens do MQTT que identifica as mensagens das quais extrair dados. A regra é ativada para cada mensagem enviada para um tópico MQTT que corresponda ao filtro de tópico especificado aqui. Obrigatório para regras que são ativadas por mensagens que passam pelo agente de mensagens. Opcional para regras que só são ativadas usando o atributo [Ingestão básica](iot-basic-ingest.md).
**WHERE**
(Opcional) Adiciona lógica condicional que determina se as ações especificadas por uma regra são executadas.
A cláusula WHERE suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),[Extensões JSON](iot-sql-json.md),, [Variáveis](iot-sql-set.md#iot-sql-set-usage) e. [Consultas de objeto aninhado](iot-sql-nested-queries.md)
Um exemplo de declaração do SQL é semelhante a:
```
SELECT color AS rgb FROM 'topic/subtopic' WHERE temperature > 50
```
Um exemplo de mensagem MQTT (também chamada de carga útil de entrada) é semelhante a:
```
{
"color":"red",
"temperature":100
}
```
Se essa mensagem for publicada no tópico `'topic/subtopic'`, a regra será acionada, e a declaração do SQL será avaliada. A declaração do SQL extrairá o valor da propriedade `color` se a propriedade `"temperature"` for superior a 50. A cláusula WHERE especifica a condição `temperature > 50`. A palavra-chave `AS` renomeia a propriedade `"color"` para `"rgb"`. O resultado (também chamado de *carga útil de saída*) é semelhante a:
```
{
"rgb":"red"
}
```
Esses dados são encaminhados para a ação da regra, que envia os dados para realizar mais processamento. Para saber mais sobre as ações de regra, consulte [AWS IoT ações de regras](iot-rule-actions.md).
**nota**
Atualmente, não há suporte para comentários na sintaxe AWS IoT SQL.
Nomes de atributos com espaços não podem ser usados como nomes de campo na instrução SQL. Embora a carga de entrada possa ter nomes de atributos com espaços, esses nomes não podem ser usados na instrução SQL. No entanto, eles serão passados para a carga de saída se você usar uma especificação de nome de campo curinga (\$1).
# Cláusula SELECT
A cláusula AWS IoT SELECT é essencialmente a mesma que a cláusula ANSI SQL SELECT, com algumas pequenas diferenças.
A cláusula SELECT suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),[Extensões JSON](iot-sql-json.md),, [Variáveis](iot-sql-set.md#iot-sql-set-usage)[Consultas de objeto aninhado](iot-sql-nested-queries.md), e. [Cargas binárias](binary-payloads.md)
Você pode usar a cláusula SELECT para extrair informações das mensagens MQTT recebidas. Você também pode usar `SELECT *` para recuperar toda a carga útil da mensagem recebida. Por exemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT * FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50}
```
Se a carga útil for um objeto JSON, você poderá fazer referência a chaves no objeto. A carga útil de saída contém o par de chave/valor. Por exemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT color FROM 'topic/subtopic'
Outgoing payload: {"color":"red"}
```
Você pode usar o teclado AS para renomear chaves. Por exemplo:
```
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"}
```
Você pode selecionar vários itens ao separá-los com uma vírgula. Por exemplo:
```
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}
```
Você pode selecionar vários itens incluindo '\$1' para adicionar itens à carga útil de entrada. Por exemplo:
```
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}
```
Você pode usar a palavra-chave `"VALUE"` para produzir cargas úteis de saída que não são objetos JSON. Com a versão SQL `2015-10-08`, você pode selecionar apenas um item. Com a versão `2016-03-23` do SQL ou posterior, você também pode selecionar uma matriz para saída como um objeto de nível superior.
**Example**
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT VALUE color FROM 'topic/subtopic'
Outgoing payload: "red"
```
Você pode usar a sintaxe `'.'` para analisar os objetos JSON aninhados na carga útil de entrada. Por exemplo:
```
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 obter informações sobre como usar nomes de objetos e propriedades JSON que incluem caracteres reservados, como números ou o caractere de hífen (menos), consulte [Extensões JSON](iot-sql-json.md)
Você pode usar funções (consulte [Funções](iot-sql-functions.md)) para transformar a carga útil de entrada. Você pode usar parênteses para agrupamento. Por exemplo:
```
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
A cláusula FROM inscreve sua regra em um [tópico](topics.md#topicnames) ou [filtro de tópicos](topics.md#topicfilters). Coloque o filtro de tópicos ou tópico entre aspas simples ('). A regra é acionada para cada mensagem enviada para um tópico MQTT que corresponda ao filtro de tópico especificado aqui. Você pode permite se inscrever em um grupo de tópicos semelhantes usando um filtro de tópicos.
**Exemplo:**
Carga útil de entrada publicada no tópico `'topic/subtopic'`: `{temperature: 50}`
Carga útil de entrada publicada no tópico `'topic/subtopic-2'`: `{temperature: 50}`
SQL: `"SELECT temperature AS t FROM 'topic/subtopic'"`.
A regra é inscrita em `'topic/subtopic'`, de modo que a carga útil de entrada é passada para a regra. A carga útil de saída, passada para as ações da regra, é: `{t: 50}`. A regra não está inscrita em `'topic/subtopic-2'`; portanto, a regra não é acionada para a mensagem publicada em `'topic/subtopic-2'`.
**Exemplo de curinga \$1:**
Você pode usar o caractere curinga "\$1" (com vários níveis) para corresponder a um ou mais elementos de caminho específicos:
Carga útil de entrada publicada no tópico `'topic/subtopic'`: `{temperature: 50}`.
Carga útil de entrada publicada no tópico `'topic/subtopic-2'`: `{temperature: 60}`.
Carga útil de entrada publicada no tópico `'topic/subtopic-3/details'`: `{temperature: 70}`.
Carga útil de entrada publicada no tópico `'topic-2/subtopic-x'`: `{temperature: 80}`.
SQL: `"SELECT temperature AS t FROM 'topic/#'"`.
A regra está inscrita em qualquer tópico que comece com`'topic'`, então é executada três vezes, enviando cargas de saída de (para tópico/subtópico), `{t: 50}` (para tópico/subtópico-2) e `{t: 60}` (para) para suas ações. `{t: 70}` topic/subtopic-3/details Se não estiver inscrito em `'topic-2/subtopic-x'`, a regra não será acionada para a mensagem `{temperature: 80}`.
**Exemplo de curinga \$1:**
Você pode usar o caractere curinga "\$1" (com nível único) para corresponder a qualquer elemento de caminho específico:
Carga útil de entrada publicada no tópico `'topic/subtopic'`: `{temperature: 50}`.
Carga útil de entrada publicada no tópico `'topic/subtopic-2'`: `{temperature: 60}`.
Carga útil de entrada publicada no tópico `'topic/subtopic-3/details'`: `{temperature: 70}`.
Carga útil de entrada publicada no tópico `'topic-2/subtopic-x'`: `{temperature: 80}`.
SQL: `"SELECT temperature AS t FROM 'topic/+'"`.
A regra é inscrita em todos os tópicos com dois elementos de caminho, em que o primeiro elemento é `'topic'`. A regra é executada para as mensagens enviadas para `'topic/subtopic'` e `'topic/subtopic-2'`, mas não `'topic/subtopic-3/details'` (tem mais níveis do que o filtro de tópicos) ou `'topic-2/subtopic-x'` (não começa com `topic`).
# Cláusula SET
Use a cláusula SET para definir variáveis que armazenam resultados de expressões. Você pode reutilizar essas variáveis nas cláusulas SELECT e WHERE e em modelos de substituição. Isso ajuda a evitar a duplicação de expressões complexas e a reduzir o número de chamadas de função em sua instrução SQL.
A cláusula SET suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),,[Extensões JSON](iot-sql-json.md), [Variáveis](#iot-sql-set-usage) e. [Consultas de objeto aninhado](iot-sql-nested-queries.md)
## Sintaxe da cláusula SET
A cláusula SET deve aparecer antes da cláusula SELECT em sua instrução SQL. Use a seguinte sintaxe:
```
SET @variable_name = expression [, @variable_name2 = expression2]
```
Regras de sintaxe:
+ Inicie os nomes das variáveis com `@`
+ Os nomes das variáveis podem conter letras, números e sublinhados
+ Os nomes das variáveis podem ter até 64 caracteres
+ Várias variáveis podem ser definidas em uma única cláusula SET, separadas por vírgulas
+ Cada variável só pode ser atribuída uma vez (as variáveis são imutáveis)
+ A palavra-chave SET só pode ser usada uma vez por instrução SQL
## Usando variáveis
Depois de definir as variáveis, você pode usá-las em:
+ Cláusulas SELECT
+ Cláusulas WHERE
+ Outras atribuições de variáveis SET
+ Modelos de substituição de ações
+ Modelos de substituição de ações de erro
+ Consultas SELECT aninhadas
+ Parâmetros de função (certos parâmetros, como parâmetros do RoLearn e parâmetros que alternam o modo de uma função semelhante a `transform("enrichArray", attributes, values)` que não suportam variáveis)
As variáveis são referenciadas usando a mesma `@variable_name` sintaxe usada na cláusula SET. Você também pode usar a sintaxe da extensão JSON para acessar propriedades de variáveis que contêm objetos, como. `@variable_name.property`
## Exemplos da cláusula SET
**Uso básico de variáveis**
O exemplo a seguir mostra uma carga publicada no tópico`device/data`: `{"temp_fahrenheit": 75, "humidity": 60}`
Declaração do SQL:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Carga útil de saída: `{"celsius": 23.89, "humidity": 60}`
**Acesse membros em objetos JSON incorporados**
O exemplo a seguir mostra uma carga publicada no tópico`device/data`: `{"device1": {"deviceId":"weather_sensor", "deviceData": {"sensors": {"temp_fahrenheit": 75, "humidity": 60}, "location": [47.606,-122.332]}}}`
Declaração do 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 de saída: `{"temp_fahrenheit":75,"humidity":60,"deviceId":"weather_sensor"}`
para obter mais informações sobre como trabalhar com extensões JSON, consulte [Extensões JSON](iot-sql-json.md)
**Evitando chamadas de função duplicadas**
As variáveis SET ajudam a evitar a duplicação de operações complexas de decodificação:
```
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
```
Sem as variáveis SET, você precisaria repetir a função de decodificação três vezes, o que excede os limites de chamada da função.
**Várias variáveis**
Você pode definir várias variáveis em uma única cláusula SET separando-as com vírgulas:
```
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
```
**Usando variáveis em modelos de substituição**
As variáveis também podem ser usadas em modelos de substituição de ações, permitindo que você reutilize valores computados nas ações da instrução SQL e da regra.
Declaração do SQL:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Configuração da ação:
```
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/testRuleRole",
"bucketName": "bucket",
"key": "temperature-data/${device_id}/temp-${@temp_celsius}C.json"
}
}
```
Neste exemplo, a variável SET `@temp_celsius` é usada em um modelo de substituição para construir o campo chave da ação S3.
**Uso de carga útil não JSON**
As variáveis SET não oferecem suporte direto a cargas não JSON, portanto, a carga deve ser codificada ou decodificada primeiro:
```
SET @encoded_payload = encode(*, 'base64')
SELECT @encoded_payload AS raw_data FROM 'device/binary'
```
para obter mais informações sobre como trabalhar com cargas não JSON, consulte [Como trabalhar com cargas úteis binárias](binary-payloads.md)
## Limites da cláusula SET
Os limites a seguir se aplicam às variáveis SET:
+ Máximo de 10 variáveis exclusivas por instrução SQL
+ Tamanho máximo do valor variável de 128 KiB (string JSON UTF-8 minificada)
+ Tamanho máximo do valor total de 128 KiB para todas as variáveis
+ Nomes de variáveis limitados a 64 caracteres
+ As variáveis podem aceitar cargas JSON diretamente como estão (cargas não JSON devem primeiro ser codificadas/decodificadas)
# Cláusula WHERE
A cláusula WHERE determina se as ações especificadas por uma regra são executadas. Se a cláusula WHERE for avaliada como verdadeira, as ações da regra serão executadas. Caso contrário, as ações da regra não serão executadas.
A cláusula WHERE suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),[Extensões JSON](iot-sql-json.md),, [Variáveis](iot-sql-set.md#iot-sql-set-usage) e. [Consultas de objeto aninhado](iot-sql-nested-queries.md)
**Exemplo:**
Carga útil de entrada publicada em `topic/subtopic`: `{"color":"red", "temperature":40}`.
SQL: `SELECT color AS my_color FROM 'topic/subtopic' WHERE temperature > 50 AND color <> 'red'`.
Nesse caso, a regra será acionada, mas as ações especificadas pela regra não serão executadas. Não haverá carga útil de saída.
Você pode usar funções e operadores na cláusula WHERE. No entanto, você não pode fazer referência a aliases criados com a palavra-chave AS no SELECT. A cláusula WHERE é avaliada primeiro para determinar se SELECT será avaliada.
**Exemplo com carga útil não JSON:**
Carga útil não JSON de entrada publicada em `tópico/subtópico`: `80`
SQL: ``SELECT decode(encode(*, 'base64'), 'base64') AS value FROM 'topic/subtopic' WHERE decode(encode(*, 'base64'), 'base64') > 50`
Nesse caso, a regra será acionada e as ações especificadas pela regra serão executadas. A carga útil de saída será transformada pela cláusula SELECT como uma carga JSON `{"value":80}`.
# Tipos de dados
O mecanismo de AWS IoT regras é compatível com todos os tipos de dados JSON.
**Tipos de dados compatíveis**
| Tipo | Significado |
| --- | --- |
| Int | Um discreto Int. 34 dígitos no máximo. |
| Decimal | Um `Decimal` com uma precisão de 34 dígitos, com um mínimo de magnitude não zero de 1E-999 e um máximo de magnitude de 9,999...E999. Algumas funções geram valores `Decimal` com precisão dupla em vez de precisão de 34 dígitos. Com o SQL V2 (23/03/2016), valores numéricos que são números inteiros, como `10.0`, são processados como um valor `Int` (`10`) em vez do valor `Decimal` esperado (`10.0`). Para processar de forma confiável valores numéricos inteiros como valores `Decimal`, use o SQL V1 (08/10/2015) para a instrução de consulta de regra. |
| Boolean | True ou False. |
| String | Uma string UTF-8. |
| Array | Uma série de valores que não precisam ter o mesmo tipo. |
| Object | Um valor JSON que consiste em uma chave e um valor. As chaves devem ser strings. Os valores podem ser de qualquer tipo. |
| Null | Null conforme definido pelo JSON. É um valor real que representa a ausência de um valor. Você pode criar explicitamente um valor Null usando a palavra-chave Null na declaração do SQL. Por exemplo: "SELECT NULL AS n FROM 'topic/subtopic'" |
| Undefined | Não é um valor. Não é explicitamente representável no JSON, exceto ao omitir o valor. Por exemplo, no objeto `{"foo": null}`, a chave "foo" gera NULL, mas a chave "bar" gera `Undefined`. Internamente, a linguagem SQL trata `Undefined` como um valor, mas não é representável no JSON; portanto, quando serializados para JSON, os resultados são `Undefined`. {"foo":null, "bar":undefined} é serializado para JSON como: {"foo":null} Da mesma forma, `Undefined` é convertido em uma string vazia quando serializado por conta própria. Funções chamadas com argumentos inválidos (por exemplo, tipos incorretos, número incorreto de argumentos, etc.) retornam `Undefined`. |
## Conversões
A tabela a seguir indica os resultados quando um valor de um tipo é convertido em outro tipo (quando um valor do tipo incorreto é dado a uma função). Por exemplo, se a função de valor absoluto "abs" (que espera um `Int` ou `Decimal`) for dado a `String`, ela tentará converter `String` em um `Decimal`, seguindo essas regras. Nesse caso, “abs ("-5,123")” é tratado como “abs(-5,123)”.
**nota**
Não há tentativa de conversões para `Array`, `Object`, `Null` ou `Undefined`.
**Para decimal**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Um Decimal sem ponto decimal. |
| Decimal | O valor de origem. |
| Boolean | Undefined. (Você pode explicitamente usar a função cast para transformar verdadeiro = 1,0, falso = 0,0.) |
| String | O mecanismo SQL tenta analisar a string como a. Decimal AWS IoT tenta analisar cadeias de caracteres que correspondam à expressão regular:. ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1 "0", "-1,2" e "5E-12" são exemplos de strings que são automaticamente convertidas em Decimals. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Null. |
| Não definido | Undefined. |
**Para int**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | O valor de origem. |
| Decimal | O valor de origem arredondado para o Int mais próximo. |
| Boolean | Undefined. (Você pode explicitamente usar a função cast para transformar verdadeiro = 1,0, falso = 0,0.) |
| String | O mecanismo SQL tenta analisar a string como a. Decimal AWS IoT tenta analisar cadeias de caracteres que correspondam à expressão regular:. ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1 “0", “-1.2", “5E-12" são todos exemplos de strings que são convertidas automaticamente em Decimal s. AWS IoT tenta converter o em a eDecimal, em seguida, trunca as casas decimais String para formar um. Decimal Int |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Null. |
| Não definido | Undefined. |
**Para Booleano**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Undefined. (Você pode explicitamente usar a função cast para transformar 0 = Falso, qualquer\$1valor\$1não\$1zero = Verdadeiro.) |
| Decimal | Undefined. (Você pode explicitamente usar a função cast para transformar 0 = Falso, qualquer\$1valor\$1não\$1zero = Verdadeiro.) |
| Boolean | O valor original. |
| String | "true" = Verdadeiro e "false" = Falso (não diferencia maiúsculas de minúsculas). Outros valores de string são Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
**Para string**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Uma representação de string do Int em notação padrão. |
| Decimal | Uma string representando o valor Decimal, possivelmente em notação científica. |
| Boolean | "true" ou "false". Todas as letras minúsculas. |
| String | O valor original. |
| Array | A Array serializada para JSON. A string resultante é uma lista separada por vírgulas, entre colchetes. A String tem aspas. Um Decimal, Int, Boolean e Null não. |
| Objeto | O objeto serializado para JSON. A string resultante é uma lista separada por vírgulas de pares de chave/valor e começa e termina com chaves. A String tem aspas. Um Decimal, Int, Boolean e Null não. |
| Null | Undefined. |
| Não definido | Indefinido. |
# Operadores
Os operadores a seguir podem ser usados nas cláusulas SELECT e WHERE.
## Operador AND
Gera um resultado `Boolean`. Realiza uma operação E lógica. Retornará verdadeiro se os operandos esquerdo e direito forem verdadeiros. Caso contrário, retorna false. Os operandos `Boolean` ou operandos de string "true" ou "false" que não diferenciam letras maiúsculas de minúsculas são necessários.
*Sintaxe:* ` expression AND expression`.
**Operador AND**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. Verdadeiro se ambos os operandos forem verdadeiros. Caso contrário, falso. |
| String/Boolean | String/Boolean | Se todas as strings forem "true" ou "false" (não diferencia letras maiúsculas de minúsculas), elas serão convertidas em Boolean e processadas normalmente como boolean AND boolean. |
| Outros valores | Outros valores | Undefined. |
## Operador OU
Gera um resultado `Boolean`. Executa uma operação OU lógica. Retornará verdadeiro se um dos operandos esquerdo ou direito for verdadeiro. Caso contrário, retorna false. Os operandos `Boolean` ou operandos de string "true" ou "false" que não diferenciam letras maiúsculas de minúsculas são necessários.
*Sintaxe:* ` expression OR expression`.
**Operador OU**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. Verdadeiro se um dos operandos for verdadeiro. Caso contrário, falso. |
| String/Boolean | String/Boolean | Se todas as strings forem "true" ou "false" (não diferencia letras maiúsculas de minúsculas), elas serão convertidas em booleanos e processadas normalmente como boolean OR boolean. |
| Outros valores | Outros valores | Undefined. |
## Operador NOT
Gera um resultado `Boolean`. Realiza uma operação NÃO lógica. Retornará verdadeiro se o operando for falso. Caso contrário, retornará verdadeiro. Um operando `Boolean` ou operando de string "true" ou "false" que não diferencia letras maiúsculas de minúsculas é necessário.
*Sintaxe:* `NOT expression`.
**Operador NOT**
| Operando | Output |
| --- | --- |
| Boolean | Boolean. Verdadeiro se o operando for falso. Caso contrário, verdadeiro. |
| String | Se a string for "true" ou "false" (não diferencia letras maiúsculas de minúsculas), ela será convertida no valor booliano correspondente, e o valor oposto será gerado. |
| Outros valores | Undefined. |
## Operador IN
Gera um resultado `Boolean`. Você pode usar o operador IN em uma cláusula WHERE para verificar se um valor corresponde a algum valor em uma matriz. Ele retornará verdadeiro se a correspondência for encontrada; caso contrário, retornará falso.
*Sintaxe:* ` expression IN expression`.
**Operador IN**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal/String/Array/Object | Array | Verdadeiro se o elemento Integer/Decimal/String/Array/Object for encontrado na matriz. Caso contrário, falso. |
*Exemplo:*
```
SQL: "select * from 'a/b' where 3 in arr"
JSON: {"arr":[1, 2, 3, "three", 5.7, null]}
```
Neste exemplo, a cláusula de condição `where 3 in arr` será avaliada como verdadeira porque 3 está presente na matriz chamada `arr`. Portanto, na instrução SQL, `select * from 'a/b'` será executado. Esse exemplo também mostra que a matriz pode ser heterogênea.
## Operador EXISTS
Gera um resultado `Boolean`. Você poderá usar o operador EXISTS em uma cláusula condicional para testar a existência de elementos em uma subconsulta. Ele retornará verdadeiro se a subconsulta retornar um ou mais elementos e falso se a subconsulta não retornar nenhum elemento.
*Sintaxe:* ` expression`.
*Exemplo:*
```
SQL: "select * from 'a/b' where exists (select * from arr as a where a = 3)"
JSON: {"arr":[1, 2, 3]}
```
Neste exemplo, a cláusula de condição `where exists (select * from arr as a where a = 3)` será avaliada como verdadeira porque 3 está presente na matriz chamada `arr`. Portanto, na instrução SQL, `select * from 'a/b'` será executado.
*Exemplo:*
```
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}]}
```
Neste exemplo, a cláusula de condição `where exists (select * from e as e where foo = 2)` será avaliada como verdadeira porque a matriz `e` dentro do objeto JSON contém o objeto `{"foo":2}`. Portanto, na instrução SQL, `select * from 'a/b'` será executado.
## > operador
Gera um resultado `Boolean`. Verdadeiro se o operando esquerdo for superior ao operando direito. Os dois operandos são convertidos em um `Decimal` e depois comparados.
*Sintaxe:* `expression > expression`.
**> operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Verdadeiro se o operando esquerdo for superior ao operando direito. Caso contrário, falso. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings puderem ser convertidas em Decimal, então Boolean. Verdadeiro se o operando esquerdo for superior ao operando direito. Caso contrário, falso. |
| Outros valores | Undefined. | Undefined. |
## >= operador
Gera um resultado `Boolean`. Verdadeiro se o operando esquerdo for superior ou igual ao operando direito. Os dois operandos são convertidos em um `Decimal` e depois comparados.
*Sintaxe:* `expression >= expression`.
**>= operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Verdadeiro se o operando esquerdo for igual ou superior ao operando direito. Caso contrário, falso. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings puderem ser convertidas em Decimal, então Boolean. Verdadeiro se o operando esquerdo for superior ou igual ao operando direito. Caso contrário, falso. |
| Outros valores | Undefined. | Undefined. |
## < operador
Gera um resultado `Boolean`. Verdadeiro se o operando esquerdo for inferior ao operando direito. Os dois operandos são convertidos em um `Decimal` e depois comparados.
*Sintaxe:* `expression < expression`.
**< operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Verdadeiro se o operando esquerdo for inferior ao operando direito. Caso contrário, falso. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings puderem ser convertidas em Decimal, então Boolean. Verdadeiro se o operando esquerdo for inferior ao operando direito. Caso contrário, falso. |
| Outros valores | Undefined | Undefined |
## <= operador
Gera um resultado `Boolean`. Verdadeiro se o operando esquerdo for inferior ou igual ao operando direito. Os dois operandos são convertidos em um `Decimal` e depois comparados.
*Syntaxe:* `expression <= expression`.
**<= operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Verdadeiro se o operando esquerdo for igual ou inferior ao operando direito. Caso contrário, falso. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings puderem ser convertidas em Decimal, então Boolean. Verdadeiro se o operando esquerdo for inferior ou igual ao operando direito. Caso contrário, falso. |
| Outros valores | Undefined | Undefined |
## <> operador
Gera um resultado `Boolean`. Retornará verdadeiro se os operandos esquerdo e direito forem diferentes. Caso contrário, retornará falso.
*Sintaxe:* ` expression <> expression`.
**<> operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Verdadeiro se o operando esquerdo não for igual ao operando direito. Caso contrário, falso. |
| Decimal | Decimal | Verdadeiro se o operando esquerdo não for igual ao operando direito. Caso contrário, falso. Int é convertido em Decimal antes de ser comparado. |
| String | String | Verdadeiro se o operando esquerdo não for igual ao operando direito. Caso contrário, falso. |
| Array | Array | Verdadeiro se os itens em cada operando não forem iguais e não estiverem na mesma ordem. Caso contrário, falso |
| Objeto | Objeto | Verdadeiro se as chaves e os valores de cada operando não forem iguais. Caso contrário, falso. A ordem de não keys/values é importante. |
| Null | Null | Falso. |
| Qualquer valor | Undefined | Indefinido. |
| Undefined | Qualquer valor | Indefinido. |
| Tipo não correspondente | Tipo não correspondente | Verdadeiro. |
## = operador
Gera um resultado `Boolean`. Retornará verdadeiro se os operandos esquerdo e direito forem iguais. Caso contrário, retornará falso.
*Sintaxe:* ` expression = expression`.
**= operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Verdadeiro se o operando esquerdo for igual ao operando direito. Caso contrário, falso. |
| Decimal | Decimal | Verdadeiro se o operando esquerdo for igual ao operando direito. Caso contrário, falso. Int é convertido em Decimal antes de ser comparado. |
| String | String | Verdadeiro se o operando esquerdo for igual ao operando direito. Caso contrário, falso. |
| Array | Array | Verdadeiro se os itens em cada operando forem iguais e estiverem na mesma ordem. Caso contrário, falso. |
| Objeto | Objeto | Verdadeiro se as chaves e os valores de cada operando forem iguais. Caso contrário, falso. A ordem de não keys/values é importante. |
| Qualquer valor | Undefined | Undefined. |
| Undefined | Qualquer valor | Undefined. |
| Tipo não correspondente | Tipo não correspondente | Falso. |
## \$1 operador
" \$1" é um operador sobrecarregado. Ele pode ser usado para concatenação ou adição de string.
*Sintaxe:* ` expression + expression`.
**\$1 operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| String | Qualquer valor | Converte o operando direito em uma string e concatena-o ao final do operando esquerdo. |
| Qualquer valor | String | Converte o operando esquerdo em uma string e concatena o operando direito ao final do operando esquerdo convertido. |
| Int | Int | Int value. Adiciona operandos juntos. |
| Int/Decimal | Int/Decimal | Decimal value. Adiciona operandos juntos. |
| Outros valores | Outros valores | Undefined. |
## - operador
Subtrai o operando direito do operando esquerdo.
*Sintaxe:* ` expression - expression`.
**- operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int value. Subtrai o operando direito do operando esquerdo. |
| Int/Decimal | Int/Decimal | Decimal value. Subtrai o operando direito do operando esquerdo. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais corretamente, um valor Decimal será gerado. Subtrai o operando direito do operando esquerdo. Caso contrário, gera Undefined. |
| Outros valores | Outros valores | Undefined. |
| Outros valores | Outros valores | Undefined. |
## \$1 operador
Multiplica o operando esquerdo pelo operando direito.
*Sintaxe:* ` expression * expression`.
**\$1 operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int value. Multiplica o operando esquerdo pelo operando direito. |
| Int/Decimal | Int/Decimal | Decimal value. Multiplica o operando esquerdo pelo operando direito. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais corretamente, um valor Decimal será gerado. Multiplica o operando esquerdo pelo operando direito. Caso contrário, gera Undefined. |
| Outros valores | Outros valores | Undefined. |
## / operador
Divide o operando esquerdo pelo operando direito.
*Sintaxe:* ` expression / expression`.
**/ operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int value. Divide o operando esquerdo pelo operando direito. |
| Int/Decimal | Int/Decimal | Decimal value. Divide o operando esquerdo pelo operando direito. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais corretamente, um valor Decimal será gerado. Divide o operando esquerdo pelo operando direito. Caso contrário, gera Undefined. |
| Outros valores | Outros valores | Undefined. |
## % operador
Gera o restante da divisão do operando esquerdo pelo operando direito.
*Sintaxe:* ` expression % expression`.
**% operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int value. Gera o restante da divisão do operando esquerdo pelo operando direito. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais corretamente, um valor Decimal será gerado. Gera o restante da divisão do operando esquerdo pelo operando direito. Caso contrário, Undefined. |
| Outros valores | Outros valores | Undefined. |
# Funções
Você pode usar as seguintes funções integradas nas cláusulas SELECT ou WHERE das expressões do SQL.
As seguintes funções externas são cobradas de forma equivalente à de uma ação de regra: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data), e. [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) Você também é cobrado pela função [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) apenas quando está [decodificando uma mensagem Protobuf para JSON](https://docs.aws.amazon.com//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf). Para obter mais detalhes, consulte a [página de precificação do AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
## abs(Decimal)
Gera o valor absoluto de um número. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `abs(-5)` gera 5.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, o valor absoluto do argumento. |
| Decimal | Decimal, o valor absoluto do argumento. |
| Boolean | Undefined. |
| String | Decimal. O resultado é o valor absoluto do argumento. Se a string não puder ser convertida, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## accountid()
Gera o ID da conta que possui essa regra como uma `String`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`accountid() ` = "123456789012"
## acos(Decimal)
Gera o cosseno inverso de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `acos(0)` = 1,5707963267948966
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o cosseno inverso do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), o cosseno inverso do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal, o cosseno inverso do argumento. Se a string não puder ser convertida, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## asin(Decimal)
Gera o seno inverso de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `asin(0)` = 0,0
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o seno inverso do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), o seno inverso do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o seno inverso do argumento. Se a string não puder ser convertida, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## atan(Decimal)
Gera a tangente inversa de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `atan(0)` = 0,0
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), a tangente inversa do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), a tangente inversa do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal, a tangente inversa do argumento. Se a string não puder ser convertida, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## atan2(Decimal, Decimal)
Gera o ângulo, em radianos, entre o eixo X positivo e o ponto (x, y) definido nos dois argumentos. O ângulo é positivo para os ângulos em sentido anti-horário (metade superior, y > 0) e negativo para os ângulos em sentido horário (metade inferior, y < 0). Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `atan2(1, 0)` = 1,5707963267948966
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal (com precisão dupla), o ângulo entre o eixo x e o ponto (x, y) especificado. |
| Int/Decimal/String | Int/Decimal/String | Decimal, a tangente inversa do ponto descrito. Se uma string não puder ser convertida, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## aws\$1lambda(functionArn, inputJson)
Chama a função do Lambda especificada passando `inputJson` para a função do Lambda e retorna o JSON gerado pela função do Lambda.
**Argumentos**
| Argumento | Description |
| --- | --- |
| functionArn | O ARN da função do Lambda a ser chamada. A função do Lambda deve retornar dados JSON. |
| inputJson | A entrada JSON passada para a função do Lambda. Para passar consultas e literais de objetos aninhados, você deve usar o SQL versão 23/03/2016. |
Você deve conceder AWS IoT `lambda:InvokeFunction` permissões para invocar a função Lambda especificada. O seguinte exemplo mostra como conceder a permissão `lambda:InvokeFunction` usando a 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"
```
Veja os argumentos do comando **add-permission**:
--nome da função
Nome da função do Lambda. Você adiciona uma nova permissão para atualizar a política de recursos da função.
--region
O Região da AWS da sua conta.
--entidade principal
O principal que está recebendo a permissão. Isso deve permitir `iot.amazonaws.com` a AWS IoT permissão para chamar uma função Lambda.
--arn de origem
O ARN da regra. Você pode usar o **get-topic-rule** AWS CLI comando para obter o ARN de uma regra.
--conta de origem
O Conta da AWS local em que a regra é definida.
--id da declaração
Um identificador de declaração exclusivo.
--action
A ação do Lambda que você deseja permitir nesta declaração. Para permitir que o AWS IoT invoque uma função do Lambda, especifique `lambda:InvokeFunction`.
**Importante**
Se você adicionar uma permissão para um AWS IoT principal sem fornecer o `source-arn` ou`source-account`, qualquer uma Conta da AWS que crie uma regra com sua ação do Lambda poderá acionar regras para invocar sua função do Lambda. AWS IoT Para obter mais informações, consulte [Modelo de permissões do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).
Dada uma carga da mensagem JSON como:
```
{
"attribute1": 21,
"attribute2": "value"
}
```
A função do `aws_lambda` pode ser usada para chamar a função do Lambda da seguinte forma.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", {"payload":attribute1}) as output FROM 'topic-filter'
```
Se você deseja passar a carga da mensagem MQTT completa, especifique a carga JSON usando "\$1", como no exemplo a seguir.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", *) as output FROM 'topic-filter'
```
`payload.inner.element` seleciona dados de mensagem publicada no tópico 'tópico/subtópico'.
`some.value` seleciona dados da saída gerada pela função do Lambda.
**nota**
O mecanismo de regras limita a duração da execução das funções do Lambda. As chamadas de função do Lambda em regras devem ser concluídas em 2.000 milissegundos.
## bitand(Int, Int)
Realiza um bitwise AND nas representações do bit dos dois argumentos `Int`(-convertido). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `bitand(13, 5)` = 5
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int | Int | Int, um bitwise AND dos dois argumentos. |
| Int/Decimal | Int/Decimal | Int, um bitwise AND dos dois argumentos. Todos os números não Int são arredondados para o Int mais próximo. Se qualquer um dos argumentos não puder ser convertido em um Int, o resultado será Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, um bitwise AND dos dois argumentos. Todas as strings são convertidas em decimais e são arredondadas para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## bitor(Int, Int)
Executa um bitwise OU das representações de bit dos dois argumentos. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `bitor(8, 5)` = 13
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int | Int | Int, o bitwise OU dos dois argumentos. |
| Int/Decimal | Int/Decimal | Int, o bitwise OU dos dois argumentos. Todos os números não Int são arredondados para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, o bitwise OU nos dois argumentos. Todas as strings são convertidas em decimais e são arredondadas para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## bitxor(Int, Int)
Realiza um bitwise XOR nas representações do bit dos dois argumentos `Int`(-convertido). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:`bitor(13, 5)` = 8
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int | Int | Int, um bitwise XOR nos dois argumentos. |
| Int/Decimal | Int/Decimal | Int, um bitwise XOR nos dois argumentos. Os números não Int são arredondados para o Int mais próximo. |
| Int/Decimal/String | Int/Decimal/String | Int, um bitwise XOR nos dois argumentos. As strings são convertidas em decimais e são arredondadas para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## bitnot(Int)
Realiza um bitwise NOT nas representações do bit do argumento `Int`(-convertido). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `bitnot(13)` = 2
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, um bitwise NOT do argumento. |
| Decimal | Int, um bitwise NOT do argumento. O valor Decimal é arredondado para o Int abaixo mais próximo. |
| String | Int, um bitwise NOT do argumento. As strings são convertidas em decimais e são arredondadas para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Outros valores | Outros valores. |
## cast()
Converte um valor de um tipo de dados para outro. O cast é muito parecido com as conversões padrão, com a adição da capacidade de converter números em ou de boolianos. Se AWS IoT não conseguir determinar como converter um tipo em outro, o resultado é`Undefined`. Compatível com a versão de 08/10/2015 do SQL e posteriores. Formato: cast (*value*as*type*).
Exemplo:
`cast(true as Int) ` = 1
As seguintes palavras-chave podem aparecer após "as" ao chamar `cast`:
**Para as versões do SQL de 08/10/2015 e 23/03/2016**
| Palavra-chave | Resultado |
| --- | --- |
| String | Aplica valor para String. |
| Nvarchar | Aplica valor para String. |
| Texto | Aplica valor para String. |
| Ntext | Aplica valor para String. |
| varchar | Aplica valor para String. |
| Int | Aplica valor para Int. |
| Inteiro | Aplica valor para Int. |
| Duplo | Converte o valor para Decimal (com precisão dupla). |
**Além disso, para as versões do SQL de 23/03/2016**
| Palavra-chave | Resultado |
| --- | --- |
| Decimal | Aplica valor para Decimal. |
| Bool | Aplica valor para Boolean. |
| Boolean | Aplica valor para Boolean. |
Regras de cast:
**Cast para decimal**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Um Decimal sem ponto decimal. |
| Decimal | O valor de origem. Com o SQL V2 (23/03/2016), valores numéricos que são números inteiros, como `10.0`, retornam um valor `Int` (`10`) em vez do valor `Decimal` esperado (`10.0`). Para converter de forma confiável valores numéricos inteiros como valores `Decimal`, use o SQL V1 (08/10/2015) para a instrução de consulta de regra. |
| Boolean | verdadeiro = 1,0, falso = 0,0. |
| String | Tenta analisar a string como um Decimal. A AWS IoT tenta analisar as strings correspondendo à regex: ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1,2" e "5E-12" são exemplos de strings que são automaticamente convertidas em decimais. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
**Cast para int**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | O valor de origem. |
| Decimal | O valor de origem arredondado para o Int abaixo mais próximo. |
| Boolean | verdadeiro = 1,0, falso = 0,0. |
| String | Tenta analisar a string como um Decimal. A AWS IoT tenta analisar as strings correspondendo à regex: ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1,2", "5E-12" são exemplos de strings que são automaticamente convertidas em decimais. A AWS IoT tenta converter a string em Decimal e arredondar para o Int mais próximo. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
**Aplicar para `Boolean`**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | 0 = Falso, qualquer\$1valor\$1não\$1zero = Verdadeiro. |
| Decimal | 0 = Falso, qualquer\$1valor\$1não\$1zero = Verdadeiro. |
| Boolean | O valor de origem. |
| String | "true" = Verdadeiro e "false" = Falso (não diferencia maiúsculas de minúsculas). Outros valores de string = Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
**Cast para string**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Uma representação de string do Int em notação padrão. |
| Decimal | Uma string representando o valor Decimal, possivelmente em notação científica. |
| Boolean | "verdadeiro" ou "falso", todas as letras minúsculas. |
| String | O valor de origem. |
| Array | A matriz serializada para JSON. A string resultante é uma lista separada por vírgulas, entre colchetes. String tem aspas. Decimals, Ints e Booleans não. |
| Objeto | O objeto serializado para JSON. A string JSON é uma lista separada por vírgulas de pares de chave/valor e começa e termina com chaves. String tem aspas. Decimals, Ints, Booleans e Null não. |
| Null | Undefined. |
| Não definido | Undefined. |
## ceil(Decimal)
Arredonda o `Decimal` fornecido para o `Int` acima mais próximo. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`ceil(1.2)` = 2
`ceil(-1.2)` = -1
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, o valor do argumento. |
| Decimal | Int, o valor Decimal arredondado para o Int acima mais próximo. |
| String | Int. A string será convertida em Decimal e arredondada para o Int acima mais próximo. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Outros valores | Undefined. |
## chr(String)
Gera o caractere ASCII que corresponde ao dado argumento `Int`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`chr(65)` = "A".
`chr(49)` = "1".
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | O caractere correspondente ao valor ASCII especificado. Se o argumento não for um valor ASCII válido, o resultado será Undefined. |
| Decimal | O caractere correspondente ao valor ASCII especificado. O argumento Decimal é arredondado para o Int abaixo mais próximo. Se o argumento não for um valor ASCII válido, o resultado será Undefined. |
| Boolean | Undefined. |
| String | Se a String puder ser convertida em Decimal, ela será arredondada para o Int mais próximo. Se o argumento não for um valor ASCII válido, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Outros valores | Undefined. |
## clientid()
Gera o ID do MQTT cliente que envia a mensagem ou `n/a` se a mensagem não foi enviada por MQTT. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`clientid() ` = "123456789012"
## concat()
Concatena as matrizes ou strings. Essa função aceita qualquer número de argumentos e gera uma `String` ou uma `Array`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`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 | O argumento é gerado sem modificações. |
| 2\$1 | Se algum argumento for uma `Array`, o resultado será uma única matriz que contém todos os argumentos. Se não houver matrizes e pelo menos um argumento for uma `String`, o resultado será a concatenação das representações de `String` de todos os argumentos. Os argumentos são convertidos em strings usando as conversões padrão listadas anteriormente. |
## cos(Decimal)
Gera o cosseno de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`cos(0)` = 1.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o cosseno do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), o cosseno do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o cosseno do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## cosh(Decimal)
Gera o cosseno hiperbólico de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `cosh(2.3)` = 5,037220649268761.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o cosseno hiperbólico do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), o cosseno hiperbólico do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o cosseno hiperbólico do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## decodificar (valor, esquema de decodificação)
Use a função `decode` para decodificar um valor codificado. Se a string decodificada for um documento JSON, um objeto endereçável será retornado. Caso contrário, a string decodificada será retornada como uma string. A função retornará NULL se a string não puder ser decodificada. Essa função é compatível com a decodificação de strings codificadas em base64 e o formato de mensagem Protocol Buffer (protobuf).
Compatível com a versão de 23/03/2016 do SQL e posteriores.
valor
Um valor de string ou qualquer uma das expressões válidas, conforme definido em [AWS IoT Referência SQL](iot-sql-reference.md), que retornam uma string.
decodingScheme
Uma string literal representando o esquema usado para decodificar o valor. Atualmente, apenas há suporte para `'base64'` e `'proto'`.
### Decodificação de strings codificadas em base64
Neste exemplo, a carga útil da mensagem inclui um valor codificado.
```
{
encoded_temp: "eyAidGVtcGVyYXR1cmUiOiAzMyB9Cg=="
}
```
A função `decode` nessa instrução SQL decodifica o valor na carga útil da mensagem.
```
SELECT decode(encoded_temp,"base64").temperature AS temp from 'topic/subtopic'
```
A decodificação do valor `encoded_temp` resulta no seguinte documento JSON válido, que permite que a instrução SELECT leia o valor da temperatura.
```
{ "temperature": 33 }
```
O resultado da instrução SELECT neste exemplo é mostrado aqui.
```
{ "temp": 33 }
```
Se o valor decodificado não fosse um documento JSON válido, o valor decodificado seria retornado como uma string.
### Decodificação da carga útil da mensagem protobuf
Você pode usar a função decodificar SQL para configurar uma regra que pode decodificar a carga útil da mensagem protobuf. Para obter mais informações, consulte [Decodificação de cargas úteis de mensagens protobuf](binary-payloads.md#binary-payloads-protobuf).
**Importante**
Se você omitir `source‐arn` ou `source‐account` ao definir permissões para um AWS IoT principal, qualquer um Conta da AWS poderá invocar sua função de decodificação por meio de outras regras. AWS IoT Para proteger sua função, consulte [Políticas de bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html) no *Guia do usuário do Amazon Simple Storage Service*.
A assinatura da função tem a seguinte aparência:
```
decode(, 'proto', '', '', '', '')
```
`ENCODED DATA`
Especifica os dados codificados por protobuf a serem decodificados. Se toda a mensagem enviada para a regra for de dados codificados por protobuf, você poderá referenciar a carga útil de entrada binária bruta usando `*`. Caso contrário, esse campo deve ser uma string JSON codificada em base 64 e uma referência à string pode ser passada diretamente.
1) Para decodificar uma carga útil bruta de entrada de protobuf binário:
```
decode(*, 'proto', ...)
```
2) Para decodificar uma mensagem codificada por protobuf representada por uma string codificada em base64 'a.b':
```
decode(a.b, 'proto', ...)
```
`proto`
Especifica os dados a serem decodificados em um formato de mensagem protobuf. Se você especificar `base64` em vez de `proto`, essa função decodificará strings codificadas em base64 como JSON.
`S3 BUCKET NAME`
O nome do bucket do Amazon S3 onde você fez upload do arquivo `FileDescriptorSet`.
`S3 OBJECT KEY`
A chave de objeto que especifica o arquivo `FileDescriptorSet` dentro do bucket do Amazon S3.
`PROTO NAME`
O nome do arquivo `.proto` (excluindo a extensão) do qual o arquivo `FileDescriptorSet` foi gerado.
`MESSAGE TYPE`
O nome da estrutura da mensagem protobuf dentro do arquivo `FileDescriptorSet`, com a qual os dados a serem decodificados devem estar em conformidade.
Um exemplo de expressão SQL usando a função decodificar SQL pode ter a seguinte aparência:
```
SELECT VALUE decode(*, 'proto', 's3-bucket', 'messageformat.desc', 'myproto', 'messagetype') FROM 'some/topic'
```
+ `*`
Representa uma carga de entrada binária, que está em conformidade com o tipo de mensagem protobuf chamado `mymessagetype`.
+ `messageformat.desc`
O arquivo `FileDescriptorSet` armazenado em um bucket do Amazon S3 chamado `s3-bucket`.
+ `myproto`
O arquivo `.proto` original usado para gerar o arquivo `FileDescriptorSet` chamado `myproto.proto`.
+ `messagetype`
O tipo de mensagem chamado `messagetype` (junto com todas as dependências importadas) conforme definido em `myproto.proto`.
## encode(value, encodingScheme)
Use a função `encode` para codificar a carga útil, que provavelmente serão dados não JSON, em sua representação de string com base no esquema de codificação. Compatível com a versão de 23/03/2016 do SQL e posteriores.
valor
Qualquer uma das expressões válidas, conforme definido em [AWS IoT Referência SQL](iot-sql-reference.md). Você pode especificar \$1 para codificar toda a carga útil, independentemente de estar no formato JSON. Se você fornecer uma expressão, o resultado da avaliação será convertido em uma string antes de ser codificado.
encodingScheme
Uma string literal que representa o esquema de codificação que você deseja usar. No momento, só há compatibilidade com `'base64'`.
## endswith(String, String)
Gera um `Boolean` indicando se o primeiro argumento de `String` termina com o segundo argumento de `String`. Se um dos argumentos for `Null` ou `Undefined`, o resultado será `Undefined`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `endswith("cat","at")` = verdadeiro.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | String | Verdadeiro se o primeiro argumento terminar no segundo argumento. Caso contrário, falso. |
| Outros valores | Outros valores | Os dois argumentos são convertidos em strings usando as regras padrão de conversão. Verdadeiro se o primeiro argumento terminar no segundo argumento. Caso contrário, falso. Se um dos argumentos for Null ou Undefined, o resultado será Undefined. |
## exp(Decimal)
Gera e elevado ao argumento `Decimal`. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `exp(1)` = e.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), argumento e ^. |
| Decimal | Decimal (com precisão dupla), argumento e ^. |
| String | Decimal (com precisão dupla), argumento e ^. Se a String não puder ser convertida em um Decimal, o resultado será Undefined. |
| Outros valores | Undefined. |
## floor(Decimal)
Arredonda o `Decimal` fornecido para o `Int` abaixo mais próximo. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`floor(1.2)` = 1
`floor(-1.2)` = -2
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, o valor do argumento. |
| Decimal | Int, o valor Decimal é arredondado para o Int abaixo mais próximo. |
| String | Int. A string será convertida em Decimal e arredondada para o Int abaixo mais próximo. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Outros valores | Undefined. |
## obter
Extrai um valor de um tipo de coleção (Matriz, String, Objeto). Nenhuma conversão é aplicada ao primeiro argumento. A conversão se aplica como documentado na tabela ao segundo argumento. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`get(["a", "b", "c"], 1) ` = "b"
`get({"a":"b"}, "a")` = "b"
`get("abc", 0)` = "a"
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| Array | Qualquer tipo (convertido em Int) | O item no índice com base 0 da Array fornecido pelo segundo argumento (convertido em Int). Se não for possível converter, o resultado será Undefined. Se o índice estiver fora dos limites da Array (negativo ou >= matriz.comprimento), o resultado será Undefined. |
| String | Qualquer tipo (convertido em Int) | O caractere no índice com base 0 da string fornecido pelo segundo argumento (convertido em Int). Se não for possível converter, o resultado será Undefined. Se o índice estiver fora dos limites da string (negativo ou >= string.comprimento), o resultado será Undefined. |
| Objeto | String (nenhuma conversão é aplicada) | O valor armazenado no primeiro objeto de argumento correspondente à chave de string fornecida como o segundo argumento. |
| Outros valores | Qualquer valor | Undefined. |
## get\$1dynamodb (nome da tabela,,,,, RoLearn partitionKeyName) partitionKeyValue sortKeyName sortKeyValue
Recupera dados de uma tabela do DynamoDB. `get_dynamodb()` permite consultar uma tabela do DynamoDB enquanto uma regra é avaliada. É possível filtrar ou aumentar cargas de mensagens usando dados recuperados do DynamoDB. Compatível com a versão de 23/03/2016 do SQL e posteriores.
`get_dynamodb()` utiliza os seguintes parâmetros:
tableName
O nome da tabela do DynamoDB a ser consultada.
partitionKeyName
O nome da chave da partição. Para obter mais informações, consulte [Chaves do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
partitionKeyValue
O valor da chave de partição usada para identificar um registro. Para obter mais informações, consulte [Chaves do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyName
(Opcional) O nome da chave de classificação. Esse parâmetro será necessário somente se a tabela do DynamoDB consultada usar uma chave composta. Para obter mais informações, consulte [Chaves do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyValue
(Opcional) O valor da chave de classificação. Esse parâmetro será necessário somente se a tabela do DynamoDB consultada usar uma chave composta. Para obter mais informações, consulte [Chaves do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
roleArn
O ARN do perfil do IAM que concede acesso à tabela do DynamoDB. O mecanismo de regras assume essa função para acessar a tabela do DynamoDB em seu nome. Evite usar uma função excessivamente permissiva. Conceda à função apenas as permissões necessárias para a regra. O exemplo de política a seguir concede acesso a uma tabela do DynamoDB.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:GetItem",
"Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/table-name"
}
]
}
```
Como um exemplo de como é possível usar `get_dynamodb()`, digamos que você tenha uma tabela do DynamoDB que contém o ID do dispositivo e as informações de localização para todos os dispositivos conectados ao AWS IoT. A instrução SELECT a seguir usa a função `get_dynamodb()` para recuperar o local para o ID do dispositivo especificado:
`SELECT *, get_dynamodb("InServiceDevices", "deviceId", id, "arn:aws:iam::12345678910:role/getdynamo").location AS location FROM 'some/topic' `
**nota**
É possível chamar `get_dynamodb()` no máximo uma vez por instrução SQL. Chamar `get_dynamodb()` várias vezes em uma única instrução SQL faz com que a regra seja encerrada sem chamar nenhuma ação.
## get\$1mqtt\$1property (nome)
Faz referência a qualquer um dos seguintes MQTT5 cabeçalhos: `contentType``payLoadFormatIndicator`,`responseTopic`, e. `correlationData` Essa função usa qualquer uma das seguintes strings literais como argumento: `content_type`, `format_indicator`, `response_topic` e `correlation_data`. Para obter mais informações, consulte a tabela de **Argumentos de função** a seguir.
contentType
String: Uma string codificada em UTF-8 que descreve o conteúdo da mensagem de publicação.
payLoadFormatIndicador
String: Um valor de string Enum que indica se a carga útil está formatada como UTF-8. Os valores válidos são `UNSPECIFIED_BYTES` e `UTF8_DATA`.
responseTopic
String: Uma string codificada em UTF-8 que é usada como nome de tópico para uma mensagem de resposta. O tópico da resposta é usado para descrever o tópico que o destinatário deve publicar como parte do fluxo solicitação-resposta. O tópico não deve conter caracteres curinga.
correlationData
String: Os dados binários codificados em base64 usados pelo remetente da mensagem de solicitação para identificar para qual solicitação é a mensagem de resposta.
A tabela a seguir mostra os argumentos de função aceitáveis e os tipos de retorno associados para a `get_mqtt_property` função:
**Argumentos de função**
| SQL | Tipo de dados retornado (se presente) | Tipo de dados retornado (se não presente) |
| --- | --- | --- |
| get\$1mqtt\$1property("format\$1indicator") | Cadeia de caracteres (UNSPECIFIED\$1BYTES ou \$1DATA) UTF8 | String (UNSPECIFIED\$1BYTES) |
| get\$1mqtt\$1property("content\$1type") | String | Não definido |
| get\$1mqtt\$1property("response\$1topic") | String | Não definido |
| get\$1mqtt\$1property("correlation\$1data") | String codificada em base64 | Não definido |
| get\$1mqtt\$1property("some\$1invalid\$1name") | Não definido | Não definido |
O exemplo a seguir Rules SQL faz referência a qualquer um dos seguintes MQTT5 cabeçalhos: `contentType``payLoadFormatIndicator`,`responseTopic`, e. `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 (expressão, DefaultValue)
Retorna o valor padrão no segundo parâmetro, se especificado, ou então retorna indefinido, quando a expressão no primeiro parâmetro retorna nula, indefinida ou falha. Compatível com a versão de 23/03/2016 do SQL e posteriores.
**Importante**
`get_or_default`não oferece suporte a cargas não JSON diretamente como estão. Se você estiver usando uma carga não JSON, use as `encode` funções ou. `decode`
`get_or_default()` utiliza os seguintes parâmetros:
expressão
Qualquer expressão válida contendo[Tipos de dados](iot-sql-data-types.md), [Funções](#iot-sql-functions)[Literais](iot-sql-literals.md),[Consultas de objeto aninhado](iot-sql-nested-queries.md), [Variáveis](iot-sql-set.md#iot-sql-set-usage) ou[Extensões JSON](iot-sql-json.md).
defaultValue
(Opcional) Qualquer expressão válida contendo [Tipos de dados](iot-sql-data-types.md)[Funções](#iot-sql-functions),[Literais](iot-sql-literals.md),[Consultas de objeto aninhado](iot-sql-nested-queries.md), [Variáveis](iot-sql-set.md#iot-sql-set-usage) ou[Extensões JSON](iot-sql-json.md). Esse é o valor a ser retornado sempre que o primeiro argumento retornar nulo, indefinido ou falhar.
Funções que buscam dados de recursos de propriedade do cliente, como get\$1secret, get\$1dynamodb, aws\$1lambda, get\$1thing\$1shadow, decode-protobuf e machinelearning\$1predict, não são permitidas no parâmetro DefaultValue.
A tabela a seguir mostra argumentos de função aceitáveis para cada argumento e suas saídas associadas:
| Primeiro argumento | Segundo argumento | Output |
| --- | --- | --- |
| Avaliação bem-sucedida | Qualquer valor ou não especificado | O valor do primeiro argumento. |
| Indefinido, nulo ou falha | Qualquer valor, incluindo indefinido ou nulo | O valor do segundo argumento. |
| Indefinido, nulo ou falha | não especificado | Undefined |
**Exemplos:**
Exemplo 1:
O exemplo a seguir fornece um valor DefaultValue se uma tabela ou consulta do DynamoDB falhar:
```
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'
```
Exemplo 2:
O exemplo a seguir fornece um valor padrão seguro “DESCONHECIDO” se o status for indefinido:
```
SELECT
get_or_default( CASE status
WHEN 'active' THEN 'GOOD'
WHEN 'inactive' THEN 'BAD'/
ELSE 'UNKNOWN'
END, 'UNKNOWN') as status_category
FROM 'topic/subtopic'
```
Exemplo 3:
O exemplo a seguir mostra como você também pode usar get\$1or\$1default com um único parâmetro. Isso é útil em cenários em que você pode não ter um valor padrão claro, mas não deseja que a execução da regra falhe.
```
SELECT
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME") as config
FROM 'device/telemetry'
```
Se a pesquisa do DynamoDB falhar, a execução da regra falhará e nenhuma ação será executada. Se o seguinte SQL for usado em vez disso:
```
SELECT
get_or_default(get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME")) as config
FROM 'device/telemetry'
```
A instrução get\$1or\$1default será avaliada como`Undefined`, portanto, neste exemplo, a instrução SELECT em geral será avaliada `{}` e qualquer ação de regra será tentada.
**Importante**
Recomendamos seguir estas melhores práticas para manter a segurança ao usar essa função:
Evite usar segredos codificados em definições de regras, incluindo valores padrão
Use AWS Secrets Manager para gerenciar informações confidenciais
## get\$1registry\$1data (RegistryAPI, ThingName, RoLearn)
Recupera dados de registro de AWS IoT coisas em uma AWS IoT regra. Você pode ler dados do registro (como atributos, tipo de coisa e grupos de coisas aos quais um dispositivo pertence) e usar essas informações para filtrar, enriquecer ou rotear mensagens dinamicamente. Compatível com a versão de 23/03/2016 do SQL e posteriores.
`get_registry_data()` utiliza os seguintes parâmetros:
API de registro
A API de registro que está sendo chamada. Os valores válidos são `DescribeThing` e `ListThingGroupsForThing`. Esses valores devem ser cadeias de caracteres constantes.
thingName
Cadeia de caracteres: o nome da coisa cujos dados de registro você deseja recuperar.
roleArn
String: um ARN de função com permissão de `iot:DescribeThing` and/or `iot:ListThingGroupsForThing` permissão com base na API que está sendo chamada.
O formato de resposta da `get_registry_data` função é o mesmo da API de registro chamada. Para obter mais informações, consulte [DescribeThing](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeThing.html) e [ListThingGroupsForThing](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingGroupsForThing.html) APIs.
Exemplo:
Você pode recuperar informações do tipo de coisa para permitir a filtragem das mensagens de eventos do AWS IoT Core ciclo de vida das coisas (com o nome da coisa correspondendo ao ID do cliente MQTT) onde está o tipo da coisa. `testenv`
```
SELECT *
FROM '$aws/events/lifecycle/+'
WHERE
get_registry_data("DescribeThing",clientId,[roleArn]).thingTypeName='testenv'
```
Exemplo:
Você pode recuperar atributos de um dispositivo com nome de coisa `sensor1` para todas as mensagens enviadas por seu dispositivo `gateway1` de gateway.
```
SELECT *, get_registry_data("DescribeThing","sensor1",[roleArn]).attributes.temperature_threhold AS device1_tempthreshold
FROM home1/gateway1/sensor1/#
```
**nota**
Você pode chamar no máximo `get_registry_data()` uma vez por instrução SQL e modelos de substituição para ações e ações de erro.
## get\$1secret (secretId, secretType, chave, roleArn)
Recupera o valor do campo criptografado `SecretString` ou `SecretBinary` da versão atual de um segredo em [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/). Para obter mais informações sobre como criar e manter segredos [CreateSecret[UpdateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html)](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html), consulte, [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html)e.
`get_secret()` utiliza os seguintes parâmetros:
secretId
String: O nome do recurso da Amazon (ARN) ou o nome amigável do segredo a ser recuperado.
secretType
String: O tipo de segredo. Valores válidos: `SecretString` \$1 `SecretBinary`.
SecretString
+ Para segredos que você cria como objetos JSON usando o APIs AWS CLI, o ou o AWS Secrets Manager console:
+ Se você especificar um valor para o parâmetro `key`, essa função retornará o valor da chave especificada.
+ Se você não especificar um valor para o parâmetro `key`, essa função retornará o objeto JSON inteiro.
+ Para segredos que você cria como objetos não JSON usando o APIs ou o: AWS CLI
+ Se você especificar um valor para o parâmetro `key`, essa função falhará com uma exceção.
+ Se você não especificar um valor para o parâmetro `key`, essa função retornará o conteúdo do segredo.
SecretBinary
+ Se você especificar um valor para o parâmetro `key`, essa função falhará com uma exceção.
+ Se você não especificar um valor para o parâmetro `key`, essa função retornará o valor secreto como uma string UTF-8 codificada em base64.
key
(Opcional) String: o nome da chave dentro de um objeto JSON armazenado no campo `SecretString` de um segredo. Use esse valor quando quiser recuperar somente o valor de uma chave armazenada em um segredo em vez do objeto JSON inteiro.
Se você especificar um valor para esse parâmetro e o segredo não contiver um objeto JSON dentro do campo `SecretString`, essa função falhará com uma exceção.
roleArn
String: um ARN de função com permissões `secretsmanager:GetSecretValue` e `secretsmanager:DescribeSecret`.
**nota**
Essa função sempre retorna a versão atual do segredo (a versão com a tag `AWSCURRENT`). O mecanismo de AWS IoT regras armazena cada segredo em cache por até 15 minutos. Como resultado, o mecanismo de regras pode levar até 15 minutos para atualizar um segredo. Isso significa que, se você recuperar um segredo até 15 minutos após uma atualização com AWS Secrets Manager, essa função poderá retornar a versão anterior.
Essa função não é medida, mas são cobradas AWS Secrets Manager taxas. Por causa do mecanismo secreto de armazenamento em cache, o mecanismo de regras chama AWS Secrets Manager ocasionalmente. Como o mecanismo de regras é um serviço totalmente distribuído, você pode ver várias chamadas de API do Secrets Manager do mecanismo de regras durante a janela de 15 minutos de armazenamento em cache.
Exemplos:
Você pode usar a função `get_secret` em um cabeçalho de autenticação em uma ação de regra HTTPS, como no exemplo de autenticação de chave de API a seguir.
```
"API_KEY": "${get_secret('API_KEY', 'SecretString', 'API_KEY_VALUE', 'arn:aws:iam::12345678910:role/getsecret')}"
```
Para obter mais informações sobre as ações de regra HTTPS, consulte [HTTP](https-rule-action.md).
## get\$1thing\$1shadow (ThingName, ShadoWName, RoLearn)
Retorna a sombra do objeto especificado. Compatível com a versão de 23/03/2016 do SQL e posteriores.
thingName
String: o nome do objeto que você quer recuperar a sombra.
shadowName
(Opcional) String: o nome da sombra. Esse parâmetro é necessário somente ao fazer referência a sombras nomeadas.
roleArn
String: um ARN de função com permissão `iot:GetThingShadow`.
Exemplos:
Quando usado com uma sombra nomeada, forneça o parâmetro `shadowName`.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","MyThingShadow","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
Quando usado com uma sombra sem nome, omita o 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
Referencia as propriedades do usuário, que é um tipo de cabeçalho de propriedade suportado no MQTT5.
userProperty
String: Uma propriedade de usuário é um par de chave/valor. Essa função usa a chave como argumento e retorna uma matriz de todos os valores que correspondem à chave associada.
**Argumentos de função**
Para as seguintes propriedades do usuário nos cabeçalhos das mensagens:
| Chave | Valor |
| --- | --- |
| alguma chave | algum valor |
| uma chave diferente | um valor diferente |
| alguma chave | valor com chave duplicada |
A tabela a seguir mostra o comportamento esperado do SQL:
| SQL | Tipo de dados de retorno | Valor de dados de retorno |
| --- | --- | --- |
| get\$1user\$1properties('alguma chave') | Matriz de strings | ['some value', 'value with duplicate key'] |
| get\$1user\$1properties('outra chave') | Matriz de strings | ['a different value'] |
| get\$1user\$1properties( ) | Matriz de objetos de chave-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('chave inexistente') | Não definido | |
O exemplo a seguir Rules SQL faz referência às propriedades do usuário (um tipo de cabeçalho de MQTT5 propriedade) na carga útil:
```
SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'
```
## Funções de hashing
AWS IoT fornece as seguintes funções de hashing:
+ md2
+ md5
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Todas as funções de hash esperam um argumento de string. O resultado é o valor de hash da string em questão. Conversões de string padrão se aplicam a argumentos de não string. Todas as funções de hash são compatíveis com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`md2("hello")` = "a9046c73e00331af68917d3804f70655"
`md5("hello")` = "5d41402abc4b2a76b9719d911017c592"
## indexof(String, String)
Apresenta o primeiro índice (base em 0) do segundo argumento como uma substring no primeiro argumento. Os dois argumentos são esperados como strings. Os argumentos que não são strings estão sujeitos às regras padrão de conversão de string. Essa função não se aplica a matrizes, apenas a strings. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`indexof("abcd", "bc") ` = 1
## isNull()
Retorna verdadeiro se o argumento é o valor `Null`. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`isNull(5) ` = false.
`isNull(Null) ` = true.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | verdadeiro |
| Undefined | false |
## isUndefined()
Retorna verdadeiro se o argumento for `Undefined`. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`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 | verdadeiro |
## length(String)
Gera o número de caracteres na string fornecida. As regras padrão de conversão se aplicam a argumentos de não `String`. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`length("hi")` = 2
`length(false)` = 5
## ln(Decimal)
Gera o logaritmo natural do argumento. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `ln(e)` = 1.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o log natural do argumento. |
| Decimal | Decimal (com precisão dupla), o log natural do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o log natural do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## log(Decimal)
Gera o logaritmo na base 10 do argumento. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `log(100)` = 2,0.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o log de base 10 do argumento. |
| Decimal | Decimal (com precisão dupla), o log de base 10 do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o log de base 10 do argumento. Se a String não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## lower(String)
Gera a versão em letra minúscula da `String` fornecida. Argumentos de não string são convertidos em strings usando as regras padrão de conversão. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`lower("HELLO")` = "hello".
`lower(["HELLO"])` = "[\$1"hello\$1"]".
## lpad(String, Int)
Gera o argumento de `String`, preenchido no lado esquerdo com o número de espaços especificado pelo segundo argumento. O argumento `Int` deve estar entre 0 e 1000. Se o valor fornecido estiver fora desse intervalo válido, o argumento será definido para o valor válido mais próximo (0 ou 1.000). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`lpad("hello", 2)` = "` hello`".
`lpad(1, 3)` = "` 1`"
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | Int | String, a String preenchida fornecida no lado esquerdo com um número de espaços igual ao Int fornecido. |
| String | Decimal | O argumento Decimal será arredondado para o Int abaixo mais próximo, e a String será preenchida à esquerda com o número especificado de espaços. |
| String | String | O segundo argumento será convertido em um Decimal, que é arredondado para o Int abaixo mais próximo, e a String será preenchida com o número de espaços especificados à esquerda. Se o segundo argumento não puder ser convertido em um Int, o resultado será Undefined. |
| Outros valores | Int/Decimal/String | O primeiro valor será convertido em uma String usando as conversões padrão, e a função LPAD será aplicada nessa String. Se não for possível fazer a conversão, o resultado será Undefined. |
| Qualquer valor | Outros valores | Undefined. |
## ltrim(String)
Remove todos os espaços em branco iniciais (caracteres de tabulação e espaços) da `String` fornecida. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`Ltrim(" h i ")` = "hi ".
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação de String do Int com todos os espaços em branco iniciais removidos. |
| Decimal | A representação de String do Decimal com todos os espaços em branco iniciais removidos. |
| Boolean | A representação de String do booliano ("verdadeiro" ou "falso") com todos os espaços em branco iniciais removidos. |
| String | O argumento com todos os espaços em branco iniciais removidos. |
| Array | A representação de String de Array (usando as regras padrão de conversão) com todos os espaços em branco iniciais removidos. |
| Objeto | A representação de String do objeto (usando as regras padrão de conversão) com todos os espaços em branco iniciais removidos. |
| Null | Undefined. |
| Não definido | Undefined. |
## machinelearning\$1predict(modelId, roleArn, registro)
Use a `machinelearning_predict` função para fazer previsões usando os dados de uma mensagem MQTT com base em um modelo de SageMaker IA da Amazon. Compatível com a versão de 08/10/2015 do SQL e posteriores. Os argumentos da função `machinelearning_predict` são:
modelId
O ID do modelo no qual executar a previsão. O endpoint em tempo real do modelo deve ser habilitado.
roleArn
O perfil do IAM; que tem uma política com as permissões `machinelearning:Predict` e `machinelearning:GetMLModel` e que permite acessar o modelo no qual a previsão é executada.
registro
Os dados a serem passados para a API SageMaker AI Predict. Isso deve ser representado como um único objeto JSON de camada. Se o registro for um objeto JSON de vários níveis, o registro será aplainado ao serializar seus valores. Por exemplo, o seguinte JSON:
```
{ "key1": {"innerKey1": "value1"}, "key2": 0}
```
se tornaria:
```
{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}
```
A função gera um objeto JSON com os seguintes campos:
predictedLabel
A classificação da entrada com base no modelo.
detalhes
Contém os seguintes atributos:
PredictiveModelType
O tipo do modelo. Os valores válidos são REGRESSION, BINARY, MULTICLASS.
Algoritmo
O algoritmo usado pela SageMaker IA para fazer previsões. O valor deve ser SGD.
predictedScores
Contém a pontuação de classificação bruta correspondente a cada rótulo.
predictedValue
O valor previsto pela SageMaker IA.
## mod(Decimal, Decimal)
Gera o restante da divisão do primeiro argumento pelo segundo argumento. Equivale a [remainder(Decimal, Decimal)](#iot-func-remainder). Você também pode usar "%" como um operador infixo para a mesma funcionalidade do módulo. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `mod(8, 3)` = 2.
****
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int, o primeiro argumento é módulo do segundo argumento. |
| Int/Decimal | Int/Decimal | Decimal, o primeiro argumento é módulo do segundo operando. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais, o resultado será o primeiro argumento como módulo do segundo argumento. Caso contrário, Undefined. |
| Outros valores | Outros valores | Undefined. |
## nanquim (,) AnyValue AnyValue
Gera o primeiro argumento se for um `Decimal` válido. Caso contrário, o segundo argumento é retornado. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `Nanvl(8, 3)` = 8.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Output |
| --- | --- | --- |
| Não definido | Qualquer valor | O segundo argumento. |
| Null | Qualquer valor | O segundo argumento. |
| Decimal (NaN) | Qualquer valor | O segundo argumento. |
| Decimal (não NaN) | Qualquer valor | O primeiro argumento. |
| Outros valores | Qualquer valor | O primeiro argumento. |
## newuuid()
Gera uma UUID aleatória de 16 bytes. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `newuuid()` = `123a4567-b89c-12d3-e456-789012345000`
## numbytes(String)
Gera o número de bytes na codificação UTF-8 da string fornecida. As regras padrão de conversão se aplicam a argumentos de não `String`. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`numbytes("hi")` = 2
`numbytes("€") ` = 3
## parse\$1time(String, Long, [String])
Use a `parse_time` função para formatar um carimbo de data/hora em um formato legível por humanos date/time . Compatível com a versão de 23/03/2016 do SQL e posteriores. Para converter uma string de carimbo de data/hora em milissegundos, consulte [time\$1to\$1epoch(String, String)](#iot-sql-function-time-to-epoch).
A função `parse_time` espera os seguintes argumentos:
pattern
(String) Um date/time padrão que segue os formatos [Joda-Time.](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html)
timestamp
(Long) O tempo a ser formatado em milissegundos desde o epoch do Unix. Consulte a função [timestamp()](#iot-function-timestamp).
timezone
(String) O fuso horário da data/hora formatada. O padrão é "UTC". A função oferece suporte para [fusos horários Joda-Time](http://joda-time.sourceforge.net/timezones.html). Esse argumento é opcional.
Exemplos:
Quando essa mensagem for publicada no tópico "A/B", a carga útil `{"ts": "1970.01.01 AD at 21:46:40 CST"}` será enviada para o bucket do 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"
}
}
```
Quando essa mensagem for publicada no tópico 'A/B', uma carga útil semelhante a `{"ts": "2017.06.09 AD at 17:19:46 UTC"}` (mas com data/hora atual) será enviada para o bucket 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()` também pode ser usado como um modelo de substituição. Por exemplo, quando esta mensagem for publicada no tópico "A/B", a carga útil será enviada para o bucket S3 com chave = "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)
Gera o primeiro argumento elevado ao segundo argumento. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `power(2, 5)` = 32,0.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Um Decimal (com precisão dupla), o primeiro argumento elevado para o poder do segundo argumento. |
| Int/Decimal/String | Int/Decimal/String | Um Decimal (com precisão dupla), o primeiro argumento elevado para o poder do segundo argumento. Quaisquer strings são convertidas em decimais. Se a conversão de alguma String em Decimal falhar, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## principal()
Retorna a entidade principal que o dispositivo usa para autenticação, com base em como a mensagem acionadora foi publicada. A tabela a seguir descreve a entidade principal retornada para cada protocolo e método de publicação.
****
| Como a mensagem é publicada | Protocolo | Tipo de credencial | Entidade principal |
| --- | --- | --- | --- |
| Cliente MQTT | MQTT | Certificado de dispositivo X.509 | Thumbprint do certificado X.509 |
| AWS IoT cliente MQTT do console | MQTT | Usuário ou perfil do IAM | iam-role-id:session-name |
| AWS CLI | HTTP | Usuário ou perfil do IAM | userid |
| AWS IoT SDK do dispositivo | MQTT | Certificado de dispositivo X.509 | Thumbprint do certificado X.509 |
| AWS IoT SDK do dispositivo | Acabou o MQTT WebSocket | Usuário ou perfil do IAM | userid |
Os exemplos a seguir mostram os diferentes tipos de valores que `principal()` pode retornar:
+ Thumbprint do certificado X.509: `ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373`
+ ID do perfil do IAM e nome da sessão: `ABCD1EFG3HIJK2LMNOP5:my-session-name`
+ Retorna um ID de usuário: `ABCD1EFG3HIJK2LMNOP5`
## rand()
Gera um pseudoaleatório, uniformemente distribuído entre 0,0 e 1,0. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`rand()` = 0,8231909191640703
## regexp\$1matches(String, String)
Retorna verdadeiro se a string (primeiro argumento) contiver uma correspondência para a expressão regular (segundo argumento). Se você usar `|` na expressão regular, use-a com `()`.
Exemplos:
`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.
**Primeiro argumento:**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| String | O String. |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined. |
*Segundo argumento:*
Deve ser uma expressão regex válida. Tipos de não string são convertidos em `String` usando as regras padrão de conversão. Dependendo do tipo, a string resultante pode não ser uma expressão regular válida. Se o argumento (convertido) não for uma regex válida, o resultado será `Undefined`.
## regexp\$1replace(String, String, String)
Substitui todas as ocorrências do segundo argumento (expressão regular) no primeiro argumento com o terceiro argumento. Faz referência a grupos de captura com "\$1". Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`regexp_replace("abcd", "bc", "x")` = "axd".
`regexp_replace("abcd", "b(.*)d", "$1")` = "ac".
**Primeiro argumento:**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| String | O valor de origem. |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined. |
*Segundo argumento:*
Deve ser uma expressão regex válida. Tipos de não string são convertidos em `String` usando as regras padrão de conversão. Dependendo do tipo, a string resultante pode não ser uma expressão regular válida. Se o argumento (convertido) não for uma expressão regex válida, o resultado será `Undefined`.
*Terceiro argumento:*
Deve ser uma string de substituição regex válida. (Pode fazer referência a grupos de captura.) Tipos de não string são convertidos em `String` usando as regras padrão de conversão. Se o argumento (convertido) não for uma string de substituição regex válida, o resultado será `Undefined`.
## regexp\$1substr(String, String)
Localiza a primeira correspondência do segundo parâmetro (regex) no primeiro parâmetro. Faz referência a grupos de captura com "\$1". Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`regexp_substr("hihihello", "hi")` = "hi"
`regexp_substr("hihihello", "(hi)*")` = "hihi"
**Primeiro argumento:**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| String | O argumento da String. |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined. |
*Segundo argumento:*
Deve ser uma expressão regex válida. Tipos de não string são convertidos em `String` usando as regras padrão de conversão. Dependendo do tipo, a string resultante pode não ser uma expressão regular válida. Se o argumento (convertido) não for uma expressão regex válida, o resultado será `Undefined`.
## remainder(Decimal, Decimal)
Gera o restante da divisão do primeiro argumento pelo segundo argumento. Equivale a [mod(Decimal, Decimal)](#iot-func-mod). Você também pode usar "%" como um operador infixo para a mesma funcionalidade do módulo. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `remainder(8, 3)` = 2.
****
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int, o primeiro argumento é módulo do segundo argumento. |
| Int/Decimal | Int/Decimal | Decimal, o primeiro argumento é módulo do segundo operando. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais, o resultado será o primeiro argumento como módulo do segundo argumento. Caso contrário, Undefined. |
| Outros valores | Outros valores | Undefined. |
## replace(String, String, String)
Substitui todas as ocorrências do segundo argumento no primeiro argumento com o terceiro argumento. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`replace("abcd", "bc", "x")` = `"axd"`.
`replace("abcdabcd", "b", "x")` = `"axcdaxcd"`.
**Todos os argumentos**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| String | O valor de origem. |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined. |
## rpad(String, Int)
Gera o argumento da string, preenchido no lado direito com o número de espaços especificado no segundo argumento. O argumento `Int` deve estar entre 0 e 1000. Se o valor fornecido estiver fora desse intervalo válido, o argumento será definido para o valor válido mais próximo (0 ou 1.000). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`rpad("hello", 2)` = "`hello `".
`rpad(1, 3)` = "`1 `".
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | Int | A String é preenchida no lado direito com um número de espaços igual ao Int fornecido. |
| String | Decimal | O argumento Decimal será arredondado para o Int abaixo mais próximo, e a string será preenchida no lado direito com um número de espaços igual ao Int fornecido. |
| String | String | O segundo argumento é convertido em um Decimal, que é arredondado para o Int mais próximo. A String é preenchida no lado direito com um número de espaços igual ao valor Int. |
| Outros valores | Int/Decimal/String | O primeiro valor será convertido em uma String usando as conversões padrão, e a função rpad será aplicada nessa String. Se não for possível fazer a conversão, o resultado será Undefined. |
| Qualquer valor | Outros valores | Undefined. |
## round(Decimal)
Arredonda o `Decimal` fornecido para o `Int` mais próximo. Se o `Decimal` for equidistante de dois valores `Int` (por exemplo, 0,5), o `Decimal` será arredondado. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `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 | O argumento. |
| Decimal | Decimal é arredondado para o Int abaixo mais próximo. |
| String | Decimal é arredondado para o Int abaixo mais próximo. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Outros valores | Undefined. |
## rtrim(String)
Remove todos os espaços em branco finais (caracteres de tabulação e espaços) da `String` fornecida. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`rtrim(" h i ")` = " h i"
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined |
## sign(Decimal)
Gera o sinal do número fornecido. Quando o sinal do argumento for positivo, 1 será gerado. Quando o sinal do argumento for negativo, -1 será gerado. Se o argumento for 0, 0 será gerado. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`sign(-7)` = -1.
`sign(0)` = 0.
`sign(13)` = 1.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, o sinal do valor Int. |
| Decimal | Int, o sinal do valor Decimal. |
| String | Int, o sinal do valor Decimal. A string é convertida em um valor Decimal, e o sinal do valor Decimal é gerado. Se a String não puder ser convertida em um Decimal, o resultado será Undefined. Compatível com a versão de 08/10/2015 do SQL e posteriores. |
| Outros valores | Undefined. |
## sin(Decimal)
Gera o seno de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `sin(0)` = 0,0
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o seno do argumento. |
| Decimal | Decimal (com precisão dupla), o seno do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o seno do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## sinh(Decimal)
Gera o seno hiperbólico de um número em radianos. Valores `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. O resultado é um valor `Decimal` de precisão dupla. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `sinh(2.3)` = 4,936961805545957
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o seno hiperbólico do argumento. |
| Decimal | Decimal (com precisão dupla), o seno hiperbólico do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o seno hiperbólico do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## sourceip()
Recupera o endereço IP de um dispositivo ou do roteador que se conecta a ele. Se o seu dispositivo estiver conectado diretamente à Internet, a função retornará o endereço IP de origem do dispositivo. Se o seu dispositivo estiver conectado a um roteador conectado à Internet, a função retornará o endereço IP de origem do dispositivo. Compatível com a versão SQL 23/03/2016. `sourceip()` não usa nenhum parâmetro.
**Importante**
O endereço IP de origem pública de um dispositivo geralmente é o endereço IP do último gateway de conversão de endereços de rede (NAT), como o roteador ou modem a cabo do seu provedor de serviços de Internet.
Exemplos:
`sourceip()="192.158.1.38"`
`sourceip()="1.102.103.104"`
`sourceip()="2001:db8:ff00::12ab:34cd"`
Exemplo de SQL:
`SELECT *, sourceip() as deviceIp FROM 'some/topic'`
Exemplos de como usar a função sourceip () em ações de AWS IoT Core regras:
**Exemplo 1**
O exemplo a seguir mostra como chamar a função () como [modelo de substituição](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) em uma ação do [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"
}
}
]
}
}
```
**Exemplo 2**
O exemplo a seguir mostra como adicionar a função sourceip() como uma propriedade de usuário do MQTT usando [modelos de substituição](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()}"
}
]
}
}
}
]
}
}
```
Você pode recuperar o endereço IP de origem das mensagens que passam para AWS IoT Core as regras dos caminhos do Message Broker e do [Basic Ingest](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html). Você também pode recuperar o IP de origem de ambos IPv4 e IPv6 das mensagens. O IP de origem será exibido da seguinte forma:
IPv6: `yyyy:yyyy:yyyy::yyyy:yyyy`
IPv4: `xxx.xxx.xxx.xxx`
**nota**
O IP de origem original não será transmitido pela [ação Republicar](republish-rule-action.md).
## substring(String, Int[, Int])
Espera uma `String` seguida de um ou dois valores `Int`. No caso de uma `String` e um único argumento `Int`, essa função gera a substring da `String` fornecida do índice `Int` fornecido (baseado em 0, inclusive) ao final da `String`. No caso de uma `String` e dois argumentos `Int`, essa função gera a substring da `String` fornecida no primeiro argumento de índice`Int` (baseado em 0, inclusive) para o segundo argumento de índice `Int` (baseado em 0, inclusive). Índices inferiores a zero são definidos como zero. Índices superiores ao comprimento da `String` são definidos para o comprimento da `String`. No caso da versão de argumento três, se o primeiro índice for superior ou igual ao segundo índice, o resultado será a `String` vazia.
Se os argumentos fornecidos não forem (*String*,*Int*) ou (*String*,*Int*,*Int*), as conversões padrão serão aplicadas aos argumentos para tentar convertê-los nos tipos corretos. Se os tipos não puderem ser convertidos, o resultado da função será `Undefined`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`substring("012345", 0)` = "012345".
`substring("012345", 2)` = "2345".
`substring("012345", 2.745)` = "2345".
`substring(123, 2)` = "3".
`substring("012345", -1)` = "012345".
`substring(true, 1.2)` = "rue".
`substring(false, -2.411E247)` = "false".
`substring("012345", 1, 3)` = "12".
`substring("012345", -50, 50)` = "012345".
`substring("012345", 3, 1)` = "".
## sql\$1version()
Retorna a versão SQL especificada nesta regra. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`sql_version()` = "23/03/2016"
## sqrt(Decimal)
Gera a raiz quadrada de um número. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `sqrt(9)` = 3,0.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A raiz quadrada do argumento. |
| Decimal | A raiz quadrada do argumento. |
| Boolean | Undefined. |
| String | A raiz quadrada do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## startswith(String, String)
Gera `Boolean`, independentemente de o primeiro argumento da string começar com o segundo argumento da string. Se um dos argumentos for `Null` ou `Undefined`, o resultado será `Undefined`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`startswith("ranger","ran")` = true
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | String | Independentemente de a primeira string começar com a segunda string. |
| Outros valores | Outros valores | Os dois argumentos são convertidos em strings usando as regras padrão de conversão. Retorna verdadeiro se independentemente de a primeira string começar com a segunda string. Se um dos argumentos for Null ou Undefined, o resultado será Undefined. |
## tan(Decimal)
Gera a tangente de um número em radianos. Valores `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `tan(3)` = -0,1425465430742778
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), a tangente do argumento. |
| Decimal | Decimal (com precisão dupla), a tangente do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), a tangente do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## tanh(Decimal)
Gera a tangente hiperbólica de um número em radianos. Valores `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `tanh(2.3)` = 0,9800963962661914
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), a tangente hiperbólica do argumento. |
| Decimal | Decimal (com precisão dupla), a tangente hiperbólica do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), a tangente hiperbólica do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## time\$1to\$1epoch(String, String)
Use a função `time_to_epoch` para converter uma string de timestamp em um número de milissegundos tempo de epoch do Unix. Compatível com a versão de 23/03/2016 do SQL e posteriores. Para converter milissegundos em uma string de carimbo de data/hora, consulte [parse\$1time(String, Long, [String])](#iot-sql-function-parse-time).
A função `time_to_epoch` espera os seguintes argumentos:
timestamp
(String) A string de carimbo de data/hora a ser convertida em milissegundos desde o epoch do Unix. Se a string do carimbo de data/hora não especificar um fuso horário, a função usará o fuso horário UTC.
pattern
(String) Um date/time padrão que segue [os formatos de JDK11 hora](http://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
Exemplos:
`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()
Retorna o timestamp atual em milissegundos a partir das 00:00:00 Horário Universal Coordenado (UTC), quinta-feira, 1º de janeiro de 1970, conforme observado pelo mecanismo de regras. AWS IoT Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `timestamp()` = `1481825251155`
## topic(Decimal)
Gera o tópico para o qual a mensagem que acionou a regra foi enviada. Se nenhum parâmetro for especificado, todo o tópico será gerado. O parâmetro `Decimal` é usado para especificar um segmento de tópico específico, com 1 designando o primeiro segmento. Para o tópico `foo/bar/baz`, topic(1) retornará `foo`, topic(2) retornará `bar`, e assim por diante. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`topic()` = "things/myThings/thingOne"
`topic(1)` = "objetos"
Quando a [Ingestão básica](iot-basic-ingest.md) for usada, o prefixo inicial do tópico (`$aws/rules/rule-name`) não estará disponível na função topic(). Por exemplo, considerando o tópico:
`$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`
`topic()` = "Buildings/Building5/Floor2/Room201/Lights"
`topic(3)` = "Floor2"
## traceid()
Gera o ID de rastreamento (UUID) da mensagem MQTT ou `Undefined` caso a mensagem não tenha sido enviada por MQTT. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`traceid() ` = "12345678-1234-1234-1234-123456789012"
## transform(String, Objeto, Matriz)
Retorna uma matriz de objetos que contém o resultado da transformação especificada do parâmetro `Object` no parâmetro `Array`.
Compatível com a versão de 23/03/2016 do SQL e posteriores.
String
O modo de transformação a ser usado. Consulte a tabela a seguir para ver os modos de transformação compatíveis e como eles criam os `Result` a partir dos parâmetros `Object` e `Array`.
Objeto
Um objeto que contém os atributos a serem aplicados a cada elemento do `Array`.
Array
Uma matriz de objetos nos quais os atributos de `Object` são aplicados.
Cada objeto nessa matriz corresponde a um objeto na resposta da função. Cada objeto na resposta da função contém os atributos presentes no objeto original e os atributos fornecidos por `Object`, conforme determinado pelo modo de transformação especificado na `String`.
| Parâmetro `String` | Parâmetro `Object` | Parâmetro `Array` | Resultado |
| --- | --- | --- | --- |
| `enrichArray` | Objeto | Matriz de objetos | Uma matriz de objetos na qual cada objeto contém os atributos de um elemento do parâmetro `Array` e os atributos do parâmetro `Object`. |
| Qualquer outro valor | Qualquer valor | Qualquer valor | Não definido |
**nota**
A matriz retornada por essa função está limitada a 128 KiB.
### Exemplo 1 da função de transformação
Este exemplo mostra como a função **transform()** produz uma única matriz de objetos a partir de um objeto de dados e uma matriz.
Neste exemplo, a mensagem a seguir é publicada no tópico `A/B` do MQTT.
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Essa instrução SQL para uma ação de regra de tópico usa a função **transform()** com um valor de `String` de `enrichArray`. Neste exemplo, `Object` é a propriedade de `attributes` da carga da mensagem e `Array` é a matriz de `values`, que contém três objetos.
```
select value transform("enrichArray", attributes, values) from 'A/B'
```
Ao receber a carga útil da mensagem, a instrução SQL avalia a seguinte resposta.
```
[
{
"a": 3,
"data1": 1,
"data2": 2
},
{
"b": 4,
"data1": 1,
"data2": 2
},
{
"c": 5,
"data1": 1,
"data2": 2
}
]
```
### Exemplo 2 da função de transformação
Este exemplo mostra como a função **transform()** pode usar valores literais para incluir e renomear atributos individuais da carga útil da mensagem.
Neste exemplo, a mensagem a seguir é publicada no tópico `A/B` do MQTT. Essa é a mesma mensagem que foi usada em [Exemplo 1 da função de transformação](#iot-func-transform-example1).
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Essa instrução SQL para uma ação de regra de tópico usa a função **transform()** com um valor de `String` de `enrichArray`. O `Object` na função **transform()** tem um único atributo chamado `key` com o valor de `attributes.data1` na carga útil da mensagem e `Array` é a matriz de `values`, que contém os mesmos três objetos usados no exemplo anterior.
```
select value transform("enrichArray", {"key": attributes.data1}, values) from 'A/B'
```
Ao receber a carga útil da mensagem, esta instrução SQL avalia a seguinte resposta. Observe como a propriedade `data1` é nomeada `key` na resposta.
```
[
{
"a": 3,
"key": 1
},
{
"b": 4,
"key": 1
},
{
"c": 5,
"key": 1
}
]
```
### Exemplo 3 da função de transformação
Este exemplo mostra como a função **transform()** pode ser usada em cláusulas SELECT aninhadas para selecionar vários atributos e criar novos objetos para processamento posterior.
Neste exemplo, a mensagem a seguir é publicada no tópico `A/B` do 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
}
]
}
}
```
O `Object` para esta função de transformação é o objeto retornado pela instrução SELECT, que contém os elementos `a` e `b` do objeto `data2` da mensagem. O parâmetro `Array` consiste nos dois objetos da matriz `data2.c` na mensagem original.
```
select value transform('enrichArray', (select a, b from data2), (select value c from data2)) from 'A/B'
```
Com a mensagem anterior, a instrução SQL avalia a seguinte resposta.
```
[
{
"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"
}
]
```
A matriz retornada nessa resposta pode ser usada com ações de regras de tópico compatíveis com `batchMode`.
## trim(String)
Remove todos os espaços em branco iniciais e finais da `String` fornecida. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`Trim(" hi ") ` = "hi"
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação de String de Int com todos os espaços em branco iniciais e finais removidos. |
| Decimal | A representação de String de Decimal com todos os espaços em branco iniciais e finais removidos. |
| Boolean | A representação de String de Boolean ("verdadeiro" ou "falso") com todos os espaços em branco iniciais e finais removidos. |
| String | A String com todos os espaços em branco iniciais e finais removidos. |
| Array | A representação da String da Array usando as regras padrão de conversão. |
| Objeto | A representação da String do Objeto usando as regras padrão de conversão. |
| Null | Undefined. |
| Não definido | Undefined. |
## trunc(Decimal, Int)
Trunca o primeiro argumento para o número de lugares `Decimal` especificado pelo segundo argumento. Se o segundo argumento for inferior a zero, ele será definido como zero. Se o segundo argumento for superior a 34, ele será definido como 34. Os zeros finais são removidos do resultado. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`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 | O valor de origem. |
| Int/Decimal | Int/Decimal | O primeiro argumento é truncado para o comprimento descrito pelo segundo argumento. O segundo argumento, se não for um Int, será arredondado para o Int abaixo mais próximo. |
| Int/Decimal/String | Int/Decimal | O primeiro argumento é truncado para o comprimento descrito pelo segundo argumento. O segundo argumento, se não for um Int, será arredondado para o Int abaixo mais próximo. A String é convertida em um valor Decimal. Se não for possível converter a string, o resultado será Undefined. |
| Outros valores | | Undefined. |
## upper(String)
Gera a versão em letra maiúscula da `String` fornecida. Os argumentos de não`String` são convertidos em `String` usando as regras de conversão padrão. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`upper("hello")` = "HELLO"
`upper(["hello"])` = "[\$1"HELLO\$1"]"
# Literais
Você pode especificar diretamente objetos literais nas cláusulas WHERE e SELECT da regra SQL, que pode ser útil para transmitir informações.
**nota**
Literais estão disponíveis somente ao usar a versão de 23/03/2016 do SQL ou posteriores.
A sintaxe de objeto JSON é usada (pares de chave-valor, separado por vírgula, em que as chaves são strings, e os valores são valores JSON, entre chaves \$1\$1). Por exemplo:
Carga útil de entrada publicada no tópico `topic/subtopic`: `{"lat_long": [47.606,-122.332]}`
Declaração do SQL: `SELECT {'latitude': get(lat_long, 0),'longitude':get(lat_long, 1)} as lat_long FROM 'topic/subtopic'`
A carga útil de saída resultante seria: `{"lat_long":{"latitude":47.606,"longitude":-122.332}}`.
Você também pode especificar diretamente matrizes nas cláusulas WHERE e SELECT da regra SQL, o que permite agrupar informações. A sintaxe JSON é usada (encapsular itens separados por vírgula entre colchetes [] para criar uma matriz literal). Por exemplo:
Carga útil de entrada publicada no tópico `topic/subtopic`: `{"lat": 47.696, "long": -122.332}`
Declaração do SQL: `SELECT [lat,long] as lat_long FROM 'topic/subtopic'`
A carga útil de saída resultante seria: `{"lat_long": [47.606,-122.332]}`.
# Declarações de caso
As declarações de caso podem ser usadas para execução de ramificação, como uma declaração de troca.
Sintaxe:
```
CASE v WHEN t[1] THEN r[1]
WHEN t[2] THEN r[2] ...
WHEN t[n] THEN r[n]
ELSE r[e] END
```
A expressão *`v`* é avaliada e comparada quanto à igualdade com o valor *`t[i]`* de cada cláusula `WHEN`. Se uma correspondência for encontrada, a expressão *`r[i]`* correspondente se tornará o resultado da declaração do `CASE`. As cláusulas `WHEN` são avaliadas em ordem para que, se houver mais de uma cláusula correspondente, o resultado da primeira cláusula correspondente se torne o resultado da declaração do `CASE`. Se não houver correspondências, *`r[e]`* da cláusula `ELSE` é o resultado. Se não houver correspondências e não houver cláusula `ELSE`, o resultado é `Undefined`.
As declarações de `CASE` exigem, pelo menos, uma cláusula `WHEN`. Qualquer cláusula `ELSE` é opcional.
Por exemplo:
Carga útil de entrada publicada no tópico `topic/subtopic`:
```
{
"color":"yellow"
}
```
Declaração do 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'
```
A carga útil de saída resultante seria:
```
{
"instructions":"caution"
}
```
**nota**
Se *`v`* for `Undefined`, o resultado da declaração do caso será `Undefined`.
# Extensões JSON
Você pode usar as seguintes extensões para a sintaxe SQL padrão ANSI para facilitar o trabalho com objetos JSON aninhados.
Operador "."
Esse operador acessa membros em objetos JSON incorporados e funciona de forma idêntica ao ANSI SQL e. JavaScript Por exemplo:
```
SELECT foo.bar AS bar.baz FROM 'topic/subtopic'
```
seleciona o valor da propriedade `bar` no objeto `foo` a partir da seguinte carga útil de mensagem enviada ao tópico `topic/subtopic`.
```
{
"foo": {
"bar": "RED",
"bar1": "GREEN",
"bar2": "BLUE"
}
}
```
Se o nome de uma propriedade JSON incluir um caractere de hífen ou caracteres numéricos, a notação 'ponto' não funcionará. Em vez disso, você deve usar a [função get](iot-sql-functions.md#iot-sql-function-get) para extrair o valor da propriedade.
Neste exemplo, a mensagem a seguir é enviada ao tópico `iot/rules`.
```
{
"mydata": {
"item2": {
"0": {
"my-key": "myValue"
}
}
}
}
```
Normalmente, o valor de `my-key` seria identificado como nessa consulta.
```
SELECT * from iot/rules WHERE mydata.item2.0.my-key= "myValue"
```
No entanto, como o nome da propriedade `my-key` contém um hífen e `item2` contém um caractere numérico, a [função get](iot-sql-functions.md#iot-sql-function-get) deve ser usada conforme mostra a consulta a seguir.
```
SELECT * from 'iot/rules' WHERE get(get(get(mydata,"item2"),"0"),"my-key") = "myValue"
```
`*`Operador
Funciona da mesma maneira que o caractere curinga `*` em SQL padrão ANSI. É usado somente na cláusula SELECT e cria outro objeto JSON contendo os dados da mensagem. Se a carga útil da mensagem não estiver no formato JSON, `*` gerará toda a carga útil da mensagem como bytes brutos. Por exemplo:
```
SELECT * FROM 'topic/subtopic'
```
**Como aplicar uma função a um valor de atributo**
Veja a seguir um exemplo de carga útil JSON que pode ser publicada por um dispositivo:
```
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
```
O exemplo a seguir aplica uma função a um valor de atributo em uma carga útil JSON:
```
SELECT temp, md5(deviceid) AS hashed_id FROM topic/#
```
O resultado dessa consulta é o seguinte objeto JSON:
```
{
"temp": 54.98,
"hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"
}
```
# Modelos de substituição
Você pode usar um modelo de substituição para aumentar os dados JSON retornados quando uma regra é acionada e AWS IoT executa uma ação. A sintaxe de um modelo de substituição é `${` *expressão`}`, em que expressão* pode ser qualquer *expressão* suportada AWS IoT nas cláusulas SELECT, nas cláusulas WHERE e. [AWS IoT ações de regras](iot-rule-actions.md) Essa expressão pode ser conectada a um campo de ação em uma regra, permitindo que você configure dinamicamente uma ação. Na verdade, esse recurso substitui uma informação em uma ação. Isso inclui funções, operadores e informações presentes na carga da mensagem original.
**Importante**
Como uma expressão em um modelo de substituição é avaliada separadamente da instrução "SELECT...", você não pode fazer referência a um alias criado com a cláusula AS. Você pode fazer referência somente às informações presentes na carga original, além das [funções](iot-sql-functions.md) e dos [operadores](iot-sql-operators.md) compatíveis.
Para obter mais informações sobre as expressões compatíveis, consulte [AWS IoT Referência SQL](iot-sql-reference.md).
As ações de regra a seguir oferecem suporte a modelos de substituição. Cada ação oferece suporte a campos diferentes que podem ser substituídos.
+ [Apache Kafka](apache-kafka-rule-action.md)
+ [CloudWatch alarmes](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)
+ [Dínamo 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)
+ [Local](location-rule-action.md)
+ [OpenSearch](opensearch-rule-action.md)
+ [Nova publicação](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)
Os modelos de substituição aparecem nos parâmetros de ação dentro de uma regra:
```
{
"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"
}
}]
}
```
Se essa regra for acionada pelo JSON a seguir publicado em `my/iot/topic`:
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
}
}
```
Em seguida, essa regra publica o seguinte JSON em`my/iot/topic/republish`, que AWS IoT substitui de: `${topic()}/republish`
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
},
"timestamp": 1579637878451
}
```
# Consultas de objeto aninhado
Você pode usar cláusulas SELECT aninhadas para consultar atributos dentro de matrizes e objetos JSON internos. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Considere a seguinte mensagem 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**
Você pode converter valores em uma nova matriz com a seguinte regra.
```
SELECT (SELECT VALUE n FROM e) as sensors FROM 'my/topic'
```
A regra gera a seguinte saída:
```
{
"sensors": [
"temperature",
"light",
"acidity"
]
}
```
**Example**
Usando a mesma mensagem MQTT, você também pode consultar um valor específico dentro de um objeto aninhado com a seguinte regra.
```
SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'
```
A regra gera a seguinte saída:
```
{
"temperature": [
{
"v": 22.5
}
]
}
```
**Example**
Você também pode nivelar a saída com uma regra mais complicada.
```
SELECT get((SELECT v FROM e WHERE n = 'temperature'), 0).v as temperature FROM 'topic'
```
A regra gera a seguinte saída:
```
{
"temperature": 22.5
}
```
# Como trabalhar com cargas úteis binárias
Para tratar a carga da mensagem como dados binários brutos (em vez de um objeto JSON), você pode usar o operador \$1 para fazer referência a ela em uma cláusula SELECT.
**Topics**
+ [
## Exemplos de cargas úteis binárias
](#binary-payloads-examples)
+ [
## Decodificar as cargas úteis da mensagem protobuf
](#binary-payloads-protobuf)
## Exemplos de cargas úteis binárias
Ao usar \$1 para se referir à carga da mensagem como dados binários brutos, você pode adicionar dados à regra. Se você tiver uma carga vazia ou JSON, a carga resultante poderá ter dados adicionados usando a regra. Veja a seguir exemplos de cláusulas `SELECT` compatíveis.
+ Você pode usar as cláusulas `SELECT` a seguir com apenas um \$1 para cargas binárias.
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ Você também pode adicionar dados e usar as cláusulas `SELECT` a seguir.
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ Você também pode usar essas cláusulas `SELECT` com cargas binárias.
+ O seguinte se refere ao `device_type` na cláusula WHERE.
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ Também há suporte para:
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
As ações de regra a seguir não oferecem suporte a cargas binárias, portanto, você deve decodificá-las.
+ Algumas ações de regra não oferecem suporte a entrada de carga útil binária, como a [ação do Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule), então é necessário decodificar cargas úteis binárias. A ação de regra do Lambda poderá receber dados binários se estiverem codificados em base64 e em uma carga útil JSON. É possível fazer isso alterando a regra para a seguinte:
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ A instrução SQL não oferece suporte a string como entrada. Para converter uma entrada de string em JSON, é possível executar o seguinte comando.
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## Decodificar as cargas úteis da mensagem protobuf
[Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers) é um formato de dados de código aberto usado para serializar dados estruturados em um formato binário compacto. É usado para transmitir dados por redes ou armazená-los em arquivos. O Protobuf permite que você envie dados em pacotes pequenos e em uma taxa mais rápida do que outros formatos de mensagens. AWS IoT Core As regras oferecem suporte ao protobuf fornecendo a função SQL [decode (value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64), que permite decodificar cargas de mensagens codificadas por protobuf para o formato JSON e roteá-las para serviços downstream. Esta seção detalha o step-by-step processo para configurar a decodificação do protobuf em Regras. AWS IoT Core
**Topics**
+ [
### Pré-requisitos
](#binary-payloads-protobuf-prerequisites)
+ [
### Criar arquivos descritores
](#binary-payloads-protobuf-descriptor-steps)
+ [
### Upload de arquivos descritores em um bucket do S3
](#binary-payloads-protobuf-s3-steps)
+ [
### Configurar a decodificação do protobuf em Regras
](#binary-payloads-protobuf-steps)
+ [
### Limitações
](#binary-payloads-protobuf-limitations)
+ [
### Práticas recomendadas
](#binary-payloads-protobuf-bestpractices)
### Pré-requisitos
+ Uma compreensão básica dos [Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers)
+ Os [arquivos `.proto`](https://developers.google.com/protocol-buffers/docs/proto3) que definem os tipos de mensagens e dependências relacionadas
+ Instalação do [compilador Protobuf (protoc)](https://github.com/protocolbuffers/protobuf/releases) em seu sistema
### Criar arquivos descritores
Se já tiver arquivos de descrição, você poderá ignorar esta etapa. Um arquivo descritor (`.desc`) é uma versão compilada de um arquivo `.proto`, que é um arquivo de texto que define as estruturas de dados e os tipos de mensagens a serem usados em uma serialização do protobuf. Para gerar um arquivo descritor, você deve definir um arquivo `.proto` e usar o compilador [protoc](https://github.com/protocolbuffers/protobuf/releases) para compilá-lo.
1. Crie arquivos `.proto` que definam os tipos de mensagem. Um exemplo de arquivo `.proto` pode ser o seguinte:
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
Neste exemplo de arquivo `.proto`, você usa a sintaxe proto3 e define o tipo de mensagem `Person`. A definição da mensagem `Person` especifica três campos (nome, ID e e-mail). Para obter mais informações sobre formatos de mensagem de arquivo `.proto`, consulte o [Guia de idiomas (proto3)](https://developers.google.com/protocol-buffers/docs/proto3).
1. Use o compilador [protoc](https://github.com/protocolbuffers/protobuf/releases) para compilar os arquivos `.proto` e gerar um arquivo descritor. Um exemplo de comando para criar um arquivo descritor (`.desc`) pode ser o seguinte:
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
Esse exemplo de comando gera um arquivo descritor`.desc`, que o AWS IoT Core Rules pode usar para decodificar cargas de protobuf que estejam em conformidade com a estrutura de dados definida em. `.proto`
+ `--descriptor_set_out`
Especifica o nome do arquivo descritor (`.desc`) que deve ser gerado.
+ `--proto_path`
Especifica os locais de todos os arquivos `.proto` importados referenciados pelo arquivo que está sendo compilado. Você pode especificar o sinalizador várias vezes se tiver vários arquivos `.proto` importados com locais diferentes.
+ `--include_imports`
Especifica que todos os arquivos `.proto` importados também devem ser compilados e incluídos no arquivo `.desc` descritor.
+ `.proto`
Especifica o nome do arquivo `.proto` que você deseja compilar.
Para obter mais informações sobre a referência protoc, consulte [Referência de API](https://developers.google.com/protocol-buffers/docs/reference/overview).
### Upload de arquivos descritores em um bucket do S3
Depois de criar seus arquivos descritores`.desc`, faça o upload dos arquivos `.desc` descritores em um bucket do Amazon S3 usando AWS a API AWS , o SDK ou o. Console de gerenciamento da AWS
**Considerações importantes**
+ Certifique-se de carregar os arquivos do descritor em um bucket do Amazon S3 no Região da AWS mesmo local em que você pretende configurar Conta da AWS suas regras.
+ Certifique-se de conceder AWS IoT Core acesso para ler o `FileDescriptorSet` do S3. Se o seu bucket do S3 tiver a criptografia do lado do servidor (SSE) desativada ou se o bucket do S3 estiver criptografado usando chaves gerenciadas pelo Amazon S3 (SSE-S3), nenhuma configuração adicional de política será necessária. Isso pode ser feito com o exemplo de política de bucket:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ Se o bucket do S3 for criptografado usando uma AWS Key Management Service chave (SSE-KMS), certifique-se de conceder AWS IoT Core permissão para usar a chave ao acessar o bucket do S3. Você pode fazer isso adicionando esta declaração à sua política de chave:
```
{
"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 a decodificação do protobuf em Regras
Depois de fazer o upload dos arquivos do descritor no bucket do Amazon S3, configure uma [regra](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html) que possa decodificar o formato de carga útil da mensagem protobuf usando a função SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64). Uma assinatura de função detalhada e um exemplo podem ser encontrados na função SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) da *referência SQL de AWS IoT *.
Veja a seguir um exemplo de expressão SQL usando a função [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64):
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
Neste exemplo de expressão:
+ Você usa a função SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) para decodificar a carga útil da mensagem binária referenciada por `*`. Isso pode ser uma carga binária codificada por protobuf ou uma string JSON que representa uma carga útil protobuf codificada em base64.
+ A carga útil da mensagem fornecida é codificada usando o tipo de mensagem `Person` definido em `PROTO_FILENAME.proto`.
+ O bucket do Amazon S3 chamado `BUCKET NAME` contém o `FILENAME.desc` gerado de `PROTO_FILENAME.proto`.
Depois de concluir a configuração, publique uma mensagem no tópico AWS IoT Core no qual a Regra está inscrita.
### Limitações
AWS IoT Core As regras oferecem suporte ao protobuf com as seguintes limitações:
+ A decodificação de cargas de mensagens protobuf em [modelos de substituição](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) não é suportada.
+ Ao decodificar cargas de mensagens protobuf, você pode usar a [função decodificar SQL](iot-sql-functions.md#iot-sql-decode-base64) em uma única expressão SQL até duas vezes.
+ O tamanho máximo da carga útil de entrada é 128 KiB (1 KiB = 1024 bytes), o tamanho máximo da carga de saída é 128 KiB e o tamanho máximo de um objeto `FileDescriptorSet` armazenado em um bucket do Amazon S3 é 32 KiB.
+ Não há suporte para buckets do Amazon S3 criptografados com a criptografia SSE-C.
### Práticas recomendadas
Veja a seguir algumas práticas recomendadas e dicas de solução de problemas.
+ Carregue seus arquivos proto no bucket no Amazon S3.
É uma prática recomendada fazer backup de seus arquivos proto caso algo dê errado. Por exemplo, se você modificar incorretamente os arquivos proto sem backups ao executar protoc, isso pode causar problemas em sua pilha de produção. Há várias maneiras de fazer backup de arquivos em um bucket do Amazon S3. Por exemplo, você pode [usar o versionamento em buckets do S3](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html). Para obter mais informações sobre como fazer backup de arquivos em buckets do Amazon S3, consulte o *[Guia do desenvolvedor do Amazon S3](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*.
+ Configure o AWS IoT registro para visualizar as entradas do registro.
É uma boa prática configurar o AWS IoT registro para que você possa verificar AWS IoT os registros da sua conta CloudWatch. Quando a consulta SQL de uma regra chama uma função externa, o AWS IoT Core Rules gera uma entrada de registro com um `eventType` de`FunctionExecution`, que contém o campo de motivo que o ajudará a solucionar falhas. Os possíveis erros incluem um objeto do Amazon S3 não encontrado ou um descritor de arquivo protobuf inválido. Para obter mais informações sobre como configurar o registro de AWS IoT e ver as entradas de log, consulte [Configurar o registro de AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html) e [Entradas de log do mecanismo de regras](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec).
+ Atualize o `FileDescriptorSet` usando uma nova chave de objeto e atualize a chave de objeto em sua regra.
Você pode atualizar o `FileDescriptorSet` fazendo upload de um arquivo de descritor atualizado para o seu bucket do Amazon S3. Suas atualizações do `FileDescriptorSet` podem levar até 15 minutos para serem refletidas. Para evitar esse atraso, é uma prática recomendada carregar seu `FileDescriptorSet` atualizado usando uma nova chave de objeto e atualizar a chave de objeto em sua regra.
# Versões do SQL
O mecanismo de AWS IoT regras usa uma sintaxe semelhante ao SQL para selecionar dados das mensagens MQTT. As instruções SQL são interpretadas com base em uma versão do SQL especificada com a propriedade `awsIotSqlVersion` em um documento JSON que descreve a regra. Para obter mais informações sobre a estrutura de documentos de regra JSON, consulte [Como criar uma regra](iot-create-rule.md). A `awsIotSqlVersion` propriedade permite especificar qual versão do mecanismo de regras AWS IoT SQL você deseja usar. Quando uma nova versão é implantada, você pode continuar usando uma versão mais antiga ou alterar a regra para usar a nova versão. As regras atuais continuam a usar a versão com a qual foram criadas.
O seguinte exemplo de JSON mostra como especificar a versão do SQL usando a propriedade `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 atualmente oferece suporte às seguintes versões do SQL:
+ `2016-03-23` – A versão SQL implantada em 23/03/2016 (recomendada).
+ `2015-10-08` – A versão original do SQL implantada em 08/10/2015.
+ `beta` – A versão beta mais recente do SQL. Essa versão pode causar alterações nas regras.
## Novidades da versão 23/03/2016 do mecanismo de regras SQL
+ Correções na seleção de objetos JSON aninhados.
+ Correções em consultas de matrizes.
+ Suporte para consulta entre objetos. Para obter mais informações, consulte [Consultas de objeto aninhado](iot-sql-nested-queries.md).
+ Suporte para emitir uma matriz como um objeto de nível superior.
+ Adição da função `encode(value, encodingScheme)`, que pode ser aplicada em dados em formato JSON e não JSON. Para obter mais informações, consulte a [função de codificação](iot-sql-functions.md#iot-sql-encode-payload).
### Resultado de uma `Array` como um objeto de nível superior
Esse recurso permite que uma regra gere uma matriz como um objeto de nível superior. Por exemplo, com base na seguinte mensagem MQTT:
```
{
"a": {"b":"c"},
"arr":[1,2,3,4]
}
```
E a seguinte regra:
```
SELECT VALUE arr FROM 'topic'
```
A regra gera a seguinte saída:
```
[1,2,3,4]
```