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

Questo articolo illustra come gestire hub IoT di Azure route ed endpoint 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 bus di servizio di Azure, Archiviazione di Azure e Cosmos DB.

Per altre informazioni sul funzionamento del routing in hub IoT, vedere Usare hub IoT routing dei messaggi 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 testando in un dispositivo simulato, vedere Esercitazione: Inviare dati del dispositivo ad Archiviazione di Azure usando hub IoT routing dei messaggi.

Prerequisiti

Le procedure descritte nell'articolo usano le risorse seguenti:

• Interfaccia della riga di comando di Azure
• Un hub IoT
• Un servizio endpoint in Azure

Interfaccia della riga di comando di Azure

Questo articolo usa l'interfaccia della riga di comando di Azure per usare 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 per 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 con l'interfaccia della riga di comando di Azure.

  • Quando richiesto, installare l'estensione dell'interfaccia della riga di comando di Azure al primo uso. 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

È necessario un hub IoT nella sottoscrizione di Azure. Se non si ha ancora un hub, è possibile seguire la procedura per creare un hub IoT usando l'interfaccia della riga di comando di Azure.

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 del dispositivo e degli eventi indirizzati: 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 la procedura 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 hub IoT l'autorizzazione per inviare dati all'hub eventi.

   Suggerimento

   Il name valore RootManageSharedAccessKey del parametro è il nome predefinito che consente di gestire, inviare, ascoltare attestazioni (accesso). Per limitare le attestazioni, assegnare al name parametro il proprio nome univoco e includere il --rights flag 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 alle 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 consentirà hub IoT di 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, un argomento e una sottoscrizione del bus di servizio. Per altre informazioni, vedere Usare l'interfaccia della riga di comando di Azure per creare un argomento e sottoscrizioni del bus di servizio per l'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 con 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'istanza di Azure Cosmos DB per NoSQL.

Creare un endpoint

Tutte le route hub IoT puntano a un endpoint, che riceverà i dati del dispositivo e dell'evento indirizzati. Più route possono puntare allo stesso endpoint. Attualmente, hub IoT supporta gli endpoint per hub eventi, code o argomenti del bus di servizio, archiviazione e Cosmos DB. Prima di creare l'endpoint, un'istanza del servizio usata per l'endpoint deve esistere 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 e ancora supportato, ma non supporta la creazione di endpoint Cosmos DB.

Usare il comando seguente per eseguire l'aggiornamento alla versione più recente dell'estensione azure-iot:

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:

   parametro	Valore
   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 l'esempio è stato copiato 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:

   parametro	Valore
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Nome univoco per il nuovo endpoint.
   eventhub_subscription	ID sottoscrizione dell'hub eventi. Questo argomento può essere lasciato fuori se l'hub eventi si trova nella stessa sottoscrizione dell'hub IoT.
   eventhub_group	Gruppo di risorse dell'hub eventi. Questo argomento può essere lasciato fuori se l'hub eventi si trova nello stesso gruppo di risorse dell'hub IoT.
   eventhub_connection_string	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 list per ottenere la stringa di connessione della coda del bus di servizio. Specificare i valori seguenti per i parametri segnaposto:

   parametro	Valore
   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	Nome della regola di autorizzazione per la coda. Se l'esempio è stato copiato 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:

   parametro	Valore
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Nome univoco per il nuovo endpoint.
   queue_connection_string	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 lasciato fuori 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 lasciato fuori 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 l'elenco az servicebus topic authorization-rule keys per ottenere la stringa di connessione dell'argomento del bus di servizio. Il nome predefinito della regola di autorizzazione fornito con un nuovo spazio dei nomi è RootManageSharedAccessKey. Specificare i valori seguenti per i parametri segnaposto:

   parametro	Valore
   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:

   parametro	Valore
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Nome univoco per il nuovo endpoint.
   topic_connection_string	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 lasciato fuori 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 lasciato fuori 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:

   parametro	Valore
   storage_group	Gruppo di risorse dell'account di archiviazione.
   storage_name	Nome dell'account di archiviazione.

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

2. Copiare la stringa di connessione dell'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 lo scenario. Specificare i valori seguenti per i parametri segnaposto:

   parametro	Valore
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Nome univoco per il nuovo endpoint.
   storage_connection_string	Stringa di connessione copiata dal comando dell'account di archiviazione.
   container_name	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 lasciato fuori 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 lasciato fuori 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:

   parametro	Valore
   iothub_name	Nome dell'hub IoT in cui viene creato questo endpoint.
   endpoint_name	Nome univoco per il nuovo endpoint.
   cosmosdb_connection_string	Stringa di connessione copiata dal comando dell'account Cosmos DB.
   container_name	Nome del contenitore nell'account Cosmos DB in cui verranno inviati i dati.
   database_name	Nome del database nell'account Cosmos DB in cui verranno inviati i dati.
   cosmosdb_subscription	ID sottoscrizione dell'account del database Cosmos DB. Questo argomento può essere lasciato fuori se il database si trova nella stessa sottoscrizione dell'hub IoT.
   cosmosdb_group	Gruppo di risorse dell'account del database Cosmos DB. Questo argomento può essere lasciato fuori 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é stringa di connessione, usare il comando az cosmosdb sql role assignment create per autenticare l'identità nell'account 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

Se si vuole 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 punta alle risorse di archiviazione:

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

Creare una route hub IoT

In 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 provengono i messaggi o i log eventi. L'endpoint è il punto in cui i messaggi o i log eventi finiscono. Quando si crea una nuova route nell'hub IoT, scegliere percorsi per l'origine dati e l'endpoint. Facoltativamente, è possibile aggiungere query alle route dei messaggi per filtrare i messaggi o gli 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 hanno usato il gruppo di comandi az iot hub route , simile e ancora supportato.

Usare il comando seguente per aggiornare alla versione più recente dell'estensione azure-iot:

az extension update --name azure-iot

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

   parametro	Valore
   iothub_name	Nome dell'hub IoT in cui viene creata questa route.
   route_name	Nome univoco per la nuova route.
   endpoint_name	Nome dell'endpoint a cui verrà inviata la route.
   data_source	Origine della route. I valori accettati sono: deviceconnectionstateeventsdevicelifecycleeventsdevicemessagesdigitaltwinchangeeventsdevicejoblifecycleevents, , invalido .twinchangeevents

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

2. Per verificare che la nuova route si trova nell'hub IoT, usare il comando az iot hub message-route list per visualizzare tutte le route nell'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 hub IoT

È possibile aggiornare alcune proprietà di una route dopo la creazione. È possibile modificare lo stato di origine, endpoint, condizione o 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 hub IoT

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

L'eliminazione di una route non elimina l'endpoint perché altre route possono puntare allo stesso endpoint. Se si vuole eliminare un endpoint, è possibile farlo 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 in 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 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 del dispositivo ad Archiviazione di Azure usando hub IoT routing dei messaggi. Nell'esercitazione si crea una route di archiviazione e la si testa con un dispositivo nell'hub IoT.