Skapa och ta bort vägar och slutpunkter med hjälp av Azure CLI

Artikel
06/01/2023

Den här artikeln visar hur du hanterar Azure IoT Hub vägar och slutpunkter med hjälp av Azure CLI. Lär dig hur du använder Azure CLI för att skapa vägar och slutpunkter för Azure Event Hubs, Azure Service Bus köer och ämnen, Azure Storage och Cosmos DB.

Mer information om hur routning fungerar i IoT Hub finns i Använda IoT Hub meddelanderoutning för att skicka meddelanden från enheten till molnet till olika slutpunkter. Information om hur du konfigurerar en väg som skickar meddelanden till lagring och sedan testar på en simulerad enhet finns i Självstudie: Skicka enhetsdata till Azure Storage med hjälp av IoT Hub meddelandedirigering.

Förutsättningar

De procedurer som beskrivs i artikeln använder följande resurser:

Azure CLI
En IoT Hub
En slutpunktstjänst i Azure

Azure CLI

Den här artikeln använder Azure CLI för att arbeta med IoT Hub och andra Azure-tjänster. Du kan välja hur du ska komma åt Azure CLI:

Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.
Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.
- Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.
- När du uppmanas att göra det installerar du Azure CLI-tillägget vid första användning. Mer information om tillägg finns i Använda tillägg med Azure CLI.
- Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

IoT Hub

Du behöver en IoT-hubb i din Azure-prenumeration. Om du inte har någon hubb ännu kan du följa stegen för att skapa en IoT-hubb med hjälp av Azure CLI.

Slutpunktstjänst

Du behöver minst en annan Azure-tjänst som ska användas som slutpunkt för vägen. Slutpunkten tar emot enhetsmeddelanden och händelseloggar.

Bestäm vilken Azure-tjänst du vill använda som slutpunkt för att ta emot dirigerade enhets- och händelsedata: en händelsehubb, en tjänstkö eller ett ämne, ett lagringskonto eller en Cosmos DB-container. För den tjänst som du väljer att använda slutför du stegen för att skapa en slutpunktstjänst.

Skapa ett Event Hubs-namnområde och en händelsehubb. Mer information finns i Snabbstart: Skapa en händelsehubb med hjälp av Azure CLI.
Skapa en auktoriseringsregel som ska användas för att ge IoT Hub behörighet att skicka data till händelsehubben.

Tips

Parameterns name värde RootManageSharedAccessKey är standardnamnet som tillåter hantera, skicka, lyssna anspråk (åtkomst). Om du vill begränsa anspråken ger du parametern name ditt eget unika namn och inkluderar --rights flaggan följt av ett av anspråken. Till exempel --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
```
Mer information finns i Auktorisera åtkomst till Azure Event Hubs.

Skapa ett namnområde och en kö för Service Bus. Mer information finns i Använda Azure CLI för att skapa ett Service Bus-namnområde och en kö.
Skapa en auktoriseringsregel som ger IoT Hub behörighet att skicka data till kön. För nameanvänder du ett unikt värde för din auktoriseringsregel.
```
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
```
Fler alternativ för auktoriseringsregler finns i az servicebus queue authorization-rule create.

Skapa en slutpunkt

Alla IoT Hub vägar pekar på en slutpunkt, som tar emot dirigerade enhets- och händelsedata. Mer än en väg kan peka på samma slutpunkt. För närvarande stöder IoT Hub slutpunkter för händelsehubbar, Service Bus-köer eller -ämnen, Storage och Cosmos DB. En instans av tjänsten som du använder för slutpunkten måste finnas i din Azure-prenumeration innan du skapar slutpunkten.

Anteckning

Den här artikeln använder kommandogruppen az iot hub message-endpoint , som introducerades i version 0.19.0 av azure-iot-tillägget för Azure CLI. Tidigare versioner av azure-iot-tillägget använde kommandogruppen az iot hub routing-endpoint , som är liknande och fortfarande stöds men inte har stöd för att skapa Cosmos DB-slutpunkter.

Använd följande kommando för att uppdatera till den senaste versionen av azure-iot-tillägget:

az extension update --name azure-iot

Om du vill skapa en Event Hubs-slutpunkt använder du auktoriseringsregeln som du skapade i förutsättningarna.

Använd kommandot az eventhubs eventhub authorization-rule keys list för att lista din auktoriseringsregel. Ange följande värden för platshållarparametrarna:

parameter	värde
eventhub_group	Resursgrupp för händelsehubben.
eventhub_namespace	Namn på Event Hubs-namnområdet.
eventhub_name	Namnet på händelsehubben.
rule_name	Namnet på auktoriseringsregeln för händelsehubben. Om du kopierade exemplet i förhandskraven är `RootManageSharedAccessKey`det här namnet .

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

Kopiera händelsehubbens anslutningssträng från utdata.

Använd kommandot az iot hub message-endpoint create eventhub för att skapa din anpassade slutpunkt. Ange följande värden för platshållarparametrarna:

parameter	värde
iothub_name	Namnet på den IoT-hubb där den här slutpunkten skapas.
endpoint_name	Ett unikt namn för den nya slutpunkten.
eventhub_subscription	Prenumerations-ID för händelsehubben. Det här argumentet kan utelämnas om händelsehubben finns i samma prenumeration som IoT-hubben.
eventhub_group	Resursgrupp för händelsehubben. Det här argumentet kan utelämnas om händelsehubben finns i samma resursgrupp som IoT-hubben.
eventhub_connection_string	Anslutningssträngen som du kopierade från händelsehubbens auktoriseringsregel.

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}

Om du vill skapa en Service Bus-köslutpunkt använder du auktoriseringsregeln som du skapade i förhandskraven.

Använd kommandot az servicebus queue authorization-rule keys list för att hämta anslutningssträngen för Service Bus-kön. Ange följande värden för platshållarparametrarna:

parameter	värde
queue_group	Resursgrupp för Service Bus-kön.
queue_namespace	Namn på Service Bus-könamnområdet.
queue_name	Namnet på kön.
rule_name	Namnet på auktoriseringsregeln för kön. Om du kopierade exemplet i förhandskraven är `my-auth-rule`det här namnet .

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

Kopiera anslutningssträngen för Service Bus-kön från utdata.

Använd kommandot az iot hub message-endpoint create servicebus-queue för att skapa din anpassade slutpunkt. Ange följande värden för platshållarparametrarna:

parameter	värde
iothub_name	Namnet på den IoT-hubb där den här slutpunkten skapas.
endpoint_name	Ett unikt namn för den nya slutpunkten.
queue_connection_string	Anslutningssträngen som du kopierade från Service Bus-köauktoriseringsregeln.
queue_subscription	Prenumerations-ID för Service Bus-kön. Det här argumentet kan utelämnas om kön finns i samma prenumeration som IoT-hubben.
queue_group	Resursgrupp för Service Bus-kön. Det här argumentet kan utelämnas om kön finns i samma resursgrupp som IoT-hubben.

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}

Använd listan az servicebus topic authorization-rule keys för att hämta anslutningssträngen för Service Bus-ämnet. Standardnamnet för auktoriseringsregeln som medföljer ett nytt namnområde är RootManageSharedAccessKey. Ange följande värden för platshållarparametrarna:

parameter värde

topic_group Resursgrupp för Service Bus-ämnet.

topic_namespace Namn på namnområdet för Service Bus-ämnet.

topic_name Namnet på ämnet.
```
az servicebus topic authorization-rule keys list --resource-group {topic_group} --namespace-name {topic_namespace} --topic-name {topic_name} --name RootManageSharedAccessKey
```
Kopiera anslutningssträngen för Service Bus-ämnet från utdata.

parameter	värde
topic_group	Resursgrupp för Service Bus-ämnet.
topic_namespace	Namn på namnområdet för Service Bus-ämnet.
topic_name	Namnet på ämnet.

Använd kommandot az iot hub message-endpoint create servicebus-topic för att skapa din anpassade slutpunkt. Ange följande värden för platshållarparametrarna:

parameter	värde
iothub_name	Namnet på den IoT-hubb där den här slutpunkten skapas.
endpoint_name	Ett unikt namn för den nya slutpunkten.
topic_connection_string	Anslutningssträngen som du kopierade från auktoriseringsregeln för Service Bus-ämnet.
topic_subscription	Prenumerations-ID för Service Bus-ämnet. Det här argumentet kan utelämnas om ämnet finns i samma prenumeration som IoT-hubben.
topic_group	Resursgrupp för Service Bus-ämnet. Det här argumentet kan utelämnas om ämnet finns i samma resursgrupp som IoT-hubben.

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}

Använd kommandot az storage account show-connection-string för att hämta anslutningssträngen från Azure Storage-resursen för att skapa en slutpunkt. Ange följande värden för platshållarparametrarna:

parameter värde

storage_group Resursgrupp för lagringskontot.

storage_name Namn på lagringskontot.
```
az storage account show-connection-string --resource-group my-resource-group --name my-storage-account 
```
Kopiera anslutningssträngen för lagringskontot från utdata.

parameter	värde
storage_group	Resursgrupp för lagringskontot.
storage_name	Namn på lagringskontot.

Använd kommandot az iot hub message-endpoint create storage-container för att skapa en ny Azure Storage-slutpunkt. Använd värden för ditt scenario för alla andra parametrar. Ange följande värden för platshållarparametrarna:

parameter	värde
iothub_name	Namnet på den IoT-hubb där den här slutpunkten skapas.
endpoint_name	Ett unikt namn för den nya slutpunkten.
storage_connection_string	Anslutningssträngen som du kopierade från lagringskontokommandot.
container_name	Namnet på containern i lagringskontot där data skickas.
storage_subscription	Prenumerations-ID för Service Bus-lagringen. Det här argumentet kan utelämnas om lagringen finns i samma prenumeration som IoT-hubben.
storage_group	Resursgrupp för Service Bus-lagringen. Det här argumentet kan utelämnas om ämnet finns i samma resursgrupp som IoT-hubben.

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}

Använd kommandot az cosmosdb keys list för att hämta anslutningssträngen från ditt Cosmos DB-databaskonto.

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

Kopiera Cosmos DB-anslutningssträngen från utdata.

Använd kommandot az iot hub message-endpoint create cosmosdb-container för att skapa din anpassade slutpunkt. Ange följande värden för platshållarparametrarna:

parameter	värde
iothub_name	Namnet på den IoT-hubb där den här slutpunkten skapas.
endpoint_name	Ett unikt namn för den nya slutpunkten.
cosmosdb_connection_string	Anslutningssträngen som du kopierade från Cosmos DB-kontokommandot.
container_name	Namnet på containern i ditt Cosmos DB-konto där data skickas.
database_name	Namnet på databasen i ditt Cosmos DB-konto där data skickas.
cosmosdb_subscription	Prenumerations-ID för Cosmos DB-databaskontot. Det här argumentet kan utelämnas om databasen finns i samma prenumeration som IoT-hubben.
cosmosdb_group	Resursgrupp för Cosmos DB-databaskontot. Det här argumentet kan utelämnas om databasen finns i samma resursgrupp som IoT-hubben.

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

Anteckning

Om du använder hanterade identiteter i stället för anslutningssträngen använder du kommandot az cosmosdb sql role assignment create för att autentisera din identitet till Cosmos DB-kontot.

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"

Ta bort en slutpunkt

Om du vill ta bort en slutpunkt från din IoT-hubb använder du kommandot az iot hub message-endpoint delete . Med det här kommandot kan du ta bort en enda slutpunkt, ta bort alla slutpunkter av en enda typ eller ta bort alla slutpunkter från en hubb.

Följande kommando tar till exempel bort alla slutpunkter i en IoT-hubb som pekar på Lagringsresurser:

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

Skapa en IoT Hub väg

I IoT Hub kan du skapa en väg för att skicka meddelanden eller avbilda händelser. Varje väg har en datakälla och en slutpunkt. Datakällan är den där meddelanden eller händelseloggar kommer från. Slutpunkten är där meddelandena eller händelseloggarna hamnar. Du väljer platser för datakällan och slutpunkten när du skapar en ny väg i din IoT-hubb. Du kan också lägga till frågor i meddelandevägar för att filtrera meddelanden eller händelser innan de går till slutpunkten.

Anteckning

Den här artikeln använder kommandogruppen az iot hub message-route , som introducerades i version 0.19.0 av azure-iot-tillägget för Azure CLI. Tidigare versioner av azure-iot-tillägget använde kommandogruppen az iot hub route , som är liknande och fortfarande stöds.

Använd följande kommando för att uppdatera till den senaste versionen av azure-iot-tillägget:

az extension update --name azure-iot

Använd kommandot az iot hub message-route create för att skapa en ny IoT Hub väg med hjälp av den slutpunkten. Ange följande värden för platshållarparametrarna:

parameter	värde
iothub_name	Namnet på den IoT-hubb där den här vägen skapas.
route_name	Ett unikt namn för den nya vägen.
endpoint_name	Namnet på den slutpunkt som vägen ska skicka data till.
data_source	Vägens källa. Godkända värden är: `deviceconnectionstateevents`, `devicejoblifecycleevents`, `devicelifecycleevents`, `devicemessages`, `digitaltwinchangeevents`, `invalid`eller `twinchangeevents`.

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

För att bekräfta att den nya vägen finns i din IoT-hubb använder du kommandot az iot hub message-route list för att se alla vägar i din IoT-hubb:

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

Du bör se ett svar i Azure CLI som liknar det här exemplet:

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

Uppdatera en IoT Hub väg

Du kan uppdatera vissa egenskaper för en väg när den har skapats. Du kan ändra källan, slutpunkten, villkoret eller det aktiverade tillståndet för en befintlig väg.

Använd kommandot az iot hub message-route show för att visa information om en väg.

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

Använd kommandot az iot hub message-route update för att uppdatera egenskaperna för en väg. Följande kommando uppdaterar till exempel vägens källa.

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

Ta bort en IoT Hub väg

Använd kommandot az iot hub message-route delete för att ta bort en väg från din IoT-hubb.

Om du tar bort en väg tas inte dess slutpunkt bort eftersom andra vägar kan peka på samma slutpunkt. Om du vill ta bort en slutpunkt kan du göra det separat från att ta bort en väg.

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

Hantera återställningsvägen

Återställningsvägen skickar alla meddelanden från devicemessages källan som inte uppfyller frågevillkoren på någon av de befintliga vägarna till den inbyggda slutpunkten.

Använd kommandot az iot hub message-route fallback show för att se status för återställningsvägen i din IoT-hubb.

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

Använd kommandot az iot hub message-route fallback set för att aktivera eller inaktivera återställningsvägen i din IoT-hubb.

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

Nästa steg

I den här artikeln har du lärt dig hur du skapar en väg och en slutpunkt för Event Hubs, Service Bus-köer och -ämnen samt Azure Storage.

Mer information om meddelanderoutning finns i Självstudie: Skicka enhetsdata till Azure Storage med hjälp av IoT Hub meddelanderoutning. I självstudien skapar du en lagringsväg och testar den med en enhet i din IoT-hubb.

Skapa och ta bort vägar och slutpunkter med hjälp av Azure CLI

Förutsättningar

Azure CLI

IoT Hub

Slutpunktstjänst

Skapa en slutpunkt

Ta bort en slutpunkt

Skapa en IoT Hub väg

Uppdatera en IoT Hub väg

Ta bort en IoT Hub väg

Hantera återställningsvägen

Nästa steg

Ytterligare resurser