Arricchimento dei messaggi per i messaggi dell'hub da dispositivo a cloudMessage enrichments for device-to-cloud IoT Hub messages

I miglioramenti apportati ai messaggi sono la possibilità dell'hub Internet di contrassegnare i messaggi con informazioni aggiuntive prima che i messaggi vengano inviati all'endpoint designato.Message enrichments is the ability of the IoT Hub to stamp messages with additional information before the messages are sent to the designated endpoint. Un motivo per utilizzare gli arricchimenti dei messaggi consiste nell'includere dati che possono essere utilizzati per semplificare l'elaborazione downstream.One reason to use message enrichments is to include data that can be used to simplify downstream processing. 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 dei dispositivi gemelli per queste informazioni.For example, enriching device telemetry messages with a device twin tag can reduce load on customers to make device twin API calls for this information.

Flusso di arricchimenti messaggi

Un arricchimento del messaggio ha tre elementi chiave:A message enrichment has three key elements:

  • Nome o chiave di arricchimentoEnrichment name or key

  • ValoreA value

  • Uno o più endpoint per i quali deve essere applicata l'arricchimento.One or more endpoints for which the enrichment should be applied.

La chiave è una stringa.The key is a string. Una chiave può contenere solo caratteri alfanumerici o i caratteri speciali seguenti: il segno meno (), il carattere di - sottolineatura ( _ ) e il punto ( . ).A key can only contain alphanumeric characters or these special characters: hyphen (-), underscore (_), and period (.).

Il valore può essere uno degli esempi seguenti:The value can be any of the following examples:

  • Qualsiasi stringa statica.Any static string. Non sono consentiti valori dinamici quali le condizioni, la logica, le operazioni e le funzioni.Dynamic values such as conditions, logic, operations, and functions are not allowed. Se, ad esempio, si sviluppa un'applicazione SaaS utilizzata da più clienti, è possibile assegnare un identificatore a ogni cliente e rendere tale identificatore disponibile nell'applicazione.For example, if you develop a SaaS application that is used by several customers, you can assign an identifier to each customer and make that identifier available in the application. Quando l'applicazione è in esecuzione, l'hub di tutti i messaggi di telemetria del dispositivo viene timbrato con l'identificatore del cliente, rendendo possibile l'elaborazione dei messaggi in modo diverso per ogni cliente.When the application runs, IoT Hub will stamp the device telemetry messages with the customer's identifier, making it possible to process the messages differently for each customer.

  • Nome dell'hub Internet delle cose che invia il messaggio.The name of the IoT hub sending the message. Questo valore è $iothubname .This value is $iothubname .

  • Informazioni del dispositivo gemello, ad esempio il percorso.Information from the device twin, such as its path. Gli esempi sono $Twin. Tags. Field e $Twin. Tags. Latitudine .Examples would be $twin.tags.field and $twin.tags.latitude .

    Nota

    Al momento, solo $iothubname, $twin. Tags, $twin. Properties. desired e $twin. Properties. Reports sono variabili supportate per l'arricchimento dei messaggi.At this time, only $iothubname, $twin.tags, $twin.properties.desired, and $twin.properties.reported are supported variables for message enrichment.

Gli arricchimenti dei messaggi vengono aggiunti come proprietà dell'applicazione ai messaggi inviati agli endpoint scelti.Message Enrichments are added as application properties to messages sent to chosen endpoint(s).

Applicazione di arricchimentiApplying enrichments

I messaggi possono provenire da qualsiasi origine dati supportata dal routing dei messaggi dell'hubInternet, inclusi gli esempi seguenti:The messages can come from any data source supported by IoT Hub message routing, including the following examples:

  • telemetria dei dispositivi, ad esempio temperatura o pressionedevice telemetry, such as temperature or pressure
  • notifiche di modifiche del dispositivo gemello: modifiche nel dispositivo gemellodevice twin change notifications -- changes in the device twin
  • eventi del ciclo di vita del dispositivo, ad esempio quando il dispositivo viene creato o eliminatodevice life-cycle events, such as when the device is created or deleted

È possibile aggiungere arricchimenti ai messaggi che vengono indirizzati all'endpoint predefinito di un hub delle cose o ai messaggi che vengono indirizzati a endpoint personalizzati, ad esempio archiviazione BLOB di Azure, una coda del bus di servizio o un argomento del bus di servizio.You can add enrichments to messages that are going to the built-in endpoint of an IoT Hub, or messages that are being routed to custom endpoints such as Azure Blob storage, a Service Bus queue, or a Service Bus topic.

È possibile aggiungere arricchimenti ai messaggi che vengono pubblicati in griglia di eventi selezionando l'endpoint come griglia di eventi.You can add enrichments to messages that are being published to Event Grid by selecting the endpoint as Event Grid. Viene creata una route predefinita nell'hub degli indirizzi Internet per la telemetria dei dispositivi, in base alla sottoscrizione di griglia di eventi.We create a default route in IoT Hub to device telemetry, based on your Event Grid subscription. Questa singola route può gestire tutte le sottoscrizioni di griglia di eventi.This single route can handle all of your Event Grid subscriptions. È possibile configurare gli arricchimenti per l'endpoint di griglia di eventi dopo aver creato la sottoscrizione di griglia di eventi per la telemetria del dispositivo.You can configure enrichments for the event grid endpoint after you have created the event grid subscription to device telemetry. Per altre informazioni, vedere Hub e griglia di eventi.For more information, see Iot Hub and Event Grid.

