Carga de archivos desde un dispositivo a la nube con Azure IoT Hub (.NET)

  • Artículo

En este artículo se muestra cómo archivar las funcionalidades de carga de IoT Hub cargar un archivo en Azure Blob Storage, mediante un SDK de servicio y dispositivo .NET de Azure IoT.

En el inicio rápido Envío de telemetría de un dispositivo a IoT Hub y el tutorial de Envío de mensajes de la nube al dispositivo con IoT Hub se muestra cómo usar la funcionalidad básica de mensajería del dispositivo a la nube y de la nube al dispositivo de IoT Hub. En el artículo Configuración del enrutamiento de mensajes con IoT Hub se muestra una forma de almacenar de manera fiable los mensajes del dispositivo a la nube en Microsoft Azure Blob Storage. Sin embargo, 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. 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.

Al final de este artículo, ejecutará dos aplicaciones de consola de .NET:

  • FileUploadSample. Esta aplicación de dispositivo carga un archivo en el almacenamiento mediante un identificador URI de SAS proporcionado por el centro de IoT. Este ejemplo es del repositorio del SDK de C# para Azure IoT que descarga en los requisitos previos.

  • ReadFileUploadNotification. Esta aplicación de servicio recibe notificaciones de carga de archivos de IoT Hub. Usted crea esta aplicación.

Nota

IoT Hub admite muchas plataformas de dispositivos y lenguajes (entre los que se incluyen C, Java, Python y JavaScript), mediante los SDK de dispositivo IoT de Azure. Consulte el Centro de desarrollo de Azure IoT para saber cómo conectar su dispositivo a Azure IoT Hub.

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. Cree uno con la CLI o el Azure Portal.

  • Dispositivo registrado. Registre uno en el Azure Portal.

  • Las aplicaciones de ejemplo que se ejecutan en este artículo se escriben con C# con .NET Core.

    Descargue el SDK de .NET Core para varias plataformas desde .NET.

    Verifique la versión actual de SDK de .NET Core en el equipo de desarrollo con el comando siguiente:

    dotnet --version

  • Descargue el SDK de C# para Azure IoT desde Descargar ejemplo y extraiga el archivo ZIP.

  • El puerto 8883 debería estar abierto en su firewall. En el ejemplo de este artículo se usa el protocolo MQTT, que se comunica mediante el 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).

Asociación de una cuenta de Azure Storage a IoT Hub

Para cargar archivos desde un dispositivo, debe tener una cuenta de Azure Storage y un contenedor de Azure Blob Storage asociado al centro de IoT. Una vez que asocie la cuenta de almacenamiento y el contenedor con el centro de IoT, este puede proporcionar los elementos de un URI de SAS cuando lo solicite un dispositivo. A continuación, el dispositivo puede usar estos elementos para construir el URI de SAS que usa para autenticarse con Azure Storage y cargar archivos en el contenedor de blobs.

Para asociar una cuenta de Azure Storage con el centro de IoT:

  1. En Configuración del centro, seleccione Carga de archivos en el panel izquierdo del centro de IoT.

    Captura de pantalla que muestra la configuración de carga de archivos seleccionada en el portal.

  2. En el panel Carga de archivos, seleccione Contenedor de Azure Storage. En este artículo, se recomienda que la cuenta de almacenamiento e IoT Hub se encuentren en la misma región.

    • Si ya tiene una cuenta de almacenamiento que desea usar, selecciónela de la lista.

    • Para crear una nueva cuenta de almacenamiento, seleccione + Cuenta de almacenamiento. Proporcione un nombre a la cuenta de almacenamiento y asegúrese de que Ubicación esté establecida en la misma región que el centro de IoT y, a continuación, seleccione Aceptar. La nueva cuenta se crea en el mismo grupo de recursos que el centro de IoT. Cuando se complete la implementación, seleccione la cuenta de almacenamiento de la lista.

    Después de seleccionar la cuenta de almacenamiento, se abre el panel Contenedores.

  3. En el panel Contenedores, seleccione el contenedor de blobs.

    • Si ya tiene un contenedor de blobs que desea usar, selecciónelo en la lista y haga clic en Seleccionar.

    • Para crear un contenedor de blobs, seleccione + Contenedor. Proporcione un nombre para el nuevo contenedor. Para los fines de este artículo, puede dejar todos los demás campos en su valor predeterminado. Seleccione Crear. Cuando finalice la implementación, seleccione el contenedor de la lista y haga clic en Seleccionar.

  4. De nuevo en el panel Carga de archivos, asegúrese de que las notificaciones de archivos estén establecidas en Activadas. Puede dejar el resto de la configuración en sus valores predeterminados. Seleccione Guardar y espere a que se complete la configuración antes de pasar a la siguiente sección.

    Captura de pantalla que muestra la configuración de confirmación de carga de archivos en el portal.

Para obtener instrucciones detalladas sobre cómo crear una cuenta de Azure Storage, consulte Crear una cuenta de almacenamiento. Para obtener instrucciones detalladas sobre cómo asociar una cuenta de almacenamiento y un contenedor de blobs a un centro de IoT, consulte Configuración de cargas de archivos mediante Azure Portal.

Carga de un archivo desde una aplicación de dispositivo

En este artículo, se usa un ejemplo del repositorio de SDK de C# para Azure IoT que descargó anteriormente como aplicación de dispositivo. Puede abrir los archivos siguientes mediante Visual Studio, Visual Studio Code o un editor de texto de su elección.

El ejemplo se encuentra en azure-iot-sdk-csharp/iothub/device/samples/getting started/FileUploadSample, en la carpeta donde extrajo el SDK de C# para Azure IoT.

Examine el código de FileUpLoadSample.cs. Este archivo contiene la lógica de ejemplo principal. Después de crear el cliente de dispositivo de IoT Hub, sigue el procedimiento estándar de tres partes para cargar archivos desde un dispositivo:

  1. El código llama al método GetFileUploadSasUriAsync en el cliente de dispositivo para obtener un URI de SAS del centro de IoT:

    var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

// Lines removed for clarity

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
Uri uploadUri = sasUri.GetBlobUri();

  2. El código usa el URI de SAS para cargar el archivo en Azure Storage. En este ejemplo, usa el URI de SAS para crear un cliente de blob en bloques de Azure Storage y carga el archivo:

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

  3. El código notifica al centro de IoT que ha completado la carga. Esto indica al centro de IoT que puede liberar recursos asociados a la carga (el URI de SAS). Si las notificaciones de carga de archivos están habilitadas, el centro de IoT envía un mensaje de notificación a los servicios backend.

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

Si examina el archivo parameter.cs, ve lo siguiente:

  • El ejemplo requiere que pase un parámetro, p, que toma una cadena de conexión de dispositivo.

  • De manera predeterminada, el ejemplo de dispositivo usa el protocolo MQTT para comunicarse con IoT Hub. Puede usar el parámetro t para cambiar este protocolo de transporte. Independientemente de esta selección, el cliente de blobs de Azure siempre usa HTTPS como protocolo para cargar el archivo a Azure Storage.

Obtención de la cadena de conexión de IoT Hub

En este artículo, crea un servicio de back-end para recibir mensajes de notificación de carga de archivos desde el centro de IoT. Para recibir mensajes de notificación de carga de archivos, el servicio necesita el permiso de conexión de 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 la cadena de conexión de IoT Hub para la directiva service, siga estos pasos:

  1. En Azure Portal, seleccione Grupos de recursos. Seleccione el grupo de recursos donde se encuentra el centro y, a continuación, seleccione el centro en la lista de recursos.

  2. En el panel de la izquierda de IoT Hub, seleccione Directivas de acceso compartido.

  3. En la lista de directivas, seleccione la directiva service.

  4. Copie la Cadena de conexión principal y guarde el valor.

Captura de pantalla que muestra cómo recuperar la cadena de conexión de su IoT Hub en el Azure Portal.

Para obtener más información sobre las directivas de acceso compartido y los permisos de IoT Hub, consulte Permisos y control del acceso.

Recepción de una notificación de carga de archivos

En esta sección, se crea una aplicación de consola de C# que recibe mensajes de notificación de carga de archivos del centro de IoT.

  1. Abra una ventana de comandos y vaya a la carpeta donde quiere crear el proyecto. Cree una carpeta denominada ReadFileUploadNotifications y cambie los directorios a esa carpeta.

    mkdir ReadFileUploadNotification
cd ReadFileUploadNotification

  2. Ejecute el siguiente comando para crear un proyecto de consola de C#. Después de ejecutar el comando, la carpeta contendrá un archivo Program.cs y un archivo ReadFileUploadNotification.csproj.

    dotnet new console --language c#

  3. Ejecute el siguiente comando para agregar el paquete Microsoft.Azure.Devices al archivo del proyecto. Este paquete es el SDK del servicio .NET de Azure IoT.

    dotnet add package Microsoft.Azure.Devices

  4. Abra el archivo Program.cs y agregue las siguientes instrucciones al principio del archivo:

    using Microsoft.Azure.Devices;

  5. Agregue los campos siguientes a la clase Program . Reemplace el valor de marcador de posición {iot hub connection string} por la cadena de conexión de IoT Hub que copió anteriormente en Obtener la cadena de conexión de IoT Hub.

    static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";

  6. Agregue el método siguiente a la clase Program :

    private async static void ReceiveFileUploadNotificationAsync()
{
    var notificationReceiver = serviceClient.GetFileNotificationReceiver();
    Console.WriteLine("\nReceiving file upload notification from service");
    while (true)
    {
        var fileUploadNotification = await notificationReceiver.ReceiveAsync();
        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);
    }
}

    Tenga en cuenta que este patrón de recepción es el mismo que se usa para recibir mensajes de nube a dispositivo desde la aplicación de dispositivo.

  7. Por último, reemplace las líneas en el método Main por las siguientes:

    Console.WriteLine("Receive file upload notifications\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
ReceiveFileUploadNotificationAsync();
Console.WriteLine("Press Enter to exit\n");
Console.ReadLine();

Ejecución de las aplicaciones

Ahora está listo para ejecutar las aplicaciones.

  1. En primer lugar, ejecute la aplicación de servicio para que reciba notificaciones de carga de archivos desde el centro de IoT. En el símbolo del sistema, en la carpeta ReadFileUploadNotification, ejecute los comandos siguientes:

    dotnet restore
dotnet run

    La aplicación se inicia y espera una notificación de carga de archivos desde el centro de IoT:

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

  2. A continuación, ejecute la aplicación de dispositivo para cargar el archivo en Azure Storage. Abra un nuevo símbolo del sistema y cambie las carpetas a azure-iot-sdk-csharp\iothub\device\samples\getting started\FileUploadSample, en la carpeta donde expandió el SDK de C# para Azure IoT. Ejecute los comandos siguientes: Reemplace el valor del marcador de posición {Your device connection string} del segundo comando por la cadena de conexión de dispositivo que vio cuando registró un dispositivo en IoT Hub.

    dotnet restore
dotnet run --p "{Your device connection string}"

    La siguiente salida corresponde a la aplicación de dispositivo una vez completada la carga:

      Uploading file TestPayload.txt
  Getting SAS URI from IoT Hub to use when uploading the file...
  Successfully got SAS URI (https://contosostorage.blob.core.windows.net/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub
  Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication
  Successfully uploaded the file to Azure Storage
  Notified IoT Hub that the file upload succeeded and that the SAS URI can be freed.
  Time to upload file: 00:00:01.5077954.
  Done.

  3. Observe que la aplicación de servicio muestra que ha recibido la notificación de carga de archivos:

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

Received file upload notification: myDeviceId/TestPayload.txt

Comprobación de la carga de archivos

Puede usar el portal para ver el archivo cargado en el contenedor de almacenamiento que configuró:

  1. Vaya a la cuenta de almacenamiento en Azure Portal.

  2. En el panel izquierdo de la cuenta de almacenamiento, seleccione Contenedores.

  3. Seleccione el contenedor donde cargó el archivo.

  4. Seleccione la carpeta que nombró tras el dispositivo.

  5. Seleccione el blob donde cargó el archivo. En este artículo, es el blob denominado TestPayload.txt.

    Captura de pantalla de la selección del archivo cargado en Azure Portal.

  6. Vea las propiedades del blob en la página que se abre. Puede seleccionar Descargar para descargar el archivo y ver su contenido localmente.

Pasos siguientes

En este artículo ha aprendido a usar la función de carga de archivos de IoT Hub para simplificar la carga de archivos desde los dispositivos. Puede seguir explorando esta característica con los siguientes artículos: