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

En este tutorial se muestra cómo usar la característica de carga de archivos de IoT Hub con los SDK de servicio y dispositivo de Azure IoT .NET.

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 tutorial Configuración del enrutamiento de mensajes con IoT Hub se describe una forma de almacenar de manera confiable los mensajes enviados del dispositivo a la nube en Microsoft Azure Blob Storage. Sin embargo, en algunos casos no se pueden asignar fácilmente los datos que los dispositivos envían en los mensajes de dispositivo a nube con un tamaño relativamente reducido que acepta IoT Hub. Por ejemplo:

  • Archivos grandes con imágenes

  • Vídeos

  • 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. Sin embargo, cuando necesite cargar archivos desde un dispositivo, todavía puede usar la seguridad y confiabilidad de IoT Hub. En este tutorial se muestra cómo realizar las siguientes acciones.

Al final de este tutorial, 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. Esta aplicación se ejecutará desde el repositorio de ejemplos de C# para Azure IoT que descargará en los requisitos previos.

  • ReadFileUploadNotification. Esta aplicación de servicio recibe notificaciones de carga de archivos de IoT Hub. Usted creará 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 para desarrolladores de IoT de Azure para obtener instrucciones paso a paso sobre cómo conectar el 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. Para obtener más información acerca de la autenticación X.509 con IoT Hub, consulte Certificados X.509 compatibles.

Requisitos previos

  • Una cuenta de Azure activa. En caso de no tener ninguna, puede crear una cuenta gratuita en tan solo unos minutos.

  • Las aplicaciones de ejemplo que se ejecutan en este artículo se escriben con C#. En los ejemplos de C# de Azure IoT, se recomienda tener la SDK de .NET Core 3.1 o superior en la máquina de desarrollo.

    Puede descargar el SDK de .NET Core para varias plataformas desde .NET.

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

    dotnet --version
    
  • Descargue los ejemplos de C# de Azure IoT de https://github.com/Azure-Samples/azure-iot-samples-csharp/archive/main.zip y extraiga el archivo ZIP.

  • Asegúrese de que el puerto 8883 está abierto en el 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).

Crear un centro de IoT

En esta sección se describe cómo crear un centro de IoT mediante Azure Portal.

  1. Inicie sesión en Azure Portal.

  2. En la página de inicio de Azure, seleccione + Crear un recurso y, después, escriba IoT Hub en el campo Buscar en Marketplace.

  3. Seleccione IoT Hub en los resultados de la búsqueda y, después, haga clic en Crear.

  4. En la pestaña Datos básicos, complete los campos como se indica a continuación:

    • Suscripción: seleccione la suscripción que quiera usar para el centro.

    • Grupo de recursos: seleccione un grupo de recursos o cree uno. Para crear uno, haga clic en Crear y escriba el nombre que quiera usar. Para usar un grupo de recursos existente, selecciónelo. Para más información, consulte Administración de grupos de recursos de Azure Resource Manager.

    • Región: seleccione la región a la que quiera asignar el centro. Seleccione la ubicación más cercana a la suya. Algunas características, como los flujos de dispositivo de IoT Hub, solo están disponibles en regiones específicas. Para ver estas características limitadas, debe seleccionar una de las regiones admitidas.

    • Nombre de la instancia de IoT Hub: escriba el nombre del centro. Este nombre debe ser globalmente único y tener una longitud que oscile entre 3 y 50 caracteres alfanuméricos. El nombre también puede incluir el carácter de guion ('-').

    Importante

    Como el centro de IoT se podrá detectar públicamente como un punto de conexión de DNS, asegúrese de que no incluye información de identificación personal ni información confidencial al asignarle un nombre.

    Create a hub in the Azure portal.

  5. Seleccione Siguiente: Redes para continuar con la creación del centro.

    Elija los puntos de conexión que los dispositivos puedan usar para conectar a su instancia de IoT Hub. Puede seleccionar la configuración predeterminada Punto de conexión público (todas las redes) o elegir Punto de conexión público (intervalos de IP seleccionados) o Punto de conexión privado. Acepte la configuración predeterminada para este ejemplo.

    Choose the endpoints that can connect.

  6. Seleccione Siguiente: Administración para continuar con la creación del centro.

    Set the size and scale for a new hub using the Azure portal.

    Puede aceptar la configuración predeterminada aquí. Si lo desea, puede modificar cualquiera de los siguientes campos:

    • Plan de tarifa y escala: nivel seleccionado. Puede elegir entre varios niveles, en función del número de características que desee, y del número de mensajes que envíe al día a través de su solución. El nivel gratis está pensado para la prueba y evaluación. Permite la conexión de 500 dispositivos con el centro de IoT y hasta 8000 mensajes al día. Cada suscripción a Azure puede crear un centro de IoT en el nivel gratis.

      Si está trabajando con un inicio rápido de flujos de dispositivo de IoT Hub, seleccione el nivel gratuito.

    • Unidades de IoT Hub: El número de mensajes que se permiten por unidad al día depende del plan de tarifa del centro. Por ejemplo, si quiere que el Centro de IoT admita la entrada de 700 000 mensajes, seleccione dos unidades del nivel S1. Para más información sobre las demás opciones del nivel, consulte la sección Elección del nivel correcto de IoT Hub.

    • Microsoft Defender para IoT: actívelo para agregar un nivel adicional de protección ante amenazas en IoT y en los dispositivos. Esta opción no está disponible para los centros de conectividad del nivel gratuito. Obtenga más información sobre las recomendaciones de seguridad para IoT Hub en Defender para IoT.

    • Configuración avanzadaParticiones del dispositivo a la nube: esta propiedad relaciona los mensajes del dispositivo a la nube con el número de lectores simultáneos de los mensajes. La mayoría de los centros solo necesitan cuatro particiones.

  7. Seleccione Siguiente: Etiquetas para pasar a la pantalla siguiente.

    Las etiquetas son pares nombre-valor. Puede asignar la misma etiqueta a varios recursos y grupos de recursos para clasificar los recursos y consolidar la facturación. En este documento, no va a agregar ninguna etiqueta. Para más información, consulte Uso de etiquetas para organizar los recursos de Azure.

    Assign tags for the hub using the Azure portal.

  8. Seleccione Siguiente: Revisar y crear para revisar sus selecciones. Verá algo parecido a esta pantalla, pero con los valores que ha seleccionado al crear el centro.

    Review information for creating the new hub.

  9. Seleccione Crear para iniciar la implementación del nuevo centro. La implementación estará en curso unos minutos mientras se crea el centro. Una vez que la implementación finalice, haga clic en Ir al recurso para abrir el nuevo centro.

Registro de un nuevo dispositivo en el centro de IoT

En esta sección, creará una identidad de dispositivo en el registro de identidades del centro de IoT. No se puede conectar un dispositivo a un centro a menos que tenga una entrada en el registro de identidades. Vea la guía para desarrolladores de IoT Hub para más información.

  1. En el menú de navegación del centro de IoT, abra Dispositivos y, después, seleccione Agregar dispositivo para agregar un dispositivo nuevo en el centro de IoT.

    Screen capture that shows how to create a device identity in the portal

  2. En Crear un dispositivo, proporcione un nombre para el dispositivo nuevo, como IdDeMiDispositivo y seleccione Guardar. Esta acción crea una nueva identidad de dispositivo para su centro de IoT. Deje activada la opción Generar claves automáticamente para que las claves principal y secundaria se generen de forma automática.

    Screen capture that shows how to add a new device

    Importante

    El identificador del dispositivo puede estar visible en los registros recopilados para soporte técnico y solución de problemas del cliente, por tanto asegúrese de evitar cualquier información confidencial al darle el nombre.

  3. Después de crear el dispositivo, ábralo desde la lista del panel Dispositivos. Copie la Cadena de conexión principal. El código del dispositivo usa esta cadena de conexión para comunicarse con el centro.

    De forma predeterminada, las claves y las cadenas de conexión se enmascaran porque son información confidencial. Si hace clic en el icono de ojo, se desvelan. No es necesario mostrarlas para copiarlas con el botón Copiar.

    Screen capture that shows the device connection string

Nota

El registro de identidades de IoT Hub solo almacena identidades de dispositivos para permitir el acceso seguro a IoT Hub. Almacena las claves y los identificadores de dispositivo para usarlos como credenciales de seguridad, y un indicador de habilitado o deshabilitado que permite deshabilitar el acceso a un dispositivo individual. Si la aplicación necesita almacenar otros metadatos específicos del dispositivo, debe usar un almacén específico de la aplicación. Consulte la guía de desarrolladores de IoT Hub para obtener más información.

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.

    Screen capture showing select file upload settings from the 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.

    Screen capture showing confirm file upload settings in the 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, usará un ejemplo del repositorio ejemplos 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-samples-csharp-main\iot-hub\Samples\device\FileUploadSample en la carpeta donde extrajo los ejemplos 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 enviará un mensaje de notificación a los servicios back-end.

    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, verá 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. Tenga en cuenta que, independientemente de esta selección, el cliente de blobs de Azure siempre usa HTTPS como protocolo para cargar el archivo 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. En Claves de acceso compartido, seleccione el icono de copia de Cadena de conexión principal y guarde el valor.

Screenshot that shows how to retrieve the connection string

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 {iot hub connection string}.

    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-samples-csharp-main\iot-hub\Samples\device\FileUploadSample en la carpeta donde expandió los ejemplos de C# para Azure IoT. Ejecute los comandos siguientes: Reemplace el valor del marcador de posición {Your device connection string} en el segundo comando por la cadena de conexión de dispositivo que copió anteriormente en {Your device connection string}.

    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.

    Screenshot of selecting the uploaded file in the 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 tutorial ha aprendido a usar la característica 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: