Introduzione alle identità dei moduli di hub IoT e ai dispositivi gemelli di identità dei moduli

• Richiede Visual Studio

Panoramica

Questo articolo descrive come usare Azure IoT SDK per .NET per creare il codice dell'applicazione del servizio back-end e del dispositivo per i moduli gemelli di identità.

Creare un'applicazione per dispositivi

Questa sezione descrive come usare il codice dell'applicazione per dispositivi per:

• Recuperare un dispositivo gemello identità del modulo ed esaminare le proprietà segnalate
• Aggiornare le proprietà del dispositivo gemello dell'identità del modulo segnalato
• Creare un gestore di callback per l'aggiornamento della proprietà desiderato del modulo

Pacchetto NuGet del dispositivo richiesto

Per le applicazioni client per dispositivi scritte in C# è necessario il pacchetto NuGet Microsoft.Azure.Devices.Client.

Aggiungere queste using istruzioni per usare la libreria di dispositivi.

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

Connettersi a un dispositivo

La classe ModuleClient espone tutti i metodi necessari per interagire con i dispositivi gemelli di identità del modulo dal dispositivo.

Connettersi al dispositivo usando il metodo CreateFromConnectionString con l'identità del modulo stringa di connessione.

La chiamata CreateFromConnectionString senza un parametro di trasporto si connette utilizzando il trasporto AMQP predefinito.

Questo esempio si connette al dispositivo usando il trasporto AMQP predefinito.

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Recuperare un modulo gemello di identità ed esaminare le proprietà

Chiamare GetTwinAsync per recuperare le proprietà del dispositivo gemello dell'identità del modulo corrente in un oggetto Twin .

In questo esempio vengono recuperate e visualizzate le proprietà del dispositivo gemello dell'identità del modulo in formato JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

Aggiornare le proprietà segnalate del dispositivo gemello dell'identità del modulo

Per aggiornare una proprietà segnalata del dispositivo gemello:

1. Creare un oggetto TwinCollection per l'aggiornamento della proprietà segnalata
2. Aggiornare una o più proprietà segnalate all'interno dell'oggetto TwinCollection
3. Usare UpdateReportedPropertiesAsync per eseguire il push delle modifiche alle proprietà segnalate al servizio hub IoT

Ad esempio:

try
{
  Console.WriteLine("Sending sample start time as reported property");
  TwinCollection reportedProperties = new TwinCollection();
  reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
  await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Creare un gestore di callback di aggiornamento delle proprietà desiderate

Passare il nome del metodo del gestore di callback a SetDesiredPropertyUpdateCallbackAsync per creare un gestore di callback di aggiornamento delle proprietà desiderato che viene eseguito quando una proprietà desiderata viene modificata nell'identità del modulo gemello.

Ad esempio, questa chiamata configura il sistema per notificare a un metodo denominato OnDesiredPropertyChangedAsync ogni volta che viene modificata una proprietà del modulo desiderata.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Le proprietà del dispositivo gemello identity del modulo vengono passate al metodo di callback come TwinCollection e possono essere esaminate come KeyValuePair strutture.

Questo esempio riceve gli aggiornamenti delle proprietà desiderate come TwinCollection, quindi scorre e visualizza gli aggiornamenti della raccolta KeyValuePair. Dopo lo scorrimento della raccolta KeyValuePair, il codice chiama UpdateReportedPropertiesAsync per aggiornare la proprietà segnalata DateTimeLastDesiredPropertyChangeReceived in modo da mantenere aggiornata l'ora dell'ultimo aggiornamento.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Esempio di modulo SDK

Azure IoT SDK per .NET fornisce esempi funzionanti di app per dispositivi che gestiscono le attività dei moduli gemelli di identità. Per altre informazioni, vedi:

• TwinSample
• Test client del dispositivo

Creare un'applicazione back-end

Questa sezione descrive come leggere e aggiornare i campi identity del modulo.

La classe RegistryManager espone tutti i metodi necessari per creare un'applicazione back-end per interagire con i dispositivi gemelli di identità del modulo dal servizio.

Pacchetto NuGet del servizio richiesto

Le applicazioni di servizio back-end richiedono il pacchetto NuGet Microsoft.Azure.Devices.

Aggiungere queste using istruzioni per usare la libreria di servizi.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

Connettersi all'hub IoT

È possibile connettere un servizio back-end a hub IoT usando i metodi seguenti:

• Criteri di accesso condiviso
• Microsoft Entra

Connettersi usando criteri di accesso condiviso

Connettere un'applicazione back-end all'hub IoT usando CreateFromConnectionString.

Il UpdateModuleAsync metodo usato in questa sezione richiede l'autorizzazione dei criteri di accesso condiviso di Service Connect per aggiungere le proprietà desiderate a un modulo. Come parametro per CreateFromConnectionString, fornire un criterio di accesso condiviso stringa di connessione che include l'autorizzazione Service Connect. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

Ad esempio:

static RegistryManager registryManager;
static string connectionString = "{IoT hub shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Connettersi con Microsoft Entra

Un'app back-end che usa Microsoft Entra deve eseguire correttamente l'autenticazione e ottenere le credenziali del token di sicurezza prima di connettersi a hub IoT. Questo token viene passato a un metodo di connessione hub IoT. Per informazioni generali sulla configurazione e l'uso di Microsoft Entra per hub IoT, vedere Controllare l'accesso alle hub IoT tramite Microsoft Entra ID.

Configurare l'app Microsoft Entra

È necessario configurare un'app Microsoft Entra configurata per le credenziali di autenticazione preferite. L'app contiene parametri come il segreto client usato dall'applicazione back-end per l'autenticazione. Le configurazioni di autenticazione delle app disponibili sono:

• Segreto client
• Certificate
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, hub IoT Collaboratore gemello è necessario per abilitare l'accesso in lettura e scrittura a un dispositivo e a moduli gemelli hub IoT. Per altre informazioni, vedere Gestire l'accesso alle hub IoT usando l'assegnazione di ruolo controllo degli accessi in base al ruolo di Azure.

Per altre informazioni sulla configurazione di un'app Microsoft Entra, vedere Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

Eseguire l'autenticazione con DefaultAzureCredential

Il modo più semplice per usare Microsoft Entra per autenticare un'applicazione back-end consiste nell'usare DefaultAzureCredential, ma è consigliabile usare un metodo diverso in un ambiente di produzione, incluso un oggetto specifico TokenCredential o ridotto.ChainedTokenCredential Per semplicità, questa sezione descrive l'autenticazione tramite DefaultAzureCredential e il segreto client. Per altre informazioni sui vantaggi e sui svantaggi dell'uso DefaultAzureCredentialdi , vedere Linee guida sull'utilizzo per DefaultAzureCredential.

DefaultAzureCredential supporta meccanismi di autenticazione diversi e determina il tipo di credenziale appropriato in base all'ambiente in cui è in esecuzione. Tenta di usare più tipi di credenziali in un ordine fino a quando non trova una credenziale funzionante.

Microsoft Entra richiede questi pacchetti NuGet e le istruzioni corrispondenti using :

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

In questo esempio, il segreto client di registrazione dell'app Microsoft Entra, l'ID client e l'ID tenant vengono aggiunti alle variabili di ambiente. Queste variabili di ambiente vengono usate da DefaultAzureCredential per autenticare l'applicazione. Il risultato di un'autenticazione di Microsoft Entra riuscita è una credenziale del token di sicurezza passata a un metodo di connessione hub IoT.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

TokenCredential risultante può quindi essere passato a una connessione a un metodo di hub IoT per qualsiasi client SDK che accetta le credenziali di Microsoft Entra:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

In questo esempio viene passato a ServiceClient.Create per creare un oggetto connessione ServiceClient.TokenCredential

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

In questo esempio viene TokenCredential passato a RegistryManager.Create per creare un oggetto RegistryManager .

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Esempio di codice

Per un esempio funzionante dell'autenticazione del servizio Microsoft Entra, vedere Esempio di autenticazione basata su ruoli.

Leggere e aggiornare i campi identity del modulo

Chiamare GetModuleAsync per recuperare i campi gemelli dell'identità del modulo corrente in un oggetto Module .

La Module classe include properties che corrispondono alle sezioni di un modulo gemello identity. Usare le proprietà della classe Module per visualizzare e aggiornare i campi del modulo gemello Identity. È possibile usare le proprietà dell'oggetto Module per aggiornare più campi prima di scrivere gli aggiornamenti nel dispositivo usando UpdateModuleAsync.

Dopo aver apportato gli aggiornamenti dei campi identity twin del modulo, chiama UpdateModuleAsync per scrivere Module gli aggiornamenti dei campi oggetto in un dispositivo. Usare la logica try e catch abbinata a un gestore errori per rilevare errori di patch formattate in modo errato da UpdateModuleAsync.

Questo esempio recupera un modulo in un Module oggetto, aggiorna la module LastActivityTime proprietà e quindi aggiorna il modulo in hub IoT usando UpdateModuleAsync.

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateModuleAsync(module);
}
catch (Exception e)
{
   console.WriteLine("Module update failed.", e.Message);
}

Altre API del modulo

• GetModulesOnDeviceAsync : recupera le identità del modulo in un dispositivo
• RemoveModuleAsync - Elimina un modulo registrato in precedenza da un dispositivo

Esempio di SDK per servizi

Azure IoT SDK per .NET fornisce un esempio funzionante di un'app del servizio che gestisce le attività dei moduli gemelli di identità. Per altre informazioni, vedere Test E2E di Registry Manager.

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

Panoramica

Questo articolo descrive come usare Azure IoT SDK per Python per creare il codice dell'applicazione del servizio back-end e del dispositivo per i moduli gemelli di identità.

Installare i pacchetti

Per creare applicazioni per dispositivi, è necessario installare la libreria azure-iot-device .

pip install azure-iot-device

Per creare applicazioni di servizio back-end, è necessario installare la libreria azure-iot-hub .

pip install azure-iot-hub

La libreria msrest viene usata per rilevare le eccezioni HTTPOperationError.

pip install msrest

Creare un'applicazione per dispositivi

Questa sezione descrive come usare il codice dell'applicazione per dispositivi per:

• Recuperare un dispositivo gemello identità del modulo ed esaminare le proprietà segnalate
• Aggiornare le proprietà segnalate del dispositivo gemello dell'identità del modulo
• Creare un gestore di callback dell'aggiornamento della proprietà desiderata dell'identità del modulo gemello

Istruzioni Import

Aggiungere questa import istruzione per usare la libreria di dispositivi.

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

Connettersi a un dispositivo

La classe IoTHubModuleClient contiene metodi che possono essere usati per lavorare con i dispositivi gemelli di identità del modulo.

Per connettere un'applicazione a un dispositivo:

1. Chiamare create_from_connection_string per aggiungere l'identità del modulo stringa di connessione
2. Chiamare connect per connettere il client del dispositivo a un hub IoT di Azure

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{Device module identity connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

Recuperare un modulo gemello di identità ed esaminare le proprietà

Chiamare get_twin per recuperare l'identità del modulo gemello dal servizio hub IoT di Azure. Le informazioni sul gemello vengono inserite in una variabile che può essere esaminata.

Questo esempio recupera il dispositivo gemello e usa il comando print per visualizzarlo in formato JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Aggiornare le proprietà segnalate del dispositivo gemello dell'identità del modulo

È possibile applicare una patch per aggiornare le proprietà segnalate del dispositivo gemello dell'identità del modulo in formato JSON.

Per applicare una patch al fine di aggiornare le proprietà segnalate:

1. Assegnare una patch JSON per le proprietà segnalate a una variabile.
2. Chiamare patch_twin_reported_properties per applicare la patch JSON alle proprietà segnalate.

Ad esempio:

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

Creare un gestore di callback dell'aggiornamento della proprietà desiderata dell'identità del modulo gemello

Chiamare on_twin_desired_properties_patch_received per creare una funzione del gestore o una coroutine chiamata quando viene ricevuta una patch delle proprietà desiderate di un'identità del modulo gemello. Il gestore accetta un solo argomento, ovvero la patch del dispositivo gemello sotto forma di oggetto dizionario JSON.

Questo esempio configura un gestore patch delle proprietà desiderate denominato twin_patch_handler.

Ad esempio:

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

twin_patch_handler riceve e visualizza gli aggiornamenti delle proprietà desiderate in formato JSON.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

Esempi di SDK per dispositivi

Azure IoT SDK per Python offre un esempio funzionante di app per dispositivi che gestiscono le attività dei moduli gemelli di identità:

• get_twin - Si connette a un dispositivo e recupera le informazioni sul dispositivo gemello.
• update_twin_reported_properties - Aggiorna le proprietà segnalate del dispositivo gemello.
• receive_twin_desired_properties - Riceve e aggiorna le proprietà desiderate.

Creare un'applicazione back-end

Questa sezione descrive come creare un'applicazione back-end per recuperare e aggiornare le proprietà desiderate dell'identità del modulo gemello.

La classe IoTHubRegistryManager espone tutti i metodi necessari per creare un'applicazione back-end per interagire con i dispositivi gemelli di identità del modulo dal servizio.

Istruzioni di importazione del servizio

Aggiungere questa import istruzione per usare la libreria di servizi.

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

Connettersi all'hub IoT

È possibile connettere un servizio back-end a hub IoT usando i metodi seguenti:

• Criteri di accesso condiviso
• Microsoft Entra

Connettersi usando criteri di accesso condiviso

Connettersi all'hub IoT mediante from_connection_string.

Il update_module_twin metodo usato in questa sezione richiede l'autorizzazione dei criteri di accesso condiviso di Service Connect per aggiungere le proprietà desiderate a un modulo. Come parametro per from_connection_string, fornire un criterio di accesso condiviso stringa di connessione che include l'autorizzazione Service Connect. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

Ad esempio:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub shared access policy connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Connettersi con Microsoft Entra

Un'app back-end che usa Microsoft Entra deve eseguire correttamente l'autenticazione e ottenere le credenziali del token di sicurezza prima di connettersi a hub IoT. Questo token viene passato a un metodo di connessione hub IoT. Per informazioni generali sulla configurazione e l'uso di Microsoft Entra per hub IoT, vedere Controllare l'accesso alle hub IoT tramite Microsoft Entra ID.

Per una panoramica dell'autenticazione di Python SDK, vedere Autenticare le app Python nei servizi di Azure usando Azure SDK per Python

Configurare l'app Microsoft Entra

È necessario configurare un'app Microsoft Entra configurata per le credenziali di autenticazione preferite. L'app contiene parametri come il segreto client usato dall'applicazione back-end per l'autenticazione. Le configurazioni di autenticazione delle app disponibili sono:

• Segreto client
• Certificate
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, hub IoT Collaboratore gemello è necessario per abilitare l'accesso in lettura e scrittura a un dispositivo e a moduli gemelli hub IoT. Per altre informazioni, vedere Gestire l'accesso alle hub IoT usando l'assegnazione di ruolo controllo degli accessi in base al ruolo di Azure.

Per altre informazioni sulla configurazione di un'app Microsoft Entra, vedere Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

Eseguire l'autenticazione con DefaultAzureCredential

Il modo più semplice per usare Microsoft Entra per autenticare un'applicazione back-end consiste nell'usare DefaultAzureCredential, ma è consigliabile usare un metodo diverso in un ambiente di produzione, incluso un oggetto specifico TokenCredential o ridotto.ChainedTokenCredential Per semplicità, questa sezione descrive l'autenticazione tramite DefaultAzureCredential e il segreto client. Per altre informazioni sui vantaggi e sui svantaggi dell'uso DefaultAzureCredentialdi , vedere Catene di credenziali nella libreria client di Identità di Azure per Python.

DefaultAzureCredential supporta meccanismi di autenticazione diversi e determina il tipo di credenziale appropriato in base all'ambiente in cui è in esecuzione. Tenta di usare più tipi di credenziali in un ordine fino a quando non trova una credenziale funzionante.

Microsoft Entra richiede questo pacchetto di importazione e l'istruzione corrispondente import :

pip install azure-identity

from azure.identity import DefaultAzureCredential

In questo esempio, il segreto client di registrazione dell'app Microsoft Entra, l'ID client e l'ID tenant sono stati aggiunti alle variabili di ambiente. Queste variabili di ambiente vengono usate da DefaultAzureCredential per autenticare l'applicazione. Il risultato di un'autenticazione di Microsoft Entra riuscita è una credenziale del token di sicurezza passata a un metodo di connessione hub IoT.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

L'oggetto AccessToken risultante può quindi essere passato a per connettersi from_token_credential a hub IoT per qualsiasi client SDK che accetta le credenziali di Microsoft Entra:

• IoTHubRegistryManager per creare una connessione al servizio per hub IoT usando le credenziali del token Entra.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

from_token_credential richiede due parametri:

• URL del servizio di Azure: l'URL del servizio di Azure deve essere nel formato {Your Entra domain URL}.azure-devices.net senza un https:// prefisso. Ad esempio: MyAzureDomain.azure-devices.net.
• Token delle credenziali di Azure

In questo esempio, le credenziali di Azure vengono ottenute usando DefaultAzureCredential. L'URL e le credenziali del servizio di Azure vengono quindi forniti per IoTHubRegistryManager.from_token_credential creare la connessione a hub IoT.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

Esempi di codice

Per esempi di utilizzo dell'autenticazione del servizio Microsoft Entra, vedere Microsoft Authentication Library (MSAL) per Python.

Recuperare e aggiornare le proprietà desiderate dell'identità del modulo gemello

È possibile aggiornare le proprietà desiderate da un'applicazione back-end usando update_module_twin.

Per recuperare e aggiornare le proprietà desiderate dell'identità del modulo gemello:

1. Chiamare get_module_twin per ottenere la versione corrente dell'identità del modulo gemello.
2. Usare la classe Twin per aggiungere le proprietà desiderate in formato JSON.
3. Chiamare update_module_twin per applicare la patch al dispositivo gemello. È anche possibile usare replace_module_twin per sostituire le proprietà e i tag desiderati per un dispositivo gemello di identità del modulo.

In questo esempio la telemetryInterval proprietà desiderata viene aggiornata a 122.

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity 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 identity 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" )

Esempio di SDK per servizi

Azure IoT SDK per Python fornisce un esempio funzionante di un'app del servizio che gestisce le attività del modulo gemello del modulo di identità del dispositivo. Per altre informazioni, vedere Test IoTHub Registry Manager.For more information, see Test IoTHub Registry Manager.

• Richiede Node.js versione 10.0.x o successiva

Panoramica

Questo articolo descrive come usare Azure IoT SDK per Node.js per creare il codice dell'applicazione del servizio back-end e del dispositivo per i moduli gemelli di identità.

Creare un'applicazione per dispositivi

Questa sezione descrive come usare il pacchetto azure-iot-device in Azure IoT SDK per Node.js per creare un’applicazione per dispositivi al fine di:

• Recuperare un dispositivo gemello identità del modulo ed esaminare le proprietà segnalate
• Aggiornare le proprietà segnalate dell'identità del modulo gemello
• Ricevere una notifica di modifica della proprietà desiderata dell'identità del modulo gemello

Il pacchetto azure-iot-device contiene oggetti che si interfacciano con i dispositivi IoT. La classe twin include oggetti specifici del dispositivo gemello. Questa sezione descrive il Client codice di classe usato per leggere e scrivere dati di identità del modulo dispositivo gemello.

Installare il pacchetto SDK

Eseguire questo comando per installare l’SDK per dispositivi azure-iot-device nel computer di sviluppo:

npm install azure-iot-device --save

Connettere un dispositivo all'hub IoT

Un'app per dispositivi può eseguire l'autenticazione con hub IoT usando i metodi seguenti:

• Chiave di accesso condiviso
• Certificato X.509

Eseguire l'autenticazione con una chiave di accesso condiviso

Scegliere un protocollo di trasporto

L'oggetto Client supporta i protocolli seguenti:

• Amqp
• Http: quando si usa Http, l'istanza Client verifica con scarsa frequenza la presenza di messaggi provenienti dall'hub IoT (almeno ogni 25 minuti).
• Mqtt
• MqttWs
• AmqpWs

Installare i protocolli di trasporto necessari nel computer di sviluppo.

Ad esempio, questo comando installa il protocollo Amqp:

npm install azure-iot-device-amqp --save

Per altre informazioni sulle differenze tra il supporto MQTT, AMQP e HTTPS, vedere Linee guida per le comunicazioni da cloud a dispositivo e Scegliere un protocollo di comunicazione del dispositivo.

Creare un oggetto client

Creare un Client oggetto usando il pacchetto installato.

Ad esempio:

const Client = require('azure-iot-device').Client;

Creare un oggetto protocollo

Creare un Protocol oggetto usando un pacchetto di trasporto installato.

In questo esempio viene assegnato il protocollo AMQP:

const Protocol = require('azure-iot-device-amqp').Amqp;

Aggiungere la stringa di connessione del dispositivo e il protocollo di trasporto

Chiamare fromConnectionString per specificare i parametri di connessione del dispositivo:

• connStr: modulo identity dell'hub IoT stringa di connessione.
• transportCtor: protocollo di trasporto.

Questo esempio usa il protocollo di trasporto Amqp:

const deviceConnectionString = "{IoT hub identity module connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Aprire la connessione all'hub IoT

Usare il metodo open per aprire una connessione tra un dispositivo IoT e l'hub IoT.

Ad esempio:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Eseguire l'autenticazione con un certificato X.509

Il certificato X.509 è collegato al trasporto di connessione da dispositivo a hub IoT.

Per configurare una connessione da dispositivo a hub IoT usando un certificato X.509:

1. Chiamare daConnectionString per aggiungere il modulo device o identity stringa di connessione e il tipo di trasporto all'oggettoClient. Aggiungere x509=true al stringa di connessione per indicare che un certificato viene aggiunto a DeviceClientOptions. Ad esempio:

   • Un dispositivo stringa di connessione:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

   • Un modulo identity stringa di connessione:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

2. Configurare una variabile JSON con i dettagli del certificato e passarla a DeviceClientOptions.

3. Chiamare setOptions per aggiungere un certificato e una chiave X.509 (e, facoltativamente, passphrase) al trasporto client.

4. Chiamare open per aprire la connessione dal dispositivo per hub IoT.

Questo esempio mostra le informazioni di configurazione del certificato all'interno di una variabile JSON. La configurazione clientOptions della certificazione viene passata a setOptionse la connessione viene aperta usando open.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

Per altre informazioni sull'autenticazione del certificato, vedere:

• Autenticare le identità con certificati X.509
• Creare e caricare certificati per i test

Esempio di codice

Per un esempio funzionante dell'autenticazione del certificato X.509 del dispositivo, vedere Dispositivo di esempio semplice X.509.

Recuperare un dispositivo gemello identità del modulo ed esaminare le proprietà segnalate

Chiamare getTwin per recuperare le informazioni sul gemello dell'identità del modulo corrente in un oggetto Twin .

Il codice del dispositivo può quindi accedere alle proprietà del dispositivo gemello dell'identità del modulo.

Ad esempio:

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

Aggiornare le proprietà segnalate del dispositivo gemello dell'identità del modulo

Usare update per aggiornare le proprietà segnalate del dispositivo. Includere una patch in formato JSON come primo parametro e il metodo di callback dello stato di esecuzione della funzione come secondo parametro del metodo.

In questo esempio, nella variabile viene archiviata patch una patch di identità del modulo gemello in formato JSON. La patch contiene un valore di aggiornamento dell'identità del modulo gemello connectivity pari a cellular. La patch e il gestore errori vengono passati al metodo update. In caso di errore, viene visualizzato un messaggio di errore della console.

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Ricevere una notifica di modifica della proprietà desiderata dell'identità del modulo gemello

Creare un listener di eventi di aggiornamento delle proprietà desiderato dell'identità del modulo gemello che viene eseguito quando viene modificata una proprietà desiderata passando il nome del metodo del gestore di callback a twin.on.

Il listener di eventi di proprietà desiderato può assumere i formati seguenti:

• Ricevere tutte le patch con un solo gestore eventi
• Ricevere un evento se qualcosa cambia in un raggruppamento di proprietà
• Ricevere un evento per la modifica di una singola proprietà

Ricevere tutte le patch con un solo gestore eventi

È possibile creare un listener per ricevere qualsiasi modifica alle proprietà desiderate.

Questo codice di esempio restituisce tutte le proprietà ricevute dal servizio.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Ricevere un evento se qualcosa cambia in un raggruppamento di proprietà

È possibile creare un listener per ricevere un evento se cambia qualcosa in un raggruppamento di proprietà.

Ad esempio:

1. Le proprietà minTemperature e maxTemperature sono contenute in un raggruppamento di proprietà denominato properties.desired.climate changes.

2. Un'applicazione del servizio back-end applica questa patch per aggiornare le proprietà desiderate minTemperature e maxTemperature:

   const twinPatch1 = {
   properties: {
      desired: {
       climate: { minTemperature: 68, maxTemperature: 76, },
       },
     },
    };
   

3. Questo codice configura un listener di eventi di modifica della proprietà desiderato che attiva tutte le modifiche all'interno del raggruppamento di properties.desired.climate proprietà. Se è presente una modifica della proprietà desiderata all'interno di questo gruppo, nella console vengono visualizzati i messaggi di modifica della temperatura minima e massima:

   twin.on('properties.desired.climate', function (delta) {
       if (delta.minTemperature || delta.maxTemperature) {
           console.log('updating desired temp:');
           console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
           console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
       }
   });
   

Ricevere un evento per la modifica di una singola proprietà

È possibile configurare un listener per una singola modifica di proprietà. In questo esempio, il codice di questo evento viene eseguito solo se il valore booleano fanOn fa parte della patch. Il codice restituisce il nuovo stato della proprietà desiderata fanOn ogni volta che il servizio lo aggiorna.

1. Un'applicazione back-end applica questa patch della proprietà desiderata:

    const twinPatch2 = {
     properties: {
       desired: {
         climate: {
           hvac: {
             systemControl: { fanOn: true, },
           },
         },
       },
     },
   };
   

2. Il listener viene attivato solo quando la proprietà fanOn cambia:

    twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
        console.log('setting fan state to ' + fanOn);
     });
   

Esempio completo

In questo esempio vengono incapsulati i principi di questa sezione, inclusa l'annidamento delle funzioni di callback a più livelli.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

Esempi di SDK per dispositivi

Azure IoT SDK per Node.js fornisce esempi funzionanti di app per dispositivi che gestiscono le attività dei moduli gemelli di identità. Per altre informazioni, vedi:

• Identità del modulo gemello
• Helper test del modulo
• Test di e2e gemelli

Creare un'applicazione back-end

Questa sezione descrive come creare un'applicazione back-end che recupera un'identità del modulo gemello e aggiorna le proprietà desiderate.

Installare il pacchetto SDK del servizio

Eseguire questo comando per installare azure-iothub nel computer di sviluppo:

npm install azure-iothub --save

Creare un oggetto Registry

La classe Registry espone tutti i metodi necessari per interagire con i dispositivi gemelli di identità del modulo da un'applicazione back-end.

let Registry = require('azure-iothub').Registry;

Connettersi all'hub IoT

È possibile connettere un servizio back-end a hub IoT usando i metodi seguenti:

• Criteri di accesso condiviso
• Microsoft Entra

Connettersi usando criteri di accesso condiviso

Usare fromConnectionString per connettersi all'hub IoT.

Il update metodo usato in questa sezione richiede l'autorizzazione dei criteri di accesso condiviso di Service Connect per aggiungere le proprietà desiderate a un modulo. Come parametro per fromConnectionString, fornire un criterio di accesso condiviso stringa di connessione che include l'autorizzazione Service Connect. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

Connettersi con Microsoft Entra

Un'app back-end che usa Microsoft Entra deve eseguire correttamente l'autenticazione e ottenere le credenziali del token di sicurezza prima di connettersi a hub IoT. Questo token viene passato a un metodo di connessione hub IoT. Per informazioni generali sulla configurazione e l'uso di Microsoft Entra per hub IoT, vedere Controllare l'accesso alle hub IoT tramite Microsoft Entra ID.

Per una panoramica dell'autenticazione Node.js SDK, vedere:

• Introduzione all'autenticazione utente in Azure
• Libreria client di Identità di Azure per JavaScript

Configurare l'app Microsoft Entra

È necessario configurare un'app Microsoft Entra configurata per le credenziali di autenticazione preferite. L'app contiene parametri come il segreto client usato dall'applicazione back-end per l'autenticazione. Le configurazioni di autenticazione delle app disponibili sono:

• Segreto client
• Certificate
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, hub IoT Collaboratore gemello è necessario per abilitare l'accesso in lettura e scrittura a un dispositivo e a moduli gemelli hub IoT. Per altre informazioni, vedere Gestire l'accesso alle hub IoT usando l'assegnazione di ruolo controllo degli accessi in base al ruolo di Azure.

Per altre informazioni sulla configurazione di un'app Microsoft Entra, vedere Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

Eseguire l'autenticazione con DefaultAzureCredential

Il modo più semplice per usare Microsoft Entra per autenticare un'applicazione back-end consiste nell'usare DefaultAzureCredential, ma è consigliabile usare un metodo diverso in un ambiente di produzione, incluso un oggetto specifico TokenCredential o ridotto.ChainedTokenCredential Per semplicità, questa sezione descrive l'autenticazione tramite DefaultAzureCredential e il segreto client. Per altre informazioni sui vantaggi e sui svantaggi dell'uso DefaultAzureCredentialdi , vedere Catene di credenziali nella libreria client di Identità di Azure per JavaScript

DefaultAzureCredential supporta meccanismi di autenticazione diversi e determina il tipo di credenziale appropriato in base all'ambiente in cui è in esecuzione. Tenta di usare più tipi di credenziali in un ordine fino a quando non trova una credenziale funzionante.

Microsoft Entra richiede questo pacchetto:

npm install --save @azure/identity

In questo esempio, il segreto client di registrazione dell'app Microsoft Entra, l'ID client e l'ID tenant sono stati aggiunti alle variabili di ambiente. Queste variabili di ambiente vengono usate da DefaultAzureCredential per autenticare l'applicazione. Il risultato di un'autenticazione di Microsoft Entra riuscita è una credenziale del token di sicurezza passata a un metodo di connessione hub IoT.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Il token delle credenziali risultante può quindi essere passato a fromTokenCredential per connettersi a hub IoT per qualsiasi client SDK che accetta le credenziali di Microsoft Entra:

• Registro
• Client
• JobClient

fromTokenCredential richiede due parametri:

• URL del servizio di Azure: l'URL del servizio di Azure deve essere nel formato {Your Entra domain URL}.azure-devices.net senza un https:// prefisso. Ad esempio: MyAzureDomain.azure-devices.net.
• Token delle credenziali di Azure

In questo esempio, le credenziali di Azure vengono ottenute usando DefaultAzureCredential. L'URL e le credenziali del dominio di Azure vengono quindi forniti per Registry.fromTokenCredential creare la connessione a hub IoT.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Esempi di codice

Per esempi di utilizzo dell'autenticazione del servizio Microsoft Entra, vedere Esempi di identità di Azure.

Recuperare un modulo gemello identità e aggiornare le proprietà desiderate

È possibile creare una patch contenente gli aggiornamenti delle proprietà desiderati per un modulo gemello di identità.

Per aggiornare un modulo gemello identity:

1. Chiamare getModuleTwin per recuperare l'oggetto dispositivo Gemello.

2. Formattare una patch contenente l'aggiornamento del dispositivo gemello dell'identità del modulo. La patch è in formato JSON come descritto in Classe Twin. Una patch del servizio back-end contiene gli aggiornamenti delle proprietà desiderati. Per altre informazioni sul formato delle patch, vedere Formato di tag e proprietà.

3. Chiamare l'aggiornamento per aggiornare l'identità del modulo gemello con la patch.

In questo esempio l'identità del modulo gemello viene recuperata per myDeviceId e myModuleId. Viene quindi applicata una patch ai gemelli che contengono climate informazioni.

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

Esempi di Service SDK

Azure IoT SDK per Node.js fornisce esempi funzionanti di app del servizio che gestiscono le attività dei moduli gemelli di identità. Per altre informazioni, vedi:

• Identità del modulo gemello
• Helper test del modulo
• Test di e2e gemelli