Carga de archivos desde un dispositivo a la nube con Azure IoT Hub

Artículo
12/20/2024

En este artículo se explica cómo:

Use las funcionalidades de carga de archivos de IoT Hub para cargar un archivo en Azure Blob Storage mediante un dispositivo Azure IoT y SDK de servicio.
Notifique a IoT Hub que el archivo se cargó correctamente y cree un servicio back-end para recibir notificaciones de carga de archivos de IoT Hub mediante los SDK del servicio Azure IoT.

En algunos escenarios, no se pueden asignar fácilmente los datos que los dispositivos envían en los mensajes del dispositivo a la nube de un tamaño relativamente reducido que acepta IoT Hub. Las funcionalidades de carga de archivos en IoT Hub permiten mover datos grandes o complejos a la nube. Por ejemplo:

Vídeos
Archivos grandes con imágenes
Datos de vibración muestreados con alta frecuencia
Cierto tipo de datos procesados previamente

Dichos archivos se suelen procesar por lotes en la nube mediante herramientas como Azure Data Factory o la pila Hadoop. Cuando necesite cargar archivos desde un dispositivo, todavía puede usar la seguridad y confiabilidad de IoT Hub. Este artículo le muestra cómo.

El objetivo de este artículo es servir de complemento a los ejemplos de SDK ejecutables a los que se hace referencia desde este artículo.

Para más información, vea:

Importante

La funcionalidad de carga de archivos de los dispositivos que usan la autenticación de la entidad de certificación X.509 está disponible como versión preliminar pública, y se debe habilitar el modo de vista previa. Está disponible con carácter general en dispositivos que usan la autenticación de huella digital X.509 o la atestación de certificado X.509 con el servicio de aprovisionamiento de dispositivos de Azure. Para obtener más información acerca de la autenticación X.509 con IoT Hub, consulte Certificados X.509 compatibles.

Requisitos previos

Una instancia de IoT Hub. Algunas llamadas al SDK requieren la cadena de conexión principal de IoT Hub, así que anótela.
Un dispositivo registrado. Algunas llamadas al SDK requieren la cadena de conexión principal del dispositivo, así que anótela.
Permiso Conexión del servicio de IoT Hub: para recibir mensajes de notificación de carga de archivos, el servicio back-end 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. Para obtener más información, consulte Conexión a un centro de IoT.
Configure la carga de archivos en el centro de IoT mediante la vinculación de una cuenta de Azure Storage y un contenedor de Azure Blob Storage. Puede configurarlos mediante Azure Portal, la CLI de Azure o Azure PowerShell.

Información general

Este procedimiento contiene dos secciones:

Carga de un archivo desde una aplicación de dispositivo
Recepción de una notificación de carga de archivos en una aplicación back-end

Carga de un archivo desde una aplicación de dispositivo

En esta sección se describe cómo cargar un archivo desde un dispositivo a un centro de IoT mediante la clase DeviceClient en el SDK de Azure IoT para .NET.

Siga este procedimiento para cargar un archivo desde un dispositivo al centro de IoT:

Conexión al centro de IoT
Obtención de un URI de SAS desde el centro de IoT
Carga del archivo en Azure Storage
Notificación al centro de IoT del estado de carga de archivos

Conexión de un dispositivo a IoT Hub

Una aplicación de dispositivo se puede autenticar con IoT Hub mediante los métodos siguientes:

Certificado X.509
Clave de acceso compartido

Autenticación mediante un certificado X.509

Para conectar un dispositivo a IoT Hub mediante un certificado X.509:

Use DeviceAuthenticationWithX509Certificate para crear un objeto que contenga la información del dispositivo y del certificado. DeviceAuthenticationWithX509Certificate se pasa como segundo parámetro a DeviceClient.Create (paso 2).
Use DeviceClient.Create para conectar el dispositivo a IoT Hub mediante un certificado X.509.

En este ejemplo, la información del dispositivo y del certificado se rellena en el objeto auth DeviceAuthenticationWithX509Certificate que se pasa a DeviceClient.Create.

En este ejemplo, se muestran los valores de parámetros de entrada de certificado como variables locales para mayor claridad. En un sistema de producción, almacene parámetros de entrada confidenciales en variables de entorno u otra ubicación de almacenamiento más segura. Por ejemplo, use Environment.GetEnvironmentVariable("HOSTNAME") para leer la variable de entorno de nombre de host.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

Para obtener más información acerca de la autenticación de certificado, vea:

Ejemplos de código

Para obtener ejemplos funcionales de autenticación de certificados X.509 de dispositivo, consulte:

Autenticación mediante una clave de acceso compartido

Llame a CreateFromConnectionString para conectarse al dispositivo. Pase la cadena de conexión principal del dispositivo.

AMQP es el protocolo de transporte predeterminado.

static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);

Obtención de un URI de SAS desde el centro de IoT

Llame a GetFileUploadSasUriAsync para obtener detalles de carga de archivos. El URI de SAS se usa en el siguiente paso para cargar un archivo de un dispositivo en Blob Storage.

const string filePath = "TestPayload.txt";
using var fileStreamSource = new FileStream(filePath, FileMode.Open);
var fileName = Path.GetFileName(fileStreamSource.Name);
var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest, System.Threading.CancellationToken cancellationToken = default);
Uri uploadUri = sasUri.GetBlobUri();

Carga de un archivo en Azure Storage

Para cargar un archivo en Azure Storage:

Cree un objeto blockBlobClient y pase un URI de carga de archivos.
Use el método UploadAsync para cargar un archivo en Blob Storage y pasar el URI de SAS. Si lo desea, puede agregar opciones de carga de blobs y parámetros de token de cancelación.

El cliente de blobs de Azure siempre usa HTTPS como protocolo para cargar el archivo en Azure Storage.

En este ejemplo, se pasa a BlockBlobClient el URI de SAS para crear un cliente de blobs en bloques de Azure Storage y carga el archivo:

var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, null, null);

Notificación al centro de IoT del estado de carga de archivos

Use CompleteFileUploadAsync para notificar al centro de IoT que el cliente del dispositivo completó la carga, pasando un objeto FileUploadCompletionNotification. La marca IsSuccess indica si la carga se realizó correctamente o no. Después de recibir una notificación, el centro de IoT liberará los recursos asociados a la carga (el URI de SAS).

Si se habilitan las notificaciones de carga de archivos, el centro de IoT envía un mensaje de notificación de carga de archivos a los servicios back-end configurados para la notificación de carga de archivos.

var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
{
    // Mandatory. Must be the same value as the correlation id returned in the sas uri response
    CorrelationId = sasUri.CorrelationId,

    // Mandatory. Will be present when service client receives this file upload notification
    IsSuccess = true,

    // Optional, user defined status code. Will be present when service client receives this file upload notification
    StatusCode = 200,

    // Optional, user-defined status description. Will be present when service client receives this file upload notification
    StatusDescription = "Success"
};

await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

Ejemplo de carga de archivos del SDK

El SDK incluye este ejemplo de carga de archivos.

Recepción de una notificación de carga de archivos en una aplicación back-end

Puede crear un servicio back-end para recibir mensajes de notificación de carga de archivos desde el centro de IoT.

La clase ServiceClient contiene métodos que los servicios pueden usar para recibir notificaciones de carga de archivos.

Agregar paquete NuGet de servicio

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

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 back-end a un dispositivo mediante CreateFromConnectionString. La aplicación necesita permiso de conexión del servicio. Proporcione esta cadena de conexión de directiva de acceso compartido como parámetro para fromConnectionString. 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:

using Microsoft.Azure.Devices;
static ServiceClient serviceClient;
static string connectionString = "{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.

Recepción de notificación de carga de archivos

Para recibir una notificación de carga de archivos:

Cree un CancellationToken.
Llame a GetFileNotificationReceiver para crear un receptor de notificaciones.
Use un bucle con ReceiveAsync para esperar a la notificación de carga de archivos.

Por ejemplo:

// Define the cancellation token
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;

// Create a notification receiver
var notificationReceiver = serviceClient.GetFileNotificationReceiver();
Console.WriteLine("\nReceiving file upload notification from service");

// Check for file upload notifications
while (true)
{
    var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);
    if (fileUploadNotification == null) continue;
    Console.ForegroundColor = ConsoleColor.Yellow;
    Console.WriteLine("Received file upload notification: {0}", 
        string.Join(", ", fileUploadNotification.BlobName));
    Console.ResetColor();
    await notificationReceiver.CompleteAsync(fileUploadNotification);
}

Ejemplo del receptor de carga de archivos del SDK

El SDK incluye este ejemplo de receptor de carga de archivos.

Información general

Este procedimiento contiene dos secciones:

Carga de un archivo desde una aplicación de dispositivo
Recepción de una notificación de carga de archivos en una aplicación back-end

Carga de un archivo desde una aplicación de dispositivo

En esta sección se describe cómo cargar un archivo desde un dispositivo a un centro de IoT mediante la clase DeviceClient desde el SDK de Azure IoT para Java.

Siga este procedimiento para cargar un archivo desde un dispositivo al centro de IoT:

Conexión del dispositivo a IoT Hub
Obtención de un URI de SAS desde el centro de IoT
Carga del archivo en Azure Storage
Envío de una notificación de estado de carga de archivos al centro de IoT

Conexión de un dispositivo a IoT Hub

Una aplicación de dispositivo se puede autenticar con IoT Hub mediante los métodos siguientes:

Certificado X.509
Clave de acceso compartido

Autenticación mediante un certificado X.509

Para conectar un dispositivo a IoT Hub mediante un certificado X.509:

Compile el objeto SSLContext mediante buildSSLContext.
Agregue la información de SSLContext a un objeto ClientOptions.
Llame a DeviceClient con la información de ClientOptions para crear la conexión del dispositivo a IoT Hub.

En este ejemplo, se muestran los valores de parámetros de entrada de certificado como variables locales para mayor claridad. En un sistema de producción, almacene parámetros de entrada confidenciales en variables de entorno u otra ubicación de almacenamiento más segura. Por ejemplo, use Environment.GetEnvironmentVariable("PUBLICKEY") para leer una variable de entorno de cadena de certificado de clave pública.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

Para obtener más información acerca de la autenticación de certificado, vea:

Ejemplos de código

Para obtener ejemplos funcionales de autenticación de certificados X.509 de dispositivo, consulte:

Autenticación mediante una clave de acceso compartido

Las operaciones de carga de archivos siempre usan HTTPS, pero DeviceClient puede definir el IotHubClientProtocol para otros servicios como telemetría, método de dispositivo y dispositivo gemelo.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

Cree una instancia del DeviceClient para conectarse al dispositivo mediante la cadena de conexión principal del dispositivo.

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

Obtención de un URI de SAS desde el centro de IoT

Llame a getFileUploadSasUri para obtener un objeto FileUploadSasUriResponse.

FileUploadSasUriResponse incluye estos métodos y valores devueltos. Los valores devueltos se pueden pasar a los métodos de carga de archivos.

Método	Valor devuelto
`getCorrelationId()`	Identificador de correlación
`getContainerName()`	Nombre del contenedor
`getBlobName()`	Blob name (Nombre de blob)
`getBlobUri()`	Identificador URI de blob

Por ejemplo:

FileUploadSasUriResponse sasUriResponse = client.getFileUploadSasUri(new FileUploadSasUriRequest(file.getName()));

System.out.println("Successfully got SAS URI from IoT hub");
System.out.println("Correlation Id: " + sasUriResponse.getCorrelationId());
System.out.println("Container name: " + sasUriResponse.getContainerName());
System.out.println("Blob name: " + sasUriResponse.getBlobName());
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());

Carga del archivo en Azure Storage

Pase el punto de conexión de URI de blob a BlobClientBuilder.buildclient para crear el objeto BlobClient.

BlobClient blobClient =
    new BlobClientBuilder()
        .endpoint(sasUriResponse.getBlobUri().toString())
        .buildClient();

Llame a uploadFromFile para cargar el archivo en Blob Storage.

String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);

Envío de una notificación de estado de carga de archivos al centro de IoT

Envíe una notificación de estado de carga al centro de IoT después de un intento de carga de archivos.

Cree un objeto FileUploadCompletionNotification. Pase el estado correcto de carga de archivos correlationId y isSuccess. Pase un valor true de isSuccess cuando la carga de archivos se haya realizado correctamente, false cuando no.

FileUploadCompletionNotification debe llamarse incluso cuando se produce un error en la carga de archivos. El centro de IoT tiene un número fijo de URI de SAS que se puede activar en un momento dado. Una vez que haya terminado con la carga de archivos, debe liberar el URI de SAS para que se pueda generar otro URI de SAS. Si un URI de SAS no se libera a través de esta API, se libera finalmente en función de cuánto tiempo se configuran los URI de SAS para vivir en un centro de IoT.

En este ejemplo se pasa un estado correcto.

FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);

Cierre el cliente

Libere los recursos de client.

client.closeNow();

Creación de una aplicación back-end

En esta sección, se describe cómo recibir una notificación de carga de archivos en una aplicación back-end.

La clase ServiceClient contiene métodos que los servicios pueden usar para recibir notificaciones de carga de archivos.

Adición de instrucciones import

Agregue estas instrucciones import para usar el SDK de Java en Azure IoT y el controlador de excepciones.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

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

Importante

Conexión mediante una directiva de acceso compartido

Definición del protocolo de conexión

Use IotHubServiceClientProtocol para definir el protocolo de la capa de aplicación usado por el cliente de servicio para comunicarse con una instancia de IoT Hub.

IotHubServiceClientProtocol solo acepta la enumeración AMQPS o AMQPS_WS.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Creación del objeto ServiceClient

Cree el objeto ServiceClient y proporcione la cadena de conexión y el protocolo de Iot Hub.

Para cargar un archivo en un dispositivo en IoT Hub, el servicio necesita el permiso de 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 ServiceClient, 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.

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
private static final ServiceClient serviceClient (iotHubConnectionString, protocol);

Apertura de la conexión entre la aplicación e IoT Hub

Abrir la conexión del remitente de AMQP. Este método crea la conexión entre la aplicación y IoT Hub.

serviceClient.open();

Conexión mediante Microsoft Entra

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

Secreto del cliente
Certificado
Credencial de identidad federada

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.

Comprobación del estado de carga de archivos

Para comprobar el estado de carga de archivos:

Cree un objeto getFileUploadNotificationReceiver.
Use abrir para conectarse al centro de IoT.
Llame a receive para comprobar el estado de carga de archivos. Este método devuelve un objeto fileUploadNotification. Si se recibe un aviso de carga, puede ver los campos de estado de carga mediante métodos fileUploadNotification.

Por ejemplo:

FileUploadNotificationReceiver receiver = serviceClient.getFileUploadNotificationReceiver();
receiver.open();
FileUploadNotification fileUploadNotification = receiver.receive(2000);

if (fileUploadNotification != null)
{
    System.out.println("File Upload notification received");
    System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
    System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
    System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
    System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
    System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
    System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
}
else
{
    System.out.println("No file upload notification");
}

// Close the receiver object
receiver.close();

Ejemplos de carga de archivos del SDK

Hay dos ejemplos de carga de archivos Java.

Instalar paquetes

La biblioteca azure-iot-device debe instalarse antes de llamar a cualquier código relacionado.

pip install azure-iot-device

El paquete azure.storage.blob se usa para realizar la carga de archivos.

pip install azure.storage.blob

Carga de un archivo desde una aplicación de dispositivo

En esta sección se describe cómo cargar un archivo desde un dispositivo a un centro de IoT mediante la clase IoTHubDeviceClient desde el SDK de Azure IoT para Python.

Importación de bibliotecas

import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient

Conexión de un dispositivo a IoT Hub

Una aplicación de dispositivo se puede autenticar con IoT Hub mediante los métodos siguientes:

Certificado X.509
Clave de acceso compartido

Autenticación mediante un certificado X.509

Para conectar un dispositivo a IoT Hub mediante un certificado X.509:

Use create_from_x509_certificate para agregar los parámetros de certificado X.509
Llame a connect para conectar el cliente del dispositivo

En este ejemplo, se muestran los valores de parámetros de entrada de certificado como variables locales para mayor claridad. En un sistema de producción, almacene parámetros de entrada confidenciales en variables de entorno u otra ubicación de almacenamiento más segura. Por ejemplo, use os.getenv("HOSTNAME") para leer la variable de entorno de nombre de host.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

Para obtener más información acerca de la autenticación de certificado, vea:

Ejemplos de código

Para obtener ejemplos funcionales de autenticación de certificados X.509 de dispositivo, consulte los ejemplos cuyos nombres de archivo terminan en x509 en escenarios del centro de Async.

Autenticación mediante una clave de acceso compartido

Para conectar un dispositivo a IoT Hub:

Llame a create_from_connection_string para agregar la cadena de conexión principal del dispositivo.
Llame a connect para conectar el cliente del dispositivo.

Por ejemplo:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Obtención de información de Blob Storage

Llame a get_storage_info_for_blob para obtener información de un centro de IoT sobre una cuenta de Azure Storage vinculada. Esta información incluye el nombre de host, el nombre del contenedor, el nombre del blob y un token de SAS. El método get_storage_info_for_blob también devuelve un correlation_id, que se usa en el método notify_blob_upload_status. El correlation_id es la forma que tiene IoT Hub de marcar en qué Blob está trabajando.

# Get the storage info for the blob
PATH_TO_FILE = "{Full path to local file}"
blob_name = os.path.basename(PATH_TO_FILE)
blob_info = device_client.get_storage_info_for_blob(blob_name)

Carga de un archivo en Blob Storage

Para cargar un archivo en Blob Storage:

Use from_blob_url para crear un objeto BlobClient a partir de una dirección URL de blob.
Llame a upload_blob para cargar el archivo en Blob Storage.

En este ejemplo se analiza la estructura de blob_info para crear una dirección URL que usa para inicializar un BlobClient. A continuación, llama a upload_blob para cargar el archivo en Blob Storage.

try:
    sas_url = "https://{}/{}/{}{}".format(
        blob_info["hostName"],
        blob_info["containerName"],
        blob_info["blobName"],
        blob_info["sasToken"]
    )

    print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))

    # Upload the specified file
    with BlobClient.from_blob_url(sas_url) as blob_client:
        with open(file_name, "rb") as f:
            result = blob_client.upload_blob(f, overwrite=True)
            return (True, result)

except FileNotFoundError as ex:
    # catch file not found and add an HTTP status code to return in notification to IoT hub
    ex.status_code = 404
    return (False, ex)

except AzureError as ex:
    # catch Azure errors that might result from the upload operation
    return (False, ex)

Notificación al centro de IoT del estado de carga

Use notify_blob_upload_status para notificar al centro de IoT el estado de la operación de Blob Storage. Pase el correlation_id obtenido por el método get_storage_info_for_blob. El centro de IoT usa el correlation_id para notificar a cualquier servicio que pueda estar escuchando una notificación con respecto al estado de la tarea de carga de archivos.

En este ejemplo se notifica al centro de IoT una carga de archivos correcta:

device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)

Apagado del cliente del dispositivo

Apague el cliente. Una vez que se llama a este método, cualquier intento de llamadas de cliente adicionales da como resultado un ClientError que se genera.

device_client.shutdown()

Ejemplos de carga de archivos del SDK

El SDK incluye dos ejemplos de carga de archivos:

Información general

En este artículo, se describe cómo usar el SDK de Azure IoT para Node.js con el fin de crear una aplicación de dispositivo para cargar un archivo y una aplicación de servicio back-end para recibir una notificación de carga de archivos.

Creación de una aplicación de dispositivo

En esta sección se describe cómo cargar un archivo desde un dispositivo a un centro de IoT mediante la clase azure-iot-device en el SDK de Azure IoT para Node.js.

Instalación de paquetes de SDK

Ejecute este comando para instalar el SDK de dispositivo azure-iot-device, el azure-iot-device-mqtt y los paquetes @azure/storage-blob en el equipo de desarrollo:

npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save

El paquete azure-iot-device contiene objetos que interactúan con dispositivos IoT.

Siga este procedimiento para cargar un archivo desde un dispositivo al centro de IoT:

Conexión del dispositivo a IoT Hub
Obtención de un token de firma de acceso compartido (SAS) de Blob desde IoT Hub
Carga del archivo en Azure Storage
Envío de una notificación de estado de carga de archivos al centro de IoT

Creación de módulos

Cree módulos de cliente, protocolo, errores y ruta de acceso mediante los paquetes instalados.

const Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

Conexión de un dispositivo a IoT Hub

Una aplicación de dispositivo se puede autenticar con IoT Hub mediante los métodos siguientes:

Certificado X.509
Clave de acceso compartido

Autenticación mediante un certificado X.509

El certificado X.509 está asociado al transporte de conexión del dispositivo a IoT Hub.

Para configurar la conexión de un dispositivo a IoT Hub mediante un certificado X.509:

Llame a fromConnectionString para agregar la cadena de conexión del dispositivo y el tipo de transporte. Agregue x509=true a la cadena de conexión del dispositivo para indicar que se agrega un certificado a DeviceClientOptions. Por ejemplo: HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true.
Configure una variable JSON con detalles del certificado y pásela a DeviceClientOptions.
Llame a setOptions para agregar un certificado y una clave X.509 (y, opcionalmente, una frase de contraseña) al transporte del cliente.
Llame a open para abrir la conexión desde el dispositivo a IoT Hub.

En este ejemplo, se muestra información de configuración del certificado dentro de una variable JSON. Las options de configuración de certificación se pasan a setOptions y la conexión se abre mediante open.

var options = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }
 client.setOptions(options, callback);
 client.open(connectCallback);

Para obtener más información acerca de la autenticación de certificado, vea:

Código de ejemplo

Para obtener un ejemplo funcional de autenticación de certificados X.509 de dispositivo, consulte Ejemplo de X.509 de dispositivo simple.

Autenticación mediante una clave de acceso compartido

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

Obtención de un token de SAS desde el centro de IoT

Use getBlobSharedAccessSignature para obtener el token de SAS de la cuenta de almacenamiento vinculada desde el centro de IoT.

Por ejemplo:

// make sure you set these environment variables prior to running the sample.
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);
const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
if (!blobInfo) {
throw new errors.ArgumentError('Invalid upload parameters');
}

Carga del archivo en el centro de IoT

Para cargar un archivo desde un dispositivo al centro de IoT:

Cree una canalización de flujo
Construya la dirección URL del blob
Cree un BlockBlobClient para la carga de archivos en Blob Storage
Llame a uploadFile para cargar el archivo en Blob Storage
Llame a notifyBlobUploadStatus para notificar al centro de IoT que la carga se realizó correctamente o produjo un error

Por ejemplo:

// Open the pipeline
const pipeline = newPipeline(new AnonymousCredential(), {
retryOptions: { maxTries: 4 },
telemetry: { value: 'HighLevelSample V1.0.0' }, // Customized telemetry string
keepAliveOptions: { enable: false }
});

// Construct the blob URL
const { hostName, containerName, blobName, sasToken } = blobInfo;
const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

// Create the BlockBlobClient for file upload to Blob Storage
const blobClient = new BlockBlobClient(blobUrl, pipeline);

// Setup blank status notification arguments to be filled in on success/failure
let isSuccess;
let statusCode;
let statusDescription;

const uploadStatus = await blobClient.uploadFile(localFilePath);
console.log('uploadStreamToBlockBlob success');

  try {
    const uploadStatus = await blobClient.uploadFile(localFilePath);
    console.log('uploadStreamToBlockBlob success');

    // Save successful status notification arguments
    isSuccess = true;
    statusCode = uploadStatus._response.status;
    statusDescription = uploadStatus._response.bodyAsText;

    // Notify IoT hub of upload to blob status (success)
    console.log('notifyBlobUploadStatus success');
  }
  catch (err) {
    isSuccess = false;
    statusCode = err.code;
    statusDescription = err.message;

    console.log('notifyBlobUploadStatus failed');
    console.log(err);
  }

// Send file upload status notification to IoT hub
await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);

Carga del archivo local en Blob Storage

Puede cargar un archivo local en Blob Storage desde un equipo.

const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

Ejemplo de carga de archivos del SDK

El SDK incluye un ejemplo avanzado de carga a blob.

Creación de una aplicación back-end

En esta sección, se describe cómo recibir una notificación de carga de archivos en una aplicación back-end.

La clase ServiceClient contiene métodos que los servicios pueden usar para recibir notificaciones de carga de archivos.

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

Conexión mediante una directiva de acceso compartido

Use fromConnectionString para conectarse a IoT Hub.

Para cargar un archivo desde un dispositivo, el servicio necesita el permiso de 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

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

Secreto del cliente
Certificado
Credencial de identidad federada

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

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.

Creación de un receptor de devolución de llamada de notificación de carga de archivos

Para crear un receptor de devolución de llamada de notificación de carga de archivos:

Llame a getFileNotificationReceiver. Proporcione el nombre de un método de devolución de llamada de carga de archivos al que se llama cuando se reciben mensajes de notificación.
Procese las notificaciones de carga de archivos en el método de devolución de llamada.

En este ejemplo se configura un receptor de devolución de llamada de notificación receiveFileUploadNotification. El receptor interpreta la información de estado de carga del archivo e imprime un mensaje de estado en la consola.

//Set up the receiveFileUploadNotification notification message callback receiver
serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
if (err) {
  console.error('error getting the file notification receiver: ' + err.toString());
} else {
  receiver.on('message', function (msg) {
    console.log('File upload from device:')
    console.log(msg.getData().toString('utf-8'));
    receiver.complete(msg, function (err) {
      if (err) {
        console.error('Could not finish the upload: ' + err.message);
      } else {
        console.log('Upload complete');
      }
    });
  });
}

Ejemplo de notificación de carga de archivos del SDK

El SDK incluye un ejemplo de carga de archivos.

Compartir a través de

Carga de archivos desde un dispositivo a la nube con Azure IoT Hub

Requisitos previos

Información general

Carga de un archivo desde una aplicación de dispositivo

Conexión de un dispositivo a IoT Hub

Autenticación mediante un certificado X.509

Ejemplos de código

Autenticación mediante una clave de acceso compartido

Obtención de un URI de SAS desde el centro de IoT

Carga de un archivo en Azure Storage

Notificación al centro de IoT del estado de carga de archivos

Ejemplo de carga de archivos del SDK

Recepción de una notificación de carga de archivos en una aplicación back-end

Agregar paquete NuGet de servicio

Conexión al centro de IoT

Conexión mediante una directiva de acceso compartido

Conexión mediante Microsoft Entra

Configuración de la aplicación de Microsoft Entra

Autenticación con DefaultAzureCredential

Código de ejemplo

Recepción de notificación de carga de archivos

Ejemplo del receptor de carga de archivos del SDK

Información general

Carga de un archivo desde una aplicación de dispositivo

Conexión de un dispositivo a IoT Hub

Autenticación mediante un certificado X.509

Ejemplos de código

Autenticación mediante una clave de acceso compartido

Obtención de un URI de SAS desde el centro de IoT

Carga del archivo en Azure Storage

Envío de una notificación de estado de carga de archivos al centro de IoT

Cierre el cliente

Creación de una aplicación back-end

Adición de instrucciones import

Conexión a IoT Hub

Conexión mediante una directiva de acceso compartido

Definición del protocolo de conexión

Creación del objeto ServiceClient

Apertura de la conexión entre la aplicación e IoT Hub

Conexión mediante Microsoft Entra

Configuración de la aplicación de Microsoft Entra

Autenticación con DefaultAzureCredential

Autenticación mediante ClientSecretCredentialBuilder

Otras clases de autenticación

Ejemplos de código

Comprobación del estado de carga de archivos

Ejemplos de carga de archivos del SDK

Instalar paquetes

Carga de un archivo desde una aplicación de dispositivo

Importación de bibliotecas

Conexión de un dispositivo a IoT Hub

Autenticación mediante un certificado X.509

Ejemplos de código

Autenticación mediante una clave de acceso compartido

Obtención de información de Blob Storage

Carga de un archivo en Blob Storage

Notificación al centro de IoT del estado de carga

Apagado del cliente del dispositivo

Ejemplos de carga de archivos del SDK

Información general

Creación de una aplicación de dispositivo

Instalación de paquetes de SDK

Creación de módulos

Conexión de un dispositivo a IoT Hub

Autenticación mediante un certificado X.509

Código de ejemplo

Autenticación mediante una clave de acceso compartido

Selección de un protocolo de transporte

Creación de un objeto de cliente

Creación de un objeto de protocolo

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

Apertura de la conexión a IoT Hub

Obtención de un token de SAS desde el centro de IoT

Carga del archivo en el centro de IoT

Carga del archivo local en Blob Storage

Ejemplo de carga de archivos del SDK

Creación de una aplicación back-end

Instalación del paquete de SDK de servicio

Conexión al centro de IoT