Chargement de fichiers avec IoT Hub

Dans de nombreux scénarios, vous ne pouvez pas facilement mapper les données que votre appareil dans des messages appareil-à-cloud relativement petits et acceptés par IoT Hub. Par exemple, l’envoi de grands fichiers multimédias comme des vidéos ou l’envoi de grands lots de données de télémétrie chargés par des appareils connectés de façon intermittente ou qui ont été agrégés et compressés pour économiser de la bande passante.

S’il vous faut charger des fichiers volumineux à partir d’un appareil, vous pouvez toujours exploiter la sécurité et la fiabilité d’IoT Hub. Au lieu de distribuer les messages via lui-même cependant, IoT Hub joue le rôle de répartiteur vers un compte de stockage Azure associé. IoT Hub pouvez également fournir une notification aux services backend lorsqu’un appareil termine un chargement de fichier.

Si vous avez besoin d’aide pour déterminer quand utiliser des propriétés signalées, des messages appareil-à-cloud ou des chargements de fichiers, consultez les Recommandations sur les communications appareil-à-cloud.

Important

La fonctionnalité de chargement de fichiers sur les appareils qui utilisent l’authentification par l’autorité de certification X.509 est en préversion publique, et le mode aperçu doit être activé. Elle est généralement disponible sur les appareils qui utilisent l’authentification par empreinte X.509 ou l’attestation de certificat X.509 avec le service de provisionnement des appareils Azure. Pour en savoir plus sur l’authentification X.509 avec IoT Hub, consultez les certificats X.509 pris en charge.

Vue d’ensemble du chargement de fichier

Un hub IoT facilite les chargements de fichiers depuis des appareils connectés en leur fournissant des URI de signature d’accès partagé (SAP) par chargement pour un conteneur d’objets blob et un compte de stockage Azure qui sont configurés pour le chargement de fichiers depuis le hub. L’utilisation des téléchargements de fichiers avec IoT Hub comporte trois parties :

• Configuration d’un compte de stockage et d’un conteneur d’objets blob Azure sur votre hub IoT.
• Chargement de fichiers depuis des appareils.
• En option, notification aux services back-ends des chargements de fichiers effectués.

Pour pouvoir utiliser la fonctionnalité de chargement de fichiers, vous devez associer un compte de stockage Azure et un conteneur d’objets BLOB à votre hub IoT. Vous pouvez également configurer des paramètres qui contrôlent la façon dont IoT Hub s’authentifie avec le stockage Azure, la durée de vie (TTL, Time-to-Live) des URI SAP que le hub IoT transmet aux appareils et les notifications de chargement de fichiers à vos services principaux. Pour en savoir plus, consultez Association d’un compte de stockage Azure à IoT Hub.

Les appareils suivent un processus en trois étapes pour charger un fichier dans le conteneur d’objets BLOB associé :

1. L’appareil lance le chargement du fichier avec le hub IoT. Il transmet le nom d’un objet BLOB dans la requête et obtient un URI SAP et un ID de corrélation en retour. L’URI SAS contient un jeton SAP pour le stockage Azure qui accorde l’autorisation de lecture/écriture de l’appareil sur l’objet BLOB demandé dans le conteneur d’objets BLOB. Pour plus d’informations, consultez Appareil : Initialiser un chargement de fichier.

2. L’appareil utilise l’URI SAS pour appeler en toute sécurité les API de stockage d’objets BLOB Azure pour charger le fichier dans le conteneur d’objets BLOB. Pour plus d’informations, consultez Appareil : Charger un fichier à l’aide des API de stockage Azure.

3. Une fois le chargement du fichier terminé, l’appareil avertit le hub IoT de l’état d’achèvement à l’aide de l’ID de corrélation qu’il a reçu du hub IoT lorsqu’il a initié le chargement. Pour plus d’informations, consultez Appareil : Notifier le hub IoT de la fin du chargement d’un fichier.

Les services principaux peuvent s’abonner à des notifications de chargement de fichier sur le point de terminaison de notification de chargement de fichier orienté vers le hub IoT. Si vous avez activé ces notifications sur votre hub IoT, il les délivre sur ce point de terminaison chaque fois qu’un appareil notifie au hub qu’il a effectué un chargement de fichier. Les services peuvent utiliser ces notifications pour déclencher un traitement supplémentaire des données BLOB. Pour plus d’informations, consultez Service : Notifications de chargement de fichiers.

Les Kits de développement logiciel (SDK) d’appareil et de service Azure IoT prennent entièrement en charge le chargement de fichiers. Pour plus d’informations, consultez Chargement de fichiers à l’aide d’un SDK.

Quotas et limites de chargement de fichiers

IoT Hub impose des limites de limitation sur le nombre de chargements de fichiers qu’il peut lancer au cours d’une période donnée. Le seuil est basé sur la référence SKU et le nombre d’unités de votre hub IoT. En outre, chaque appareil est limité à 10 chargements de fichiers actifs simultanés à la fois. Pour plus d'informations, consultez Quotas et limitations IoT Hub.

Association d’un compte de stockage Azure à IoT Hub

Vous devez associer un compte de stockage Azure et un conteneur d’objets blob à votre hub IoT pour pouvoir utiliser les fonctionnalités de chargement de fichiers. Tous les chargements de fichiers depuis des appareils inscrits auprès de votre hub IoT vont dans ce conteneur. Pour configurer un compte de stockage et un conteneur d’objets blob sur votre hub IoT, consultez Configurer des chargements de fichiers IoT Hub à l’aide du portail Azure, Configurer des chargements de fichiers IoT Hub à l’aide d’Azure CLI ou Configurer des chargements de fichiers IoT Hub à l’aide de PowerShell. Vous pouvez également utiliser les API de gestion IoT Hub pour configurer les chargements de fichiers par programme.

Par défaut, Azure IoT Hub utilise l’authentification basée sur les clés pour la connexion et l’autorisation avec le Stockage Azure. Vous pouvez également configurer des identités managées affectées par l’utilisateur ou affectées par le système pour authentifier Azure IoT Hub avec le Stockage Azure. 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.

Le chargement de fichiers est soumis aux paramètres de pare-feu de Stockage Azure. Vous devez vérifier que vos appareils peuvent communiquer avec le stockage Azure en fonction de votre configuration de l’authentification.

Il existe plusieurs autres paramètres qui contrôlent le comportement des chargements de fichiers et des notifications de chargement de fichiers. Les sections suivantes répertorient tous les paramètres disponibles. Selon que vous utilisez le portail Azure, Azure CLI, PowerShell ou les API de gestion pour configurer les chargements de fichiers, certains de ces paramètres peuvent ne pas être disponibles. Veillez à définir le paramètre enableFileUploadNotifications si vous souhaitez que les notifications soient envoyées à vos services principaux quand un chargement de fichier se termine.

Paramètres de stockage et d’authentification d’IoT Hub

Les paramètres suivants associent un compte de stockage et un conteneur à votre hub IoT et contrôlent la façon dont votre hub s’authentifie auprès du stockage Azure. Ces paramètres n’affectent pas la manière dont les appareils s’authentifient auprès du stockage Azure. Vous devez toujours connecter vos appareils au stockage en utilisant l’URI de la signature d’accès partagé (SAP). Actuellement, l’URI SAS est généré à l’aide d’une chaîne de connexion.

Pour plus d’informations sur la configuration du chargement de fichiers pour utiliser l’authentification basée sur l’identité, consultez Configurer le chargement de fichiers avec des identités managées.

Propriété	Description	Plage et valeur par défaut
storageEndpoints.$default.authenticationType	Contrôle la façon dont IoT Hub s’authentifie auprès du stockage Azure.	Les valeurs possibles sont keyBased et identityBased. Valeur par défaut : keyBased.
storageEndpoints.$default.connectionString	Chaîne de connexion au compte de stockage Azure à utiliser pour les chargements de fichiers.	Valeur par défaut : chaîne vide.
storageEndpoints.$default.containerName	Nom du conteneur dans lequel charger les fichiers.	Valeur par défaut : chaîne vide.
storageEndpoints.$default.identity	Identité managée à utiliser pour l’authentification basée sur l’identité.	Les valeurs possibles sont [system] pour l’identité managée affectée par le système ou un ID de ressource pour une identité managée affectée par l’utilisateur. La valeur n’est pas utilisée pour l’authentification basée sur les clés. Valeur par défaut : null.

Paramètres de chargement de fichier

Les paramètres suivants contrôlent les chargements de fichiers à partir de l’appareil.

Propriété	Description	Plage et valeur par défaut
storageEndpoints.$default.ttlAsIso8601	Durée de vie par défaut des URI SAS générés par IoT Hub.	Intervalle ISO_8601 jusqu’à 48 heures (minimum une minute). Valeur par défaut : une heure.

Paramètres de notification de chargement de fichier

Les paramètres suivants contrôlent les notifications de chargement de fichier vers les services principaux.

Propriété	Description	Plage et valeur par défaut
enableFileUploadNotifications	Indique si les notifications de téléchargement de fichier sont écrites dans le point de terminaison de notification de fichier.	Valeur booléenne. Valeur par défaut : False.
fileNotifications.ttlAsIso8601	Durée de vie par défaut des notifications de téléchargement de fichier.	Intervalle ISO_8601 jusqu’à 48 heures (minimum une minute). Valeur par défaut : une heure.
fileNotifications.lockDuration	Durée de verrouillage de la file d’attente des notifications de téléchargement de fichiers.	5 à 300 secondes. Valeur par défaut : 60 secondes.
fileNotifications.maxDeliveryCount	Nombre maximal de diffusions pour la file d’attente de notification de téléchargement de fichier.	1 à 100. Par défaut : 10.

Charger des fichiers à l’aide d’un kit de développement logiciel (SDK)

Les guides pratiques suivants fournissent des instructions pas à pas complètes pour charger des fichiers à l’aide des kits de développement logiciel (SDK) d’appareils et de services Azure IoT. Les guides vous montrent comment utiliser le portail Azure pour associer un compte de stockage à un hub IoT. Ils contiennent également des extraits de code ou font référence à des exemples qui vous guident tout au long d’un chargement.

Guide pratique	Exemple de SDK d’appareil	Exemple de SDK de service
.NET	Oui	Oui
Java	Oui	Oui
Node.JS	Oui	Oui
Python	Oui	Non (non pris en charge)

Notes

Le Kit de développement logiciel (SDK) d’appareil C utilise un seul appel sur le client d’appareil pour effectuer des chargements de fichiers. Pour plus d’informations, consultez IoTHubDeviceClient_UploadToBlobAsync() et IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Ces fonctions effectuent tous les aspects du chargement d’un fichier en un seul appel : lancer le chargement, charger le fichier dans le stockage Azure et notifier IoT Hub quand l’opération est terminée. Cette interaction signifie que, en plus du protocole que l’appareil utilise pour communiquer avec IoT Hub, l’appareil doit également être en mesure de communiquer par le biais du protocole HTTPS avec le stockage Azure, car ces fonctions effectuent des appels aux API de stockage Azure.

Appareil : initialiser un chargement de fichier

L’appareil appelle l’API REST de création de fichier de chargement d’URI SAS ou l’API équivalente dans l’un des Kits de développement logiciel (SDK) d’appareil pour lancer un chargement de fichier.

Protocoles pris en charge : HTTPS
Point de terminaison : {iot hub}.azure-devices.net/devices/{deviceId}/files
Méthode : POST

{
    "blobName":"myfile.txt"
}

Propriété	Description
blobName	Nom de l’objet BLOB pour lequel générer l’URI SAS.

IoT Hub répond avec un ID de corrélation et les éléments d’un URI SAS que l’appareil peut utiliser pour s’authentifier auprès du stockage Azure. Cette réponse est soumise aux limites de limitation et aux limites de chargement par appareil du hub IoT cible.

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.windows.net",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}

Propriété	Description
correlationId	Identificateur de l’appareil à utiliser lors de l’envoi de la notification de téléchargement de fichier complet à IoT Hub.
hostName	Nom d’hôte du compte de stockage Azure pour le compte de stockage configuré sur le hub IoT
containerName	Nom du conteneur d’objets BLOB configuré sur le hub IoT.
blobName	Emplacement où l’objet BLOB sera stocké dans le conteneur. Ce nom respecte le format suivant : {device ID of the device making the request}/{blobName in the request}
sasToken	Jeton SAP qui accorde l’accès en lecture-écriture à l’objet BLOB avec le stockage Azure. Le jeton est généré et signé par IoT Hub.

Lorsqu’il reçoit la réponse, l’appareil :

• Enregistre l’ID de corrélation à inclure dans la notification de fin de téléchargement de fichier dans le hub IoT lorsqu’il effectue le téléchargement.

• Utilise les autres propriétés pour construire un URI SAP pour l’objet BLOB qu’il utilise pour s’authentifier auprès du stockage Azure. L’URI SAP contient l’URI de la ressource pour l’objet BLOB demandé et le jeton SAP. Elle prend la forme suivante : https://{hostName}/{containerName}/{blobName}{sasToken} (la propriété sasToken dans la réponse contient un caractère «  ? » de début). Les accolades ne sont pas incluses.

  Par exemple, pour les valeurs retournées dans l’exemple ci-dessus, l’URI SAP est https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw.

  Pour plus d’informations sur l’URI SAP et le jeton SAP, consultez Créer une SAP de service dans la documentation sur le stockage Azure.

Appareil : charger un fichier à l’aide des API de stockage Azure

L’appareil utilise les API REST de Stockage Blob Azure ou les API du SDK Stockage Azure équivalentes pour charger le fichier dans l’objet blob, dans le stockage Azure.

Protocoles pris en charge : HTTPS

L’exemple suivant montre une requête Put Blob pour créer ou mettre à jour un objet blob de petits blocs. Notez que l’URI utilisé pour cette demande est l’URI SAP retourné par IoT Hub dans la section précédente. L'en-tête x-ms-blob-type indique que cette requête concerne un objet blob de blocs. Si la requête réussit, le stockage Azure retourne un 201 Created.

PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob

hello world

L’utilisation des API de stockage Azure sort du cadre de cet article. Outre les API REST de stockage BLOB Azure liées précédemment dans cette section, vous pouvez explorer la documentation suivante pour vous aider à commencer :

• Pour en savoir plus sur l’utilisation des objets blob dans le stockage Azure, consultez la documentation de Stockage Blob Azure.

• Pour plus d’informations sur l’utilisation des Kits de développement logiciel (SDK) client de stockage Azure pour charger des objets blob, consultez Informations de référence sur les API Stockage Blob Azure.

Appareil : notifier IoT Hub de la fin du chargement d’un fichier

L’appareil appelle l’API REST de mise à jour de fichier de chargement des fichiers ou l’API équivalente dans l’un des Kits de développement logiciel (SDK) d’appareil lorsqu’il effectue le chargement de fichier. L’appareil doit mettre à jour l’état de chargement du fichier avec IoT Hub que le chargement réussisse ou échoue.

Protocoles pris en charge : HTTPS
Point de terminaison : {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Méthode : POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}

Propriété	Description
correlationId	ID de corrélation reçu dans la requête d’URI SAP initiale.
isSuccess	Valeur booléenne qui indique si le chargement du fichier a réussi.
statusCode	Entier qui représente le code d’état du chargement de fichier. Généralement trois chiffres ; par exemple, 200 ou 201.
statusDescription	Description de l’état du chargement du fichier.

Lorsqu’il reçoit une notification de fin de chargement de fichier de l’appareil, IoT Hub :

• Déclenche une notification de chargement de fichier pour les services principaux si les notifications de chargement de fichier sont configurées.

• Libère les ressources associées au chargement de fichier. Si IoT Hub ne reçoit pas de notification, il conserve les ressources jusqu’à ce que la durée de vie de l’URI de la signature d’accès partagé (SAP) associée au chargement expire.

Service : notifications de chargement de fichier

Si les notifications de chargement de fichiers sont activées sur votre hub IoT, votre hub génère un message de notification pour les services back-end quand il reçoit une notification provenant d’un appareil indiquant qu’un chargement de fichier est terminé. IoT Hub remet ces notifications de chargement de fichier via un point de terminaison côté service. La sémantique de réception des notifications de chargement de fichiers est identique à celle des messages cloud-à-appareil et présente le même cycle de vie des messages. Les SDK de service exposent des API pour gérer les notifications de chargement de fichier.

Protocoles pris en charge : AMQP, AMQP-WS
Point de terminaison : {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Méthode GET

Chaque message récupéré à partir du point de terminaison de notification de chargement de fichier est un enregistrement JSON :

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}

Propriété	Description
enqueuedTimeUtc	Horodatage indiquant la date et l’heure de création de la notification.
deviceId	ID de l’appareil qui a chargé le fichier.
blobUri	URI du fichier chargé.
blobName	Nom du fichier chargé. Ce nom respecte le format suivant : {device ID of the device}/{name of the blob}
lastUpdatedTime	Horodatage indiquant la date et l’heure de dernière mise à jour du fichier.
blobSizeInBytes	Entier qui représente la taille du fichier chargé en octets.

Les services peuvent utiliser des notifications pour gérer les chargements. Par exemple, ils peuvent déclencher leur propre traitement des données d’objet BLOB, déclencher le traitement des données BLOB à l’aide d’autres services Azure ou consigner la notification de chargement de fichier pour consultation ultérieure.

Étapes suivantes

• Comment configurer les chargements de fichiers sur IoT Hub

• Comment configurer des identités managées sur IoT Hub