Samouczek: wysyłanie danych urządzenia do usługi Azure Storage przy użyciu routingu komunikatów usługi IoT Hub

Routing komunikatów w usłudze Azure IoT Hub umożliwia wysyłanie danych telemetrycznych z urządzeń IoT do usług platformy Azure, takich jak magazyn obiektów blob, kolejki usługi Service Bus, tematy usługi Service Bus i event hubs. Każde centrum IoT ma domyślny wbudowany punkt końcowy zgodny z usługą Event Hubs. Możesz również utworzyć niestandardowe punkty końcowe i kierować komunikaty do innych usług platformy Azure, definiując zapytania routingu. Każdy komunikat docierający do centrum IoT jest kierowany do wszystkich punktów końcowych, których zapytania dotyczące routingu są zgodne. Jeśli komunikat nie jest zgodny z żadnym ze zdefiniowanych zapytań routingu, jest kierowany do domyślnego punktu końcowego.

Ten samouczek obejmuje wykonanie następujących zadań:

• Utwórz centrum IoT Hub i wyślij do niego komunikaty urządzenia.
• Create a storage account (Tworzenie konta magazynu).
• Utwórz niestandardowy punkt końcowy dla konta magazynu i skierować do niego komunikaty z centrum IoT Hub.
• Wyświetlanie komunikatów urządzenia w obiekcie blob konta magazynu.

Wymagania wstępne

• Subskrypcja platformy Azure. Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

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

• W tym samouczku jest używany przykładowy kod z zestawu Azure IoT SDK dla języka C#.

  • Pobierz lub sklonuj repozytorium zestawu SDK na maszynę dewelopera.
  • Platforma .NET Core 3.0.0 lub nowsza na maszynie dewelopera. Sprawdź swoją wersję, uruchamiając dotnet --version polecenie i pobierz platformę .NET , jeśli to konieczne.

• Upewnij się, że port 8883 jest otwarty w zaporze. Przykład w tym samouczku używa protokołu MQTT, który komunikuje się za pośrednictwem portu 8883. Ten port może zostać zablokowany w niektórych środowiskach sieci firmowych i edukacyjnych. Aby uzyskać więcej informacji i sposobów obejścia tego problemu, zobacz Nawiązywanie połączenia z usługą IoT Hub (MQTT).

• Opcjonalnie zainstaluj narzędzie Azure IoT Explorer. To narzędzie ułatwia obserwowanie komunikatów podczas ich docierania do centrum IoT Hub. W tym artykule jest używany program Azure IoT Explorer.

Witryna Azure Portal

W witrynie Azure Portal nie ma żadnych innych wymagań wstępnych.

Interfejs 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.

Rejestrowanie urządzenia i wysyłanie komunikatów do usługi IoT Hub

Zarejestruj nowe urządzenie w centrum IoT.

Ważne

Ten artykuł zawiera kroki łączenia urządzenia przy użyciu sygnatury dostępu współdzielonego, nazywanej również uwierzytelnianiem klucza symetrycznego. Ta metoda uwierzytelniania jest wygodna do testowania i oceny, ale uwierzytelnianie urządzenia przy użyciu certyfikatów X.509 jest bardziej bezpieczne. Aby dowiedzieć się więcej, zobacz Zabezpieczenia najlepszych rozwiązań > zabezpieczeń Zabezpieczenia zabezpieczeń Zabezpieczenia zabezpieczeń.

Witryna Azure Portal

1. Zaloguj się do witryny Azure Portal i przejdź do centrum IoT Hub.

2. Wybierz pozycję Urządzenia w sekcji Zarządzanie urządzeniami w menu.

3. Wybierz pozycję Dodaj urządzenie.

   

4. Podaj identyfikator urządzenia i wybierz pozycję Zapisz.

5. Nowe urządzenie powinno teraz znajdować się na liście urządzeń. Jeśli tak nie jest, odśwież stronę. Wybierz identyfikator urządzenia, aby otworzyć stronę szczegółów urządzenia.

6. Skopiuj jeden z kluczy urządzenia i zapisz go. Użyjesz tej wartości do skonfigurowania przykładowego kodu, który generuje symulowane komunikaty telemetryczne urządzenia.

   

Interfejs wiersza polecenia platformy Azure

Napiwek

Wiele poleceń interfejsu wiersza polecenia używanych w tym samouczku używa tych samych parametrów. Dla wygody definiujemy zmienne lokalne, które można wywoływać zgodnie z potrzebami. Pamiętaj, aby uruchomić wszystkie polecenia w tej samej sesji lub trzeba będzie ponownie zdefiniować zmienne.

1. Zdefiniuj zmienne dla centrum IoT i urządzenia.

   IOTHUB_NAME: zastąp ten symbol zastępczy nazwą centrum IoT Hub.

   DEVICE_NAME: zastąp ten symbol zastępczy dowolną nazwą, której chcesz użyć dla urządzenia w tym samouczku.

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. Uruchom polecenie az iot hub device-identity create w powłoce interfejsu wiersza polecenia. To polecenie tworzy tożsamość urządzenia.

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. Z danych wyjściowych tożsamości urządzenia skopiuj wartość primaryKey bez otaczających cudzysłowów i zapisz ją. Użyjesz tej wartości do skonfigurowania przykładowego kodu, który generuje symulowane komunikaty telemetryczne urządzenia.

Teraz, gdy masz identyfikator urządzenia i klucz, użyj przykładowego kodu, aby rozpocząć wysyłanie komunikatów telemetrycznych urządzenia do usługi IoT Hub.

Napiwek

Jeśli wykonasz kroki interfejsu wiersza polecenia platformy Azure dla tego samouczka, uruchom przykładowy kod w oddzielnej sesji. Dzięki temu możesz zezwolić na kontynuowanie działania przykładowego kodu podczas wykonywania pozostałych kroków interfejsu wiersza polecenia.

1. Jeśli nie jesteś częścią wymagań wstępnych, pobierz lub sklonuj zestaw SDK usługi Azure IoT dla repozytorium C# z usługi GitHub.

2. Z folderu, w którym pobrano lub sklonował zestaw SDK, przejdź do azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample folderu.

3. Zainstaluj zestaw SDK języka C# usługi Azure IoT i niezbędne zależności, jak określono w HubRoutingSample.csproj pliku:

   dotnet restore
   

4. W wybranym edytorze otwórz Parameters.cs plik. Ten plik zawiera parametry obsługiwane przez przykład. PrimaryConnectionString Tylko parametr będzie używany w tym artykule podczas uruchamiania przykładu. Przejrzyj kod w tym pliku. Nie są potrzebne żadne zmiany.

5. Skompiluj i uruchom przykładowy kod przy użyciu następującego polecenia:

   Zastąp <myDevicePrimaryConnectionString> element podstawowym parametry połączenia z urządzenia w centrum IoT.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. Należy zacząć widzieć komunikaty drukowane w danych wyjściowych, ponieważ są one wysyłane do usługi IoT Hub. Pozostaw ten program uruchomiony podczas pracy z samouczkiem.

Konfigurowanie eksploratora IoT do wyświetlania komunikatów

Skonfiguruj program IoT Explorer, aby nawiązać połączenie z centrum IoT Hub i odczytywać komunikaty po dotarciu do wbudowanego punktu końcowego.

Najpierw pobierz parametry połączenia dla centrum IoT.

Witryna Azure Portal

1. W witrynie Azure Portal przejdź do centrum IoT Hub.

2. Wybierz pozycję Zasady dostępu współdzielonego w sekcji Ustawienia zabezpieczeń menu.

3. Wybierz zasady iothubowner.

   

4. Skopiuj parametry połączenia podstawową.

   

Interfejs wiersza polecenia platformy Azure

1. Uruchom polecenie az iot hub connection-string show:

   az iot hub connection-string show --hub-name $hubName
   

2. Skopiuj parametry połączenia bez otaczającego cudzysłowu.

Teraz użyj tej parametry połączenia, aby skonfigurować narzędzie IoT Explorer dla centrum IoT.

1. Otwórz program IoT Explorer na maszynie dewelopera.

2. Wybierz opcję Dodaj połączenie.

   

3. Wklej parametry połączenia centrum w polu tekstowym.

4. Wybierz pozycję Zapisz.

5. Po nawiązaniu połączenia z centrum IoT hub powinna zostać wyświetlona lista urządzeń. Wybierz identyfikator urządzenia utworzony na potrzeby tego samouczka.

6. Wybierz Telemetria.

7. Gdy urządzenie jest nadal uruchomione, wybierz pozycję Uruchom. Jeśli urządzenie nie jest uruchomione, nie zobaczysz telemetrii.

   

8. Powinny zostać wyświetlone komunikaty przychodzące z urządzenia z najnowszymi komunikatami wyświetlanymi u góry.

   

   Obejrzyj komunikaty przychodzące przez kilka chwil, aby sprawdzić, czy są widoczne trzy różne typy komunikatów: normalny, magazyn i krytyczny. Gdy to zobaczysz, możesz zatrzymać urządzenie.

Wszystkie te komunikaty docierają do domyślnego wbudowanego punktu końcowego centrum IoT Hub. W następnych sekcjach utworzymy niestandardowy punkt końcowy i skierować niektóre z tych komunikatów do magazynu na podstawie właściwości komunikatu. Te komunikaty przestaną pojawiać się w eksploratorze IoT, ponieważ komunikaty przechodzą tylko do wbudowanego punktu końcowego, gdy nie są zgodne z żadnymi innymi trasami w centrum IoT.

Konfigurowanie routingu komunikatów

Będziesz kierować komunikaty do różnych zasobów na podstawie właściwości dołączonych do komunikatu przez urządzenie symulowane. Komunikaty, które nie są trasami niestandardowymi, są wysyłane do domyślnego punktu końcowego (komunikaty/zdarzenia).

Przykładowa aplikacja na potrzeby tego samouczka przypisuje właściwość level do każdego komunikatu wysyłanego do centrum IoT. Każdy komunikat jest losowo przypisany do poziomu normalnego, magazynu lub krytycznego.

Pierwszym krokiem jest skonfigurowanie punktu końcowego, do którego będą kierowane dane. Drugim krokiem jest skonfigurowanie trasy komunikatów korzystającej z tego punktu końcowego. Po skonfigurowaniu routingu można wyświetlić punkty końcowe i trasy komunikatów w portalu.

Tworzenie konta magazynu

Utwórz konto usługi Azure Storage i kontener w ramach tego konta, które będzie przechowywać komunikaty urządzenia, które są kierowane do niego.

Witryna Azure Portal

1. W witrynie Azure Portal wyszukaj pozycję Konta magazynu.

2. Wybierz pozycję Utwórz.

3. Podaj następujące wartości dla konta magazynu:

   Parametr	Wartość
   Subskrypcja	Wybierz tę samą subskrypcję, która zawiera centrum IoT Hub.
   Grupa zasobów:	Wybierz tę samą grupę zasobów, która zawiera centrum IoT Hub.
   Nazwa konta magazynu	Podaj globalnie unikatową nazwę konta magazynu.
   Wydajność	Zaakceptuj domyślną wartość standardową .

   

4. Możesz zaakceptować wszystkie pozostałe wartości domyślne, wybierając pozycję Przejrzyj i utwórz.

5. Po zakończeniu walidacji wybierz pozycję Utwórz.

6. Po zakończeniu wdrożenia wybierz pozycję Przejdź do zasobu.

7. W menu konta magazynu wybierz pozycję Kontenery w sekcji Magazyn danych.

8. Wybierz pozycję + Kontener , aby utworzyć nowy kontener.

   

9. Podaj nazwę kontenera i wybierz pozycję Utwórz.

Interfejs wiersza polecenia platformy Azure

1. Zdefiniuj zmienne dla konta magazynu i kontenera.

   GROUP_NAME: zastąp ten symbol zastępczy nazwą grupy zasobów, która zawiera centrum IoT.

   STORAGE_NAME: zastąp ten symbol zastępczy nazwą konta magazynu. Nazwy kont magazynu muszą być małe i globalnie unikatowe.

   CONTAINER_NAME: zastąp ten symbol zastępczy nazwą kontenera.

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. Użyj polecenia az storage account create, aby utworzyć standardowe konto magazynu ogólnego przeznaczenia w wersji 2.

   az storage account create --name $storageName --resource-group $resourceGroup
   

3. Użyj polecenia az storage container create , aby dodać kontener do konta magazynu.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

Kierowanie do konta magazynu

Teraz należy skonfigurować routing dla konta magazynu. W tej sekcji zdefiniujesz nowy punkt końcowy wskazujący utworzone konto magazynu. Następnie utwórz trasę, która filtruje komunikaty, w których właściwość level jest ustawiona na magazyn, i kieruj je do punktu końcowego magazynu.

Uwaga

Dane można zapisywać w magazynie obiektów blob w formacie Apache Avro , który jest domyślny lub JSON.

Format kodowania można ustawić tylko w momencie skonfigurowania punktu końcowego magazynu obiektów blob. Nie można zmienić formatu dla punktu końcowego, który został już skonfigurowany. W przypadku korzystania z kodowania JSON należy ustawić właściwość contentType na wartość JSON, a właściwość contentEncoding na wartość UTF-8 we właściwościach systemu komunikatów.

Aby uzyskać bardziej szczegółowe informacje na temat korzystania z punktu końcowego magazynu obiektów blob, zobacz wskazówki dotyczące routingu do magazynu.

Ważne

Ten artykuł zawiera kroki nawiązywania połączenia z usługą przy użyciu sygnatury dostępu współdzielonego. Ta metoda uwierzytelniania jest wygodna do testowania i oceny, ale uwierzytelnianie w usłudze przy użyciu identyfikatora Entra firmy Microsoft lub tożsamości zarządzanych jest bardziej bezpieczne. Aby dowiedzieć się więcej, zobacz Security best practices Cloud security (Najlepsze rozwiązania > dotyczące zabezpieczeń w chmurze).

Witryna Azure Portal

1. W witrynie Azure Portal przejdź do centrum IoT Hub.

2. W menu zasobów w obszarze Ustawienia centrum wybierz pozycję Routing komunikatów , a następnie wybierz pozycję Dodaj.

   

3. Na karcie Punkt końcowy utwórz punkt końcowy magazynu, podając następujące informacje:

   Parametr	Wartość
   Typ punktu końcowego	Wybierz pozycję Magazyn.
   Nazwa punktu końcowego	Podaj unikatową nazwę dla tego punktu końcowego.
   Kontener usługi Azure Storage	Wybierz pozycję Wybierz kontener. Postępuj zgodnie z monitami, aby wybrać konto magazynu i kontener utworzony w poprzedniej sekcji.
   Kodowanie	Wybierz pozycję JSON. Jeśli to pole jest wyszarzone, region konta magazynu nie obsługuje formatu JSON. W takim przypadku kontynuuj korzystanie z domyślnej usługi AVRO.

   

4. Zaakceptuj wartości domyślne pozostałych parametrów i wybierz pozycję Utwórz i dalej.

5. Na karcie Trasa podaj następujące informacje, aby utworzyć trasę wskazującą utworzony punkt końcowy magazynu:

   Parametr	Wartość
   Nazwa/nazwisko	Utwórz nazwę trasy.
   Źródło danych	Sprawdź, czy z listy rozwijanej wybrano pozycję Komunikaty telemetryczne urządzenia.
   Włączanie trasy	Sprawdź, czy to pole jest zaznaczone.
   Zapytanie dotyczące routingu	Wprowadź level="storage" jako ciąg zapytania.

   

6. Wybierz pozycję Utwórz i pomiń wzbogacania.

Interfejs wiersza polecenia platformy Azure

1. Skonfiguruj zmienne potrzebne dla punktu końcowego i poleceń trasy.

   ENDPOINT_NAME: podaj nazwę punktu końcowego reprezentującego kontener magazynu.

   ROUTE_NAME: podaj nazwę trasy, która filtruje komunikaty dla punktu końcowego magazynu

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

2. Użyj polecenia az iot hub message-endpoint create, aby utworzyć niestandardowy punkt końcowy wskazujący kontener magazynu utworzony w poprzedniej sekcji.

   az iot hub message-endpoint create storage-container \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Użyj polecenia az iot hub message-route create, aby utworzyć trasę przekazującą dowolny komunikat do level=storage punktu końcowego kontenera magazynu.

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

Wyświetlanie komunikatów kierowanych

Po utworzeniu trasy w usłudze IoT Hub i włączeniu go natychmiast rozpocznie routing komunikatów spełniających warunek zapytania do punktu końcowego magazynu.

Monitorowanie wbudowanego punktu końcowego za pomocą narzędzia IoT Explorer

Wróć do sesji usługi IoT Explorer na komputerze deweloperskim. Pamiętaj, że Eksplorator IoT monitoruje wbudowany punkt końcowy centrum IoT. Oznacza to, że teraz powinny być widoczne tylko komunikaty, które nie są kierowane przez utworzoną trasę niestandardową.

Uruchom ponownie przykład, uruchamiając kod. Obejrzyj komunikaty przychodzące przez kilka chwil i powinny być widoczne tylko komunikaty, w których level ustawiono normal wartość lub critical.

Wyświetlanie komunikatów w kontenerze magazynu

Sprawdź, czy komunikaty docierają do kontenera magazynu.

1. W witrynie Azure Portal przejdź do swojego konta magazynu.

2. Wybierz pozycję Kontenery w sekcji Magazyn danych w menu.

3. Wybierz kontener utworzony na potrzeby tego samouczka.

4. Powinien istnieć folder o nazwie centrum IoT Hub. Przechodzenie do szczegółów struktury plików do momentu przejścia do pliku .json .

   

5. Wybierz plik JSON, a następnie wybierz pozycję Pobierz , aby pobrać plik JSON. Upewnij się, że plik zawiera komunikaty z urządzenia, które mają właściwość ustawioną level na storagewartość .

6. Zatrzymaj uruchamianie przykładu.

Czyszczenie zasobów

Jeśli chcesz usunąć wszystkie zasoby platformy Azure używane na potrzeby tego samouczka, usuń grupę zasobów. Ta akcja spowoduje również usunięcie wszystkich zasobów znajdujących się w grupie. Jeśli nie chcesz usuwać całej grupy zasobów, użyj witryny Azure Portal, aby zlokalizować i usunąć poszczególne zasoby.

Jeśli zamierzasz przejść do następnego samouczka, zachowaj utworzone tutaj zasoby.

Witryna Azure Portal

1. W witrynie Azure Portal przejdź do grupy zasobów zawierającej centrum IoT i konto magazynu na potrzeby tego samouczka.
2. Przejrzyj wszystkie zasoby, które znajdują się w grupie zasobów, aby określić, które zasoby chcesz wyczyścić.
   • Jeśli chcesz usunąć cały zasób, wybierz pozycję Usuń grupę zasobów.
   • Jeśli chcesz usunąć tylko określony zasób, użyj pól wyboru obok każdej nazwy zasobu, aby wybrać te, które chcesz usunąć. Następnie wybierz Usuń.

Interfejs wiersza polecenia platformy Azure

1. Użyj polecenia az resource list, aby wyświetlić wszystkie zasoby w grupie zasobów.

   az resource list --resource-group $resourceGroup --output table
   

2. Przejrzyj wszystkie zasoby, które znajdują się w grupie zasobów, aby określić, które zasoby chcesz wyczyścić.

   • Jeśli chcesz usunąć wszystkie zasoby, użyj polecenia az group delete .

     az group delete --name $resourceGroup
     

   • Jeśli chcesz usunąć tylko niektóre zasoby, użyj polecenia az resource delete . Na przykład:

     az resource delete --resource-group $resourceGroup --name $storageName
     

Następne kroki

W tym samouczku przedstawiono sposób tworzenia niestandardowego punktu końcowego dla zasobu platformy Azure, a następnie tworzenia trasy wysyłania komunikatów urządzeń do tego punktu końcowego. Przejdź do następnego samouczka, aby dowiedzieć się, jak wzbogacić komunikaty o dodatkowe dane, których można użyć do uproszczenia przetwarzania podrzędnego

Korzystanie z wzbogacenia komunikatów usługi Azure IoT Hub