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à. # 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"]"