Tworzenie i usuwanie tras i punktów końcowych przy użyciu interfejsu wiersza polecenia platformy Azure

W tym artykule pokazano, jak zarządzać trasami i punktami końcowymi usługi Azure IoT Hub przy użyciu interfejsu wiersza polecenia platformy Azure. Dowiedz się, jak używać interfejsu wiersza polecenia platformy Azure do tworzenia tras i punktów końcowych dla usługi Azure Event Hubs, kolejek i tematów usługi Azure Service Bus, usługi Azure Storage i usługi Cosmos DB.

Aby dowiedzieć się więcej o sposobie działania routingu w usłudze IoT Hub, zobacz Używanie routingu komunikatów usługi IoT Hub w celu wysyłania komunikatów z urządzenia do chmury do różnych punktów końcowych. Aby zapoznać się z konfigurowaniem trasy, która wysyła komunikaty do magazynu, a następnie testowania na urządzeniu symulowanym, zobacz Samouczek: wysyłanie danych urządzenia do usługi Azure Storage przy użyciu routingu komunikatów usługi IoT Hub.

Wymagania wstępne

Procedury opisane w artykule korzystają z następujących zasobów:

• Interfejs wiersza polecenia platformy Azure
• Centrum IoT Hub.
• Usługa punktu końcowego na platformie Azure

Interfejs wiersza polecenia platformy Azure

W tym artykule użyto interfejsu wiersza polecenia platformy Azure do pracy z usługą IoT Hub i innymi usługami platformy Azure. Możesz wybrać sposób uzyskiwania dostępu do interfejsu wiersza polecenia platformy Azure:

• Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.

  

• Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.

  • Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.

  • Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.

  • Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.

Usługa IoT Hub

Masz centrum IoT Hub w ramach subskrypcji platformy Azure. Jeśli nie masz jeszcze centrum, możesz wykonać kroki opisane w temacie Tworzenie centrum IoT Hub.

Usługa punktu końcowego

Musisz użyć co najmniej jednej innej usługi platformy Azure jako punktu końcowego do trasy. Punkt końcowy odbiera komunikaty urządzenia i dzienniki zdarzeń.

Zdecyduj, która usługa platformy Azure ma być używana jako punkt końcowy do odbierania danych zdarzeń i urządzeń kierowanych: centrum zdarzeń, kolejki usługi lub tematu, konta magazynu lub kontenera usługi Cosmos DB. W przypadku usługi, której chcesz użyć, wykonaj kroki tworzenia usługi punktu końcowego.

Event Hubs

1. Utwórz przestrzeń nazw usługi Event Hubs i centrum zdarzeń. Aby uzyskać więcej informacji, zobacz Szybki start: tworzenie centrum zdarzeń przy użyciu interfejsu wiersza polecenia platformy Azure.

2. Utwórz regułę autoryzacji, która będzie używana do nadawania usłudze IoT Hub uprawnień do wysyłania danych do centrum zdarzeń.

   Napiwek

   Wartość name RootManageSharedAccessKey parametru jest nazwą domyślną, która zezwala na zarządzanie, wysyłanie, nasłuchiwanie oświadczeń (dostęp). Jeśli chcesz ograniczyć oświadczenia, nadaj name parametrowi własną unikatową nazwę i dołącz flagę --rights , po której następuje jedna z oświadczeń. Na przykład --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
   

   Aby uzyskać więcej informacji, zobacz Autoryzowanie dostępu do usługi Azure Event Hubs.

Kolejka usługi Service Bus

1. Utwórz przestrzeń nazw i kolejkę usługi Service Bus. Aby uzyskać więcej informacji, zobacz Tworzenie przestrzeni nazw usługi Service Bus i kolejki przy użyciu interfejsu wiersza polecenia platformy Azure.

2. Utwórz regułę autoryzacji, która da usłudze IoT Hub uprawnienie do wysyłania danych do kolejki. W przypadku nameprogramu użyj unikatowej wartości dla reguły autoryzacji.

   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
   

   Aby uzyskać więcej opcji reguły autoryzacji, zobacz az servicebus queue authorization-rule create.

Temat usługi Service Bus

Utwórz przestrzeń nazw, temat i subskrypcję usługi Service Bus. Aby uzyskać więcej informacji, zobacz Tworzenie tematu i subskrypcji usługi Service Bus przy użyciu interfejsu wiersza polecenia platformy Azure.

Azure Storage

1. Create a storage account (Tworzenie konta magazynu). Aby uzyskać więcej informacji, zobacz temat Tworzenie konta.

2. Utwórz kontener na koncie magazynu. Aby uzyskać więcej informacji, zobacz Zarządzanie kontenerami obiektów blob przy użyciu interfejsu wiersza polecenia platformy Azure

Cosmos DB

Utwórz konto usługi Cosmos DB dla interfejsu API SQL i kontenera usługi Cosmos DB. Aby uzyskać więcej informacji, zobacz Tworzenie usługi Azure Cosmos DB for NoSQL.

Tworzenie punktu końcowego

Wszystkie trasy usługi IoT Hub wskazują punkt końcowy, który będzie otrzymywać dane kierowanego urządzenia i zdarzenia. Więcej niż jedna trasa może wskazywać ten sam punkt końcowy. Obecnie usługa IoT Hub obsługuje punkty końcowe dla centrów zdarzeń, kolejek lub tematów usługi Service Bus, usługi Storage i Cosmos DB. Wystąpienie usługi używanej dla punktu końcowego musi istnieć w subskrypcji platformy Azure przed utworzeniem punktu końcowego.

Uwaga

W tym artykule użyto grupy poleceń az iot hub message-endpoint , która została wprowadzona w wersji 0.19.0 rozszerzenia azure-iot dla interfejsu wiersza polecenia platformy Azure. Poprzednie wersje rozszerzenia azure-iot używały grupy poleceń az iot hub routing-endpoint , która jest podobna i nadal obsługiwana, ale nie obsługuje tworzenia punktów końcowych usługi Cosmos DB.

Użyj następującego polecenia, aby zaktualizować do najnowszej wersji rozszerzenia azure-iot:

az extension update --name azure-iot

Event Hubs

Aby utworzyć punkt końcowy usługi Event Hubs, użyj reguły autoryzacji utworzonej w wymaganiach wstępnych.

1. Użyj polecenia az eventhubs eventhub authorization-rule keys list, aby wyświetlić listę reguł autoryzacji. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   eventhub_group	Grupa zasobów centrum zdarzeń.
   eventhub_namespace	Nazwa przestrzeni nazw usługi Event Hubs.
   eventhub_name	Nazwa centrum zdarzeń.
   rule_name	Nazwa reguły autoryzacji dla centrum zdarzeń. Jeśli skopiowano przykład w wymaganiach wstępnych, ta nazwa to 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. Skopiuj parametry połączenia centrum zdarzeń z danych wyjściowych.

3. Użyj polecenia az iot hub message-endpoint create eventhub, aby utworzyć niestandardowy punkt końcowy. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   iothub_name	Nazwa centrum IoT, w którym jest tworzony ten punkt końcowy.
   endpoint_name	Unikatowa nazwa nowego punktu końcowego.
   eventhub_subscription	Identyfikator subskrypcji centrum zdarzeń. Ten argument można pominąć, jeśli centrum zdarzeń znajduje się w tej samej subskrypcji co centrum IoT.
   eventhub_group	Grupa zasobów centrum zdarzeń. Ten argument można pominąć, jeśli centrum zdarzeń znajduje się w tej samej grupie zasobów co centrum IoT.
   eventhub_connection_string	Parametry połączenia skopiowane z reguły autoryzacji centrum zdarzeń.

   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}
   

Kolejka usługi Service Bus

Aby utworzyć punkt końcowy kolejki usługi Service Bus, użyj reguły autoryzacji utworzonej w wymaganiach wstępnych.

1. Użyj polecenia az servicebus queue authorization-rule keys list, aby uzyskać parametry połączenia kolejki usługi Service Bus. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   queue_group	Grupa zasobów kolejki usługi Service Bus.
   queue_namespace	Nazwa przestrzeni nazw kolejki usługi Service Bus.
   queue_name	Nazwa kolejki.
   rule_name	Nazwa reguły autoryzacji dla kolejki. Jeśli skopiowano przykład w wymaganiach wstępnych, ta nazwa to 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. Skopiuj parametry połączenia kolejki usługi Service Bus z danych wyjściowych.

3. Użyj polecenia az iot hub message-endpoint create servicebus-queue, aby utworzyć niestandardowy punkt końcowy. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   iothub_name	Nazwa centrum IoT, w którym jest tworzony ten punkt końcowy.
   endpoint_name	Unikatowa nazwa nowego punktu końcowego.
   queue_connection_string	Parametry połączenia skopiowane z reguły autoryzacji kolejki usługi Service Bus.
   queue_subscription	Identyfikator subskrypcji kolejki usługi Service Bus. Ten argument można pominąć, jeśli kolejka znajduje się w tej samej subskrypcji co centrum IoT.
   queue_group	Grupa zasobów kolejki usługi Service Bus. Ten argument można pominąć, jeśli kolejka znajduje się w tej samej grupie zasobów co centrum 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}
   

Temat usługi Service Bus

1. Użyj listy az servicebus topic authorization-rule keys (Klucze reguł autoryzacji tematu az servicebus), aby uzyskać parametry połączenia tematu usługi Service Bus. Domyślną nazwą reguły autoryzacji, która jest dostarczana z nową przestrzenią nazw, jest RootManageSharedAccessKey. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   topic_group	Grupa zasobów tematu usługi Service Bus.
   topic_namespace	Nazwa przestrzeni nazw tematu usługi Service Bus.
   topic_name	Nazwa tematu.

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

2. Skopiuj temat usługi Service Bus parametry połączenia z danych wyjściowych.

3. Użyj polecenia az iot hub message-endpoint create servicebus-topic, aby utworzyć niestandardowy punkt końcowy. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   iothub_name	Nazwa centrum IoT, w którym jest tworzony ten punkt końcowy.
   endpoint_name	Unikatowa nazwa nowego punktu końcowego.
   topic_connection_string	Parametry połączenia skopiowany z reguły autoryzacji tematu usługi Service Bus.
   topic_subscription	Identyfikator subskrypcji tematu usługi Service Bus. Ten argument można pominąć, jeśli temat znajduje się w tej samej subskrypcji co centrum IoT.
   topic_group	Grupa zasobów tematu usługi Service Bus. Ten argument można pominąć, jeśli temat znajduje się w tej samej grupie zasobów co centrum 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}
   

Azure Storage

1. Użyj polecenia az storage account show-connection-string, aby uzyskać parametry połączenia z zasobu usługi Azure Storage w celu utworzenia punktu końcowego. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   storage_group	Grupa zasobów konta magazynu.
   storage_name	Nazwa konta magazynu

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

2. Skopiuj konto magazynu parametry połączenia z danych wyjściowych.

3. Użyj polecenia az iot hub message-endpoint create storage-container, aby utworzyć nowy punkt końcowy usługi Azure Storage. Dla wszystkich innych parametrów użyj wartości dla danego scenariusza. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   iothub_name	Nazwa centrum IoT, w którym jest tworzony ten punkt końcowy.
   endpoint_name	Unikatowa nazwa nowego punktu końcowego.
   storage_connection_string	Parametry połączenia skopiowany z polecenia konta magazynu.
   container_name	Nazwa kontenera na koncie magazynu, na którym będą wysyłane dane.
   storage_subscription	Identyfikator subskrypcji magazynu usługi Service Bus. Ten argument można pominąć, jeśli magazyn znajduje się w tej samej subskrypcji co centrum IoT.
   storage_group	Grupa zasobów magazynu usługi Service Bus. Ten argument można pominąć, jeśli temat znajduje się w tej samej grupie zasobów co centrum 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. Użyj polecenia az cosmosdb keys list, aby pobrać parametry połączenia z konta bazy danych usługi Cosmos DB.

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

2. Skopiuj parametry połączenia usługi Cosmos DB z danych wyjściowych.

3. Użyj polecenia az iot hub message-endpoint create cosmosdb-container, aby utworzyć niestandardowy punkt końcowy. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   iothub_name	Nazwa centrum IoT, w którym jest tworzony ten punkt końcowy.
   endpoint_name	Unikatowa nazwa nowego punktu końcowego.
   cosmosdb_connection_string	Parametry połączenia skopiowany z polecenia konta usługi Cosmos DB.
   container_name	Nazwa kontenera na koncie usługi Cosmos DB, na którym będą wysyłane dane.
   database_name	Nazwa bazy danych na koncie usługi Cosmos DB, na którym będą wysyłane dane.
   cosmosdb_subscription	Identyfikator subskrypcji konta bazy danych usługi Cosmos DB. Ten argument można pominąć, jeśli baza danych znajduje się w tej samej subskrypcji co centrum IoT.
   cosmosdb_group	Grupa zasobów konta bazy danych usługi Cosmos DB. Ten argument można pominąć, jeśli baza danych znajduje się w tej samej grupie zasobów co centrum 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
   

   Uwaga

   Jeśli używasz tożsamości zarządzanych zamiast parametry połączenia, użyj polecenia az cosmosdb sql role assignment create, aby uwierzytelnić swoją tożsamość na koncie usługi 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"
   

Usuwanie punktu końcowego

Jeśli chcesz usunąć punkt końcowy z centrum IoT Hub, użyj polecenia az iot hub message-endpoint delete . Za pomocą tego polecenia można usunąć pojedynczy punkt końcowy, usunąć wszystkie punkty końcowe jednego typu lub usunąć wszystkie punkty końcowe z centrum.

Na przykład następujące polecenie usuwa wszystkie punkty końcowe w centrum IoT Hub, które wskazują na zasoby usługi Storage:

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

Tworzenie trasy usługi IoT Hub

W usłudze IoT Hub możesz utworzyć trasę do wysyłania komunikatów lub przechwytywania zdarzeń. Każda trasa ma źródło danych i punkt końcowy. Źródło danych to miejsce, z którego pochodzą komunikaty lub dzienniki zdarzeń. Punkt końcowy to miejsce, w którym kończą się komunikaty lub dzienniki zdarzeń. Lokalizacje źródła danych i punktu końcowego są wybierane podczas tworzenia nowej trasy w centrum IoT. Opcjonalnie możesz dodać zapytania do tras komunikatów w celu filtrowania komunikatów lub zdarzeń przed przejściem do punktu końcowego.

Uwaga

W tym artykule użyto grupy poleceń az iot hub message-route , która została wprowadzona w wersji 0.19.0 rozszerzenia azure-iot dla interfejsu wiersza polecenia platformy Azure. Poprzednie wersje rozszerzenia azure-iot używały grupy poleceń az iot hub route , która jest podobna i nadal obsługiwana.

Użyj następującego polecenia, aby zaktualizować do najnowszej wersji rozszerzenia azure-iot:

az extension update --name azure-iot

1. Użyj polecenia az iot hub message-route create, aby utworzyć nową trasę usługi IoT Hub przy użyciu tego punktu końcowego. Podaj następujące wartości dla parametrów symbolu zastępczego:

   parametr	wartość
   iothub_name	Nazwa centrum IoT, w którym jest tworzona ta trasa.
   route_name	Unikatowa nazwa nowej trasy.
   endpoint_name	Nazwa punktu końcowego, do którego trasa będzie wysyłać dane.
   data_source	Źródło trasy. Akceptowane wartości to: deviceconnectionstateevents, , devicejoblifecycleevents, devicemessagesdevicelifecycleevents, digitaltwinchangeevents, , invalidlub twinchangeevents.

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

2. Aby potwierdzić, że nowa trasa znajduje się w centrum IoT Hub, użyj polecenia az iot hub message-route list , aby wyświetlić wszystkie trasy w centrum IoT:

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

   W interfejsie wiersza polecenia platformy Azure powinna zostać wyświetlona odpowiedź podobna do tego przykładu:

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

Aktualizowanie trasy usługi IoT Hub

Niektóre właściwości trasy można zaktualizować po jej utworzeniu. Możesz zmienić źródło, punkt końcowy, warunek lub włączony stan istniejącej trasy.

Użyj polecenia az iot hub message-route show, aby wyświetlić szczegóły trasy.

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

Użyj polecenia az iot hub message-route update, aby zaktualizować właściwości trasy. Na przykład następujące polecenie aktualizuje źródło trasy.

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

Usuwanie trasy usługi IoT Hub

Użyj polecenia az iot hub message-route delete, aby usunąć trasę z centrum IoT Hub.

Usunięcie trasy nie powoduje usunięcia punktu końcowego, ponieważ inne trasy mogą wskazywać ten sam punkt końcowy. Jeśli chcesz usunąć punkt końcowy, możesz to zrobić niezależnie od usuwania trasy.

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

Zarządzanie trasą rezerwową

Trasa rezerwowa wysyła wszystkie komunikaty ze devicemessages źródła, które nie spełniają warunków zapytania w żadnej z istniejących tras do wbudowanego punktu końcowego.

Użyj polecenia az iot hub message-route fallback show, aby wyświetlić stan trasy rezerwowej w centrum IoT.

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

Użyj polecenia az iot hub message-route fallback set, aby włączyć lub wyłączyć trasę rezerwową w centrum IoT.

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

Następne kroki

W tym artykule z instrukcjami przedstawiono sposób tworzenia trasy i punktu końcowego dla usługi Event Hubs, kolejek i tematów usługi Service Bus oraz usługi Azure Storage.

Aby dowiedzieć się więcej na temat routingu komunikatów, zobacz Samouczek: wysyłanie danych urządzenia do usługi Azure Storage przy użyciu routingu komunikatów usługi IoT Hub. W tym samouczku utworzysz trasę magazynu i przetestujesz ją za pomocą urządzenia w centrum IoT.