Configuración de cargas de archivos de IoT Hub mediante la CLI de Azure
En este artículo se muestra cómo configurar cargas de archivos en el centro de IoT mediante la CLI de Azure.
Para usar la funcionalidad de carga de archivos en IoT Hub, primero debe asociar una cuenta de Azure Storage y un contenedor de blobs al centro de IoT. IoT Hub genera automáticamente identificadores URI de SAS con permisos de escritura en este contenedor de blobs para los dispositivos que se utilizarán cuando se carguen archivos. Además de la cuenta de almacenamiento y el contenedor de blobs, puede establecer el período de vida del URI de SAS y el tipo de autenticación que IoT Hub usa con Azure Storage. También puede configurar opciones para las notificaciones de carga de archivos opcionales que IoT Hub puede entregar a los servicios de back-end.
Requisitos previos
Una cuenta de Azure activa. En caso de no tener ninguna, puede crear una cuenta gratuita en tan solo unos minutos.
Una instancia de IoT Hub en la suscripción de Azure. Si aún no tiene un centro, puede seguir los pasos descritos en Creación de un centro de IoT.
Una cuenta de Azure Storage con un contenedor de blobs. Si no tiene ninguna cuenta de Azure Storage, puede usar la CLI de Azure para crear una. Para obtener más información, consulte Creación de una cuenta de almacenamiento.
Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.
Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.
Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.
En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.
Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.
Nota
En este artículo se usa la versión más reciente de la extensión de Azure IoT, denominada azure-iot. La versión heredada se denomina azure-cli-iot-ext. Solo debe tener instalada una versión a la vez. Puede usar el comando az extension list para validar las extensiones instaladas actualmente.
Use az extension remove --name azure-cli-iot-ext para eliminar la versión heredada de la extensión.
Use az extension add --name azure-iot para agregar la nueva versión de la extensión.
Para ver las extensiones que ha instalado, use az extension list.
Inicio de sesión y configuración de la cuenta de Azure
Inicie sesión en la cuenta de Azure y seleccione su suscripción. Si usa Azure Cloud Shell, ya debería haber iniciado sesión; pero es posible que todavía tenga que seleccionar la suscripción de Azure si tiene varias suscripciones.
En el símbolo del sistema, ejecute el comando de inicio de sesión:
az loginSiga las instrucciones para realizar la autenticación mediante el código e inicie sesión en la cuenta de Azure a través de un explorador web.
Si tiene varias suscripciones de Azure, iniciar sesión en Azure le concede acceso a todas las cuentas de Azure asociadas con las credenciales. Use el siguiente comando para mostrar las cuentas de Azure que tiene disponibles para su uso:
az account listUse el siguiente comando para seleccionar la suscripción que desee usar para ejecutar los comandos que crearán la instancia de IoT Hub. Puede usar el nombre de la suscripción o el identificador de la salida del comando anterior:
az account set --subscription {your subscription name or id}
Configuración del acceso de la cuenta de almacenamiento
En los siguientes pasos se supone que ha creado la cuenta de almacenamiento mediante el modelo de implementación de Resource Manager, y no el modelo clásico.
Para configurar las cargas de archivos desde los dispositivos, debe conceder permisos de acceso al centro de IoT para la cuenta de Azure Storage. Esta cuenta debe encontrarse en la misma suscripción que IoT Hub. También necesitará el nombre de un contenedor de blobs de la cuenta de almacenamiento.
Puede usar la autenticación basada en claves o basada en identidades para proporcionar los permisos de acceso. Microsoft recomienda la autenticación basada en identidades como la opción más segura.
Autenticación basada en claves
Para la autenticación basada en claves, proporcione la cadena de conexión de la cuenta de almacenamiento. Use el comando az storage account show-connection-string para recuperar las claves de la cuenta de almacenamiento.
Anote el valor connectionString. La cadena de conexión tiene un aspecto similar al siguiente resultado:
{
"connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your_storage_account_name};AccountKey={your_storage_account_key}"
}
Habilitación basada en identidad
Puede usar identidades administradas asignadas por el sistema o identidades administradas asignadas por el usuario para la autenticación basada en identidades. Para obtener más información, consulte la compatibilidad de IoT Hub con identidades administradas.
Use el comando az role assignment create para asignar un rol a la identidad administrada. Para más información, vea Asignación de un rol de Azure para el acceso a datos de blob.
Configuración del centro de IoT
Ahora puede configurar la instancia de IoT Hub para permitir la carga de archivos en IoT Hub con los datos de la cuenta de almacenamiento.
La configuración requiere los siguientes valores:
Contenedor de almacenamiento: : un contenedor de blobs en una cuenta de Azure Storage en la suscripción actual para asociar con IoT Hub. En la sección anterior, recuperó la información necesaria de la cuenta de almacenamiento. IoT Hub genera automáticamente identificadores URI de SAS con permisos de escritura en este contenedor de blobs para los dispositivos que se utilizarán cuando se carguen archivos.
Receive notifications for uploaded files (Recibir notificaciones para archivos cargados): habilite o deshabilite las notificaciones de carga de archivos.
SAS TTL(TTL SAS): este valor es el periodo de vida de los URI de SAS que Azure IoT Hub devuelve al dispositivo. De forma predeterminada, está establecido en una hora.
File notification settings default TTL (TTL predeterminado de configuración de notificación de archivos): el periodo de vida de una notificación de carga de archivos antes de que expire. De forma predeterminada, está establecido en un día.
File notification maximum delivery count(Número máximo de entregas de notificaciones de archivo): el número de veces que Azure IoT Hub tratará de entregar una notificación de carga de archivos. De forma predeterminada, está establecido en 10.
File notification lock duration (Duración del bloqueo de notificación de archivo): duración del bloqueo de la cola de notificación de archivos. Se establece en 60 segundos de forma predeterminada.
Tipo de autenticación: tipo de autenticación IoT Hub que se usará con Azure Storage. Esta configuración determina cómo se autentica y autoriza el centro de IoT con Azure Storage. El valor predeterminado es la autenticación basada en claves; sin embargo, se recomiendan las opciones de autenticación de identidad administrada asignada por el sistema o asignada por el usuario. Las identidades administradas proporcionan a los servicios de Azure una identidad administrada automáticamente en Microsoft Entra ID de forma segura.
Nota:
La configuración del tipo de autenticación establece cómo se autentica el centro de IoT con la cuenta de Azure Storage. Los dispositivos siempre se autentican con Azure Storage mediante el URI de SAS que obtienen del centro de IoT.
Use los siguientes comandos para mostrar cómo configurar la carga de archivos en el centro de IoT. Estos comandos se muestran por separado para mayor claridad, pero, normalmente, emitiría un único comando con todos los parámetros necesarios para su escenario. Incluya comillas cuando aparezcan en la línea de comandos. No incluya las llaves. Puede encontrar más detalles sobre cada parámetro en la documentación de la CLI de Azure del comando az iot hub update.
El siguiente comando configura la cuenta de almacenamiento y el contenedor de blobs.
az iot hub update --name {your iot hub name} \
--fileupload-storage-connectionstring "{your storage account connection string}" \
--fileupload-storage-container-name "{your container name}"
El comando siguiente establece el período de vida del URI de SAS en el valor predeterminado (una hora).
az iot hub update --name {your iot hub name} \
--fileupload-sas-ttl 1
El siguiente comando habilita las notificaciones de archivos y establece las propiedades de notificación de archivos en sus valores predeterminados. (El período de vida de la notificación de carga de archivos se establece en una hora y la duración del bloqueo en 60 segundos).
az iot hub update --name {your iot hub name} \
--fileupload-notifications true \
--fileupload-notification-max-delivery-count 10 \
--fileupload-notification-ttl 1 \
--fileupload-notification-lock-duration 60
El comando siguiente configura la autenticación basada en claves:
az iot hub update --name {your iot hub name} \
--fileupload-storage-auth-type keyBased
El comando siguiente configura la autenticación mediante la identidad administrada asignada por el sistema del centro de IoT. Para poder ejecutar este comando, debe habilitar la identidad administrada asignada por el sistema para IoT Hub y concederle el rol de control de acceso basado en rol correcto en la cuenta de Azure Storage. Para obtener más información, vea Compatibilidad de IoT Hub con identidades administradas.
az iot hub update --name {your iot hub name} \
--fileupload-storage-auth-type identityBased \
--fileupload-storage-identity [system]
Los comandos siguientes recuperan las identidades administradas asignadas por el usuario configuradas en el centro de IoT y configuran la autenticación con una de ellas. Para poder usar una identidad administrada asignada por el usuario para autenticarse, en el centro de IoT debe configurar y conceder un rol de control de acceso basado en rol adecuado en la cuenta de Azure Storage. Para obtener más información y conocer los pasos, vea Compatibilidad de IoT Hub con identidades administradas.
Para consultar identidades administradas asignadas por el usuario en el centro de IoT, use el comando az iot hub identity show.
az iot hub identity show --name {your iot hub name} --query userAssignedIdentities
El comando devuelve una colección de las identidades administradas asignadas por el usuario configuradas en el centro de IoT. En la salida siguiente se muestra una colección que contiene una única identidad administrada asignada por el usuario.
{
"/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}":
{
"clientId": "<client ID GUID>",
"principalId": "<principal ID GUID>"
}
}
El comando siguiente configura la autenticación para usar la identidad asignada por el usuario anterior.
az iot hub update --name {your iot hub name} \
--fileupload-storage-auth-type identityBased \
--fileupload-storage-identity "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}"
Puede revisar la configuración en el centro de IoT mediante el siguiente comando:
az iot hub show --name {your iot hub name}
Para revisar solo la configuración de carga de archivos, use el siguiente comando:
az iot hub show --name {your iot hub name}
--query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'
Para la mayoría de las situaciones, es más fácil usar los parámetros con nombre de la CLI de Azure; sin embargo, también puede configurar la carga de archivos con el parámetro --set. Los comandos siguientes pueden ayudarle a comprender cómo hacerlo.
az iot hub update --name {your iot hub name} \
--set properties.storageEndpoints.'$default'.connectionString="{your storage account connection string}"
az iot hub update --name {your iot hub name} \
--set properties.storageEndpoints.'$default'.containerName="{your storage container name}"
az iot hub update --name {your iot hub name} \
--set properties.storageEndpoints.'$default'.sasTtlAsIso8601=PT1H0M0S
az iot hub update --name {your iot hub name} \
--set properties.enableFileUploadNotifications=true
az iot hub update --name {your iot hub name} \
--set properties.messagingEndpoints.fileNotifications.maxDeliveryCount=10
az iot hub update --name {your iot hub name} \
--set properties.messagingEndpoints.fileNotifications.ttlAsIso8601=PT1H0M0S