Come pianificare e trasmettere processi

• Richiede Visual Studio

Panoramica

Questo articolo descrive come usare Azure IoT SDK per .NET per creare codice dell'applicazione del servizio back-end per un processo di pianificazione per richiamare un metodo diretto o eseguire un aggiornamento del dispositivo gemello in uno o più dispositivi.

Aggiungere un 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 registryReadWrite con nome di criteri di accesso condiviso che concede tale autorizzazione.i.

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:

• Segreto client
• Certificate
• Credenziali di identità federate

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

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

Eseguire l'autenticazione con DefaultAzureCredential

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

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

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

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

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

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

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

TokenCredential tokenCredential = new DefaultAzureCredential();

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

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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

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

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

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

Esempio di codice

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

Pianificare un processo 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 contenuti nel secondo parametro come condizione di query. Per altre informazioni sulle condizioni di query, vedere hub IoT linguaggio di query per dispositivi e moduli gemelli, processi e 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 gemello 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;

ScheduleTwinUpdateAsyncChiamare quindi . Specificare i dispositivi da aggiornare come query nel secondo parametro. Per altre informazioni sulle condizioni di query, vedere hub IoT linguaggio di query per dispositivi e moduli gemelli, processi e 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 del processo per un ID processo fino a quando lo stato del processo non viene completato o non è riuscito. 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 processi di pianificazione 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 usare Azure IoT SDK per Java per creare 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.

Istruzioni 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 registryReadWrite con nome di criteri di accesso condiviso che concede tale autorizzazione.i.

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:

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

• 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 scheduleUpdateTwin quindi per pianificare il processo 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 processo in base a un ID processo 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 processo

Usare queryDeviceJob per eseguire una query sullo stato del processo per 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 di pianificazione 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 Esempio di client di 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 pianificare il processo per richiamare un metodo diretto o eseguire un aggiornamento delle proprietà desiderato del dispositivo gemello in 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 Import

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 registryReadWrite con nome di criteri di accesso condiviso che concede tale autorizzazione.i.

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:

• Segreto client
• Certificate
• Credenziali di identità federate

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

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

Eseguire l'autenticazione con DefaultAzureCredential

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

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

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

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

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

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

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

TokenCredential tokenCredential = new DefaultAzureCredential();

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

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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

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

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

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

Esempio di codice

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

Pianificare un processo 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 parametro:

• 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 altre informazioni sulle condizioni di query, vedere hub IoT linguaggio di query per dispositivi e moduli gemelli, processi e 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 parametro:

• 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 altre informazioni sulle condizioni di query, vedere hub IoT linguaggio di query per dispositivi e moduli gemelli, processi e 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 processo per un ID processo specifico ogni cinque secondi fino al completamento del processo.

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 processi di pianificazione 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 processo 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 registryReadWrite con nome di criteri di accesso condiviso che concede tale autorizzazione.i.

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 client
• Certificate
• Credenziali di identità federate

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

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

Eseguire l'autenticazione con DefaultAzureCredential

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

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

Microsoft Entra richiede questo pacchetto:

npm install --save @azure/identity

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

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

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

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

• Registro
• Client
• JobClient

fromTokenCredential richiede due parametri:

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

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

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

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

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

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

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

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

Esempi di codice

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

Creare un processo di 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
};

Chiamare scheduleDeviceMethod quindi per pianificare il processo di chiamata al metodo diretto:

• Ogni processo deve avere un ID processo univoco. È possibile usare questo ID processo per monitorare un processo come descritto nella sezione Monitorare un processo di questo articolo.
• Specificare un queryCondition parametro per valutare i dispositivi in cui eseguire il processo. Per altre informazioni sulle condizioni di query, vedere hub IoT linguaggio di query per dispositivi e moduli gemelli, processi e 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 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
       }
   }
};

Chiamare scheduleTwinUpdate quindi per pianificare il processo di aggiornamento della proprietà desiderata del dispositivo gemello:

• Ogni processo deve avere un ID processo univoco. È possibile usare questo ID processo per monitorare un processo come descritto nella sezione Monitorare un processo di questo articolo.
• Specificare un queryCondition parametro per valutare i dispositivi in cui eseguire il processo. Per altre informazioni sulle condizioni di query, vedere hub IoT linguaggio di query per dispositivi e moduli gemelli, processi e 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 del processo per un ID processo specifico fino al completamento o all'esito negativo 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 di pianificazione 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 altre informazioni, vedere Test E2E del client di processo.