Gli arricchimenti vengono applicati per ogni endpoint.Enrichments are applied per endpoint. Se si specificano cinque arricchimenti da contrassegnare per un endpoint specifico, tutti i messaggi che passano a tale endpoint vengono contrassegnati con gli stessi cinque arricchimenti.If you specify five enrichments to be stamped for a specific endpoint, all messages going to that endpoint are stamped with the same five enrichments.

È possibile configurare gli arricchimenti usando i metodi seguenti:Enrichments can be configured using the the following methods:

MetodoMethod ComandoCommand
PortalePortal Portale di AzureAzure portal Vedere l' esercitazione relativa all'arricchimento dei messaggiSee the message enrichments tutorial
Interfaccia della riga di comando di AzureAzure CLI AZ all hub Message-arricchimentoaz iot hub message-enrichment
Azure PowerShellAzure PowerShell Add-AzIotHubMessageEnrichmentAdd-AzIotHubMessageEnrichment

L'aggiunta di arricchimenti dei messaggi non consente di aggiungere latenza al routing dei messaggi.Adding message enrichments doesn't add latency to the message routing.

Per provare ad arricchire i messaggi, vedere l' esercitazione sull'arricchimento dei messaggiTo try out message enrichments, see the message enrichments tutorial

LimitazioniLimitations

  • È possibile aggiungere fino a 10 arricchimenti per l'hub di tutti gli hub nel livello standard o Basic.You can add up to 10 enrichments per IoT Hub for those hubs in the standard or basic tier. Per gli hub Internet nel livello gratuito, è possibile aggiungere fino a 2 arricchimenti.For IoT Hubs in the free tier, you can add up to 2 enrichments.

  • In alcuni casi, se si applica un arricchimento con un valore impostato su un tag o una proprietà nel dispositivo gemello, il valore verrà timbrato come valore stringa.In some cases, if you are applying an enrichment with a value set to a tag or property in the device twin, the value will be stamped as a string value. Se, ad esempio, un valore di arricchimento è impostato su $twin. Tags. Field, i messaggi verranno contrassegnati con la stringa "$twin. Tags. Field" invece del valore di tale campo dal dispositivo gemello.For example, if an enrichment value is set to $twin.tags.field, the messages will be stamped with the string "$twin.tags.field" rather than the value of that field from the twin. Questo problema si verifica nei casi seguenti:This happens in the following cases:

    • L'hub Internet delle cose è nel livello Basic.Your IoT Hub is in the basic tier. Gli hub Internet del livello Basic non supportano i dispositivi gemelli.Basic tier IoT hubs do not support device twins.

    • L'hub Internet delle cose è nel livello standard, ma il dispositivo che invia il messaggio non ha un dispositivo gemello.Your IoT Hub is in the standard tier, but the device sending the message has no device twin.

    • L'hub Internet delle cose è nel livello standard, ma il percorso del dispositivo gemello usato per il valore dell'arricchimento non esiste.Your IoT Hub is in the standard tier, but the device twin path used for the value of the enrichment does not exist. Se, ad esempio, il valore di arricchimento è impostato su $twin. Tags. location e il dispositivo gemello non dispone di una proprietà location in Tags, il messaggio viene contrassegnato con la stringa "$twin. Tags. location".For example, if the enrichment value is set to $twin.tags.location, and the device twin does not have a location property under tags, the message is stamped with the string "$twin.tags.location".

  • Gli aggiornamenti a un dispositivo gemello possono richiedere fino a cinque minuti per essere riflessi nel valore di arricchimento corrispondente.Updates to a device twin can take up to five minutes to be reflected in the corresponding enrichment value.

  • Le dimensioni totali dei messaggi, incluse le arricchimenti, non possono superare 256 KB.The total message size, including the enrichments, can't exceed 256 KB. Se le dimensioni di un messaggio superano 256 KB, l'hub delle cose eliminerà il messaggio.If a message size exceeds 256 KB, the IoT Hub will drop the message. È possibile usare le metriche dell'hub Internet per identificare ed eseguire il debug degli errori quando i messaggi vengono eliminati.You can use IoT Hub metrics to identify and debug errors when messages are dropped. Ad esempio, è possibile monitorare la metrica dei messaggi di telemetria incompatibile ( D2C. telemetria. uscita. non valida ) nelle metriche di routing.For example, you can monitor the telemetry messages incompatible ( d2c.telemetry.egress.invalid ) metric in the routing metrics. Per altre informazioni, vedere monitorare l'hub.To learn more, see Monitor IoT Hub.

  • Gli arricchimenti del messaggio non si applicano agli eventi di modifica del dispositivo gemello digitale.Message enrichments don't apply to digital twin change events.

PrezziPricing

Gli arricchimenti dei messaggi sono disponibili senza costi aggiuntivi.Message enrichments are available for no additional charge. Attualmente viene addebitato un addebito quando si invia un messaggio a un hub Internet.Currently, you are charged when you send a message to an IoT Hub. Viene addebitata una sola volta per il messaggio, anche se il messaggio viene indirizzato a più endpoint.You are only charged once for that message, even if the message goes to multiple endpoints.

Passaggi successiviNext steps

Vedere questi articoli per altre informazioni sul routing dei messaggi a un hub Internet:Check out these articles for more information about routing messages to an IoT Hub: