Esempi di payload binari Decodifica dei payload del messaggio protbuf

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 * per farvi riferimento in una clausola SELECT.

In questo argomento:

Esempi di payload binari
Decodifica dei payload del messaggio protbuf

Esempi di payload binari

Quando si utilizza * 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 * 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, 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) è 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 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.

In questa sezione:

Prerequisiti
Creazione di file descrittori
Caricamento dei file descrittori nel bucket S3
Configurazione della decodifica protobuf in Rules
Limitazioni
Best practice

Prerequisiti

Una conoscenza di base di Protocol Buffers (protobuf)
I file .proto che definiscono i tipi di messaggio e le dipendenze correlate
Installazione di Protobuf Compiler (protoc) 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 per compilarlo.

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).
Utilizza il compilatore protoc 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=<FILENAME>.desc \
    --proto_path=<PATH_TO_IMPORTS_DIRECTORY> \
    --include_imports \
    <PROTO_FILENAME>.proto
```
Questo comando di esempio genera un file descrittore<FILENAME>.desc, che AWS IoT Core Rules può utilizzare per decodificare i payload protobuf conformi alla struttura di dati definita in. <PROTO_FILENAME>.proto
- --descriptor_set_out
  
  Specifica il nome del file descrittore (<FILENAME>.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 <FILENAME>.desc.
- <PROTO_FILENAME>.proto
  
  Specifica il nome del file .proto da compilare.
Per ulteriori informazioni sul riferimento protoc, consulta Documentazione di riferimento delle API.

Caricamento dei file descrittori nel bucket S3

Dopo aver creato i file descrittori<FILENAME>.desc, carica i file descrittori in un bucket Amazon S3, utilizzando AWS l'API AWS , l'SDK o il. <FILENAME>.desc AWS Management Console

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:::<BUCKET NAME>/<FILENAME>.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 in grado di decodificare il formato di payload dei messaggi protobuf utilizzando la funzione SQL decode(value, decodingScheme). Una firma della funzione dettagliata e un esempio sono disponibili nella funzione SQL decode(value, decodingScheme) della Documentazione di riferimento SQL AWS IoT .

Di seguito è riportata un'espressione SQL di esempio che utilizza la funzione decode(value, decodingScheme):


SELECT VALUE decode(*, 'proto', '<BUCKET NAME>', '<FILENAME>.desc', '<PROTO_FILENAME>', '<PROTO_MESSAGE_TYPE>') FROM '<MY_TOPIC>'

In questa espressione di esempio:

La funzione SQL decode(value, decodingScheme) 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 non è supportata.
Quando si decodificano i payload dei messaggi protobuf, è possibile utilizzare la funzione SQL di decodifica 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. Per ulteriori informazioni su come eseguire il backup dei file nei bucket Amazon S3, consulta la Guida per gli sviluppatori di Amazon S3.
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 ofFunctionExecution, 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 e Voci di registro del motore delle regole.
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.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Query di oggetti nidificati

Versioni SQL