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

W tym artykule przedstawiono sposób zarządzania trasami i punktami końcowymi 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 Azure Event Hubs, kolejek i tematów Azure Service Bus, usługi Azure Storage i usługi Cosmos DB.

Aby dowiedzieć się więcej na temat sposobu działania routingu w IoT Hub, zobacz Używanie routingu komunikatów IoT Hub do 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 symulowanym urządzeniu, zobacz Samouczek: wysyłanie danych urządzenia do usługi Azure Storage przy użyciu routingu komunikatów 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 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 przy pierwszym użyciu. 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

Potrzebujesz centrum IoT w ramach subskrypcji platformy Azure. Jeśli nie masz jeszcze centrum, możesz wykonać kroki tworzenia centrum IoT Przy użyciu interfejsu wiersza polecenia platformy Azure.

Usługa punktu końcowego

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

Zdecyduj, której usługi platformy Azure chcesz użyć jako punktu końcowego do odbierania kierowanych danych urządzenia i zdarzeń: centrum zdarzeń, kolejki usługi lub tematu, konta magazynu lub kontenera usługi Cosmos DB. W przypadku wybranej usługi 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 udzielania IoT Hub uprawnień do wysyłania danych do centrum zdarzeń.

   Porada

   Wartość nameRootManageSharedAccessKey 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 , a następnie jedną 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 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 za pomocą interfejsu wiersza polecenia platformy Azure.

2. Utwórz regułę autoryzacji, która da IoT Hub uprawnienia do wysyłania danych do kolejki. W przypadku nameprogramu użyj unikatowej wartości 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. 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 IoT Hub trasy wskazują punkt końcowy, który będzie odbierał kierowane urządzenie i dane zdarzenia. Więcej niż jedna trasa może wskazywać ten sam punkt końcowy. Obecnie IoT Hub obsługuje punkty końcowe dla centrów zdarzeń, kolejek usługi Service Bus lub tematów, magazynu i usługi 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 przykład został skopiowany 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 przykład został skopiowany 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 ,aby uzyskać parametry połączenia tematu usługi Service Bus. Domyślna nazwa reguły autoryzacji, która jest dostarczana z nową przestrzenią nazw, to 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 parametry połączenia tematu usługi Service Bus 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 skopiowane 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 pobrać 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 parametry połączenia konta magazynu 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 skopiowane 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 skopiowane 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.
   Nazwa_bazy_danych	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 parametrów 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, 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 pojedynczego typu lub usunąć wszystkie punkty końcowe z centrum.

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

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

Tworzenie trasy IoT Hub

W IoT Hub można utworzyć trasę służącą 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, aby filtrować komunikaty lub zdarzenia 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ę 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 będzie wysyłana trasa.
   Data_source	Źródło trasy. Akceptowane wartości to: deviceconnectionstateevents, , devicelifecycleeventsdevicejoblifecycleeventsdigitaltwinchangeeventsdevicemessages, 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, 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 IoT Hub

Niektóre właściwości trasy można zaktualizować po jej utworzeniu. Możesz zmienić stan źródła, punktu końcowego, warunku lub włączonego 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 IoT Hub

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

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 zobaczyć 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 IoT Hub. W samouczku utworzysz trasę magazynu i przetestujesz ją za pomocą urządzenia w centrum IoT.