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 i trasy komunikatów w celu ich wysłania. 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 centrum kieruje je do obu kontenerów magazynu. Wzbogacone są tylko komunikaty wysyłane do punktu końcowego dla wzbogaconego kontenera magazynu.

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

• Utwórz drugi kontener na koncie magazynu.
• Utwórz kolejny niestandardowy punkt końcowy i kieruj do niego komunikaty z centrum IoT Hub.
• Skonfiguruj wzbogacania komunikatów, które są kierowane 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.

• Ukończono Samouczek: wysyłanie danych urządzenia do usługi Azure Storage przy użyciu routingu komunikatów usługi IoT Hub i utrzymywanie utworzonych zasobów.

• Upewnij się, że port 8883 jest otwarty w zaporze. Przykład urządzenia 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 Połączenie do usługi IoT Hub (MQTT).

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.

Tworzenie drugiego kontenera na koncie magazynu

W pierwszej części tego samouczka utworzono konto magazynu i kontener dla komunikatów kierowanych. Teraz należy utworzyć drugi kontener dla wzbogaconych komunikatów.

Witryna Azure Portal

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

2. Wybierz utworzone wcześniej konto magazynu.

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

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

   

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

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.

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 centrum 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: zastąp ten symbol zastępczy nazwą konta magazynu.

   Na potrzeby tego samouczka należy wzbogacić wartość zmiennejcontainerName.

   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.

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	Wprowadź ContosoStorageEndpointEnriched.
   Kontener usługi Azure Storage	Wybierz pozycję Wybierz kontener. Postępuj zgodnie z monitami, aby wybrać konto magazynu i wzbogacony 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. Kontynuuj tworzenie nowej trasy, po dodaniu punktu końcowego magazynu. Podaj następujące informacje dotyczące nowej trasy:

   Parametr	Wartość
   Nazwa/nazwisko	ContosoStorageRouteEnriched
   Źródło danych	Sprawdź, czy z listy rozwijanej wybrano pozycję Komunikaty telemetryczne urządzenia.
   Włączanie trasy	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 wzbogacania.

Interfejs wiersza polecenia platformy Azure

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 magazynu 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 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"'
   

Dodawanie wzbogacania komunikatów do nowego punktu końcowego

Utwórz trzy wzbogacania komunikatów, które zostaną przekierowane do wzbogaconego kontenera magazynu.

Witryna Azure Portal

1. Na karcie Wzbogacanie kreatora Dodawanie trasy dodaj trzy wzbogacania komunikatów dla komunikatów przechodzących do punktu końcowego dla kontenera magazynu o nazwie wzbogacone.

   Dodaj te wartości jako wzbogacenia komunikatów dla punktu końcowego ContosoStorageEndpointEnriched:

   Nazwa/nazwisko	Wartość
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (zakłada, że bliźniacza reprezentacja urządzenia ma tag lokalizacji)
   Idklienta	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.

Interfejs wiersza polecenia platformy Azure

Wykonaj trzy wywołania polecenia az iot hub message-enrichment create , aby dodać wzbogacanie komunikatów do trasy przechodzącej do utworzonego wcześniej 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źniaczej reprezentacji urządzenia, możesz przejść do sekcji Testowanie wzbogacania komunikatów, aby kontynuować samouczek.

Dodawanie tagu lokalizacji do bliźniaczej reprezentacji urządzenia

Jedno z wzbogacenia komunikatów skonfigurowanych w centrum IoT Hub określa klucz DeviceLocation z jego 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 $twin.tags.locationbliźniaczej reprezentacji zostanie oznaczona jako ciąg klucza DeviceLocation w wzbogacaniu komunikatu.

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

Witryna Azure Portal

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"}
   

   

Interfejs wiersza polecenia platformy Azure

Użyj polecenia az iot hub device-twin update, aby zaktualizować bliźniacze reprezentacje urządzenia przy użyciu nowego klucza tagu i wartości.

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

Napiwek

Poczekaj około pięciu minut, zanim przejdziesz do następnej sekcji. Może upłynąć do tego czasu, aby aktualizacje bliźniaczej reprezentacji urządzenia mogły zostać odzwierciedlone w wartościach wzbogacania komunikatów.

Aby dowiedzieć się więcej o obsłudze ścieżek bliźniaczych reprezentacji urządzenia przy użyciu wzbogacania komunikatów, zobacz Ograniczenia wzbogacania komunikatów. Aby dowiedzieć się więcej na temat bliźniaczych reprezentacji urządzeń, zobacz Omówienie bliźniaczych reprezentacji urządzeń i korzystanie z nich w usłudze IoT Hub.

Wzbogacanie komunikatów testowych

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

• Komunikaty kierowane do punktu końcowego magazynu utworzonego w pierwszej części samouczka nie zostaną wzbogacone i będą przechowywane w utworzonym kontenerze magazynu.

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

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

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

Po opuszczeniu aplikacji konsolowej do uruchomienia przez kilka minut wyświetl dane:

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

2. Wybierz pozycję Przeglądarka magazynu z menu nawigacji. Wybierz pozycję Kontenery obiektów blob, aby wyświetlić dwa kontenery utworzone w ramach tych samouczków.

   

Komunikaty w kontenerze o nazwie wzbogacone zawierają wzbogacenia komunikatów zawarte w komunikatach. Komunikaty w utworzonym wcześniej kontenerze mają nieprzetworzone komunikaty bez wzbogacenia. 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ąć.

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 skonfigurowano i przetestowano wzbogacanie komunikatów 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