Usare il routing dei messaggi dell'hub Internet per inviare messaggi da dispositivo a cloud a endpoint diversiUse IoT Hub message routing to send device-to-cloud messages to different endpoints

Nota

Alcune delle funzionalità indicate in questo articolo, come la messaggistica da cloud a dispositivo, i dispositivi gemelli e la gestione dei dispositivi, sono disponibili solo nel livello Standard dell'hub IoT.Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT Hub. Per altre informazioni sui livelli Basic e Standard dell'hub IoT, vedere come scegliere il livello corretto dell'hub IoT.For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

Il routing dei messaggi consente di inviare messaggi dai dispositivi ai servizi cloud in modo automatizzato, scalabile e affidabile.Message routing enables you to send messages from your devices to cloud services in an automated, scalable, and reliable manner. Il routing dei messaggi può essere usato per:Message routing can be used for:

  • Inviare i messaggi di telemetria del dispositivo e gli eventi in particolare gli eventi del ciclo di vita del dispositivo e gli eventi di modifica del dispositivo gemello all'endpoint predefinito e agli endpoint personalizzati.Sending device telemetry messages as well as events namely, device lifecycle events, and device twin change events to the built-in-endpoint and custom endpoints. Informazioni sugli endpoint di routing.Learn about routing endpoints.

  • Filtrare i dati prima del routing a vari endpoint applicando query complesse.Filtering data before routing it to various endpoints by applying rich queries. Il routing dei messaggi consente di eseguire query sulle proprietà dei messaggi e sul corpo del messaggio, nonché sui tag e sulle proprietà del dispositivo gemello.Message routing allows you to query on the message properties and message body as well as device twin tags and device twin properties. Altre informazioni sull'uso delle query nel routing dei messaggi.Learn more about using queries in message routing.

Hub IoT richiede l'accesso in scrittura a questi endpoint di servizio affinché il routing dei messaggi funzioni correttamente.IoT Hub needs write access to these service endpoints for message routing to work. Se si configurano gli endpoint tramite il Portale di Azure, verranno aggiunte le autorizzazioni necessarie.If you configure your endpoints through the Azure portal, the necessary permissions are added for you. Accertarsi di configurare i servizi per supportare la velocità effettiva prevista.Make sure you configure your services to support the expected throughput. Ad esempio, se si usa hub eventi come endpoint personalizzato, è necessario configurare le unità di velocità effettiva per tale hub eventi in modo da poter gestire l'ingresso degli eventi che si intende inviare tramite il routing dei messaggi dell'hub Internet.For example, if you are using Event Hubs as a custom endpoint, you must configure the throughput units for that event hub so it can handle the ingress of events you plan to send via IoT Hub message routing. Analogamente, quando si usa una coda del bus di servizio come endpoint, è necessario configurare la dimensione massima per assicurarsi che la coda possa conservare tutti i dati in ingresso, fino a quando non viene uscita dai consumer.Similarly, when using a Service Bus Queue as an endpoint, you must configure the maximum size to ensure the queue can hold all the data ingressed, until it is egressed by consumers. Durante la prima configurazione della soluzione IoT, potrebbe essere necessario monitorare gli endpoint aggiuntivi e quindi apportare le modifiche necessarie per il carico effettivo.When you first configure your IoT solution, you may need to monitor your additional endpoints and make any necessary adjustments for the actual load.

L'hub IoT definisce un formato comune per tutta la messaggistica da dispositivo a cloud per l'interoperabilità tra i protocolli.The IoT Hub defines a common format for all device-to-cloud messaging for interoperability across protocols. Se un messaggio corrisponde a più route che puntano allo stesso endpoint, l'hub IoT invia il messaggio a questo endpoint una sola volta.If a message matches multiple routes that point to the same endpoint, IoT Hub delivers message to that endpoint only once. Pertanto, non è necessario configurare la deduplicazione nella coda o nell'argomento del bus di servizio.Therefore, you don't need to configure deduplication on your Service Bus queue or topic. Nelle code partizionate, l'affinità della partizione garantisce l'ordinamento dei messaggi.In partitioned queues, partition affinity guarantees message ordering. Usare questa esercitazione per imparare a configurare il routing dei messaggi.Use this tutorial to learn how to configure message routing.

Endpoint di routingRouting endpoints

Un hub IoT ha un endpoint incorporato predefinito ( messaggi/eventi ) compatibile con Hub eventi.An IoT hub has a default built-in-endpoint ( messages/events ) that is compatible with Event Hubs. È possibile creare endpoint personalizzati per indirizzare i messaggi collegando altri servizi nella sottoscrizione all'hub IoT.You can create custom endpoints to route messages to by linking other services in your subscription to the IoT Hub.

Ogni messaggio viene indirizzato a tutti gli endpoint le cui query di routing corrispondono.Each message is routed to all endpoints whose routing queries it matches. In altre parole, è possibile indirizzare un messaggio a più endpoint.In other words, a message can be routed to multiple endpoints.

Se l'endpoint personalizzato ha configurazioni del firewall, prendere in considerazione l'uso dell'eccezione Microsoft attendibile per la prima parte, per consentire all'hub delle cose di accedere all'endpoint specifico, ovvero archiviazione di Azure, Hub eventi di Azure e il bus di servizio di Azure.If your custom endpoint has firewall configurations, consider using the Microsoft trusted first party exception, to give your IoT Hub access to the specific endpoint - Azure Storage, Azure Event Hubs and Azure Service Bus. Questa operazione è disponibile in aree selezionate per gli hub Internet con identità del servizio gestito.This is available in select regions for IoT Hubs with managed service identity.

L'hub Internet delle cose supporta attualmente gli endpoint seguenti:IoT Hub currently supports the following endpoints:

  • Endpoint predefinitoBuilt-in endpoint
  • Archiviazione di AzureAzure Storage
  • Code e argomenti del bus di servizioService Bus Queues and Service Bus Topics
  • Hub eventiEvent Hubs

Endpoint predefinito come endpoint di routingBuilt-in endpoint as a routing endpoint

È possibile usare l' integrazione standard di Hub eventi e gli SDK per ricevere i messaggi da dispositivo a cloud dall'endpoint predefinito ( messaggi/eventi ).You can use standard Event Hubs integration and SDKs to receive device-to-cloud messages from the built-in endpoint ( messages/events ). Una volta creata una route, i dati vengono interrotti verso l'endpoint incorporato, a meno che non venga creata una route per tale endpoint.Once a Route is created, data stops flowing to the built-in-endpoint unless a Route is created to that endpoint.

Archiviazione di Azure come endpoint di routingAzure Storage as a routing endpoint

È possibile instradare i messaggi a un account di archiviazione BLOB di Azure e Azure Data Lake storage Gen2 (ADLS Gen2).There are two storage services IoT Hub can route messages to -- Azure Blob Storage and Azure Data Lake Storage Gen2 (ADLS Gen2) accounts. Azure Data Lake Storage account sono account di archiviazione gerarchici abilitati per gli spazi dei nomibasati su archiviazione BLOB.Azure Data Lake Storage accounts are hierarchical namespace-enabled storage accounts built on top of blob storage. Entrambi usano i BLOB per la loro archiviazione.Both of these use blobs for their storage.

L'hub Internet delle cose supporta la scrittura di dati in archiviazione di Azure in formato Apache avro e in formato JSON.IoT Hub supports writing data to Azure Storage in the Apache Avro format as well as in JSON format. Il valore predefinito è AVRO.The default is AVRO. Quando si usa la codifica JSON, è necessario impostare contentType su Application/JSON e ContentEncoding su UTF-8 nelle proprietà del sistemadel messaggio.When using JSON encoding, you must set the contentType to application/json and contentEncoding to UTF-8 in the message system properties. Entrambi i valori non fanno distinzione tra maiuscole e minuscole.Both of these values are case-insensitive. Se la codifica del contenuto non è impostata, l'hub Internet scriverà i messaggi nel formato con codifica base 64.If the content encoding is not set, then IoT Hub will write the messages in base 64 encoded format.

Il formato di codifica può essere impostato solo quando è configurato l'endpoint di archiviazione BLOB. non può essere modificato per un endpoint esistente.The encoding format can be only set when the blob storage endpoint is configured; it can't be edited for an existing endpoint. Per cambiare i formati di codifica per un endpoint esistente, è necessario eliminare e ricreare l'endpoint personalizzato con il formato desiderato.To switch encoding formats for an existing endpoint, you'll need to delete and re-create the custom endpoint with the format you want. Una strategia utile potrebbe consistere nel creare un nuovo endpoint personalizzato con il formato di codifica desiderato e aggiungere una route parallela a tale endpoint.One helpful strategy might be to create a new custom endpoint with your desired encoding format and add a parallel route to that endpoint. In questo modo è possibile verificare i dati prima di eliminare l'endpoint esistente.In this way you can verify your data before deleting the existing endpoint.

È possibile selezionare il formato di codifica usando l'API REST di creazione o aggiornamento dell'hub Internet, in particolare RoutingStorageContainerProperties, il portale di Azure, l'interfaccia della riga di comando di Azureo l' Azure PowerShell.You can select the encoding format using the IoT Hub Create or Update REST API, specifically the RoutingStorageContainerProperties, the Azure portal, Azure CLI, or the Azure PowerShell. Nell'immagine seguente viene illustrato come selezionare il formato di codifica nel portale di Azure.The following image shows how to select the encoding format in the Azure portal.

Codifica dell'endpoint di archiviazione BLOB

L'hub Internet delle cose raggruppa i messaggi e scrive i dati nella risorsa di archiviazione ogni volta che il batch raggiunge una determinata dimensione o è trascorso un determinato periodo di tempo.IoT Hub batches messages and writes data to storage whenever the batch reaches a certain size or a certain amount of time has elapsed. Per impostazione predefinita, l'hub IoT usa la convenzione di denominazione di file seguente:IoT Hub defaults to the following file naming convention:

{iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}

È possibile usare qualsiasi convenzione di denominazione. È tuttavia necessario usare tutti i token elencati.You may use any file naming convention, however you must use all listed tokens. L'hub IoT scriverà in un BLOB vuoto se non sono presenti dati da scrivere.IoT Hub will write to an empty blob if there is no data to write.

È consigliabile elencare i BLOB o i file e quindi scorrerli per assicurarsi che tutti i BLOB o i file vengano letti senza creare presupposti della partizione.We recommend listing the blobs or files and then iterating over them, to ensure all blobs or files are read without making any assumptions of partition. L'intervallo di partizione potrebbe potenzialmente cambiare durante un failover avviato da Microsofto un failover manuale dell'hub IoT.The partition range could potentially change during a Microsoft-initiated failover or IoT Hub manual failover. È possibile usare l' API List Blobs per enumerare l'elenco di BLOB o elencare ADLS Gen2 API per l'elenco di file.You can use the List Blobs API to enumerate the list of blobs or List ADLS Gen2 API for the list of files. Per informazioni, vedere l'esempio seguente.Please see the following sample as guidance.

public void ListBlobsInContainer(string containerName, string iothub)
{
    var storageAccount = CloudStorageAccount.Parse(this.blobConnectionString);
    var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
    if (cloudBlobContainer.Exists())
    {
        var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
        foreach (IListBlobItem item in results)
        {
            Console.WriteLine(item.Uri);
        }
    }
}

Per creare un account di archiviazione Azure Data Lake compatibile con Gen2, creare un nuovo account di archiviazione V2 e selezionare abilitato nel campo spazio dei nomi gerarchico nella scheda Avanzate , come illustrato nell'immagine seguente:To create an Azure Data Lake Gen2-compatible storage account, create a new V2 storage account and select enabled on the Hierarchical namespace field on the Advanced tab as shown in the following image:

Selezionare Azure Data Lake Gen2 storage

Code del bus di servizio e argomenti del bus di servizio come endpoint di routingService Bus Queues and Service Bus Topics as a routing endpoint

Nelle code e negli argomenti del bus di servizio usati come endpoint dell'hub IoT non devono essere abilitati le sessioni e il rilevamento duplicati .Service Bus queues and topics used as IoT Hub endpoints must not have Sessions or Duplicate Detection enabled. Se una di queste opzioni è abilitata, l'endpoint risulta non raggiungibile nel portale di Azure.If either of those options are enabled, the endpoint appears as Unreachable in the Azure portal.

Hub eventi come endpoint di routingEvent Hubs as a routing endpoint

Oltre all'endpoint compatibile con Hub eventi predefinito, è anche possibile indirizzare i dati a endpoint personalizzati di tipo Hub eventi.Apart from the built-in-Event Hubs compatible endpoint, you can also route data to custom endpoints of type Event Hubs.

Lettura dei dati indirizzatiReading data that has been routed

È possibile configurare una route seguendo questa esercitazione.You can configure a route by following this tutorial.

Usare le esercitazioni seguenti per informazioni su come leggere messaggi da un endpoint.Use the following tutorials to learn how to read message from an endpoint.

Route di fallbackFallback route

La route di fallback invia tutti i messaggi che non soddisfano le condizioni di query su una delle route esistenti all'istanza predefinita di Hub eventi ( messaggi/eventi ), compatibile con Hub eventi.The fallback route sends all the messages that don't satisfy query conditions on any of the existing routes to the built-in-Event Hubs ( messages/events ), that is compatible with Event Hubs. Se il routing dei messaggi è attivato, è possibile abilitare la funzionalità di route di fallback.If message routing is turned on, you can enable the fallback route capability. Una volta creata una route, i dati vengono interrotti verso l'endpoint incorporato, a meno che non venga creata una route per tale endpoint.Once a route is created, data stops flowing to the built-in-endpoint, unless a route is created to that endpoint. Se non esistono route verso l'endpoint predefinito ed è abilitata una route di fallback, solo i messaggi che non corrispondono ad alcuna condizione di query sulle route verranno inviati all'endpoint predefinito.If there are no routes to the built-in-endpoint and a fallback route is enabled, only messages that don't match any query conditions on routes will be sent to the built-in-endpoint. Inoltre, se vengono eliminate tutte le route esistenti, è necessario abilitare la route di fallback per ricevere tutti i dati sull'endpoint predefinito.Also, if all existing routes are deleted, fallback route must be enabled to receive all data at the built-in-endpoint.

È possibile abilitare o disabilitare la route di fallback nel pannello routing dei messaggi portale di Azure >.You can enable/disable the fallback route in the Azure portal->Message Routing blade. È anche possibile usare Azure Resource Manager per FallbackRouteProperties per usare un endpoint personalizzato per la route di fallback.You can also use Azure Resource Manager for FallbackRouteProperties to use a custom endpoint for fallback route.

Eventi non di telemetriaNon-telemetry events

Oltre ai dati di telemetria del dispositivo, il routing dei messaggi consente anche l'invio di eventi di modifica del dispositivo gemello, eventi del ciclo di vita del dispositivo e eventi di modificaIn addition to device telemetry, message routing also enables sending device twin change events, device lifecycle events, and digital twin change events. Ad esempio, se viene creata una route con origine dati impostata su Eventi di modifica del dispositivo gemello , l'hub IoT invia messaggi all'endpoint che contengono la modifica nel dispositivo gemello.For example, if a route is created with data source set to device twin change events , IoT Hub sends messages to the endpoint that contain the change in the device twin. Analogamente, se viene creata una route con l'origine dati impostata su eventi del ciclo di vita del dispositivo, l'hub Internet invia un messaggio che indica se il dispositivo è stato eliminato o creato.Similarly, if a route is created with data source set to device lifecycle events , IoT Hub sends a message indicating whether the device was deleted or created. Infine, come parte del plug and Playdi Internet delle cose, uno sviluppatore può creare route con l'origine dati impostata su eventi di modifica digitali gemelli e l'hub Internet invia messaggi ogni volta che viene impostata o modificata una proprietà di un dispositivo gemello digitale o quando si verifica un evento di modifica per il dispositivo gemello sottostante.Finally, as part of the IoT Plug and Play, a developer can create routes with data source set to digital twin change events and IoT Hub sends messages whenever a digital twin property is set or changed, a digital twin is replaced, or when a change event happens for the underlying device twin.

L'hub Internet si integra anche con griglia di eventi di Azure per pubblicare gli eventi del dispositivo per supportare integrazioni in tempo reale e automazione dei flussi di lavoro in base a questi eventi.IoT Hub also integrates with Azure Event Grid to publish device events to support real-time integrations and automation of workflows based on these events. Vedere le principali differenze tra il routing dei messaggi e Griglia di eventi per determinare la soluzione ottimale per il proprio scenario.See key differences between message routing and Event Grid to learn which works best for your scenario.

Test delle routeTesting routes

Quando si crea una nuova route o si modifica una route esistente, è consigliabile testare la query di route con un messaggio di esempio.When you create a new route or edit an existing route, you should test the route query with a sample message. È possibile testare singole route o testarle tutte contemporaneamente. Nessuno messaggio viene indirizzato agli endpoint durante il test.You can test individual routes or test all routes at once and no messages are routed to the endpoints during the test. Per i test è possibile usare portale di Azure, Azure Resource Manager, Azure PowerShell e l'interfaccia della riga di comando di Azure.Azure portal, Azure Resource Manager, Azure PowerShell, and Azure CLI can be used for testing. I risultati consentono di identificare se il messaggio di esempio corrisponde alla query, il messaggio non corrisponde alla query o se il test non è stato eseguito perché la sintassi del messaggio o della query di esempio non è corretta.Outcomes help identify whether the sample message matched the query, message did not match the query, or test couldn't run because the sample message or query syntax are incorrect. Per altre informazioni, vedere Test Route (Testare una route) e Test all routes (Testare tutte le route).To learn more, see Test Route and Test all routes.

Ordinamento delle garanzie con recapito almeno una voltaOrdering guarantees with at least once delivery

Il routing dei messaggi dell'hub Internet garantisce il recapito ordinato e almeno una volta per gli endpoint.IoT Hub message routing guarantees ordered and at least once delivery of messages to the endpoints. Ciò significa che possono essere presenti messaggi duplicati e una serie di messaggi può essere ritrasmessa rispettando l'ordinamento originale del messaggio.This means that there can be duplicate messages and a series of messages can be retransmitted honoring the original message ordering. Se, ad esempio, l'ordine originale del messaggio è [1, 2, 3, 4], è possibile ricevere una sequenza di messaggi come [1, 2, 1, 2, 3, 1, 2, 3, 4].For example, if the original message order is [1,2,3,4], you could receive a message sequence like [1,2,1,2,3,1,2,3,4]. La garanzia di ordinamento è che, se si riceve un messaggio [1], sarà sempre seguito da [2, 3, 4].The ordering guarantee is that if you ever receive message [1], it would always be followed by [2,3,4].

Per la gestione dei duplicati dei messaggi, è consigliabile contrassegnare un identificatore univoco nelle proprietà dell'applicazione del messaggio al punto di origine, che in genere è un dispositivo o un modulo.For handling message duplicates, we recommend stamping a unique identifier in the application properties of the message at the point of origin, which is usually a device or a module. Il servizio che utilizza i messaggi è in grado di gestire i messaggi duplicati utilizzando questo identificatore.The service consuming the messages can handle duplicate messages using this identifier.

LatenzaLatency

Quando si indirizzano i messaggi di telemetria da dispositivo a cloud tramite endpoint predefiniti, si verifica un lieve aumento della latenza end-to-end dopo la creazione della prima route.When you route device-to-cloud telemetry messages using built-in endpoints, there is a slight increase in the end-to-end latency after the creation of the first route.

Nella maggior parte dei casi, l'aumento medio della latenza è inferiore a 500 ms.In most cases, the average increase in latency is less than 500 ms. È possibile monitorare la latenza con la metrica dell'hub IoT Routing: message latency for messages/events (Routing: latenza messaggi per messaggi/eventi) o d2c.endpoints.latency.builtIn.events .You can monitor the latency using Routing: message latency for messages/events or d2c.endpoints.latency.builtIn.events IoT Hub metric. La creazione o l'eliminazione di una route successiva alla prima non influisce sulla latenza end-to-end.Creating or deleting any route after the first one does not impact the end-to-end latency.

Monitoraggio e risoluzione dei problemiMonitoring and troubleshooting

L'hub Internet delle cose offre diverse metriche relative al routing e agli endpoint per offrire una panoramica dell'integrità dell'hub e dei messaggi inviati.IoT Hub provides several metrics related to routing and endpoints to give you an overview of the health of your hub and messages sent. Per un elenco di tutte le metriche dell'hub delle cose suddivise per categoria funzionale, vedere metriche nel riferimento ai dati di monitoraggio.For a list of all of the IoT Hub metrics broken out by functional category, see Metrics in the Monitoring data reference. È possibile tenere traccia degli errori che si verificano durante la valutazione di una query di routing e l'integrità dell'endpoint come percepiti dall'hub degli indirizzi Internet con la categoria Route nei log delle risorse dell'hubInternet.You can track errors that occur during evaluation of a routing query and endpoint health as perceived by IoT Hub with the routes category in IoT Hub resource logs. Per altre informazioni sull'uso di metriche e log delle risorse con l'hub Internet, vedere monitorare l'hub.To learn more about using metrics and resource logs with IoT Hub, see Monitor IoT Hub.

È possibile usare l'API REST per ottenere l'integrità dell'endpoint per ottenere lo stato di integrità degli endpoint.You can use the REST API Get Endpoint Health to get health status of the endpoints.

Per ulteriori informazioni e supporto per la risoluzione dei problemi relativi al routing, utilizzare la Guida alla risoluzione dei problemi per il routing .Use the troubleshooting guide for routing for more details and support for troubleshooting routing.

Passaggi successiviNext steps