Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# AWS IoT Riferimento SQL
Nel AWS IoT, le regole vengono definite utilizzando una sintassi simile a SQL. Le istruzioni SQL sono costituite da tre tipi di clausole:
**SET**
(Facoltativo) Definisce le variabili che è possibile riutilizzare nelle istruzioni SQL e nei modelli di sostituzione. Assegna valori alle variabili utilizzando espressioni. Fai riferimento a queste variabili nelle clausole SELECT e WHERE e nei modelli di sostituzione delle azioni.
[La clausola SET supporta[Tipi di dati](iot-sql-data-types.md),,,, [Operatori](iot-sql-operators.md)[Funzioni](iot-sql-functions.md)[Valori letterali](iot-sql-literals.md)[Istruzioni case](iot-sql-case.md), [Estensioni JSON](iot-sql-json.md) Variables e.](iot-sql-set.md#iot-sql-set-usage) [Query di oggetti nidificati](iot-sql-nested-queries.md)
**SELECT**
(Obbligatorio) Estrae le informazioni dal payload del messaggio in ingresso ed esegue le trasformazioni sulle informazioni. I messaggi da utilizzare sono identificati dal [Filtro di argomenti](topics.md#topicfilters) specificato nella clausola FROM.
La clausola SELECT supporta [Tipi di dati](iot-sql-data-types.md)[Operatori](iot-sql-operators.md),,[Funzioni](iot-sql-functions.md),[Valori letterali](iot-sql-literals.md),[Istruzioni case](iot-sql-case.md), [Estensioni JSON](iot-sql-json.md) [Modelli di sostituzione](iot-substitution-templates.md)[Query di oggetti nidificati](iot-sql-nested-queries.md), [Variables](iot-sql-set.md#iot-sql-set-usage) e. [Payload binari](binary-payloads.md)
**FROM**
Il messaggio MQTT [Filtro di argomenti](topics.md#topicfilters) che identifica i messaggi da cui estrarre i dati. La regola viene attivata per ogni messaggio inviato a un argomento MQTT che corrisponde al filtro argomento specificato qui. Obbligatorio per le regole che vengono attivate da messaggi che attraversano il broker di messaggi. Facoltativo per le regole che vengono attivate solo utilizzando la caratteristica [Basic Ingest](iot-basic-ingest.md).
**WHERE**
(Facoltativo) Aggiunge una logica condizionale che determina se le operazioni specificate da una regola vengono eseguite.
La clausola WHERE supporta[Tipi di dati](iot-sql-data-types.md),[Operatori](iot-sql-operators.md),[Funzioni](iot-sql-functions.md),[Valori letterali](iot-sql-literals.md), [Istruzioni case](iot-sql-case.md)[Estensioni JSON](iot-sql-json.md), [Variables](iot-sql-set.md#iot-sql-set-usage) e. [Query di oggetti nidificati](iot-sql-nested-queries.md)
Un'istruzione SQL di esempio è simile a quanto segue:
```
SELECT color AS rgb FROM 'topic/subtopic' WHERE temperature > 50
```
Un messaggio MQTT di esempio (detto anche payload in ingresso) è simile a quanto segue:
```
{
"color":"red",
"temperature":100
}
```
Se questo messaggio viene pubblicato nell'argomento `'topic/subtopic'`, la regola viene attivata e l'istruzione SQL viene valutata. L'istruzione SQL estrae il valore della proprietà `color` se la proprietà `"temperature"` è superiore a 50. La clausola WHERE specifica la condizione `temperature > 50`. La parola chiave `AS` rinomina la proprietà `"color"` in `"rgb"`. Il risultato (detto anche *payload in uscita*) è simile al seguente:
```
{
"rgb":"red"
}
```
Questi dati vengono quindi inoltrati all'operazione della regola, che invia i dati per l'ulteriore elaborazione. Per ulteriori informazioni sulle operazioni delle regole, consulta [AWS IoT azioni relative alle regole](iot-rule-actions.md).
**Nota**
I commenti non sono attualmente supportati nella sintassi AWS IoT SQL.
I nomi degli attributi che contengono spazi non possono essere utilizzati come nomi di campo nell'istruzione SQL. Il payload in entrata può avere nomi di attributi contenenti spazi, ma tali nomi non possono essere utilizzati nell'istruzione SQL. Tuttavia, vengono passati al payload in uscita se utilizzi una specifica jolly (\$1) per il nome del campo.
# Clausola SELECT
La clausola AWS IoT SELECT è essenzialmente la stessa della clausola ANSI SQL SELECT, con alcune differenze minori.
La clausola SELECT supporta[Tipi di dati](iot-sql-data-types.md),,[Operatori](iot-sql-operators.md),[Funzioni](iot-sql-functions.md), [Valori letterali](iot-sql-literals.md) [Istruzioni case](iot-sql-case.md)[Estensioni JSON](iot-sql-json.md), [Variables](iot-sql-set.md#iot-sql-set-usage) e. [Query di oggetti nidificati](iot-sql-nested-queries.md) [Payload binari](binary-payloads.md)
È possibile usare la clausola SELECT per estrarre informazioni dai messaggi MQTT in ingresso. È inoltre possibile utilizzare `SELECT *` per recuperare l'intero payload del messaggio in arrivo. Ad esempio:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT * FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50}
```
Se il payload è un oggetto JSON, è possibile fare riferimento alle chiavi nell'oggetto. Il payload in uscita contiene la coppia chiave-valore. Ad esempio:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT color FROM 'topic/subtopic'
Outgoing payload: {"color":"red"}
```
È possibile usare la parola chiave AS per rinominare le chiavi. Ad esempio:
```
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"}
```
È possibile selezionare più elementi separandoli con una virgola. Ad esempio:
```
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}
```
È possibile selezionare più elementi includendo "\$1" per aggiungere gli elementi al payload in ingresso. Ad esempio:
```
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}
```
È possibile usare la parola chiave `"VALUE"` per produrre payload in uscita che non sono oggetti JSON. Con SQL versione `2015-10-08`, è possibile selezionare solo un elemento. Con SQL versione `2016-03-23` o successiva, è anche possibile selezionare una matrice da produrre come oggetto di primo livello.
**Example**
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT VALUE color FROM 'topic/subtopic'
Outgoing payload: "red"
```
È possibile usare la sintassi `'.'` per analizzare in maggiore dettaglio gli oggetti JSON nidificati nel payload in ingresso. Ad esempio:
```
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}
```
Per informazioni su come utilizzare i nomi degli oggetti e delle proprietà JSON che includono caratteri riservati, ad esempio i numeri o il trattino (meno), consulta [Estensioni JSON](iot-sql-json.md)
È possibile usare le funzioni (consulta [Funzioni](iot-sql-functions.md)) per trasformare il payload in ingresso. È possibile utilizzare le parentesi per il raggruppamento. Ad esempio:
```
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"}
```
# Clausola FROM
La clausola FROM esegue la sottoscrizione della regola in un [argomento](topics.md#topicnames) or [filtro argomenti](topics.md#topicfilters). L'argomento o il filtro dell’argomento deve essere racchiuso tra virgolette singole ('). La regola viene attivata per ogni messaggio inviato a un argomento MQTT che corrisponde al filtro argomento specificato qui. Esegui la sottoscrizione di un gruppo di argomenti simili utilizzando un filtro di argomenti.
**Esempio**:
Payload in ingresso pubblicato nell'argomento `'topic/subtopic'`: `{temperature: 50}`
Payload in ingresso pubblicato nell'argomento `'topic/subtopic-2'`: `{temperature: 50}`
SQL: `"SELECT temperature AS t FROM 'topic/subtopic'"`.
La regola è sottoscritta in `'topic/subtopic'`, quindi il payload in ingresso viene passato alla regola. Il payload in uscita, passato alle operazioni della regola, è: `{t: 50}`. La regola non viene sottoscritta in `'topic/subtopic-2'`, quindi la regola non viene attivata per il messaggio pubblicato in `'topic/subtopic-2'`.
**Esempio di carattere jolly \$1:**
Puoi utilizzare il carattere jolly '\$1' (multi-livello) per la corrispondenza con uno o più elementi del percorso particolari:
Payload in ingresso pubblicato nell'argomento `'topic/subtopic'`: `{temperature: 50}`.
Payload in ingresso pubblicato nell'argomento `'topic/subtopic-2'`: `{temperature: 60}`.
Payload in ingresso pubblicato nell'argomento `'topic/subtopic-3/details'`: `{temperature: 70}`.
Payload in ingresso pubblicato nell'argomento `'topic-2/subtopic-x'`: `{temperature: 80}`.
SQL: `"SELECT temperature AS t FROM 'topic/#'"`.
La regola è sottoscritta a qualsiasi argomento che inizia con`'topic'`, quindi viene eseguita tre volte, inviando payload in uscita di (per argomento/sottoargomento), `{t: 50}` (per argomento/subtopic-2) e `{t: 60}` (per) alle relative azioni. `{t: 70}` topic/subtopic-3/details La regola non viene sottoscritta in `'topic-2/subtopic-x'`, pertanto non viene attivata per il messaggio `{temperature: 80}`.
**Esempio di carattere jolly \$1:**
Puoi utilizzare il carattere jolly '\$1' (livello singolo) per la corrispondenza con qualsiasi elemento del percorso particolare:
Payload in ingresso pubblicato nell'argomento `'topic/subtopic'`: `{temperature: 50}`.
Payload in ingresso pubblicato nell'argomento `'topic/subtopic-2'`: `{temperature: 60}`.
Payload in ingresso pubblicato nell'argomento `'topic/subtopic-3/details'`: `{temperature: 70}`.
Payload in ingresso pubblicato nell'argomento `'topic-2/subtopic-x'`: `{temperature: 80}`.
SQL: `"SELECT temperature AS t FROM 'topic/+'"`.
La regola viene sottoscritta in tutti gli argomenti con due elementi di percorso, dove il primo elemento è `'topic'`. La regola viene eseguita per i messaggi inviati a `'topic/subtopic'` e `'topic/subtopic-2'`, ma non a `'topic/subtopic-3/details'` (ha più livelli rispetto al filtro argomento) o a `'topic-2/subtopic-x'` (non inizia con `topic`).
# Clausola SET
Utilizzate la clausola SET per definire le variabili che memorizzano i risultati delle espressioni. È possibile riutilizzare queste variabili nelle clausole SELECT e WHERE e nei modelli sostitutivi. Ciò consente di evitare la duplicazione di espressioni complesse e di ridurre il numero di chiamate di funzione nell'istruzione SQL.
La clausola SET supporta[Tipi di dati](iot-sql-data-types.md),,[Operatori](iot-sql-operators.md),[Funzioni](iot-sql-functions.md), [Valori letterali](iot-sql-literals.md) [Istruzioni case](iot-sql-case.md)[Estensioni JSON](iot-sql-json.md), [Variabili](#iot-sql-set-usage) e. [Query di oggetti nidificati](iot-sql-nested-queries.md)
## Sintassi della clausola SET
La clausola SET deve comparire prima della clausola SELECT nell'istruzione SQL. Utilizzare la seguente sintassi:
```
SET @variable_name = expression [, @variable_name2 = expression2]
```
Regole di sintassi:
+ Inizia i nomi delle variabili con `@`
+ I nomi delle variabili possono contenere lettere, numeri e caratteri di sottolineatura
+ I nomi delle variabili possono avere una lunghezza massima di 64 caratteri
+ È possibile impostare più variabili in una singola clausola SET, separate da virgole
+ Ogni variabile può essere assegnata una sola volta (le variabili sono immutabili)
+ La parola chiave SET può essere utilizzata solo una volta per istruzione SQL
## Utilizzo di variabili
Dopo aver definito le variabili, puoi usarle in:
+ Clausole SELECT
+ Clausole WHERE
+ Altre assegnazioni di variabili SET
+ Modelli di sostituzione delle azioni
+ Modelli di sostituzione delle azioni di errore
+ Interrogazioni SELECT annidate
+ Parametri delle funzioni (alcuni parametri come i parametri ROLearn e i parametri che modificano la modalità di una funzione in modo simile a `transform("enrichArray", attributes, values)` non supportare le variabili)
Le variabili vengono referenziate utilizzando la stessa `@variable_name` sintassi utilizzata nella clausola SET. È inoltre possibile utilizzare la sintassi dell'estensione JSON per accedere alle proprietà delle variabili che contengono oggetti, ad esempio. `@variable_name.property`
## Esempi di clausole SET
**Utilizzo delle variabili di base**
L'esempio seguente mostra un payload pubblicato sull'argomento`device/data`: `{"temp_fahrenheit": 75, "humidity": 60}`
Istruzione SQL:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Payload in uscita: `{"celsius": 23.89, "humidity": 60}`
**Accedi ai membri negli oggetti JSON incorporati**
L'esempio seguente mostra un payload pubblicato sull'argomento: `device/data` `{"device1": {"deviceId":"weather_sensor", "deviceData": {"sensors": {"temp_fahrenheit": 75, "humidity": 60}, "location": [47.606,-122.332]}}}`
Istruzione 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'
```
Payload in uscita: `{"temp_fahrenheit":75,"humidity":60,"deviceId":"weather_sensor"}`
per ulteriori informazioni su come lavorare con le estensioni JSON, consulta [Estensioni JSON](iot-sql-json.md)
**Evitare chiamate di funzione duplicate**
Le variabili SET aiutano a evitare la duplicazione di operazioni di decodifica complesse:
```
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
```
Senza le variabili SET, sarebbe necessario ripetere la funzione di decodifica tre volte, il che supera i limiti di chiamata alla funzione.
**Variabili multiple**
È possibile definire più variabili in una singola clausola SET separandole con virgole:
```
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
```
**Utilizzo di variabili nei modelli sostitutivi**
Le variabili possono essere utilizzate anche nei modelli di sostituzione delle azioni, che consentono di riutilizzare i valori calcolati sia nell'istruzione SQL che nelle azioni delle regole.
Istruzione SQL:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Configurazione dell'azione:
```
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/testRuleRole",
"bucketName": "bucket",
"key": "temperature-data/${device_id}/temp-${@temp_celsius}C.json"
}
}
```
In questo esempio, la variabile SET `@temp_celsius` viene utilizzata in un modello sostitutivo per costruire il campo chiave dell'azione S3.
**Utilizzo di payload non JSON**
Le variabili SET non supportano direttamente payload non JSON, quindi il payload deve essere prima codificato o decodificato:
```
SET @encoded_payload = encode(*, 'base64')
SELECT @encoded_payload AS raw_data FROM 'device/binary'
```
per ulteriori informazioni su come lavorare con payload non JSON, consulta [Utilizzo di payload binari](binary-payloads.md)
## Limiti della clausola SET
I seguenti limiti si applicano alle variabili SET:
+ Massimo 10 variabili univoche per istruzione SQL
+ Dimensione massima del valore variabile di 128 KiB (stringa JSON UTF-8 minimizzata)
+ Dimensione massima del valore totale di 128 KB per tutte le variabili
+ Nomi di variabili limitati a 64 caratteri
+ Le variabili possono accettare i payload JSON direttamente così come sono (i payload non JSON devono prima essere codificati/decodificati)
# Clausola WHERE
La clausola WHERE determina se le operazioni specificate da una regola vengono eseguite. Se la clausola WHERE restituisce true, le operazioni della regola vengono eseguite. In caso contrario, le operazioni della regola non vengono eseguite.
La clausola WHERE supporta[Tipi di dati](iot-sql-data-types.md),[Operatori](iot-sql-operators.md),[Funzioni](iot-sql-functions.md),[Valori letterali](iot-sql-literals.md), [Istruzioni case](iot-sql-case.md)[Estensioni JSON](iot-sql-json.md), [Variables](iot-sql-set.md#iot-sql-set-usage) e. [Query di oggetti nidificati](iot-sql-nested-queries.md)
**Esempio**:
Payload in ingresso pubblicato in `topic/subtopic`: `{"color":"red", "temperature":40}`.
SQL: `SELECT color AS my_color FROM 'topic/subtopic' WHERE temperature > 50 AND color <> 'red'`.
In questo caso la regola verrebbe attivata, ma non verrebbero eseguite le operazioni specificate dalla regola. Non ci sarà alcun payload in uscita.
È possibile usare le funzioni e gli operatori nella clausola WHERE. Tuttavia, non è possibile fare riferimento agli alias creati con la parola chiave AS in SELECT. La clausola WHERE viene valutata per prima, per determinare se la clausola SELECT viene valutata.
**Esempio con payload non JSON:**
Payload non JSON in entrata pubblicato su `topic/subtopic`: `80`
SQL: ``SELECT decode(encode(*, 'base64'), 'base64') AS value FROM 'topic/subtopic' WHERE decode(encode(*, 'base64'), 'base64') > 50`
In questo caso la regola verrebbe attivata, ma non verrebbero eseguite le operazioni specificate dalla regola. Il payload in uscita verrà trasformato dalla clausola SELECT come payload JSON `{"value":80}`.
# Tipi di dati
Il motore AWS IoT delle regole supporta tutti i tipi di dati JSON.
**Tipi di dati supportati**
| Tipo | Significato |
| --- | --- |
| Int | Un discreto Int. 34 cifre al massimo. |
| Decimal | Tipo `Decimal` con una precisione di 34 cifre, con grandezza minima diversa da zero corrispondente a 1E-999 e grandezza massima di 9.999…E999. Alcune funzioni restituiscono valori `Decimal` a precisione doppia invece di 34 cifre di precisione. Con SQL V2 (23/03/2016), valori numerici che sono numeri interi, come `10.0`, vengono elaborati come un valore `Int` (`10`) invece del previsto valore `Decimal` (`10.0`). Per elaborare in modo affidabile valori numerici interi come i valori `Decimal`, utilizzare SQL V1 (08/10/2015) per l'istruzione di query della regola. |
| Boolean | True o False. |
| String | Stringa UTF-8. |
| Array | Serie di valori non necessariamente dello stesso tipo. |
| Object | Valore JSON costituito da una chiave e un valore. Le chiavi devono essere stringhe. I valori possono essere di qualsiasi tipo. |
| Null | Null come definito da JSON. Si tratta di un valore effettivo che rappresenta l'assenza di un valore. È possibile creare in modo esplicito un valore Null usando la parola chiave Null nell'istruzione SQL. Ad esempio: "SELECT NULL AS n FROM 'topic/subtopic'" |
| Undefined | Non un valore. Non si tratta di in tipo rappresentabile in modo esplicito in JSON, se non omettendo il valore. Ad esempio, nell'oggetto `{"foo": null}` la chiave "foo" restituisce NULL, ma la chiave "bar" restituisce `Undefined`. Internamente, il linguaggio SQL tratta `Undefined` come un valore, ma questo tipo non è rappresentabile in JSON, quindi quando viene serializzato in JSON i risultati sono `Undefined`. {"foo":null, "bar":undefined} viene serializzato in JSON come: {"foo":null} Analogamente, `Undefined` viene convertito in una stringa vuota quando serializzato. Le funzioni chiamate con argomenti non validi (ad esempio tipi errati, numero errato di argomenti e così via) restituiscono `Undefined`. |
## Conversioni
La tabella seguente elenca i risultati quando un valore di un tipo viene convertito in un altro tipo (quando un valore del tipo non corretto viene fornito a una funzione). Se, ad esempio, alla funzione di valore assoluto "abs" (che richiede un tipo `Int` o `Decimal`) viene passato un tipo `String`, viene eseguito un tentativo di convertire `String` in `Decimal`, seguendo queste regole. In questo caso, 'abs("-5.123")' viene trattato come 'abs(-5.123)'.
**Nota**
Non vengono eseguiti tentativi di conversione in un tipo `Array``Object`, `Null` o `Undefined`.
**Nel tipo Decimal**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Tipo Decimal senza separatore decimale. |
| Decimal | Valore di origine. |
| Boolean | Undefined. (È possibile usare in modo esplicito la funzione cast per trasformare true = 1.0, false = 0.0.) |
| String | Il motore SQL tenta di analizzare la stringa come una. Decimal AWS IoT tenta di analizzare le stringhe che corrispondono all'espressione regolare:. ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1 "0", "-1.2", "5E-12" sono tutti esempi di stringhe che vengono convertite automaticamente in tipi Decimal. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Null. |
| Undefined | Undefined. |
**Nel tipo Int**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Valore di origine. |
| Decimal | Valore di origine arrotondato al valore Int più vicino. |
| Boolean | Undefined. (È possibile usare in modo esplicito la funzione cast per trasformare true = 1.0, false = 0.0.) |
| String | Il motore SQL tenta di analizzare la stringa come una. Decimal AWS IoT tenta di analizzare le stringhe che corrispondono all'espressione regolare:. ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1 «0", «-1.2", «5E-12" sono tutti esempi di stringhe che vengono convertite automaticamente in Decimal s. AWS IoT Tenta di convertirle in aDecimal, quindi tronca le String posizioni decimali per formare un. Decimal Int |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Null. |
| Undefined | Undefined. |
**Nel tipo Boolean**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Undefined. (È possibile usare in modo esplicito la funzione cast per trasformare 0 = False, any\$1nonzero\$1value = True). |
| Decimal | Undefined. (È possibile usare in modo esplicito la funzione cast per trasformare 0 = False, qualsiasi\$1valore\$1diverso\$1da\$1zero = True.) |
| Boolean | Valore originale. |
| String | "true"=True e "false"=False (senza distinzione tra maiuscole e minuscole). Altri valori stringa sono Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
**Nel tipo String**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Rappresentazione di stringa del tipo Int in notazione standard. |
| Decimal | Stringa che rappresenta il valore Decimal, possibilmente in notazione scientifica. |
| Boolean | "true" o "false". Tutto in caratteri minuscoli. |
| String | Valore originale. |
| Array | Tipo Array serializzato in JSON. La stringa risultante è un elenco separato da virgole, racchiuso tra parentesi quadre. I tipi String sono racchiusi tra virgolette. I tipi Decimal, Int, Boolean e Null non sono racchiusi tra virgolette. |
| Oggetto | Oggetto serializzato in JSON. La stringa risultante è un elenco separato da virgole di coppie chiave-valore e inizia e termina con parentesi graffe. I tipi String sono racchiusi tra virgolette. I tipi Decimal, Int, Boolean e Null non sono racchiusi tra virgolette. |
| Null | Undefined. |
| Undefined | Undefined. |
# Operatori
Gli operatori seguenti possono essere usati nelle clausole SELECT e WHERE.
## Operatore AND
Restituisce un risultato `Boolean`. Esegue un'operazione AND logica. Restituisce true se gli operandi sinistro e destro sono true. In caso contrario, restituisce false. Sono necessari operandi di tipo `Boolean` o operandi di tipo String "true" o "false" che non facciano distinzione tra maiuscole e minuscole.
*Sintassi:* ` expression AND expression`.
**Operatore AND**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. True se entrambi gli operandi sono true. In caso contrario, false. |
| String/Boolean | String/Boolean | Se tutte le stringhe sono "true" o "false" (senza distinzione tra maiuscole e minuscole), vengono convertite in Boolean ed elaborate normalmente come tipi boolean AND boolean. |
| Altro valore | Altro valore | Undefined. |
## Operatore OR
Restituisce un risultato `Boolean`. Esegue un'operazione OR logica. Restituisce true se l'operando sinistro o quello destro è true. In caso contrario, restituisce false. Sono necessari operandi di tipo `Boolean` o operandi di tipo String "true" o "false" che non facciano distinzione tra maiuscole e minuscole.
*Sintassi:* ` expression OR expression`.
**Operatore OR**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. True se uno degli operandi è true. In caso contrario, false. |
| String/Boolean | String/Boolean | Se tutte le stringhe sono "true" o "false" (senza distinzione tra maiuscole e minuscole), vengono convertite in valori booleani ed elaborate normalmente come boolean OR boolean. |
| Altro valore | Altro valore | Undefined. |
## Operatore NOT
Restituisce un risultato `Boolean`. Esegue un'operazione NOT logica. Restituisce true se l'operando è false. In caso contrario, restituisce true. È necessario un operando di tipo `Boolean` o un operando di tipo String "true" o "false" senza distinzione tra maiuscole e minuscole.
*Sintassi:* `NOT expression`.
**Operatore NOT**
| Operando | Output |
| --- | --- |
| Boolean | Boolean. True se l'operando è false. In caso contrario, true. |
| String | Se la stringa è "true" o "false" (senza distinzione tra maiuscole e minuscole), viene convertita nel valore booleano corrispondente e viene restituito il valore opposto. |
| Altro valore | Undefined. |
## Operatore IN
Restituisce un risultato `Boolean`. È possibile utilizzare l'operatore IN in una clausola WHERE per verificare se un valore corrisponde a qualsiasi valore in un array. Restituisce true se viene trovata la corrispondenza e false in caso contrario.
*Sintassi:* ` expression IN expression`.
**Operatore IN**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int/Decimal/String/Array/Object | Array | Vero se l'Objectelemento Integer DecimalString/Array///viene trovato nell'array. In caso contrario, false. |
*Esempio*:
```
SQL: "select * from 'a/b' where 3 in arr"
JSON: {"arr":[1, 2, 3, "three", 5.7, null]}
```
In questo esempio, la clausola condition `where 3 in arr` restituirà true perché 3 è presente nell'array denominato`arr`. Quindi, nell'istruzione SQL, `select * from 'a/b'` verrà eseguito. Questo esempio mostra anche che l'array può essere eterogeneo.
## Operatore EXISTS
Restituisce un risultato `Boolean`. È possibile utilizzare l'operatore EXISTS in una clausola condizionale per verificare l'esistenza di elementi in una sottoquery. Restituisce true se la sottoquery restituisce uno o più elementi e false se la sottoquery non restituisce alcun elemento.
*Sintassi:* ` expression`.
*Esempio*:
```
SQL: "select * from 'a/b' where exists (select * from arr as a where a = 3)"
JSON: {"arr":[1, 2, 3]}
```
In questo esempio, la clausola condition `where exists (select * from arr as a where a = 3)` restituirà true perché 3 è presente nell'array denominato. `arr` Quindi, nell'istruzione SQL, `select * from 'a/b'` verrà eseguito.
*Esempio*:
```
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}]}
```
In questo esempio, la clausola condition `where exists (select * from e as e where foo = 2)` verrà valutata vera perché l'array all'`e`interno dell'oggetto JSON contiene l'oggetto. `{"foo":2}` Quindi, nell'istruzione SQL, `select * from 'a/b'` verrà eseguito.
## Operatore >
Restituisce un risultato `Boolean`. Restituisce true se l'operando sinistro è maggiore dell'operando destro. Entrambi gli operandi vengono convertiti in un tipo `Decimal` e quindi confrontati.
*Sintassi:* `expression > expression`.
**Operatore >**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. True se l'operando sinistro è maggiore dell'operando destro. In caso contrario, false. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe possono essere convertite in Decimal, restituisce un valore Boolean. Restituisce true se l'operando sinistro è maggiore dell'operando destro. In caso contrario, false. |
| Altro valore | Undefined. | Undefined. |
## Operatore >=
Restituisce un risultato `Boolean`. Restituisce true se l'operando sinistro è maggiore o uguale all'operando destro. Entrambi gli operandi vengono convertiti in un tipo `Decimal` e quindi confrontati.
*Sintassi:* `expression >= expression`.
**Operatore >=**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. True se l'operando sinistro è maggiore o uguale all'operando destro. In caso contrario, false. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe possono essere convertite in Decimal, restituisce un valore Boolean. Restituisce true se l'operando sinistro è maggiore o uguale all'operando destro. In caso contrario, false. |
| Altro valore | Undefined. | Undefined. |
## Operatore <
Restituisce un risultato `Boolean`. Restituisce true se l'operando sinistro è minore dell'operando destro. Entrambi gli operandi vengono convertiti in un tipo `Decimal` e quindi confrontati.
*Sintassi:* `expression < expression`.
**Operatore <**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. True se l'operando sinistro è minore dell'operando destro. In caso contrario, false. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe possono essere convertite in Decimal, restituisce un valore Boolean. Restituisce true se l'operando sinistro è minore dell'operando destro. In caso contrario, false. |
| Altro valore | Undefined | Undefined |
## Operatore <=
Restituisce un risultato `Boolean`. Restituisce true se l'operando sinistro è minore o uguale all'operando destro. Entrambi gli operandi vengono convertiti in un tipo `Decimal` e quindi confrontati.
*Sintassi:* `expression <= expression`.
**Operatore <=**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. True se l'operando sinistro è minore o uguale all'operando destro. In caso contrario, false. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe possono essere convertite in Decimal, restituisce un valore Boolean. Restituisce true se l'operando sinistro è minore o uguale all'operando destro. In caso contrario, false. |
| Altro valore | Undefined | Undefined |
## Operatore <>
Restituisce un risultato `Boolean`. Restituisce true se gli operandi sinistro e destro non sono uguali. In caso contrario, restituisce false.
*Sintassi:* ` expression <> expression`.
**Operatore <>**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int | Int | True se l'operando sinistro non è uguale all'operando destro. In caso contrario, false. |
| Decimal | Decimal | True se l'operando sinistro non è uguale all'operando destro. In caso contrario, false. Int viene convertito in Decimal prima di essere confrontato. |
| String | String | True se l'operando sinistro non è uguale all'operando destro. In caso contrario, false. |
| Array | Array | True se gli elementi di ogni operando non sono uguali e non sono nello stesso ordine. In caso contrario, false |
| Oggetto | Oggetto | True se le chiavi e i valori di ogni operando non sono uguali. In caso contrario, false. L'ordine di non keys/values è importante. |
| Null | Null | Falso. |
| Qualsiasi valore | Undefined | Undefined. |
| Undefined | Qualsiasi valore | Undefined. |
| Tipo non corrispondente | Tipo non corrispondente | True. |
## Operatore =
Restituisce un risultato `Boolean`. Restituisce true se gli operandi sinistro e destro sono uguali. In caso contrario, restituisce false.
*Sintassi:* ` expression = expression`.
**Operatore =**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int | Int | True se l'operando sinistro è uguale all'operando destro. In caso contrario, false. |
| Decimal | Decimal | True se l'operando sinistro è uguale all'operando destro. In caso contrario, false. Int viene convertito in Decimal prima di essere confrontato. |
| String | String | True se l'operando sinistro è uguale all'operando destro. In caso contrario, false. |
| Array | Array | True se gli elementi di ogni operando sono uguali e sono nello stesso ordine. In caso contrario, false. |
| Oggetto | Oggetto | True se le chiavi e i valori di ogni operando sono uguali. In caso contrario, false. L'ordine di non keys/values è importante. |
| Qualsiasi valore | Undefined | Undefined. |
| Undefined | Qualsiasi valore | Undefined. |
| Tipo non corrispondente | Tipo non corrispondente | Falso. |
## Operatore \$1
L'operatore "\$1" è un operatore di overload. Può essere usato per la concatenazione di stringhe o la somma.
*Sintassi:* ` expression + expression`.
**Operatore \$1**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| String | Qualsiasi valore | Converte l'operando destro in una stringa e lo concatena alla fine dell'operando sinistro. |
| Qualsiasi valore | String | Converte l'operando sinistro in una stringa e lo concatena all'operando destro alla fine dell'operando sinistro convertito. |
| Int | Int | Int value. Somma gli operandi. |
| Int/Decimal | Int/Decimal | Decimal value. Somma gli operandi. |
| Altro valore | Altro valore | Undefined. |
## Operatore -
Sottrae l'operando destro dall'operando sinistro.
*Sintassi:* ` expression - expression`.
**Operatore -**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int | Int | Int value. Sottrae l'operando destro dall'operando sinistro. |
| Int/Decimal | Int/Decimal | Decimal value. Sottrae l'operando destro dall'operando sinistro. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe possono essere convertite in valori decimali, viene restituito un valore Decimal. Sottrae l'operando destro dall'operando sinistro. In caso contrario, restituisce Undefined. |
| Altro valore | Altro valore | Undefined. |
| Altro valore | Altro valore | Undefined. |
## Operatore \$1
Moltiplica l'operando sinistro per l'operando destro.
*Sintassi:* ` expression * expression`.
**Operatore \$1**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int | Int | Int value. Moltiplica l'operando sinistro per l'operando destro. |
| Int/Decimal | Int/Decimal | Decimal value. Moltiplica l'operando sinistro per l'operando destro. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe possono essere convertite in valori decimali, viene restituito un valore Decimal. Moltiplica l'operando sinistro per l'operando destro. In caso contrario, restituisce Undefined. |
| Altro valore | Altro valore | Undefined. |
## Operatore /
Divide l'operando sinistro per l'operando destro.
*Sintassi:* ` expression / expression`.
**Operatore /**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int | Int | Int value. Divide l'operando sinistro per l'operando destro. |
| Int/Decimal | Int/Decimal | Decimal value. Divide l'operando sinistro per l'operando destro. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe possono essere convertite in valori decimali, viene restituito un valore Decimal. Divide l'operando sinistro per l'operando destro. In caso contrario, restituisce Undefined. |
| Altro valore | Altro valore | Undefined. |
## Operatore %
Restituisce il resto della divisione dell'operando sinistro per l'operando destro.
*Sintassi:* ` expression % expression`.
**Operatore %**
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int | Int | Int value. Restituisce il resto della divisione dell'operando sinistro per l'operando destro. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe possono essere convertite in valori decimali, viene restituito un valore Decimal. Restituisce il resto della divisione dell'operando sinistro per l'operando destro. In caso contrario, Undefined. |
| Altro valore | Altro valore | Undefined. |
# Funzioni
È possibile usare le seguenti funzioni predefinite nelle clausole SELECT o WHERE delle espressioni SQL.
Le seguenti funzioni esterne sono fatturate in modo equivalente a quelle di un'azione di regola: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb), 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) La [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)funzione viene inoltre fatturata solo quando [decodifichi un messaggio Protobuf](https://docs.aws.amazon.com//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf) in JSON. [Per maggiori dettagli, consulta la pagina dei prezzi.AWS IoT Core](https://aws.amazon.com/iot-core/pricing/)
## abs(Decimal)
Restituisce il valore assoluto di un numero. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `abs(-5)` restituisce 5.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Int, il valore assoluto dell'argomento. |
| Decimal | Decimal, il valore assoluto dell'argomento. |
| Boolean | Undefined. |
| String | Decimal. Il risultato è il valore assoluto dell'argomento. Se la stringa non può essere convertita, il risultato è Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## accountid()
Restituisce l'ID dell'account proprietario della regola come `String`. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`accountid() ` = "123456789012"
## acos(Decimal)
Restituisce il coseno inverso di un numero in radianti. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `acos(0)` = 1.5707963267948966
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), il coseno inverso dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Decimal | Decimal (a precisione doppia), il coseno inverso dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Boolean | Undefined. |
| String | Decimal, il coseno inverso dell'argomento. Se la stringa non può essere convertita, il risultato è Undefined. I risultati immaginari vengono restituiti come Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## asin(Decimal)
Restituisce il seno inverso di un numero in radianti. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `asin(0)` = 0.0
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), il seno inverso dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Decimal | Decimal (a precisione doppia), il seno inverso dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Boolean | Undefined. |
| String | Decimal (a precisione doppia), il seno inverso dell'argomento. Se la stringa non può essere convertita, il risultato è Undefined. I risultati immaginari vengono restituiti come Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## atan(Decimal)
Restituisce la tangente inversa di un numero in radianti. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `atan(0)` = 0.0
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), la tangente inversa dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Decimal | Decimal (a precisione doppia), la tangente inversa dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Boolean | Undefined. |
| String | Decimal, la tangente inversa dell'argomento. Se la stringa non può essere convertita, il risultato è Undefined. I risultati immaginari vengono restituiti come Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## atan2(Decimal, Decimal)
Restituisce l'angolo in radianti, tra l'asse X positivo e il punto (x, y) definito nei due argomenti. L'angolo è positivo per gli angoli in senso antiorario (semipiano superiore, y > 0) e negativo per gli angoli in senso orario (semipiano inferiore, y < 0). Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `atan2(1, 0)` = 1.5707963267948966
****
| Tipo di argomento | Tipo di argomento | Risultato |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal (a precisione doppia), l'angolo tra l'asse X e il punto (x, y) specificato. |
| Int/Decimal/String | Int/Decimal/String | Decimal, la tangente inversa del punto descritto. Se una stringa non può essere convertita, il risultato è Undefined. |
| Altro valore | Altro valore | Undefined. |
## aws\$1lambda(functionArn, inputJson)
Chiama la funzione Lambda specificata passando `inputJson` alla funzione Lambda e restituisce il codice JSON generato dalla funzione Lambda.
**Arguments (Argomenti)**
| Argomento | Description |
| --- | --- |
| functionArn | ARN della funzione Lambda da chiamare. La funzione Lambda deve restituire dati JSON. |
| inputJson | Input JSON passato alla funzione Lambda. Per passare query di oggetti nidificati e valori letterali, devi utilizzare SQL versione 23/03/2016. |
È necessario concedere AWS IoT `lambda:InvokeFunction` le autorizzazioni per richiamare la funzione Lambda specificata. L'esempio seguente illustra come concedere l'autorizzazione `lambda:InvokeFunction` usando l' 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"
```
Di seguito sono illustrati gli argomenti per il comando **add-permission**:
--function-name
Il nome della funzione Lambda. Aggiungi una nuova autorizzazione per aggiornare la policy delle risorse della funzione.
--region
Il del tuo Regione AWS account.
--principal
Entità principale che riceve l'autorizzazione. Questo dovrebbe consentire AWS IoT il `iot.amazonaws.com` permesso di chiamare una funzione Lambda.
--source-arn
ARN della regola. È possibile utilizzare il **get-topic-rule** AWS CLI comando per ottenere l'ARN di una regola.
--source-account
Il Account AWS luogo in cui viene definita la regola.
--statement-id
Identificatore univoco di un'istruzione.
--action
Le operazioni Lambda da permettere nell’istruzione. Per consentire a AWS IoT di invocare una funzione Lambda, specifica `lambda:InvokeFunction`.
**Importante**
Se aggiungi un'autorizzazione per un AWS IoT principale senza fornire `source-arn` o`source-account`, qualsiasi cosa Account AWS che crea una regola con l'azione Lambda può attivare regole da cui richiamare la funzione Lambda. AWS IoT Per ulteriori informazioni, consulta [Modello di autorizzazione Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).
Dato un payload di messaggio JSON, ad esempio:
```
{
"attribute1": 21,
"attribute2": "value"
}
```
È possibile utilizzare la funzione `aws_lambda` per chiamare la funzione Lambda come segue.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", {"payload":attribute1}) as output FROM 'topic-filter'
```
Se desideri passare il payload di messaggio MQTT completo, puoi specificare il payload JSON utilizzando "\$1", come nell’esempio seguente.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", *) as output FROM 'topic-filter'
```
`payload.inner.element` seleziona i dati dai messaggi pubblicati nell'argomento 'argomento/sottoargomento'.
`some.value` seleziona i dati dall'output generato dalla funzione Lambda.
**Nota**
Il motore di regole limita la durata dell'esecuzione delle funzioni Lambda. Le chiamate alle funzioni Lambda dalle regole devono essere completate entro 2000 millisecondi.
## bitand(Int, Int)
Esegue un'operazione AND bit per bit sulle rappresentazioni in bit dei due argomenti `Int` (convertiti). Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `bitand(13, 5)` = 5
****
| Tipo di argomento | Tipo di argomento | Risultato |
| --- | --- | --- |
| Int | Int | Int, un'operazione AND bit per bit sui due argomenti. |
| Int/Decimal | Int/Decimal | Int, un'operazione AND bit per bit sui due argomenti. Tutti i numeri non di tipo Int vengono arrotondati per difetto al valore Int più vicino. Se uno o più argomenti non possono essere convertiti in un tipo Int, il risultato è Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, un'operazione AND bit per bit sui due argomenti. Tutte le stringhe vengono convertite in decimali e arrotondate per difetto al valore Int più vicino. Se la conversione non riesce, il risultato è Undefined. |
| Altro valore | Altro valore | Undefined. |
## bitor(Int, Int)
Esegue un'operazione OR bit per bit sulle rappresentazioni in bit dei due argomenti. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `bitor(8, 5)` = 13
****
| Tipo di argomento | Tipo di argomento | Risultato |
| --- | --- | --- |
| Int | Int | Int, l'operazione OR bit per bit sui due argomenti. |
| Int/Decimal | Int/Decimal | Int, l'operazione OR bit per bit sui due argomenti. Tutti i numeri non di tipo Int vengono arrotondati per difetto al valore Int più vicino. Se la conversione non riesce, il risultato è Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, l'operazione OR bit per bit sui due argomenti. Tutte le stringhe vengono convertite in decimali e arrotondate per difetto al valore Int più vicino. Se la conversione non riesce, il risultato è Undefined. |
| Altro valore | Altro valore | Undefined. |
## bitxor(Int, Int)
Esegue un'operazione XOR bit per bit sulle rappresentazioni in bit dei due argomenti `Int` (convertiti). Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:`bitor(13, 5)` = 8
****
| Tipo di argomento | Tipo di argomento | Risultato |
| --- | --- | --- |
| Int | Int | Int, un'operazione XOR bit per bit sui due argomenti. |
| Int/Decimal | Int/Decimal | Int, un'operazione XOR bit per bit sui due argomenti. I numeri non di tipo Int vengono arrotondati per difetto al valore Int più vicino. |
| Int/Decimal/String | Int/Decimal/String | Int, un'operazione XOR bit per bit sui due argomenti. Le stringhe vengono convertite in decimali e arrotondate per difetto al valore Int più vicino. Se la conversione non riesce, il risultato è Undefined. |
| Altro valore | Altro valore | Undefined. |
## bitnot(Int)
Esegue un'operazione NOT bit per bit sulle rappresentazioni in bit dell'argomento `Int` (convertito). Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `bitnot(13)` = 2
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Int, un'operazione NOT bit per bit sull'argomento. |
| Decimal | Int, un'operazione NOT bit per bit sull'argomento. Il valore Decimal viene arrotondato per difetto al valore Int più vicino. |
| String | Int, un'operazione NOT bit per bit sull'argomento. Le stringhe vengono convertite in decimali e arrotondate per difetto al valore Int più vicino. Se la conversione non riesce, il risultato è Undefined. |
| Altro valore | Altro valore. |
## cast()
Converte un valore da un tipo di dati a un altro. Le operazioni di cast hanno un comportamento per lo più simile alle conversioni standard, con in più la possibilità di eseguire il cast dei numeri da e verso tipi booleani. Se AWS IoT non riesci a determinare come passare da un tipo a un altro, il risultato è. `Undefined` Supportata da SQL versione 2015-10-08 e versioni successive. Formato: cast (*value*as*type*).
Esempio:
`cast(true as Int) ` = 1
Di seguito sono indicate le parole chiave che potrebbero seguire la parola "as" quando si chiama `cast`:
**Per la versione SQL 2015-10-08 e 2016-03-23**
| Parola chiave | Risultato |
| --- | --- |
| String | Esegue il cast del valore nel tipo String. |
| Nvarchar | Esegue il cast del valore nel tipo String. |
| Testo | Esegue il cast del valore nel tipo String. |
| Ntext | Esegue il cast del valore nel tipo String. |
| varchar | Esegue il cast del valore nel tipo String. |
| Int | Esegue il cast del valore nel tipo Int. |
| Numero intero | Esegue il cast del valore nel tipo Int. |
| Double | Esegue il cast del valore Decimal (a precisione doppia). |
**Inoltre, per la versione SQL 2016-03-23**
| Parola chiave | Risultato |
| --- | --- |
| Decimal | Esegue il cast del valore nel tipo Decimal. |
| Bool | Esegue il cast del valore nel tipo Boolean. |
| Boolean | Esegue il cast del valore nel tipo Boolean. |
Regole per il cast:
**Cast nel tipo Decimal**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Tipo Decimal senza separatore decimale. |
| Decimal | Valore di origine. Con SQL V2 (23/03/2016), valori numerici che sono numeri interi, come `10.0`, restituiscono un valore `Int` (`10`) invece del previsto valore `Decimal` (`10.0`). Per lanciare in modo affidabile valori numerici interi come valori `Decimal`, utilizza SQL V1 (08/10/2015) per l'istruzione di query della regola. |
| Boolean | true = 1.0, false = 0.0. |
| String | Cerca di analizzare la stringa come Decimal. AWS IoT tenta di analizzare le stringhe che corrispondono all'espressione regolare: ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1.2", "5E-12" sono tutti esempi di stringhe che vengono convertite automaticamente in decimali. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
**Cast nel tipo Int**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Valore di origine. |
| Decimal | Valore di origine, arrotondato per difetto al valore Int più vicino. |
| Boolean | true = 1.0, false = 0.0. |
| String | Cerca di analizzare la stringa come Decimal. AWS IoT tenta di analizzare le stringhe che corrispondono all'espressione regolare: ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1.2", "5E-12" sono tutti esempi di stringhe che vengono convertite automaticamente in decimali. AWS IoT prova a convertire la stringa in un tipo Decimal e ad arrotondarla per difetto al valore Int più vicino. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
**Cast nel tipo `Boolean`**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | 0 = False, qualsiasi\$1valore\$1diverso\$1da\$1zero = True. |
| Decimal | 0 = False, qualsiasi\$1valore\$1diverso\$1da\$1zero = True. |
| Boolean | Valore di origine. |
| String | "true" = True e "false" = False (senza distinzione tra maiuscole e minuscole). Altri valori stringa = Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
**Cast nel tipo String**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Rappresentazione di stringa del tipo Int, in notazione standard. |
| Decimal | Stringa che rappresenta il valore Decimal, possibilmente in notazione scientifica. |
| Boolean | "true" o "false", tutto in caratteri minuscoli. |
| String | Valore di origine. |
| Array | Matrice serializzata in JSON. La stringa risultante è un elenco separato da virgole racchiuso tra parentesi quadre. I tipi String sono racchiusi tra virgolette. I tipi Decimal, Int e Boolean non sono racchiusi tra virgolette. |
| Oggetto | Oggetto serializzato in JSON. La stringa JSON è un elenco separato da virgole di coppie chiave-valore e inizia e termina con parentesi graffe. Il tipo String è racchiuso tra virgolette. I tipi Decimal, Int, Boolean e Null non sono racchiusi tra virgolette. |
| Null | Undefined. |
| Undefined | Undefined. |
## ceil(Decimal)
Arrotonda per eccesso il tipo `Decimal` specificato al valore `Int` più vicino. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`ceil(1.2)` = 2
`ceil(-1.2)` = -1
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Int, il valore dell'argomento. |
| Decimal | Int, il valore Decimal arrotondato per eccesso al valore Int più vicino. |
| String | Int. La stringa viene convertita in Decimal e arrotondata per eccesso al valore Int più vicino. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. |
| Altro valore | Undefined. |
## chr(String)
Restituisce il carattere ASCII corrispondente all'argomento `Int` specificato. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`chr(65)` = "A".
`chr(49)` = "1".
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Carattere corrispondente al valore ASCII specificato. Se l'argomento non è un valore ASCII valido, il risultato è Undefined. |
| Decimal | Carattere corrispondente al valore ASCII specificato. L'argomento Decimal viene arrotondato per difetto al valore Int più vicino. Se l'argomento non è un valore ASCII valido, il risultato è Undefined. |
| Boolean | Undefined. |
| String | Se il tipo String può essere convertito in Decimal, viene arrotondato per difetto al valore Int più vicino. Se l'argomento non è un valore ASCII valido, il risultato è Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Altro valore | Undefined. |
## clientid()
Restituisce l'ID del client MQTT che invia il messaggio oppure `n/a` se il messaggio non è stato inviato tramite MQTT. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`clientid() ` = "123456789012"
## concat()
Concatena matrici o stringhe. Questa funzione accetta qualsiasi numero di argomenti e restituisce un tipo `String` o `Array`. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`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]
****
| Numero di argomenti | Risultato |
| --- | --- |
| 0 | Undefined. |
| 1 | L'argomento viene restituito non modificato. |
| 2\$1 | Se un argomento è un tipo `Array`, il risultato è una singola matrice contenente tutti gli argomenti. Se nessun argomento è un array e almeno un argomento è di tipo `String`, il risultato è la concatenazione delle rappresentazioni `String` di tutti gli argomenti. Gli argomenti vengono convertiti in stringhe usando le conversioni standard illustrate in precedenza. |
## cos(Decimal)
Restituisce il coseno di un numero in radianti. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`cos(0)` = 1.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), il coseno dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Decimal | Decimal (a precisione doppia), il coseno dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Boolean | Undefined. |
| String | Decimal (a precisione doppia), il coseno dell'argomento. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. I risultati immaginari vengono restituiti come Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## cosh(Decimal)
Restituisce il coseno iperbolico di un numero in radianti. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `cosh(2.3)` = 5.037220649268761.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), il coseno iperbolico dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Decimal | Decimal (a precisione doppia), il coseno iperbolico dell'argomento. I risultati immaginari vengono restituiti come Undefined. |
| Boolean | Undefined. |
| String | Decimal (a precisione doppia), il coseno iperbolico dell'argomento. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. I risultati immaginari vengono restituiti come Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## decodifica(valore, decodingScheme)
Utilizzo della funzione `decode` per decodificare un valore codificato. Se la stringa decodificata è un documento JSON, viene restituito un oggetto indirizzabile. In caso contrario, la stringa decodificata viene restituita come una stringa. La funzione restituisce NULL se la stringa non può essere decodificata. Questa funzione supporta la decodifica di stringhe con codifica base64 e il formato del messaggio Protocol Buffer (protobuf).
Supportata da SQL versione 2016-03-23 e versioni successive.
value
Un valore stringa o una qualsiasi delle espressioni valide, in base a quanto definito in [AWS IoT Riferimento SQL](iot-sql-reference.md), che restituiscono una stringa.
decodingScheme
Una stringa letterale che rappresenta lo schema utilizzato per decodificare il valore. Attualmente, solo `'base64'` e `'proto'` sono supportati.
### Decodifica di stringhe con codifica base64
In questo esempio, il payload del messaggio include un valore codificato.
```
{
encoded_temp: "eyAidGVtcGVyYXR1cmUiOiAzMyB9Cg=="
}
```
La funzione `decode` in questa istruzione SQL decodifica il valore nel payload del messaggio.
```
SELECT decode(encoded_temp,"base64").temperature AS temp from 'topic/subtopic'
```
La decodifica del valore `encoded_temp` restituisce il seguente documento JSON valido, che consente all'istruzione SELECT di leggere il valore della temperatura.
```
{ "temperature": 33 }
```
Il risultato dell'istruzione SELECT in questo esempio viene mostrato di seguito.
```
{ "temp": 33 }
```
Se il valore decodificato non era un documento JSON valido, il valore decodificato dovrebbe essere restituito come stringa.
### Decodifica del payload del messaggio protbuf
È possibile utilizzare la funzione di decodifica SQL per configurare una regola in grado di decodificare il payload del messaggio protobuf. Per ulteriori informazioni, consulta [Decodifica dei payload dei messaggi protbuf](binary-payloads.md#binary-payloads-protobuf).
**Importante**
Se ometti `source‐arn` o `source‐account` quando imposti i permessi per un AWS IoT principale, chiunque Account AWS può richiamare la funzione Decode tramite altre regole. AWS IoT Per proteggere la tua funzionalità, consulta [le politiche di Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html) nella *Guida per l'utente di Amazon Simple Storage Service*.
L'aspetto della firma della funzione è simile al seguente:
```
decode(, 'proto', '', '', '', '')
```
`ENCODED DATA`
Specifica i dati codificati con codifica protobuf da decodificare. Se l'intero messaggio inviato alla Regola è costituito da dati con codifica protobuf, puoi fare riferimento al payload in entrata di dati binari non elaborati utilizzando `*`. In caso contrario, questo campo deve essere una stringa JSON con codifica base-64 e un riferimento alla stringa può essere passato direttamente.
1) Per decodificare un payload in entrata protobuf di dati binari non elaborati:
```
decode(*, 'proto', ...)
```
2) Per decodificare un messaggio con codifica protobuf rappresentato da una stringa con codifica base64 'a.b':
```
decode(a.b, 'proto', ...)
```
`proto`
Specifica i dati da decodificare in un formato messaggio protobuf. Se si specifica `base64` anziché `proto`, questa funzione decodificherà le stringhe con codifica base64 come JSON.
`S3 BUCKET NAME`
Il nome del bucket Amazon S3 in cui è stato caricato il file `FileDescriptorSet`.
`S3 OBJECT KEY`
La chiave oggetto che specifica il file `FileDescriptorSet` nel bucket Amazon S3.
`PROTO NAME`
Il nome del file `.proto` (esclusa l'estensione) da cui è stato generato il file `FileDescriptorSet`.
`MESSAGE TYPE`
Il nome della struttura di messaggi protobuf all'interno del file `FileDescriptorSet` rispetto alla quale i dati da decodificare devono essere conformi.
L'aspetto di un'espressione SQL di esempio che utilizza la funzione SQL di decodifica può essere simile al seguente:
```
SELECT VALUE decode(*, 'proto', 's3-bucket', 'messageformat.desc', 'myproto', 'messagetype') FROM 'some/topic'
```
+ `*`
Rappresenta un payload in entrata binario, conforme al tipo di messaggio protobuf chiamato `mymessagetype`.
+ `messageformat.desc`
Il file `FileDescriptorSet` archiviato in un bucket Amazon S3 denominato `s3-bucket`.
+ `myproto`
Il file `.proto` originale utilizzato per generare il file `FileDescriptorSet` denominato `myproto.proto`.
+ `messagetype`
Il tipo di messaggio chiamato `messagetype` (insieme a eventuali dipendenze importate) come definito in `myproto.proto`.
## encode(value, encodingScheme)
Usa la funzione `encode` per codificare il payload, che potenzialmente può essere costituito da dati non JSON, nella rappresentazione di stringa in base allo schema di codifica. Supportata da SQL versione 2016-03-23 e versioni successive.
value
Qualsiasi espressioni valida, in base a quanto definito in [AWS IoT Riferimento SQL](iot-sql-reference.md). È possibile specificare \$1 per codificare l'intero payload, indipendentemente dal fatto che sia in formato JSON. Se si fornisce un'espressione, il risultato della valutazione verrà prima convertito in una stringa e quindi codificato.
encodingScheme
Stringa letterale che rappresenta lo schema di codifica da usare. Attualmente è supportato solo `'base64'`.
## endswith(String, String)
Restituisce un tipo `Boolean` che indica se il primo argomento `String` termina con il secondo argomento `String`. Se uno degli argomenti è `Null` oppure `Undefined`, il risultato è `Undefined`. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `endswith("cat","at")` = true.
****
| Tipo di argomento 1 | Tipo di argomento 2 | Risultato |
| --- | --- | --- |
| String | String | True se il primo argomento termina con il secondo argomento. In caso contrario, false. |
| Altro valore | Altro valore | Entrambi gli argomenti vengono convertiti in stringhe usando le regole di conversione standard. True se il primo argomento termina con il secondo argomento. In caso contrario, false. Se uno degli argomenti è Null oppure Undefined, il risultato è Undefined. |
## exp(Decimal)
Restituisce il valore e elevato all'argomento `Decimal`. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `exp(1)` = e.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), argomento e ^. |
| Decimal | Decimal (a precisione doppia), argomento e ^. |
| String | Decimal (a precisione doppia), argomento e ^. Se il tipo String non può essere convertito in Decimal, il risultato è Undefined. |
| Altro valore | Undefined. |
## floor(Decimal)
Arrotonda il `Decimal` per difetto al valore `Int` più vicino. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`floor(1.2)` = 1
`floor(-1.2)` = -2
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Int, il valore dell'argomento. |
| Decimal | Int, il valore Decimal viene arrotondato per difetto al valore Int più vicino. |
| String | Int. La stringa viene convertita in Decimal e arrotondata per difetto al valore Int più vicino. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. |
| Altro valore | Undefined. |
## get
Estrae un valore da un tipo di raccolta (Array, String, Object). Al primo argomento non viene applicata alcuna conversione. La conversione viene applicata al secondo argomento come illustrato nella tabella. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`get(["a", "b", "c"], 1) ` = "B USD"
`get({"a":"b"}, "a")` = "B USD"
`get("abc", 0)` = "a"
****
| Tipo di argomento 1 | Tipo di argomento 2 | Risultato |
| --- | --- | --- |
| Array | Qualsiasi tipo (convertito in Int) | Elemento con indice in base 0 del tipo Array fornito dal secondo argomento (convertito in Int). Se la conversione non riesce, il risultato è Undefined. Se l'indice non rientra nei limiti di Array (negativo o >= array.length), il risultato è Undefined. |
| Stringa | Qualsiasi tipo (convertito in Int) | Carattere con indice in base 0 della stringa fornita dal secondo argomento (convertita in Int). Se la conversione non riesce, il risultato è Undefined. Se l'indice non rientra nei limiti della stringa (negativo o >= string.length), il risultato è Undefined. |
| Oggetto | String (non viene applicata alcuna conversione) | Valore archiviato nell'oggetto del primo argomento corrispondente alla chiave di stringa fornita come secondo argomento. |
| Altro valore | Qualsiasi valore | Undefined. |
## get\$1dynamodb (TableName,,,,, partitionKeyName roLearn) partitionKeyValue sortKeyName sortKeyValue
Recupera i dati da una tabella Dynamo DB. `get_dynamodb()` consente di eseguire le query su una tabella Dynamo DB mentre viene valutata una regola. È possibile filtrare o aumentare i payload dei messaggi utilizzando i dati recuperati da Dynamo DB. Supportata da SQL versione 2016-03-23 e versioni successive.
`get_dynamodb()` prende i seguenti parametri:
tableName
Nome della tabella Dynamo DB su cui eseguire le query.
partitionKeyName
Il nome della chiave della partizione. Per ulteriori informazioni, consulta [ Chiavi Dynamo DB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
partitionKeyValue
Il valore della chiave di partizione utilizzata per identificare un record. Per ulteriori informazioni, consulta [ Chiavi Dynamo DB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyName
(Facoltativo) Il nome della chiave di ordinamento. Questo parametro è obbligatorio solo se la tabella Dynamo DB interrogata utilizza una chiave composita. Per ulteriori informazioni, consulta [ Chiavi Dynamo DB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyValue
(Facoltativo) Il valore della chiave di ordinamento. Questo parametro è obbligatorio solo se la tabella Dynamo DB interrogata utilizza una chiave composita. Per ulteriori informazioni, consulta [ Chiavi Dynamo DB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
roleArn
ARN del ruolo IAM che concede l'accesso alla tabella Dynamo DB. Il motore di regole assume questo ruolo per accedere alla tabella Dynamo DB per conto dell'utente. Evitare di utilizzare un ruolo eccessivamente permissivo. Concedere al ruolo solo le autorizzazioni richieste dalla regola. Di seguito è riportato una policy di esempio che consente l'accesso a una tabella Dynamo DB.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:GetItem",
"Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/table-name"
}
]
}
```
Per un esempio di come è possibile utilizzare `get_dynamodb()`, supponi di avere una tabella Dynamo DB che contiene l'ID del dispositivo e le informazioni sulla posizione per tutti i dispositivi collegati a AWS IoT. La seguente istruzione SELECT utilizza la funzione `get_dynamodb()` per recuperare il percorso per l'ID dispositivo specificato:
`SELECT *, get_dynamodb("InServiceDevices", "deviceId", id, "arn:aws:iam::12345678910:role/getdynamo").location AS location FROM 'some/topic' `
**Nota**
È possibile chiamare `get_dynamodb()` al massimo una volta per istruzione SQL. Più chiamate di `get_dynamodb()` in una singola istruzione SQL causano la chiusura della regola senza richiamare alcuna operazione.
## get\$1mqtt\$1property(name)
Fa riferimento a una delle seguenti MQTT5 intestazioni:,, e. `contentType` `payLoadFormatIndicator` `responseTopic` `correlationData` Questa funzione accetta come argomento una qualsiasi delle seguenti stringhe letterali: `content_type`, `format_indicator`, `response_topic` e `correlation_data`. Per ulteriori informazioni, consulta la tabella **Argomenti della funzione** seguente.
contentType
Stringa: una stringa con codifica UTF-8 che descrive il contenuto del messaggio di pubblicazione.
payLoadFormatIndicatore
Stringa: un valore stringa Enum che indica se il payload è formattato come UTF-8. I valori validi sono `UNSPECIFIED_BYTES` e `UTF8_DATA`.
responseTopic
Stringa: una stringa con codifica UTF-8 utilizzata come il nome dell'argomento per un messaggio di risposta. L'argomento della risposta viene utilizzato per descrivere l'argomento in cui il destinatario deve pubblicare come parte del flusso richiesta-risposta. L'argomento non deve contenere caratteri jolly.
correlationData
Stringa: dati binari con codifica base64 utilizzati dal mittente del messaggio di richiesta per identificare a quale richiesta è destinato il messaggio di risposta quando viene ricevuto.
Nella tabella seguente vengono mostrati gli argomenti della funzione accettabili e i tipi di restituzione associati per la funzione `get_mqtt_property`:
**Argomenti della funzione**
| SQL | Tipo di dati restituito (se presente) | Tipo di dati restituito (se non presente) |
| --- | --- | --- |
| get\$1mqtt\$1property("format\$1indicator") | Stringa (UNSPECIFIED\$1BYTES o \$1DATA) UTF8 | Stringa (UNSPECIFIED\$1BYTES) |
| get\$1mqtt\$1property("content\$1type") | Stringa | Undefined |
| get\$1mqtt\$1property("response\$1topic") | Stringa | Undefined |
| get\$1mqtt\$1property("correlation\$1data") | Stringa con codifica base64 | Undefined |
| get\$1mqtt\$1property("some\$1invalid\$1name") | Undefined | Undefined |
L'esempio seguente Rules SQL fa riferimento a una delle seguenti MQTT5 intestazioni:,, e. `contentType` `payLoadFormatIndicator` `responseTopic` `correlationData`
```
SELECT *, get_mqtt_property('content_type') as contentType,
get_mqtt_property('format_indicator') as payloadFormatIndicator,
get_mqtt_property('response_topic') as responseTopic,
get_mqtt_property('correlation_data') as correlationData
FROM 'some/topic'
```
## get\$1or\$1default (espressione, defaultValue)
Restituisce il valore predefinito nel secondo parametro se specificato oppure restituisce undefined, quando l'espressione nel primo parametro restituisce null, undefined o fallisce. Supportata da SQL versione 2016-03-23 e versioni successive.
**Importante**
`get_or_default`non supporta direttamente payload non JSON così come sono. Se utilizzi un payload non JSON, usa le funzioni or. `encode` `decode`
`get_or_default()` prende i seguenti parametri:
expression
Qualsiasi espressione valida contenente[Tipi di dati](iot-sql-data-types.md),, [Funzioni](#iot-sql-functions)[Valori letterali](iot-sql-literals.md), [[Query di oggetti nidificati](iot-sql-nested-queries.md)Variabili](iot-sql-set.md#iot-sql-set-usage) o. [Estensioni JSON](iot-sql-json.md)
defaultValue
(Facoltativo) Qualsiasi espressione valida contenente [Tipi di dati](iot-sql-data-types.md)[Funzioni](#iot-sql-functions),[Valori letterali](iot-sql-literals.md),[Query di oggetti nidificati](iot-sql-nested-queries.md), [Variabili](iot-sql-set.md#iot-sql-set-usage) o[Estensioni JSON](iot-sql-json.md). Questo è il valore da restituire ogni volta che il primo argomento restituisce null, undefined o fallisce.
Le funzioni che recuperano dati da risorse di proprietà del cliente, come get\$1secret, get\$1dynamodb, aws\$1lambda, get\$1thing\$1shadow, decode-protobuf e machinelearning\$1predict, non sono consentite per il parametro defaultValue.
La tabella seguente mostra gli argomenti delle funzioni accettabili per ogni argomento e i relativi output associati:
| Primo argomento | Secondo argomento | Output |
| --- | --- | --- |
| Valutazione riuscita | Qualsiasi valore o non specificato | Il valore del primo argomento. |
| Indefinito, nullo o non riuscito | Qualsiasi valore, incluso Undefined o Null | Il valore del secondo argomento. |
| Indefinito, nullo o non riuscito | non specificata | Undefined |
**Esempi:**
Esempio 1:
L'esempio seguente fornisce un valore DefaultValue se una tabella o una query DynamoDB fallisce:
```
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'
```
Esempio 2:
L'esempio seguente fornisce un valore predefinito sicuro «UNKNOWN» se lo status non è definito:
```
SELECT
get_or_default( CASE status
WHEN 'active' THEN 'GOOD'
WHEN 'inactive' THEN 'BAD'/
ELSE 'UNKNOWN'
END, 'UNKNOWN') as status_category
FROM 'topic/subtopic'
```
Esempio 3:
L'esempio seguente mostra come è possibile utilizzare get\$1or\$1default anche con un singolo parametro. Ciò è utile in scenari in cui potresti non avere un valore predefinito chiaro, ma non vuoi che l'esecuzione delle regole abbia esito negativo.
```
SELECT
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME") as config
FROM 'device/telemetry'
```
Se la ricerca in DynamoDB fallisce, l'esecuzione della regola avrà esito negativo e non verrà eseguita alcuna azione. Se invece viene utilizzato il seguente codice SQL:
```
SELECT
get_or_default(get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME")) as config
FROM 'device/telemetry'
```
L'istruzione get\$1or\$1default restituirà a`Undefined`, quindi in questo esempio l'istruzione SELECT nel complesso valuterà a `{}` e verrà tentata qualsiasi azione relativa alla regola.
**Importante**
Consigliamo di seguire queste best practice per mantenere la sicurezza quando si utilizza questa funzione:
Evita di utilizzare segreti codificati nelle definizioni delle regole, compresi i valori predefiniti
Utilizzatelo Gestione dei segreti AWS per la gestione di informazioni riservate
## get\$1registry\$1data (RegistryAPI, ThingName, roLearn)
Recupera i dati AWS IoT del registro degli oggetti in una AWS IoT regola. È possibile leggere i dati del registro (ad esempio attributi, tipi di oggetti e gruppi di oggetti a cui appartiene un dispositivo) e utilizzare queste informazioni per filtrare, arricchire o instradare dinamicamente i messaggi. Supportata da SQL versione 2016-03-23 e versioni successive.
`get_registry_data()` prende i seguenti parametri:
API di registro
L'API del registro chiamata. I valori validi sono `DescribeThing` e `ListThingGroupsForThing`. Questi valori devono essere stringhe costanti.
thingName
Stringa: il nome dell'oggetto di cui si desidera recuperare i dati di registro.
roleArn
String: un ARN di ruolo con `iot:DescribeThing` and/or `iot:ListThingGroupsForThing` autorizzazione basata sull'API chiamata.
Il formato di risposta della `get_registry_data` funzione è lo stesso dell'API di registro chiamata. Per ulteriori informazioni, consulta [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.
Esempio:
È possibile recuperare informazioni sul tipo di oggetto per consentire il filtraggio dei messaggi relativi agli eventi del AWS IoT Core ciclo di vita per gli elementi (il cui nome corrisponde all'ID del client MQTT) in cui si trova il tipo di oggetto. `testenv`
```
SELECT *
FROM '$aws/events/lifecycle/+'
WHERE
get_registry_data("DescribeThing",clientId,[roleArn]).thingTypeName='testenv'
```
Esempio:
È possibile recuperare gli attributi dell'oggetto per un dispositivo con il nome dell'oggetto `sensor1` per tutti i messaggi inviati dal relativo dispositivo gateway. `gateway1`
```
SELECT *, get_registry_data("DescribeThing","sensor1",[roleArn]).attributes.temperature_threhold AS device1_tempthreshold
FROM home1/gateway1/sensor1/#
```
**Nota**
È possibile chiamare al massimo `get_registry_data()` una volta per istruzione SQL e modelli sostitutivi per azioni e azioni di errore.
## get\$1secret (secretId, secretType, chiave, roleArn)
Recupera il valore del file crittografato `SecretString` o del campo `SecretBinary` della versione corrente di un segreto in [Gestione dei segreti AWS](https://docs.aws.amazon.com/secretsmanager/latest/userguide/). Per ulteriori informazioni sulla creazione e la gestione di segreti, vedere [CreateSecret[UpdateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html)](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html), e. [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html)
`get_secret()` prende i seguenti parametri:
secretId
Stringa: Amazon Resource Name (ARN) o il nome descrittivo del segreto da recuperare.
secretType
Stringa: il tipo segreto. Valori validi: `SecretString` \$1 `SecretBinary`.
SecretString
+ Per i segreti che crei come oggetti JSON utilizzando la APIs AWS CLI, la o la Gestione dei segreti AWS console:
+ Se specifichi un valore per il parametro `key`, questa funzione restituisce il valore della chiave specificata.
+ Se non specifichi un valore per il parametro `key`, questa funzione restituisce l'intero oggetto JSON.
+ Per i segreti che crei come oggetti non JSON utilizzando o il APIs : AWS CLI
+ Se specifichi un valore per il parametro `key`, questa funzione non riesce con un'eccezione.
+ Se non specifichi un valore per il parametro `key`, questa funzione restituisce il contenuto del segreto.
SecretBinary
+ Se specifichi un valore per il parametro `key`, questa funzione non riesce con un'eccezione.
+ Se non specifichi un valore per il parametro `key`, questa funzione restituisce il valore segreto come stringa UTF-8 con codifica base64.
Chiave
(Facoltativo) Stringa: il nome della chiave all'interno di un oggetto JSON memorizzato nel campo `SecretString` di un segreto. Utilizza questo valore quando desideri recuperare solo il valore di una chiave memorizzata in un segreto anziché l'intero oggetto JSON.
Se specifichi un valore per questo parametro e il segreto non contiene un oggetto JSON all'interno del suo campo `SecretString`, questa funzione non riesce con un'eccezione.
roleArn
Stringa: ARN di un ruolo con `secretsmanager:GetSecretValue` e autorizzazioni `secretsmanager:DescribeSecret`.
**Nota**
Questa funzione restituisce sempre la versione corrente del segreto (la versione con il tag `AWSCURRENT`). Il motore AWS IoT delle regole memorizza nella cache ogni segreto per un massimo di 15 minuti. Di conseguenza, il motore delle regole può richiedere fino a 15 minuti per aggiornare un segreto. Ciò significa che se recuperi un segreto fino a 15 minuti dopo un aggiornamento con Gestione dei segreti AWS, questa funzione potrebbe restituire la versione precedente.
Questa funzione non viene misurata, ma sono Gestione dei segreti AWS previsti costi. A causa del meccanismo di memorizzazione nella cache segreta, il motore delle regole chiama occasionalmente Gestione dei segreti AWS. Poiché il motore delle regole è un servizio completamente distribuito, è possibile che vengano visualizzate più chiamate API di Secrets Manager dal motore delle regole durante la finestra di memorizzazione nella cache, dalla durata di 15 minuti.
Esempi:
Puoi utilizzare la funzione `get_secret` in un'intestazione di autenticazione in un'operazione regola HTTPS, come nell'esempio di autenticazione della chiave API seguente.
```
"API_KEY": "${get_secret('API_KEY', 'SecretString', 'API_KEY_VALUE', 'arn:aws:iam::12345678910:role/getsecret')}"
```
Per ulteriori informazioni sull’operazione della regola HTTPS, consulta [HTTP](https-rule-action.md).
## get\$1thing\$1shadow (ThingName, shadowName, roLearn)
Restituisce la copia shadow specificata dell'oggetto specificato. Supportata da SQL versione 2016-03-23 e versioni successive.
thingName
String: nome della copia shadow dell'oggetto da recuperare.
shadowName
(Facoltativo) Stringa: il nome della copia shadow. Questo parametro è obbligatorio solo quando si fa riferimento alle copie shadow con nome.
roleArn
String: ARN di un ruolo con autorizzazione `iot:GetThingShadow`.
Esempi:
Se utilizzato con una copia shadow denominata, fornire il parametro `shadowName`.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","MyThingShadow","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
Se utilizzato con una copia shadow senza nome, omettere il parametro `shadowName`.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
## get\$1user\$1properties () userPropertyKey
Fa riferimento alle proprietà utente, che è un tipo di intestazioni di proprietà supportate in. MQTT5
userProperty
Stringa: una proprietà utente è una coppia chiave-valore. Questa funzione accetta la chiave come un argomento e restituisce una matrice di tutti i valori che corrispondono alla chiave associata.
**Argomenti della funzione**
Per le seguenti Proprietà utente nelle intestazioni messaggio:
| Chiave | Valore |
| --- | --- |
| some key | un valore |
| a different key | un valore diverso |
| some key | valore con chiave duplicata |
Nella tabella seguente viene mostrato il comportamento SQL previsto:
| SQL | Tipo di dati restituito | Valore dati restituito |
| --- | --- | --- |
| get\$1user\$1properties('some key') | Array di stringhe | ['some value', 'value with duplicate key'] |
| get\$1user\$1properties('other key') | Array di stringhe | ['a different value'] |
| get\$1user\$1properties( ) | Array di oggetti coppie chiave-valore | [\$1'"some key": "some value"'\$1, \$1"other key": "a different value"\$1, \$1"some key": "value with duplicate key"\$1] |
| get\$1user\$1properties('non-existent key') | Undefined | |
L'esempio seguente Rules SQL fa riferimento alle proprietà utente (un tipo di intestazione di MQTT5 proprietà) nel payload:
```
SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'
```
## Funzioni di hashing
AWS IoT fornisce le seguenti funzioni di hashing:
+ md2
+ md5
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Tutte le funzioni hash richiedono un argomento stringa. Il risultato è il valore della stringa sottoposto ad hashing. Agli argomenti non di tipo String si applicano le conversioni standard nel tipo String. Tutte le funzioni hash sono supportate da SQL versione 2015-10-08 e successive.
Esempi:
`md2("hello")` = "a9046c73e00331af68917d3804f70655"
`md5("hello")` = "5d41402abc4b2a76b9719d911017c592"
## indexof(String, String)
Restituisce il primo indice (base 0) del secondo argomento come sottostringa nel primo argomento. Entrambi gli argomenti devono essere stringhe. Gli argomenti non di tipo String sono soggetti alle regole di conversione standard nel tipo String. Questa funzione non si applica alle matrici, ma solo alle stringhe. Supportata da SQL versione 2016-03-23 e versioni successive.
Esempi:
`indexof("abcd", "bc") ` = 1
## isNull()
Restituisce true se l'argomento è il valore `Null`. Supportata da SQL versione 2016-03-23 e versioni successive.
Esempi:
`isNull(5) ` = false.
`isNull(Null) ` = true.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | true |
| Undefined | false |
## isUndefined()
Restituisce true se l'argomento è `Undefined`. Supportata da SQL versione 2016-03-23 e versioni successive.
Esempi:
`isUndefined(5) ` = false.
`isUndefined(floor([1,2,3]))) ` = true.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | false |
| Undefined | true |
## length(String)
Restituisce il numero di caratteri della stringa fornita. Agli argomenti non di tipo `String` si applicano le regole di conversione standard. Supportata da SQL versione 2016-03-23 e versioni successive.
Esempi:
`length("hi")` = 2
`length(false)` = 5
## ln(Decimal)
Restituisce il logaritmo naturale dell'argomento. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `ln(e)` = 1.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), il logaritmo naturale dell'argomento. |
| Decimal | Decimal (a precisione doppia), il logaritmo naturale dell'argomento. |
| Boolean | Undefined. |
| String | Decimal (a precisione doppia), il logaritmo naturale dell'argomento. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## log(Decimal)
Restituisce il logaritmo in base 10 dell'argomento. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `log(100)` = 2.0.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), il logaritmo in base 10 dell'argomento. |
| Decimal | Decimal (a precisione doppia), il logaritmo in base 10 dell'argomento. |
| Boolean | Undefined. |
| String | Decimal (a precisione doppia), il logaritmo in base 10 dell'argomento. Se il tipo String non può essere convertito in Decimal, il risultato è Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## lower(String)
Restituisce la versione con caratteri minuscoli del tipo `String` specificato. Gli argomenti non di tipo String vengono convertiti in stringhe usando le regole di conversione standard. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`lower("HELLO")` = "hello".
`lower(["HELLO"])` = "[\$1"hello\$1"]".
## lpad(String, Int)
Restituisce l'argomento `String` con spaziatura sul lato sinistro, con il numero di spazi specificato dal secondo argomento. L'argomento `Int` deve essere compreso tra 0 e 1.000. Se il valore fornito è al di fuori di questo intervallo valido, l'argomento viene impostato sul valore valido più vicino (0 o 1000). Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`lpad("hello", 2)` = "` hello`".
`lpad(1, 3)` = "` 1`"
****
| Tipo di argomento 1 | Tipo di argomento 2 | Risultato |
| --- | --- | --- |
| String | Int | String, il tipo String fornito con spaziatura sul lato sinistro, con un numero di spazi corrispondente a Int. |
| String | Decimal | L'argomento Decimal viene arrotondato per difetto al valore Int più vicino e al tipo String viene aggiunta una spaziatura a sinistra, con il numero di spazi specificato. |
| String | String | Il secondo argomento viene convertito in un tipo Decimal, arrotondato per difetto al valore Int più vicino e al tipo String viene aggiunta una spaziatura a sinistra con il numero di spazi specificato. Se il secondo argomento non può essere convertito in un tipo Int, il risultato è Undefined. |
| Altro valore | Int/Decimal/String | Il primo valore viene convertito in un tipo String usando le conversioni standard e quindi al tipo String viene applicata la funzione LPAD. Se la conversione non è possibile, il risultato è Undefined. |
| Qualsiasi valore | Altro valore | Undefined. |
## ltrim(String)
Rimuove tutti gli spazi vuoti iniziali (tabulazioni e spazi) dal tipo `String` fornito. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`Ltrim(" h i ")` = "hi ".
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | La rappresentazione String di Int con tutti gli spazi vuoti iniziali rimossi. |
| Decimal | La rappresentazione String di Decimal con tutti gli spazi vuoti iniziali rimossi. |
| Boolean | La rappresentazione String del tipo booleano ("true" o "false") con tutti gli spazi vuoti iniziali rimossi. |
| String | L'argomento con tutti gli spazi vuoti iniziali rimossi. |
| Array | La rappresentazione String del tipo Array (usando le regole di conversione standard) con tutti gli spazi vuoti iniziali rimossi. |
| Oggetto | La rappresentazione String del tipo Object (usando le regole di conversione standard) con tutti gli spazi vuoti iniziali rimossi. |
| Null | Undefined. |
| Undefined | Undefined. |
## machinelearning\$1predict(modelId, roleArn, record)
Usa la `machinelearning_predict` funzione per fare previsioni utilizzando i dati di un messaggio MQTT basato su un modello Amazon SageMaker AI. Supportata da SQL versione 2015-10-08 e versioni successive. Gli argomenti per la funzione `machinelearning_predict` sono i seguenti:
modelId
ID del modello in base a cui effettuare la previsione. L'endpoint in tempo reale del modello deve essere abilitato.
roleArn
Ruolo IAM che dispone di una policy con autorizzazioni `machinelearning:Predict` e `machinelearning:GetMLModel` e permette l'accesso al modello in base a cui viene effettuata la previsione.
record
I dati da passare all' SageMaker API AI Predict. Questo elemento deve essere rappresentato come oggetto JSON a singolo livello. Se il record è un oggetto JSON multilivello, viene appiattito mediante la serializzazione dei rispettivi valori. Ad esempio, l'oggetto JSON seguente:
```
{ "key1": {"innerKey1": "value1"}, "key2": 0}
```
diventerebbe:
```
{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}
```
La funzione restituisce un oggetto JSON con i campi seguenti:
predictedLabel
Classificazione dell'input in base al modello.
details
Contiene gli attributi seguenti:
PredictiveModelType
Tipo di modello. I valori validi sono REGRESSION, BINARY, MULTICLASS.
Algoritmo
L'algoritmo utilizzato dall' SageMaker IA per fare previsioni. Il valore deve essere SGD.
predictedScores
Contiene il punteggio di classificazione non elaborato corrispondente a ogni etichetta.
predictedValue
Il valore previsto dall' SageMaker IA.
## mod(Decimal, Decimal)
Restituisce il resto della divisione del primo argomento per il secondo argomento. Equivalente a [remainder(Decimal, Decimal)](#iot-func-remainder). È anche possibile usare "%" come operatore infisso per la stessa funzionalità di modulo. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `mod(8, 3)` = 2.
****
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int | Int | Int, il resto della divisione del primo argomento per il secondo argomento. |
| Int/Decimal | Int/Decimal | Decimal, il resto della divisione del primo argomento per il secondo operando. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe vengono convertite in decimali, il risultato è il resto della divisione del primo argomento per il secondo argomento. In caso contrario, Undefined. |
| Altro valore | Altro valore | Undefined. |
## nanvl (,) AnyValue AnyValue
Restituisce il primo argomento, se si tratta di un tipo `Decimal` valido. In caso contrario, viene restituito il secondo argomento. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `Nanvl(8, 3)` = 8.
****
| Tipo di argomento 1 | Tipo di argomento 2 | Output |
| --- | --- | --- |
| Undefined | Qualsiasi valore | Secondo argomento. |
| Null | Qualsiasi valore | Secondo argomento. |
| Decimal (non un numero) | Qualsiasi valore | Secondo argomento. |
| Decimal (numero) | Qualsiasi valore | Primo argomento. |
| Altro valore | Qualsiasi valore | Primo argomento. |
## newuuid()
Restituisce un valore UUID casuale a 16 byte. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `newuuid()` = `123a4567-b89c-12d3-e456-789012345000`
## numbytes(String)
Restituisce il numero di byte nella codifica UTF-8 della stringa fornita. Agli argomenti non di tipo `String` si applicano le regole di conversione standard. Supportata da SQL versione 2016-03-23 e versioni successive.
Esempi:
`numbytes("hi")` = 2
`numbytes("€") ` = 3
## parse\$1time(String, Long[, String])
Usa la `parse_time` funzione per formattare un timestamp in un formato leggibile dall'uomo. date/time Supportata da SQL versione 2016-03-23 e versioni successive. Per convertire una stringa di timestamp in millisecondi, consulta [time\$1to\$1epoch(String, String)](#iot-sql-function-time-to-epoch).
La funzione `parse_time` prevede i seguenti argomenti:
pattern
[(Stringa) Un date/time modello che segue i formati Joda-Time.](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html)
timestamp
(Long) Ora da formattare in millisecondi dall'epoca (Unix epoch). Consulta la funzione [timestamp()](#iot-function-timestamp).
timezone
(Stringa) Fuso orario del valore di data/ora formattato. Il valore predefinito è "UTC". La funzione supporta i [fusi orari Joda-Time](http://joda-time.sourceforge.net/timezones.html). Questo argomento è facoltativo.
Esempi:
Quando questo messaggio viene pubblicato nell'argomento "A/B", il payload `{"ts": "1970.01.01 AD at 21:46:40 CST"}` viene inviato al 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\", 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 questo messaggio viene pubblicato nell'argomento "A/B", un payload simile a `{"ts": "2017.06.09 AD at 17:19:46 UTC"}` (ma con valore di data/ora corrente) viene inviato al 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"
}
}
```
È anche possibile usare `parse_time()` come modello di sostituzione. Quando, ad esempio, questo messaggio viene pubblicato nell'argomento "A/B", il payload viene inviato al bucket S3 con key = "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)
Restituisce il primo argomento elevato al secondo argomento. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `power(2, 5)` = 32.0.
****
| Tipo di argomento 1 | Tipo di argomento 2 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Tipo Decimal (a precisione doppia), il primo argomento elevato alla potenza del secondo argomento. |
| Int/Decimal/String | Int/Decimal/String | Tipo Decimal (a precisione doppia), il primo argomento elevato alla potenza del secondo argomento. Le stringhe vengono convertite in decimali. Se il tipo String non può essere convertito in Decimal, il risultato è Undefined. |
| Altro valore | Altro valore | Undefined. |
## principal()
Restituisce l'entità principale utilizzata dal dispositivo per l'autenticazione, in base al modo in cui il messaggio di attivazione è stato pubblicato. La tabella seguente descrive il principale restituito per ogni metodo e protocollo di pubblicazione.
****
| Come viene pubblicato il messaggio | Protocollo | Tipo di credenziali | Principale |
| --- | --- | --- | --- |
| Client MQTT | MQTT | Certificato del dispositivo X.509 | Identificazione personale del certificato X.509 |
| AWS IoT console (client MQTT) | MQTT | Utente o ruolo IAM | iam-role-id:session-name |
| AWS CLI | HTTP | Utente o ruolo IAM | userid |
| AWS IoT SDK del dispositivo | MQTT | Certificato del dispositivo X.509 | Identificazione personale del certificato X.509 |
| AWS IoT SDK del dispositivo | MQTT over WebSocket | Utente o ruolo IAM | userid |
I seguenti esempi mostrano i diversi tipi di valori che `principal()` può restituire:
+ Identificazione personale del certificato X.509: `ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373`
+ ID del ruolo IAM e nome della sessione: `ABCD1EFG3HIJK2LMNOP5:my-session-name`
+ Restituisce un ID utente: `ABCD1EFG3HIJK2LMNOP5`
## rand()
Restituisce un tipo double pseudocasuale, distribuito uniformemente e compreso tra 0,0 e 1,0. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`rand()` = 0.8231909191640703
## regexp\$1matches(String, String)
Restituisce true se la stringa (primo argomento) contiene una corrispondenza dell'espressione regolare (secondo argomento). Se lo usi `|` nell'espressione regolare, usala con`()`.
Esempi:
`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.
**Primo argomento:**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Rappresentazione String del tipo Int. |
| Decimal | Rappresentazione String del tipo Decimal. |
| Boolean | Rappresentazione String del tipo booleano ("true" o "false"). |
| String | Tipo String. |
| Array | Rappresentazione String del tipo Array (usando le regole di conversione standard). |
| Oggetto | Rappresentazione String del tipo Object (usando le regole di conversione standard). |
| Null | Undefined. |
| Undefined | Undefined. |
*Secondo argomento:*
Deve essere un'espressione regex valida. I tipi non String vengono convertiti in tipi `String` usando le regole di conversione standard. A seconda del tipo, la stringa risultante potrebbe non essere un'espressione regolare valida. Se l'argomento (convertito) non è un valore regex valido, il risultato è `Undefined`.
## regexp\$1replace(String, String, String)
Sostituisce tutte le occorrenze del secondo argomento (espressione regolare) nel primo argomento con il terzo argomento. Può fare riferimento a gruppi Capture con "\$1". Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`regexp_replace("abcd", "bc", "x")` = "axd".
`regexp_replace("abcd", "b(.*)d", "$1")` = "ac".
**Primo argomento:**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Rappresentazione String del tipo Int. |
| Decimal | Rappresentazione String del tipo Decimal. |
| Boolean | Rappresentazione String del tipo booleano ("true" o "false"). |
| String | Valore di origine. |
| Array | Rappresentazione String del tipo Array (usando le regole di conversione standard). |
| Oggetto | Rappresentazione String del tipo Object (usando le regole di conversione standard). |
| Null | Undefined. |
| Undefined | Undefined. |
*Secondo argomento:*
Deve essere un'espressione regex valida. I tipi non String vengono convertiti in tipi `String` usando le regole di conversione standard. A seconda del tipo, la stringa risultante potrebbe non essere un'espressione regolare valida. Se l'argomento (convertito) non è un'espressione regex valida, il risultato è `Undefined`.
*Terzo argomento:*
Deve essere una stringa di sostituzione regex valida. Può fare riferimento a gruppi Capture. I tipi non String vengono convertiti in tipi `String` usando le regole di conversione standard. Se l'argomento (convertito) non è una stringa di sostituzione regex valida, il risultato è `Undefined`.
## regexp\$1substr(String, String)
Trova la prima corrispondenza del secondo parametro (regex) nel primo parametro. Può fare riferimento a gruppi Capture con "\$1". Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`regexp_substr("hihihello", "hi")` = "hi"
`regexp_substr("hihihello", "(hi)*")` = «hihi»
**Primo argomento:**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Rappresentazione String del tipo Int. |
| Decimal | Rappresentazione String del tipo Decimal. |
| Boolean | Rappresentazione String del tipo booleano ("true" o "false"). |
| String | Argomento String. |
| Array | Rappresentazione String del tipo Array (usando le regole di conversione standard). |
| Oggetto | Rappresentazione String del tipo Object (usando le regole di conversione standard). |
| Null | Undefined. |
| Undefined | Undefined. |
*Secondo argomento:*
Deve essere un'espressione regex valida. I tipi non String vengono convertiti in tipi `String` usando le regole di conversione standard. A seconda del tipo, la stringa risultante potrebbe non essere un'espressione regolare valida. Se l'argomento (convertito) non è un'espressione regex valida, il risultato è `Undefined`.
## remainder(Decimal, Decimal)
Restituisce il resto della divisione del primo argomento per il secondo argomento. Equivalente a [mod(Decimal, Decimal)](#iot-func-mod). È anche possibile usare "%" come operatore infisso per la stessa funzionalità di modulo. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `remainder(8, 3)` = 2.
****
| Operando sinistro | Operando destro | Output |
| --- | --- | --- |
| Int | Int | Int, il resto della divisione del primo argomento per il secondo argomento. |
| Int/Decimal | Int/Decimal | Decimal, il resto della divisione del primo argomento per il secondo operando. |
| String/Int/Decimal | String/Int/Decimal | Se tutte le stringhe vengono convertite in decimali, il risultato è il resto della divisione del primo argomento per il secondo argomento. In caso contrario, Undefined. |
| Altro valore | Altro valore | Undefined. |
## replace(String, String, String)
Sostituisce tutte le occorrenze del secondo argomento nel primo argomento con il terzo argomento. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`replace("abcd", "bc", "x")` = `"axd"`.
`replace("abcdabcd", "b", "x")` = `"axcdaxcd"`.
**Tutti gli argomenti**
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Rappresentazione String del tipo Int. |
| Decimal | Rappresentazione String del tipo Decimal. |
| Boolean | Rappresentazione String del tipo booleano ("true" o "false"). |
| String | Valore di origine. |
| Array | Rappresentazione String del tipo Array (usando le regole di conversione standard). |
| Oggetto | Rappresentazione String del tipo Object (usando le regole di conversione standard). |
| Null | Undefined. |
| Undefined | Undefined. |
## rpad(String, Int)
Restituisce l'argomento String con spaziatura sul lato destro, con il numero di spazi specificato nel secondo argomento. L'argomento `Int` deve essere compreso tra 0 e 1.000. Se il valore fornito è al di fuori di questo intervallo valido, l'argomento viene impostato sul valore valido più vicino (0 o 1000). Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`rpad("hello", 2)` = "`hello `".
`rpad(1, 3)` = "`1 `".
****
| Tipo di argomento 1 | Tipo di argomento 2 | Risultato |
| --- | --- | --- |
| String | Int | Al tipo String viene aggiunta una spaziatura sul lato destro, con un numero di spazi corrispondente al valore Int fornito. |
| String | Decimal | L'argomento Decimal viene arrotondato per difetto al valore Int più vicino e alla stringa viene aggiunta una spaziatura sul lato destro, con un numero di spazi corrispondente al valore Int fornito. |
| String | String | Il secondo argomento viene convertito in un tipo Decimal, arrotondato per difetto al valore Int più vicino. Al tipo String viene aggiunta una spaziatura sul lato destro, con un numero di spazi corrispondente al valore Int . |
| Altro valore | Int/Decimal/String | Il primo valore viene convertito in un tipo String usando le conversioni standard e quindi al tipo String viene applicata la funzione rpad. Se la conversione non è possibile, il risultato è Undefined. |
| Qualsiasi valore | Altro valore | Undefined. |
## round(Decimal)
Arrotonda il tipo `Decimal` specificato al valore `Int` più vicino. Se `Decimal` è equidistante da due valori `Int` (ad esempio, 0,5), il tipo `Decimal` viene arrotondato per eccesso. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `Round(1.2)` = 1.
`Round(1.5)` = 2.
`Round(1.7)` = 2.
`Round(-1.1)` = -1.
`Round(-1.5)` = -2.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Argomento. |
| Decimal | Decimal viene arrotondato per difetto al valore Int più vicino. |
| String | Decimal viene arrotondato per difetto al valore Int più vicino. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. |
| Altro valore | Undefined. |
## rtrim(String)
Rimuove tutti gli spazi vuoti finali (tabulazioni e spazi) dal tipo `String` fornito. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`rtrim(" h i ")` = " h i"
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Rappresentazione String del tipo Int. |
| Decimal | Rappresentazione String del tipo Decimal. |
| Boolean | Rappresentazione String del tipo booleano ("true" o "false"). |
| Array | Rappresentazione String del tipo Array (usando le regole di conversione standard). |
| Oggetto | Rappresentazione String del tipo Object (usando le regole di conversione standard). |
| Null | Undefined. |
| Undefined | Undefined |
## sign(Decimal)
Restituisce il segno di un determinato numero. Quando il segno dell'argomento è positivo, viene restituito 1. Quando il segno dell'argomento è negativo, viene restituito -1. Se l'argomento è 0, viene restituito 0. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`sign(-7)` = -1.
`sign(0)` = 0.
`sign(13)` = 1.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Int, il segno del valore Int. |
| Decimal | Int, il segno del valore Decimal. |
| String | Int, il segno del valore Decimal. La stringa viene convertita in un valore Decimal e viene restituito il segno del valore Decimal. Se il tipo String non può essere convertito in Decimal, il risultato è Undefined. Supportata da SQL versione 2015-10-08 e versioni successive. |
| Altro valore | Undefined. |
## sin(Decimal)
Restituisce il seno di un numero in radianti. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `sin(0)` = 0.0
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), il seno dell'argomento. |
| Decimal | Decimal (a precisione doppia), il seno dell'argomento. |
| Boolean | Undefined. |
| String | Decimal (a precisione doppia), il seno dell'argomento. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## sinh(Decimal)
Restituisce il seno iperbolico di un numero. I valori `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Il risultato è un valore `Decimal` a precisione doppia. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `sinh(2.3)` = 4.936961805545957
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), il seno iperbolico dell'argomento. |
| Decimal | Decimal (a precisione doppia), il seno iperbolico dell'argomento. |
| Boolean | Undefined. |
| String | Decimal (a precisione doppia), il seno iperbolico dell'argomento. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## sourceip()
Recupera l'indirizzo IP di un dispositivo o del router a cui si connette. Se il dispositivo è connesso direttamente a Internet, la funzione restituirà l'indirizzo IP di origine del dispositivo. Se il dispositivo è connesso a un router che si connette a Internet, la funzione restituirà l'indirizzo IP di origine del router. Supportato da SQL versione 2016-03-23. `sourceip()` non accetta alcun parametro.
**Importante**
L'indirizzo IP di origine pubblico di un dispositivo è spesso l'indirizzo IP dell'ultimo gateway Network Address Translation (NAT), ad esempio il router o il modem via cavo del provider di servizi Internet.
Esempi:
`sourceip()="192.158.1.38"`
`sourceip()="1.102.103.104"`
`sourceip()="2001:db8:ff00::12ab:34cd"`
Esempio SQL:
`SELECT *, sourceip() as deviceIp FROM 'some/topic'`
Esempi di come utilizzare la funzione sourceip () nelle azioni delle AWS IoT Core regole:
**Esempio 1**
L'esempio seguente mostra come chiamare la funzione () come [modello di sostituzione](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) in un'[operazione 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"
}
}
]
}
}
```
**Esempio 2**
L'esempio seguente mostra come aggiungere la funzione sourceip() come proprietà utente MQTT utilizzando i [modelli di sostituzione](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()}"
}
]
}
}
}
]
}
}
```
È possibile recuperare l'indirizzo IP di origine dai messaggi che passano alle AWS IoT Core regole dai percorsi Message Broker e [Basic](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html) Ingest. Puoi anche recuperare l'IP di origine per entrambi i messaggi. IPv4 IPv6 L'IP di origine verrà visualizzato come segue:
IPv6: `yyyy:yyyy:yyyy::yyyy:yyyy`
IPv4: `xxx.xxx.xxx.xxx`
**Nota**
L'IP di origine originale non verrà passato tramite l'[operazione Republish](republish-rule-action.md).
## substring(String, Int[, Int])
Richiede un tipo `String` seguito da uno o due valori `Int`. Per un tipo `String` e un singolo argomento `Int`, questa funzione restituisce la sottostringa del tipo `String` fornito dall'indice `Int` specificato (in base 0, incluso) fino alla fine di `String`. Per un tipo `String` e due argomenti `Int`, questa funzione restituisce la sottostringa del tipo `String` fornito dal primo argomento di indice `Int` specificato (in base 0, incluso) al secondo argomento di indice `Int` (in base 0, escluso). Gli indici inferiori a zero vengono impostati su zero. Gli indici superiori alla lunghezza di `String` vengono impostati sulla lunghezza di `String`. Per la versione con tre argomenti, se il primo indice è maggiore o uguale al secondo indice, il risultato è il tipo `String` vuoto.
Se gli argomenti forniti non sono (*String*,*Int*) o (,*String*,*Int*)*Int*, le conversioni standard vengono applicate agli argomenti per tentare di convertirli nei tipi corretti. Se i tipi non possono essere convertiti, il risultato della funzione è `Undefined`. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`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()
Restituisce la versione SQL specificata in questa regola. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`sql_version()` = "2016-03-23"
## sqrt(Decimal)
Restituisce la radice quadrata di un numero. Gli argomenti `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `sqrt(9)` = 3.0.
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Radice quadrata dell'argomento. |
| Decimal | Radice quadrata dell'argomento. |
| Boolean | Undefined. |
| String | Radice quadrata dell'argomento. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## startswith(String, String)
Restituisce un tipo `Boolean` che indica se il primo argomento String inizia con il secondo argomento String. Se uno degli argomenti è `Null` oppure `Undefined`, il risultato è `Undefined`. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`startswith("ranger","ran")` = true
****
| Tipo di argomento 1 | Tipo di argomento 2 | Risultato |
| --- | --- | --- |
| String | String | Indica se il primo argomento String inizia con il secondo argomento String. |
| Altro valore | Altro valore | Entrambi gli argomenti vengono convertiti in stringhe usando le regole di conversione standard. Restituisce true se il primo argomento String inizia con il secondo argomento String. Se uno degli argomenti è Null oppure Undefined, il risultato è Undefined. |
## tan(Decimal)
Restituisce la tangente di un numero in radianti. I valori `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `tan(3)` = -0.1425465430742778
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), la tangente dell'argomento. |
| Decimal | Decimal (a precisione doppia), la tangente dell'argomento. |
| Boolean | Undefined. |
| String | Decimal (a precisione doppia), la tangente dell'argomento. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## tanh(Decimal)
Restituisce la tangente iperbolica di un numero in radianti. I valori `Decimal` vengono arrotondati a un valore a precisione doppia prima dell'applicazione della funzione. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `tanh(2.3)` = 0.9800963962661914
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | Decimal (a precisione doppia), la tangente iperbolica dell'argomento. |
| Decimal | Decimal (a precisione doppia), la tangente iperbolica dell'argomento. |
| Boolean | Undefined. |
| String | Decimal (a precisione doppia), la tangente iperbolica dell'argomento. Se la stringa non può essere convertita in un tipo Decimal, il risultato è Undefined. |
| Array | Undefined. |
| Oggetto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## time\$1to\$1epoch(String, String)
Utilizzo della funzione `time_to_epoch` per convertire una stringa di timestamp in un numero di millisecondi nel tempo dell'epoca Unix. Supportata da SQL versione 2016-03-23 e versioni successive. Per convertire millisecondi in una stringa di timestamp formattata, consulta [parse\$1time(String, Long[, String])](#iot-sql-function-parse-time).
La funzione `time_to_epoch` accetta i seguenti argomenti:
timestamp
(Stringa) Stringa dell'indicatore temporale da convertire in millisecondi dall'epoca di Unix. Se la stringa del timestamp non specifica un fuso orario, la funzione utilizza il fuso orario UTC.
pattern
(Stringa) Un date/time modello che segue i [formati JDK11 temporali](http://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
Esempi:
`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()
Restituisce il timestamp corrente in millisecondi a partire dalle 00:00:00 Coordinated Universal Time (UTC) di giovedì 1 gennaio 1970, come osservato dal motore delle regole. AWS IoT Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio: `timestamp()` = `1481825251155`
## topic(Decimal)
Restituisce l'argomento a cui è stato inviato il messaggio che ha attivato la regola. Se non viene specificato alcun parametro, viene restituito l'intero argomento. Il parametro `Decimal` viene utilizzato per specificare un segmento di argomento specifico, con 1 che indica il primo segmento. Per l'argomento `foo/bar/baz`, topic(1) restituisce `foo`, topic(2) restituisce `bar` e così via. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`topic()` = "things/myThings/thingOne"
`topic(1)` = "things"
Quando viene utilizzato [Basic Ingest](iot-basic-ingest.md), il prefisso iniziale dell'argomento (`$aws/rules/rule-name`) non è disponibile per la funzione dell'argomento(). Ad esempio, dato l'argomento:
`$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`
`topic()` = "Buildings/Building5/Floor2/Room201/Lights"
`topic(3)` = "Floor2"
## traceid()
Restituisce l'ID traccia (UUID) del messaggio MQTT oppure `Undefined` se il messaggio non è stato inviato tramite MQTT. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`traceid() ` = "12345678-1234-1234-1234-123456789012"
## transform(String, Object, Array)
Restituisce una matrice di oggetti contenenti il risultato della trasformazione specificata del parametro `Object` sul parametro `Array`.
Supportata da SQL versione 2016-03-23 e versioni successive.
Stringa
Modalità di trasformazione da utilizzare. Consulta la tabella seguente per informazioni sulle modalità di trasformazione supportate e sulla modalità di creazione dell'oggetto `Result` da `Object` e dai parametri `Array`.
Oggetto
Un oggetto che contiene gli attributi da applicare a ciascun elemento dell’`Array`.
Array
Matrice di oggetti in cui gli attributi di `Object` vengono applicati.
Ogni oggetto in questa matrice corrisponde a un oggetto nella risposta della funzione. Ogni oggetto nella risposta della funzione contiene gli attributi presenti nell'oggetto originale e gli attributi forniti da `Object` come determinato dalla modalità di trasformazione specificata in `String`.
| Parametro `String` | Parametro `Object` | Parametro `Array` | Risultato |
| --- | --- | --- | --- |
| `enrichArray` | Oggetto | Matrice di oggetti | Una matrice di oggetti in cui ogni oggetto contiene gli attributi di un elemento del parametro `Array` e gli attributi del parametro `Object`. |
| Qualsiasi altro valore | Qualsiasi valore | Qualsiasi valore | Undefined |
**Nota**
L'array restituito da questa funzione è limitato a 128 KiB.
### Esempio 1 di funzione Transform
In questo esempio viene mostrato come la funzione **transform()** produce una singola matrice di oggetti da un oggetto dati e una matrice.
In questo esempio, il seguente messaggio viene pubblicato nell'argomento MQTT `A/B`.
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Questa istruzione SQL per un'operazione regola argomento utilizza la funzione **transform()** con un valore `String` di `enrichArray`. In questo esempio, `Object` è la proprietà `attributes` dal payload del messaggio e `Array` è la matrice `values` che contiene tre oggetti.
```
select value transform("enrichArray", attributes, values) from 'A/B'
```
Dopo aver ricevuto il payload del messaggio, l'istruzione SQL valuta la seguente risposta.
```
[
{
"a": 3,
"data1": 1,
"data2": 2
},
{
"b": 4,
"data1": 1,
"data2": 2
},
{
"c": 5,
"data1": 1,
"data2": 2
}
]
```
### Esempio 2 di funzione Transform
In questo esempio viene mostrato come la funzione **transform()** può utilizzare valori letterali per includere e rinominare singoli attributi dal payload del messaggio.
In questo esempio, il seguente messaggio viene pubblicato nell'argomento MQTT `A/B`. Questo è lo stesso messaggio utilizzato in [Esempio 1 di funzione Transform](#iot-func-transform-example1).
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Questa istruzione SQL per un'operazione regola argomento utilizza la funzione **transform()** con un valore `String` di `enrichArray`. L’`Object` nella funzione **transform()** ha un singolo attributo denominato `key` con il valore di `attributes.data1` nel payload del messaggio e `Array` è la matrice `values`, che contiene gli stessi tre oggetti utilizzati nell'esempio precedente.
```
select value transform("enrichArray", {"key": attributes.data1}, values) from 'A/B'
```
Dopo aver ricevuto il payload del messaggio, questa istruzione SQL valuta la seguente risposta. Nota come la proprietà `data1` è denominata `key` nella risposta.
```
[
{
"a": 3,
"key": 1
},
{
"b": 4,
"key": 1
},
{
"c": 5,
"key": 1
}
]
```
### Esempio 3 di funzione Transform
In questo esempio viene mostrato come la funzione **transform()** può essere utilizzata in clausole SELECT nidificate per selezionare più attributi e creare nuovi oggetti per l'elaborazione successiva.
In questo esempio, il seguente messaggio viene pubblicato nell'argomento MQTT `A/B`.
```
{
"data1": "example",
"data2": {
"a": "first attribute",
"b": "second attribute",
"c": [
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false
}
]
}
}
```
L’`Object` per questa funzione di trasformazione è l'oggetto restituito dall'istruzione SELECT, che contiene `a` ed elementi `b` del messaggio `data2` oggetto. Il parametro `Array` è costituito dai due oggetti della matrice `data2.c` nel messaggio originale.
```
select value transform('enrichArray', (select a, b from data2), (select value c from data2)) from 'A/B'
```
Con il messaggio precedente, l'istruzione SQL valuta la seguente risposta.
```
[
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true,
"a": "first attribute",
"b": "second attribute"
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false,
"a": "first attribute",
"b": "second attribute"
}
]
```
La matrice restituita in questa risposta può essere utilizzata con operazioni di regole di argomento che supportano `batchMode`.
## trim(String)
Rimuove tutti gli spazi vuoti iniziali e finali dal tipo `String` fornito. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempio:
`Trim(" hi ") ` = "hi"
****
| Tipo di argomento | Risultato |
| --- | --- |
| Int | La rappresentazione String di Int con tutti gli spazi vuoti iniziali e finali rimossi. |
| Decimal | La rappresentazione String di Decimal con tutti gli spazi vuoti iniziali e finali rimossi. |
| Boolean | La rappresentazione String di Boolean ("true" o "false") con tutti gli spazi vuoti iniziali e finali rimossi. |
| String | String con tutti gli spazi vuoti iniziali e finali rimossi. |
| Array | Rappresentazione String del tipo Array usando le regole di conversione standard. |
| Oggetto | Rappresentazione String del tipo Object usando le regole di conversione standard. |
| Null | Undefined. |
| Undefined | Undefined. |
## trunc(Decimal, Int)
Tronca il primo argomento al numero di posizioni `Decimal` specificato nel secondo argomento. Se il secondo argomento è inferiore a zero, viene impostato su zero. Se il secondo argomento è superiore a 34, viene impostato su 34. Gli zeri finali vengono eliminati dal risultato. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`trunc(2.3, 0)` = 2.
`trunc(2.3123, 2)` = 2.31.
`trunc(2.888, 2)` = 2.88.
`trunc(2.00, 5)` = 2.
****
| Tipo di argomento 1 | Tipo di argomento 2 | Risultato |
| --- | --- | --- |
| Int | Int | Valore di origine. |
| Int/Decimal | Int/Decimal | Il primo argomento viene troncato alla lunghezza indicata dal secondo argomento. Il secondo argomento, se non è un tipo Int, viene arrotondato per difetto al valore Int più vicino. |
| Int/Decimal/String | Int/Decimal | Il primo argomento viene troncato alla lunghezza indicata dal secondo argomento. Il secondo argomento, se non è un tipo Int, viene arrotondato per difetto al valore Int più vicino. Un tipo String viene convertito in un valore Decimal. Se la conversione della stringa non riesce, il risultato è Undefined. |
| Altro valore | | Undefined. |
## upper(String)
Restituisce la versione con caratteri maiuscoli del tipo `String` specificato. Gli argomenti non di tipo `String` vengono convertiti in `String` usando le regole di conversione standard. Supportata da SQL versione 2015-10-08 e versioni successive.
Esempi:
`upper("hello")` = "HELLO"
`upper(["hello"])` = "[\$1"HELLO\$1"]"
# Valori letterali
È possibile specificare direttamente oggetti letterali nelle clausole SELECT e WHERE della regola SQL, che possono essere utili per passare informazioni.
**Nota**
I valori letterali sono disponibili solo quando si usa SQL 2016-03-23 o una versione successiva.
Viene usata la sintassi degli oggetti JSON (coppie chiave-valore, separate da virgole, dove le chiavi sono stringhe e i valori sono valori JSON, racchiusi tra parentesi graffe \$1\$1). Ad esempio:
Payload in ingresso pubblicato nell'argomento `topic/subtopic`: `{"lat_long": [47.606,-122.332]}`
Istruzione SQL: `SELECT {'latitude': get(lat_long, 0),'longitude':get(lat_long, 1)} as lat_long FROM 'topic/subtopic'`
Il payload in uscita risultante sarebbe: `{"lat_long":{"latitude":47.606,"longitude":-122.332}}`.
È anche possibile specificare direttamente matrici nelle clausole SELECT e WHERE della regola SQL, per poter raggruppare le informazioni. Viene usata la sintassi JSON (elementi separati da virgola racchiusi tra parentesi quadre [] per creare una matrice letterale). Ad esempio:
Payload in ingresso pubblicato nell'argomento `topic/subtopic`: `{"lat": 47.696, "long": -122.332}`
Istruzione SQL: `SELECT [lat,long] as lat_long FROM 'topic/subtopic'`
Il payload in uscita risultante sarebbe: `{"lat_long": [47.606,-122.332]}`.
# Istruzioni case
Le istruzioni case possono essere usate per l'esecuzione con diramazioni, come un'istruzione switch.
Sintassi:
```
CASE v WHEN t[1] THEN r[1]
WHEN t[2] THEN r[2] ...
WHEN t[n] THEN r[n]
ELSE r[e] END
```
L'espressione *`v`* viene valutata e confrontata per verificare la corrispondenza con il valore *`t[i]`* di ogni espressione `WHEN`. Se viene trovata una corrispondenza, la clausola *`r[i]`* diventa il risultato dell'istruzione `CASE`. Le clausole `WHEN` vengono valutate in ordine, cosicché, in caso di più di una clausola di corrispondenza, il risultato della prima clausola di corrispondenza diventi il risultato dell'istruzione `CASE`. Se non ci sono corrispondenze, il risultato è il *`r[e]`* della clausola `ELSE`. Se non c'è corrispondenza e nessuna clausola `ELSE`, il risultato è `Undefined`.
Le istruzioni `CASE` richiedono almeno una clausola `WHEN`. Una clausola `ELSE` è facoltativa.
Ad esempio:
Payload in ingresso pubblicato nell'argomento `topic/subtopic`:
```
{
"color":"yellow"
}
```
Istruzione 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'
```
Il payload in uscita risultante sarebbe:
```
{
"instructions":"caution"
}
```
**Nota**
Se *`v`* è `Undefined`, il risultato dell'istruzione del caso è `Undefined`.
# Estensioni JSON
È possibile usare le estensioni seguenti nella sintassi SQL ANSI per semplificare l'uso degli oggetti JSON nidificati.
Operatore "."
Questo operatore accede ai membri degli oggetti e delle funzioni JSON incorporati in modo identico a ANSI SQL e. JavaScript Esempio:
```
SELECT foo.bar AS bar.baz FROM 'topic/subtopic'
```
seleziona il valore della proprietà `bar` nell’oggetto `foo` dal seguente payload del messaggio inviato all'argomento `topic/subtopic`.
```
{
"foo": {
"bar": "RED",
"bar1": "GREEN",
"bar2": "BLUE"
}
}
```
Se il nome di una proprietà JSON include caratteri quali il trattino o caratteri numerici, la notazione "punto" non funzionerà. Invece, devi utilizzare [get function](iot-sql-functions.md#iot-sql-function-get) per estrarre il valore della proprietà.
In questo esempio viene inviato il seguente messaggio all'argomento `iot/rules`.
```
{
"mydata": {
"item2": {
"0": {
"my-key": "myValue"
}
}
}
}
```
Normalmente, il valore di `my-key` verrebbe identificato come in questa query.
```
SELECT * from iot/rules WHERE mydata.item2.0.my-key= "myValue"
```
Tuttavia, poiché il nome della proprietà `my-key` contiene un trattino e `item2` contiene un carattere numerico, [get function](iot-sql-functions.md#iot-sql-function-get) deve essere utilizzato come mostra la seguente query.
```
SELECT * from 'iot/rules' WHERE get(get(get(mydata,"item2"),"0"),"my-key") = "myValue"
```
Operatore `*`
Funziona nello stesso modo del carattere jolly `*` in SQL ANSI. Viene usato solo nella clausola SELECT e crea un nuovo oggetto JSON contenente i dati del messaggio. Se il payload del messaggio non è in formato JSON, `*` restituisce l'intero payload del messaggio come byte non elaborati. Ad esempio:
```
SELECT * FROM 'topic/subtopic'
```
**Applicazione di un funzione a un valore di attributo**
Di seguito è illustrato un esempio di payload JSON che potrebbe essere pubblicato da un dispositivo:
```
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
```
L'esempio seguente applica una funzione a un valore di attributo in un payload JSON:
```
SELECT temp, md5(deviceid) AS hashed_id FROM topic/#
```
Il risultato di questa query è l'oggetto JSON seguente:
```
{
"temp": 54.98,
"hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"
}
```
# Modelli di sostituzione
Puoi utilizzare un modello sostitutivo per aumentare i dati JSON restituiti quando una regola viene attivata ed esegue un'azione. AWS IoT La sintassi per un modello sostitutivo è `${` *espressione`}`, dove espressione può essere qualsiasi espressione* supportata dalle *clausole* SELECT, dalle AWS IoT clausole WHERE e. [AWS IoT azioni relative alle regole](iot-rule-actions.md) Questa espressione può essere inserita in un campo dell’operazione di una regola, consentendo di configurare dinamicamente un'operazione. In effetti, questa funzione sostituisce un'informazione in un'operazione. Questo include funzioni, operatori e informazioni presenti nel payload del messaggio originale.
**Importante**
Dal momento che un'espressione in un modello di sostituzione viene valutata separatamente dall'istruzione "SELECT...", non è possibile fare riferimento a un alias creato utilizzando la clausola AS. È possibile fare riferimento solo alle informazioni presenti nel payload originale, oltre alle [funzioni](iot-sql-functions.md) e agli [operatori](iot-sql-operators.md).
Per ulteriori informazioni sulle espressioni supportate, consulta [AWS IoT Riferimento SQL](iot-sql-reference.md).
Le seguenti operazioni delle regole supportano i modelli di sostituzione. Ogni operazione supporta campi diversi che possono essere sostituiti.
+ [Apache Kafka](apache-kafka-rule-action.md)
+ [CloudWatch allarmi](cloudwatch-alarms-rule-action.md)
+ [CloudWatch Registri](cloudwatch-logs-rule-action.md)
+ [CloudWatch metriche](cloudwatch-metrics-rule-action.md)
+ [DynamoDB](dynamodb-rule-action.md)
+ [Dynamo 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)
+ [Flussi di dati Kinesis](kinesis-rule-action.md)
+ [Firehose](kinesis-firehose-rule-action.md)
+ [Lambda](lambda-rule-action.md)
+ [Location (Ubicazione)](location-rule-action.md)
+ [OpenSearch](opensearch-rule-action.md)
+ [Ripubblica](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)
I modelli di sostituzione vengono visualizzati nei parametri di azione all'interno di una regola:
```
{
"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 questa regola viene attivata dal codice JSON seguente pubblicato su `my/iot/topic`:
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
}
}
```
Quindi questa regola pubblica il seguente codice JSON in, che sostituisce da: `my/iot/topic/republish` AWS IoT `${topic()}/republish`
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
},
"timestamp": 1579637878451
}
```
# Query di oggetti nidificati
Puoi utilizzare le clausole SELECT nidificate per eseguire le query sugli attributi all'interno di matrici e oggetti JSON interni. Supportata da SQL versione 2016-03-23 e versioni successive.
Considera il seguente messaggio 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**
Puoi convertire i valori in una nuova matrice con la seguente regola.
```
SELECT (SELECT VALUE n FROM e) as sensors FROM 'my/topic'
```
La regola genera l'output seguente.
```
{
"sensors": [
"temperature",
"light",
"acidity"
]
}
```
**Example**
Utilizzando lo stesso messaggio MQTT, puoi anche eseguire le query su un valore specifico all'interno di un oggetto nidificato con la seguente regola.
```
SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'
```
La regola genera l'output seguente.
```
{
"temperature": [
{
"v": 22.5
}
]
}
```
**Example**
Puoi anche livellare l'output con una regola più complicata.
```
SELECT get((SELECT v FROM e WHERE n = 'temperature'), 0).v as temperature FROM 'topic'
```
La regola genera l'output seguente.
```
{
"temperature": 22.5
}
```
# Utilizzo di payload binari
Quando il payload del messaggio deve essere gestito come dati binari non elaborati (invece che come oggetto JSON), è possibile usare l'operatore \$1 per farvi riferimento in una clausola SELECT.
**Topics**
+ [Esempi di payload binari](#binary-payloads-examples)
+ [Decodifica dei payload del messaggio protbuf](#binary-payloads-protobuf)
## Esempi di payload binari
Quando si utilizza \$1 per fare riferimento al payload del messaggio come dati binari non elaborati, puoi aggiungere dati alla regola. Se si dispone di un payload vuoto o in formato JSON, il payload risultante può aggiungere dati utilizzando la regola. Di seguito vengono riportati degli esempi di clausole `SELECT` supportate.
+ È possibile utilizzare le seguenti clausole `SELECT` solo con un \$1 per payload binari.
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ Puoi inoltre aggiungere dati e utilizzare le seguenti clausole `SELECT`.
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ È possibile utilizzare anche queste clausole `SELECT` con payload binari.
+ Quanto segue si riferisce al `device_type` nella clausola WHERE.
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ Il seguente elemento non è supportato.
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
Le seguenti operazioni della regola non supportano i payload binari, quindi è necessario decodificarli.
+ Alcune operazioni delle regole non supportano l'input del payload binario, come ad esempio una [operazione Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule), pertanto è necessario decodificare i payload binari. L'operazione della regola Lambda può ricevere dati binari se è codificata in base64 e in un payload JSON. Puoi farlo modificando la regola esistente con la seguente.
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ L'istruzione SQL non supporta la stringa come input. Per convertire un input di stringa in JSON, puoi eseguire il seguente comando.
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## Decodifica dei payload del messaggio protbuf
[Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers) è un formato di dati open-source utilizzato per serializzare dati strutturati in una forma binaria, compatta. Viene utilizzato per la trasmissione di dati su reti o l'archiviazione in file. Protobuf consente di inviare dati in pacchetti di piccole dimensioni e a una velocità maggiore rispetto ad altri formati di messaggistica. AWS IoT Core Le regole supportano protobuf fornendo la funzione SQL [decode (value, decodingScheme), che consente di decodificare](iot-sql-functions.md#iot-sql-decode-base64) i payload di messaggi con codifica protobuf in formato JSON e di indirizzarli ai servizi downstream. Questa sezione step-by-step descrive in dettaglio il processo per configurare la AWS IoT Core decodifica protobuf in Rules.
**Topics**
+ [Prerequisiti](#binary-payloads-protobuf-prerequisites)
+ [Creazione di file descrittori](#binary-payloads-protobuf-descriptor-steps)
+ [Caricamento dei file descrittori nel bucket S3](#binary-payloads-protobuf-s3-steps)
+ [Configurazione della decodifica protobuf in Rules](#binary-payloads-protobuf-steps)
+ [Limitazioni](#binary-payloads-protobuf-limitations)
+ [Best practice](#binary-payloads-protobuf-bestpractices)
### Prerequisiti
+ Una conoscenza di base di [Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers)
+ I [file `.proto`](https://developers.google.com/protocol-buffers/docs/proto3) che definiscono i tipi di messaggio e le dipendenze correlate
+ Installazione di [Protobuf Compiler (protoc)](https://github.com/protocolbuffers/protobuf/releases) nel sistema
### Creazione di file descrittori
Se si dispone già di file descrittori, è possibile ignorare questa fase. Un file descrittore (`.desc`) è una versione compilata di un file `.proto`, ovvero un file di testo che definisce le strutture di dati e i tipi di messaggi da utilizzare in una serializzazione protobuf. Per generare un file descrittore, è necessario definire un file `.proto` e utilizzare il compilatore [protoc](https://github.com/protocolbuffers/protobuf/releases) per compilarlo.
1. Crea i file `.proto` che definiscono i tipi di messaggio. Un file `.proto` di esempio può avere l'aspetto seguente:
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
In questo file `.proto` di esempio, si utilizza la sintassi proto3 e si definisce il tipo di messaggio `Person`. La definizione del messaggio `Person` specifica tre campi (name, id ed email). Per ulteriori informazioni sui formati messaggio del file `.proto`, consulta [Guida alle lingue (proto3)](https://developers.google.com/protocol-buffers/docs/proto3).
1. Utilizza il compilatore [protoc](https://github.com/protocolbuffers/protobuf/releases) per compilare i file `.proto` e generare un file descrittore. Di seguito è riportato un comando di esempio per creare un file descrittore (`.desc`):
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
Questo comando di esempio genera un file descrittore`.desc`, che AWS IoT Core Rules può utilizzare per decodificare i payload protobuf conformi alla struttura di dati definita in. `.proto`
+ `--descriptor_set_out`
Specifica il nome del file descrittore (`.desc`) da generare.
+ `--proto_path`
Specifica le posizioni degli eventuali file `.proto` importati a cui fa riferimento il file in fase di compilazione. È possibile specificare il flag più volte se si dispone di più file `.proto` importati con posizioni differenti.
+ `--include_imports`
Specifica che anche gli eventuali file `.proto` importati devono essere compilati e inclusi nel file descrittore `.desc`.
+ `.proto`
Specifica il nome del file `.proto` da compilare.
Per ulteriori informazioni sul riferimento protoc, consulta [Documentazione di riferimento delle API](https://developers.google.com/protocol-buffers/docs/reference/overview).
### Caricamento dei file descrittori nel bucket S3
Dopo aver creato i file descrittori`.desc`, carica i file descrittori in un bucket Amazon S3, utilizzando AWS l'API AWS , l'SDK o il. `.desc` Console di gestione AWS
**Considerazioni importanti**
+ Assicurati di caricare i file descrittori in un bucket Amazon S3 Regione AWS nello stesso spazio in cui intendi Account AWS configurare le regole.
+ Assicurati di concedere l' AWS IoT Core accesso per leggere i file da S3. `FileDescriptorSet` Se la crittografia lato server (SSE) è disattivata nel bucket S3 o se il bucket S3 è crittografato tramite chiavi gestite da Amazon S3 (SSE-S3), non sono necessarie configurazioni delle policy aggiuntive. Ciò può essere ottenuto con l'esempio della policy di bucket di esempio:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ Se il tuo bucket S3 è crittografato utilizzando una AWS Key Management Service chiave (SSE-KMS), assicurati di concedere l' AWS IoT Core autorizzazione all'uso della chiave quando accedi al bucket S3. Per farlo, aggiungi questa istruzione alla policy della chiave:
```
{
"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"
}
```
### Configurazione della decodifica protobuf in Rules
Dopo aver caricato i file descrittori nel bucket Amazon S3, configura una [Regola](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html) in grado di decodificare il formato di payload dei messaggi protobuf utilizzando la funzione SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64). Una firma della funzione dettagliata e un esempio sono disponibili nella funzione SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) della *Documentazione di riferimento SQL AWS IoT *.
Di seguito è riportata un'espressione SQL di esempio che utilizza la funzione [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64):
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
In questa espressione di esempio:
+ La funzione SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) viene utilizzata per decodificare il payload del messaggio binario a cui fa riferimento `*`. Può essere un payload con codifica protobuf binario o una stringa JSON che rappresenta un payload protobuf con codifica base64.
+ Il payload del messaggio fornito è codificato utilizzando il tipo di messaggio `Person` definito in `PROTO_FILENAME.proto`.
+ Il bucket Amazon S3 denominato `BUCKET NAME` contiene il `FILENAME.desc` generato da `PROTO_FILENAME.proto`.
Dopo aver completato la configurazione, pubblica un messaggio AWS IoT Core sull'argomento a cui è sottoscritta la regola.
### Limitazioni
AWS IoT Core Le regole supportano protobuf con le seguenti limitazioni:
+ La decodifica dei payload dei messaggi protobuf all'interno di [modelli di sostituzione](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) non è supportata.
+ Quando si decodificano i payload dei messaggi protobuf, è possibile utilizzare la [funzione SQL di decodifica](iot-sql-functions.md#iot-sql-decode-base64) all'interno di una singola espressione SQL fino a due volte.
+ La dimensione massima del payload in entrata è 128 KiB (1 KiB = 1024 byte), la dimensione massima del payload in uscita è 128 KiB e la dimensione massima per un oggetto `FileDescriptorSet` archiviato in un bucket Amazon S3 è 32 KiB.
+ I bucket Amazon S3 crittografati con crittografia SSE-C non sono supportati.
### Best practice
Di seguito sono indicate alcune best practice e suggerimenti per la risoluzione dei problemi.
+ Eseguire il backup dei file proto nel bucket Amazon S3.
È buona prassi eseguire il backup dei file proto in caso si verifichino problemi. Ad esempio, se si modificano erroneamente i file proto senza backup durante l'esecuzione di protoc, si possono verificare problemi nello stack di produzione. Esistono diversi modi per eseguire il backup dei file in un bucket Amazon S3. Ad esempio, è possibile [utilizzare il controllo delle versioni nei bucket S3](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html). Per ulteriori informazioni su come eseguire il backup dei file nei bucket Amazon S3, consulta la *[Guida per gli sviluppatori di Amazon S3](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*.
+ Configurare la AWS IoT registrazione per visualizzare le voci di registro.
È buona norma configurare la AWS IoT registrazione in modo da poter controllare AWS IoT i registri del proprio account. CloudWatch Quando una query SQL di una regola richiama una funzione esterna, AWS IoT Core Rules genera una voce di registro con un `eventType` of`FunctionExecution`, che contiene il campo del motivo che consente di risolvere gli errori. I possibili errori includono un oggetto Amazon S3 non trovato o un descrittore del file protobuf non valido. Per ulteriori informazioni su come configurare la registrazione AWS IoT e visualizzare le voci di log, consulta [Configurazione della registrazione AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html) e [Voci di registro del motore delle regole](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec).
+ Aggiornare `FileDescriptorSet` utilizzando una nuova chiave oggetto e aggiornare la chiave oggetto nella regola.
È possibile aggiornare `FileDescriptorSet` caricando un file descrittore aggiornato nel bucket Amazon S3. Gli aggiornamenti a `FileDescriptorSet` possono richiedere fino a 15 minuti per essere visualizzati. Per evitare questo ritardo, è buona prassi caricare il `FileDescriptorSet` aggiornato utilizzando una nuova chiave oggetto e aggiornare la chiave oggetto nella regola.
# Versioni SQL
Il motore AWS IoT delle regole utilizza una sintassi simile a SQL per selezionare i dati dai messaggi MQTT. Le istruzioni SQL vengono interpretate in base a una versione di SQL specificata con la proprietà `awsIotSqlVersion` in un documento JSON che descrive la regola. Per ulteriori informazioni sulla struttura dei documenti di regole JSON, consulta la pagina relativa alla [creazione di una regola](iot-create-rule.md). La `awsIotSqlVersion` proprietà consente di specificare quale versione del motore di regole AWS IoT SQL si desidera utilizzare. Quando viene distribuita una nuova versione, puoi continuare a usare una versione precedente o modificare la regola per usare la nuova versione. Le regole correnti continuano a usare la versione con cui sono state create.
L'esempio JSON seguente ti illustra come specificare la versione SQL usando la proprietà `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 attualmente supporta le seguenti versioni SQL:
+ `2016-03-23` - versione SQL creata il 23/03/2016 (consigliata).
+ `2015-10-08` – versione SQL originale creata il 08/10/2015.
+ `beta` – la più recente versione beta di SQL. Questa versione potrebbe comportare modifiche che interrompono il funzionamento delle regole.
## Novità della versione del motore di regole SQL 2016-03-23
+ Correzioni per la selezione di oggetti JSON nidificati.
+ Correzioni per le query su matrici.
+ Supporto per query tra oggetti. Per ulteriori informazioni, consulta [Query di oggetti nidificati](iot-sql-nested-queries.md).
+ Supporto per l'output di una matrice come oggetto di primo livello.
+ Aggiunta della funzione `encode(value, encodingScheme)`, che può essere applicata ai dati in formato JSON e non JSON. Per ulteriori informazioni, consulta la [funzione di codifica](iot-sql-functions.md#iot-sql-encode-payload).
### Output di un oggetto `Array` come oggetto di primo livello
Questa caratteristica permette a una regola di restituire una matrice come oggetto di primo livello. Ad esempio, partendo dal messaggio MQTT seguente:
```
{
"a": {"b":"c"},
"arr":[1,2,3,4]
}
```
E dalla regola seguente:
```
SELECT VALUE arr FROM 'topic'
```
La regola genera l'output seguente.
```
[1,2,3,4]
```