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.
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.
Creare una regola di autorizzazione che verrà usata per concedere hub IoT l'autorizzazione per inviare dati all'hub eventi.
Suggerimento
Il
name
valoreRootManageSharedAccessKey
del parametro è il nome predefinito che consente di gestire, inviare, ascoltare attestazioni (accesso). Per limitare le attestazioni, assegnare alname
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.
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
Per creare un endpoint di Hub eventi, usare la regola di autorizzazione creata nei prerequisiti.
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}
Copiare la stringa di connessione dell'hub eventi dall'output.
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}
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
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: deviceconnectionstateevents
devicelifecycleevents
devicemessages
digitaltwinchangeevents
devicejoblifecycleevents
, ,invalid
o .twinchangeevents
az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}
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.