Condividi tramite

Introduzione alla gestione dei dispositivi

  • Articolo

Le app back-end possono usare primitive dell'hub IoT di Azure, ad esempio dispositivi gemelli e metodi diretti, per avviare e monitorare le azioni di gestione nei dispositivi in modalità remota.

Usare un metodo diretto da un'applicazione back-end per avviare azioni di gestione dei dispositivi, ad esempio il riavvio, il ripristino delle impostazioni predefinite e l'aggiornamento del firmware.

Il dispositivo è responsabile per:

  • Gestione della richiesta di metodo diretto inviata da hub IoT
  • Avvio dell'azione specifica del dispositivo corrispondente nel dispositivo
  • Fornire aggiornamenti dello stato tramite le proprietà segnalate a hub IoT

Questo articolo illustra come un'app back-end e un'app per dispositivi possono collaborare per avviare e monitorare un'azione remota del dispositivo usando un metodo diretto.

  • Un'app del servizio chiama un metodo diretto per il riavvio in un'app per dispositivi tramite un hub IoT.
  • Un'app per dispositivi gestisce un metodo diretto per riavviare un dispositivo.

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.

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 descrive come usare Azure IoT SDK per .NET per creare il codice dell'applicazione del servizio back-end e del dispositivo per i messaggi diretti del dispositivo.

Creare un'applicazione per dispositivi

Questa sezione descrive come usare il codice dell'applicazione del dispositivo per creare un listener di callback del metodo diretto.

Pacchetti NuGet del dispositivo necessari

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;

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 messaggi del dispositivo 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
  • Http1

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

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:

Creare un listener di callback del metodo diretto

Usare SetMethodHandlerAsync per inizializzare un listener di callback del metodo diretto. Il listener è associato a una parola chiave del nome del metodo, ad esempio "reboot". Il nome del metodo può essere usato in un'applicazione back-end o hub IoT per attivare il metodo di callback nel dispositivo.

In questo esempio viene configurato un listener di callback denominato onReboot che verrà attivato quando viene chiamato il nome del metodo diretto "reboot".

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

Continuando l'esempio, il onReboot metodo di callback implementa il metodo diretto nel dispositivo.

La funzione del gestore chiama MethodResponse per inviare un riconoscimento della risposta all'applicazione chiamante.

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Nota

Per semplicità, in questo articolo non si implementa alcun criterio di ripetizione dei tentativi. Nel codice di produzione è consigliabile implementare criteri di ripetizione dei tentativi (ad esempio, un backoff esponenziale) come suggerito in Gestione degli errori temporanei.

Esempi di SDK per dispositivi

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

Creare un'applicazione back-end

Questa sezione descrive come attivare un metodo diretto in un dispositivo.

La classe ServiceClient espone tutti i metodi necessari per creare un'applicazione back-end per inviare chiamate al metodo diretto ai dispositivi.

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

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

Per richiamare un metodo diretto in un dispositivo tramite l'hub IoT, è necessario che il servizio disponga delle autorizzazioni di connessione al servizio. Per impostazione predefinita, ogni hub IoT viene creato con un servizio con nome di criteri di accesso condiviso che concede tale autorizzazione.

Come parametro per CreateFromConnectionString, specificare i criteri di accesso condiviso del servizio . Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy connection string}";
serviceClient = ServiceClient.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.

Richiamare un metodo su un dispositivo

Per richiamare un metodo in un dispositivo:

  1. Creare un oggetto CloudToDeviceMethod . Passare il nome del metodo diretto del dispositivo come parametro.
  2. Chiama InvokeDeviceMethodAsync per richiamare il metodo nel dispositivo.

In questo esempio viene chiamato il metodo "reboot" per avviare un riavvio nel dispositivo. Il metodo "reboot" viene mappato a un listener nel dispositivo come descritto nella sezione Creare un listener di callback del metodo diretto di questo articolo.

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

Esempi di servizio SDK

Azure IoT SDK per .NET fornisce esempi funzionanti di app di servizio che gestiscono le attività dei messaggi. Per altre informazioni, vedi:

  • 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 descrive come usare Azure IoT SDK per Java per creare il codice dell'applicazione del servizio back-end e del dispositivo per i metodi diretti del dispositivo.

Creare un'applicazione per dispositivi

Questa sezione descrive come usare il codice dell'applicazione del dispositivo per creare un listener di callback del metodo diretto.

La classe DeviceClient espone tutti i metodi necessari per interagire con metodi diretti nel 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.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

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 connettersi a un dispositivo:

  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:

Creare un listener di callback del metodo diretto

Usare subscribeToMethods per inizializzare un listener di callback del metodo diretto. subscribeToMethods rimane in ascolto dei metodi diretti in ingresso fino a quando la connessione non viene terminata. Il nome del metodo e il payload sono ricevuti per ogni chiamata al metodo diretto.

Il listener deve chiamare DirectMethodResponse per inviare un riconoscimento della risposta del metodo all'applicazione chiamante.

Ad esempio:

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

Nota

Per semplicità, in questo articolo non si implementa alcun criterio di ripetizione dei tentativi. Nel codice di produzione è consigliabile implementare criteri di ripetizione dei tentativi (ad esempio, un backoff esponenziale) come suggerito in Gestione degli errori temporanei.

Esempi 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 metodo diretto.

Creare un'applicazione back-end

Questa sezione descrive come avviare un riavvio remoto in un dispositivo usando un metodo diretto.

La ServiceClient classe DeviceMethod contiene metodi che i servizi possono usare per accedere ai metodi diretti.

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.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

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 il costruttore DeviceMethod per aggiungere il stringa di connessione primario del servizio e connettersi a hub IoT.

Per richiamare un metodo diretto in un dispositivo tramite l'hub IoT, è necessario che il servizio disponga delle autorizzazioni di connessione al servizio. Per impostazione predefinita, ogni hub IoT viene creato con un servizio con nome di criteri di accesso condiviso che concede tale autorizzazione.

Come parametro per il DeviceMethod costruttore, specificare i criteri di accesso condiviso del servizio . Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

Ad esempio:

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(iotHubConnectionString);

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.

Richiamare un metodo su un dispositivo

Chiamare DeviceMethod.invoke per richiamare un metodo in un dispositivo e restituire lo stato del risultato.

Il invoke parametro payload è facoltativo. Usare null se non è disponibile alcun payload. Il parametro payload può accettare forme di dati diverse, tra cui stringa, matrice di byte e HashMap. Per esempi, vedere Test del metodo diretto.

In questo esempio viene chiamato il metodo "reboot" per avviare un riavvio nel dispositivo. Il metodo "reboot" viene mappato a un listener nel dispositivo come descritto nella sezione Creare un listener di callback del metodo diretto di questo articolo.

Ad esempio:

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

Esempi di servizio SDK

Azure IoT SDK per Java offre un esempio funzionante di app di servizio che gestiscono attività di metodo diretto. Per altre informazioni, vedi:

  • 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 descrive come usare Azure IoT SDK per Python per creare il codice dell'applicazione del servizio back-end e del dispositivo per i metodi diretti del dispositivo.

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

Questa sezione descrive come usare il codice dell'applicazione del dispositivo per creare un listener di callback del metodo diretto.

La classe IoTHubDeviceClient contiene metodi che possono essere usati per lavorare con metodi diretti.

Istruzione di importazione del dispositivo

Aggiungere questa istruzione import per accedere IoTHubDeviceClient a e MethodResponse.

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

Connettersi a un dispositivo

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

Usare create_from_connection_string per connettere un'applicazione a un dispositivo usando un dispositivo stringa di connessione.

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

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.

Creare un callback del metodo diretto

Usare on_method_request_received per creare una funzione del gestore o una coroutine chiamata quando viene ricevuto un metodo diretto. Il listener è associato a una parola chiave del nome del metodo, ad esempio "reboot". Il nome del metodo può essere usato in un'applicazione back-end o hub IoT per attivare il metodo di callback nel dispositivo.

La funzione del gestore deve creare un metodoResponse e passarlo a send_method_response per inviare un riconoscimento di risposta al metodo diretto all'applicazione chiamante.

In questo esempio viene configurato un gestore di metodi diretti denominato method_request_handler.

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

In questo esempio il method_request_handler metodo di callback implementa il metodo diretto nel dispositivo. Il codice viene eseguito quando viene chiamato il metodo diretto "rebootDevice" da un'applicazione di servizio. Il metodo chiama send_method_response per inviare un riconoscimento di risposta al metodo diretto all'applicazione chiamante.

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

Esempi di SDK per dispositivi

Azure IoT SDK per Python fornisce un esempio funzionante di un'app per dispositivi che gestisce le attività dei metodi diretti. Per altre informazioni, vedere Ricevere un metodo diretto.

Creare un'applicazione back-end

Questa sezione descrive come usare un'applicazione del servizio back-end per chiamare un metodo diretto in un dispositivo.

La classe IoTHubRegistryManager espone tutti i metodi necessari per creare un'applicazione back-end per inviare messaggi a un dispositivo.

Istruzioni di importazione del servizio

Aggiungere queste istruzioni di importazione per connettersi all'hub Iot, inviare metodi diretti da cloud a dispositivo e ricevere risposte al metodo diretto del dispositivo.

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

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.

Per richiamare un metodo diretto in un dispositivo tramite l'hub IoT, è necessario che il servizio disponga delle autorizzazioni di connessione al servizio. Per impostazione predefinita, ogni hub IoT viene creato con un servizio con nome di criteri di accesso condiviso che concede tale autorizzazione.

Come parametro per from_connection_string, specificare i criteri di accesso condiviso del servizio . 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 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.

Richiamare un metodo su un dispositivo

È possibile richiamare un metodo diretto in base al nome in un dispositivo. Il nome del metodo identifica il metodo . Nell'esempio di dispositivo seguente e precedente illustrato in Creare un callback del metodo diretto, il nome del metodo diretto è "rebootDevice".

Per richiamare un metodo diretto in un dispositivo:

  1. Creare un oggetto CloudToDeviceMethod . Specificare il nome del metodo e il payload come parametri.
  2. Chiamare invoke_device_method per richiamare un metodo diretto in un dispositivo. Specificare l'ID dispositivo e CloudToDeviceMethod l'oggetto payload come parametri.

Questo esempio chiama CloudToDeviceMethod per richiamare un metodo diretto denominato "rebootDevice" in un dispositivo. Dopo che il metodo diretto viene richiamato correttamente, viene visualizzato il payload della risposta al metodo diretto.

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

Esempi di servizio SDK

Azure IoT SDK per Python fornisce esempi funzionanti di app di servizio che gestiscono attività di metodo diretto. Per altre informazioni, vedi:

  • 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 metodi diretti del dispositivo.

Creare un'applicazione per dispositivi

Questa sezione descrive come usare il codice dell'applicazione del dispositivo per creare un callback del metodo diretto.

Installare il pacchetto SDK

Il pacchetto azure-iot-device contiene oggetti che si interfacciano con i dispositivi IoT. 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

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 di MQTT, AMQP e HTTPS, vedere Linee guida per le comunicazioni da cloud a dispositivo e Scegliere un protocollo di comunicazione.

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: stringa di connessione del dispositivo.
  • transportCtor: protocollo di trasporto.

Questo esempio usa il protocollo di trasporto Amqp:

const deviceConnectionString = "{IoT hub device 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 la connessione tra un dispositivo IoT e hub IoT.

Ad esempio:

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

Creare un callback del metodo diretto

Chiamare onDeviceMethod per creare una funzione del gestore di callback o una coroutine chiamata quando viene ricevuto un metodo diretto. Il listener è associato a una parola chiave del nome del metodo, ad esempio "reboot". Il nome del metodo può essere usato in un'applicazione back-end o hub IoT per attivare il metodo di callback nel dispositivo.

La funzione del gestore di callback deve chiamare response.send per inviare un messaggio di riconoscimento della risposta all'applicazione chiamante.

In questo esempio viene configurato un gestore del metodo diretto denominato onReboot che viene chiamato quando viene usato il nome del metodo diretto "reboot".

client.onDeviceMethod('reboot', onReboot);

In questo esempio il onReboot metodo di callback implementa il metodo diretto nel dispositivo. Il codice viene eseguito quando viene chiamato il metodo diretto "reboot" da un'applicazione di servizio. La funzione chiama response.send per inviare un messaggio di riconoscimento della risposta all'applicazione chiamante.

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

Esempi di SDK per dispositivi

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

Creare un'applicazione back-end

Questa sezione descrive come richiamare un metodo diretto in un dispositivo.

Installare il pacchetto SDK del servizio

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

npm install azure-iothub --save

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.

Per richiamare un metodo diretto in un dispositivo tramite l'hub IoT, è necessario che il servizio disponga delle autorizzazioni di connessione al servizio. Per impostazione predefinita, ogni hub IoT viene creato con un servizio con nome di criteri di accesso condiviso che concede tale autorizzazione.

Come parametro di CreateFromConnectionString, specificare i criteri di accesso condiviso del servizio stringa di connessione. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.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.

Richiamare un metodo su un dispositivo

Usare invokeDeviceMethod per richiamare un metodo diretto in base al nome in un dispositivo. Il parametro del nome del metodo identifica il metodo diretto.

In questo esempio viene chiamato il metodo "reboot" per avviare un riavvio nel dispositivo. Il metodo "reboot" viene mappato a una funzione del gestore di callback nel dispositivo, come descritto nella sezione Creare un callback del metodo diretto di questo articolo.

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

Esempi di servizio SDK

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