Creare ed eliminare route ed endpoint usando l'interfaccia della riga di comando di Azure

Questo articolo illustra come gestire route ed endpoint dell'hub IoT di Azure usando l'interfaccia della riga di comando di Azure. Informazioni su come usare l'interfaccia della riga di comando di Azure per creare route ed endpoint per Hub eventi di Azure, code e argomenti del bus di servizio di Azure, Archiviazione di Azure e Cosmos DB.

Per altre informazioni sul funzionamento del routing nell'hub IoT, vedere Usare il routing dei messaggi dell'hub IoT per inviare messaggi da dispositivo a cloud a endpoint diversi. Per informazioni dettagliate sulla configurazione di una route che invia messaggi all'archiviazione e quindi sui test in un dispositivo simulato, vedere Esercitazione: Inviare i dati dei dispositivi ad Archiviazione di Azure usando il routing dei messaggi dell'hub IoT.

Prerequisiti

Le procedure descritte nell'articolo usano le risorse seguenti:

• L'interfaccia della riga di comando di Azure
• Un hub IoT
• Un servizio endpoint in Azure

Interfaccia della riga di comando di Azure

Questo articolo illustra l'uso dell'interfaccia della riga di comando di Azure per usare l'hub IoT e altri servizi di Azure. È possibile scegliere come accedere all'interfaccia della riga di comando di Azure:

• Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.

  

• Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

  • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.

  • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.

  • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

Hub IoT

Creare un hub IoT nella propria sottoscrizione di Azure. Se non si ha ancora un hub, è possibile seguire la procedura descritta in Creare un hub IoT.

Servizio endpoint

È necessario almeno un altro servizio di Azure da usare come endpoint per la route. L'endpoint riceve messaggi del dispositivo e registri eventi.

Decidere quale servizio di Azure usare come endpoint per ricevere i dati degli eventi e del dispositivo con routing: un hub eventi, una coda o un argomento del servizio, un account di archiviazione o un contenitore Cosmos DB. Per il servizio che si sceglie di usare, completare i passaggi per creare un servizio endpoint.

Hub eventi

1. Creare uno spazio dei nomi di Hub eventi e un hub eventi. Per altre informazioni, vedere Avvio rapido: Creare un hub eventi usando l'interfaccia della riga di comando di Azure.

2. Creare una regola di autorizzazione che verrà usata per concedere all'hub IoT l'autorizzazione per inviare dati all'hub eventi.

   Suggerimento

   Il valore RootManageSharedAccessKey del parametro name è il nome predefinito che consente gestire, inviare, ascoltare attestazioni (accesso). Se si desidera limitare le attestazioni, assegnare al parametro name il proprio nome univoco e includere il flag --rights seguito da una delle attestazioni. Ad esempio: --name my-name --rights Send.

   az eventhubs eventhub authorization-rule create --resource-group my-resource-group --namespace-name my-routing-namespace --eventhub-name my-event-hubs --name RootManageSharedAccessKey
   

   Per altre informazioni, vedere Autorizzare l'accesso a Hub eventi di Azure.

coda del bus di servizio

1. Creare uno spazio dei nomi del bus di servizio e una coda Per altre informazioni, vedere Usare l'interfaccia della riga di comando di Azure per creare uno spazio dei nomi del bus di servizio e una coda.

2. Creare una regola di autorizzazione che concederà all'hub IoT l'autorizzazione per inviare dati alla coda. Per name, usare un valore univoco per la regola di autorizzazione.

   az servicebus queue authorization-rule create --resource-group my-resource-group --namespace-name my-namespace --queue-name my-queue --name my-auth-rule --rights Listen
   

   Per altre opzioni delle regole di autorizzazione, vedere az servicebus queue authorization-rule create.

Argomento del bus di servizio

Creare uno spazio dei nomi del bus di servizio, un argomento e una sottoscrizione. Per altre informazioni, vedere Usare l'interfaccia della riga di comando di Azure per creare un argomento del bus di servizio e le sottoscrizioni all'argomento.

Archiviazione di Azure

1. Creare un account di archiviazione. Per altre informazioni, vedere Creare un account di archiviazione.

2. Creare un contenitore nell'account di archiviazione. Per altre informazioni, vedere Gestire contenitori BLOB tramite l'interfaccia della riga di comando di Azure

Cosmos DB

Creare un account Cosmos DB per l'API SQL e un contenitore Cosmos DB. Per altre informazioni, vedere Creare un Azure Cosmos DB for NoSQL.

Creare un endpoint

Tutte le route dell'hub IoT puntano a un endpoint, che riceverà i dati degli eventi e del dispositivo con routing. Più route possono puntare allo stesso endpoint. Attualmente, l'hub IoT supporta endpoint per Hub eventi, code o argomenti del bus di servizio, archiviazione e Cosmos DB. Per creare l'endpoint, è necessario che esista un'istanza del servizio usata per l'endpoint nella sottoscrizione di Azure.

Nota

Questo articolo usa il gruppo di comandi az iot hub message-endpoint, introdotto nella versione 0.19.0 dell'estensione azure-iot per l'interfaccia della riga di comando di Azure. Le versioni precedenti dell'estensione azure-iot usavano il gruppo di comandi az iot hub routing-endpoint, che è simile ed è ancora supportato ma non supporta la creazione di endpoint Cosmos DB.

Per eseguire l'aggiornamento all'ultima versione dell'estensione azure-iot, usare il comando seguente:

az extension update --name azure-iot

Hub eventi

Per creare un endpoint di Hub eventi, usare la regola di autorizzazione creata nei prerequisiti.

1. Usare il comando az eventhubs eventhub authorization-rule keys list per elencare la regola di autorizzazione. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   eventhub_group	Gruppo di risorse dell'hub eventi.
   eventhub_namespace	Nome dello spazio dei nomi di Hub eventi.
   eventhub_name	Nome dell'hub eventi.
   rule_name	Nome della regola di autorizzazione per l'hub eventi. Se è stato copiato l'esempio nei prerequisiti, questo nome è RootManageSharedAccessKey.

   az eventhubs eventhub authorization-rule keys list --resource-group {eventhub_group} --namespace-name {eventhub_namespace} --eventhub-name my-event-hubs --name {rule_name}
   

2. Copiare la stringa di connessione dell'hub eventi dall'output.

3. Usare il comando az iot hub message-endpoint create eventhub per creare l'endpoint personalizzato. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Un nome univoco per il nuovo endpoint.
   eventhub_subscription	ID sottoscrizione dell'hub eventi. Questo argomento può essere omesso se l'hub eventi si trova nella stessa sottoscrizione dell'hub IoT.
   eventhub_group	Gruppo di risorse dell'hub eventi. Questo argomento può essere omesso se l'hub eventi si trova nello stesso gruppo di risorse dell'hub IoT.
   eventhub_connection_string	La stringa di connessione copiata dalla regola di autorizzazione dell'hub eventi.

   az iot hub message-endpoint create eventhub --hub-name {iothub_name} --endpoint-name {endpoint_name}  --connection-string "{eventhub_connection_string}" --endpoint-subscription-id {eventhub_subscription} --endpoint-resource-group {eventhub_group}
   

coda del bus di servizio

Per creare un endpoint della coda del bus di servizio, usare la regola di autorizzazione creata nei prerequisiti.

1. Usare il comando az servicebus queue authorization-rule keys list per ottenere la stringa di connessione della coda del bus di servizio. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   queue_group	Gruppo di risorse della coda del bus di servizio.
   queue_namespace	Nome dello spazio dei nomi della coda del bus di servizio.
   queue_name	Nome della coda.
   rule_name	Il nome della regola di autorizzazione per la coda. Se è stato copiato l'esempio nei prerequisiti, questo nome è my-auth-rule.

   az servicebus queue authorization-rule keys list --resource-group {queue_group} --namespace-name {queue_namespace} --queue-name {queue_name} --name {rule_name}
   

2. Copiare la stringa di connessione della coda del bus di servizio dall'output.

3. Usare il comando az iot hub message-endpoint create servicebus-queue per creare l'endpoint personalizzato. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Un nome univoco per il nuovo endpoint.
   queue_connection_string	La stringa di connessione copiata dalla regola di autorizzazione della coda del bus di servizio.
   queue_subscription	ID sottoscrizione della coda del bus di servizio. Questo argomento può essere omesso se la coda si trova nella stessa sottoscrizione dell'hub IoT.
   queue_group	Gruppo di risorse della coda del bus di servizio. Questo argomento può essere omesso se la coda si trova nello stesso gruppo di risorse dell'hub IoT.

   az iot hub message-endpoint create servicebus-queue --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={queue_connection_string}" --endpoint-resource-group {queue_group} --endpoint-subscription-id {queue_subscription}
   

Argomento del bus di servizio

1. Usare il comando az servicebus topic authorization-rule keys list per ottenere la stringa di connessione dell'argomento del bus di servizio. Il nome predefinito della regola di autorizzazione fornita con un nuovo spazio dei nomi è RootManageSharedAccessKey. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   topic_group	Gruppo di risorse dell'argomento del bus di servizio.
   topic_namespace	Nome dello spazio dei nomi dell'argomento del bus di servizio.
   topic_name	Nome dell'argomento.

   az servicebus topic authorization-rule keys list --resource-group {topic_group} --namespace-name {topic_namespace} --topic-name {topic_name} --name RootManageSharedAccessKey
   

2. Copiare la stringa di connessione dell'argomento del bus di servizio dall'output.

3. Usare il comando az iot hub message-endpoint create servicebus-topic per creare l'endpoint personalizzato. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Un nome univoco per il nuovo endpoint.
   topic_connection_string	La stringa di connessione copiata dalla regola di autorizzazione dell'argomento del bus di servizio.
   topic_subscription	ID sottoscrizione dell'argomento del bus di servizio. Questo argomento può essere omesso se l'argomento si trova nella stessa sottoscrizione dell'hub IoT.
   topic_group	Gruppo di risorse dell'argomento del bus di servizio. Questo argomento può essere omesso se l'argomento si trova nello stesso gruppo di risorse dell'hub IoT.

   az iot hub message-endpoint create servicebus-topic --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={topic_connection_string};EntityPath=my-service-bus-topic --endpoint-resource-group {topic_group} --endpoint-subscription-id {topic_subscription}
   

Archiviazione di Azure

1. Usare il comando az storage account show-connection-string per ottenere la stringa di connessione dalla risorsa di Archiviazione di Azure per creare un endpoint. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   storage_group	Gruppo di risorse dell'account di archiviazione.
   storage_name	Nome dell'account archiviazione.

   az storage account show-connection-string --resource-group my-resource-group --name my-storage-account 
   

2. Copiare la stringa di connessione dall'account di archiviazione dall'output.

3. Usare il comando az iot hub message-endpoint create storage-container per creare un nuovo endpoint di Archiviazione di Azure. Per tutti gli altri parametri, usare i valori per il proprio scenario. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Un nome univoco per il nuovo endpoint.
   storage_connection_string	La stringa di connessione copiata dal comando dell'account di archiviazione.
   container_name	Il nome del contenitore nell'account di archiviazione in cui verranno inviati i dati.
   storage_subscription	ID sottoscrizione dell'archiviazione del bus di servizio. Questo argomento può essere omesso se l'archiviazione si trova nella stessa sottoscrizione dell'hub IoT.
   storage_group	Gruppo di risorse dell'archiviazione del bus di servizio. Questo argomento può essere omesso se l'argomento si trova nello stesso gruppo di risorse dell'hub IoT.

   az iot hub message-endpoint create storage-container--hub-name {iothub_name} --endpoint-name {endpoint_name} --container {container_name} --endpoint-resource-group {storage_group} --connection-string "DefaultEndpointsProtocol={storage_connection_string}" --endpoint-subscription-id {storage_subscription} --resource-group {storage_group}
   

Cosmos DB

1. Usare il comando az cosmosdb keys list per ottenere la stringa di connessione dall'account del database Cosmos DB.

   az cosmosdb keys list --name my-cosmosdb-account --resource-group my-resource-group --type connection-strings
   

2. Copiare la stringa di connessione di Cosmos DB dall'output.

3. Usare il comando az iot hub message-endpoint create cosmosdb-container per creare l'endpoint personalizzato. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Un nome univoco per il nuovo endpoint.
   cosmosdb_connection_string	La stringa di connessione copiata dal comando dell'account di archiviazione di Cosmos DB.
   container_name	Il nome del contenitore nell'account di Cosmos DB in cui verranno inviati i dati.
   database_name	Il nome del database nell'account di Cosmos DB in cui verranno inviati i dati.
   cosmosdb_subscription	ID sottoscrizione dell'account del database di Cosmos DB. Questo argomento può essere omesso se il database si trova nella stessa sottoscrizione dell'hub IoT.
   cosmosdb_group	Gruppo di risorse dell'account del database di Cosmos DB. Questo argomento può essere omesso se il database si trova nello stesso gruppo di risorse dell'hub IoT.

   az iot hub message-endpoint create cosmosdb-container --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "{cosmosdb_connection_string}" --container {container_name} --database-name {database_name} --resource-group my-resource-group --endpoint-account my-cosmosdb-account --container my-cosmosdb-database-container
   

   Nota

   Se si usano identità gestite anziché una stringa di connessione, usare il comando az cosmosdb sql role assignment create per autenticare la propria identità nell'account di Cosmos DB.

   az cosmosdb sql role assignment create -a my-cosmosdb-account -g my-resource-group --scope '/' -n 'Cosmos DB Built-in Data Contributor' -p "IoT Hub System Assigned or User Assigned Identity"
   

Eliminare un endpoint

Per eliminare un endpoint dall'hub IoT, usare il comando az iot hub message-endpoint delete. Con questo comando è possibile eliminare un singolo endpoint, eliminare tutti gli endpoint di un singolo tipo o eliminare tutti gli endpoint da un hub.

Ad esempio, il comando seguente elimina tutti gli endpoint in un hub IoT che puntano alle risorse di archiviazione:

az iot hub message-endpoint delete --hub-name {iothub_name} --endpoint-type storage-container

Creare una route dell'hub IoT

Nell'hub IoT è possibile creare una route per inviare messaggi o acquisire eventi. Ogni route ha un'origine dati e un endpoint. L'origine dati è la posizione in cui hanno origine i messaggi o i log eventi. L'endpoint è la posizione in cui finiscono i messaggi o i log eventi. È possibile scegliere le posizioni per l'origine dati e l'endpoint quando si crea una nuova route nell'hub IoT. Facoltativamente, è possibile Aggiungere query alle route di messaggi per filtrare messaggi o eventi prima di passare all'endpoint.

Nota

Questo articolo usa il gruppo di comandi az iot hub message-route, introdotto nella versione 0.19.0 dell'estensione azure-iot per l'interfaccia della riga di comando di Azure. Le versioni precedenti dell'estensione azure-iot usavano il gruppo di comandi az iot hub route, che è simile ed è ancora supportato.

Per eseguire l'aggiornamento all'ultima versione dell'estensione azure-iot, usare il comando seguente:

az extension update --name azure-iot

1. Usare il comando az iot hub message-route create per creare una nuova route dell'hub IoT usando tale endpoint. Specificare i valori seguenti per i parametri segnaposto:

   parameter	value
   iothub_name	Il nome dell'hub IoT in cui viene creata questa route.
   route_name	Un nome univoco per la nuova route.
   endpoint_name	Nome dell'endpoint a cui la route invierà i dati.
   data_source	L'origine della route. I valori accettati sono: deviceconnectionstateevents, devicejoblifecycleevents, devicelifecycleevents, devicemessages, digitaltwinchangeevents, invalid o twinchangeevents.

   az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}
   

2. Per assicurarsi che la nuova route si trovi nell'hub IoT, usare il comando az iot hub message-route list per visualizzare tutte le route nel proprio hub IoT:

   az iot hub message-route list --hub-name {iothub_name}
   

   Verrà visualizzata una risposta nell'interfaccia della riga di comando di Azure simile a questo esempio:

   [
      {
        "condition": "true",
        "endpointNames": [
          "endpoint_name"
        ],
        "isEnabled": true,
        "name": "route_name",
        "source": "DeviceConnectionStateEvents"
      }
   ]
   

Aggiornare una route dell'hub IoT

È possibile aggiornare alcune proprietà di una route dopo che è stata creata. È possibile modificare l'origine, l'endpoint, la condizione o lo stato abilitato di una route esistente.

Usare il comando az iot hub message-route show per visualizzare i dettagli di una route.

az iot hub message-route show --hub-name {iothub_name} --route-name {route_name}

Usare il comando az iot hub message-route update per aggiornare le proprietà di una route. Ad esempio, il comando seguente aggiorna l'origine della route.

az iot hub message-route update --hub-name {iothub_name} --route-name {route_name} --source devicejoblifecycleevents

Eliminare una route dell'hub IoT

Usare comando az iot hub message-route delete per eliminare una route dall'hub IoT.

L'eliminazione di una route non comporta l'eliminazione dell'endpoint perché altre route possono puntare allo stesso endpoint. Se si desidera eliminare un endpoint, l'operazione può essere eseguita separatamente dall'eliminazione di una route.

az iot hub message-route delete --hub-name {iothub_name} --route-name {route_name}

Gestire la route di fallback

La route di fallback invia tutti i messaggi dall'origine devicemessages che non soddisfano le condizioni di query su una delle route esistenti all'endpoint predefinito.

Usare il comando az iot hub message-route fallback show per visualizzare lo stato della route di fallback nell'hub IoT.

az iot hub message-route fallback show --hub-name {iothub_name}

Usare il comando az iot hub message-route fallback set per abilitare o disabilitare la route di fallback nell'hub IoT.

az iot hub message-route fallback set --hub-name {iothub_name} --enabled {true_false}

Passaggi successivi

In questo articolo di istruzioni si è appreso come creare una route e un endpoint per Hub eventi, code e argomenti del Bus di servizio e Archiviazione di Azure.

Per altre informazioni sul routing dei messaggi, vedere Esercitazione: Inviare dati dei dispositivi ad Archiviazione di Azure usando il routing dei messaggi dell'hub IoT. Nell'esercitazione viene creata una route di archiviazione che viene testata con un dispositivo nell'hub IoT.