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à.
# Regole per AWS IoT
Le regole offrono ai tuoi dispositivi la possibilità di interagire con Servizi AWS. Le regole vengono analizzate e vengono eseguite operazioni in base al flusso di argomenti MQTT. È possibile usare le regole a supporto di attività come le seguenti:
+ Aumentare o filtrare i dati ricevuti da un dispositivo.
+ Scrivere i dati ricevuti da un dispositivo in un database Amazon DynamoDB.
+ Salvare un file in Amazon S3.
+ Inviare una notifica push a tutti gli utenti che utilizzano Amazon SNS.
+ Pubblicare i dati in una coda Amazon SQS.
+ Richiamare una funzione Lambda per estrarre i dati.
+ Elaborare i messaggi da un numero elevato di dispositivi con Amazon Kinesis.
+ Invia dati ad Amazon OpenSearch Service.
+ Acquisisci una CloudWatch metrica.
+ Cambia una CloudWatch sveglia.
+ Invia i dati da un messaggio MQTT ad Amazon SageMaker AI per fare previsioni basate su un modello di machine learning (ML).
+ Inviare un messaggio a un flusso di input Salesforce IoT.
+ Avviare il processo di una macchina a stati Step Functions.
+ Invia i dati del messaggio a un AWS IoT Events input.
+ Inviare i dati del messaggio a una proprietà di asset in AWS IoT SiteWise.
+ Inviare i dati dei messaggi a un'applicazione Web o a un servizio.
Le tue regole possono utilizzare messaggi MQTT che passano attraverso il publish/subscribe protocollo supportato da. [Protocolli di dispositivo di comunicazione](protocols.md) [È inoltre possibile utilizzare la funzione [Basic Ingest](iot-basic-ingest.md) per inviare in modo sicuro i dati del dispositivo a Servizi AWS quelli elencati in precedenza, senza incorrere in costi di messaggistica.](https://aws.amazon.com/iot-core/pricing/) La funzione [Basic Ingest](iot-basic-ingest.md) ottimizza il flusso di dati rimuovendo il broker di publish/subscribe messaggi dal percorso di ingestione. Ciò la rende conveniente pur mantenendo le funzionalità di sicurezza ed elaborazione dei dati di. AWS IoT
Prima di AWS IoT poter eseguire queste azioni, devi concedergli l'autorizzazione ad accedere alle tue AWS risorse per tuo conto. Quando le azioni vengono eseguite, ti vengono addebitati i costi standard per le azioni Servizi AWS che utilizzi.
**Topics**
+ [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md)
+ [Passaggio delle autorizzazioni ai ruoli](pass-role.md)
+ [Creare una AWS IoT regola](iot-create-rule.md)
+ [Gestione di una regola AWS IoT](iot-managae-rule.md)
+ [AWS IoT azioni relative alle regole](iot-rule-actions.md)
+ [Risoluzione dei problemi relativi a una regola](#iot-troubleshoot-rule)
+ [Accesso alle risorse di più account utilizzando le regole AWS IoT](accessing-cross-account-resources-using-rules.md)
+ [Gestione degli errori (operazione in caso di errore)](rule-error-handling.md)
+ [Riduzione dei costi di messaggistica con Basic Ingest](iot-basic-ingest.md)
+ [AWS IoT Riferimento SQL](iot-sql-reference.md)
# Concedere a qualsiasi AWS IoT regola l'accesso richiesto
Usa i ruoli IAM per controllare le AWS risorse a cui ogni regola ha accesso. Prima di creare una regola, devi creare un ruolo IAM con una policy che consenta l'accesso alle AWS risorse richieste. AWS IoT assume questo ruolo quando implementa una regola.
**Completa i seguenti passaggi per creare il ruolo e la AWS IoT policy IAM che garantiscano a una AWS IoT regola l'accesso richiesto (AWS CLI).**
1. Salva il seguente documento sulla politica di fiducia, che concede AWS IoT l'autorizzazione ad assumere il ruolo, in un file denominato`iot-role-trust.json`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:iot:us-east-1:123456789012:rule/rulename"
}
}
}
]
}
```
Utilizzare il comando [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) per creare un ruolo IAM specificando il file `iot-role-trust.json`:
```
aws iam create-role --role-name my-iot-role --assume-role-policy-document file://iot-role-trust.json
```
L'output di questo comando è simile al seguente:
```
{
"Role": {
"AssumeRolePolicyDocument": "url-encoded-json",
"RoleId": "AKIAIOSFODNN7EXAMPLE",
"CreateDate": "2015-09-30T18:43:32.821Z",
"RoleName": "my-iot-role",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
```
1. Salvare il seguente JSON in un file denominato `my-iot-policy.json`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "*"
}
]
}
```
Questo JSON è un esempio di documento di policy che concede l'accesso AWS IoT dell'amministratore a DynamoDB.
Utilizzate il comando [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) per concedere AWS IoT l'accesso alle vostre AWS risorse dopo aver assunto il ruolo, inserendo nel file: `my-iot-policy.json`
```
aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy.json
```
Per ulteriori informazioni su come concedere l'accesso a Servizi AWS nelle politiche per AWS IoT, consulta. [Creare una AWS IoT regola](iot-create-rule.md)
L'output del comando [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) contiene l'ARN della policy. Collegamento di una policy al ruolo.
```
{
"Policy": {
"PolicyName": "my-iot-policy",
"CreateDate": "2015-09-30T19:31:18.620Z",
"AttachmentCount": 0,
"IsAttachable": true,
"PolicyId": "ZXR6A36LTYANPAI7NJ5UV",
"DefaultVersionId": "v1",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:policy/my-iot-policy",
"UpdateDate": "2015-09-30T19:31:18.620Z"
}
}
```
1. Usa il [attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html)comando per associare la tua politica al tuo ruolo:
```
aws iam attach-role-policy --role-name my-iot-role --policy-arn "arn:aws:iam::123456789012:policy/my-iot-policy"
```
## Revoca l'accesso al motore delle regole
Per revocare immediatamente l'accesso al Rule Engine, procedi come segue
1. [Rimuovi iot.amazonaws.com dalla politica di fiducia](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)
1. [Segui i passaggi per revocare le sessioni di ruolo iot](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html)
# Passaggio delle autorizzazioni ai ruoli
Parte di una definizione di regola è costituita da un ruolo IAM che concede l'autorizzazione di accesso alle risorse specificate nell'operazione della regola. Il motore di regole presuppone l'uso del ruolo quando l'operazione della regola viene richiamata. Il ruolo deve essere definito nello stesso modo della Account AWS regola.
Quando crei o sostituisci una regola, in realtà passi un ruolo al motore di regole. È necessaria l’autorizzazione `iam:PassRole` per eseguire questa operazione. Per verificare che disponi di questa autorizzazione, crea una policy che conceda l'autorizzazione `iam:PassRole` e collegala al tuo utente IAM. La policy seguente mostra come concedere l'autorizzazione `iam:PassRole` per un ruolo.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::123456789012:role/myRole"
]
}
]
}
```
In questa policy di esempio viene concessa l'autorizzazione `iam:PassRole` al ruolo `myRole`. Il ruolo viene specificato usando l'ARN del ruolo. Collega questa policy all'utente IAM o al ruolo a cui l'utente appartiene. Per ulteriori informazioni, consulta la sezione relativa all'[utilizzo di policy gestite](https://docs.aws.amazon.com/service-authorization/latest/reference/access_policies_managed-using.html).
**Nota**
Le funzioni Lambda usano una policy basata sulle risorse collegata direttamente alla funzione Lambda stessa. Quando crei una regola che richiama una funzione Lambda, non trasferisci un ruolo; pertanto, l'utente che crea la regola non ha bisogno dell'autorizzazione `iam:PassRole`. Per ulteriori informazioni sull'autorizzazione per la funzione Lambda, consulta la pagina relativa alla [Concessione di autorizzazioni usando una policy per le risorse](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy).
# Creare una AWS IoT regola
Puoi creare AWS IoT regole per indirizzare i dati dagli oggetti connessi all'interazione con altri AWS servizi. Una AWS IoT regola è composta dai seguenti componenti:
**Componenti di una regola**
| Componente | Description | Obbligatorio o facoltativo |
| --- | --- | --- |
| Nome regola | Nome della regola . Tieni presente che non consigliamo l'uso di informazioni di identificazione personale nei nomi delle regole. | Obbligatorio. |
| Descrizione della regola | Una descrizione testuale della regola. Tieni presente che non consigliamo l'uso di informazioni di identificazione personale nelle descrizioni delle regole. | Opzionale. |
| Istruzione SQL | Sintassi SQL semplificata per filtrare i messaggi ricevuti in un argomento MQTT ed effettuare il push dei dati in un’altra posizione. Per ulteriori informazioni, consulta [AWS IoT Riferimento SQL](iot-sql-reference.md). | Obbligatorio. |
| Versione SQL | Versione del motore di regole SQL da usare durante la valutazione della regola. Sebbene questa proprietà sia facoltativa, si consiglia vivamente di specificare la versione SQL. La AWS IoT Core console imposta questa proprietà come `2016-03-23` predefinita. Se questa proprietà non è impostata, ad esempio in un AWS CLI comando o in un CloudFormation modello, `2015-10-08` viene utilizzata. Per ulteriori informazioni, consulta [Versioni SQL](iot-rule-sql-version.md). | Obbligatorio. |
| Una o più azioni | Le azioni AWS IoT eseguite quando si applica la regola. Ad esempio, è possibile inserire i dati in una tabella Dynamo DB, scrivere i dati in un bucket Amazon S3, eseguire la pubblicazione in un argomento Amazon SNS o invocare una funzione Lambda. | Obbligatorio. |
| Un'operazione in caso di errore | L'azione viene AWS IoT eseguita quando non è in grado di eseguire l'azione di una regola. | Opzionale. |
Prima di creare una AWS IoT regola, devi creare un ruolo IAM con una policy che consenta l'accesso alle AWS risorse richieste. AWS IoT assume questo ruolo quando implementa una regola. Per ulteriori informazioni, vedere [Concessione a una AWS IoT regola dell'accesso richiesto](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html) e [Passaggio delle autorizzazioni di ruolo](https://docs.aws.amazon.com//iot/latest/developerguide/pass-role.html).
Quando crei una regola, fai attenzione alla quantità di dati che pubblichi negli argomenti. Se crei regole che includono uno schema di argomento con caratteri jolly, potrebbero corrispondere a una percentuale elevata dei tuoi messaggi. In tal caso, potrebbe essere necessario aumentare la capacità delle risorse AWS utilizzate dalle operazioni di destinazione. Consigliamo di evitare schemi di argomento con caratteri jolly nelle regole di ripubblicazione per evitare elaborazioni duplicate e ridurre i costi.
**Nota**
La creazione e l’aggiornamento di regole sono operazioni a livello di amministratore. Qualsiasi utente che abbia l'autorizzazione per creare o aggiornare regole potrà accedere ai dati elaborati dalle regole.
## Crea una regola (Console)
**Per creare una regola (Console di gestione AWS)**
Usa il [Console di gestione AWS](https://console.aws.amazon.com//iot/home#/home)comando per creare una regola:
1. Apri la [AWS IoT console](https://console.aws.amazon.com//iot/home#/home).
1. Nella barra di navigazione a sinistra, scegli **Instradamento dei messaggi** dalla sezione **Gestisci**. Quindi scegli **Regole**.
1. Nella pagina **Regole**, scegli **Crea regola**.
1. Nella pagina **Specificare le proprietà della regola**, inserisci un nome per la regola. **La descrizione e i **tag** della regola** sono facoltativi. Scegli **Next (Successivo)**.
1. Nella pagina **Configura l'istruzione SQL**, scegli una versione SQL e inserisci un'istruzione SQL. Un esempio di istruzione SQL può essere`SELECT temperature FROM 'iot/topic' WHERE temperature > 50`. Per ulteriori informazioni, vedere [Versioni SQL](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-sql-version.html) e [riferimenti AWS IoT SQL](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-reference.html).
1. Nella pagina **Allega azioni alle regole**, aggiungi le azioni delle regole per indirizzare i dati ad altri AWS servizi.
1. In **Azioni relative alle** regole, seleziona un'azione della regola dall'elenco a discesa. Ad esempio, puoi scegliere **Kinesis** Stream. Per ulteriori informazioni sulle azioni delle regole, consulta le [azioni delle AWS IoT regole](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-actions.html).
1. A seconda dell'azione della regola scelta, inserisci i dettagli di configurazione correlati. Ad esempio, se scegli **Kinesis Stream**, dovrai scegliere o creare una risorsa di flusso di dati e, facoltativamente, inserire dettagli di configurazione come la **chiave di partizione**, che viene utilizzata per raggruppare i dati per shard in uno stream.
1. Nel **ruolo IAM**, scegli o crea un ruolo per concedere AWS IoT l'accesso al tuo endpoint. Tieni presente che AWS IoT creerà automaticamente una policy con un prefisso corrispondente al ruolo IAM selezionato. `aws-iot-rule` Puoi scegliere **Visualizza per visualizzare** il tuo ruolo IAM e la policy dalla console IAM. **L'azione di errore** è facoltativa. Ulteriori informazioni sono disponibili in [Gestione degli errori (azione di errore)](https://docs.aws.amazon.com//iot/latest/developerguide/rule-error-handling.html). Per ulteriori informazioni sulla creazione di un ruolo IAM per la regola, consulta [Concedere a una regola l'accesso richiesto](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html). Scegli **Next (Successivo)**.
1. Nella pagina **Rivedi e crea**, esamina tutta la configurazione e apporta le modifiche necessarie. Scegli **Create** (Crea).
Dopo aver creato correttamente una regola, la regola verrà visualizzata nella pagina **Regole**. È possibile selezionare una regola per aprire la pagina **Dettagli** in cui è possibile visualizzare una regola, modificare una regola, disattivarla ed eliminarla.
## Creare una regola (CLI)
**Per creare una regola (AWS CLI)**
Usa il [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)comando per creare una regola:
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
Di seguito è riportato un esempio di file di payload con una regola che inserisce tutti i messaggi inviati all'argomento `iot/test` nella tabella Dynamo DB specificata. L'istruzione SQL filtra i messaggi e il ruolo ARN concede il AWS IoT permesso di scrivere nella tabella DynamoDB.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my-dynamodb-table",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"hashKeyField": "topic",
"hashKeyValue": "${topic(2)}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}"
}
}
]
}
```
Di seguito è riportato un esempio di file di payload con una regola che inserisce tutti i messaggi inviati all'argomento `iot/test` nel bucket S3 specificato. L'istruzione SQL filtra i messaggi e il ruolo ARN concede l' AWS IoT autorizzazione alla scrittura nel bucket Amazon S3.
```
{
"awsIotSqlVersion": "2016-03-23",
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName": "amzn-s3-demo-bucket",
"key": "myS3Key"
}
}
]
}
```
Di seguito è riportato un esempio di file di payload con una regola che invia i dati ad Amazon OpenSearch Service:
```
{
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"OpenSearch": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es",
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}"
}
}
]
}
```
Di seguito è riportato un esempio di file di payload con una regola che richiama una funzione Lambda:
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"
}
}
]
}
```
Di seguito è riportato un esempio di file di payload con una regola che esegue la pubblicazione in un argomento Amazon SNS:
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-west-2:123456789012:my-sns-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
Di seguito è riportato un esempio di file di payload con una regola che esegue la ripubblicazione in un argomento MQTT diverso:
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
Di seguito è riportato un esempio di file di payload con una regola che invia i dati a un flusso Amazon Data Firehose:
```
{
"sql": "SELECT * FROM 'my-topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"deliveryStreamName": "my-stream-name"
}
}
]
}
```
Di seguito è riportato un esempio di file di payload con una regola che utilizza la `machinelearning_predict` funzione Amazon SageMaker AI per ripubblicare su un argomento se i dati nel payload MQTT sono classificati come 1.
```
{
"sql": "SELECT * FROM 'iot/test' where machinelearning_predict('my-model', 'arn:aws:iam::123456789012:role/my-iot-aml-role', *).predictedLabel=1",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role",
"topic": "my-mqtt-topic"
}
}
]
}
```
Di seguito è riportato un esempio di file di payload con una regola che pubblica messaggi in un flusso di input Salesforce IoT Cloud.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"salesforce": {
"token": "ABCDEFGHI123456789abcdefghi123456789",
"url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event"
}
}
]
}
```
Di seguito è riportato un esempio di file di payload con una regola che avvia un'esecuzione di una macchina a stati Step Functions.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myCoolStateMachine",
"executionNamePrefix": "coolRunning",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
# Gestione di una regola AWS IoT
È possibile utilizzare le seguenti azioni per gestire le AWS IoT regole.
**Topics**
+ [Taggare una regola](#iot-create-rule-tagging)
+ [Visualizzazione di una regola](#iot-view-rules)
+ [Eliminazione di una regola](#iot-delete-rule)
## Taggare una regola
Per aggiungere un altro livello di specificità alle regole nuove o esistenti, puoi applicare i tag. L'etichettatura sfrutta le coppie chiave-valore nelle regole per offrirti un maggiore controllo su come e dove le regole vengono applicate alle tue risorse e ai tuoi servizi. AWS IoT Ad esempio, puoi limitare l'ambito della regola in modo da applicarla solo nell'ambiente beta per i test precedenti al rilascio (`Key=environment, Value=beta`) o acquisendo tutti i messaggi inviati all'argomento `iot/test` da un endpoint specifico e archiviandoli in un bucket Amazon S3.
### Esempio di policy IAM
Per un esempio che mostra come concedere le autorizzazioni per l'assegnazione di tag per una regola, prendi in considerazione un utente che esegue il comando seguente per creare una regola e aggiungervi un tag che si applica solo in un ambiente beta.
Nell'esempio, sostituisci:
+ *MyTopicRuleName*con il nome della regola.
+ *myrule.json*con il nome del documento di policy.
```
aws iot create-topic-rule
--rule-name MyTopicRuleName
--topic-rule-payload file://myrule.json
--tags "environment=beta"
```
Per questo esempio, devi utilizzare la seguente policy IAM:
****
```
{
"Version":"2012-10-17",
"Statement":
{
"Action": [ "iot:CreateTopicRule", "iot:TagResource" ],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:rule/MyTopicRuleName"
]
}
}
```
L'esempio precedente mostra una regola appena creata denominata `MyTopicRuleName` che si applica solo all'ambiente beta. `iot:TagResource` nell'istruzione della policy con `MyTopicRuleName` specificatamente richiamato consente di assegnare tag durante la creazione o l'aggiornamento di `MyTopicRuleName`. Il parametro `--tags "environment=beta"` utilizzato durante la creazione della regola limita l'ambito di `MyTopicRuleName` solo all'ambiente beta. Se rimuovi il parametro `--tags "environment=beta"`, `MyTopicRuleName` si applicherà a tutti gli ambienti.
Per ulteriori informazioni relative alla creazione di policy e ruoli IAM specifici per una regola AWS IoT , consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md)
Per informazioni sull'assegnazione di tag alle risorse, consulta [Taggare le tue risorse AWS IoT](tagging-iot.md).
## Visualizzazione di una regola
Usa il [list-topic-rules](https://docs.aws.amazon.com/cli/latest/reference/iot/list-topic-rules.html)comando per elencare le tue regole:
```
aws iot list-topic-rules
```
Usa il [get-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/get-topic-rule.html)comando per ottenere informazioni su una regola:
```
aws iot get-topic-rule --rule-name myrule
```
## Eliminazione di una regola
Quando una regola non è più necessaria, è possibile eliminarla.
**Per eliminare una regola (AWS CLI)**
Usa il [delete-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-topic-rule.html)comando per eliminare una regola:
```
aws iot delete-topic-rule --rule-name myrule
```
# AWS IoT azioni relative alle regole
AWS IoT le azioni delle regole specificano cosa fare quando viene richiamata una regola. Puoi definire azioni per inviare dati a un database Amazon DynamoDB, inviare dati ad Amazon Kinesis Data Streams, AWS Lambda richiamare una funzione e così via. AWS IoT supporta le seguenti azioni Regioni AWS laddove il servizio dell'azione è disponibile.
| Operazione delle regole | Description | Nome nell'API |
| --- | --- | --- |
| [Apache Kafka](apache-kafka-rule-action.md) | Invia un messaggio a un cluster Apache Kafka. | kafka |
| [CloudWatch allarmi](cloudwatch-alarms-rule-action.md) | Modifica lo stato di un CloudWatch allarme Amazon. | cloudwatchAlarm |
| [CloudWatch Registri](cloudwatch-logs-rule-action.md) | Invia un messaggio ad Amazon CloudWatch Logs. | cloudwatchLogs |
| [CloudWatch metriche](cloudwatch-metrics-rule-action.md) | Invia un messaggio a una CloudWatch metrica. | cloudwatchMetric |
| [DynamoDB](dynamodb-rule-action.md) | Invia un messaggio a una tabella Dynamo DB. | dynamoDB |
| [Dynamo DBv2](dynamodb-v2-rule-action.md) | Invia i dati dei messaggi a più colonne in una tabella Dynamo DB. | dynamoDBv2 |
| [Elasticsearch](elasticsearch-rule-action.md) | Invia un messaggio a un OpenSearch endpoint. | OpenSearch |
| [HTTP](https-rule-action.md) | Invia un messaggio a un endpoint HTTPS. | http |
| [AWS IoT Events](iotevents-rule-action.md) | Invia un messaggio a un AWS IoT Events input. | iotEvents |
| [AWS IoT SiteWise](iotsitewise-rule-action.md) | Invia i dati dei messaggi alle proprietà AWS IoT SiteWise delle risorse. | iotSiteWise |
| [Firehose](kinesis-firehose-rule-action.md) | Invia un messaggio a un flusso di distribuzione di Firehose. | firehose |
| [Flussi di dati Kinesis](kinesis-rule-action.md) | Invia un messaggio a un flusso dei dati Kinesis. | kinesis |
| [Lambda](lambda-rule-action.md) | Richiama una funzione Lambda con i dati dei messaggi come input. | lambda |
| [Location (Ubicazione)](location-rule-action.md) | Invia i dati sulla posizione al servizio di posizione Amazon. | location |
| [OpenSearch](opensearch-rule-action.md) | Invia un messaggio a un endpoint OpenSearch di Amazon Service. | OpenSearch |
| [Ripubblica](republish-rule-action.md) | Ripubblica un messaggio in un altro argomento MQTT. | republish |
| [S3](s3-rule-action.md) | Archivia un messaggio in un bucket Amazon Simple Storage Service (Amazon S3). | s3 |
| [IoT di Salesforce](salesforce-iot-rule-action.md) | Invia un messaggio a un flusso di input Salesforce IoT. | salesforce |
| [SNS](sns-rule-action.md) | Pubblica un messaggio come notifica push di Amazon Simple Notification Service (Amazon SNS). | sns |
| [SQS](sqs-rule-action.md) | Pubblica un messaggio in una coda Amazon Simple Queue Service (Amazon SQS). | sqs |
| [Step Functions](stepfunctions-rule-action.md) | Avvia una macchina a AWS Step Functions stati. | stepFunctions |
| [Timestream](timestream-rule-action.md) | Invia un messaggio a una tabella di database Amazon Timestream. | timestream |
**Note**
Definisci la regola nella stessa Regione AWS risorsa di un altro servizio in modo che l'azione della regola possa interagire con quella risorsa.
Il motore AWS IoT delle regole potrebbe effettuare più tentativi di eseguire un'azione se si verificano errori intermittenti. Se tutti i tentativi falliscono, il messaggio viene scartato e l'errore è disponibile nei registri. CloudWatch È possibile specificare un’operazione di errore per ciascuna regola che viene invocata quando si verifica un errore. Per ulteriori informazioni, consulta [Gestione degli errori (operazione in caso di errore)](rule-error-handling.md).
Alcune operazioni delle regole attivano operazioni nei servizi che si integrano con AWS Key Management Service (AWS KMS) per supportare la crittografia dei dati a riposo. Se si utilizza una chiave KMS gestita dal cliente AWS KMS key per crittografare i dati inattivi, il servizio deve disporre dell'autorizzazione a utilizzare la chiave KMS per conto del chiamante. Per informazioni su come gestire le autorizzazioni per la chiave KSM gestita dal cliente, consulta gli argomenti sulla crittografia dei dati nella guida del servizio appropriata. Per ulteriori informazioni sulle chiavi KMS gestite dal cliente, consulta [Concetti di AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) nella *Guida per sviluppatori di AWS Key Management Service *.
È possibile utilizzare qualsiasi [funzione](iot-sql-functions.md) o [modello di sostituzione](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) nell'istruzione SQL di un'azione di errore, incluse le funzioni esterne: [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),,,, e. [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) Se un'azione di errore richiede la chiamata di una funzione esterna, l'invocazione dell'azione di errore può comportare un fatturato aggiuntivo per la funzione esterna.
# Apache Kafka
[L'azione Apache Kafka (Kafka) invia messaggi direttamente ai tuoi cluster Amazon [Managed Streaming for Apache Kafka (Amazon MSK), ai cluster Apache Kafka gestiti](https://docs.aws.amazon.com//msk/latest/developerguide/what-is-msk.html) da provider di terze parti come Confluent Cloud o ai cluster Apache Kafka autogestiti.](https://www.confluent.io/) Con Kafka rule action, puoi indirizzare i tuoi dati IoT ai cluster Kafka. Ciò consente di creare pipeline di dati ad alte prestazioni per vari scopi, come analisi di streaming, integrazione dei dati, visualizzazione e applicazioni aziendali cruciali.
**Nota**
Questo argomento presuppone la familiarità con la piattaforma Apache Kafka e i relativi concetti. Per ulteriori informazioni su Apache Kafka, consulta [Apache Kafka](https://kafka.apache.org/). [MSK](https://docs.aws.amazon.com//msk/latest/developerguide/serverless.html) Serverless non è supportato. I cluster MSK Serverless possono essere eseguiti solo tramite l'autenticazione IAM, che l'azione delle regole di Apache Kafka attualmente non supporta. Per ulteriori informazioni su come configurare AWS IoT Core con Confluent, consulta [Sfruttare Confluent e AWS risolvere le sfide della gestione dei dati e dei dispositivi IoT](https://aws.amazon.com/blogs/apn/leveraging-confluent-and-aws-to-solve-iot-device-and-data-management-challenges/).
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire`ec2:CreateNetworkInterface`,,,`ec2:DescribeNetworkInterfaces`, `ec2:CreateNetworkInterfacePermission` `ec2:DeleteNetworkInterface``ec2:DescribeSubnets`, `ec2:DescribeVpcs` e operazioni. `ec2:DescribeVpcAttribute` `ec2:DescribeSecurityGroups` Questo ruolo crea e gestisce interfacce di rete elastiche per il tuo Amazon Virtual Private Cloud per raggiungere il tuo broker Kafka. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT Core eseguire questa azione basata sulla regola.
Per maggiori informazioni sulle interfacce di rete, consulta [Interfacce di rete elastiche](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) nella *Guida per l'utente di Amazon EC2*.
La policy associata al ruolo che specifichi sarà simile a quella del seguente esempio.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
}
]
}
```
+ Se utilizzi Gestione dei segreti AWS per memorizzare le credenziali necessarie per connetterti al tuo broker Kafka, devi creare un ruolo IAM che AWS IoT Core possa assumersi di eseguire le `secretsmanager:GetSecretValue` operazioni and. `secretsmanager:DescribeSecret`
La policy associata al ruolo che specifichi sarà simile a quella del seguente esempio.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_client_truststore-*",
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_keytab-*"
]
}
]
}
```
+ Puoi eseguire i cluster Apache Kafka all'interno di Amazon Virtual Private Cloud (Amazon VPC). È necessario creare una destinazione Apache Kafka Virtual Private Cloud (VPC) e utilizzare un gateway NAT nelle sottoreti per inoltrare messaggi da un cluster Kafka pubblico. AWS IoT Il motore AWS IoT delle regole crea un'interfaccia di rete in ciascuna delle sottoreti elencate nella destinazione per indirizzare il traffico direttamente al VPC. Quando arrivi a destinazione, il motore AWS IoT delle regole crea automaticamente un'azione della regola VPC. Per ulteriori informazioni sulle operazioni delle regole VPC, consulta [Destinazioni Apache Kafka Virtual Private Cloud (VPC)](kafka-vpc-destination.md).
+ Se si utilizza una chiave gestita dal cliente AWS KMS key (chiave KMS) per crittografare i dati inattivi, il servizio deve disporre dell'autorizzazione a utilizzare la chiave KMS per conto del chiamante. Per ulteriori informazioni, consulta [crittografia di Amazon MSK](https://docs.aws.amazon.com/msk/latest/developerguide/msk-encryption.html) nella *Guida per sviluppatori Amazon Managed Streaming for Apache Kafka*.
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
destinationArn
L'Amazon Resource Name (ARN) della destinazione Apache Kafka Virtual Private Cloud (VPC). Per informazioni sulla creazione di una destinazione, consulta. [Destinazioni Apache Kafka Virtual Private Cloud (VPC)](kafka-vpc-destination.md)
topic
L'argomento Kafka per i messaggi da inviare al broker Kafka.
È possibile sostituire questo campo utilizzando un modello di sostituzione. Per ulteriori informazioni, consulta [Modelli di sostituzione](iot-substitution-templates.md).
chiave (opzionale)
La chiave del messaggio Kafka.
È possibile sostituire questo campo utilizzando un modello di sostituzione. Per ulteriori informazioni, consulta [Modelli di sostituzione](iot-substitution-templates.md).
intestazioni (opzionali)
L'elenco delle intestazioni specificate. Ogni intestazione è una coppia chiave-valore che puoi specificare quando crei un'operazione Kafka. Puoi utilizzare queste intestazioni per instradare i dati dai client IoT ai cluster Kafka a valle senza modificare il payload dei messaggi.
È possibile sostituire questo campo utilizzando un modello di sostituzione. Per capire come passare la funzione di una regola in linea come modello sostitutivo nell'intestazione dell'operazione Kafka, consulta [Esempi](#apache-kafka-rule-action-examples). Per ulteriori informazioni, consulta [Modelli di sostituzione](iot-substitution-templates.md).
Le intestazioni in formato binario non sono supportate.
partizione (opzionale)
La partizione del messaggio Kafka.
È possibile sostituire questo campo utilizzando un modello di sostituzione. Per ulteriori informazioni, consulta [Modelli di sostituzione](iot-substitution-templates.md).
clientProperties
Un oggetto che definisce le proprietà del client del produttore Apache Kafka.
conferme (facoltativo)
Il numero di conferme che, secondo il produttore, il server deve aver ricevuto, prima di considerare una richiesta come completa.
Se specifichi 0 come valore, il produttore non attenderà alcuna conferma da parte del server. Se il server non riceve il messaggio, il produttore non tenterà di inviare il messaggio un'altra volta.
Valori validi: `-1`, `0`, `1`, `all`. Il valore predefinito è `1`.
bootstrap.servers
Un elenco di coppie host e porta (ad esempio `host1:port1`, `host2:port2`) utilizzato per stabilire la connessione iniziale al cluster Kafka.
compression.type (opzionale)
Il tipo di compressione per tutti i dati generati dal produttore.
Valori validi: `none`, `gzip`, `snappy`, `lz4`, `zstd`. Il valore predefinito è `none`.
security.protocol
Il protocollo di sicurezza usato per collegarsi al broker Kafka.
Valori validi: `SSL`, `SASL_SSL`. Il valore predefinito è `SSL`.
key.serializer
Specifica come trasformare gli oggetti chiave che fornisci con il `ProducerRecord` in byte.
Valore valido: `StringSerializer`.
value.serializer
Specifica come trasformare gli oggetti valore che fornisci con il `ProducerRecord` in byte.
Valore valido: `ByteBufferSerializer`.
ssl.truststore
Il file truststore in formato base64 o la posizione del file truststore in [Gestione dei segreti AWS](https://docs.aws.amazon.com/secretsmanager/latest/userguide/). Questo valore non è richiesto se il tuo truststore è considerato attendibile dalle autorità di certificazione Amazon (CA).
Questo campo supporta i modelli di sostituzione. Se utilizzi Secrets Manager per archiviare le credenziali necessarie per connetterti al broker Kafka, puoi utilizzare la funzione SQL `get_secret` per recuperare il valore di questo campo. Per ulteriori informazioni sui modelli di sostituzione, consulta [Modelli di sostituzione](iot-substitution-templates.md). Per ulteriori informazioni sulla funzione SQL `get_secret`, consulta [get\$1secret (secretId, secretType, chiave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Se il truststore ha la forma di un file, usa il parametro `SecretBinary`. Se il truststore è sotto forma di una stringa, usa il parametro `SecretString`.
La dimensione massima di questo valore è di 65 KB.
ssl.truststore.password
La password del truststore. Questo valore è richiesto solo se è stata creata una password per il truststore.
ssl.keystore
Il file keystore. Questo valore è obbligatorio quando si specifica `SSL` come valore per `security.protocol`.
Questo campo supporta i modelli di sostituzione. Utilizza Secrets Manager per archiviare le credenziali necessarie per connetterti al broker Kafka. Utilizza la funzione SQL `get_secret` per recuperare il valore di questo campo. Per ulteriori informazioni sui modelli di sostituzione, consulta [Modelli di sostituzione](iot-substitution-templates.md). Per ulteriori informazioni sulla funzione SQL `get_secret`, consulta [get\$1secret (secretId, secretType, chiave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilizzo del parametro `SecretBinary`.
ssl.keystore.password
La password dell'archivio per il file keystore. Questo valore è obbligatorio se viene specificato un valore per `ssl.keystore`.
Il valore di questo campo può essere un testo semplice. Questo campo supporta anche i modelli di sostituzione. Utilizza Secrets Manager per archiviare le credenziali necessarie per connetterti al broker Kafka. Utilizza la funzione SQL `get_secret` per recuperare il valore di questo campo. Per ulteriori informazioni sui modelli di sostituzione, consulta [Modelli di sostituzione](iot-substitution-templates.md). Per ulteriori informazioni sulla funzione SQL `get_secret`, consulta [get\$1secret (secretId, secretType, chiave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilizzo del parametro `SecretString`.
ssl.key.password
La password della chiave privata nel file keystore.
Questo campo supporta i modelli di sostituzione. Utilizza Secrets Manager per archiviare le credenziali necessarie per connetterti al broker Kafka. Utilizza la funzione SQL `get_secret` per recuperare il valore di questo campo. Per ulteriori informazioni sui modelli di sostituzione, consulta [Modelli di sostituzione](iot-substitution-templates.md). Per ulteriori informazioni sulla funzione SQL `get_secret`, consulta [get\$1secret (secretId, secretType, chiave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilizzo del parametro `SecretString`.
sasl.mechanism
Il meccanismo di sicurezza utilizzato per connettersi al broker Kafka. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol`.
Valori validi: `PLAIN`, `SCRAM-SHA-512`, `GSSAPI`.
`SCRAM-SHA-512`è l'unico meccanismo di sicurezza supportato nelle regioni cn-north-1, cn-northwest-1, -1 e -1. us-gov-east us-gov-west
sasl.plain.username
Il nome utente utilizzato per recuperare la stringa segreta da Secrets Manager. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol` e `PLAIN` per `sasl.mechanism`.
sasl.plain.password
La password utilizzata per recuperare la stringa segreta da Secrets Manager. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol` e `PLAIN` per `sasl.mechanism`.
sasl.scram.username
Il nome utente utilizzato per recuperare la stringa segreta da Secrets Manager. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol` e `SCRAM-SHA-512` per `sasl.mechanism`.
sasl.scram.password
La password utilizzata per recuperare la stringa segreta da Secrets Manager. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol` e `SCRAM-SHA-512` per `sasl.mechanism`.
sasl.kerberos.keytab
Il file keytab per l'autenticazione di Kerberos in Secrets Manager. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol` e `GSSAPI` per `sasl.mechanism`.
Questo campo supporta i modelli di sostituzione. Utilizza Secrets Manager per archiviare le credenziali necessarie per connetterti al broker Kafka. Utilizza la funzione SQL `get_secret` per recuperare il valore di questo campo. Per ulteriori informazioni sui modelli di sostituzione, consulta [Modelli di sostituzione](iot-substitution-templates.md). Per ulteriori informazioni sulla funzione SQL `get_secret`, consulta [get\$1secret (secretId, secretType, chiave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilizzo del parametro `SecretBinary`.
sasl.kerberos.service.name
Il nome principale Kerberos con il quale Apache Kafka funziona. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol` e `GSSAPI` per `sasl.mechanism`.
sasl.kerberos.krb5.kdc
Il nome host del centro di distribuzione delle chiavi (KDC) a cui si connette il client produttore Apache Kafka. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol` e `GSSAPI` per `sasl.mechanism`.
sasl.kerberos.krb5.realm
Il dominio a cui si connette il client del produttore Apache Kafka. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol` e `GSSAPI` per `sasl.mechanism`.
sasl.kerberos.principal
L'identità Kerberos univoca a cui Kerberos può assegnare ticket per accedere ai servizi compatibili con Kerberos. Questo valore è obbligatorio quando si specifica `SASL_SSL` per `security.protocol` e `GSSAPI` per `sasl.mechanism`.
## Esempi
Il seguente esempio JSON definisce un'azione di Apache Kafka in una regola. AWS IoT L'esempio seguente passa la funzione in linea [sourceIp()](iot-sql-functions.md#iot-function-sourceip) come [modello di sostituzione](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) nell'intestazione dell'operazione Kafka.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kafka": {
"destinationArn": "arn:aws:iot:region:123456789012:ruledestination/vpc/VPCDestinationARN",
"topic": "TopicName",
"clientProperties": {
"bootstrap.servers": "kafka.com:9092",
"security.protocol": "SASL_SSL",
"ssl.truststore": "${get_secret('kafka_client_truststore', 'SecretBinary','arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"ssl.truststore.password": "kafka password",
"sasl.mechanism": "GSSAPI",
"sasl.kerberos.service.name": "kafka",
"sasl.kerberos.krb5.kdc": "kerberosdns.com",
"sasl.kerberos.keytab": "${get_secret('kafka_keytab','SecretBinary', 'arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"sasl.kerberos.krb5.realm": "KERBEROSREALM",
"sasl.kerberos.principal": "kafka-keytab/kafka-keytab.com"
},
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
},
{
"key": "source_ip",
"value": "${sourceIp()}"
}
]
}
}
]
}
}
```
**Note importanti sulla configurazione di Kerberos**
+ Il centro di distribuzione delle chiavi (KDC) deve essere risolvibile tramite Domain Name System (DNS) privato all'interno del VPC di destinazione. Un possibile approccio è quello di aggiungere la voce DNS del KDC a una zona ospitata privata. Per ulteriori informazioni su questo approccio, consulta [Utilizzo delle zone ospitate private](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html).
+ Ogni VPC deve avere la risoluzione DNS abilitata. Per ulteriori informazioni, consulta [Utilizzo del DNS con il tuo VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html).
+ I gruppi di sicurezza dell'interfaccia di rete e i gruppi di sicurezza a livello di istanza nella destinazione VPC devono consentire il traffico dall'interno del VPC sulle seguenti porte.
+ Traffico TCP sulla porta listener del broker bootstrap (spesso 9092, ma deve essere compreso nell'intervallo 9000-9100)
+ Traffico TCP e UDP sulla porta 88 per il KDC
+ `SCRAM-SHA-512`è l'unico meccanismo di sicurezza supportato nelle regioni cn-north-1, cn-northwest-1, -1 e -1. us-gov-east us-gov-west
# Destinazioni Apache Kafka Virtual Private Cloud (VPC)
L'operazione della regola di Apache Kafka instrada i dati a un cluster Apache Kafka in un Amazon Virtual Private Cloud (Amazon VPC). La configurazione VPC utilizzata dall'operazione della regola Apache Kafka viene attivata automaticamente quando si specifica la destinazione VPC per l'operazione della regola.
Una destinazione Virtual Private Cloud (VPC) di Apache Kafka contiene un elenco di sottoreti all'interno del VPC. Il motore delle regole crea un'interfaccia di rete elastica in ciascuna sottorete specificata nell'elenco. Per maggiori informazioni sulle interfacce di rete, consulta le [Interfacce di rete elastiche](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) nella Guida per l'utente di Amazon EC2.
## Requisiti e considerazioni
+ Se utilizzi un cluster Apache Kafka autogestito a cui si accede utilizzando un endpoint pubblico su Internet:
+ Crea un gateway NAT per le istanze nelle sottoreti. Il gateway NAT dispone di un indirizzo IP pubblico che può connettersi a Internet e consente al motore delle regole di inoltrare i messaggi al cluster Kafka pubblico.
+ Alloca un indirizzo IP elastico con le interfacce di rete elastiche (ENIs) create dalla destinazione Apache Kafka Virtual Private Cloud (VPC). I gruppi di sicurezza utilizzati devono essere configurati per bloccare il traffico in entrata.
**Nota**
Se la destinazione Apache Kafka Virtual Private Cloud (VPC) è disabilitata e quindi riattivata, è necessario associare nuovamente l'elastico al nuovo. IPs ENIs
+ Se una destinazione Apache Kafka Virtual Private Cloud (VPC) non riceve traffico per 30 giorni consecutivi, verrà disabilitata.
+ Se una delle risorse utilizzate dalla destinazione del Virtual Private Cloud (VPC) di Apache Kafka cambia, la destinazione verrà disabilitata e non potrà essere utilizzata.
+ Alcune modifiche che possono disabilitare una destinazione Virtual Private Cloud (VPC) di Apache Kafka includono:
+ Eliminazione del VPC, delle sottoreti, dei gruppi di sicurezza o del ruolo utilizzato.
+ Modifica del ruolo in modo che non disponga più delle autorizzazioni necessarie.
+ Il raggiungimento di una capacità prossima alla sottorete ci rende incapaci di applicare le patch [FedRAMP](https://aws.amazon.com/compliance/fedramp/).
+ Disattivazione della destinazione.
## Prezzi
Ai fini della determinazione dei prezzi, un'operazione della regola VPC viene misurata in aggiunta all'azione che invia un messaggio a una risorsa quando la risorsa si trova nel VPC. Per informazioni sui prezzi, consulta [Prezzi di AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
## Creazione di destinazioni Virtual Private Cloud (VPC) Apache Kafka
È possibile creare una destinazione Apache Kafka Virtual Private Cloud (VPC) utilizzando l'API o la console. [CreateTopicRuleDestination](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRuleDestination.html) AWS IoT Core
Quando si crea una destinazione, è necessario specificare le seguenti informazioni.
vpcId
L'ID univoco di Amazon VPC.
subnetIds
Un elenco di sottoreti in cui il motore delle regole crea interfacce di rete elastiche. Il motore delle regole alloca una singola interfaccia di rete per ogni sottorete nell'elenco.
SecurityGroups (facoltativa)
Un elenco di gruppi di sicurezza da applicare alle interfacce di rete.
roleArn
L'Amazon Resource Name (ARN) di un ruolo che ha l'autorizzazione a creare interfacce di rete per tuo conto.
A questo ARN dovrebbe essere associata una policy simile a quella del seguente esempio.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeVpcs",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:CreateNetworkInterfacePermission",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/VPCDestinationENI": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface",
"aws:RequestTag/VPCDestinationENI": "true"
}
}
}
]
}
```
### Creazione di una destinazione Virtual Private Cloud (VPC) Apache Kafka utilizzando AWS CLI
L'esempio seguente mostra come creare una destinazione utilizzando. AWS CLI
```
aws --region regions iot create-topic-rule-destination --destination-configuration 'vpcConfiguration={subnetIds=["subnet-123456789101230456"],securityGroups=[],vpcId="vpc-123456789101230456",roleArn="arn:aws:iam::123456789012:role/role-name"}'
```
Dopo aver eseguito questo comando, lo stato della destinazione sarà`IN_PROGRESS`. Dopo alcuni istanti, il suo stato cambierà in `ERROR` (se il comando non ha esito positivo) o `ENABLED`. Quando lo stato di destinazione è `ENABLED`, la destinazione è pronta per l'uso.
È possibile utilizzare il seguente comando per ottenere lo stato della destinazione Apache Kafka Virtual Private Cloud (VPC).
```
aws --region region iot get-topic-rule-destination --arn "VPCDestinationARN"
```
### Creazione di una destinazione Virtual Private Cloud (VPC) Apache Kafka utilizzando la console AWS IoT Core
I passaggi seguenti descrivono come creare una destinazione utilizzando la console. AWS IoT Core
1. Accedere alla AWS IoT Core console. Nel riquadro a sinistra, nella scheda **Act** (Atto), scegli **Destinations** (Destinazioni).
1. Inserisci i valori per i seguenti campi.
+ **ID VPC**
+ **Sottorete IDs**
+ **Gruppo di sicurezza**
1. Seleziona un ruolo con le autorizzazioni necessarie per creare interfacce di rete. La policy di esempio precedente contiene queste autorizzazioni.
Quando lo stato di destinazione di Apache Kafka Virtual Private Cloud (VPC) **è ABILITATO, è** pronto per l'uso.
# CloudWatch allarmi
L'azione CloudWatch alarm (`cloudWatchAlarm`) modifica lo stato di un CloudWatch allarme Amazon. In questa chiamata è possibile specificare il motivo della modifica dello stato e il valore.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'`cloudwatch:SetAlarmState`operazione. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`alarmName`
Il nome CloudWatch dell'allarme.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`stateReason`
Motivo della modifica dell'allarme.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`stateValue`
Valore dello stato dell'allarme. Valori validi: `OK`, `ALARM`, `INSUFFICIENT_DATA`.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleArn`
Il ruolo IAM che consente l'accesso all' CloudWatch allarme. Per ulteriori informazioni, consulta [Requisiti](#cloudwatch-alarms-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione di CloudWatch allarme in una AWS IoT regola.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "IotAlarm",
"stateReason": "Temperature stabilized.",
"stateValue": "OK",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## Consulta anche
+ [Che cos'è Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) nella *Amazon CloudWatch User Guide*
+ [Utilizzo degli CloudWatch allarmi Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) nella Guida per l'* CloudWatch utente di Amazon*
# CloudWatch Registri
L'azione CloudWatch Logs (`cloudwatchLogs`) invia dati ad Amazon CloudWatch Logs. Puoi utilizzare `batchMode` per caricare e indicare data e ora di più record di log del dispositivo in un unico messaggio. Puoi anche specificare il gruppo di log in cui l'azione invia i dati.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere di eseguire le operazioni `logs:CreateLogStream``logs:DescribeLogStreams`, e`logs:PutLogEvents`. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo per consentire l'esecuzione di questa azione relativa AWS IoT alla regola.
+ Se si utilizza una chiave gestita dal cliente AWS KMS key (chiave KMS) per crittografare i dati di registro in CloudWatch Logs, il servizio deve disporre dell'autorizzazione a utilizzare la chiave KMS per conto del chiamante. Per ulteriori informazioni, [consulta Encrypt log data in CloudWatch Logs using AWS KMS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html) nella *Amazon CloudWatch Logs* User Guide.
## Requisiti relativi al formato del messaggio MQTT per `batchMode`
Se utilizzi l'azione della regola CloudWatch Logs con `batchMode` disattivata, non ci sono requisiti di formattazione dei messaggi MQTT. Nota: il valore predefinito del parametro `batchMode` è `false`. Tuttavia, se si utilizza l'azione della regola CloudWatch Logs con `batchMode` attivata (il valore del parametro è`true`), i messaggi MQTT contenenti registri lato dispositivo devono essere formattati in modo da contenere un timestamp e un payload dei messaggi. **Nota:** `timestamp` rappresenta l'ora in cui si è verificato l'evento ed è espressa come numero di millisecondi dopo le ore 00:00:00 UTC del 1° gennaio 1970.
Di seguito è riportato un esempio del formato di pubblicazione:
```
[
{"timestamp": 1673520691093, "message": "Test message 1"},
{"timestamp": 1673520692879, "message": "Test message 2"},
{"timestamp": 1673520693442, "message": "Test message 3"}
]
```
A seconda di come vengono generati i log lato dispositivo, potrebbe essere necessario filtrarli e riformattarli prima che vengano inviati per soddisfare questo requisito. Per ulteriori informazioni, consulta [Payload del messaggio MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/topicdata.html).
Indipendentemente dal parametro, i contenuti devono rispettare i limiti di dimensione dei messaggi. `batchMode` `message` AWS IoT Per ulteriori informazioni, consulta [Endpoint e quote per AWS IoT Core](https://docs.aws.amazon.com/general/latest/gr/iot-core.html).
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`logGroupName`
Il gruppo di CloudWatch log a cui l'azione invia i dati.
Supporta [modelli sostitutivi](iot-substitution-templates.md): API e solo AWS CLI
`roleArn`
Il ruolo IAM che consente l'accesso al gruppo di CloudWatch log. Per ulteriori informazioni, consulta [Requisiti](#cloudwatch-logs-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`batchMode` (facoltativo)
Indica se i batch di record di registro verranno estratti e caricati in. CloudWatch I valori includono `true` o `false` (impostazione predefinita). Per ulteriori informazioni, consulta [Requisiti](#cloudwatch-logs-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione CloudWatch Logs in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchLogs": {
"logGroupName": "IotLogs",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw",
"batchMode": false
}
}
]
}
}
```
## Consulta anche
+ [Che cos'è Amazon CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/) nella Guida per l'*utente di Amazon CloudWatch Logs*
# CloudWatch metriche
L'azione CloudWatch metric (`cloudwatchMetric`) acquisisce una metrica Amazon CloudWatch. È possibile specificare namespace, nome, valore, unità e timestamp per il parametro.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'operazione. `cloudwatch:PutMetricData` Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`metricName`
Il nome della CloudWatch metrica.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`metricNamespace`
Il nome dello spazio dei nomi della CloudWatch metrica.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`metricUnit`
L'unità metrica supportata da. CloudWatch
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`metricValue`
Una stringa che contiene il valore CloudWatch metrico.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`metricTimestamp`
(Facoltativo) Una stringa che contiene l’orario espresso in secondi nel tempo di epoca Unix. Il valore predefinito utilizzato è il tempo di epoca Unix corrente.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleArn`
Il ruolo IAM che consente l'accesso alla CloudWatch metrica. Per ulteriori informazioni, consulta [Requisiti](#cloudwatch-metrics-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione CloudWatch metrica in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "IotMetric",
"metricNamespace": "IotNamespace",
"metricUnit": "Count",
"metricValue": "1",
"metricTimestamp": "1456821314",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione CloudWatch metrica con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "${topic()}",
"metricNamespace": "${namespace}",
"metricUnit": "${unit}",
"metricValue": "${value}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## Consulta anche
+ [Che cos'è Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) nella *Amazon CloudWatch User Guide*
+ [Utilizzo dei CloudWatch parametri di Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) nella *Amazon CloudWatch User Guide*
# DynamoDB
L’operazione Dynamo DB (`dynamoDB`) scrive, completamente o in parte, un messaggio MQTT a una tabella Amazon DynamoDB.
È possibile seguire un tutorial che mostra come creare una regola con un'operazione Dynamo DB. Per ulteriori informazioni, consulta [Tutorial: Archiviazione dei dati del dispositivo in una tabella DynamoDB](iot-ddb-rule.md).
**Nota**
Questa regola scrive dati non JSON a Dynamo DB come dati binari. La console Dynamo DB mostra i dati come testo con codifica Base64.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'operazione. `dynamodb:PutItem` Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Se si utilizza una chiave gestita dal cliente AWS KMS key (chiave KMS) per crittografare i dati inattivi in DynamoDB, il servizio deve disporre dell'autorizzazione a utilizzare la chiave KMS per conto del chiamante. Per ulteriori informazioni, consulta [Chiave KMS gestita dal cliente](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed) nella *Guida introduttiva di Amazon DynamoDB*.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`tableName`
Nome della tabella DynamoDB.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`hashKeyField`
Nome della chiave hash (detta anche chiave di partizione).
Supporta [modelli sostitutivi: API](iot-substitution-templates.md) e solo AWS CLI
`hashKeyType`
(Facoltativo) Tipo di dati della chiave hash (detta anche chiave di partizione). Valori validi: `STRING`, `NUMBER`.
Supporta [modelli sostitutivi: API](iot-substitution-templates.md) e solo AWS CLI
`hashKeyValue`
Valore della chiave hash. Prendere in considerazione l'utilizzo di un modello di sostituzione come `${topic()}` o `${timestamp()}`.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`rangeKeyField`
(Facoltativo) Nome della chiave di intervallo (detta anche chiave di ordinamento).
Supporta [modelli sostitutivi: API](iot-substitution-templates.md) e solo AWS CLI
`rangeKeyType`
(Facoltativo) Tipo di dati della chiave di intervallo (detta anche chiave di ordinamento). Valori validi: `STRING`, `NUMBER`.
Supporta [modelli sostitutivi: API](iot-substitution-templates.md) e solo AWS CLI
`rangeKeyValue`
(Facoltativo) Valore della chiave di intervallo. Prendere in considerazione l'utilizzo di un modello di sostituzione come `${topic()}` o `${timestamp()}`.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`payloadField`
(Facoltativo) Nome del campo in cui viene scritto il payload. Se questo valore viene omesso, il payload viene scritto nella colonna denominata `payload`.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`operation`
(Facoltativo) Tipo di operazione da eseguire. Valori validi: `INSERT`, `UPDATE`, `DELETE`.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleARN`
Il ruolo IAM che permette l'accesso alla tabella DynamoDB. Per ulteriori informazioni, consulta [Requisiti](#dynamodb-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
I dati scritti nella tabella Dynamo DB sono il risultato dell'istruzione SQL della regola.
## Esempi
Il seguente esempio JSON definisce un'azione DynamoDB in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${topic()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
## Consulta anche
+ [Cos'è Amazon DynamoDB?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) nella *Guida per gli sviluppatori di Amazon DynamoDB*
+ [Guida introduttiva su DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) nella *Guida per gli sviluppatori di Amazon DynamoDB*
+ [Tutorial: Archiviazione dei dati del dispositivo in una tabella DynamoDB](iot-ddb-rule.md)
# Dynamo DBv2
L'azione Dynamo DBv2 (`dynamoDBv2`) scrive tutto o parte di un messaggio MQTT in una tabella Amazon DynamoDB. Ogni attributo nel payload viene scritto in una colonna separata del database Dynamo DB.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'operazione. `dynamodb:PutItem` Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Il payload del messaggio MQTT deve contenere una chiave di livello root corrispondente alla chiave di partizione primaria della tabella e una chiave di livello root corrispondente alla chiave di ordinamento primaria della tabella, se definita.
+ Se si utilizza una chiave gestita dal cliente AWS KMS key (chiave KMS) per crittografare i dati inattivi in DynamoDB, il servizio deve disporre dell'autorizzazione a utilizzare la chiave KMS per conto del chiamante. Per ulteriori informazioni, consulta [Chiave KMS gestita dal cliente](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed) nella *Guida introduttiva di Amazon DynamoDB*.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`putItem`
Un oggetto che specifica la tabella Dynamo DB in cui verranno scritti i dati del messaggio. Questo oggetto deve contenere le seguenti informazioni:
`tableName`
Nome della tabella DynamoDB.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`roleARN`
Il ruolo IAM che permette l'accesso alla tabella DynamoDB. Per ulteriori informazioni, consulta [Requisiti](#dynamodb-v2-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
I dati scritti nella tabella Dynamo DB sono il risultato dell'istruzione SQL della regola.
## Esempi
Il seguente esempio JSON definisce un'azione Dynamo DBv2 in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "my_ddb_table"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2",
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione DynamoDB con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2015-10-08",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "${topic()}"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2"
}
}
]
}
}
```
## Consulta anche
+ [Cos'è Amazon DynamoDB?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) nella *Guida per gli sviluppatori di Amazon DynamoDB*
+ [Guida introduttiva su DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) nella *Guida per gli sviluppatori di Amazon DynamoDB*
# Elasticsearch
L'azione Elasticsearch (`elasticsearch`) scrive i dati dai messaggi MQTT in un dominio Amazon OpenSearch Service. Puoi quindi utilizzare strumenti come OpenSearch Dashboards per interrogare e visualizzare i dati in Service. OpenSearch
**avvertimento**
L'operazione `Elasticsearch` può essere utilizzata solo da operazioni regola esistenti. Per creare una nuova operazione regola o per aggiornarne una esistente, utilizzare invece l'operazione regola `OpenSearch`. Per ulteriori informazioni, consulta [OpenSearch](opensearch-rule-action.md).
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'`es:ESHttpPut`operazione. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Se si utilizza una chiave gestita dal cliente AWS KMS key (chiave KMS) per crittografare i dati inattivi OpenSearch, il servizio deve disporre dell'autorizzazione a utilizzare la chiave KMS per conto del chiamante. Per ulteriori informazioni, consulta [Encryption of data at rest for Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html) nella *Amazon OpenSearch Service Developer Guide*.
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
`endpoint`
Endpoint del dominio del tuo servizio.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`index`
Indice in cui archiviare i dati.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`type`
Tipo di documento che stai archiviando.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`id`
Identificatore univoco per ogni documento.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleARN`
Il ruolo IAM che consente l'accesso al dominio del OpenSearch servizio. Per ulteriori informazioni, consulta [Requisiti](#elasticsearch-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione Elasticsearch in una AWS IoT regola e come specificare i campi per l'azione. `elasticsearch` Per ulteriori informazioni, consulta [ElasticsearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_ElasticsearchAction.html).
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione Elasticsearch con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
## Consulta anche
+ [OpenSearch](opensearch-rule-action.md)
+ [Cos'è Amazon OpenSearch Service?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)
# HTTP
L'azione HTTPS (`http`) invia i dati da un messaggio MQTT a un endpoint HTTPS, che può puntare a un'applicazione o un servizio Web.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ È necessario confermare e abilitare gli endpoint HTTPS prima che il motore delle regole possa utilizzarli. Per ulteriori informazioni, consulta [Destinazioni di azioni HTTP](http-action-destination.md).
## Parameters
Quando create una AWS IoT regola con questa azione, dovete specificare le seguenti informazioni:
`url`
L'endpoint HTTPS in cui il messaggio viene inviato utilizzando il metodo HTTP POST. Se si utilizza un indirizzo IP al posto di un nome host, deve essere un IPv4 indirizzo. IPv6 gli indirizzi non sono supportati.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`confirmationUrl`
(Facoltativo) Se specificato, AWS IoT utilizza l'URL di conferma per creare una destinazione per la regola dell'argomento corrispondente. È necessario abilitare la destinazione dell'azione HTTP prima di utilizzarla in un'azione HTTP. Per ulteriori informazioni, consulta [Destinazioni di azioni HTTP](http-action-destination.md). Se si utilizzano modelli sostitutivi, è necessario creare manualmente una destinazione dell'azione HTTP prima di poter utilizzare l'`http`azione. `confirmationUrl`deve essere un prefisso di. `url`
La relazione tra `url` ed `confirmationUrl` è descritta come segue:
+ Se `url` è codificato e non `confirmationUrl` viene fornito, trattiamo implicitamente il `url` campo come. `confirmationUrl` AWS IoT crea una destinazione per le regole tematiche per. `url`
+ Se `url` e `confirmationUrl` sono codificati, `url` deve iniziare con. `confirmationUrl` AWS IoT crea una destinazione per le regole tematiche per. `confirmationUrl`
+ Se `url` contiene un modello di sostituzione, è necessario specificare `confirmationUrl` e `url` deve cominciare con `confirmationUrl`. Se `confirmationUrl` contiene modelli di sostituzione, è necessario creare manualmente una destinazione di azione HTTP prima di poter utilizzare l'`http`azione. Se `confirmationUrl` non contiene modelli sostitutivi, AWS IoT crea una destinazione per le regole tematiche per. `confirmationUrl`
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`headers`
(Facoltativo) L’elenco delle intestazioni da includere nelle richieste HTTP all'endpoint. Ogni richiesta deve contenere le seguenti informazioni:
`key`
La chiave dell'intestazione.
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`value`
Il valore dell'intestazione.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
Il tipo di contenuto predefinito è application/json quando il payload è in formato JSON. Altrimenti, è application/octet-stream. È possibile sovrascriverlo specificando il tipo di contenuto esatto nell'intestazione con il tipo di contenuto chiave (senza distinzione tra maiuscole e minuscole).
`auth`
(Facoltativo) L’autenticazione utilizzata dal motore di regole per connettersi all'URL dell'endpoint specificato nell'argomento `url`. Attualmente, la versione 4 della firma è l'unico tipo di autenticazione supportato. Per ulteriori informazioni, vedere l'[Autorizzazione HTTP](https://docs.aws.amazon.com/iot/latest/apireference/API_HttpAuthorization.html).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`enableBatching`
(Facoltativo) Se elaborare i messaggi di azione HTTP in un'unica richiesta per un determinato URL. Il valore può essere vero o falso. Per ulteriori informazioni sul batch, vedere Creazione in [batch dei messaggi di azione HTTP](http_batching.md).
Valore booleano
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`batchConfig`
(Facoltativo) Impostazioni di configurazione per il batch. Una volta abilitati, è necessario specificare `batchConfig` i parametri. Se `batchConfig` i parametri non vengono specificati, verranno utilizzati i valori predefiniti.
`maxBatchOpenMs`
Il periodo di tempo massimo (in millisecondi) in cui un messaggio in uscita attende che altri messaggi creino il batch. Maggiore è l'impostazione, maggiore è la latenza dell'azione HTTP in batch.
Valore minimo: 5 ms. Valore massimo: 200 ms.
Valore predefinito: 20 ms
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`maxBatchSize`
Il numero massimo di messaggi raggruppati in un'unica esecuzione di azione.
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
Valore minimo: 2 messaggi. Valore massimo: 10 messaggi
Valore predefinito: 10 messaggi
`maxBatchSizeBytes`
Dimensione massima di un batch di messaggi, in byte.
Valore minimo: 100 byte. Valore massimo: 131.072 byte
Valore predefinito: 5.120 byte
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
Il tipo di contenuto predefinito è application/json quando il payload è in formato JSON. Altrimenti, è application/octet-stream. È possibile sovrascriverlo specificando il tipo di contenuto esatto nell'intestazione con il tipo di contenuto chiave (senza distinzione tra maiuscole e minuscole).
## Esempi
Il seguente esempio JSON definisce una AWS IoT regola con un'azione HTTP.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
]
}
}
]
}
}
```
```
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 123,
"maxBatchSize": 5,
"maxBatchSizeBytes": 131072,
}
},
"errorAction": {
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com"
// batchConfig is not allowed here
}
}
```
## Logica di ripetizione dell'operazione HTTP
Il motore AWS IoT delle regole ritenta l'azione HTTP in base alle seguenti regole:
+ Il motore delle regole tenta di inviare un messaggio almeno una volta.
+ Il motore delle regole effettua un massimo di due tentativi. Il numero massimo di tentativi è tre.
+ Il motore delle regole non effettua un nuovo tentativo se:
+ Il tentativo precedente ha fornito una risposta maggiore di 16.384 byte.
+ Il servizio Web downstream o l'applicazione chiude la connessione TCP dopo il tentativo.
+ Il tempo totale per completare una richiesta con nuovi tentativi ha superato il limite di timeout della richiesta.
+ La richiesta restituisce un codice di stato HTTP diverso da 429, 500-599.
**Nota**
I [costi standard di trasferimento dei dati](https://aws.amazon.com/ec2/pricing/on-demand/) si applicano ai nuovi tentativi.
## Consulta anche
+ [Messaggi di azione HTTP in batch](http_batching.md)
+ [Destinazioni di azioni HTTP](http-action-destination.md)
+ [Indirizza i dati AWS IoT Core direttamente dai tuoi servizi Web](https://aws.amazon.com/blogs/iot/route-data-directly-from-iot-core-to-your-web-services/) nell'*Internet of Things sul blog AWS*
# Messaggi di azione HTTP in batch
È possibile utilizzare il batch per inviare più messaggi di azione HTTP in un'unica richiesta.
## Panoramica di
Il batching consente di inviare messaggi da AWS IoT Core Rules Engine agli endpoint HTTP in batch. Questa funzionalità può aiutare a ridurre i costi riducendo il numero di esecuzioni di azioni HTTP e a migliorare l'efficienza riducendo il sovraccarico associato alla creazione di nuove connessioni.
**Nota**
L'azione HTTP in batch viene misurata come singola azione. Il calcolo viene effettuato in incrementi di 5 KiB, in base alla dimensione del payload in batch in uscita emesso dal Rules Engine al servizio downstream. AWS IoT Core Per ulteriori informazioni, consultare la [pagina dei prezzi di AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
Quando abiliti il batching nella definizione della tua IoT Rule Action, i seguenti parametri saranno disponibili per la configurazione:
`maxBatchOpenMs`
La quantità massima di tempo (in millisecondi) in cui un messaggio in uscita attende che altri messaggi creino il batch. Maggiore è l'impostazione, maggiore è la latenza dell'azione HTTP in batch.
Valore minimo: 5 ms. Valore massimo: 200 ms.
Valore predefinito: 20 ms
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`maxBatchSize`
Il numero massimo di messaggi raggruppati in una singola esecuzione di un'azione di regole IoT.
Valore minimo: 2 messaggi. Valore massimo: 10 messaggi
Valore predefinito: 10 messaggi
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`maxBatchSizeBytes`
Dimensione massima di un batch di messaggi, in byte.
Valore minimo: 100 byte. Valore massimo: 131.072 byte
Valore predefinito: 5120 byte
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
**Importante**
Quando si specificano più parametri batch, il batch viene completato quando viene raggiunto il primo limite. Ad esempio, se si specifica 100 ms come Tempo di apertura massimo del batch e 5 KiB come dimensione massima del batch e Rules Engine esegue batch solo 2 KiB entro 100 ms, verrà creato e inviato un batch da 2 KiB.
## Utilizzo delle intestazioni HTTP in un batch
Quando si utilizzano le intestazioni nell'azione HTTP, la richiesta in batch utilizza il valore di intestazione dell'ultimo messaggio aggiunto al batch (non necessariamente l'ultimo messaggio pubblicato). Ti consigliamo di utilizzare valori di intestazione che siano i seguenti:
+ Identici in tutti i messaggi del batch
+ Applicabile a tutti i messaggi (ad esempio, credenziali di autenticazione)
Le intestazioni vengono inviate con la richiesta HTTP e non fanno parte del corpo del messaggio.
**Nota**
Quando il batching è abilitato:
La richiesta in batch include automaticamente l'`Content-Type: application/json`intestazione, poiché il batch viene inviato come array JSON.
Non possiamo garantire che l'ultimo messaggio del batch sia l'ultimo messaggio che hai pubblicato. È l'ultimo messaggio che è stato inserito nel batch.
## Esempio di payload
L'esempio seguente mostra la struttura di un payload di messaggi in batch inviato all'endpoint HTTP:
```
[
{
"user_id": "user1",
"steps_today": 1000
},
{
"user_id": "user2",
"steps_today": 21000
},
{
"user_id": "user8",
"steps_today": 1500
},
...
]
```
## Limitazioni
Di seguito sono riportate le limitazioni relative al batching:
+ AWS IoT Core non garantisce l'ordinamento complessivo dei messaggi. Il batch viene eseguito localmente su ciascun host, il che può comportare l'elaborazione dei messaggi all'interno di un batch in un ordine diverso da quello di ricezione.
+ AWS IoT Core non fornisce supporto per l'elaborazione dei messaggi sul lato del destinatario. L'utente è responsabile di garantire che il servizio downstream sia configurato per accettare ed elaborare i dati in batch.
+ Il batching tra account non è supportato, anche se i messaggi sono destinati allo stesso identificatore di risorsa (URL HTTP o ARN della risorsa).
+ AWS IoT Core non garantisce che la dimensione del batch soddisfi la configurazione specificata. I batch possono essere inferiori ai limiti configurati in base alla tempistica e al flusso dei messaggi.
+ Quando il batching è abilitato, i payload binari (dati non UTF-8) non sono supportati. Sono accettati solo payload di testo UTF-8 (come JSON). Per inviare dati binari, base64 li codifica prima di inviarli all'azione HTTP, quindi li decodifica sull'endpoint ricevente. Ad esempio, è possibile utilizzare la [funzione encode](iot-sql-functions.html#iot-function-encode) nelle regole IoT per codificare il payload binario. In alternativa, puoi codificare il payload binario nel tuo dispositivo IoT e pubblicarlo su. AWS IoT Core
## Azioni di errore per il batching
Non sarà possibile definire una logica di batch separata nella definizione dell'azione di errore. Tuttavia, l'azione di errore supporterà il batch se è stata definita la logica di batch nell'azione principale.
Quando una richiesta batch ha esito negativo, il motore AWS IoT Core Rules seguirà la logica di [ripetizione dell'azione HTTP](https-rule-action.md#https-rule-action-retry-logic). Dopo l'ultimo tentativo, verrà richiamata un'azione di errore per l'intero batch non riuscito.
Di seguito è riportato un esempio di messaggio di errore con il batching abilitato:
```
{
"ruleName": "FailedTopicRule",
"topic": "topic/rulesengine",
"payloadsWithMetadata": [
{
"id": 1,
"cloudwatchTraceId": "bebd6d93-6d4a-899e-9e40-56e82252d2be",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 2,
"cloudwatchTraceId": "af94d3b8-0b18-1dbf-2c7d-513f5cb9e2e1",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 3,
"cloudwatchTraceId": "ca441266-c2ce-c916-6aee-b9e5c7831675",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
}
],
"failures": [
{
"affectedIds": [
1,
2,
3
],
"failedAction": "HttpAction",
"failedResource": "https://example.foobar.com/HttpAction",
"errorMessage": "HttpAction failed to make a request to the specified endpoint. StatusCode: 500. Reason: Internal Server Error."
},
{
"affectedIds": [
3
],
"failedAction": "S3Action",
"failedResource": "amzn-s3-demo-bucket",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist"
},
{
"affectedIds": [
3
],
"failedAction": "LambdaAction",
"failedResource": "arn:aws:lambda:us-west-2:123456789012:function:dummy",
"errorMessage": "Failed to invoke lambda function. Received Server error from Lambda. The error code is 403"
}
]
}
```
**Nota**
Gli errori di azione in batch generano anche payload di azioni di errore più grandi, il che può aumentare la probabilità di errori dovuti alle dimensioni. È possibile monitorare gli errori relativi alle azioni di errore utilizzando la metrica. `ErrorActionFailure` Per ulteriori informazioni, consulta [Parametri delle operazioni sulle regole](metrics_dimensions.md#rule-action-metrics).
## Combinazione in batch dei messaggi di azione HTTP con AWS CLI
### Creazione o aggiornamento di un'azione di regola con batch
1. Usa il AWS CLI comando appropriato per creare o aggiornare una regola:
+ Per creare una nuova regola, usa il [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)comando:
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
+ Per aggiornare una regola esistente, usa il [replace-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/replace-topic-rule.html)comando:
```
aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
1. Abilita le funzionalità di batch impostando il parametro enableBatching su true nel payload della regola dell'argomento:
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 100,
"maxBatchSize": 5,
"maxBatchSizeBytes": 1024
}
}
}
]
}
```
1. Configura i parametri di batch. Non è necessario specificare tutti i parametri del batch. È possibile scegliere di specificare 1, 2 o tutti e 3 i parametri del batch. Se non si specifica un parametro batch, Rules Engine aggiornerà tale parametro con i valori predefiniti. Per ulteriori informazioni sui parametri di batch e sui relativi valori predefiniti, vedere [Parametri HTTP](https-rule-action.md#https-rule-action-parameters).
# Destinazioni di azioni HTTP
Una destinazione di azione HTTP è un servizio Web verso il quale il motore delle regole può indirizzare i dati da una regola tematica. Una AWS IoT Core risorsa descrive il servizio Web per AWS IoT. Le risorse di destinazione possono essere condivise secondo regole diverse.
Prima di AWS IoT Core poter inviare dati a un altro servizio Web, è necessario confermare che può accedere all'endpoint del servizio.
## Panoramica di
Una destinazione di azione HTTP si riferisce a un servizio Web che supporta un URL di conferma e una o più raccolte URLs di dati. La risorsa di destinazione contiene l'URL di conferma del servizio Web. Quando configuri un'azione HTTP, specifichi l'URL effettivo dell'endpoint che deve ricevere i dati insieme all'URL di conferma del servizio web. Una volta che la destinazione è confermata, la regola dell'argomento invia il risultato dell'istruzione SQL all'endpoint HTTPS (e non all'URL di conferma).
Una destinazione di azione HTTP può trovarsi in uno dei seguenti stati:
ABILITATO
La destinazione è stata confermata e può essere utilizzata da un'operazione della regola. Una destinazione deve essere nello stato `ENABLED` per essere utilizzata in una regola. È possibile abilitare solo una destinazione che si trovi nello stato DISABLED.
DISABILITATO
La destinazione è stata confermata ma non può essere utilizzata da un'operazione della regola. Ciò è utile se si desidera impedire temporaneamente il traffico verso l'endpoint senza dover ripetere il processo di conferma. È possibile disabilitare solo una destinazione che si trovi nello stato ENABLED.
IN\$1PROGRESS
La conferma della destinazione è in corso.
ERRORE
La conferma della destinazione è scaduta.
Dopo che una destinazione di azione HTTP è stata confermata e abilitata, può essere utilizzata con qualsiasi regola del tuo account.
## Gestione delle destinazioni di azione HTTP
È possibile utilizzare le seguenti operazioni per gestire le destinazioni delle azioni HTTP.
### Creazione di destinazioni d'azione HTTP
È possibile creare una destinazione di azione HTTP chiamando l'`CreateTopicRuleDestination`operazione o utilizzando la AWS IoT console.
Dopo aver creato una destinazione, AWS IoT invia una richiesta di conferma all'URL di conferma. La richiesta di conferma ha il seguente formato:
```
HTTP POST {confirmationUrl}/?confirmationToken={confirmationToken}
Headers:
x-amz-rules-engine-message-type: DestinationConfirmation
x-amz-rules-engine-destination-arn:"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4"
Content-Type: application/json
Body:
{
"arn":"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4",
"confirmationToken": "AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"enableUrl": "https://iot.us-east-1.amazonaws.com/confirmdestination/AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"messageType": "DestinationConfirmation"
}
```
Il contenuto della richiesta di conferma include le informazioni seguenti:
arn
L'Amazon Resource Name (ARN) per la destinazione dell'azione HTTP da confermare.
confirmationToken
Il token di conferma inviato da AWS IoT Core. Il token nell'esempio viene troncato. Il token sarà più lungo. Avrai bisogno di questo token per confermare la tua destinazione con AWS IoT Core.
enableUrl
L'URL che si utilizza per confermare la destinazione di una regola dell'argomento.
messageType
Il tipo di messaggio.
### Conferma delle destinazioni di azione HTTP
Per completare il processo di conferma dell'endpoint, se utilizzi il AWS CLI, devi eseguire i seguenti passaggi dopo che l'URL di conferma ha ricevuto la richiesta di conferma.
1.
**Verifica che la destinazione sia pronta per ricevere messaggi**
Per confermare che la destinazione dell'azione HTTP è pronta a ricevere messaggi IoT, `enableUrl` chiamala nella richiesta di conferma oppure esegui l'operazione `ConfirmTopicRuleDestination` API e passa la richiesta `confirmationToken` di conferma.
1.
**Imposta lo stato della regola dell'argomento su abilitato**
Dopo aver confermato che la destinazione può ricevere messaggi, devi eseguire l'operazione `UpdateTopicRuleDestination` API per impostare lo stato della regola dell'argomento su`ENABLED`.
Se utilizzi la AWS IoT console, copiala `confirmationToken` e incollala nella finestra di dialogo di conferma della destinazione nella AWS IoT console. Puoi quindi abilitare la regola dell'argomento.
### Invio di una nuova richiesta di conferma
Per attivare un nuovo messaggio di conferma per una destinazione, chiama `UpdateTopicRuleDestination` e imposta lo stato della destinazione della regola dell'argomento su `IN_PROGRESS`.
Ripeti la procedura di conferma dopo aver inviato una nuova richiesta di conferma.
### Disabilitazione ed eliminazione di una destinazione di azione HTTP
Per disabilitare una destinazione, chiamare `UpdateTopicRuleDestination` e impostare lo stato della destinazione della regola dell'argomento su `DISABLED`. Una regola dell'argomento nello stato DISABLED può essere nuovamente abilitata senza dover inviare una nuova richiesta di conferma.
Per eliminare una destinazione di azione HTTP, chiama. `DeleteTopicRuleDestination`
## Supporto per l'autorità di certificazione
**Nota**
I certificati autofirmati non sono supportati.
Gli endpoint HTTPS in una destinazione di azione HTTP supportano i certificati emessi sia da [AWS Private Certificate Authority che da [Let's](https://letsencrypt.org/certificates/)](https://www.amazontrust.com/repository/) Encrypt.
# AWS IoT Events
L'azione AWS IoT Events (`iotEvents`) invia i dati da un messaggio MQTT a un AWS IoT Events input.
**Importante**
Se il payload viene inviato AWS IoT Core senza o se la chiave non si trova nello stesso percorso JSON specificato nella chiave, la regola IoT non funzionerà con l'errore. `Input attribute Key` `Failed to send message to Iot Events`
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere di eseguire l'`iotevents:BatchPutMessage`operazione. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`batchMode`
(Facoltativo) Indica se elaborare le azioni evento come batch. Il valore predefinito è `false`.
Quando l'istruzione SQL `batchMode` is `true` e la regola restituisce un Array, ogni elemento Array viene trattato come un messaggio separato quando viene inviato a AWS IoT Events tramite una chiamata [https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html](https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html). L'array risultante non può avere più di 10 messaggi.
Quando `batchMode` è `true`, non è possibile specificare un `messageId`.
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`inputName`
Il nome dell' AWS IoT Events input.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`messageId`
(Facoltativo) Utilizzatelo per verificare che un solo input (messaggio) con un dato dato `messageId` venga elaborato da un AWS IoT Events rilevatore. Puoi utilizzare il modello di sostituzione `${newuuid()}` per generare un ID univoco per ogni richiesta.
Quando `batchMode` è `true`, non è possibile specificare un valore `messageId`: verrà assegnato un nuovo valore UUID.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleArn`
Il ruolo IAM che consente di AWS IoT inviare un input a un AWS IoT Events rilevatore. Per ulteriori informazioni, consulta [Requisiti](#iotevents-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
L'esempio JSON seguente illustra come definire un'operazione Eventi IoT in una regola AWS IoT .
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotEvents": {
"inputName": "MyIoTEventsInput",
"messageId": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_events"
}
}
]
}
}
```
## Consulta anche
+ [Che cos'è AWS IoT Events?](https://docs.aws.amazon.com/iotevents/latest/developerguide/) nella *Guida per gli AWS IoT Events sviluppatori*
# AWS IoT SiteWise
L'azione AWS IoT SiteWise (`iotSiteWise`) invia i dati da un messaggio MQTT alle proprietà dell'asset in. AWS IoT SiteWise
Puoi seguire un tutorial che mostra come importare dati dagli AWS IoT oggetti. *Per ulteriori informazioni, consulta il tutorial [Ingesting data to AWS IoT SiteWise from AWS IoT things](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) o la sezione [Ingesting data using AWS IoT Core rules](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html) nella Guida per l'utente.AWS IoT SiteWise *
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'operazione. `iotsitewise:BatchPutAssetPropertyValue` Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
È possibile collegare al ruolo la seguente policy di fiducia di esempio.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*"
}
]
}
```
Per migliorare la sicurezza, è possibile specificare un percorso di gerarchia AWS IoT SiteWise degli asset nella `Condition` proprietà. L'esempio seguente è una policy di attendibilità che specifica un percorso della gerarchia di un asset.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
+ Quando si inviano dati a AWS IoT SiteWise con questa azione, i dati devono soddisfare i requisiti dell'`BatchPutAssetPropertyValue`operazione. Per ulteriori informazioni, consulta [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) nella *documentazione di riferimento dell’API AWS IoT SiteWise *.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`putAssetPropertyValueEntries`
Un elenco di voci del valore della proprietà dell'asset che contengono ciascuna le seguenti informazioni:
`propertyAlias`
(Facoltativo) L'alias di proprietà associato alla proprietà dell'asset. Specifica un `propertyAlias` o un `assetId` e un `propertyId` insieme. Per ulteriori informazioni sugli alias di proprietà, consulta [Mappatura dei flussi di dati industriali alle proprietà degli asset](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/connect-data-streams.html) nella *Guida per l'utente AWS IoT SiteWise *.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`assetId`
(Facoltativo) L'ID della AWS IoT SiteWise risorsa. Specifica un `propertyAlias` o un `assetId` e un `propertyId` insieme.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`propertyId`
(Facoltativo) L'ID di una proprietà di asset. Specifica un `propertyAlias` o un `assetId` e un `propertyId` insieme.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`entryId`
(Facoltativo) Un identificatore univoco per questa voce. Definisci `entryId` per monitorare meglio il messaggio che ha causato un errore, se del caso. Il valore predefinito è un nuovo UUID.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`propertyValues`
Un elenco di valori di proprietà da inserire che contengono timestamp, quality e value (TQV) nel formato seguente:
`timestamp`
Una struttura timestamp contenente le seguenti informazioni:
`timeInSeconds`
Una stringa che contiene il tempo in secondi nel tempo di epoca Unix. Se il payload del messaggio non ha un timestamp, è possibile utilizzare [timestamp()](iot-sql-functions.md#iot-function-timestamp), che restituisce l'ora corrente in millisecondi. Per convertire il tempo in secondi, è possibile utilizzare il seguente modello di sostituzione: **\$1\$1floor(timestamp() / 1E3)\$1**.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`offsetInNanos`
(Facoltativo) Una stringa che contiene l'offset del tempo in nanosecondi dal tempo espresso in secondi. Se il payload del messaggio non ha un timestamp, è possibile utilizzare [timestamp()](iot-sql-functions.md#iot-function-timestamp), che restituisce l'ora corrente in millisecondi. Per calcolare l'offset del nanosecondo da quel momento, è possibile utilizzare il seguente modello di sostituzione: **\$1\$1(timestamp() % 1E3) \$1 1E6\$1**.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
Per quanto riguarda Unix epoch Time, AWS IoT SiteWise accetta solo le voci che hanno un timestamp che va da un massimo di 7 giorni nel passato fino a 5 minuti nel futuro.
`quality`
(Facoltativo) Una stringa che descrive la qualità del valore. Valori validi: `GOOD`, `BAD`, `UNCERTAIN`.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`value`
Una struttura di valori che contiene uno dei seguenti campi valore, a seconda del tipo di dati della proprietà dell'asset:
`booleanValue`
(Facoltativo) Una stringa che contiene il valore booleano della voce di valore.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`doubleValue`
(Facoltativo) Una stringa che contiene il doppio valore della voce di valore.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`integerValue`
(Facoltativo) Una stringa che contiene il valore intero della voce di valore.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`stringValue`
(Facoltativo) Il valore stringa della voce valore.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleArn`
L'ARN del ruolo IAM a cui concede l' AWS IoT autorizzazione a inviare il valore di una proprietà dell'asset a. AWS IoT SiteWise Per ulteriori informazioni, consulta [Requisiti](#iotsitewise-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un' SiteWise azione IoT di base in una AWS IoT regola.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "/some/property/alias",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${my.payload.timeInSeconds}"
},
"value": {
"integerValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
Il seguente esempio JSON definisce un' SiteWise azione IoT in una AWS IoT regola. In questo esempio vengono utilizzati l'argomento come alias di proprietà e la funzione `timestamp()`. Ad esempio, se si pubblicano i dati su `/company/windfarm/3/turbine/7/rpm`, questa operazione invia i dati alla proprietà dell'asset con un alias di proprietà uguale all'argomento specificato.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM '/company/windfarm/+/turbine/+/+'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "${topic()}",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${floor(timestamp() / 1E3)}",
"offsetInNanos": "${(timestamp() % 1E3) * 1E6}"
},
"value": {
"doubleValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
## Consulta anche
+ [Cos'è AWS IoT SiteWise?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) nella *Guida per l'utente di AWS IoT SiteWise *
+ [Inserimento di dati utilizzando AWS IoT Core le regole](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html) *della Guida per l'utente AWS IoT SiteWise *
+ [Inserimento di dati AWS IoT SiteWise da AWS IoT elementi contenuti nella Guida per](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) *l'utente AWS IoT SiteWise *
+ [Risoluzione dei problemi relativi a un'azione AWS IoT SiteWise relativa alle regole](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/troubleshoot-rule.html) *nella Guida per l'utente AWS IoT SiteWise *
# Firehose
L'azione Firehose (`firehose`) invia dati da un messaggio MQTT a uno stream Amazon Data Firehose.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'operazione. `firehose:PutRecord` Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Se utilizzi Firehose per inviare dati a un bucket Amazon S3 e utilizzi AWS KMS un cliente che è AWS KMS key riuscito a crittografare i dati inattivi in Amazon S3, Firehose deve avere accesso al tuo bucket e il permesso di utilizzarlo per conto del chiamante. AWS KMS key Per ulteriori informazioni, consulta [Concedere a Firehose l'accesso a una destinazione Amazon S3 nella Amazon](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-s3) *Data Firehose* Developer Guide.
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
`batchMode`
(Facoltativo) Se distribuire lo stream Firehose come batch utilizzando. [https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html) Il valore predefinito è `false`.
Quando `batchMode` è `true` e l'istruzione SQL della regola restituisce un array, ogni elemento dell'array forma un record nella richiesta `PutRecordBatch`. L'array risultante non può avere più di 500 record.
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`deliveryStreamName`
Lo stream Firehose in cui scrivere i dati dei messaggi.
Supporta [modelli sostitutivi: solo](iot-substitution-templates.md) API AWS CLI
`separator`
(Facoltativo) Un separatore di caratteri utilizzato per separare i record scritti nel flusso Firehose. Se ometti questo parametro, il flusso non utilizza alcun separatore. Valori validi: `,` (virgola), `\t` (scheda), `\n` (nuova riga), `\r\n` (Nuova riga di Windows).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`roleArn`
Il ruolo IAM che consente l'accesso allo stream Firehose. Per ulteriori informazioni, consulta [Requisiti](#kinesis-firehose-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione Firehose in AWS IoT una regola.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "my_firehose_stream",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione Firehose con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
## Consulta anche
+ [Cos'è Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/) nella Guida per *sviluppatori di Amazon Data Firehose*
# Flussi di dati Kinesis
L’operazione Kinesis Data Streams (`kinesis`) scrive i dati da un messaggio MQTT in Amazon Kinesis Data Streams.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'operazione. `kinesis:PutRecord` Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Se utilizzi una chiave KMS AWS KMS gestita dal cliente AWS KMS key per crittografare i dati inattivi in Kinesis Data Streams, il servizio deve disporre dell'autorizzazione a utilizzarla per conto del chiamante. AWS KMS key Per ulteriori informazioni, consulta [Autorizzazioni per l'uso di AWS KMS keys generate dall'utente](https://docs.aws.amazon.com/streams/latest/dev/permissions-user-key-KMS.html) nella *Guida per gli sviluppatori di Amazon Kinesis Data Streams*.
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
`stream`
Flusso di dati Kinesis in cui scrivere i dati.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`partitionKey`
Chiave di partizione usata per determinare in quale shard vengono scritti i dati. La chiave di partizione è in genere composta da un'espressione (ad esempio, `${topic()}` o `${timestamp()}`).
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleArn`
L'ARN del ruolo IAM che concede l' AWS IoT autorizzazione per accedere al flusso di dati Kinesis. Per ulteriori informazioni, consulta [Requisiti](#kinesis-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione Kinesis Data Streams in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "my_kinesis_stream",
"partitionKey": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione Kinesis con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "${topic()}",
"partitionKey": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
## Consulta anche
+ [Cos'è Amazon Kinesis Data Streams?](https://docs.aws.amazon.com/streams/latest/dev/) nella *Guida per gli sviluppatori Amazon Kinesis Data Streams*
# Lambda
Un'azione Lambda (`lambda`) richiama una AWS Lambda funzione, passando un messaggio MQTT. AWS IoT richiama le funzioni Lambda in modo asincrono.
È possibile seguire un tutorial che mostra come creare e testare una regola con un'operazione Lambda. Per ulteriori informazioni, consulta [Tutorial: Formattazione di una notifica utilizzando una funzione AWS Lambda](iot-lambda-rule.md).
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ AWS IoT Per richiamare una funzione Lambda, è necessario configurare una politica che conceda l'autorizzazione `lambda:InvokeFunction` a. AWS IoT Puoi richiamare solo una funzione Lambda definita nella Regione AWS stessa in cui esiste la tua policy Lambda. Le funzioni Lambda usano policy basate sulle risorse, quindi è necessario collegare la policy alla funzione Lambda stessa.
Usa il AWS CLI comando seguente per allegare una politica che conceda l'autorizzazione. `lambda:InvokeFunction` In questo comando, sostituisci:
+ *function\$1name*con il nome della funzione Lambda. Aggiungi una nuova autorizzazione per aggiornare la policy delle risorse della funzione.
+ *region*con Regione AWS la funzione.
+ *account-id*con il Account AWS numero in cui è definita la regola.
+ *rule-name*con il nome della AWS IoT regola per la quale si sta definendo l'azione Lambda.
+ *unique\$1id*con un identificatore di dichiarazione univoco.
**Importante**
Se aggiungi un'autorizzazione per un' AWS IoT entità principale senza fornire `source-arn` o`source-account`, chiunque Account AWS crei una regola con l'azione Lambda può attivare regole da cui richiamare la funzione Lambda. AWS IoT
Per ulteriori informazioni, consulta [Autorizzazioni di AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).
```
aws lambda add-permission \
--function-name function_name \
--region region \
--principal iot.amazonaws.com \
--source-arn arn:aws:iot:region:account-id:rule/rule_name \
--source-account account-id
--statement-id unique_id
--action "lambda:InvokeFunction"
```
+ Se si utilizza la AWS IoT console per creare una regola per l'azione della regola Lambda, la funzione Lambda viene attivata automaticamente. Se si utilizza AWS CloudFormation invece con [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html), è necessario aggiungere una risorsa. [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html) La risorsa ti concede quindi il permesso di attivare la funzione Lambda.
Il codice seguente mostra un esempio di come aggiungere questa risorsa. In questo esempio, sostituisci:
+ *function\$1name*con il nome della funzione Lambda.
+ *region*con Regione AWS la funzione.
+ *account-id*con il Account AWS numero in cui è definita la regola.
+ *rule-name*con il nome della AWS IoT regola per la quale si sta definendo l'azione Lambda.
```
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName: !Ref function_name
Principal: "iot.amazonaws.com"
SourceAccount: account-id
SourceArn: arn:aws:iot:region:account-id:rule/rule_name
```
+ Se utilizzi un AWS KMS cliente gestito AWS KMS key per crittografare i dati inattivi in Lambda, il servizio deve avere l'autorizzazione a utilizzarli per conto AWS KMS key del chiamante. Per ulteriori informazioni, consulta [Crittografia dei dati a riposo](https://docs.aws.amazon.com/lambda/latest/dg/security-dataprotection.html#security-privacy-atrest) nella *Guida per gli sviluppatori di AWS Lambda *.
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
`functionArn`
L'ARN della funzione Lambda da richiamare. AWS IoT deve avere il permesso di richiamare la funzione. Per ulteriori informazioni, consulta [Requisiti](#lambda-rule-action-requirements).
Se non specifici una versione o un alias per la funzione Lambda, la versione più recente della funzione viene arrestata. Se desideri arrestare una versione specifica della funzione Lambda, puoi specificare una versione o un alias. Per specificare una versione o un alias, aggiungere la versione o l'alias all'ARN della funzione Lambda.
```
arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias
```
Per ulteriori informazioni sulla funzione di controllo delle versioni e sugli alias, consulta [Funzione di controllo delle versioni e degli alias in AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html).
Supporta [modelli sostitutivi: API](iot-substitution-templates.md) e solo AWS CLI
## Esempi
Il seguente esempio JSON definisce un'azione Lambda in AWS IoT una regola.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione Lambda con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:${topic()}"
}
}
]
}
}
```
## Consulta anche
+ [AWS Lambda Che cos'è?](https://docs.aws.amazon.com/lambda/latest/dg/) nella *Guida per gli AWS Lambda sviluppatori*
+ [Tutorial: Formattazione di una notifica utilizzando una funzione AWS Lambda](iot-lambda-rule.md)
# Location (Ubicazione)
L'operazione (`location`) Posizione instrada i dati sulla posizione geografica al [servizio di posizione Amazon](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html).
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'`geo:BatchUpdateDevicePosition`operazione. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`deviceId`
L'ID univoco del dispositivo che fornisce i dati sulla posizione. Per ulteriori informazioni, consulta [https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html](https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html) dalla *Documentazione di riferimento delle API del servizio di posizione Amazon*.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`latitude`
Una stringa che restituisce un valore doppio che rappresenta la latitudine della posizione del dispositivo.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`longitude`
Una stringa che restituisce un valore doppio che rappresenta la longitudine della posizione del dispositivo.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleArn`
Il ruolo IAM che permette di accedere al dominio del servizio di posizione Amazon. Per ulteriori informazioni, consulta [Requisiti](#location-rule-action-requirements).
`timestamp`
L'ora in cui i dati sulla posizione sono stati campionati. Il valore predefinito è l'ora in cui è stato elaborato il messaggio MQTT.
Il valore `timestamp` è composto dai due valori seguenti:
+ `value`: un'espressione che restituisce un valore temporale periodo lungo. Puoi utilizzare la funzione [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) per creare un timestamp valido da un valore di data o ora passato nel payload del messaggio. Supporta [modelli di sostituzione](iot-substitution-templates.md): Sì.
+ `unit`: (facoltativo) la precisione del valore timestamp risultante dall'espressione descritta in `value`. Valori validi: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`. Il valore predefinito è `MILLISECONDS`. Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API. AWS CLI
`trackerName`
Il nome della risorsa tracker nel servizio di posizione Amazon in cui la posizione viene aggiornata. Per ulteriori informazioni, consulta [Tracker](https://docs.aws.amazon.com//location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview) nella *Guida per gli sviluppatori del servizio di posizione Amazon*.
Supporta [modelli sostitutivi: API](iot-substitution-templates.md) e solo AWS CLI
## Esempi
Il seguente esempio JSON definisce un'azione Location in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123454962127:role/service-role/ExampleRole",
"trackerName": "MyTracker",
"deviceId": "001",
"sampleTime": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "-12.3456",
"longitude": "65.4321"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione Location con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/ExampleRole",
"trackerName": "${TrackerName}",
"deviceId": "${DeviceID}",
"timestamp": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "${get(position, 0)}",
"longitude": "${get(position, 1)}"
}
}
]
}
}
```
Il seguente esempio di payload MQTT mostra in che modo i modelli di sostituzione nell'esempio precedente accedono ai dati. È possibile utilizzare il comando [https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html](https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html) della CLI per verificare che i dati del payload MQTT vengano distribuiti nel tracker di posizione.
```
{
"TrackerName": "mytracker",
"DeviceID": "001",
"position": [
"-12.3456",
"65.4321"
]
}
```
```
aws location get-device-position-history --device-id 001 --tracker-name mytracker
```
```
{
"DevicePositions": [
{
"DeviceId": "001",
"Position": [
-12.3456,
65.4321
],
"ReceivedTime": "2022-11-11T01:31:54.464000+00:00",
"SampleTime": "2022-11-11T01:31:54.308000+00:00"
}
]
}
```
## Consulta anche
+ [Cos'è il servizio di posizione Amazon?](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html) nella *Guida per sviluppatori del servizio di posizione Amazon*.
# OpenSearch
L'azione OpenSearch (`openSearch`) scrive i dati dai messaggi MQTT in un dominio Amazon OpenSearch Service. Puoi quindi utilizzare strumenti come le OpenSearch dashboard per interrogare e visualizzare i dati in Service. OpenSearch
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'`es:ESHttpPut`operazione. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Se utilizzi un cliente che è riuscito AWS KMS key a crittografare i dati archiviati nel OpenSearch Servizio, il servizio deve disporre dell'autorizzazione a utilizzare la chiave KMS per conto del chiamante. Per ulteriori informazioni, consulta [Encryption of data at rest for Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html) nella *Amazon OpenSearch Service Developer Guide*.
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
`endpoint`
L'endpoint del tuo dominio Amazon OpenSearch Service.
Supporta [modelli sostitutivi: solo](iot-substitution-templates.md) API AWS CLI
`index`
L' OpenSearch indice in cui desideri archiviare i tuoi dati.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`type`
Tipo di documento che stai archiviando.
Per OpenSearch le versioni successive alla 1.0, il valore del `type` parametro deve essere`_doc`. Per ulteriori informazioni, consulta la [documentazione relativa ad OpenSearch ](https://opensearch.org/docs/1.0/opensearch/rest-api/document-apis/index-document/#response-body-fields).
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`id`
Identificatore univoco per ogni documento.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleARN`
Il ruolo IAM che consente l'accesso al dominio del OpenSearch servizio. Per ulteriori informazioni, consulta [Requisiti](#opensearch-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Limitazioni
L'azione OpenSearch (`openSearch`) non può essere utilizzata per fornire dati ai cluster VPC Elasticsearch.
## Esempi
Il seguente esempio JSON definisce un' OpenSearch azione in una AWS IoT regola e come specificare i campi per l'azione. `OpenSearch` Per ulteriori informazioni, consulta [OpenSearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_OpenSearchAction.html).
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "_doc",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
Il seguente esempio JSON definisce un' OpenSearch azione con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
**Nota**
Il `type` campo sostituito funziona per la versione 1.0. OpenSearch Per tutte le versioni successive alla 1.0, il valore di `type` deve essere. `_doc`
## Consulta anche
[Cos'è Amazon OpenSearch Service?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/) nella *Amazon OpenSearch Service Developer Guide*
# Ripubblica
L’operazione di ripubblicazione (`republish`) ripubblica un messaggio MQTT in un altro argomento MQTT.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'operazione. `iot:Publish` Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`headers`
Informazioni sulle intestazioni MQTT versione 5.0.
Per ulteriori informazioni, consulta le pagine [RepublishAction](https://docs.aws.amazon.com//iot/latest/apireference/API_RepublishAction.html) e [MqttHeaders](https://docs.aws.amazon.com//iot/latest/apireference/API_MqttHeaders.html) nella *Documentazione di riferimento dell'API AWS *.
`topic`
Argomento MQTT in cui ripubblicare il messaggio.
Per ripubblicare in un argomento riservato, che inizia con `$`, usa `$$`. Ad esempio, se stai ripubblicando in un argomento Device Shadow `$aws/things/MyThing/shadow/update`, specifica l'argomento come `$$aws/things/MyThing/shadow/update`.
La ripubblicazione in [Argomenti di processi riservati](reserved-topics.md#reserved-topics-job) non è supportata.
AWS IoT Device Defender gli argomenti riservati non supportano la pubblicazione HTTP.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`qos`
(Facoltativo) Il livello di qualità del servizio (QoS) da usare per la ripubblicazione dei messaggi. Valori validi: `0`, `1`. Il valore predefinito è `0`. Per ulteriori informazioni su QoS MQTT, consulta [MQTT](mqtt.md).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`roleArn`
Il ruolo IAM che AWS IoT consente la pubblicazione sull'argomento MQTT. Per ulteriori informazioni, consulta [Requisiti](#republish-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione di ripubblicazione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "another/topic",
"qos": 1,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione di ripubblicazione con modelli di sostituzione in una regola. AWS IoT
```
{
"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"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione di ripubblicazione con in una regola. `headers` AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
"headers": {
"payloadFormatIndicator": "UTF8_DATA",
"contentType": "rule/contentType",
"correlationData": "cnVsZSBjb3JyZWxhdGlvbiBkYXRh",
"userProperties": [
{
"key": "ruleKey1",
"value": "ruleValue1"
},
{
"key": "ruleKey2",
"value": "ruleValue2"
}
]
}
}
}
]
}
}
```
**Nota**
L'IP di origine originale non verrà passato tramite l'[operazione Republish](#republish-rule-action).
# S3
L’operazione S3 (`s3`) scrive i dati da un messaggio MQTT in un bucket Amazon Simple Storage Service (Amazon S3).
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'operazione. `s3:PutObject` Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Se utilizzi un servizio AWS KMS gestito dal cliente AWS KMS key per crittografare i dati inattivi in Amazon S3, il servizio deve disporre dell'autorizzazione a utilizzarlo per AWS KMS key conto del chiamante. Per ulteriori informazioni, consulta [AWS Managed AWS KMS keys e Customer managed AWS KMS keys](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-cmks) nella *Amazon Simple Storage Service Developer Guide*.
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
`bucket`
Il bucket Amazon S3 in cui scrivere i dati.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`cannedacl`
(Facoltativo) Lista di controllo degli accessi predefinita Amazon S3 che controlla l'accesso all'oggetto identificato dalla chiave dell'oggetto. Per ulteriori informazioni, inclusi i valori consentiti, consulta la pagina relativa alle [liste di controllo degli accessi predefinite](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`key`
Percorso del file in cui vengono scritti i dati.
Considera un esempio in cui questo parametro è `${topic()}/${timestamp()}` e la regola riceve un messaggio in cui l'argomento è `some/topic`. Se il timestamp corrente è `1460685389`, questa operazione scrive i dati in un file chiamato `1460685389` nella cartella `some/topic` del bucket S3.
Se utilizzi una chiave statica, AWS IoT sovrascrive un singolo file ogni volta che viene richiamata la regola. Consigliamo di utilizzare il timestamp di un messaggio o un altro identificatore univoco del messaggio in modo che, per ogni messaggio ricevuto, venga salvato un nuovo file in Amazon S3.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleArn`
Il ruolo IAM che permette l'accesso al bucket Amazon S3. Per ulteriori informazioni, consulta [Requisiti](#s3-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione S3 in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"cannedacl": "public-read",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3"
}
}
]
}
}
```
## Consulta anche
+ [Cos’è Amazon S3?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/) nella *Guida per l'utente di Amazon Simple Storage Service*
# IoT di Salesforce
Un'operazione Saleforce IoT (`salesforce`) invia i dati dal messaggio MQTT che ha attivato la regola a un flusso di input Salesforce IoT.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`url`
URL esposto dal flusso di input Salesforce IoT. L'URL è disponibile dalla piattaforma Salesforce IoT durante la creazione di un flusso di input. Per ulteriori informazioni, consulta la documentazione di Salesforce IoT.
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`token`
Token usato per autenticare l'accesso al flusso di input Salesforce IoT specificato. Il token è disponibile dalla piattaforma Salesforce IoT durante la creazione di un flusso di input. Per ulteriori informazioni, consulta la documentazione di Salesforce IoT.
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
L'esempio JSON seguente illustra come definire un'operazione Saleforce IoT in una regola AWS IoT .
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"salesforce": {
"token": "ABCDEFGHI123456789abcdefghi123456789",
"url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event"
}
}
]
}
}
```
# SNS
L’operazione SNS (`sns`) invia i dati da un messaggio MQTT come notifica push Amazon Simple Notification Service (Amazon SNS).
È possibile seguire un tutorial che mostra come creare e testare una regola con un'operazione SNS. Per ulteriori informazioni, consulta [Tutorial: Invio di una notifica Amazon SNS](iot-sns-rule.md).
**Nota**
L'operazione SNS non supporta [Argomenti Amazon SNS FIFO (First-In-First-Out)](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html). Poiché il motore di regole è un servizio completamente distribuito, non vi è alcuna garanzia in merito all'ordine dei messaggi quando viene attivata l'operazione SNS.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'`sns:Publish`operazione. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Se utilizzi un AWS KMS servizio gestito dal cliente AWS KMS key per crittografare i dati inattivi in Amazon SNS, il servizio deve disporre dell'autorizzazione a utilizzarlo per AWS KMS key conto del chiamante. Per maggiori informazioni, consulta [Gestione delle chiavi](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html) nel *Guida per gli sviluppatori di Amazon Simple Notification Service*.
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
`targetArn`
Argomento SNS o singolo dispositivo a cui viene inviata la notifica push.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`messageFormat`
(Opzionale) Formato del messaggio. Amazon SNS usa questa impostazione per determinare se il payload deve essere analizzato e se le parti specifiche della piattaforma rilevanti del payload devono essere estratte. Valori validi: `JSON`, `RAW`. L’impostazione predefinita è `RAW`.
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`roleArn`
Il ruolo IAM che permette l'accesso a SNS. Per ulteriori informazioni, consulta [Requisiti](#sns-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione SNS in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-2:123456789012:my_sns_topic",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione SNS con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-1:123456789012:${topic()}",
"messageFormat": "JSON",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
## Consulta anche
+ [Cos'è Amazon Simple Notification Service?](https://docs.aws.amazon.com/sns/latest/dg/) nella *Guida per gli sviluppatori di Amazon Simple Notification Service*
+ [Tutorial: Invio di una notifica Amazon SNS](iot-sns-rule.md)
# SQS
L’operazione SQS (`sqs`) invia i dati da un messaggio MQTT a una coda Amazon Simple Queue Service (Amazon SQS).
**Nota**
L'operazione SQS non supporta [Code Amazon SQS FIFO (First-In-First-Out)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html). Poiché il motore di regole è un servizio completamente distribuito, non vi è alcuna garanzia in merito all'ordine dei messaggi quando viene attivata l'operazione SQS.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'operazione. `sqs:SendMessage` Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Se utilizzi un AWS KMS cliente che è riuscito AWS KMS key a crittografare i dati inattivi in Amazon SQS, il servizio deve avere l'autorizzazione a utilizzarli per AWS KMS key conto del chiamante. Per ulteriori informazioni, consulta [Gestione delle chiavi](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html) nella *Guida per gli sviluppatori di Amazon Simple Queue Service*.
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
`queueUrl`
L’URL della coda Amazon SQS in cui scrivere i dati. Non è necessario che l'area in questo URL sia la stessa della tua Regione AWS [AWS IoT regola](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html).
Potrebbero essere previsti costi aggiuntivi per il trasferimento incrociato dei dati Regioni AWS utilizzando l'azione della regola SQS. Per ulteriori informazioni, consulta i [prezzi di Amazon SQS.](https://aws.amazon.com/sqs/pricing/)
Supporta [modelli sostitutivi: solo](iot-substitution-templates.md) API AWS CLI
`useBase64`
Imposta questo parametro su `true` per configurare l'operazione della regola per codificare in base64 i dati del messaggio prima di scrivere i dati nella coda Amazon SQS. L’impostazione predefinita è `false`.
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`roleArn`
Il ruolo IAM che permette l'accesso alla coda Amazon SQS. Per ulteriori informazioni, consulta [Requisiti](#sqs-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione SQS in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/my_sqs_queue",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
Il seguente esempio JSON definisce un'azione SQS con modelli di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/${topic()}",
"useBase64": true,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
## Consulta anche
+ [Che cos'è Amazon Simple Queue Service?](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/) nella *Guida per gli sviluppatori di Amazon Simple Queue Service*
# Step Functions
L'azione Step Functions (`stepFunctions`) avvia una macchina a AWS Step Functions stati.
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire l'`states:StartExecution`operazione. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
## Parameters
Quando si crea una AWS IoT regola con questa azione, è necessario specificare le seguenti informazioni:
`stateMachineName`
Il nome della macchina a stati Step Functions per avviare l’esecuzione.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`executionNamePrefix`
(Facoltativo) All'esecuzione della macchina a stati verrà assegnato un nome costituito da questo prefisso seguito da un UUID. Se non ne viene fornito uno, Step Functions crea automaticamente un nome univoco per ogni esecuzione della macchina a stati.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleArn`
L'ARN del ruolo che concede il AWS IoT permesso di avviare la macchina a stati. Per ulteriori informazioni, consulta [Requisiti](#stepfunctions-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
## Esempi
Il seguente esempio JSON definisce un'azione Step Functions in una AWS IoT regola.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myStateMachine",
"executionNamePrefix": "myExecution",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_step_functions"
}
}
]
}
}
```
## Consulta anche
+ [Che cos'è AWS Step Functions?](https://docs.aws.amazon.com/step-functions/latest/dg/) nella *Guida per gli AWS Step Functions sviluppatori*
# Timestream
L'operazione della regola Timestream scrive attributi (misure) da un messaggio MQTT in una tabella Amazon Timestream. Per ulteriori informazioni su Amazon Timestream, consulta [Che cos'è Amazon Timestream?](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html).
**Nota**
Amazon Timestream non è disponibile in tutti i sistemi. Regione AWS Se Amazon Timestream non è disponibile nella tua regione, non verrà visualizzato nell'elenco delle operazioni della regola.
Gli attributi memorizzati da questa regola nel database Timestream sono quelli derivanti dall'istruzione query della regola. Il valore di ogni attributo nel risultato dell'istruzione query viene analizzato per dedurre il suo tipo di dati (come in un’operazione [Dynamo DBv2](dynamodb-v2-rule-action.md)). Il valore di ogni attributo viene scritto nel proprio record nella tabella Timestream. Per specificare o modificare il tipo di dati di un attributo, utilizza la funzione [`cast()`](iot-sql-functions.md#iot-sql-function-cast) nell'istruzione di query. Per ulteriori informazioni sul contenuto di ogni record Timestream, consulta [Contenuto del record Timestream](#timestream-rule-action-data).
**Nota**
Con SQL V2 (23/03/2016), i valori numerici che sono numeri interi, come `10.0`, vengono convertite la loro rappresentazione Integer (`10`). Trasmettendoli esplicitamente a un valore `Decimal`, ad esempio utilizzando la funzione [cast()](iot-sql-functions.md#iot-sql-function-cast), non si impedisce questo comportamento: il risultato è ancora un valore `Integer`. Ciò può causare errori di mancata corrispondenza dei tipi, che impediscono la registrazione dei dati nel database Timestream. Per elaborare in modo affidabile valori numerici interi come i valori `Decimal`, utilizza SQL V1 (08/10/2015) per l'istruzione di query della regola.
**Nota**
Il numero massimo di valori che un'azione regola Timestream può scrivere in una tabella Amazon Timestream è 100. Per ulteriori informazioni, consulta [Riferimento della quota Amazon Timestream](https://docs.aws.amazon.com//timestream/latest/developerguide/ts-limits.html#limits.default).
## Requisiti
Questa operazione della regola presenta i seguenti requisiti:
+ Un ruolo IAM che AWS IoT può assumere per eseguire le operazioni `timestream:DescribeEndpoints` and`timestream:WriteRecords`. Per ulteriori informazioni, consulta [Concedere a qualsiasi AWS IoT regola l'accesso richiesto](iot-create-role.md).
Nella AWS IoT console, puoi scegliere, aggiornare o creare un ruolo che consenta di AWS IoT eseguire questa azione relativa alla regola.
+ Se utilizzi un cliente- AWS KMS per crittografare i dati inattivi in Timestream, il servizio deve disporre dell'autorizzazione a utilizzarli per AWS KMS key conto del chiamante. Per ulteriori informazioni, consulta [Come i servizi utilizzano KMS AWS](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html). AWS
## Parameters
Quando crei una AWS IoT regola con questa azione, devi specificare le seguenti informazioni:
`databaseName`
Il nome di un database Amazon Timestream con la tabella per ricevere i record creati dall'azione. Consulta anche `tableName`.
Supporta [modelli sostitutivi](iot-substitution-templates.md): solo API AWS CLI
`dimensions`
Attributi dei metadati delle serie temporali scritti in ogni record di misura. Ad esempio, il nome e la zona di disponibilità di un'istanza EC2 o il nome del produttore di una turbina eolica sono dimensioni.
`name`
Il nome della dimensione dei metadati. Questo è il nome della colonna nel record della tabella del database.
Le dimensioni non possono essere denominate: `measure_name`, `measure_value` oppure `time`. Questi nomi sono riservati. I nomi delle dimensioni non possono iniziare con `ts_` o `measure_value` e non possono contenere i due punti (`:`).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`value`
Il valore da scrivere in questa colonna del record di database.
Supporta [modelli di sostituzione](iot-substitution-templates.md): sì
`roleArn`
L’Amazon Resource Name (ARN) del ruolo che concede l'autorizzazione AWS IoT per scrivere nella tabella del database Timestream. Per ulteriori informazioni, consulta [Requisiti](#timestream-rule-action-requirements).
Supporta [modelli di sostituzione](iot-substitution-templates.md): no
`tableName`
Il nome della tabella del database in cui scrivere i registri delle misure. Consulta anche `databaseName`.
Supporta [modelli sostitutivi: API](iot-substitution-templates.md) e solo AWS CLI
`timestamp`
Il valore da utilizzare per il timestamp della voce. Se vuoto, viene utilizzata l'ora in cui la voce è stata elaborata.
`unit`
La precisione del valore timestamp risultante dall’espressione descritta in `value`.
Valori validi: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`. Il valore predefinito è `MILLISECONDS`.
`value`
Un'espressione che restituisce un lungo valore temporale epoch.
Puoi utilizzare la funzione [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) per creare un timestamp valido da un valore di data o ora passato nel payload del messaggio.
## Contenuto del record Timestream
I dati scritti nella tabella Amazon Timestream da questa operazione includono un timestamp, i metadati dell'operazione della regola Timestream e il risultato dell'istruzione query della regola.
Per ogni attributo (misura) nel risultato dell'istruzione query, questa operazione della regola scrive un record nella tabella TimeStream specificata con queste colonne.
| Nome della colonna | Tipo di attributo | Valore | Commenti |
| --- | --- | --- | --- |
| *dimension-name* | DIMENSIONE | Il valore specificato nella voce di operazione della regola Timestream. | Ciascuna **Dimensione** specificata nella voce di operazione della regola crea una colonna nel database Timestream con il nome della dimensione. |
| measure\$1name | MEASURE\$1NAME | Il nome dell'attributo | Nome dell'attributo nel risultato dell'istruzione query il cui valore è specificato nella colonna `measure_value::data-type`. |
| valore\$1misura:: *data-type* | MISURA\$1VALORE | Il valore dell'attributo nel risultato dell'istruzione di query. Il nome dell'attributo si trova nella colonna `measure_name`. | Il valore viene interpretato\$1 e lanciato come la migliore corrispondenza di: `bigint`, `boolean`, `double` oppure `varchar`. Amazon Timestream crea una colonna separata per ogni tipo di dati. Il valore nel messaggio può essere sottoposto a trasferimento su un altro tipo di dati utilizzando la funzione [`cast()`](iot-sql-functions.md#iot-sql-function-cast) nell'istruzione query della regola. |
| time | TIMESTAMP | La data e l'ora della registrazione nel database. | Questo valore viene assegnato dal motore delle regole o dalla proprietà `timestamp`, se è definita. |
\$1 Il valore dell'attributo, letto dal payload del messaggio, viene interpretato come segue. Consulta [Esempi](#timestream-rule-action-examples) per un'illustrazione di ciascuno di questi casi.
+ Un valore non quotato di `true` o `false` viene interpretato come `boolean`.
+ Un numerico decimale viene interpretato come `double`.
+ Un valore numerico senza virgola decimale viene interpretato come `bigint`.
+ Una stringa tra virgolette viene interpretata come `varchar`.
+ Gli oggetti e i valori dell'array vengono convertiti in stringhe JSON e memorizzati come `varchar`.
## Esempi
Il seguente esempio JSON definisce un'azione della regola Timestream con un modello di sostituzione in una regola. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'iot/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"timestream": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_timestream",
"tableName": "devices_metrics",
"dimensions": [
{
"name": "device_id",
"value": "${clientId()}"
},
{
"name": "device_firmware_sku",
"value": "My Static Metadata"
}
],
"databaseName": "record_devices"
}
}
]
}
}
```
Se utilizzi l'operazione della regola argomento del timestream definita nell'esempio precedente con il payload del messaggio seguente, si ottengono i record di Amazon Timestream scritti nella tabella che segue.
```
{
"boolean_value": true,
"integer_value": 123456789012,
"double_value": 123.456789012,
"string_value": "String value",
"boolean_value_as_string": "true",
"integer_value_as_string": "123456789012",
"double_value_as_string": "123.456789012",
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"],
"complex_value": {
"simple_element": 42,
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"]
}
}
```
Nella tabella seguente vengono visualizzate le colonne del database e i record creati utilizzando l'operazione della regola dell’argomento specificata per elaborare il payload del messaggio precedente. Le colonne `device_firmware_sku` e `device_id` sono le DIMENSIONI definite nell'operazione della regola dell’argomento. L'azione della regola dell’argomento Timestream crea la colonna `time`, `measure_name` e `measure_value::*`, che riempie con i valori del risultato dell'istruzione query dell'operazione della regola dell’argomento.
| device\$1firmware\$1sku | device\$1id | measure\$1name | measure\$1value::bigint | measure\$1value::varchar | measure\$1value::double | measure\$1value::boolean | time |
| --- | --- | --- | --- | --- | --- | --- | --- |
| I miei metadati statici | EXAMPLE738iotconsole-159 -0 | complex\$1value | - | \$1"simple\$1element":42,"array\$1of\$1integers":[23,36,56,72],"array of strings":["red","green","blue"]\$1 | - | - | 2020-08-26 22:42:16.423000000 |
| I miei metadati statici | iotconsole-159 -0 EXAMPLE738 | integer\$1value\$1as\$1string | - | 123456789012 | - | - | 2020-08-26 22:42:16.423000000 |
| I miei metadati statici | iotconsole-159 -0 EXAMPLE738 | boolean\$1value | - | - | - | TRUE | 2020-08-26 22:42:16.423000000 |
| I miei metadati statici | iotconsole-159 -0 EXAMPLE738 | integer\$1value | 123456789012 | - | - | - | 2020-08-26 22:42:16.423000000 |
| I miei metadati statici | iotconsole-159 -0 EXAMPLE738 | string\$1value | - | Valore di stringa | - | - | 2020-08-26 22:42:16.423000000 |
| I miei metadati statici | iotconsole-159 -0 EXAMPLE738 | array\$1of\$1integers | - | [23,36,56,72] | - | - | 2020-08-26 22:42:16.423000000 |
| I miei metadati statici | iotconsole-159 -0 EXAMPLE738 | matrice di stringhe | - | ["red","green","blue"] | - | - | 2020-08-26 22:42:16.423000000 |
| I miei metadati statici | iotconsole-159 -0 EXAMPLE738 | boolean\$1value\$1as\$1string | - | TRUE | - | - | 2020-08-26 22:42:16.423000000 |
| I miei metadati statici | iotconsole-159 -0 EXAMPLE738 | double\$1value | - | - | 123,456789012 | - | 2020-08-26 22:42:16.423000000 |
| I miei metadati statici | console iot-159 -0 EXAMPLE738 | double\$1value\$1as\$1string | - | 123,45679 | - | - | 2020-08-26 22:42:16.423000000 |
## Risoluzione dei problemi relativi a una regola
Se hai un problema con le tue regole, ti consigliamo di attivare i log. CloudWatch Analizzando i registri, è possibile determinare se il problema riguarda l'autorizzazione o, ad esempio, una condizione della clausola DOVE non corrispondente. Per ulteriori informazioni, consulta [Configurazione dei CloudWatch registri](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html).
# Accesso alle risorse di più account utilizzando le regole AWS IoT
È possibile configurare AWS IoT le regole per l'accesso tra account in modo che i dati importati sugli argomenti MQTT di un account possano essere instradati verso i AWS servizi, come Amazon SQS e Lambda, di un altro account. Di seguito viene spiegato come impostare AWS IoT le regole per l'acquisizione di dati tra account diversi, da un argomento MQTT in un account a una destinazione in un altro account.
Le regole cross-account possono essere configurate utilizzando [Autorizzazioni basate su risorse](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#TypesPermissions) sulla risorsa di destinazione. Pertanto, solo le destinazioni che supportano le autorizzazioni basate sulle risorse possono essere abilitate per l'accesso tramite regole tra account. AWS IoT Le destinazioni supportate includono Amazon SQS, Amazon SNS, Amazon S3 e AWS Lambda.
**Nota**
Per le destinazioni supportate, ad eccezione di Amazon SQS, è necessario definire la regola nella stessa Regione AWS risorsa di un altro servizio in modo che l'azione della regola possa interagire con quella risorsa. Per ulteriori informazioni sulle azioni delle AWS IoT regole, consulta le [azioni delle AWS IoT regole](iot-rule-actions.md). Per ulteriori informazioni sull'azione SQS della regola, vedere[SQS](sqs-rule-action.md).
## Prerequisiti
+ Familiarità con [Regole AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)
+ Una comprensione di [utenti](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html) IAM, [Ruoli](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) e [Autorizzazione basata su risorsa](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions.html#TypesPermissions)
+ Avendo [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) installato
## Configurazione tra account per Amazon SQS
Scenario: l'account A invia i dati da un messaggio MQTT a una coda Amazon SQS dell’account B.
| Account AWS | Account denominato | Description |
| --- | --- | --- |
| 1111-1111-1111 | Account A | Operazione delle regole: sqs:SendMessage |
| 2222-2222-2222 | Account B | Coda Amazon SQS [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/accessing-cross-account-resources-using-rules.html) |
**Nota**
[La coda Amazon SQS di destinazione non deve necessariamente corrispondere alla regola Regione AWS .AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) Per ulteriori informazioni sull'azione SQS della regola, consulta. [SQS](sqs-rule-action.md)
**Eseguire le attività dell'Account A**
**Nota**
Per eseguire i seguenti comandi, l'utente IAM deve disporre delle autorizzazioni per `iot:CreateTopicRule` con l’Amazon Resource Name (ARN) della regola e le autorizzazioni a un’operazione `iam:PassRole` con una risorsa come l’ARN del ruolo.
1. [Configura AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) utilizzando l’account IAM dell'utente A.
1. Crea un ruolo IAM che si fidi del motore AWS IoT delle regole e alleghi una policy che consenta l'accesso alla coda Amazon SQS dell'account B. Vedi esempi di comandi e documenti relativi alle policy in [AWS IoT Garantire](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html) l'accesso richiesto.
1. Per creare una regola allegata a un argomento, esegui il [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html).
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
Di seguito è riportato un esempio di file di payload con una regola che inserisce tutti i messaggi inviati all'argomento `iot/test` nella coda Amazon SQS specificata. L'istruzione SQL filtra i messaggi e l'ARN del ruolo concede ad AWS IoT l'autorizzazione per aggiungere il messaggio alla cosa di Amazon SQS.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role",
"useBase64": false
}
}
]
}
```
Per ulteriori informazioni su come definire un'azione Amazon SQS in una AWS IoT regola, consulta [AWS IoT rule actions - Amazon SQS.](https://docs.aws.amazon.com/iot/latest/developerguide/sqs-rule-action.html)
**Esegui le attività dell'Account B**
1. [Configura AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) utilizzando l'account IAM dell’utente B.
1. Per concedere le autorizzazioni per la risorsa della coda Amazon SQS per l'account A, esegui il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/sqs/add-permission.html).
```
aws sqs add-permission --queue-url https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue --label SendMessagesToMyQueue --aws-account-ids 1111-1111-1111 --actions SendMessage
```
## Configurazione tra account per Amazon SNS
Scenario: l'account A invia i dati da un messaggio MQTT a un argomento Amazon SNS dell’account B.
| Account AWS | Account denominato | Description |
| --- | --- | --- |
| 1111-1111-1111 | Account A | Operazione delle regole: sns:Publish |
| 2222-2222-2222 | Account B | ARN Argomento Amazon SNS: arn:aws:sns:region:2222-2222-2222:ExampleTopic |
**Esegui le attività dell'Account A**
**Note**
Per eseguire i seguenti comandi, l'utente IAM deve disporre delle autorizzazioni per `iot:CreateTopicRule` con la regola ARN come risorsa e le autorizzazioni per le operazioni `iam:PassRole` con una risorsa come ruolo ARN.
1. [Configura AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) utilizzando l'account IAM dell’utente A.
1. Crea un ruolo IAM che si fidi del motore AWS IoT delle regole e alleghi una policy che consenta l'accesso all'argomento Amazon SNS dell'account B. Ad esempio, comandi e documenti relativi alle policy, consulta [Garantire AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html) l'accesso richiesto.
1. Per creare una regola allegata a un argomento, esegui il [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html).
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
Di seguito è riportato un esempio di file di payload con una regola che inserisce tutti i messaggi inviati all'argomento `iot/test` nell’argomento Amazon SNS specificato. L'istruzione SQL filtra i messaggi e l'ARN del ruolo concede ad AWS IoT l'autorizzazione per inviare il messaggio all’argomento Amazon SNS.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:region:2222-2222-2222:ExampleTopic",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
Per ulteriori informazioni su come definire un'azione Amazon SNS in una AWS IoT regola, consulta [AWS IoT rule actions - Amazon SNS](https://docs.aws.amazon.com/iot/latest/developerguide/sns-rule-action.html).
**Esegui le attività dell'Account B**
1. [Configura AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) utilizzando l’account IAM dell'utente B.
1. Per concedere l'autorizzazione alla risorsa dell’argomento Amazon SNS all'account A, esegui il [comando add-permission](https://docs.aws.amazon.com/cli/latest/reference/sns/add-permission.html).
```
aws sns add-permission --topic-arn arn:aws:sns:region:2222-2222-2222:ExampleTopic --label Publish-Permission --aws-account-id 1111-1111-1111 --action-name Publish
```
## Configurazione tra account per Amazon S3
Scenario: l'account A invia i dati da un messaggio MQTT a un bucket Amazon S3 dell’account B.
| Account AWS | Account denominato | Description |
| --- | --- | --- |
| 1111-1111-1111 | Account A | Operazione delle regole: s3:PutObject |
| 2222-2222-2222 | Account B | ARN bucket Amazon S3: arn:aws:s3:::amzn-s3-demo-bucket |
**Eseguire le attività dell'Account A**
**Nota**
Per eseguire i seguenti comandi, l'utente IAM deve disporre delle autorizzazioni per `iot:CreateTopicRule` con la regola ARN come risorsa e le autorizzazioni per l’operazione `iam:PassRole` con una risorsa come ruolo ARN.
1. [Configura AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) utilizzando l’account IAM dell'utente A.
1. Crea un ruolo IAM che si fidi del motore AWS IoT delle regole e alleghi una policy che consenta l'accesso al bucket Amazon S3 dell'account B. Ad esempio, comandi e documenti relativi alle policy, consulta [AWS IoT Garantire](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html) l'accesso richiesto.
1. [Per creare una regola da allegare al bucket S3 di destinazione, esegui il comando. create-topic-rule ](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
Di seguito è riportato un esempio di file di payload con una regola che inserisce tutti i messaggi inviati all'argomento `iot/test` nel bucket Amazon S3 specificato. L'istruzione SQL filtra i messaggi e l'ARN del ruolo concede ad AWS IoT l'autorizzazione per aggiungere il messaggio nel bucket Amazon S3.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
Per ulteriori informazioni su come definire un'azione Amazon S3 in una AWS IoT regola, consulta [AWS IoT rule actions - Amazon S3](https://docs.aws.amazon.com/iot/latest/developerguide/s3-rule-action.html).
**Esegui le attività dell'Account B**
1. [Configura AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) utilizzando l’account IAM dell'utente B.
1. Crea una policy bucket che consideri attendibile l'entità dell'account A principale.
Di seguito è riportato un esempio di file di payload che definisce una policy di bucket che considera attendibile l'entità di un altro account.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AddCannedAcl",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::123456789012:root"
]
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
Per ulteriori informazioni, consulta [Esempi di policy bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-use-case-1).
1. [Per allegare la policy del bucket al bucket specificato, esegui il comando. put-bucket-policy ](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-policy.html)
```
aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://./amzn-s3-demo-bucket-policy.json
```
1. Per far sì che l'accesso tra account funzioni, assicurati di avere l’impostazione corretta **Blocca tutti gli accessi pubblici**. Per ulteriori informazioni, consulta [Best practice relative alla sicurezza per Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html).
## Configurazione tra più account per AWS Lambda
Scenario: l'account A richiama una AWS Lambda funzione dell'account B, trasmettendo un messaggio MQTT.
| Account AWS | Account denominato | Description |
| --- | --- | --- |
| 1111-1111-1111 | Account A | Operazione delle regole: lambda:InvokeFunction |
| 2222-2222-2222 | Account B | L'ARN della funzione Lambda: arn:aws:lambda:region:2222-2222-2222:function:example-function |
**Eseguire le attività dell'Account A**
**Note**
Per eseguire i seguenti comandi, l'utente IAM deve disporre delle autorizzazioni a `iot:CreateTopicRule` con la regola ARN come risorsa e le autorizzazioni per l’operazione `iam:PassRole` con risorsa come ruolo ARN.
1. [Configura AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) utilizzando l’account IAM dell'utente A.
1. Esegui il [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) per creare una regola che definisca l'accesso tra account alla funzione Lambda dell'account B.
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
Di seguito è riportato un esempio di file di payload con una regola che inserisce tutti i messaggi inviati all'argomento `iot/test` nella funzione Lambda specificata. L'istruzione SQL filtra i messaggi e l'ARN del ruolo concede ad AWS IoT l'autorizzazione per il passaggio dei dati alla funzione Lambda.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:region:2222-2222-2222:function:example-function"
}
}
]
}
```
Per ulteriori informazioni su come definire un' AWS Lambda azione in una AWS IoT regola, leggi [AWS IoT rule actions - Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/lambda-rule-action.html).
**Esegui le attività dell'Account B**
1. [Configura AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) utilizzando l'account IAM dell’utente B.
1. Esegui il [comando add-permission di Lambda](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) per autorizzare AWS IoT le regole ad attivare la funzione Lambda. Per eseguire il seguente comando, l'utente IAM dovrebbe avere l'autorizzazione per l’operazione `lambda:AddPermission`.
```
aws lambda add-permission --function-name example-function --region us-east-1 --principal iot.amazonaws.com --source-arn arn:aws:iot:region:1111-1111-1111:rule/example-rule --source-account 1111-1111-1111 --statement-id "unique_id" --action "lambda:InvokeFunction"
```
**Opzioni:**
**--principal**
Questo campo consente a AWS IoT (rappresentato da`iot.amazonaws.com`) di chiamare la funzione Lambda.
**--source-arn**
Questo campo conferma che solo `arn:aws:iot:region:1111-1111-1111:rule/example-rule` in AWS IoT attiva questa funzione Lambda e che nessun'altra regola nello stesso o in un altro account può attivare questa funzione Lambda.
**--source-account**
Questo campo conferma che AWS IoT attiva questa funzione Lambda solo per conto dell'`1111-1111-1111`account.
**Note**
Se viene visualizzato un messaggio di errore "Impossibile trovare la regola" nella console della funzione AWS Lambda sotto **Configurazione**, ignora il messaggio di errore e procedi al test della connessione.
# Gestione degli errori (operazione in caso di errore)
Quando AWS IoT riceve un messaggio da un dispositivo, il motore delle regole verifica se il messaggio corrisponde a una regola. In tal caso, l'istruzione query della regola viene valutata e vengono attivate le operazioni della regola, passando il risultato dell'istruzione query.
Se si verifica un problema quando si richiama un'operazione, il motore di regole richiama un'operazione da eseguire in caso di errore, se ne è stata specificata una per la regola. Questo può accadere quando:
+ Una regola non dispone dell'autorizzazione per l'accesso a un bucket Amazon S3.
+ Un errore dell'utente causa il superamento della velocità effettiva di Dynamo DB di cui è stato effettuato il provisioning.
**Nota**
La gestione degli errori trattata in questo argomento riguarda le [operazioni delle regole](iot-rule-actions.md). Per eseguire il debug dei problemi SQL, incluse le funzioni esterne, puoi configurare la AWS IoT registrazione. Per ulteriori informazioni, consulta [Configurare la registrazione AWS IoT](configure-logging.md).
## Formato del messaggio dell'operazione da eseguire in caso di errore
Viene generato un singolo messaggio per ogni regola e messaggio. Se, ad esempio, si verifica un errore per due operazioni nella stessa regola, l'operazione da eseguire in caso di errore riceve un messaggio contenente entrambi gli errori.
Il messaggio dell'operazione di errore è simile a quello nell'esempio seguente.
```
{
"ruleName": "TestAction",
"topic": "testme/action",
"cloudwatchTraceId": "7e146a2c-95b5-6caf-98b9-50e3969734c7",
"clientId": "iotconsole-1511213971966-0",
"base64OriginalPayload": "ewogICJtZXNzYWdlIjogIkhlbGxvIHZyb20gQVdTIElvVCBjb25zb2xlIgp9",
"failures": [
{
"failedAction": "S3Action",
"failedResource": "us-east-1-s3-verify-user",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist (Service: Amazon S3; Status Code: 404; Error Code: NoSuchBucket; Request ID: 9DF5416B9B47B9AF; S3 Extended Request ID: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y=). Message arrived on: error/action, Action: s3, Bucket: us-east-1-s3-verify-user, Key: \"aaa\". Value of x-amz-id-2: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y="
}
]
}
```
ruleName
Nome della regola che ha attivato l'operazione da eseguire in caso di errore.
topic
Argomento dove è stato ricevuto il messaggio originale.
cloudwatchTraceId
Un'identità univoca che si riferisce ai log in degli errori. CloudWatch
clientId
ID client di chi ha pubblicato il messaggio.
base64 OriginalPayload
Payload del messaggio originale con codifica Base64.
failures
failedAction
Nome dell'operazione che non è stato possibile completare, ad esempio "S3Action".
failedResource
Nome della risorsa, ad esempio il nome di un bucket S3.
errorMessage
Descrizione e spiegazione dell'errore.
## Esempio di operazione in caso di errore
Di seguito è illustrato un esempio di una regola a cui è stata aggiunta un'operazione da eseguire in caso di errore. La regola seguente include un'operazione di scrittura dei dati dei messaggi in una tabella Dynamo DB e un'operazione da eseguire in caso di errore di scrittura dei dati in un bucket Amazon S3:
```
{
"sql" : "SELECT * FROM ..."
"actions" : [{
"dynamoDB" : {
"table" : "PoorlyConfiguredTable",
"hashKeyField" : "AConstantString",
"hashKeyValue" : "AHashKey"}}
],
"errorAction" : {
"s3" : {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName" : "message-processing-errors",
"key" : "${replace(topic(), '/', '-') + '-' + timestamp() + '-' + newuuid()}"
}
}
}
```
È possibile utilizzare qualsiasi [funzione](iot-sql-functions.md) o [modello di sostituzione](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) nell'istruzione SQL di un'azione di errore, incluse le funzioni esterne: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda),,,, [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret)e. [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning) Se un'azione di errore richiede la chiamata di una funzione esterna, l'invocazione dell'azione di errore può comportare un fatturato aggiuntivo per la funzione esterna.
Per ulteriori informazioni sulle regole e su come specificare un'azione di errore, vedere [Creazione di una AWS IoT regola](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html).
Per ulteriori informazioni sull'utilizzo CloudWatch per monitorare l'esito positivo o negativo delle regole, vedere[AWS IoT metriche e dimensioni](metrics_dimensions.md).
# Riduzione dei costi di messaggistica con Basic Ingest
[Puoi utilizzare Basic Ingest per inviare in modo sicuro i dati del dispositivo al Servizi AWS supporto da[AWS IoT azioni relative alle regole](iot-rule-actions.md), senza incorrere in costi di messaggistica.](https://aws.amazon.com/iot-core/pricing/) La funzionalità Basic Ingest ottimizza il flusso di dati rimuovendo il broker di messaggistica publish/subscribe dal percorso di inserimento.
Basic Ingest ti permette di inviare messaggi dai tuoi dispositivi o applicazioni. I messaggi hanno nomi di argomenti che iniziano con `$aws/rules/rule_name` per i primi tre livelli, dove `rule_name` è il nome della regola AWS IoT che desideri chiamare.
Con Basic Ingest puoi utilizzare una regola esistente semplicemente aggiungendo il prefisso Basic Ingest (`$aws/rules/rule_name`) all'argomento del messaggio con cui chiami la regola. Ad esempio, se hai una regola denominata `BuildingManager` che viene chiamata da messaggi con argomenti come `Buildings/Building5/Floor2/Room201/Lights` (`"sql": "SELECT * FROM 'Buildings/#'"`), puoi chiamare la stessa regola con Basic Ingest inviando un messaggio con argomento `$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`.
**Nota**
I dispositivi e le regole non possono sottoscrivere gli argomenti Basic Ingest riservati. Ad esempio, le AWS IoT Device Defender `num-messages-received` metriche non vengono emesse in quanto non supportano la sottoscrizione agli argomenti. Per ulteriori informazioni, consulta [Argomenti riservati](reserved-topics.md).
Se hai bisogno di un broker di pubblicazione/sottoscrizione per distribuire messaggi a più abbonati (ad esempio, per recapitare messaggi ad altri dispositivi e al motore delle regole), dovresti continuare a utilizzare il broker di messaggi per gestire la AWS IoT distribuzione dei messaggi. Pertanto, ti consigliamo di pubblicare i messaggi su argomenti diversi da quelli Basic Ingest.
## Utilizzo di Basic Ingest
Prima di utilizzare Basic Ingest, verifica che il tuo dispositivo o la tua applicazione utilizzi una [policy](iot-policies.md) con autorizzazioni di pubblicazione su `$aws/rules/*`. In alternativa, puoi specificare l'autorizzazione per le singole regole nella politica. `$aws/rules/rule_name/*` In caso contrario, i dispositivi e le applicazioni possono continuare a utilizzare le connessioni esistenti con AWS IoT Core.
Quando il messaggio raggiunge il motore di regole, non sussistono differenze di implementazione o gestione dell'errore tra le regole chiamate da Basic Ingest e quelle chiamate tramite sottoscrizioni al broker di messaggi.
Puoi anche creare regole da utilizzare con Basic Ingest. Ricorda:
+ Il prefisso iniziale di un argomento Basic Ingest (`$aws/rules/rule_name`) non è disponibile per la funzione [topic(Decimal)](iot-sql-functions.md#iot-function-topic).
+ Se definisci una regola che viene chiamata solo con Basic Ingest, la clausola `FROM` è facoltativa nel campo `sql` della definizione `rule`. È comunque necessaria se la regola viene chiamata anche da altri messaggi che devono essere inviati tramite il broker di messaggi, ad esempio perché gli altri messaggi devono essere distribuiti a più sottoscrittori. Per ulteriori informazioni, consulta [AWS IoT Riferimento SQL](iot-sql-reference.md).
+ I primi tre livelli di argomento Basic Ingest (`$aws/rules/rule_name`) non vengono conteggiati ai fini del limite di lunghezza di 8 segmenti o del limite totale di 256 caratteri per un argomento. In caso contrario, si applicano le stesse restrizioni, come documentato in [Limiti per AWS IoT](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#limits_iot).
+ Se viene ricevuto un messaggio con un argomento Basic Ingest che specifica una regola inattiva o una regola che non esiste, viene creato un log degli errori in un CloudWatch log Amazon per aiutarti con il debug. Per ulteriori informazioni, consulta [Voci di registro del motore delle regole](cwl-format.md#rule-engine-logs). È indicato un parametro `RuleNotFound` ed è possibile creare allarmi su questo parametro. Per ulteriori informazioni, consulta Parametri delle regole in [Parametri delle regole](metrics_dimensions.md#rulemetrics).
+ È ancora possibile pubblicare con QoS 1 su argomenti Basic Ingest. Riceverai un messaggio PUBACK dopo che il messaggio è stato inviato correttamente al motore delle regole. La ricezione di un PUBACK messaggio non significa che le azioni relative alle regole siano state completate correttamente. Puoi configurare un'operazione di errore per gestire gli errori durante l'esecuzione dell'operazione. Per ulteriori informazioni, consulta [Gestione degli errori (operazione in caso di errore)](rule-error-handling.md).
# 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]
```