Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Gli arricchimenti dei messaggi sono la possibilità di un hub IoT di stampare i messaggi con informazioni aggiuntive prima che i messaggi vengano inviati 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 del dispositivo con un tag del dispositivo gemello può ridurre il carico sui clienti per effettuare chiamate API del dispositivo gemello per queste informazioni.
Un arricchimento dei messaggi ha tre elementi chiave:
Nome o chiave di arricchimento
Un valore.
Uno o più endpoint ai quali applicare l'arricchimento.
La chiave è una stringa. Una chiave può contenere solo caratteri alfanumerici o caratteri speciali: trattino (-), carattere di 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 più clienti, è possibile assegnare un identificatore a ogni cliente e rendere tale identificatore disponibile nell'applicazione. Quando l'applicazione viene eseguita, l'hub IoT contrassegna i messaggi di telemetria del dispositivo con l'identificatore del cliente, consentendo di 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.latitude.
Annotazioni
Al momento, solo $iothubname, $twin.tags, $twin.properties.desired e $twin.properties.reported 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 agli endpoint scelti.
Applicazione degli arricchimenti
I messaggi possono provenire da qualsiasi origine dati supportata dal routing dei messaggi dell'hub IoT, 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 indirizzati 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, viene creata una route predefinita nell'hub IoT di Azure per i dati di telemetria. Questa singola route può gestire tutte le sottoscrizioni di Event Grid. È quindi possibile configurare gli arricchimenti per l'endpoint usando la scheda Arricchire i messaggi della sezione Routing messaggi dell'hub IoT. Per informazioni sulla reazione agli eventi utilizzando Event Grid, vedere Reagire agli eventi di IoT Hub utilizzando Event Grid per attivare azioni.
Gli arricchimenti vengono applicati per endpoint. Se si specificano cinque arricchimenti da stampare per un endpoint specifico, tutti i messaggi che passano a tale endpoint vengono stampati con gli stessi cinque arricchimenti.
È possibile configurare gli arricchimenti usando i metodi seguenti:
| metodo | Comando |
|---|---|
| Portale |
Portale di Azure Per altre informazioni, vedere Esercitazione: Usare gli arricchimenti dei messaggi dell'hub IoT di Azure. |
| Interfaccia CLI di Azure | az iot hub message-enrichment |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
L'aggiunta di arricchimenti di messaggi non aggiunge latenza al routing dei messaggi.
Per provare gli arricchimenti dei messaggi, vedere Esercitazione: Usare gli arricchimenti dei messaggi dell'hub IoT di Azure
Limitazioni
È possibile aggiungere fino a 10 arricchimenti per ogni hub IoT per tali hub nel livello Standard o Basic. Per gli hub IoT nel livello gratuito, è possibile aggiungere fino a due arricchimenti.
In alcuni casi, il valore viene etichettato con il percorso specificato del device twin se si arricchisce il messaggio inserendo un valore impostato su un tag o una proprietà del device twin. Ad esempio, se un valore di arricchimento è impostato su $twin.tags.field, i messaggi vengono contrassegnati 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 basic. Gli hub IoT di livello Basic non supportano dispositivi gemelli.
L'hub IoT è 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 contrassegnato con la stringa "$twin.tags.location".
L'hub IoT è 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 nei tag è un oggetto che contiene proprietà figlio come
{"building": 43, "room": 503}, il messaggio viene contrassegnato 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 dei messaggi, inclusi gli arricchimenti, non possono superare 256 KB. Se una dimensione del messaggio supera 256 KB, l'hub IoT elimina il messaggio. È possibile usare le metriche dell'hub IoT per identificare ed eseguire il debug degli errori quando i messaggi vengono eliminati. Ad esempio, è possibile monitorare i messaggi di telemetria incompatibili (d2c.telemetry.egress.invalid) nelle metriche di routing. Per altre informazioni, vedere Monitorare l'hub IoT di Azure.
Gli arricchimenti dei messaggi non si applicano agli eventi di modifiche del gemello digitale.
I moduli non ereditano tag gemelli dai dispositivi corrispondenti. Gli arricchimenti per i messaggi provenienti dai moduli del dispositivo (ad esempio dai moduli IoT Edge) devono usare i tag gemelli impostati nel modulo gemello.
Tariffazione
Gli arricchimenti dei messaggi sono disponibili senza costi aggiuntivi. Attualmente, viene addebitato un addebito quando si invia un messaggio a un hub IoT. L'addebito viene effettuato una sola volta per il messaggio, anche se il messaggio passa a più endpoint.
Passaggi successivi
Per altre informazioni sul routing dei messaggi a un hub IoT, vedere questi articoli: