Programación y difusión de trabajos

• Requiere Visual Studio

Información general

En este artículo se describe cómo usar la SDK de Azure IoT para .NET para crear código de aplicación de servicio back-end en un trabajo de programación para invocar un método directo o realizar una actualización de dispositivo gemelo en uno o varios dispositivos.

Agregar el paquete NuGet de servicio

Las aplicaciones de servicio back-end requieren el paquete NuGet de Microsoft.Azure.Devices.

Uso de declaraciones

Agregue las siguientes instrucciones de uso.

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

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

Conexión al centro de IoT

Puede conectar un servicio de back-end a IoT Hub mediante los siguientes métodos:

• Directiva de acceso compartido
• Microsoft Entra

Conexión mediante una directiva de acceso compartido

Conecte una aplicación back-end a un dispositivo mediante CreateFromConnectionString.

En este artículo se describe el código de back-end que puede programar un trabajo para invocar un método directo, programar un trabajo para actualizar un dispositivo gemelo y supervisar el progreso de un trabajo para uno o varios dispositivos. Para realizar estas operaciones, el servicio necesita los permisos de lectura del registro y escritura en el registro. De manera predeterminada, todas las instancias del centro de IoT se crean con una directiva de acceso compartido denominada registryReadWrite que concede estos permisos.

Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

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

Conexión mediante Microsoft Entra

Una aplicación de back-end que usa Microsoft Entra debe autenticarse de forma correcta y obtener una credencial de token de seguridad antes de conectarse a IoT Hub. El token se pasa a un método de conexión del IoT Hub. Para obtener información general sobre cómo configurar y usar Microsoft Entra para IoT Hub, vea Control del acceso a IoT Hub mediante Microsoft Entra ID.

Configuración de la aplicación de Microsoft Entra

Debe configurar una aplicación de Microsoft Entra que esté configurada para la credencial de autenticación que prefiera. La aplicación contiene parámetros como el secreto de cliente que son usados por la aplicación de back-end para autenticarse. Las configuraciones de autenticación de aplicaciones disponibles son las siguientes:

• Secreto del cliente
• Certificado
• Credencial de identidad federada

Es posible que las aplicaciones de Microsoft Entra necesiten permisos de rol específicos en función de las operaciones que se realicen. Por ejemplo, el Colaborador de gemelos de IoT Hub es necesario para permitir el acceso de lectura y escritura a un dispositivo IoT Hub y a los módulos gemelos. Para más información, vea Administración del acceso a IoT Hub mediante la asignación de roles de RBAC de Azure.

Para más información sobre la configuración de una aplicación de Microsoft Entra, vea Inicio rápido: Registro de una aplicación con la plataforma de identidad de Microsoft.

Autenticación con DefaultAzureCredential

La forma más sencilla de usar Microsoft Entra para autenticar una aplicación de back-end consiste en usar DefaultAzureCredential, pero se recomienda usar otro método en un entorno de producción, incluyendo una instancia de TokenCredential o reducida de ChainedTokenCredential específica. Para simplificar, en esta sección se describe la autenticación mediante DefaultAzureCredential y Secreto de cliente. Para información sobre las ventajas y las desventajas de usar DefaultAzureCredential, vea Guía de uso de DefaultAzureCredential.

DefaultAzureCredential admite distintos mecanismos de autenticación y determina el tipo de credencial adecuado en función del entorno en el que se ejecute. Intenta usar varios tipos de credenciales en un orden hasta que encuentra una credencial que funciona.

Microsoft Entra necesita estos paquetes NuGet y las instrucciones using correspondientes:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

En este ejemplo, el secreto de cliente de registro de la aplicación de Microsoft Entra, el id. de cliente y el id. de inquilino se agregan a variables de entorno. Estas variables de entorno son usadas por DefaultAzureCredential para autenticar la aplicación. El resultado de una autenticación correcta de Microsoft Entra es una credencial de token de seguridad que se pasa a un método de conexión de IoT Hub.

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

El TokenCredential resultante se puede pasar a un método para conectar a IoT Hub para cualquier cliente de SDK que acepte credenciales de Microsoft Entra.

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

En este ejemplo, TokenCredential se pasa a ServiceClient.Create para crear un objeto de conexión ServiceClient.

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

En este ejemplo, TokenCredential se pasa a RegistryManager.Create para crear un objeto RegistryManager.

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

Código de ejemplo

Para obtener un ejemplo práctico de autenticación de servicios de Microsoft Entra, vea Ejemplo de autenticación basada en roles.

Programar un trabajo de método directo

Use ScheduleDeviceMethodAsync para programar un trabajo para ejecutar un método directo en uno o varios dispositivos.

Usa el objeto CloudToDeviceMethod para especificar el nombre del método directo y los valores de tiempo de espera de conexión del dispositivo.

Por ejemplo:

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

En este ejemplo se programa un trabajo para un método directo denominado "LockDoor" en un dispositivo denominado "Device-1". Los dispositivos incluidos en el trabajo programado contienen el segundo parámetro como una condición de consulta. Para obtener más información sobre las condiciones de consulta, consulte Lenguaje de consulta de IoT Hub para dispositivos y módulos gemelos, trabajos y enrutamiento de mensajes.

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

Programación de un trabajo de actualización de dispositivo gemelo

Use ScheduleTwinUpdateAsync para programar un nuevo trabajo de actualización de etiquetas y propiedades deseadas de dispositivos gemelos para que se ejecuten en uno o varios dispositivos.

En primer lugar, cree y rellene un dispositivo objeto Gemelo digital para la actualización. Por ejemplo:

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;

A continuación, llame a ScheduleTwinUpdateAsync. Especifique los dispositivos que se van a actualizar como una consulta en el segundo parámetro. Para obtener más información sobre las condiciones de consulta, consulte Lenguaje de consulta de IoT Hub para dispositivos y módulos gemelos, trabajos y enrutamiento de mensajes.

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

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

Supervisión de un trabajo

Utiliza GetJobAsync para supervisar el estado del trabajo para un ID de trabajo específico.

En este ejemplo se comprueba el estado del trabajo de un identificador de trabajo periódicamente hasta que se complete o se haya producido un error en el estado del trabajo. Por ejemplo:

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

Ejemplos de tareas programadas con el SDK

El SDK de Azure IoT para .NET proporciona ejemplos de trabajo de aplicaciones de servicio que controlan las tareas de programación de trabajos. Para más información, vea:

• Ejemplo de actualización de programación de gemelo digital
• Ejemplo de actualización del gemelo de programación de E2E.

• Requiere Java SE Development Kit 8. Asegúrese de seleccionar Java 8 en Soporte técnico a largo plazo para obtener descargas de JDK 8.

Información general

En este artículo se describe cómo usar la SDK de Azure IoT para Java para crear código de aplicación de servicio back-end para programar el trabajo para invocar un método directo o realizar una actualización de dispositivo gemelo en uno o varios dispositivos.

Declaraciones de importación de servicios

La clase JobClient contiene métodos que los servicios pueden usar para programar trabajos.

Use las siguientes instrucciones de importación de servicio para acceder al SDK de Azure IoT para 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;

Conexión a IoT Hub

Puede conectar un servicio de back-end a IoT Hub mediante los siguientes métodos:

• Directiva de acceso compartido
• Microsoft Entra

Conexión mediante una directiva de acceso compartido

Use un constructor JobClient para crear la conexión a IoT Hub. El objeto JobClient controla la comunicación con el IoT Hub.

En este artículo se describe el código de back-end que puede programar un trabajo para invocar un método directo, programar un trabajo para actualizar un dispositivo gemelo y supervisar el progreso de un trabajo para uno o varios dispositivos. Para realizar estas operaciones, el servicio necesita los permisos de lectura del registro y escritura en el registro. De manera predeterminada, todas las instancias del centro de IoT se crean con una directiva de acceso compartido denominada registryReadWrite que concede estos permisos.

Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

Por ejemplo:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(iotHubConnectionString);

Conexión mediante Microsoft Entra

Una aplicación de back-end que usa Microsoft Entra debe autenticarse de forma correcta y obtener una credencial de token de seguridad antes de conectarse a IoT Hub. Este token se pasa a un método de conexión de IoT Hub. Para obtener información general sobre cómo configurar y usar Microsoft Entra para IoT Hub, vea Control del acceso a IoT Hub mediante Microsoft Entra ID.

Para obtener información general sobre la autenticación del SDK de Java, vea Autenticación de Azure con Java e Identidad de Azure.

Para simplificar, en esta sección se describe la autenticación mediante un secreto de cliente.

Configuración de la aplicación de Microsoft Entra

Debe configurar una aplicación de Microsoft Entra que esté configurada para la credencial de autenticación que prefiera. La aplicación contiene parámetros como el secreto de cliente que son usados por la aplicación de back-end para autenticarse. Las configuraciones de autenticación de aplicaciones disponibles son las siguientes:

• Secreto del cliente
• Certificado
• Credencial de identidad federada

Es posible que las aplicaciones de Microsoft Entra necesiten permisos de rol específicos en función de las operaciones que se realicen. Por ejemplo, Colaborador de gemelos de IoT Hub es necesario para permitir el acceso de lectura y escritura a un dispositivo IoT Hub y a los módulos gemelos. Para más información, vea Administración del acceso a IoT Hub mediante la asignación de roles de RBAC de Azure.

Para más información sobre la configuración de una aplicación de Microsoft Entra, vea Inicio rápido: Registro de una aplicación con la plataforma de identidad de Microsoft.

Autenticación con DefaultAzureCredential

La forma más sencilla de usar Microsoft Entra para autenticar una aplicación de back-end consiste en usar DefaultAzureCredential, pero se recomienda usar otro método en un entorno de producción, incluyendo una instancia específica o simplificada de ChainedTokenCredential. Para más información sobre las ventajas y desventajas de usar DefaultAzureCredential, vea Cadenas de credenciales en la biblioteca cliente de Identidad de Azure para Java.

DefaultAzureCredential admite distintos mecanismos de autenticación y determina el tipo de credencial adecuado en función del entorno en el que se ejecute. Intenta usar varios tipos de credenciales en un orden hasta que encuentra una credencial que funciona.

Puede autenticar las credenciales de aplicación de Microsoft Entra mediante DefaultAzureCredentialBuilder. Guarde parámetros de conexión como tenantID del secreto de cliente, clientID y valores de secreto de cliente como variables de entorno. Una vez que se haya creadTokenCredential, páselo a ServiceClient u otro generador como parámetro "credential".

En este ejemplo, DefaultAzureCredentialBuilder intenta autenticar una conexión de la lista descrita en DefaultAzureCredential. El resultado de una autenticación correcta de Microsoft Entra es una credencial de token de seguridad que se pasa a un constructor como ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Autenticación mediante ClientSecretCredentialBuilder

Puede usar ClientSecretCredentialBuilder para crear una credencial mediante la información del secreto de cliente. Si se ejecuta correctamente, este método devuelve un valor TokenCredential que se puede pasar a ServiceClient u otro generador como parámetro "credential".

En este ejemplo, los valores de secreto de cliente de registro de la aplicación de Microsoft Entra, el id. de cliente y el id. de inquilino se han agregado a las variables de entorno. Estas variables de entorno las usa ClientSecretCredentialBuilder para crear la credencial.

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

Otras clases de autenticación

El SDK de Java también incluye estas clases que autentican una aplicación de back-end con Microsoft Entra:

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

Ejemplos de código

Para obtener ejemplos prácticos de autenticación de servicios de Microsoft Entra, vea Ejemplo de autenticación basada en roles.

Programar una tarea de actualización mediante un método directo

Use scheduleDeviceMethod para ejecutar un método directo en uno o varios dispositivos.

Este método de ejemplo programa una tarea para un método directo llamado "lockDoor" en un dispositivo llamado "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());
}

Programación de un trabajo de actualización de dispositivo gemelo

Use scheduleUpdateTwin para programar un trabajo para ejecutar una actualización de dispositivos gemelos en uno o varios dispositivos.

En primer lugar, prepare un registro DeviceTwinDevice para la actualización del dispositivo gemelo. Por ejemplo:

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("*");

A continuación, llame a scheduleUpdateTwin para programar el trabajo de actualización. Por ejemplo:

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

Supervisión de un trabajo

Use getJob para capturar información del trabajo en función de un identificador de trabajo específico. getJob devuelve un objeto JobResult que contiene métodos y propiedades que puede usar para comprobar la información del trabajo, incluido el estado de ejecución.

Por ejemplo:

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

Consulta de un estado de trabajo

Use queryDeviceJob para consultar el estado del trabajo de uno o varios trabajos.

Por ejemplo:

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

Ejemplo de trabajo de programación del SDK

El SDK de Azure IoT para Java proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas de programación de trabajos. Para más información, consulte Ejemplo de cliente de trabajo.

• SDK de Python: se recomienda la versión 3.7 de Python o posterior. Asegúrese de usar la instalación de 32 bits o 64 bits en función del programa de instalación. Cuando se le solicite durante la instalación, asegúrese de agregar Python a la variable de entorno específica de la plataforma.

Información general

En este artículo se describe cómo usar la SDK de Azure IoT para Python para crear código de aplicación de servicio back-end que programa el trabajo para invocar un método directo o realizar una actualización de propiedad deseada del dispositivo gemelo en uno o varios dispositivos.

Instalación del paquete

La biblioteca azure-iot-hub debe estar instalada para crear aplicaciones de servicios back-end.

pip install azure-iot-hub

Instrucciones import

La clase IoTHubJobManager expone todos los métodos necesarios para crear una aplicación back-end para programar trabajos desde el servicio.

Agregue las siguientes instrucciones import.

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

Conexión al centro de IoT

Puede conectar un servicio de back-end a IoT Hub mediante los siguientes métodos:

• Directiva de acceso compartido
• Microsoft Entra

Conexión mediante una directiva de acceso compartido

Conéctese a IoT Hub mediante from_connection_string.

En este artículo se describe el código de back-end que puede programar un trabajo para invocar un método directo, programar un trabajo para actualizar un dispositivo gemelo y supervisar el progreso de un trabajo para uno o varios dispositivos. Para realizar estas operaciones, el servicio necesita los permisos de lectura del registro y escritura en el registro. De manera predeterminada, todas las instancias del centro de IoT se crean con una directiva de acceso compartido denominada registryReadWrite que concede estos permisos.

Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

Por ejemplo:

IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(IoTHubConnectionString)

Conexión mediante Microsoft Entra

Una aplicación de back-end que usa Microsoft Entra debe autenticarse de forma correcta y obtener una credencial de token de seguridad antes de conectarse a IoT Hub. Este token se pasa a un método de conexión de IoT Hub. Para obtener información general sobre cómo configurar y usar Microsoft Entra para IoT Hub, vea Control del acceso a IoT Hub mediante Microsoft Entra ID.

Configuración de la aplicación de Microsoft Entra

Debe configurar una aplicación de Microsoft Entra que esté configurada para la credencial de autenticación que prefiera. La aplicación contiene parámetros como el secreto de cliente que son usados por la aplicación de back-end para autenticarse. Las configuraciones de autenticación de aplicaciones disponibles son las siguientes:

• Secreto del cliente
• Certificado
• Credencial de identidad federada

Es posible que las aplicaciones de Microsoft Entra necesiten permisos de rol específicos en función de las operaciones que se realicen. Por ejemplo, Colaborador de gemelos de IoT Hub es necesario para permitir el acceso de lectura y escritura a un dispositivo IoT Hub y a los módulos gemelos. Para más información, vea Administración del acceso a IoT Hub mediante la asignación de roles de RBAC de Azure.

Para más información sobre la configuración de una aplicación de Microsoft Entra, vea Inicio rápido: Registro de una aplicación con la plataforma de identidad de Microsoft.

Autenticación con DefaultAzureCredential

La forma más sencilla de usar Microsoft Entra para autenticar una aplicación de back-end consiste en usar DefaultAzureCredential, pero se recomienda utilizar otro método para un entorno de producción, como una TokenCredential específica o una ChainedTokenCredential simplificada. Para simplificar, en esta sección se describe la autenticación mediante DefaultAzureCredential y Secreto de cliente. Para información sobre las ventajas y las desventajas de usar DefaultAzureCredential, vea Guía de uso de DefaultAzureCredential.

DefaultAzureCredential admite distintos mecanismos de autenticación y determina el tipo de credencial adecuado en función del entorno en el que se ejecute. Intenta usar varios tipos de credenciales en un orden hasta que encuentra una credencial que funciona.

Microsoft Entra necesita estos paquetes NuGet y las instrucciones using correspondientes:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

En este ejemplo, el secreto de cliente de registro de la aplicación de Microsoft Entra, el id. de cliente y el id. de inquilino se agregan a variables de entorno. Estas variables de entorno son usadas por DefaultAzureCredential para autenticar la aplicación. El resultado de una autenticación exitosa de Microsoft Entra es una credencial de token de seguridad que se transfiere a un método de conexión de IoT Hub.

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

El TokenCredential resultante se puede pasar a un método para conectar a IoT Hub para cualquier cliente del SDK que acepte credenciales de Microsoft Entra.

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

En este ejemplo, TokenCredential se pasa a ServiceClient.Create para crear un objeto de conexión ServiceClient.

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

En este ejemplo, TokenCredential se pasa a RegistryManager.Create para crear un objeto RegistryManager.

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

Código de ejemplo

Para obtener un ejemplo práctico de autenticación de servicios de Microsoft Entra, vea Ejemplo de autenticación basada en roles.

Programar un trabajo de método directo

Use create_scheduled_job para programar un nuevo método directo para ejecutar un método directo en uno o varios dispositivos:

create_scheduled_job notas de parámetros:

• job_id deben ser únicos
• Establezca type en scheduleDeviceMethod.
• Use cloud_to_device_method para establecer el nombre y la carga del método directo
• Usar max_execution_time_in_seconds para especificar el tiempo de ejecución en segundos
• Use query_condition para especificar los dispositivos que se incluirán para la llamada al método directo. Para obtener más información sobre las condiciones de consulta, consulte Lenguaje de consulta de IoT Hub para dispositivos y módulos gemelos, trabajos y enrutamiento de mensajes.

Por ejemplo:

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)

Programación de un trabajo de actualización de dispositivo gemelo

Use create_scheduled_job para crear un nuevo trabajo para ejecutar una actualización de propiedades deseadas de dispositivo gemelo en uno o varios dispositivos.

create_scheduled_job notas de parámetros:

• job_id deben ser únicos
• Establezca type en scheduleUpdateTwin.
• Use update_twin para establecer el nombre y la carga del método directo
• Usar max_execution_time_in_seconds para especificar el tiempo de ejecución en segundos
• Use query_condition para especificar una condición para uno o varios dispositivos que tengan la llamada de método directo. Para obtener más información sobre las condiciones de consulta, consulte Lenguaje de consulta de IoT Hub para dispositivos y módulos gemelos, trabajos y enrutamiento de mensajes.

Por ejemplo:

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)

Supervisión de un trabajo

Emplea get_scheduled_job para recuperar los detalles de un trabajo específico en un centro IoT.

En este ejemplo se comprueba el estado del trabajo de un identificador de trabajo específico cada cinco segundos hasta que se complete el trabajo.

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)

Ejemplos de tareas programadas del SDK

El SDK de Azure IoT para Python proporciona ejemplos de trabajo de aplicaciones de servicio que controlan las tareas de programación de trabajos. Para más información, vea:

• Programar un trabajo de método directo
• Programar una actualización de dispositivo gemelo.

• Requiere Node.js versión 10.0.x o posterior

Información general

En este artículo se describe cómo usar el SDK de Azure IoT de para Node.js para crear código de aplicación de servicio back-end para programar el trabajo para invocar un método directo o realizar una actualización de dispositivo gemelo en uno o varios dispositivos.

Instalación del paquete de SDK de servicio

Ejecute este comando para instalar azure-iothub en la máquina de desarrollo:

npm install azure-iothub --save

La clase JobClient expone todos los métodos necesarios para interactuar con la programación de trabajos desde una aplicación back-end.

Conexión al centro de IoT

Puede conectar un servicio de back-end a IoT Hub mediante los siguientes métodos:

• Directiva de acceso compartido
• Microsoft Entra

Conexión mediante una directiva de acceso compartido

Use fromConnectionString para conectarse a IoT Hub.

En este artículo se describe el código de back-end que puede programar un trabajo para invocar un método directo, programar un trabajo para actualizar un dispositivo gemelo y supervisar el progreso de un trabajo para uno o varios dispositivos. Para realizar estas operaciones, el servicio necesita los permisos de lectura del registro y escritura en el registro. De manera predeterminada, todas las instancias del centro de IoT se crean con una directiva de acceso compartido denominada registryReadWrite que concede estos permisos.

Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

Por ejemplo:

'use strict';
var JobClient = require('azure-iothub').JobClient;
var connectionString = '{Shared access policy connection string}';
var jobClient = JobClient.fromConnectionString(connectionString);

Conexión mediante Microsoft Entra

Una aplicación de back-end que usa Microsoft Entra debe autenticarse de forma correcta y obtener una credencial de token de seguridad antes de conectarse a IoT Hub. Este token se pasa a un método de conexión de IoT Hub. Para obtener información general sobre cómo configurar y usar Microsoft Entra para IoT Hub, vea Control del acceso a IoT Hub mediante Microsoft Entra ID.

Para obtener información general sobre la autenticación del SDK de Node.js, vea lo siguiente:

• Introducción a la autenticación de usuarios en Azure
• Biblioteca cliente de Azure Identity para JavaScript

Configuración de la aplicación de Microsoft Entra

Debe configurar una aplicación de Microsoft Entra que esté configurada para la credencial de autenticación que prefiera. La aplicación contiene parámetros como el secreto de cliente que son usados por la aplicación de back-end para autenticarse. Las configuraciones de autenticación de aplicaciones disponibles son las siguientes:

• Secreto del cliente
• Certificado
• Credencial de identidad federada

Es posible que las aplicaciones de Microsoft Entra necesiten permisos de rol específicos en función de las operaciones que se realicen. Por ejemplo, Colaborador de gemelos de IoT Hub es necesario para permitir el acceso de lectura y escritura a un dispositivo IoT Hub y a los módulos gemelos. Para más información, vea Administración del acceso a IoT Hub mediante la asignación de roles de RBAC de Azure.

Para más información sobre la configuración de una aplicación de Microsoft Entra, vea Inicio rápido: Registro de una aplicación con la plataforma de identidad de Microsoft.

Autenticación con DefaultAzureCredential

La forma más sencilla de usar Microsoft Entra para autenticar una aplicación de back-end consiste en usar DefaultAzureCredential, pero se recomienda usar otro método en un entorno de producción, incluyendo una instancia específica de TokenCredential o una versión reducida de ChainedTokenCredential. Para simplificar, en esta sección se describe la autenticación mediante DefaultAzureCredential y Secreto de cliente. Para más información sobre las ventajas y desventajas de usar DefaultAzureCredential, vea Cadenas de credenciales en la biblioteca cliente de Identidad de Azure para JavaScript

DefaultAzureCredential admite distintos mecanismos de autenticación y determina el tipo de credencial adecuado en función del entorno en el que se ejecute. Intenta usar varios tipos de credenciales en un orden hasta que encuentra una credencial que funciona.

Microsoft Entra necesita este paquete:

npm install --save @azure/identity

En este ejemplo, el secreto de cliente de registro de la aplicación de Microsoft Entra, el id. de cliente y el id. de inquilino se han agregado a variables de entorno. Estas variables de entorno son usadas por DefaultAzureCredential para autenticar la aplicación. El resultado de una autenticación correcta de Microsoft Entra es una credencial de token de seguridad que se pasa a un método de conexión de IoT Hub.

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

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

Después, el token de credencial resultante se puede pasar a fromTokenCredential a fin de conectarse a IoT Hub para cualquier cliente SDK que acepte las credenciales de Microsoft Entra:

• Registro
• Cliente
• JobClient

fromTokenCredential necesita dos parámetros:

• URL del servicio de Azure: la URL del servicio de Azure debe tener el formato {Your Entra ___domain URL}.azure-devices.net sin un prefijo https://. Por ejemplo, MyAzureDomain.azure-devices.net.
• El token de credenciales de Azure

En este ejemplo, la credencial de Azure se obtiene mediante DefaultAzureCredential. Después, la URL y las credenciales del dominio de Azure se proporcionan a Registry.fromTokenCredential para crear la conexión a IoT Hub.

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

Ejemplos de código

Para obtener ejemplos prácticos de autenticación del servicio Microsoft Entra, vea Ejemplos de identidad de Azure.

Crear un trabajo de método directo

Utilice scheduleDeviceMethod para programar un trabajo que ejecute un método directo en uno o varios dispositivos.

Primero, cree una variable para actualizar el método directo que incluya el nombre del método, la carga útil y la información del tiempo de espera de respuesta. Por ejemplo:

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

A continuación, llame a scheduleDeviceMethod para programar la tarea de llamada del método directo.

• Cada trabajo debe tener un identificador de trabajo único. Puede usar este identificador de trabajo para supervisar un trabajo como se describe en la sección Supervisión de un trabajo de este artículo.
• Especifique un parámetro queryCondition para evaluar los dispositivos en los que ejecutar el trabajo. Para obtener más información sobre las condiciones de consulta, consulte Lenguaje de consulta de IoT Hub para dispositivos y módulos gemelos, trabajos y enrutamiento de mensajes.
• Compruebe la devolución de llamada de jobResult para obtener el resultado de la programación del trabajo. Si el trabajo se programó correctamente, puede supervisar el estado del trabajo como se muestra en la sección Supervisión de un trabajo de este artículo.

Por ejemplo:

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

Programación de un trabajo de actualización de dispositivo gemelo

Utiliza scheduleTwinUpdate para crear una nueva tarea que ejecuta una actualización de dispositivo gemelo en uno o varios dispositivos.

En primer lugar, cree una variable de actualización de propiedad deseada del dispositivo gemelo.

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

A continuación, llame a scheduleTwinUpdate para programar el trabajo de actualización de propiedades deseadas del dispositivo gemelo:

• Cada trabajo debe tener un identificador de trabajo único. Puede usar este identificador de trabajo para supervisar un trabajo como se describe en la sección Supervisión de un trabajo de este artículo.
• Especifique un parámetro queryCondition para evaluar los dispositivos en los que ejecutar el trabajo. Para obtener más información sobre las condiciones de consulta, consulte Lenguaje de consulta de IoT Hub para dispositivos y módulos gemelos, trabajos y enrutamiento de mensajes.
• Compruebe la devolución de llamada jobResult para obtener el resultado de la programación del trabajo. Si el trabajo se programó correctamente, puede supervisar el estado del trabajo como se muestra en la sección Supervisión de un trabajo de este artículo.

Por ejemplo:

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

Supervisión de un trabajo

Usa getJob para monitorear el estado de un trabajo con un ID específico.

Esta función de ejemplo comprueba el estado del trabajo de un identificador de trabajo específico periódicamente hasta que el trabajo se complete o se haya producido un error.

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

Ejemplo de trabajo de programación del SDK

El SDK de Azure IoT para Node.js proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas de programación de trabajos. Para obtener más información, consulte Prueba del cliente de trabajo E2E.