Wprowadzenie do tożsamości modułu IoT Hub i bliźniaczej reprezentacji modułu (Python)

Artykuł
03/18/2023

Tożsamości modułów i bliźniacze reprezentacje modułów są podobne do tożsamości urządzeń Azure IoT Hub i bliźniaczych reprezentacji urządzeń, ale zapewniają bardziej szczegółowość. Podczas gdy Azure IoT Hub tożsamości urządzeń i bliźniacze reprezentacje urządzeń umożliwiają aplikacji zaplecza skonfigurowanie urządzenia i zapewnienie widoczności warunków urządzenia, tożsamości modułu i bliźniacze reprezentacje modułu zapewniają te możliwości dla poszczególnych składników urządzenia. Na urządzeniach obsługujących wiele składników, takich jak urządzenia z systemem operacyjnym lub urządzenia układowe, umożliwiają one izolowane konfiguracje i warunki dla każdego składnika.

Uwaga

Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa IoT Hub. Aby uzyskać więcej informacji o warstwach podstawowa i Standardowa/Bezpłatna IoT Hub, zobacz Wybieranie odpowiedniej warstwy IoT Hub dla rozwiązania.

Na końcu tego artykułu masz trzy aplikacje języka Python:

CreateModule: tworzy tożsamość urządzenia, tożsamość modułu i skojarzone klucze zabezpieczeń w celu połączenia klientów urządzenia i modułu.
UpdateModuleTwinDesiredProperties: wysyła zaktualizowaną reprezentację modułu, żądane właściwości do IoT Hub.
ReceiveModuleTwinDesiredPropertiesPatch: odbiera bliźniaczą reprezentację modułu, żądaną poprawkę właściwości na urządzeniu.

Uwaga

Aby uzyskać więcej informacji na temat narzędzi zestawu SDK dostępnych do kompilowania aplikacji zarówno urządzeń, jak i zaplecza, zobacz Zestawy SDK usługi Azure IoT.

Wymagania wstępne

Aktywne konto platformy Azure. (Jeśli nie masz konta, możesz utworzyć bezpłatne konto w ciągu zaledwie kilku minut).
Centrum IoT. Utwórz go przy użyciu interfejsu wiersza polecenia lub Azure Portal.
Zalecane jest użycie języka Python w wersji 3.7 lub nowszej. Upewnij się, że używasz 32-bitowej lub 64-bitowej instalacji zgodnie z wymaganiami konfiguracji. Po wyświetleniu monitu podczas instalacji upewnij się, że język Python został dodany do zmiennej środowiskowej specyficznej dla platformy.

Uwierzytelnianie modułu

Do uwierzytelniania tożsamości modułów można użyć kluczy symetrycznych lub certyfikatów X.509. W przypadku uwierzytelniania certyfikatu X.509 certyfikat modułu musi mieć jego nazwę pospolitą (CN) w formacie , na przykład CN=<deviceid>/<moduleid>. Na przykład:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Pobieranie parametrów połączenia centrum IoT

W tym artykule utworzysz usługę zaplecza, która dodaje urządzenie w rejestrze tożsamości, a następnie dodaje moduł do tego urządzenia. Ta usługa wymaga uprawnienia do zapisu rejestru (który obejmuje również odczyt rejestru). Utworzysz również usługę, która dodaje żądane właściwości do bliźniaczej reprezentacji modułu dla nowo utworzonego modułu. Ta usługa wymaga uprawnienia do nawiązywania połączenia z usługą . Mimo że istnieją domyślne zasady dostępu współdzielonego, które udzielają tych uprawnień indywidualnie, w tej sekcji utworzysz niestandardowe zasady dostępu współdzielonego, które zawierają oba te uprawnienia.

Aby utworzyć zasady dostępu współdzielonego, które udzielają uprawnień do nawiązywania połączenia z usługą i zapisu rejestru oraz pobierania parametrów połączenia dla tych zasad, wykonaj następujące kroki:

W Azure Portal wybierz pozycję Grupy zasobów. Wybierz grupę zasobów, w której znajduje się centrum, a następnie wybierz centrum z listy zasobów.
W okienku po lewej stronie centrum wybierz pozycję Zasady dostępu współdzielonego.
Z menu powyżej listy zasad wybierz pozycję Dodaj zasady dostępu współdzielonego.
W obszarze Dodaj zasady dostępu współdzielonego wprowadź opisową nazwę zasad, taką jak serviceAndRegistryReadWrite. W obszarze Uprawnienia wybierz pozycję Zapis rejestru i połączenie z usługą, a następnie wybierz pozycję Dodaj. (Uprawnienie odczyt rejestru jest uwzględniane automatycznie po wybraniu opcji Zapis rejestru).
Wybierz nowe zasady z listy zasad.
W obszarze Klucze dostępu współdzielonego wybierz ikonę kopiowania dla podstawowych parametrów połączenia i zapisz wartość.

Aby uzyskać więcej informacji na temat IoT Hub zasad dostępu współdzielonego i uprawnień, zobacz Kontrola dostępu i uprawnienia.

Tworzenie tożsamości urządzenia i tożsamości modułu w IoT Hub

W tej sekcji utworzysz aplikację usługi języka Python, która tworzy tożsamość urządzenia i tożsamość modułu w rejestrze tożsamości w centrum IoT. Urządzenie lub moduł nie może nawiązać połączenia z centrum IoT, chyba że ma wpis w rejestrze tożsamości. Aby uzyskać więcej informacji, zobacz Opis rejestru tożsamości w centrum IoT. Uruchomienie tej aplikacji konsolowej powoduje wygenerowanie unikatowego identyfikatora i klucza zarówno dla urządzenia, jak i modułu. W identyfikatorze i kluczu jest rozróżniana wielkość liter. Urządzenie i moduł korzystają z tych wartości w celu identyfikowania się podczas wysyłania komunikatów urządzenie-chmura do usługi IoT Hub.

W wierszu polecenia uruchom następujące polecenie, aby zainstalować pakiet azure-iot-hub :
```
pip install azure-iot-hub
```
W wierszu polecenia uruchom następujące polecenie, aby zainstalować pakiet msrest . Ten pakiet jest potrzebny do przechwytywania wyjątków HTTPOperationError .
```
pip install msrest
```
Za pomocą edytora tekstów utwórz plik o nazwie CreateModule.py w katalogu roboczym.

Dodaj następujący kod do pliku python. Zastąp ciąg YourIoTHubConnectionString parametrami połączenia skopiowanymi w sekcji Pobieranie parametrów połączenia centrum IoT.

import sys
from msrest.exceptions import HttpOperationError
from azure.iot.hub import IoTHubRegistryManager

CONNECTION_STRING = "YourIotHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    try:
        # CreateDevice - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        device_state = "enabled"
        new_device = iothub_registry_manager.create_device_with_sas(
            DEVICE_ID, primary_key, secondary_key, device_state
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the device already exists.
            new_device = iothub_registry_manager.get_device(DEVICE_ID)
        else:
            raise

    print("device <" + DEVICE_ID +
          "> has primary key = " + new_device.authentication.symmetric_key.primary_key)

    try:
        # CreateModule - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        managed_by = ""
        new_module = iothub_registry_manager.create_module_with_sas(
            DEVICE_ID, MODULE_ID, managed_by, primary_key, secondary_key
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the module already exists.
            new_module = iothub_registry_manager.get_module(DEVICE_ID, MODULE_ID)
        else:
            raise

    print("device/module <" + DEVICE_ID + "/" + MODULE_ID +
          "> has primary key = " + new_module.authentication.symmetric_key.primary_key)

except Exception as ex:
    print("Unexpected error {0}".format(ex))
except KeyboardInterrupt:
    print("IoTHubRegistryManager sample stopped")

W wierszu polecenia uruchom następujące polecenie:
```
python CreateModule.py
```

Ta aplikacja tworzy tożsamość urządzenia o identyfikatorze myFirstDevice i tożsamości modułu o identyfikatorze myFirstModule w obszarze urządzenia myFirstDevice. (Jeśli identyfikator urządzenia lub modułu już istnieje w rejestrze tożsamości, kod po prostu pobiera informacje o istniejącym urządzeniu lub module). Aplikacja wyświetla identyfikator i klucz podstawowy dla każdej tożsamości.

Uwaga

Rejestr tożsamości usługi IoT Hub przechowuje tożsamości urządzenia i modułu tylko po to, aby umożliwić bezpieczny dostęp do centrum IoT. W rejestrze tożsamości są przechowywane identyfikatory urządzeń i klucze służące jako poświadczenia zabezpieczeń. W rejestrze tożsamości są także przechowywane flagi włączenia/wyłączenia dla każdego urządzenia, za pomocą których można wyłączyć dostęp do danego urządzenia. Jeśli aplikacja wymaga przechowywania innych metadanych dla określonego urządzenia, powinna korzystać z magazynu określonego dla aplikacji. Nie istnieje flaga włączenia/wyłączenia tożsamości modułów. Aby uzyskać więcej informacji, zobacz Opis rejestru tożsamości w centrum IoT.

Aktualizowanie bliźniaczej reprezentacji modułu przy użyciu zestawu SDK usługi języka Python

W tej sekcji utworzysz aplikację usługi języka Python, która aktualizuje żądane właściwości bliźniaczej reprezentacji modułu.

W wierszu polecenia uruchom następujące polecenie, aby zainstalować pakiet azure-iot-hub . Ten krok można pominąć, jeśli pakiet azure-iot-hub został zainstalowany w poprzedniej sekcji.
```
pip install azure-iot-hub
```
Za pomocą edytora tekstów utwórz plik o nazwie UpdateModuleTwinDesiredProperties.py w katalogu roboczym.

Dodaj następujący kod do pliku python. Zastąp ciąg YourIoTHubConnectionString parametrami połączenia skopiowanymi w sekcji Pobieranie parametrów połączenia centrum IoT.

import sys
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties

CONNECTION_STRING = "YourIoTHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module twin properties before update    :" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

Pobieranie aktualizacji po stronie urządzenia

W tej sekcji utworzysz aplikację w języku Python, aby pobrać aktualizację żądanych właściwości bliźniaczej reprezentacji modułu na urządzeniu.

Pobierz parametry połączenia modułu. W Azure Portal przejdź do IoT Hub i wybierz pozycję Urządzenia w okienku po lewej stronie. Wybierz pozycję myFirstDevice z listy urządzeń i otwórz ją. W obszarze Tożsamości modułów wybierz pozycję myFirstModule. Wybierz ikonę kopiowania dla pozycji Parametry połączenia (klucz podstawowy). Te parametry połączenia są potrzebne w następnym kroku.
W wierszu polecenia uruchom następujące polecenie, aby zainstalować pakiet azure-iot-device :
```
pip install azure-iot-device
```
Za pomocą edytora tekstów utwórz plik o nazwie ReceiveModuleTwinDesiredPropertiesPatch.py w katalogu roboczym.

Dodaj następujący kod do pliku python. Zastąp ciąg YourModuleConnectionString parametrami połączenia modułu skopiowanymi w kroku 1.

import time
from azure.iot.device import IoTHubModuleClient

CONNECTION_STRING = "YourModuleConnectionString"


def twin_patch_handler(twin_patch):
    print("")
    print("Twin desired properties patch received:")
    print(twin_patch)


def main():
    print ("Starting the IoT Hub Python sample...")
    client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Attach the handler to the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler

        while True:
            time.sleep(1000)
    except KeyboardInterrupt:
        print("IoTHubModuleClient sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Uruchamianie aplikacji

W tej sekcji uruchomisz aplikację urządzenia ReceiveModuleTwinDesiredPropertiesPatch , a następnie uruchomisz aplikację usługi UpdateModuleTwinDesiredProperties , aby zaktualizować żądane właściwości modułu.

Otwórz wiersz polecenia i uruchom aplikację urządzenia:
```
python ReceiveModuleTwinDesiredPropertiesPatch.py
```
Otwórz osobny wiersz polecenia i uruchom aplikację usługi:
```
python UpdateModuleTwinDesiredProperties.py
```
Zwróć uwagę, że żądana właściwość TelemetryInterval jest wyświetlana w zaktualizowanej reprezentacji bliźniaczej modułu w danych wyjściowych aplikacji usługi:

Ta sama właściwość jest wyświetlana w żądanych poprawkach właściwości odebranych w danych wyjściowych aplikacji urządzenia: