Condividi tramite

Introduzione ai dispositivi gemelli

  • Articolo

Usare l'SDK per dispositivi e l'SDK per servizi dell'hub IoT di Azure per sviluppare applicazioni che gestiscono attività comuni dei dispositivi gemelli. I dispositivi gemelli sono documenti JSON che archiviano informazioni sullo stato dei dispositivi, tra cui metadati, configurazioni e condizioni. L'hub IoT rende permanente un dispositivo gemello per ogni dispositivo che si connette.

È possibile usare i dispositivi gemelli per:

  • Archiviare i metadati dei dispositivi dal back-end della soluzione
  • Segnalare informazioni sullo stato corrente, come funzionalità disponibili e condizioni (ad esempio, il metodo di connettività usato) dall'app per dispositivi
  • Sincronizzare lo stato dei flussi di lavoro a esecuzione prolungata (come gli aggiornamenti del firmware e della configurazione) tra un'app per dispositivi e un'app back-end
  • Eseguire query sui metadati, la configurazione o lo stato dei dispositivi

Per altre informazioni sui dispositivi gemelli, tra cui quando usarli, vedere Comprendere e usare dispositivi gemelli nell'hub IoT.

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.

Questo articolo illustra come sviluppare due tipi di applicazioni:

  • Le app per dispositivi possono gestire le richieste di aggiornamento delle proprietà desiderate e rispondere con modifiche alle proprietà segnalate.
  • Le app di servizio possono aggiornare i tag dei dispositivi gemelli, impostare nuove proprietà desiderate ed eseguire query sui dispositivi in base ai valori dei dispositivi gemelli.

Nota

Questo articolo ha lo scopo di integrare gli esempi degli SDK di Azure IoT a cui si fa riferimento al suo interno. È possibile usare gli strumenti degli SDK per compilare sia applicazioni per dispositivi sia applicazioni back-end.

Prerequisiti

  • Un hub IoT

  • Un dispositivo registrato

  • Se l'applicazione usa il protocollo MQTT, verificare che la porta 8883 sia aperta nel firewall. Il protocollo MQTT comunica infatti sulla porta 8883. Questa porta potrebbe essere bloccata in alcuni ambienti di rete aziendali e didattici. Per altre informazioni e soluzioni alternative per questo problema, vedere Connettersi all'hub IoT (MQTT).

  • Richiede Visual Studio

Panoramica

Questo articolo illustra come usare Azure IoT SDK per .NET per creare codice di applicazioni per dispositivi e del servizio back-end per dispositivi gemelli.

Creare un'applicazione per dispositivi

Le applicazioni per dispositivi possono leggere e scrivere proprietà segnalate dei dispositivi gemelli e ricevere una notifica delle modifiche alle proprietà desiderate dei dispositivi gemelli impostate da un'applicazione back-end o da un hub IoT.

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

  • Recuperare un dispositivo gemello ed esaminare le proprietà segnalate
  • Aggiornare le proprietà segnalate del dispositivo gemello
  • Creare un gestore di callback di aggiornamento delle proprietà desiderate

Pacchetto NuGet del dispositivo richiesto

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

Aggiungere questa using istruzione per usare la libreria di dispositivi.

using Microsoft.Azure.Devices.Client;

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

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.

Eseguire l'autenticazione con una chiave di accesso condiviso

La classe DeviceClient espone tutti i metodi necessari per interagire con i dispositivi gemelli dal dispositivo.

Connettersi al dispositivo usando il metodo CreateFromConnectionString insieme alla stringa di connessione del dispositivo e al protocollo di trasporto della connessione.

Il parametro del protocollo di trasporto TransportType CreateFromConnectionString supporta i protocolli di trasporto seguenti:

  • Mqtt
  • Mqtt_WebSocket_Only
  • Mqtt_Tcp_Only
  • Amqp
  • Amqp_WebSocket_Only
  • Amqp_Tcp_Only

Il protocollo Http1 non è supportato per gli aggiornamenti dei dispositivi gemelli.

Questo esempio si connette a un dispositivo mediante il protocollo di trasporto Mqtt.

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

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Eseguire l'autenticazione con un certificato X.509

Per connettere un dispositivo a hub IoT usando un certificato X.509:

  1. Usare DeviceAuthenticationWithX509Certificate per creare un oggetto contenente informazioni sul dispositivo e sul certificato. DeviceAuthenticationWithX509Certificate viene passato come secondo parametro a DeviceClient.Create (passaggio 2).

  2. Usare DeviceClient.Create per connettere il dispositivo a hub IoT usando un certificato X.509.

In questo esempio le informazioni sul dispositivo e sul certificato vengono popolate nell'oggetto auth DeviceAuthenticationWithX509Certificate passato a DeviceClient.Create.

Questo esempio mostra i valori dei parametri di input del certificato come variabili locali per maggiore chiarezza. In un sistema di produzione archiviare i parametri di input sensibili nelle variabili di ambiente o in un altro percorso di archiviazione più sicuro. Ad esempio, usare Environment.GetEnvironmentVariable("HOSTNAME") per leggere la variabile di ambiente del nome host.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

Per altre informazioni sull'autenticazione del certificato, vedere:

Esempi di codice

Per esempi funzionanti di autenticazione del certificato X.509 del dispositivo, vedere:

Recuperare un dispositivo gemello ed esaminare le proprietà

Chiamare GetTwinAsync per recuperare le proprietà del dispositivo gemello corrente. Esistono numerose proprietà dell'oggetto Twin che possono essere usate per accedere ad aree specifiche dei dati JSON dell’oggetto Twin, tra cui Properties, Status, Tags e Version.

Questo esempio recupera le proprietà del dispositivo gemello e visualizza i valori del dispositivo gemello in formato JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Aggiornare le proprietà segnalate del dispositivo gemello

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

Creare un gestore di callback di aggiornamento delle proprietà desiderate da eseguire quando una proprietà desiderata viene modificata nel dispositivo gemello passando il nome del metodo del gestore di callback a SetDesiredPropertyUpdateCallbackAsync.

Ad esempio, questa chiamata configura il sistema in modo da inviare una notifica a un metodo denominato OnDesiredPropertyChangedAsync ogni volta che viene modificata una proprietà desiderata.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

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

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 _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Esempio di SDK per dispositivi

Azure IoT SDK per .NET offre un esempio funzionante di un'app per dispositivi che gestisce le attività dei dispositivi gemelli. Per altre informazioni, vedere TwinSample.

Creare un'applicazione back-end

Un'applicazione back-end si connette a un dispositivo tramite l'hub IoT e può leggere le proprietà segnalate e desiderate del dispositivo, scrivere le proprietà desiderate del dispositivo ed eseguire query del dispositivo.

Questa sezione descrive come creare il codice dell'applicazione back-end per:

  • Leggere e aggiornare i campi del dispositivo gemello
  • Creare una query del dispositivo gemello

La classe RegistryManager espone tutti i metodi necessari per creare un’applicazione back-end che interagisca con i dispositivi gemelli dal servizio.

Aggiungere il pacchetto NuGet del servizio

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

Connettersi all'hub IoT

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

  • Criteri di accesso condiviso
  • Microsoft Entra

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.

Connettersi usando criteri di accesso condiviso

Connettere un'applicazione back-end a un dispositivo mediante CreateFromConnectionString. L'applicazione necessita dell'autorizzazione di connessione del servizio per modificare le proprietà desiderate di un dispositivo gemello e deve disporre dell'autorizzazione di lettura del Registro di sistema per eseguire query nel Registro di sistema delle identità. Non esiste alcun criterio di accesso condiviso predefinito che contiene solo queste due autorizzazioni, quindi è necessario crearne uno se non esiste già. Specificare questo criterio di accesso condiviso stringa di connessione come parametro a fromConnectionString. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{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:

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 del dispositivo gemello

È possibile recuperare i campi del dispositivo gemello corrente in un oggetto Twin chiamando GetTwinAsync.

La classe Twin include proprietà corrispondenti a ogni sezione di un dispositivo gemello. Usare le proprietà della classe Twin per visualizzare e aggiornare i campi del dispositivo gemello. È possibile usare le proprietà dell'oggetto Twin per aggiornare più campi del dispositivo gemello prima di scrivere gli aggiornamenti nel dispositivo usando UpdateTwinAsync.

Dopo aver aggiornato i campi del dispositivo gemello, chiamare UpdateTwinAsync per riscrivere gli aggiornamenti dei campi dell’oggetto Twin in un dispositivo. Usare la logica try e catch abbinata a un gestore errori per rilevare errori di patch formattate in modo errato da UpdateTwinAsync.

Leggere e aggiornare i tag del dispositivo gemello

Usare la proprietà Tags del dispositivo gemello per leggere e scrivere informazioni sui tag del dispositivo.

Aggiornare i tag usando un oggetto Twin

Questo esempio crea una patch per i tag location, la assegna all'oggetto Twin usando la proprietà Tags e quindi applica la patch mediante UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}
Aggiornare i tag usando una stringa JSON

È possibile creare e applicare una patch di aggiornamento delle informazioni sul dispositivo gemello in formato JSON. L'hub IoT analizza e applica la patch se è formattata correttamente.

Questo esempio chiama GetTwinAsync per recuperare i campi del dispositivo gemello corrente in un oggetto Twin, crea una patch tag in formato JSON con informazioni sulla posizione dell'area e dello stabilimento, quindi chiama UpdateTwinAsync per applicare la patch in modo da aggiornare il dispositivo gemello. Se UpdateTwinAsync non riesce, viene visualizzato un messaggio di errore.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Visualizzare e aggiornare le proprietà desiderate del dispositivo gemello

Usare la proprietà TwinProperties.Desired del dispositivo gemello per leggere e scrivere le informazioni sulle proprietà desiderate del dispositivo. Aggiornare le proprietà Desired del dispositivo gemello usando una patch in formato JSON.

Questo esempio chiama GetTwinAsync per recuperare i campi del dispositivo gemello corrente in un oggetto Twin, aggiorna la proprietà desiderata speed del dispositivo gemello e quindi chiama UpdateTwinAsync per applicare l'oggetto Twin in modo da aggiornare il dispositivo gemello.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Altri metodi di aggiornamento dei dispositivi gemelli

È possibile applicare gli aggiornamenti dei dispositivi gemelli anche usando questi metodi SDK:

  • Chiamare ReplaceTwinAsync per sostituire l'intero dispositivo gemello.
  • Chiamare UpdateTwins2Async per aggiornare un elenco di dispositivi gemelli precedentemente creati nel sistema.

Creare una query del dispositivo gemello

Questa sezione illustra due query del dispositivo gemello. Le query del dispositivo gemello sono query in formato simile a SQL che restituiscono un set di risultati di dispositivi gemelli.

Per creare una query del dispositivo gemello, chiamare CreateQuery per inviare una query SQL dei dispositivi gemelli e ottenere un'interfaccia IQuery. Se si vuole, è possibile chiamare CreateQuery con un secondo parametro per specificare un numero massimo di elementi per pagina.

Chiamare quindi il metodo GetNextAsTwinAsync o GetNextAsJsonAsync il numero di volte necessarie per recuperare tutti i risultati del dispositivo gemello.

L'interfaccia IQuery include una proprietà booleana HasMoreResults che può essere usata per verificare se sono presenti più risultati di dispositivi gemelli da recuperare.

Questa query di esempio seleziona solo i dispositivi gemelli dei dispositivi ubicati nello stabilimento Redmond43.

var query = registryManager.CreateQuery(
"SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", 
string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

Questa query di esempio affina la prima query in modo da selezionare solo i dispositivi connessi anche tramite una rete cellulare.

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

Esempio di SDK per servizi

Azure IoT SDK per .NET offre un esempio funzionante di un'app di servizio che gestisce le attività dei dispositivi gemelli. Per altre informazioni, vedere Esempio di gestore registro.

  • Richiede Java SE Development Kit 8. Assicurarsi di selezionare Java 8 in Supporto a lungo termine per accedere ai download per JDK 8.

Panoramica

Questo articolo illustra come usare Azure IoT SDK per Java per creare codice di applicazioni per dispositivi e del servizio back-end per dispositivi gemelli.

Creare un'applicazione per dispositivi

Le applicazioni per dispositivi possono leggere e scrivere proprietà segnalate dei dispositivi gemelli e ricevere una notifica delle modifiche alle proprietà desiderate dei dispositivi gemelli impostate da un'applicazione back-end o da un hub IoT.

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

  • Recuperare e visualizzare un dispositivo gemello
  • Aggiornare le proprietà segnalate del dispositivo gemello
  • Sottoscrivere le modifiche alle proprietà desiderate

La classe DeviceClient espone tutti i metodi necessari per interagire con i dispositivi gemelli dal dispositivo.

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.

Istruzioni di importazione del dispositivo

Usare le istruzioni di importazione del dispositivo seguenti per accedere ad Azure IoT SDK per Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

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

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.

Eseguire l'autenticazione con una chiave di accesso condiviso

Per connettere un dispositivo a hub IoT:

  1. Usare IotHubClientProtocol per scegliere un protocollo di trasporto. Ad esempio:

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

  2. Usare il costruttore DeviceClient per aggiungere la stringa di connessione primaria del dispositivo e il protocollo.

    String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

  3. Usare open per connettere il dispositivo all'hub IoT. Se il client è già aperto, il metodo non esegue alcuna operazione.

    client.open(true);

Eseguire l'autenticazione con un certificato X.509

Per connettere un dispositivo a hub IoT usando un certificato X.509:

  1. Compilare l'oggetto SSLContext usando buildSSLContext.
  2. Aggiungere le SSLContext informazioni a un oggetto ClientOptions .
  3. Chiamare DeviceClient usando le ClientOptions informazioni per creare la connessione da dispositivo a hub IoT.

Questo esempio mostra i valori dei parametri di input del certificato come variabili locali per maggiore chiarezza. In un sistema di produzione archiviare i parametri di input sensibili nelle variabili di ambiente o in un altro percorso di archiviazione più sicuro. Ad esempio, usare Environment.GetEnvironmentVariable("PUBLICKEY") per leggere una variabile di ambiente della stringa di certificato a chiave pubblica.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

Per altre informazioni sull'autenticazione del certificato, vedere:

Esempi di codice

Per esempi funzionanti di autenticazione del certificato X.509 del dispositivo, vedere:

Recuperare e visualizzare un dispositivo gemello

Dopo aver aperto la connessione client, chiamare getTwin per recuperare le proprietà del dispositivo gemello corrente in un oggetto Twin.

Ad esempio:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Aggiornare le proprietà segnalate del dispositivo gemello

Dopo aver recuperato il dispositivo gemello corrente, è possibile iniziare ad aggiornare le proprietà segnalate. Le proprietà segnalate possono essere aggiornate anche senza recuperare il dispositivo gemello corrente, purché si disponga della versione corretta delle proprietà segnalate. Se dopo l’invio delle proprietà segnalate si riceve un errore di precondizione non riuscita, significa che la versione delle proprietà segnalate non è aggiornata. In tal caso, ottenere la versione più recente chiamando di nuovo getTwin.

Per aggiornare le proprietà segnalate:

  1. Chiamare getReportedProperties per recuperare le proprietà segnalate del dispositivo gemello in un oggetto TwinCollection.

  2. Usare put per aggiornare una proprietà segnalata all'interno dell'oggetto TwinCollection. Chiamare put per ogni aggiornamento di proprietà segnalata.

  3. Usare updateReportedProperties per applicare il gruppo di proprietà segnalate che sono state aggiornate mediante il metodo put.

Ad esempio:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Sottoscrivere le modifiche alle proprietà desiderate

Chiamare subscribeToDesiredProperties per sottoscrivere le modifiche alle proprietà desiderate. Questo client riceve un callback con un oggetto Twin ogni volta che viene aggiornata una proprietà desiderata. Il callback contiene il set completo di proprietà desiderate oppure solo la proprietà desiderata aggiornata, a seconda del modo in cui è stata modificata la proprietà desiderata.

In questo esempio vengono sottoscritte le modifiche alle proprietà desiderate. Tutte le modifiche alle proprietà desiderate vengono passate a un gestore denominato DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

In questo esempio, il gestore di callback di modifica delle proprietà desiderate DesiredPropertiesUpdatedHandler chiama getDesiredProperties per recuperare le modifiche alle proprietà, quindi visualizza le proprietà aggiornate del dispositivo gemello.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

Esempio di SDK per dispositivi

Azure IoT SDK per Java include un esempio funzionante da usare per testare i concetti dell'app per dispositivi descritti in questo articolo. Per altre informazioni, vedere Esempio di dispositivo gemello.

Creare un'applicazione back-end

Questa sezione descrive come creare un'applicazione back-end che:

  • Aggiorna i tag dei dispositivi gemelli
  • Esegue query sui dispositivi con filtri sui tag e sulle proprietà

La classe DeviceTwin di ServiceClient contiene metodi che i servizi possono usare per accedere ai dispositivi gemelli.

Istruzioni di importazione del servizio

Usare le istruzioni di importazione del servizio seguenti per accedere ad Azure IoT SDK per Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Connettersi all'hub IoT

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

  • Criteri di accesso condiviso
  • Microsoft Entra

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.

Connettersi usando criteri di accesso condiviso

Usare un costruttore DeviceTwin per creare la connessione all'hub IoT. L'oggetto DeviceTwin gestisce la comunicazione con l'hub IoT.

L'applicazione necessita dell'autorizzazione di connessione del servizio per modificare le proprietà desiderate di un dispositivo gemello e deve disporre dell'autorizzazione di lettura del Registro di sistema per eseguire query nel Registro di sistema delle identità. Non esiste alcun criterio di accesso condiviso predefinito che contiene solo queste due autorizzazioni, quindi è necessario crearne uno se non esiste già. Specificare questo criterio di accesso condiviso stringa di connessione come parametro a fromConnectionString. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

L'oggetto DeviceTwinDevice rappresenta il dispositivo gemello con le relative proprietà e i relativi tag.

Ad esempio:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

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 Java SDK, vedere Autenticazione di Azure con Java e Identità di Azure.

Per semplicità, questa sezione è incentrata sulla descrizione dell'autenticazione tramite il segreto client.

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 altre informazioni sui vantaggi e sui svantaggi dell'uso DefaultAzureCredentialdi , vedere Catene di credenziali nella libreria client di Identità di Azure per Java.

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.

È possibile autenticare le credenziali dell'app Microsoft Entra usando DefaultAzureCredentialBuilder. Salvare i parametri di connessione, ad esempio tenantID del segreto client, clientID e valori dei segreti client come variabili di ambiente. TokenCredential Una volta creato, passarlo a ServiceClient o ad altri generatori come parametro 'credential'.

In questo esempio tenta DefaultAzureCredentialBuilder di autenticare una connessione dall'elenco descritto in DefaultAzureCredential. Il risultato di un'autenticazione riuscita di Microsoft Entra è una credenziale del token di sicurezza passata a un costruttore, ad esempio ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Eseguire l'autenticazione con ClientSecretCredentialBuilder

È possibile usare ClientSecretCredentialBuilder per creare credenziali usando le informazioni sul segreto client. In caso di esito positivo, questo metodo restituisce un tokenCredential che può essere passato a ServiceClient o a un altro generatore come parametro 'credential'.

In questo esempio i valori del segreto client di registrazione dell'app Microsoft Entra, DELL'ID client e dell'ID tenant sono stati aggiunti alle variabili di ambiente. Queste variabili di ambiente vengono usate da ClientSecretCredentialBuilder per compilare le credenziali.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();
Altre classi di autenticazione

Java SDK include anche queste classi che autenticano un'app back-end con Microsoft Entra:

Esempi di codice

Per esempi di utilizzo dell'autenticazione del servizio Microsoft Entra, vedere Esempio di autenticazione basata sui ruoli.

Aggiornare i campi del dispositivo gemello

Per aggiornare i campi del dispositivo gemello:

  1. Usare getTwin per recuperare i campi del dispositivo gemello corrente

    Questo esempio recupera e visualizza i campi del dispositivo gemello:

    // Get the device twin from IoT Hub
System.out.println("Device twin before update:");
twinClient.getTwin(device);
System.out.println(device);

  2. Usare un oggetto HashSet per aggiungere tramite add un gruppo di coppie di tag del dispositivo gemello

  3. Usare setTags per aggiungere un gruppo di coppie di tag da un oggetto tags a un oggetto DeviceTwinDevice

  4. Usare updateTwin per aggiornare il dispositivo gemello nell'hub IoT

    Questo esempio aggiorna i tag region e plant per un dispositivo gemello:

    // Update device twin tags if they are different
// from the existing values
String currentTags = device.tagsToString();
if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {

// Create the tags and attach them to the DeviceTwinDevice object
Set<Pair> tags = new HashSet<Pair>();
tags.add(new Pair("region", region));
tags.add(new Pair("plant", plant));
device.setTags(tags);

// Update the device twin in IoT Hub
System.out.println("Updating device twin");
twinClient.updateTwin(device);
}

// Retrieve and display the device twin with the tag values from IoT Hub
System.out.println("Device twin after update:");
twinClient.getTwin(device);
System.out.println(device);

Creare una query del dispositivo gemello

Questa sezione illustra due query del dispositivo gemello. Le query del dispositivo gemello sono query in formato simile a SQL che restituiscono un set di risultati di dispositivi gemelli.

La classe Query contiene metodi che possono essere usati per creare query di tipo SQL nell'hub IoT per dispositivi gemelli, processi, processi di dispositivi o dati non elaborati.

Per creare una query del dispositivo:

  1. Usare createSqlQuery per compilare la query SQL dei dispositivi gemelli

  2. Usare queryTwin per eseguire la query

  3. Usare hasNextDeviceTwin per verificare se nel set di risultati è presente un altro dispositivo gemello

  4. Usare getNextDeviceTwin per recuperare il dispositivo gemello successivo dal set di risultati

Le query di esempio seguenti restituiscono un massimo di 100 dispositivi.

Questa query di esempio seleziona solo i dispositivi gemelli dei dispositivi ubicati nello stabilimento Redmond43.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Questa query di esempio affina la prima query in modo da selezionare solo i dispositivi connessi anche tramite una rete cellulare.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Esempio di SDK per servizi

Azure IoT SDK per Java offre un esempio funzionante di un'app di servizio che gestisce le attività dei dispositivi gemelli. Per altre informazioni, vedere Esempio di dispositivo gemello.

  • Python SDK: è consigliabile usare Python versione 3.7 o successiva . 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 illustra come usare Azure IoT SDK per Python per creare codice di applicazioni per dispositivi e del servizio back-end per dispositivi gemelli.

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

Creare un'applicazione per dispositivi

Le applicazioni per dispositivi possono leggere e scrivere proprietà segnalate dei dispositivi gemelli e ricevere una notifica delle modifiche alle proprietà desiderate dei dispositivi gemelli impostate da un'applicazione back-end o da un hub IoT.

La classe IoTHubDeviceClient contiene metodi che possono essere applicati ai dispositivi gemelli.

Questa sezione descrive come creare codice dell'applicazione per dispositivi che:

  • Recupera un dispositivo gemello ed esamina le proprietà segnalate
  • Applica una patch alle proprietà segnalate del dispositivo gemello

Istruzione di importazione del dispositivo

Aggiungere questo codice per importare le IoTHubDeviceClient funzioni da azure.iot.device SDK.

from azure.iot.device import IoTHubDeviceClient

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

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.

Eseguire l'autenticazione con una chiave di accesso condiviso

Per connettere un dispositivo a hub IoT:

  1. Chiamare create_from_connection_string per aggiungere il stringa di connessione primario del dispositivo.
  2. Chiamare connect per connettere il client del dispositivo.

Ad esempio:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Eseguire l'autenticazione con un certificato X.509

Per connettere un dispositivo a hub IoT usando un certificato X.509:

  1. Usare create_from_x509_certificate per aggiungere i parametri del certificato X.509
  2. Chiamare la connessione per connettere il client del dispositivo

Questo esempio mostra i valori dei parametri di input del certificato come variabili locali per maggiore chiarezza. In un sistema di produzione archiviare i parametri di input sensibili nelle variabili di ambiente o in un altro percorso di archiviazione più sicuro. Ad esempio, usare os.getenv("HOSTNAME") per leggere la variabile di ambiente del nome host.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

Per altre informazioni sull'autenticazione del certificato, vedere:

Esempi di codice

Per esempi di utilizzo dell'autenticazione del certificato X.509 del dispositivo, vedere gli esempi i cui nomi di file terminano in x509 negli scenari dell'hub asincrono.

Recuperare un dispositivo gemello ed esaminare le proprietà segnalate

È possibile recuperare ed esaminare le informazioni sul dispositivo gemello, inclusi tag e proprietà. Le informazioni sul dispositivo gemello recuperate corrispondono ai dati in formato JSON del dispositivo gemello che è possibile visualizzare per un dispositivo nel portale di Azure.

Chiamare get_twin per ottenere il dispositivo gemello dal servizio hub IoT di Azure. Le informazioni sul dispositivo gemello vengono inserite in una variabile che può essere visualizzata o 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))

Applicare una patch alle proprietà segnalate del dispositivo gemello

È possibile applicare una patch per aggiornare le proprietà segnalate del dispositivo 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. Si tratta di una chiamata sincrona, quindi questa funzione non restituisce nulla finché la patch non viene inviata al servizio e riconosciuta.

Se patch_twin_reported_properties restituisce un errore, questa funzione genera l'errore corrispondente.

# 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)

È anche possibile chiamare i metodi seguenti per aggiornare i dispositivi gemelli:

  • Chiamare replace_twin per sostituire i tag e le proprietà desiderate del dispositivo gemello.
  • Chiamare update_twin per aggiornare i tag e le proprietà desiderate del dispositivo gemello.

Gestore patch delle proprietà desiderate in ingresso

Chiamare on_twin_desired_properties_patch_received per creare una funzione del gestore o una coroutine che viene chiamata quando si riceve una patch delle proprietà desiderate del dispositivo 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 include gli esempi seguenti:

Creare un'applicazione back-end

Un'applicazione back-end si connette a un dispositivo tramite l'hub IoT e può leggere le proprietà segnalate e desiderate del dispositivo, scrivere le proprietà desiderate del dispositivo ed eseguire query del dispositivo.

Questa sezione descrive come creare un'applicazione back-end che:

  • Aggiorna i tag e le proprietà desiderate del dispositivo gemello
  • Esegue query sui dispositivi con filtri sui tag e sulle proprietà

La classe IoTHubRegistryManager espone tutti i metodi necessari per creare un’applicazione back-end che interagisca con i dispositivi gemelli dal servizio.

Connettersi all'hub IoT

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

  • Criteri di accesso condiviso
  • Microsoft Entra

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.

Connettersi usando criteri di accesso condiviso

Connettersi all'hub IoT mediante from_connection_string. L'applicazione necessita dell'autorizzazione di connessione del servizio per modificare le proprietà desiderate di un dispositivo gemello e deve disporre dell'autorizzazione di lettura del Registro di sistema per eseguire query nel Registro di sistema delle identità. Non esiste alcun criterio di accesso condiviso predefinito che contiene solo queste due autorizzazioni, quindi è necessario crearne uno se non esiste già. Specificare questo criterio di accesso condiviso stringa di connessione come parametro a fromConnectionString. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

Ad esempio:

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

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service 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:

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.

Aggiornare i tag e le proprietà desiderate del dispositivo gemello

È possibile aggiornare sia i tag che le proprietà desiderate del dispositivo gemello da un'applicazione back-end contemporaneamente usando update_twin.

  1. Chiamare get_twin per ottenere la versione corrente del dispositivo gemello
  2. Usare la classe Twin per aggiungere tag e proprietà in formato JSON.
  3. Chiamare update_twin per applicare la patch al dispositivo gemello. Si può anche usare replace_twin per sostituire le proprietà desiderate e i tag di un dispositivo gemello.

Questo esempio aggiorna le informazioni sui tag region e plant e imposta una proprietà desiderata power_level su 1.

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Creare una query del dispositivo gemello

È possibile eseguire query sulle informazioni del dispositivo gemello usando query del dispositivo gemello. Le query del dispositivo gemello sono query in formato simile a SQL che restituiscono un set di risultati di dispositivi gemelli.

Per usare una query del dispositivo gemello:

  1. Usare un oggetto QuerySpecification per definire una richiesta di query di tipo SQL.

  2. Usare query_iot_hub per eseguire query su un hub IoT e recuperare le informazioni sul dispositivo gemello usando la specifica di query di tipo SQL.

Questo esempio esegue due query. La prima seleziona solo i dispositivi gemelli dei dispositivi situati nello stabilimento Redmond43 e la seconda affina la query in modo da selezionare solo i dispositivi che sono anche connessi tramite una rete cellulare. I risultati vengono visualizzati dopo ogni query.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

Esempio di SDK per servizi

Azure IoT SDK per Python offre un esempio funzionante di un'app di servizio che gestisce le attività dei dispositivi gemelli. Per altre informazioni, vedere Esempio di query del gestore registro.

  • Richiede Node.js versione 10.0.x o successiva

Panoramica

Questo articolo illustra come usare Azure IoT SDK per Node.js per creare codice di applicazioni per dispositivi e del servizio back-end per dispositivi gemelli.

Creare un'applicazione per dispositivi

Le applicazioni per dispositivi possono leggere e scrivere proprietà segnalate dei dispositivi gemelli e ricevere una notifica delle modifiche alle proprietà desiderate dei dispositivi gemelli impostate da un'applicazione back-end o da un hub IoT.

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 ed esaminare le proprietà segnalate
  • Aggiornare le proprietà segnalate del dispositivo gemello
  • Ricevere notifica delle modifiche apportate alle proprietà desiderate

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.

Installare il pacchetto SDK del dispositivo

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:

  • Certificato X.509
  • Chiave di accesso condiviso

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.

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:

Esempio di codice

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

Eseguire l'autenticazione con una chiave di accesso condiviso

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 codice della classe Client usato per leggere e scrivere dati del dispositivo gemello.

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 Mqtt:

npm install azure-iot-device-mqtt --save

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

Creare un modulo client

Creare un modulo Client usando il pacchetto installato.

Ad esempio:

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

Creare un modulo di protocollo

Creare un modulo Protocol usando un pacchetto di trasporto installato.

Questo esempio assegna il protocollo MQTT:

const Protocol = require('azure-iot-device-mqtt').Mqtt;

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

Chiamare fromConnectionString per specificare i parametri di connessione del dispositivo:

  • connStr: stringa di connessione che incapsula le autorizzazioni di connessione del dispositivo per un hub IoT. La stringa di connessione contiene nome host, ID dispositivo e chiave di accesso condiviso nel formato seguente: "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>".
  • transportCtor: protocollo di trasporto.

Questo esempio usa il protocollo di trasporto Mqtt:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
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. Usare .catch(err) per rilevare un errore ed eseguire il codice del gestore.

Ad esempio:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Recuperare un dispositivo gemello ed esaminare le proprietà segnalate

Chiamare getTwin per recuperare le informazioni sul dispositivo gemello corrente in un oggetto Twin.

Ad esempio:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Aggiornare le proprietà segnalate del dispositivo gemello

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, una patch del dispositivo gemello in formato JSON viene archiviata nella variabile patch. La patch contiene un valore di aggiornamento connectivity del dispositivo gemello di tipo cellular. La patch e il gestore errori vengono passati al metodo update. In caso di errore, viene visualizzato un messaggio di errore della console.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Ricevere notifica delle modifiche apportate alle proprietà desiderate

Creare un listener di eventi di aggiornamento delle proprietà desiderate da eseguire quando una proprietà desiderata viene modificata nel dispositivo passando il nome del metodo del gestore di callback a twin.on.

Il listener di eventi delle proprietà desiderate può assumere una delle forme 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 delle proprietà desiderate che viene attivato ogni volta che si verifica una modifica all'interno del raggruppamento di proprietà properties.desired.climate. Se all'interno di questo gruppo è stata apportata una modifica alle proprietà desiderate, i messaggi di modifica della temperatura minima e massima vengono visualizzati nella console:

    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);
  });

Esempi di SDK per dispositivi

Azure IoT SDK per Node.js contiene due esempi di dispositivi gemelli:

Creare un'applicazione back-end

Un'applicazione back-end si connette a un dispositivo tramite l'hub IoT e può leggere le proprietà segnalate e desiderate del dispositivo, scrivere le proprietà desiderate del dispositivo ed eseguire query del dispositivo.

Questa sezione descrive come creare un'applicazione back-end che:

  • Recupera e aggiorna un dispositivo gemello
  • Crea una query del dispositivo gemello

Installare il pacchetto SDK del servizio

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

npm install azure-iothub --save

La classe Registry espone tutti i metodi necessari per interagire con i dispositivi gemelli da un’applicazione back-end.

Connettersi all'hub IoT

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

  • Criteri di accesso condiviso
  • Microsoft Entra

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.

Connettersi usando criteri di accesso condiviso

Usare fromConnectionString per connettersi all'hub IoT. L'applicazione necessita dell'autorizzazione di connessione del servizio per modificare le proprietà desiderate di un dispositivo gemello e deve disporre dell'autorizzazione di lettura del Registro di sistema per eseguire query nel Registro di sistema delle identità. Non esiste alcun criterio di accesso condiviso predefinito che contiene solo queste due autorizzazioni, quindi è necessario crearne uno se non esiste già. Specificare questo criterio di accesso condiviso stringa di connessione come parametro a fromConnectionString. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(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.

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

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:

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 e aggiornare un dispositivo gemello

È possibile creare una patch contenente gli aggiornamenti dei tag e delle proprietà desiderate di un dispositivo gemello.

Per aggiornare un dispositivo gemello:

  1. Chiamare getTwin per recuperare l'oggetto dispositivo gemello.
  • Formattare una patch contenente l'aggiornamento del dispositivo gemello. La patch è in formato JSON come descritto in Classe Twin. Una patch del servizio back-end può contenere gli aggiornamenti dei tag e delle proprietà desiderate. Per altre informazioni sul formato delle patch, vedere Formato di tag e proprietà.
  1. Chiamare update per aggiornare il dispositivo gemello con la patch.

In questo esempio viene recuperato il dispositivo gemello per myDeviceId, quindi viene applicata una patch ai dispositivi gemelli che contiene il tag location aggiornato come region: 'US', plant: 'Redmond43'.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Creare una query del dispositivo gemello

È possibile creare query del dispositivo di tipo SQL per raccogliere informazioni dai dispositivi gemelli.

Usare createQuery per creare una query che può essere eseguita in un'istanza dell'hub IoT per trovare informazioni su dispositivi o processi.

createQuery include due parametri:

  • sqlQuery: query scritta come stringa SQL.
  • pageSize: numero desiderato di risultati per pagina (facoltativo; impostazione predefinita: 1000; numero massimo: 10000).

Se viene specificato il parametro pageSize, l'oggetto query contiene una proprietà booleana hasMoreResults che è possibile controllare e si può usare il metodo nextAsTwin per ottenere la pagina successiva dei risultati del dispositivo gemello il numero di volte necessario per recuperare tutti i risultati. È disponibile un metodo chiamato next per i risultati che non sono dispositivi gemelli, ad esempio i risultati delle query di aggregazione.

Questa query di esempio seleziona solo i dispositivi gemelli dei dispositivi ubicati nello stabilimento Redmond43.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

Questa query di esempio affina la prima query in modo da selezionare solo i dispositivi che sono anche connessi tramite rete cellulare.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Esempio di SDK per servizi

Azure IoT SDK per Node.js offre un esempio funzionante di un'app di servizio che gestisce le attività dei dispositivi gemelli. Per altre informazioni, vedere Servizio back-end del dispositivo gemello. Questo progetto viene usato per inviare gli aggiornamenti delle patch dei dispositivi gemelli per un dispositivo specifico.