Arricchimenti dei messaggi per i messaggi di hub IoT da dispositivo a cloud
Gli arricchimenti dei messaggi sono la possibilità di un hub IoT di stampare i messaggi con informazioni aggiuntive prima dell'invio dei messaggi all'endpoint designato. Un motivo per usare gli arricchimenti dei messaggi consiste nell'includere dati che possono essere usati per semplificare l'elaborazione downstream. Ad esempio, l'arricchimento dei messaggi di telemetria dei dispositivi con un tag del dispositivo gemello può ridurre il carico sui clienti per effettuare chiamate all'API del dispositivo gemello per queste informazioni.
L'arricchimento dei messaggi è costituito da tre elementi principali:
Nome o chiave di arricchimento
Valore
Uno o più endpoint per i quali deve essere applicato l'arricchimento.
La chiave è una stringa. Una chiave può contenere solo caratteri alfanumerici o questi caratteri speciali: trattino (), sottolineatura (-) e punto (._).
Il valore può essere uno degli esempi seguenti:
Qualsiasi stringa statica. I valori dinamici, ad esempio condizioni, logica, operazioni e funzioni non sono consentiti. Ad esempio, se si sviluppa un'applicazione SaaS usata da diversi clienti, è possibile assegnare un identificatore a ogni cliente e renderlo disponibile nell'applicazione. Quando l'applicazione viene eseguita, l'hub IoT stamperà i messaggi di telemetria del dispositivo con l'identificatore del cliente, rendendo possibile elaborare i messaggi in modo diverso per ogni cliente.
Nome dell'hub IoT che invia il messaggio. Questo valore è $iothubname.
Informazioni dal dispositivo gemello, ad esempio il relativo percorso. Gli esempi sono $twin.tags.field e $twin.tags.latitudine.
Nota
A questo punto, solo $iothubname, $twin.tags, $twin.properties.desired e $twin.properties.report sono variabili supportate per l'arricchimento dei messaggi. Inoltre, solo i tipi primitivi sono supportati per gli arricchimenti. I messaggi non possono essere arricchiti con tipi di oggetto.
Gli arricchimenti dei messaggi vengono aggiunti come proprietà dell'applicazione ai messaggi inviati a specifici endpoint.
Applicazione di arricchimenti
I messaggi possono venire da qualsiasi origine dati supportata da hub IoT routing dei messaggi, inclusi gli esempi seguenti:
- telemetria del dispositivo, ad esempio temperatura o pressione
- notifiche di modifica del dispositivo gemello - modifiche nel dispositivo gemello
- eventi del ciclo di vita del dispositivo, ad esempio quando il dispositivo viene creato o eliminato
È possibile aggiungere arricchimenti ai messaggi che verranno aggiunti all'endpoint predefinito di un hub IoT o ai messaggi indirizzati a endpoint personalizzati, ad esempio archiviazione BLOB di Azure, coda del bus di servizio o argomento del bus di servizio.
È anche possibile aggiungere arricchimenti ai messaggi pubblicati in Griglia di eventi creando prima una sottoscrizione di Griglia di eventi con il tipo di messaggio di telemetria del dispositivo. In base a questa sottoscrizione, verrà creata una route predefinita in hub IoT di Azure per i dati di telemetria. Questa singola route può gestire tutte le sottoscrizioni di Griglia di eventi. È quindi possibile configurare gli arricchimenti per l'endpoint usando la scheda Arricchiti messaggi della sezione di routing dei messaggi di hub IoT. Per informazioni sulla reazione agli eventi tramite Griglia di eventi, vedere Iot Hub e Griglia di eventi.
Gli arricchimenti vengono applicati per ogni endpoint. Se si specificano cinque arricchimenti da stampare per un endpoint specifico, tutti i messaggi che passano a tale endpoint vengono contrassegnati con gli stessi cinque arricchimenti.
Gli arricchimenti possono essere configurati usando i metodi seguenti:
| Metodo | Comando |
|---|---|
| Portale | portale di Azure Vedere l'esercitazione sull'arricchimento dei messaggi |
| Interfaccia della riga di comando di Azure | az iot hub message-arricchimento |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
L'aggiunta di arricchimenti dei messaggi non aggiunge latenza al routing dei messaggi.
Per provare gli arricchimenti dei messaggi, vedere l'esercitazione sull'arricchimento dei messaggi
Limitazioni
È possibile aggiungere fino a 10 arricchimenti per hub IoT per tali hub nel livello standard o di base. Per gli hub IoT nel livello gratuito, è possibile aggiungere fino a 2 arricchimenti.
In alcuni casi, se si arricchisce un messaggio con un valore impostato su un tag o una proprietà nel dispositivo gemello, il valore verrà stampato con il percorso del dispositivo gemello specificato. Ad esempio, se un valore di arricchimento è impostato su $twin.tags.field, i messaggi verranno stampati con la stringa "$twin.tags.field", anziché il valore di tale campo dal gemello. Questo comportamento si verifica nei casi seguenti:
L'hub IoT è nel livello di base. Gli hub IoT di base non supportano i dispositivi gemelli.
L'hub IoT si trova nel livello standard, ma il percorso del dispositivo gemello usato per il valore dell'arricchimento non esiste. Ad esempio, se il valore di arricchimento è impostato su $twin.tags.location e il dispositivo gemello non dispone di una proprietà location in tag, il messaggio viene stampato con la stringa "$twin.tags.location".
L'hub IoT si trova nel livello standard, ma il percorso del dispositivo gemello usato per il valore dell'arricchimento viene risolto in un oggetto anziché in una proprietà semplice. Ad esempio, se il valore di arricchimento è impostato su $twin.tags.location e la proprietà location in tag è un oggetto che contiene proprietà figlio come
{"building": 43, "room": 503}, il messaggio viene stampato con la stringa "$twin.tags.location".
Gli aggiornamenti a un dispositivo gemello possono richiedere fino a cinque minuti per riflettersi nel valore di arricchimento corrispondente.
Le dimensioni totali del messaggio, inclusi gli arricchimenti, non possono superare i 256 KB. Se una dimensione del messaggio supera 256 KB, l'hub IoT rilascia il messaggio. È possibile usare hub IoT metriche per identificare ed eseguire il debug degli errori quando vengono eliminati i messaggi. Ad esempio, è possibile monitorare i messaggi di telemetria incompatibili (d2c.telemetry.egress.invalid) nelle metriche di routing. Per altre informazioni, vedere Monitoraggio dell'hub IoT di Azure.
Gli arricchimenti dei messaggi non si applicano agli eventi di modifica di gemelli digitali.
I moduli non ereditano tag gemelli dai propri dispositivi corrispondenti. Gli arricchimenti per i messaggi provenienti dai moduli del dispositivo , ad esempio dai moduli di IoT Edge, devono usare i tag gemelli impostati nel modulo gemello.
Prezzi
Gli arricchimenti dei messaggi sono disponibili senza costi aggiuntivi. Attualmente, viene addebitato l'addebito quando si invia un messaggio a un hub IoT. Il messaggio viene addebitato una sola volta, anche se il messaggio passa a più endpoint.
Passaggi successivi
Per altre informazioni sul routing dei messaggi in un hub IoT, vedere questi articoli: