Compartir vía

Introducción a la administración de dispositivos

  • Artículo

Las aplicaciones de back-end pueden usar primitivos de Azure IoT Hub, como dispositivos gemelos y métodos directos, para iniciar y supervisar de forma remota las acciones de administración de dispositivos en los dispositivos.

Use un método directo desde una aplicación de back-end para iniciar acciones de administración de dispositivos, como el reinicio, el restablecimiento de fábrica y la actualización del firmware.

El dispositivo es responsable de:

  • Control de la solicitud de método directo enviada desde IoT Hub
  • Inicio de la acción específica del dispositivo correspondiente en el dispositivo
  • Proporcionar actualizaciones de estado mediante las propiedades notificadas a IoT Hub

Este artículo le muestra cómo una aplicación de back-end y una aplicación de dispositivo pueden trabajar juntas para iniciar y supervisar la acción de un dispositivo remoto usando un método directo.

  • Una aplicación de servicio llama a un método directo para reiniciar en una aplicación de dispositivo a través de un centro de IoT.
  • Una aplicación de dispositivo controla un método directo para reiniciar un dispositivo.

Nota:

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.

Nota:

Este artículo está diseñado para complementar los ejemplos del SDK de Azure IoT a los que se hace referencia desde este artículo. Puede usar las herramientas del SDK para compilar aplicaciones de dispositivo y back-end.

Requisitos previos

  • Un centro de IoT

  • Un dispositivo registrado

  • Si la aplicación usa el protocolo MQTT, asegúrese de que el puerto 8883 esté abierto en el firewall. El protocolo MQTT se comunica a través del puerto 8883. Este puerto puede estar bloqueado en algunos entornos de red corporativos y educativos. Para más información y para saber cómo solucionar este problema, consulte el artículo sobre la conexión a IoT Hub (MQTT).

  • Requiere Visual Studio

Información general

En este artículo se describe cómo usar el SDK de Azure IoT para .NET para crear código de aplicación de servicio de dispositivo y back-end para mensajes directos de dispositivos.

Creación de una aplicación de dispositivo

En esta sección se describe cómo usar el código de aplicación de dispositivo para crear un agente de escucha de devolución de llamada de método directo.

Importante

En este artículo se incluyen los pasos para conectar un dispositivo mediante una firma de acceso compartido, también denominada autenticación de clave simétrica. Este método de autenticación es cómodo para probar y evaluar, pero autenticar un dispositivo mediante certificados X.509 es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de > Seguridad de la conexión.

Paquete NuGet de dispositivo necesario

Las aplicaciones cliente de dispositivo escritas en C# requieren el paquete NuGet Microsoft.Azure.Devices.Client.

Agregue estas instrucciones using para usar la biblioteca de dispositivos.

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

Conectarse a un dispositivo

La clase DeviceClient expone todos los métodos necesarios para interactuar con mensajes de dispositivos desde el dispositivo.

Conéctese al dispositivo mediante el método CreateFromConnectionString junto con la cadena de conexión del dispositivo y el protocolo de transporte de conexión.

El parámetro de protocolo de transporte CreateFromConnectionString TransportType admite los siguientes protocolos de transporte:

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

Este ejemplo se conecta a un dispositivo mediante el protocolo de transporte Mqtt.

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

Creación de un agente de escucha de devolución de llamada de método directo

Use SetMethodHandlerAsync para inicializar un agente de escucha de devolución de llamada de método directo. El agente de escucha está asociado a una palabra clave de nombre de método, como "reboot". El nombre del método se puede usar en una aplicación de IoT Hub o back-end para desencadenar el método de devolución de llamada en el dispositivo.

En este ejemplo se configura un agente de escucha de devolución de llamada denominado onReboot que se desencadenará cuando se llame al nombre del método directo "reboot".

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

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

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

Siguiendo con el ejemplo, el método de devolución de llamada onReboot implementa el método directo en el dispositivo.

La función del controlador llama a MethodResponse para enviar una confirmación de respuesta a la aplicación que llama.

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

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

Nota:

Por simplificar, este artículo no implementa ninguna directiva de reintentos. En el código de producción, deberá implementar directivas de reintentos (por ejemplo, retroceso exponencial), tal y como se sugiere en Control de errores transitorios.

Ejemplos de dispositivos del SDK

El SDK de Azure IoT para .NET proporciona muestras de funcionamiento de aplicaciones para dispositivos que controlan tareas de métodos directos. Para más información, vea:

Creación de una aplicación back-end

En esta sección se describe cómo desencadenar un método directo en un dispositivo.

La clase ServiceClient expone todos los métodos necesarios para crear una aplicación de back-end que envíe llamadas de método directas a los dispositivos.

Paquete NuGet de servicio requerido

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

Agregue estas instrucciones using para usar la biblioteca de servicios.

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

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

Importante

En este artículo se incluyen los pasos para conectarse a un servicio mediante una firma de acceso compartido. Este método de autenticación es cómodo para las pruebas y la evaluación, pero la autenticación en un servicio con el Microsoft Entra ID o las identidades administradas es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de seguridad> Seguridad en la nube.

Conexión mediante una directiva de acceso compartido

Conecte una aplicación de back-end usando CreateFromConnectionString.

Para invocar un método directo en un dispositivo a través de IoT Hub, el servicio necesita el permiso Conexión del servicio. De forma predeterminada, todas las instancias de IoT Hub se crean con una directiva de acceso compartido denominada servicio que concede este permiso.

Como parámetro para CreateFromConnectionString, proporcione la directiva de acceso compartido del servicio. Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

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

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 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 valor TokenCredential resultante se puede pasar a un método de conexión a IoT Hub para cualquier cliente del SDK que acepte credenciales de Microsoft Entra:

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.

Invocación a un método en un dispositivo

Para invocar un método en un dispositivo:

  1. Cree un objeto CloudToDeviceMethod. Pase el nombre del método directo del dispositivo como parámetro.
  2. Llame a InvokeDeviceMethodAsync para invocar el método en el dispositivo.

En este ejemplo se llama al método "reboot" para iniciar un reinicio en el dispositivo. El método "reboot" se asigna a un agente de escucha en el dispositivo, tal como se describe en la sección Creación de un agente de escucha de devolución de llamada de método directo de este artículo.

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

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

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

Muestras de servicio SDK

El SDK de Azure IoT para .NET proporciona muestras de funcionamiento de aplicaciones de servicio que controlan las tareas relacionadas con los mensajes. Para más información, vea:

  • 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 de dispositivo y back-end para métodos directos de dispositivo.

Creación de una aplicación de dispositivo

En esta sección se describe cómo usar el código de aplicación de dispositivo para crear un agente de escucha de devolución de llamada de método directo.

Importante

En este artículo se incluyen los pasos para conectar un dispositivo mediante una firma de acceso compartido, también denominada autenticación de clave simétrica. Este método de autenticación es cómodo para probar y evaluar, pero autenticar un dispositivo mediante certificados X.509 es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de > Seguridad de la conexión.

Instrucción de importación de dispositivos

Use las siguientes instrucciones de importación de dispositivos para acceder al SDK de Azure IoT para Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

Conectarse a un dispositivo

La clase DeviceClient expone todos los métodos que necesita para interactuar con los métodos directos del dispositivo.

Cómo conectarlo a un dispositivo:

  1. Use IotHubClientProtocol para elegir un protocolo de transporte. Por ejemplo:

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

  2. Use el constructor DeviceClient para agregar la cadena de conexión principal y el protocolo del dispositivo.

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

  3. Use abrir para conectar el dispositivo a IoT Hub. Si el cliente ya está abierto, el método no hace nada.

    client.open(true);

Creación de un agente de escucha de devolución de llamada de método directo

Use subscribeToMethods para inicializar un agente de escucha de devolución de llamada de método directo. subscribeToMethods escucha los métodos directos entrantes hasta que finaliza la conexión. El nombre del método y la carga se reciben para cada llamada de método directo.

El agente de escucha debe llamar a DirectMethodResponse para enviar una confirmación de respuesta de método a la aplicación que realiza la llamada.

Por ejemplo:

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

Nota:

Por simplificar, este artículo no implementa ninguna directiva de reintentos. En el código de producción, deberá implementar directivas de reintentos (por ejemplo, retroceso exponencial), tal y como se sugiere en Control de errores transitorios.

Ejemplos de dispositivos del SDK

El SDK de Azure IoT para Java incluye un ejemplo de trabajo para probar los conceptos de la aplicación de dispositivo descritos en este artículo. Para más información, consulte Muestra de método directo.

Creación de una aplicación back-end

En esta sección se describe cómo iniciar un reinicio remoto en un dispositivo mediante un método directo.

La clase ServiceClient DeviceMethod contiene métodos que los servicios pueden utilizar para acceder a los dispositivos gemelos.

Instrucciones de importación de servicio

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

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

Importante

En este artículo se incluyen los pasos para conectarse a un servicio mediante una firma de acceso compartido. Este método de autenticación es cómodo para las pruebas y la evaluación, pero la autenticación en un servicio con el Microsoft Entra ID o las identidades administradas es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de seguridad> Seguridad en la nube.

Conexión mediante una directiva de acceso compartido

Use el constructor DeviceMethod para agregar la cadena de conexión principal del servicio y conectarse a IoT Hub.

Para invocar un método directo en un dispositivo a través de IoT Hub, el servicio necesita el permiso Conexión del servicio. De forma predeterminada, todas las instancias de IoT Hub se crean con una directiva de acceso compartido denominada servicio que concede este permiso.

Como parámetro del constructor DeviceMethod, proporcione la directiva de acceso compartido del servicio. 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:

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(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 de TokenCredential o reducida de ChainedTokenCredential específica. 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:

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.

Invocación a un método en un dispositivo

Llame a DeviceMethod.invoke para invocar un método en un dispositivo y devolver el estado del resultado.

El parámetro de carga invoke es opcional. Use null si no se proporciona ninguna carga útil. El parámetro de carga puede tomar diferentes formas de datos, como cadena, matriz de bytes y HashMap. Para ver ejemplos, consulte Pruebas de métodos directos.

En este ejemplo se llama al método "reboot" para iniciar un reinicio en el dispositivo. El método "reboot" se asigna a un agente de escucha en el dispositivo, tal como se describe en la sección Creación de un agente de escucha de devolución de llamada de método directo de este artículo.

Por ejemplo:

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

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

Muestras de servicio SDK

El SDK de Azure IoT para Java proporciona una muestra en funcionamiento de aplicaciones de servicio que controlan tareas de métodos directos. Para más información, vea:

  • 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 de dispositivo y back-end para métodos directos de dispositivo.

Instalar paquetes

La biblioteca azure-iot-device debe estar instalada para crear aplicaciones de dispositivos.

pip install azure-iot-device

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

pip install azure-iot-hub

Creación de una aplicación de dispositivo

En esta sección se describe cómo usar el código de aplicación de dispositivo para crear un agente de escucha de devolución de llamada de método directo.

Importante

En este artículo se incluyen los pasos para conectar un dispositivo mediante una firma de acceso compartido, también denominada autenticación de clave simétrica. Este método de autenticación es cómodo para probar y evaluar, pero autenticar un dispositivo mediante certificados X.509 es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de > Seguridad de la conexión.

Instrucciones de importación de dispositivos

Agregue esta instrucción de importación para acceder a IoTHubDeviceClient y MethodResponse.

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

Conectarse a un dispositivo

La clase IoTHubDeviceClient contiene métodos que se pueden usar para trabajar con métodos directos.

Use create_from_connection_string para conectar una aplicación a un dispositivo mediante una cadena de conexión de dispositivo.

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

Creación de una devolución de llamada de método directo

Use on_method_request_received para crear una función de controlador o corrutina a la que se llama cuando se recibe un método directo. El agente de escucha está asociado a una palabra clave de nombre de método, como "reboot". El nombre del método se puede usar en una aplicación de IoT Hub o back-end para desencadenar el método de devolución de llamada en el dispositivo.

La función del controlador debería crear una MethodResponse y pasarla a send_method_response para enviar una confirmación de respuesta de método directo a la aplicación que llama.

En este ejemplo se configura un controlador de método directo denominado method_request_handler.

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

En este ejemplo, el método de devolución de llamada method_request_handler implementa el método directo en el dispositivo. El código se ejecuta cuando se llama al método directo "rebootDevice" desde una aplicación de servicio. El método llama a send_method_response para enviar una confirmación de respuesta de método directo a la aplicación que llama.

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

    # Send the method response
    client.send_method_response(method_response)

Ejemplos de dispositivos del SDK

El SDK de Azure IoT para Python proporciona un ejemplo de trabajo de una aplicación de dispositivo que controla las tareas de método directo. Para más información, consulte Recepción de método directo.

Creación de una aplicación back-end

Esta sección describe cómo usar una aplicación de servicio de back-end para llamar a un método directo en un dispositivo.

La clase IoTHubRegistryManager expone todos los métodos necesarios para crear una aplicación de back-end para enviar mensajes a un dispositivo.

Instrucciones de importación de servicio

Agregue estas instrucciones de importación para conectarse a IoT Hub, enviar métodos directos de nube a dispositivo y recibir respuestas de métodos directos de dispositivo.

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

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

Importante

En este artículo se incluyen los pasos para conectarse a un servicio mediante una firma de acceso compartido. Este método de autenticación es cómodo para las pruebas y la evaluación, pero la autenticación en un servicio con el Microsoft Entra ID o las identidades administradas es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de seguridad> Seguridad en la nube.

Conexión mediante una directiva de acceso compartido

Conéctese a IoT Hub mediante from_connection_string.

Para invocar un método directo en un dispositivo a través de IoT Hub, el servicio necesita el permiso Conexión del servicio. De forma predeterminada, todas las instancias de IoT Hub se crean con una directiva de acceso compartido denominada servicio que concede este permiso.

Como parámetro para from_connection_string, proporcione la directiva de acceso compartido del servicio. 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:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

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 de la autenticación del SDK de Python, vea Autenticación de aplicaciones de Python en servicios de Azure mediante el SDK de Azure para Python

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

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 de importación y la instrucción import correspondiente:

pip install azure-identity

from azure.identity import DefaultAzureCredential

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.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

El valor AccessToken resultante se puede pasar a from_token_credential a fin de conectarse a IoT Hub para cualquier cliente SDK que acepte credenciales de Microsoft Entra:

from_token_credential 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 servicio de Azure se proporcionan a IoTHubRegistryManager.from_token_credential para crear la conexión a IoT Hub.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

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

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)
Ejemplos de código

Para obtener ejemplos prácticos de autenticación del servicio Microsoft Entra, vea Biblioteca de autenticación de Microsoft (MSAL) para Python.

Invocación a un método en un dispositivo

Puede invocar un método directo por su nombre en un dispositivo. El nombre del método identifica el método. En el siguiente y anterior ejemplo de dispositivo mostrado en Creación de una devolución de llamada de método directo, el nombre del método directo es "rebootDevice".

Para invocar un método directo en un dispositivo, haga lo siguiente:

  1. Cree un objeto CloudToDeviceMethod. Proporcione el nombre del método y la carga como parámetros.
  2. Llame a invoke_device_method para invocar un método directo en un dispositivo. Proporcione como parámetros el id. del dispositivo y el objeto de carga CloudToDeviceMethod.

En este ejemplo se llama a CloudToDeviceMethod para invocar un método directo denominado "rebootDevice" en un dispositivo. Una vez invocado correctamente el método directo, se muestra la carga de respuesta del método directo.

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

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

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

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

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

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

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

Muestras de servicio SDK

El SDK de Azure IoT para Python proporciona muestras de funcionamiento de aplicaciones de servicio que controlan tareas de métodos directos. Para más información, vea:

  • 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 para Node.js para crear código de aplicación de servicio de dispositivo y back-end para métodos directos de dispositivo.

Creación de una aplicación de dispositivo

En esta sección se describe cómo usar el código de aplicación de dispositivo para crear una devolución de llamada de método directo.

Instalación de paquetes de SDK

El paquete azure-iot-device contiene objetos que interactúan con dispositivos IoT. Ejecute este comando para instalar el SDK de dispositivo de azure-iot-device en la máquina de desarrollo:

npm install azure-iot-device --save

Selección de un protocolo de transporte

EClientl objeto admite estos protocolos:

  • Amqp
  • Http: al usar Http, la instancia de Client comprueba si hay mensajes de IoT Hub con poca frecuencia (cada 25 minutos como mínimo).
  • Mqtt
  • MqttWs
  • AmqpWs

Instale los protocolos de transporte necesarios en la máquina de desarrollo.

Por ejemplo, este comando instala el protocolo Amqp:

npm install azure-iot-device-amqp --save

Para más información sobre las diferencias entre la compatibilidad con MQTT, AMQP y HTTPS, consulte Guía de comunicación de nube a dispositivo y Elección de un protocolo de comunicación.

Creación de un objeto de cliente

Cree un objeto Client mediante el paquete instalado.

Por ejemplo:

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

Creación de un objeto de protocolo

Cree un objeto Protocol mediante un paquete de transporte instalado.

En este ejemplo se asigna el protocolo AMQP:

const Protocol = require('azure-iot-device-amqp').Amqp;

Adición de la cadena de conexión del dispositivo y el protocolo de transporte

Llame a fromConnectionString para proporcionar parámetros de conexión de dispositivo:

  • connStr: la cadena de conexión del dispositivo.
  • transportCtor: el protocolo de transporte.

En este ejemplo se usa el protocolo de transporte Amqp:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Apertura de la conexión a IoT Hub

Use el método open para abrir una conexión entre un dispositivo IoT e IoT Hub.

Por ejemplo:

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

Creación de una devolución de llamada de método directo

Llame a onDeviceMethod para crear una función de controlador de devolución de llamada o corrutina a la que se llama cuando se recibe un método directo. El agente de escucha está asociado a una palabra clave de nombre de método, como "reboot". El nombre del método se puede usar en una aplicación de IoT Hub o back-end para desencadenar el método de devolución de llamada en el dispositivo.

La función del controlador de devolución de llamada debe llamar a response.send para enviar un mensaje de confirmación de respuesta a la aplicación que realiza la llamada.

Este ejemplo configura un controlador de método directo llamado onReboot al que se llama cuando se usa el nombre de método directo "reboot".

client.onDeviceMethod('reboot', onReboot);

En este ejemplo, el método de devolución de llamada onReboot implementa el método directo en el dispositivo. El código se ejecuta cuando se llama al método directo "reboot" desde una aplicación de servicio. La función llama a response.send para enviar un mensaje de confirmación de respuesta a la aplicación que realiza la llamada.

var onReboot = function(request, response) {

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

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

Ejemplos de dispositivos del SDK

El SDK de Azure IoT para Node.js proporciona ejemplos de funcionamiento de aplicaciones de dispositivo que administran tareas de administración de dispositivos. Para más información, vea:

Creación de una aplicación back-end

En esta sección se describe cómo invocar un método directo en un dispositivo.

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

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

Importante

En este artículo se incluyen los pasos para conectarse a un servicio mediante una firma de acceso compartido. Este método de autenticación es cómodo para las pruebas y la evaluación, pero la autenticación en un servicio con el Microsoft Entra ID o las identidades administradas es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de seguridad> Seguridad en la nube.

Conexión mediante una directiva de acceso compartido

Use fromConnectionString para conectarse a IoT Hub.

Para invocar un método directo en un dispositivo a través de IoT Hub, el servicio necesita el permiso Conexión del servicio. De forma predeterminada, todas las instancias de IoT Hub se crean con una directiva de acceso compartido denominada servicio que concede este permiso.

Como parámetro de CreateFromConnectionString, proporcione la cadena de conexión de la directiva de acceso compartido de servicio. Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

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

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

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.

Invocación a un método en un dispositivo

Use invokeDeviceMethod para invocar un método directo por nombre en un dispositivo. El parámetro de nombre del método identifica el método directo.

En este ejemplo se llama al método "reboot" para iniciar un reinicio en el dispositivo. El método "reboot" se asigna a una función de controlador de devolución de llamada en el dispositivo, tal como se describe en la sección Creación de una devolución de llamada de método directo de este artículo.

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

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

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

Muestras de servicio SDK

El SDK de Azure IoT para Node.js proporciona ejemplos de funcionamiento de aplicaciones de servicio que administran tareas de administración de dispositivos. Para más información, vea: