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