Samouczek: używanie wzbogacania komunikatów usługi Azure IoT Hub

Wzbogacanie komunikatów to zdolność usługi Azure IoT Hub do oznaczania komunikatów dodatkowymi informacjami przed wysłaniem komunikatów do wyznaczonego punktu końcowego. Jednym z powodów używania wzbogacenia komunikatów jest uwzględnienie danych, których można użyć do uproszczenia przetwarzania podrzędnego. Na przykład wzbogacanie komunikatów urządzenia za pomocą tagu bliźniaczej reprezentacji urządzenia może zmniejszyć obciążenie klientów w celu wywołania interfejsu API bliźniaczej reprezentacji urządzenia dla tych informacji. Aby uzyskać więcej informacji, zobacz Omówienie wzbogacania komunikatów.

W pierwszej części tego samouczka przedstawiono sposób tworzenia niestandardowych punktów końcowych i kierowania komunikatów do innych usług platformy Azure. W tym samouczku zobaczysz, jak utworzyć i skonfigurować dodatkowe zasoby potrzebne do testowania wzbogacania komunikatów dla centrum IoT. Zasoby obejmują drugi kontener magazynu dla istniejącego konta magazynu (utworzonego w pierwszej części samouczka) do przechowywania wzbogaconych komunikatów oraz trasę komunikatów, aby je tam wysyłać. Po zakończeniu konfiguracji routingu komunikatów i wzbogacania komunikatów należy użyć aplikacji do wysyłania komunikatów do centrum IoT. Następnie hub kieruje je do obu kontenerów do przechowywania. Tylko komunikaty wysyłane do punktu końcowego dla kontenera wzbogaconego storage są wzbogacane.

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

• Utwórz drugi kontener na koncie magazynowym.
• Utwórz kolejny niestandardowy punkt końcowy i kieruj do niego komunikaty z centrum IoT Hub.
• Skonfiguruj wzbogacenia komunikatów kierowanych do nowego punktu końcowego.
• Uruchom aplikację, która symuluje urządzenie IoT wysyłające komunikaty do centrum.
• Wyświetl wyniki i sprawdź, czy wzbogacenia komunikatów są stosowane do komunikatów docelowych.

Wymagania wstępne

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

• Musisz ukończyć Samouczek: wysyłanie danych urządzenia do usługi Azure Storage przy użyciu routingu komunikatów usługi IoT Hub i zachować zasoby, które utworzyłeś dla niego.

• Upewnij się, że port 8883 jest otwarty w twoim firewallu. Przykład urządzenia demonstracyjnego 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).

Portal Azure

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

"Azure CLI"

• Użyj środowiska Bash w Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Rozpoczynanie pracy z usługą 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 Uwierzytelnianie na platformie Azure przy użyciu interfejsu wiersza polecenia platformy Azure.

  • Po wyświetleniu monitu zainstaluj rozszerzenie Azure CLI przy pierwszym użyciu. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Używanie rozszerzeń i zarządzanie nimi za pomocą interfejsu 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.

Utwórz drugi kontener w swoim koncie magazynowym

W pierwszej części tego samouczka utworzono konto pamięci masowej i kontener na kierowane komunikaty. Teraz należy utworzyć drugi kontener dla wzbogaconych komunikatów.

Portal Azure

1. W portalu Azure wyszukaj Konta magazynu.

2. Wybierz utworzone wcześniej konto.

3. W menu konta magazynowania wybierz opcję Kontenery z sekcji Przechowywanie danych.

4. Wybierz pozycję Kontener , aby utworzyć nowy kontener.

   

5. Nadaj kontenerowi enrichednazwę , a następnie wybierz pozycję Utwórz.

"Azure CLI"

Tip

Wiele poleceń CLI w tym samouczku korzysta z 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.

Wartości tych zmiennych powinny dotyczyć tych samych zasobów, które zostały użyte w pierwszej części tego samouczka.

1. Zdefiniuj zmienne dla IoT Hub, konta magazynu i kontenera.

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

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

   DEVICE_ID: zastąp ten symbol zastępczy identyfikatorem urządzenia.

   STORAGE_NAME: Zamień ten zamiennik na nazwę swojego konta magazynowego.

   Na potrzeby tego samouczka należy containerName wartość zmiennej.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

2. 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 komunikatów do drugiego punktu końcowego

Utwórz drugi punkt końcowy i trasę dla wzbogaconych komunikatów.

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 Najlepsze rozwiązania w zakresie zabezpieczeń rozwiązań > IoT w chmurze.

Portal Azure

1. W portalu Azure przejdź do centrum IoT.

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

   

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

   Parameter	Wartość
   Typ punktu końcowego	Wybierz pozycję Przechowywanie.
   Nazwa punktu końcowego	Wprowadź ContosoStorageEndpointEnriched.
   Kontener usługi Azure Storage	Wybierz pozycję Wybierz kontener. Postępuj zgodnie z monitami, aby wybrać konto przechowywania i ulepszony kontener, który utworzyłeś w poprzedniej sekcji.
   Kodowanie	Wybierz pozycję JSON. Jeśli to pole jest wyszarzone, oznacza to, że Twój 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. Kontynuuj tworzenie nowej trasy, po dodaniu punktu końcowego magazynu. Podaj następujące informacje dotyczące nowej trasy:

   Parameter	Wartość
   Nazwa/nazwisko	ContosoStorageRouteEnriched
   Źródło danych	Sprawdź, czy z listy rozwijanej wybrano pozycję Komunikaty telemetryczne urządzenia .
   Włącz trasę	Sprawdź, czy to pole ma wartość enabled.
   Zapytanie dotyczące routingu	Wprowadź level="storage" jako ciąg zapytania.

   

6. Wybierz pozycję Utwórz i dodaj dodatki.

"Azure CLI"

1. Skonfiguruj zmienne dla poleceń punktu końcowego i routingu, aby używać odpowiednio wartości ContosoStorageEndpointEnriched i ContosoStorageRouteEnriched.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

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

   az iot hub message-endpoint create \
     --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, gdzie level=storage do 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"'
   

Dodaj wzbogacenie komunikatów do nowego punktu końcowego

Utwórz trzy wzbogacone komunikaty, które zostaną przekierowane do wzbogaconego kontenera.

Portal Azure

1. Na karcie Wzbogacanie kreatora Dodawanie trasy dodaj trzy ulepszenia komunikatów dla wiadomości przechodzących do punktu końcowego kontenera przechowywania o nazwie wzbogacone.

   Dodaj te wartości jako rozszerzenia komunikatów dla punktu końcowego ContosoStorageEndpointEnriched.

   Nazwa/nazwisko	Wartość
   myIotHub	$hubname
   Lokalizacja urządzenia	$twin.tags.location (zakłada, że bliźniak urządzenia ma tag lokalizacji)
   identyfikator klienta	6ce345b8-1e4a-411e-9398-d34587459a3a

   Po zakończeniu wzbogacanie powinno wyglądać podobnie do poniższego obrazu:

   

2. Wybierz pozycję Dodaj , aby dodać wzbogacanie komunikatów.

"Azure CLI"

Wykonaj trzy wywołania polecenia az iot hub message-enrichment create, aby wzbogacić komunikaty na trasie kierowanej do wcześniej utworzonego punktu końcowego.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

Masz teraz skonfigurowane wzbogacania komunikatów dla wszystkich komunikatów kierowanych do punktu końcowego utworzonego dla wzbogaconych komunikatów. Jeśli nie chcesz dodawać tagu lokalizacji do bliźniaka urządzenia, możesz przejść do sekcji Testowanie wzbogacania komunikatów, aby kontynuować samouczek.

Dodaj tag lokalizacji do bliźniaka urządzenia

Jedno z wzbogaceń komunikatów skonfigurowanych w IoT Hub specyfikuje klucz DeviceLocation z wartością określoną przez następującą ścieżkę bliźniaczej reprezentacji urządzenia: $twin.tags.location. Jeśli bliźniacza reprezentacja urządzenia nie ma tagu lokalizacji, ścieżka bliźniaka $twin.tags.location zostanie zakodowana jako ciąg znaków dla klucza DeviceLocation we wzbogaceniach komunikatu.

Wykonaj następujące kroki, aby dodać tag lokalizacji do bliźniaka urządzenia:

Portal Azure

1. Przejdź do centrum IoT w witrynie Azure Portal.

2. Wybierz pozycję Urządzenia w menu nawigacji centrum IoT, a następnie wybierz urządzenie.

3. Wybierz kartę Bliźniacze reprezentacje urządzenia w górnej części strony urządzenia i dodaj następujący wiersz tuż przed zamykającym nawiasem klamrowym u dołu bliźniaczej reprezentacji urządzenia. Następnie wybierz opcję Zapisz.

     , "tags": {"location": "Plant 43"}
   

   

"Azure CLI"

Użyj polecenia az iot hub device-twin update aby zaktualizować bliźniak urządzenia za pomocą nowego klucza tagu i jego wartości.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

Tip

Poczekaj około pięciu minut, zanim przejdziesz do następnej sekcji. Może upłynąć dość dużo czasu, zanim aktualizacje bliźniaka urządzenia zostaną odzwierciedlone w wartościach wzbogacania komunikatów.

Aby dowiedzieć się więcej na temat obsługi ścieżek reprezentacji urządzenia w kontekście wzbogacania komunikatów, zobacz Ograniczenia wzbogacania komunikatów. Aby dowiedzieć się więcej na temat bliźniaczych urządzeń, zobacz Zrozumienie i korzystanie z bliźniaczych urządzeń w usłudze IoT Hub.

Wzbogacanie komunikatów testowych

Po skonfigurowaniu wzbogacania komunikatów dla punktu końcowego ContosoStorageEndpointEnriched, uruchom aplikację symulowanego urządzenia, aby wysyłać komunikaty do centrum IoT. W tym momencie routing komunikatów został skonfigurowany w następujący sposób:

• Komunikaty kierowane do utworzonego punktu końcowego magazynu w pierwszej części samouczka nie zostaną wzbogacone i będą przechowywane w kontenerze magazynu, który utworzyłeś wtedy.

• Komunikaty kierowane do punktu końcowego przechowywania ContosoStorageEndpointEnriched zostaną wzbogacone i przechowywane w kontenerze enriched.

Jeśli nadal nie uruchamiasz aplikacji konsolowej SimulatedDevice z pierwszej części tego samouczka, uruchom ją ponownie:

Tip

Jeśli wykonujesz kroki Azure CLI dla tego poradnika, uruchamiasz 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. W folderze przykładowym przejdź do /iot-hub/Tutorials/Routing/SimulatedDevice/ folderu .

2. Definicje zmiennych, które zostały zaktualizowane wcześniej, powinny być prawidłowe, ale jeśli nie, należy je edytować w Program.cs pliku:

   1. Znajdź definicje zmiennych w górnej części klasy Program . Zaktualizuj następujące zmienne przy użyciu własnych informacji:

      • s_myDeviceId: identyfikator urządzenia przypisany podczas rejestrowania urządzenia w centrum IoT.
      • s_iotHubUri: nazwa hosta centrum IoT Hub, która przyjmuje format IOTHUB_NAME.azure-devices.net.
      • s_deviceKey: klucz podstawowy urządzenia znajdujący się w informacjach o tożsamości urządzenia.

   2. Zapisz i zamknij plik.

3. Uruchom przykładowy kod:

   dotnet run
   

Pozostaw aplikację konsolową uruchomioną przez kilka minut, aby wyświetlić dane.

1. Na portalu Azure przejdź do swojego konta przechowywania.

2. Wybierz Przeglądarka pamięci masowej z menu nawigacji. Wybierz kontenery Blob, aby wyświetlić dwa kontenery utworzone w trakcie tych samouczków.

   

Komunikaty w kontenerze o nazwie wzbogacone zawierają wzbogacenia wiadomości. Komunikaty w utworzonym wcześniej kontenerze to surowe wiadomości, bez żadnych wzbogaceń. Przejdź do wzbogaconego kontenera, aż przejdziesz do dołu, a następnie otwórz najnowszy plik wiadomości. Następnie wykonaj to samo dla innego kontenera, aby sprawdzić, czy jeden jest wzbogacony, a drugi nie.

Gdy przyjrzysz się komunikatom, które zostały wzbogacone, powinna zostać wyświetlona "myIotHub" nazwa centrum, lokalizacja i identyfikator klienta, w następujący sposób:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

Czyszczenie zasobów

Aby usunąć wszystkie zasoby utworzone w obu częściach 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, możesz wybrać poszczególne zasoby, aby je usunąć.

Portal Azure

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

"Azure CLI"

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 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 skonfigurowano i przetestowano rozszerzenia wiadomości dla komunikatów usługi IoT Hub podczas ich kierowania do punktu końcowego.

Aby uzyskać więcej informacji na temat wzbogacania komunikatów, zobacz Omówienie wzbogaceń komunikatów.

Aby dowiedzieć się więcej na temat usługi IoT Hub, przejdź do następnego samouczka.

Samouczek: konfigurowanie i używanie metryk i dzienników za pomocą centrum IoT