Introduzione all'identità del modulo e ai moduli gemelli dell'hub IoT (Python)

Articolo
10/01/2024

Le identità del modulo e i moduli gemelli sono simili alle identità del dispositivo e ai dispositivi gemelli dell'hub IoT di Azure, ma offrono una granularità superiore. Mentre le identità del dispositivo e i dispositivi gemelli dell'hub IoT di Azure consentono a un'applicazione back-end di configurare un dispositivo e fornire visibilità sulle condizioni del dispositivo, le identità del modulo e i moduli gemelli offrono queste funzionalità per i singoli componenti di un dispositivo. Nei dispositivi con più componenti, ad esempio dispositivi del sistema operativo o dispositivi firmware, consentono condizioni e configurazione isolate per ogni componente.

Nota

Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli Basic e Standard/Gratuito dell'hub IoT, vedere Scegliere il livello appropriato dell'hub IoT per la soluzione.

Al termine di questo articolo si avranno tre app Python:

CreateModule: crea un'identità del dispositivo, un'identità del modulo e le chiavi di sicurezza associate per connettere i client dispositivo e modulo.
UpdateModuleTwinDesiredProperties: invia le proprietà desiderate aggiornate del modulo gemello all'hub IoT.
ReceiveModuleTwinDesiredPropertiesPatch: riceve la patch delle proprietà desiderate del modulo gemello nel dispositivo.

Nota

Vedere Azure IoT SDK per altre informazioni sugli strumenti SDK disponibili per creare app sia per dispositivi che back-end.

Prerequisiti

Un account Azure attivo. Se non si dispone di un account, è possibile crearne uno gratuito in pochi minuti.
Un hub IoT nella sottoscrizione di Azure. Se non si ha ancora un hub, è possibile seguire la procedura descritta in Creare un hub IoT.
È consigliabile usare Python versione 3.7 o successive. Assicurarsi di usare le installazioni a 32 bit o 64 bit, come richiesto dalla configurazione. Quando richiesto durante l'installazione, assicurarsi di aggiungere Python alla variabile di ambiente specifica per la piattaforma.

Autenticazione modulo

È possibile usare chiavi simmetriche o certificati X.509 per autenticare le identità del modulo. Per l'autenticazione del certificato X.509, il certificato del modulo deve avere il nome comune (CN) formattato come CN=<deviceid>/<moduleid>. Ad esempio:

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

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end che aggiunge un dispositivo nel registro delle identità e quindi aggiunge un modulo a tale dispositivo. Questo servizio richiede l'autorizzazione Scrittura registro, che include anche l'autorizzazione Lettura registro. Verrà inoltre creato un servizio che aggiunge le proprietà desiderate al modulo gemello per il modulo appena creato. Questo servizio necessita dell'autorizzazione Connessione servizio. Anche se esistono criteri di accesso condiviso predefiniti che concedono queste autorizzazioni singolarmente, in questa sezione verrà creato un criterio di accesso condiviso personalizzato che contiene entrambe queste autorizzazioni.

Per creare un criterio di accesso condiviso che concede le autorizzazioni Connessione servizio e Scrittura registro e per ottenere una stringa di connessione per questo criterio, seguire questa procedura:

Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.
Nel riquadro sinistro dell'hub selezionare Criteri di accesso condiviso.
Dal menu sopra l'elenco dei criteri selezionare Aggiungi criterio di accesso condiviso.
In Aggiungi criterio di accesso condiviso immettere un nome descrittivo per il criterio, ad esempio serviceAndRegistryReadWrite. In Autorizzazioni selezionare Scrittura registro e Connessione servizio e quindi selezionare Aggiungi. L'autorizzazione Lettura registro è inclusa automaticamente quando si seleziona Scrittura registro.
Selezionare il nuovo criterio dall'elenco dei criteri.
In Chiavi di accesso condiviso selezionare l'icona di copia per Stringa di connessione primaria e salvare il valore.

Per altre informazioni sui criteri di accesso condiviso e sulle autorizzazioni dell'hub IoT, vedere Controllo dell'accesso e autorizzazioni.

Importante

Questo articolo include la procedura per connettersi a un servizio usando una firma di accesso condiviso. Questo metodo di autenticazione è comodo per i test e le valutazioni, ma l'autenticazione a un servizio con Microsoft Entra ID o identità gestite rappresenta un approccio più sicuro. Per altre informazioni, vedere Procedure consigliate per la sicurezza > Sicurezza cloud.

Creare un'identità del dispositivo e un'identità del modulo nell'hub IoT

In questa sezione verrà creata un'app per servizi Python che crea un'identità del dispositivo e un'identità del modulo nel registro delle identità nell'hub IoT. Un dispositivo o un modulo non può connettersi all'hub IoT a meno che non sia presente una voce nel registro delle identità. Per altre informazioni, vedere Informazioni sul registro delle identità nell'hub IoT. Quando si esegue questa app console vengono generati un ID e una chiave univoci sia per il dispositivo che per il modulo. L'ID e la chiave fanno distinzione tra maiuscole e minuscole. Il dispositivo e il modulo usano questi valori per identificarsi quando inviano messaggi da dispositivo a cloud all'hub IoT.

Importante

Questo articolo include la procedura per connettere un dispositivo usando una firma di accesso condiviso, altrimenti chiamata autenticazione con chiave simmetrica. Questo metodo di autenticazione è comodo per i test e le valutazioni, ma l'autenticazione tramite certificati X.509 rappresenta un approccio più sicuro. Per scoprire di più, vedere Procedure consigliate per la sicurezza > Sicurezza della connessione.

Al prompt dei comandi eseguire il comando seguente per installare il pacchetto azure-iot-hub:
```
pip install azure-iot-hub
```
Al prompt dei comandi eseguire il comando seguente per installare il pacchetto msrest. Questo pacchetto è necessario per intercettare le eccezioni di tipo HTTPOperationError.
```
pip install msrest
```
Usando un editor di testo, creare un file denominato CreateModule.py nella directory di lavoro.

Aggiungere il codice seguente al file Python. Sostituire YourIoTHubConnectionString con la stringa di connessione copiata in Ottenere la stringa di connessione dell'hub 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")

Al prompt dei comandi eseguire il comando seguente:
```
python CreateModule.py
```

Questa app crea un'identità del dispositivo con ID myFirstDevice e un'identità del modulo con ID myFirstModule per il dispositivo myFirstDevice. Se il dispositivo o l'ID modulo esiste già nel registro delle identità, il codice recupera semplicemente le informazioni esistenti sul dispositivo o sul modulo. L'app visualizza l'ID e la chiave primaria per ogni identità.

Nota

Il registro delle identità dell'hub IoT archivia solo le identità del dispositivo e del modulo per abilitare l'accesso sicuro all'hub. Il registro delle identità archivia gli ID dispositivo e le chiavi da usare come credenziali di sicurezza. Il registro delle identità archivia anche un flag di abilitazione/disabilitazione per ogni dispositivo che consente di disabilitare l'accesso per un dispositivo. Se l'applicazione deve archiviare altri metadati specifici del dispositivo, dovrà usare un archivio specifico dell'applicazione. Non esiste alcun flag abilitato/disabilitato per le identità del modulo. Per altre informazioni, vedere Informazioni sul registro delle identità nell'hub IoT.

Aggiornare il modulo gemello usando l'SDK per servizi Python

In questa sezione verrà creata un'app per servizi Python che aggiorna le proprietà desiderate del modulo gemello.

Al prompt dei comandi eseguire il comando seguente per installare il pacchetto azure-iot-hub. È possibile ignorare questo passaggio se il pacchetto azure-iot-hub è stato installato nella sezione precedente.
```
pip install azure-iot-hub
```
Usando un editor di testo, creare un file denominato UpdateModuleTwinDesiredProperties.py nella directory di lavoro.

Aggiungere il codice seguente al file Python. Sostituire YourIoTHubConnectionString con la stringa di connessione copiata in Ottenere la stringa di connessione dell'hub 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" )

Ottenere aggiornamenti sul lato dispositivo

In questa sezione verrà creata un'app Python per ottenere l'aggiornamento delle proprietà desiderate del modulo gemello nel dispositivo.

Ottenere la stringa di connessione del modulo. Nel portale di Azure passare all'hub IoT e selezionare Dispositivi nel riquadro sinistro. Selezionare myFirstDevice nell'elenco dei dispositivi e aprirlo. In Identità del moduloselezionare myFirstModule. Selezionare l'icona di copia per Stringa di connessione (chiave primaria). Questa stringa di connessione sarà necessaria in un passaggio successivo.
Al prompt dei comandi eseguire il comando seguente per installare il pacchetto azure-iot-device:
```
pip install azure-iot-device
```
Usando un editor di testo, creare un file denominato ReceiveModuleTwinDesiredPropertiesPatch.py nella directory di lavoro.

Aggiungere il codice seguente al file Python. Sostituire YourModuleConnectionString con la stringa di connessione del modulo copiata nel passaggio 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()

Eseguire le app

In questa sezione si esegue l'app per dispositivi ReceiveModuleTwinDesiredPropertiesPatch e quindi si esegue l'app per servizi UpdateModuleTwinDesiredProperties per aggiornare le proprietà desiderate del modulo.

Aprire un prompt dei comandi ed eseguire l'app per dispositivi:
```
python ReceiveModuleTwinDesiredPropertiesPatch.py
```
Aprire un prompt dei comandi separato ed eseguire l'app per servizi:
```
python UpdateModuleTwinDesiredProperties.py
```
Si noti che la proprietà TelemetryInterval desiderata viene visualizzata nel modulo gemello aggiornato nell'output dell'app per servizi:

La stessa proprietà viene visualizzata nella patch delle proprietà desiderata ricevuta nell'output dell'app per dispositivi: