Partager via

Configurer les chargements de fichiers IoT Hub à l’aide d’Azure CLI

  • Article

Cet article explique comment configurer des chargements de fichiers sur votre hub IoT à l’aide d’Azure CLI.

Pour utiliser la fonctionnalité de chargement de fichiers dans IoT Hub, vous devez d’abord associer un compte de stockage Azure et un conteneur blob à votre hub IoT. IoT Hub génère automatiquement des URI SAS avec des autorisations d’écriture pour ce conteneur d’objets blob pour les appareils à utiliser lorsqu’ils chargent des fichiers. En plus du compte de stockage et du conteneur blob, vous pouvez définir la durée de vie de l’URI SAS et le type d’authentification que IoT Hub utilise avec le stockage Azure. Vous pouvez également configurer les paramètres des notifications de chargement de fichiers facultatives que IoT Hub peut remettre aux services principaux.

Prérequis

  • Un compte Azure actif. Si vous ne possédez pas de compte, vous pouvez créer un compte gratuit en quelques minutes.

  • Un hub IoT dans votre abonnement Azure. Si vous n’avez pas encore de hub, vous pouvez suivre les étapes décrites dans Créer un hub IoT.

  • Compte Stockage Azure avec conteneur d’objets blob. Si vous n’avez pas de compte Stockage Azure, vous pouvez utiliser Azure CLI pour en créer un. Pour plus d’informations, consultez la rubrique Création d’un compte de stockage .

Notes

Cet article utilise la version la plus récente de l’extension Azure IoT, appelée azure-iot. La version héritée est appelée azure-cli-iot-ext. Une seule version doit être installée à la fois. Vous pouvez utiliser la commande az extension list pour valider les extensions actuellement installées.

Utilisez az extension remove --name azure-cli-iot-ext pour supprimer la version héritée de l’extension.

Utilisez az extension add --name azure-iot pour ajouter la nouvelle version de l’extension.

Pour voir les extensions que vous avez installées, utilisez az extension list.

Se connecter à votre compte Azure et le définir

Vous connecter à votre compte Azure et sélectionner votre abonnement. Si vous utilisez Azure Cloud Shell, vous devez être déjà connecté. Toutefois, vous devrez peut-être sélectionner votre abonnement Azure si vous avez plusieurs abonnements.

  1. Dans l’invite de commande, exécutez la commande login :

    az login

    Suivez les instructions pour vous authentifier à l’aide du code et vous connecter à votre compte Azure via un navigateur web.

  2. Si vous possédez plusieurs abonnements Azure, la connexion à Azure vous donne accès à tous les abonnements Azure associés à vos informations d’identification. Utilisez la commande pour répertorier les comptes Azure ci-dessous :

    az account list

    Utilisez la commande suivante pour sélectionner l’abonnement que vous souhaitez utiliser afin d’exécuter les commandes pour créer votre hub IoT. Vous pouvez utiliser le nom de l’abonnement ou l’ID de la sortie de la commande précédente :

    az account set --subscription {your subscription name or id}

Configurer l’accès du compte de stockage

Les étapes suivantes supposent que vous avez créé votre compte de stockage à l’aide du modèle de déploiement de Resource Manager et non à partir du modèle de déploiement classique.

Pour configurer les chargements de fichiers à partir de vos appareils, vous devez accorder à votre hub IoT des autorisations d’accès au compte de stockage Azure. Le compte de stockage doit être situé dans le même abonnement que votre IoT Hub. Vous avez également besoin du nom d’un conteneur d’objets blob dans le compte de stockage.

Vous pouvez utiliser l’authentification basée sur des clés ou basée sur une identité pour fournir des autorisations d’accès. Microsoft recommande l’authentification basée sur l’identité, car cette option est plus sécurisée.

Authentification basée sur une clé

Pour l’authentification basée sur des clés, fournissez la chaîne de connexion de votre compte de stockage. Utilisez la commande az storage account show-connection-string pour récupérer vos clés de compte de stockage.

Notez la valeur de connectionString. Une chaîne de connexion ressemble au résultat suivant :

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your_storage_account_name};AccountKey={your_storage_account_key}"
}

Authentification basée sur l’identité

Vous pouvez utiliser des identités managées affectées par le système ou des identités managées affectées par l’utilisateur pour l’authentification basée sur l’identité. Pour plus d’informations, consultez Prise en charge d’IoT Hub pour les identités managées.

Utilisez la commande az role assignment create pour affecter un rôle à votre identité managée. Pour plus d’informations, consultez Attribuer un rôle Azure pour l’accès aux données d’objet blob.

Configuration de votre IoT Hub

Vous pouvez désormais configurer votre hub IoT pour activer la fonctionnalité de chargement des fichiers vers le hub IoT à l’aide des informations de votre compte de stockage.

La configuration requiert les valeurs suivantes :

  • Conteneur de stockage : conteneur d’objets blob dans un compte de stockage Azure de votre abonnement Azure actuel à associer à votre hub IoT. Vous avez extrait les informations de compte de stockage nécessaires dans la section précédente. IoT Hub génère automatiquement des URI SAS avec des autorisations d’écriture pour ce conteneur d’objets blob pour les appareils à utiliser lorsqu’ils chargent des fichiers.

  • Recevoir des notifications pour les fichiers chargés : activez ou désactivez les notifications de chargement de fichiers.

  • Durée de vie de SAS : ce paramètre est la durée de vie des URI de signature d’accès partagé retournés à l’appareil par IoT Hub. Défini sur 1 heure par défaut.

  • TTL par défaut des paramètres de notification de fichiers : la durée de vie d’une notification de chargement de fichiers avant son expiration. Défini sur 1 jour par défaut.

  • Nombre maximal de remises de notifications de fichier : nombre de tentatives de remise d’une notification de chargement de fichier par le hub IoT. Défini sur 10 par défaut.

  • Durée du verrouillage des notifications de fichiers : durée de verrouillage de la file d’attente de notifications de fichiers. Défini sur 60 secondes par défaut.

  • Type d’authentification : type d’authentification pour IoT Hub à utiliser avec le stockage Azure. Ce paramètre détermine la manière dont votre hub IoT s’authentifie et autorise le stockage Azure. La valeur par défaut est l’authentification basée sur des clés ; Toutefois, les options d’authentification d’identité managée attribuées par le système ou attribuées par l’utilisateur sont recommandées. Les identités gérées fournissent aux services Azure une identité gérée automatiquement dans Microsoft Entra ID de manière sécurisée.

    Remarque

    Le paramètre du type d’authentification configure la manière dont votre hub IoT s’authentifie avec votre compte de stockage Azure. Les appareils s’authentifient toujours avec le stockage Azure à l’aide de l’URI SAS qu’ils obtiennent du hub IoT.

Utilisez les commandes suivantes pour configurer les paramètres de chargement de fichiers sur votre hub IoT : Ces commandes sont affichées séparément pour plus de clarté, mais, en général, vous émettez une seule commande avec tous les paramètres requis pour votre scénario. Incluez les guillemets où ils apparaissent dans la ligne de commande. N’incluez pas les accolades. Vous trouverez plus d’informations sur chaque paramètre dans la documentation Azure CLI pour la commande az iot hub update.

La commande suivante configure le compte de stockage et le conteneur blob.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}"

La commande suivante définit la durée de vie de l’URI SAS sur la valeur par défaut (une heure).

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1

La commande suivante active les notifications de fichiers et définit les propriétés de notification de fichiers à leurs valeurs par défaut. (La durée de vie de la notification de chargement de fichier est définie sur une heure et la durée de verrouillage est définie sur 60 secondes.)

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

La commande suivante configure l’authentification basée sur les clés :

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

La commande suivante configure l’authentification à l’aide de l’identité managée affectée par le système du hub IoT. Avant de pouvoir exécuter cette commande, vous devez activer l’identité managée affectée par le système pour votre hub IoT et lui accorder le rôle de contrôle d’accès en fonction du rôle approprié sur votre compte de stockage Azure. Pour savoir comment, consultez Support des identités managées par IoT Hub.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system]

Les commandes suivantes récupèrent les identités managées affectées par l’utilisateur configurées sur votre hub IoT et configurent l’authentification avec l’une d’entre elles. Avant de pouvoir utiliser une identité managée affectée par l’utilisateur pour l’authentification, vous devez la configurer sur votre hub IoT et disposer d’un rôle de contrôle d’accès en fonction du rôle approprié sur votre compte de stockage Azure. Pour plus d’informations et pour connaître les étapes à suivre, consultez Support des identités managées par IoT Hub.

Pour interroger les identités managées affectées à l’utilisateur sur votre hub IoT, utilisez la commande az iot hub identity show.

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

La commande retourne une collection des identités managées affectées par l’utilisateur configurées sur votre hub IoT. La sortie suivante montre une collection qui contient une seule identité managée affectée par l’utilisateur.

{
  "/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>"
  }
}

La commande suivante configure l’authentification pour utiliser l’identité affectée par l’utilisateur ci-dessus.

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}"

Vous pouvez réviser les paramètres sur votre hub IoT à l’aide de la commande suivante :

az iot hub show --name {your iot hub name}

Pour ne réviser que les paramètres de chargement de fichiers, utilisez la commande suivante :

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

Dans la plupart des cas, l’utilisation des paramètres nommés dans les commandes Azure CLI est plus simple. Toutefois, vous pouvez également configurer les paramètres de chargement de fichiers avec le paramètre --set. Les commandes suivantes peuvent vous aider à comprendre comment faire.

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

Étapes suivantes