Come pianificare e trasmettere attività

• Richiede Visual Studio

Panoramica

Questo articolo descrive come usare Azure IoT SDK per .NET per creare il codice dell'applicazione di un servizio back-end per un processo pianificato che richiami un metodo diretto o esegua un aggiornamento del gemello del dispositivo su uno o più dispositivi.

Aggiungi il pacchetto NuGet del servizio

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

Uso delle istruzioni

Aggiungere i seguenti elementi utilizzando le istruzioni.

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

using System.Threading;
using System.Threading.Tasks;

Connettersi all'hub IoT

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

• Criteri di accesso condiviso
• Microsoft Entra

Connettersi usando criteri di accesso condiviso

Connettere un'applicazione back-end a un dispositivo mediante CreateFromConnectionString.

Questo articolo descrive il codice back-end in grado di pianificare un processo per richiamare un metodo diretto, pianificare un processo per aggiornare un dispositivo gemello e monitorare lo stato di avanzamento di un processo per uno o più dispositivi. Per eseguire queste operazioni, è necessario che il servizio disponga delle autorizzazioni di lettura del registro di sistema e scrittura del registro di sistema. Per impostazione predefinita, ogni hub IoT viene creato con un criterio di accesso condiviso denominato registryReadWrite che concede tali autorizzazioni.

Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

static JobClient jobClient;
static string connectionString = "{Shared access policy connection string}";
jobClient = JobClient.CreateFromConnectionString(connString);

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:

• Chiave segreta del cliente
• Certificato
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, IoT Hub Twin Contributor è necessario per abilitare l'accesso in lettura e scrittura a un dispositivo IoT Hub e ai gemelli del modulo. Per altre informazioni, vedere Gestire l'accesso a IoT Hub usando l'assegnazione di ruoli RBAC 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 adottare un metodo diverso in un ambiente di produzione, come un metodo specifico TokenCredential o semplificato ChainedTokenCredential. Per semplicità, questa sezione descrive l'autenticazione tramite DefaultAzureCredential e il segreto client. Per altre informazioni sui vantaggi e sui svantaggi dell'uso di DefaultAzureCredential, vedere Guida all'uso di 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 dell'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();

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

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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

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.

Pianifica un'attività di metodo diretto

Usare ScheduleDeviceMethodAsync per pianificare un processo per eseguire un metodo diretto in uno o più dispositivi.

Usare l'oggetto CloudToDeviceMethod per specificare il nome del metodo diretto e i valori di timeout della connessione del dispositivo.

Ad esempio:

// The CloudToDeviceMethod record specifies the direct method name and device connection time-out
CloudToDeviceMethod directMethod = 
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
TimeSpan.FromSeconds(5));

Questo esempio pianifica un processo per un metodo diretto denominato "LockDoor" in un dispositivo denominato "Device-1". I dispositivi inclusi nel processo pianificato sono indicati nel secondo parametro come condizione di query. Per ulteriori informazioni sulle condizioni delle query, vedere Hub IoT, linguaggio di query per i dispositivi e moduli gemelli, i processi, e il routing dei messaggi.

string methodJobId = Guid.NewGuid().ToString();  // a unique job ID
static string deviceId = "Device-1";             // In this example, there is only one device affected
JobResponse result = await jobClient.ScheduleDeviceMethodAsync(methodJobId,
   $"DeviceId IN ['{deviceId}']",
   directMethod,
   DateTime.UtcNow,
   (long)TimeSpan.FromMinutes(2).TotalSeconds);

Pianificare un processo di aggiornamento del dispositivo gemello

Usare ScheduleTwinUpdateAsync per pianificare un nuovo processo di aggiornamento delle proprietà e dei tag desiderati del dispositivo gemello per l'esecuzione in uno o più dispositivi.

Prima di tutto, creare e popolare un oggetto dispositivo Twin per l'aggiornamento. Ad esempio:

static string deviceId = "Device-1";

Twin twin = new Twin(deviceId);
twin.Tags = new TwinCollection();
twin.Tags["Building"] = "43";
twin.Tags["Floor"] = "3";
twin.ETag = "*";
twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

Quindi, chiamare ScheduleTwinUpdateAsync. Specificare i dispositivi da aggiornare come query nel secondo parametro. Per ulteriori informazioni sulle condizioni delle query, vedere Hub IoT, linguaggio di query per i dispositivi e moduli gemelli, i processi, e il routing dei messaggi.

string twinJobId = Guid.NewGuid().ToString();

JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
   twinJobId,
   $"DeviceId IN ['{deviceId}']", 
   twin, 
   DateTime.UtcNow, 
   (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

Monitorare un processo

Usare GetJobAsync per monitorare lo stato del processo per un ID processo specifico.

Questo esempio controlla periodicamente lo stato di un processo identificato da un ID, fino al completamento o all'errore del processo. Ad esempio:

JobResponse result;
do
{
   result = await jobClient.GetJobAsync(jobId);
   Console.WriteLine("Job Status : " + result.Status.ToString());
   Thread.Sleep(2000);
} while ((result.Status != JobStatus.Completed) && (result.Status != JobStatus.Failed));

Esempi di attività pianificate SDK

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

• Esempio di pianificazione dell'aggiornamento dei dispositivi gemelli
• Esempio di aggiornamento del gemello pianificato da E2E.

• 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 utilizzare l'Azure IoT SDK per Java per creare il codice per un'applicazione di servizio di back-end che pianifica un'attività per invocare un metodo diretto o eseguire un aggiornamento del gemello digitale su uno o più dispositivi.

Dichiarazioni di importazione del servizio

La classe JobClient contiene metodi che i servizi possono usare per pianificare i processi.

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

import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;
import com.microsoft.azure.sdk.iot.service.devicetwin.Pair;
import com.microsoft.azure.sdk.iot.service.devicetwin.Query;
import com.microsoft.azure.sdk.iot.service.devicetwin.SqlQuery;
import com.microsoft.azure.sdk.iot.service.jobs.JobClient;
import com.microsoft.azure.sdk.iot.service.jobs.JobResult;
import com.microsoft.azure.sdk.iot.service.jobs.JobStatus;

import java.util.Date;
import java.time.Instant;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;

Connettersi all'hub IoT

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

• Criteri di accesso condiviso
• Microsoft Entra

Connettersi usando criteri di accesso condiviso

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

Questo articolo descrive il codice back-end in grado di pianificare un processo per richiamare un metodo diretto, pianificare un processo per aggiornare un dispositivo gemello e monitorare lo stato di avanzamento di un processo per uno o più dispositivi. Per eseguire queste operazioni, è necessario che il servizio disponga delle autorizzazioni di lettura del registro di sistema e scrittura del registro di sistema. Per impostazione predefinita, ogni hub IoT viene creato con un criterio di accesso condiviso denominato registryReadWrite che concede tali autorizzazioni.

Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

Ad esempio:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(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:

• Chiave segreta del cliente
• Certificato
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, IoT Hub Twin Contributor è necessario per abilitare l'accesso in lettura e scrittura a un dispositivo IoT Hub e ai gemelli del modulo. Per altre informazioni, vedere Gestire l'accesso a IoT Hub usando l'assegnazione di ruoli RBAC 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 adottare un metodo diverso in un ambiente di produzione, come un metodo specifico TokenCredential o semplificato ChainedTokenCredential. Per ulteriori informazioni sui vantaggi e sugli svantaggi dell'uso di DefaultAzureCredential, 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, come client secret tenantID, clientID e client secret, come variabili di ambiente. TokenCredential Una volta creato, passarlo a ServiceClient o ad altri builder come parametro credenziale.

In questo esempio tenta DefaultAzureCredentialBuilder di autenticare una connessione dall'elenco descritto in DefaultAzureCredential. Il risultato di un'autenticazione riuscita da parte di Microsoft Entra è una credenziale del token di sicurezza che viene passata a un costruttore come 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 client secret, dell'ID client ID e dell'ID tenant della registrazione dell'app Microsoft Entra 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:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

Esempi di codice

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

Pianificare un processo di aggiornamento del metodo diretto

Usare scheduleDeviceMethod per eseguire un metodo diretto in uno o più dispositivi.

Questo metodo di esempio pianifica un processo per un metodo diretto denominato "lockDoor" in un dispositivo denominato "Device-1".

// Schedule a job now to call the lockDoor direct method
// against a single device. Response and connection
// timeouts are set to 5 seconds.
String deviceId = "Device-1";
String jobId = "DMCMD" + UUID.randomUUID();  //Job ID must be unique

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleDeviceMethod(jobId,
    "deviceId='" + deviceId + "'",
    "lockDoor",
    5L, 5L, null,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling direct method job: " + jobId);
  System.out.println(e.getMessage());
}

Pianificare un processo di aggiornamento del dispositivo gemello

Usare scheduleUpdateTwin per pianificare un processo per eseguire un aggiornamento del dispositivo gemello in uno o più dispositivi.

Prima di tutto, preparare un record DeviceTwinDevice per l'aggiornamento del dispositivo gemello. Ad esempio:

String deviceId = "Device-1";

//Create a device twin desired properties update object
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
Set<Pair> desiredProperties = new HashSet<Pair>();
desiredProperties.add(new Pair("Building", 43));
desiredProperties.add(new Pair("Floor", 3));
twin.setDesiredProperties(desiredProperties);
// Optimistic concurrency control
twin.setETag("*");

Chiamare quindi scheduleUpdateTwin per pianificare l'attività di aggiornamento. Ad esempio:

String jobId = "DPCMD" + UUID.randomUUID();  //Unique job ID

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

// Schedule the update twin job to run now for a single device
System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleUpdateTwin(jobId, 
    "deviceId='" + deviceId + "'",
    twin,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling desired properties job: " + jobId);
  System.out.println(e.getMessage());
}

Monitorare un processo

Usare getJob per recuperare le informazioni sul job in base a un ID job specifico. getJob restituisce un oggetto JobResult che contiene metodi e proprietà che è possibile utilizzare per controllare le informazioni sul processo, incluso lo stato di esecuzione.

Ad esempio:

try {
  JobResult jobResult = jobClient.getJob(jobId);
  if(jobResult == null)
  {
    System.out.println("No JobResult for: " + jobId);
    return;
  }
  // Check the job result until it's completed
  while(jobResult.getJobStatus() != JobStatus.completed)
  {
    Thread.sleep(100);
    jobResult = jobClient.getJob(jobId);
    System.out.println("Status " + jobResult.getJobStatus() + " for job " + jobId);
  }
  System.out.println("Final status " + jobResult.getJobStatus() + " for job " + jobId);
} catch (Exception e) {
  System.out.println("Exception monitoring job: " + jobId);
  System.out.println(e.getMessage());
  return;
}

Eseguire una query sullo stato di un'attività

Usare queryDeviceJob per eseguire query sullo stato di uno o più processi.

Ad esempio:

private static void queryDeviceJobs(JobClient jobClient, String start) throws Exception {
  System.out.println("\nQuery device jobs since " + start);

  // Create a jobs query using the time the jobs started
  Query deviceJobQuery = jobClient
      .queryDeviceJob(SqlQuery.createSqlQuery("*", SqlQuery.FromType.JOBS, "devices.jobs.startTimeUtc > '" + start + "'", null).getQuery());

  // Iterate over the list of jobs and print the details
  while (jobClient.hasNextJob(deviceJobQuery)) {
    System.out.println(jobClient.getNextJob(deviceJobQuery));
  }
}

Esempio di processo pianificato dell'SDK

Azure IoT SDK per Java fornisce un esempio funzionante di un'app di servizio che gestisce le attività di pianificazione dei processi. Per altre informazioni, vedere l'esempio di client del processo.

• 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 codice dell'applicazione del servizio back-end per schedulare un'attività per invocare un metodo diretto o eseguire un aggiornamento delle proprietà desiderate del gemello digitale su uno o più dispositivi.

Installare il pacchetto

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

pip install azure-iot-hub

Istruzioni di importazione

La classe IoTHubJobManager espone tutti i metodi necessari per creare un'applicazione back-end per pianificare i processi dal servizio.

Aggiungere le istruzioni import seguenti.

import os
import sys
import datetime
import time
import threading
import uuid
import msrest

from azure.iot.hub import IoTHubJobManager
from azure.iot.hub.models import JobProperties, JobRequest, Twin, TwinProperties, CloudToDeviceMethod

Connettersi all'hub IoT

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

• Criteri di accesso condiviso
• Microsoft Entra

Connettersi usando criteri di accesso condiviso

Connettersi all'hub IoT mediante from_connection_string.

Questo articolo descrive il codice back-end in grado di pianificare un processo per richiamare un metodo diretto, pianificare un processo per aggiornare un dispositivo gemello e monitorare lo stato di avanzamento di un processo per uno o più dispositivi. Per eseguire queste operazioni, è necessario che il servizio disponga delle autorizzazioni di lettura del registro di sistema e scrittura del registro di sistema. Per impostazione predefinita, ogni hub IoT viene creato con un criterio di accesso condiviso denominato registryReadWrite che concede tali autorizzazioni.

Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

Ad esempio:

IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(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.

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:

• Chiave segreta del cliente
• Certificato
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, IoT Hub Twin Contributor è necessario per abilitare l'accesso in lettura e scrittura a un dispositivo IoT Hub e ai gemelli del modulo. Per altre informazioni, vedere Gestire l'accesso a IoT Hub usando l'assegnazione di ruoli RBAC 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 adottare un metodo diverso in un ambiente di produzione, come un metodo specifico TokenCredential o semplificato ChainedTokenCredential. Per semplicità, questa sezione descrive l'autenticazione tramite DefaultAzureCredential e il segreto client. Per altre informazioni sui vantaggi e sui svantaggi dell'uso di DefaultAzureCredential, vedere Guida all'uso di 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 dell'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();

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

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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

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.

Pianifica un'attività di metodo diretto

Usare create_scheduled_job per pianificare un nuovo metodo diretto per eseguire un metodo diretto in uno o più dispositivi:

create_scheduled_job note sui parametri:

• job_id deve essere univoco
• Impostare type su scheduleDeviceMethod
• Usare cloud_to_device_method per impostare il nome e il payload del metodo diretto
• Usare max_execution_time_in_seconds per specificare il tempo di esecuzione in secondi
• Usare query_condition per specificare i dispositivi da includere per la chiamata al metodo diretto. Per ulteriori informazioni sulle condizioni delle query, vedere Hub IoT, linguaggio di query per i dispositivi e moduli gemelli, i processi, e il routing dei messaggi.

Ad esempio:

METHOD_NAME = "lockDoor"
METHOD_PAYLOAD = "{\"lockTime\":\"10m\"}"
job_id = uuid.uuid4()
DEVICE_ID = "Device-1"
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleDeviceMethod"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.cloud_to_device_method = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

Pianificare un processo di aggiornamento del dispositivo gemello

Usare create_scheduled_job per creare un nuovo processo per eseguire un aggiornamento delle proprietà desiderate del dispositivo gemello in uno o più dispositivi.

create_scheduled_job note sui parametri:

• job_id deve essere univoco
• Impostare type su scheduleUpdateTwin
• Usare update_twin per impostare il nome e il payload del metodo diretto
• Usare max_execution_time_in_seconds per specificare il tempo di esecuzione in secondi
• Usare query_condition per specificare una condizione per uno o più dispositivi che dispongono della chiamata al metodo diretto. Per ulteriori informazioni sulle condizioni delle query, vedere Hub IoT, linguaggio di query per i dispositivi e moduli gemelli, i processi, e il routing dei messaggi.

Ad esempio:

UPDATE_PATCH = {"building":43,"floor":3}
job_id = uuid.uuid4()
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleUpdateTwin"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.update_twin = Twin(etag="*", properties=TwinProperties(desired=UPDATE_PATCH))
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

Monitorare un processo

Usare get_scheduled_job per recuperare i dettagli di un processo specifico in un hub IoT.

Questo esempio controlla lo stato del lavoro per un ID lavoro specifico ogni cinque secondi fino a quando il lavoro è completo.

while True:
    get_job_response = iothub_job_manager.get_scheduled_job(job_request.job_id)
    print_job_response("Get job response: ", get_job_response)
    if get_job_response.status == "completed":
      print ( "Job is completed." )
    time.sleep(5)

Esempi di attività pianificate SDK

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

• Pianificare un'attività di metodo diretto
• Pianificare un aggiornamento del dispositivo gemello.

• 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 per pianificare il processo per richiamare un metodo diretto o eseguire un aggiornamento del dispositivo gemello in uno o più dispositivi.

Installare il pacchetto SDK del servizio

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

npm install azure-iothub --save

La classe JobClient espone tutti i metodi necessari per interagire con la pianificazione dei processi 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

Connettersi usando criteri di accesso condiviso

Usare fromConnectionString per connettersi all'hub IoT.

Questo articolo descrive il codice back-end in grado di pianificare un processo per richiamare un metodo diretto, pianificare un processo per aggiornare un dispositivo gemello e monitorare lo stato di avanzamento di un processo per uno o più dispositivi. Per eseguire queste operazioni, è necessario che il servizio disponga delle autorizzazioni di lettura del registro di sistema e scrittura del registro di sistema. Per impostazione predefinita, ogni hub IoT viene creato con un criterio di accesso condiviso denominato registryReadWrite che concede tali autorizzazioni.

Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

Ad esempio:

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

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

Configurare l'app Microsoft Entra

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

• Segreto del client
• Certificato
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, IoT Hub Twin Contributor è necessario per l'accesso in lettura e scrittura a un dispositivo e ai moduli gemelli di un IoT Hub. Per altre informazioni, vedere Gestire l'accesso all'hub IoT usando l'assegnazione del ruolo Controllo degli accessi in base ai ruoli 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 utilizzare un metodo diverso in un ambiente di produzione, inclusi un elemento specifico TokenCredential o semplificato.ChainedTokenCredential Per semplicità, questa sezione descrive l'autenticazione tramite DefaultAzureCredential e il segreto client. Per ulteriori informazioni sui vantaggi e svantaggi dell'uso di DefaultAzureCredential, vedere Catene di credenziali nella libreria client Azure Identity 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 dell'hub IoT.

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

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

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

• Registro
• Client
• JobClient

fromTokenCredential richiede due parametri:

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

In questo esempio, le credenziali di Azure vengono ottenute usando DefaultAzureCredential. L'URL e le credenziali del dominio di Azure vengono quindi forniti a Registry.fromTokenCredential per 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.

Creare un processo del metodo diretto

Usare scheduleDeviceMethod per pianificare un processo per eseguire un metodo diretto in uno o più dispositivi.

Creare prima di tutto una variabile di aggiornamento del metodo diretto con il nome del metodo, il payload e le informazioni sul timeout della risposta. Ad esempio:

var methodParams = {
    methodName: 'lockDoor',
    payload: null,
    responseTimeoutInSeconds: 15 // Time-out after 15 seconds if device is unable to process method
};

Quindi, chiamare scheduleDeviceMethod per pianificate il processo di chiamata del metodo diretto:

• Ogni attività deve avere un ID attività univoco. È possibile utilizzare questo ID job per monitorare un job come descritto nella sezione Monitorare un job di questo articolo.
• Specificare un queryCondition parametro per valutare i dispositivi in cui eseguire il processo. Per ulteriori informazioni sulle condizioni di query, vedere linguaggio di query di IoT Hub per dispositivi e moduli gemelli, processi e instradamento dei messaggi.
• Controllare il jobResult callback per il risultato della pianificazione del processo. Se il processo è stato pianificato correttamente, è possibile monitorare lo stato del processo come illustrato nella sezione Monitorare un processo di questo articolo.

Ad esempio:

var methodJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

jobClient.scheduleDeviceMethod(methodJobId,
                            queryCondition,
                            methodParams,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule direct method job: ' + err.message);
    } else {
        monitorJob(methodJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor direct method job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Pianificare un processo di aggiornamento del dispositivo gemello

Usare scheduleTwinUpdate per creare un nuovo processo per eseguire un aggiornamento del dispositivo gemello in uno o più dispositivi.

Creare prima di tutto una variabile di aggiornamento della proprietà desiderata del dispositivo gemello.

var twinPatch = {
   etag: '*',
   properties: {
       desired: {
           building: '43',
           floor: 3
       }
   }
};

Poi, chiamare scheduleTwinUpdate per pianificare il processo di aggiornamento della proprietà desiderata del dispositivo gemello:

• Ogni attività deve avere un ID attività univoco. È possibile utilizzare questo ID job per monitorare un job come descritto nella sezione Monitorare un job di questo articolo.
• Specificare un queryCondition parametro per valutare i dispositivi in cui eseguire il processo. Per ulteriori informazioni sulle condizioni delle query, vedere Hub IoT, linguaggio di query per i dispositivi e moduli gemelli, i processi, e il routing dei messaggi.
• Controllare il jobResult callback per il risultato della pianificazione del processo. Se il processo è stato pianificato correttamente, è possibile monitorare lo stato del processo come illustrato nella sezione Monitorare un processo di questo articolo.

Ad esempio:

var twinJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

console.log('scheduling Twin Update job with id: ' + twinJobId);
jobClient.scheduleTwinUpdate(twinJobId,
                            queryCondition,
                            twinPatch,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule twin update job: ' + err.message);
    } else {
        monitorJob(twinJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor twin update job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Monitorare un processo

Usare GetJob per monitorare lo stato del processo per un ID processo specifico.

Questa funzione di esempio controlla periodicamente lo stato di un ID processo specifico, fino al completamento o all'errore del processo.

function monitorJob (jobId, callback) {
    var jobMonitorInterval = setInterval(function() {
        jobClient.getJob(jobId, function(err, result) {
        if (err) {
            console.error('Could not get job status: ' + err.message);
        } else {
            console.log('Job: ' + jobId + ' - status: ' + result.status);
            if (result.status === 'completed' || result.status === 'failed' || result.status === 'cancelled') {
            clearInterval(jobMonitorInterval);
            callback(null, result);
            }
        }
        });
    }, 5000);
}

Esempio di processo pianificato dell'SDK

Azure IoT SDK per Node.js fornisce un esempio funzionante di un'app di servizio che gestisce le attività di pianificazione dei processi. Per ulteriori informazioni, vedere Job client Test E2E.