Charger des fichiers sur le cloud à partir d’un appareil avec Azure IoT Hub (Node.js)

Article
03/21/2023

Cet article montre les capacités de chargement de fichiers d’IoT Hub pour charger un fichier vers un stockage blob Azure en utilisant Node.js.

Les articles de démarrage rapide Envoyer des données de télémétrie d’un appareil vers un hub IoT et Envoyer des messages cloud-à-appareil avec IoT Hub illustrent les fonctionnalités de messages appareil-à-cloud et cloud-à-appareil de base offertes par IoT Hub. Le tutoriel Configurer le routage des messages avec IoT Hub montre un moyen de stocker de façon fiable les messages appareil-à-cloud dans Stockage Blob Microsoft Azure. Cependant, dans certains scénarios, vous ne pouvez pas mapper facilement les données que vos appareils envoient dans les messages appareil-à-cloud relativement petits acceptés par IoT Hub. Par exemple :

Vidéos
Fichiers volumineux qui contiennent des images
Données de vibration échantillonnées à une fréquence élevée
Un certain type de données prétraitées.

Ces fichiers sont généralement traités par lot dans le cloud à l’aide d’outils tels que Azure Data Factory ou de la pile Hadoop. Lorsque vous avez besoin de charger des fichiers à partir d’un appareil, vous pouvez quand même exploiter la sécurité et la fiabilité d’IoT Hub. Cet article vous montre comment procéder.

À la fin de cet article, vous exécuterez deux applications de console Node.js :

FileUpload.js, qui charge un fichier dans le stockage à l’aide d’un URI SAS fourni par votre hub IoT.
FileUploadNotification, qui reçoit les notifications de chargement de fichier à partir de votre hub IoT.

Notes

IoT Hub offre la prise en charge de nombreux langages (notamment C, Java, Python et JavaScript) et plateformes d’appareils par le biais des Kits Azure IoT device SDK. Consultez le Centre de développement Azure IoT pour savoir comment connecter votre appareil à Azure IoT Hub.

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.

Prérequis

Un IoT Hub. Créez-en un avec l’interface CLI ou le portail Azure.
Appareil inscrit. Inscrivez-en un dans le portail Azure.
Node.j version 10.0.x ou ultérieure. La version LTS est recommandée. Vous pouvez télécharger Node.js depuis nodejs.org.
Le port 8883 doit être ouvert dans votre pare-feu. L’exemple d’appareil décrit dans cet article utilise le protocole MQTT, qui communique via le port 8883. Ce port peut être bloqué dans certains environnements réseau professionnels et scolaires. Pour plus d’informations sur les différentes façons de contourner ce problème, consultez Connexion à IoT Hub (MQTT).

Associer un compte Azure Storage à IoT Hub

Pour télécharger des fichiers à partir d’un appareil, vous devez disposer d’un compte de stockage Azure et d’un conteneur Stockage Blob Azure associés à votre IoT Hub. Une fois que vous associez le compte de stockage et le conteneur à votre hub IoT, il peut fournir les éléments d’un URI SAS lorsqu’il est demandé par un appareil. L’appareil peut ensuite utiliser ces éléments pour construire l’URI SAS qu’il utilise pour s’authentifier auprès du Stockage Azure et charger des fichiers dans le conteneur d’objets blob.

Pour associer un compte de Stockage Azure à votre hub IoT :

DansParamètres hub, sélectionnez Chargement de fichiers dans le volet gauche de votre hub IoT.
Dans le voletChargement de fichiers sélectionnez Conteneur de stockage Azure. Pour cet article, il est recommandé que votre compte de stockage et votre IoT Hub se trouvent dans la même région.
- Si vous avez déjà un compte de stockage que vous souhaitez utiliser, sélectionnez-le dans la liste.
- Pour créer un nouveau compte de stockage, sélectionnez +Compte de stockage. Donnez un nom au compte de stockage et veillez à ce que l’Emplacement soit défini sur la même région que votre hub IoT, puis sélectionnez OK. Le nouveau compte est créé dans le même groupe de ressources que votre IoT Hub. Une fois le déploiement terminé, sélectionnez le compte de stockage dans la liste.
Une fois le compte de stockage sélectionné, le volet Conteneurs s’ouvre.
Dans le volet Conteneurs, sélectionnez le conteneur d’objets blob.
- Si vous disposez déjà d’un conteneur d’objets blob que vous souhaitez utiliser, sélectionnez-le dans la liste et cliquez sur Sélectionner.
- Sélectionnez + Conteneur pour créer un nouveau conteneur d’objets blob. Donnez un nom au nouveau conteneur. Dans le cadre de cet article, vous pouvez conserver les valeurs par défaut de tous les autres champs. Sélectionnez Create (Créer). Une fois le déploiement terminé, sélectionnez le conteneur dans la liste et cliquez sur Sélectionner.
De nouveau dans le volet Chargement de fichiers veillez à ce que les notifications de fichiers soient configurées sur On. Vous pouvez garder les valeurs par défaut de tous les autres paramètres. Sélectionnez Enregistrer et attendez l’exécution des paramètres avant de passer à la section suivante.

Pour plus d’informations sur la création d’un compte de stockage Azure, consultez Créer un compte de stockage. Pour obtenir des instructions plus détaillées sur la façon d’associer un compte de stockage et un conteneur d’objets blob à un hub IoT, consultez Configurer les chargements de fichiers à l’aide du portail Azure.

Charger un fichier à partir d’une application d’appareil

Dans cette section, créez une application d’appareil pour charger un fichier sur IoT Hub. Le code est basé sur le code disponible dans l’exemple upload_to_blob_advanced.js des exemples d’appareil du SDK Azure IoT node.js.

Créez un dossier vide appelé fileupload. Dans le dossier fileupload, créez un fichier package.json en saisissant la commande suivante dans votre invite de commandes. Acceptez toutes les valeurs par défaut :
```
npm init
```
Dans l’invite de commandes du dossier fileupload, exécutez la commande suivante pour installer le Kit de développement logiciel (SDK) d’appareil azure-iot-device, ainsi que les packages azure-iot-device-mqtt et @azure/storage-blob :
```
npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save
```

À l’aide d’un éditeur de texte, créez un fichier FileUpload.js dans le dossier fileupload, puis copiez le code suivant dans celui-ci.

'use strict';

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

const {
  AnonymousCredential,
  BlockBlobClient,
  newPipeline
} = require('@azure/storage-blob');

// make sure you set these environment variables prior to running the sample.
const deviceConnectionString = process.env.DEVICE_CONNECTION_STRING;
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);

async function uploadToBlob(localFilePath, client) {
  const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
  if (!blobInfo) {
    throw new errors.ArgumentError('Invalid upload parameters');
  }

  const pipeline = newPipeline(new AnonymousCredential(), {
    retryOptions: { maxTries: 4 },
    telemetry: { value: 'HighLevelSample V1.0.0' }, // Customized telemetry string
    keepAliveOptions: { enable: false }
  });

  // Construct the blob URL to construct the blob client for file uploads
  const { hostName, containerName, blobName, sasToken } = blobInfo;
  const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

  // Create the BlockBlobClient for file upload to the Blob Storage Blob
  const blobClient = new BlockBlobClient(blobUrl, pipeline);

  // Setup blank status notification arguments to be filled in on success/failure
  let isSuccess;
  let statusCode;
  let statusDescription;

  try {
    const uploadStatus = await blobClient.uploadFile(localFilePath);
    console.log('uploadStreamToBlockBlob success');

    // Save successful status notification arguments
    isSuccess = true;
    statusCode = uploadStatus._response.status;
    statusDescription = uploadStatus._response.bodyAsText;

    // Notify IoT Hub of upload to blob status (success)
    console.log('notifyBlobUploadStatus success');
  }
  catch (err) {
    isSuccess = false;
    statusCode = err.code;
    statusDescription = err.message;

    console.log('notifyBlobUploadStatus failed');
    console.log(err);
  }

  await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);
}

// Create a client device from the connection string and upload the local file to blob storage.
const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

Enregistrez et fermez le fichier FileUpload.js.
Copiez un fichier image dans le dossier fileupload et attribuez-lui un nom, tel que myimage.png.
Ajoutez des variables d’environnement pour la chaîne de connexion de votre appareil et le chemin du fichier que vous souhaitez charger. Vous avez obtenu la chaîne de connexion de l'appareil lorsque vous avez enregistré un appareil dans le hub IoT.
- Pour Windows :
```
set DEVICE_CONNECTION_STRING={your device connection string}
set PATH_TO_FILE={your image filepath}
```
- Pour Linux/Bash :
```
export DEVICE_CONNECTION_STRING="{your device connection string}"
export PATH_TO_FILE="{your image filepath}"
```

Obtenir la chaîne de connexion du hub IoT

Dans cet article, vous créez un service back-end pour recevoir les messages de notification de chargement de fichiers depuis le hub IoT que vous avez créé. Pour recevoir les messages de notification de chargement de fichiers, votre service a besoin de l'autorisation de connexion de service. Par défaut, chaque IoT Hub est créé avec une stratégie d’accès partagé nommée service qui accorde cette autorisation.

Pour obtenir la chaîne de connexion IoT Hub pour la stratégie service, procédez comme suit :

Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.
Dans le volet de gauche de votre IoT Hub, sélectionnez Stratégies d’accès partagé.
Dans la liste des stratégies, sélectionnez la stratégie service.
Copiez la Chaîne de connexion principale, puis enregistrez la valeur.

Pour plus d’informations sur les autorisations et les stratégies d’accès partagé IoT Hub, consultez Contrôle d’accès et autorisations.

Recevoir une notification de téléchargement de fichier

Dans cette section, vous allez créer une application console Node.js qui reçoit des messages de notification de chargement de fichiers envoyés par IoT Hub.

Créez un dossier vide appelé fileuploadnotification. Dans le dossier fileuploadnotification, créez un fichier package.json en saisissant la commande suivante dans votre invite de commandes. Acceptez toutes les valeurs par défaut :
```
npm init
```
Depuis votre invite de commandes, dans le dossier fileuploadnotification, exécutez la commande suivante pour installer le package SDK azure-iothub :
```
npm install azure-iothub --save
```
À l’aide d’un éditeur de texte, créez un fichier FileUploadNotification.js dans le dossier fileuploadnotification.
Ajoutez les instructions require ci-dessous au début du fichier FileUploadNotification.js :
```
'use strict';

const Client = require('azure-iothub').Client;
```
Lisez la chaîne de connexion de votre hub IoT à partir de l’environnement :
```
const connectionString = process.env.IOT_HUB_CONNECTION_STRING;
```
Ajoutez le code suivant pour créer un client de service à partir de la chaîne de connexion :
```
const serviceClient = Client.fromConnectionString(connectionString);
```

Ouvrez le client et utilisez la fonction getFileNotificationReceiver pour recevoir les mises à jour d’état.

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
      if (err) {
        console.error('error getting the file notification receiver: ' + err.toString());
      } else {
        receiver.on('message', function (msg) {
          console.log('File upload from device:')
          console.log(msg.getData().toString('utf-8'));
          receiver.complete(msg, function (err) {
            if (err) {
              console.error('Could not finish the upload: ' + err.message);
            } else {
              console.log('Upload complete');
            }
          });
        });
      }
    });
  }
});

Notes

Si vous souhaitez recevoir des notifications de déconnexion pendant que vous écoutez les notifications de chargement de fichiers, vous devez inscrire 'error' à l’aide de receiver.on. Pour continuer à recevoir des notifications de chargement de fichiers, vous devez vous reconnecter à IoT Hub à l’aide de la méthode serviceClient.open.

Enregistrez et fermez le fichier FileUploadNotification.js.
Ajouter une variable d’environnement pour votre chaîne de connexion IoT Hub. Vous avez copié cette chaîne précédemment dans Get Obtenir la chaîne de connexion du hub IoT.
- Pour Windows :
```
set IOT_HUB_CONNECTION_STRING={your iot hub connection string}
```
- Pour Linux/Bash :
```
export IOT_HUB_CONNECTION_STRING="{your iot hub connection string}"
```

Exécution des applications

Vous êtes maintenant prêt à exécuter les applications.

Dans une invite de commandes, exécutez la commande suivante dans le dossier fileuploadnotification :

node FileUploadNotification.js

Dans une invite de commandes, exécutez la commande suivante dans le dossier fileupload :

node FileUpload.js

La sortie suivante provient de l’application FileUpload une fois le téléchargement terminé :

uploadStreamToBlockBlob success
notifyBlobUploadStatus success

L’exemple de sortie suivant provient de l’application FileUploadNotification après la fin du téléchargement :

Service client connected
File upload from device:
{"deviceId":"myDeviceId","blobUri":"https://{your storage account name}.blob.core.windows.net/device-upload-container/myDeviceId/image.png","blobName":"myDeviceId/image.png","lastUpdatedTime":"2021-07-23T23:27:06+00:00","blobSizeInBytes":26214,"enqueuedTimeUtc":"2021-07-23T23:27:07.2580791Z"}

Vérifier le chargement du fichier

Vous pouvez utiliser le portail pour afficher le fichier chargé dans le conteneur de stockage que vous avez configuré :

Accédez à votre compte de stockage dans le portail Azure.
Sur le volet gauche de votre compte de stockage, sélectionnez Conteneurs.
Sélectionnez le conteneur dans lequel vous avez chargé le fichier.
Sélectionnez le dossier portant le nom de votre appareil.
Sélectionnez l’objet blob dans lequel vous avez chargé votre fichier. Dans cet article, il s’agit de l’objet blob portant le même nom que votre fichier.
Affichez les propriétés de l’objet blob sur la page qui s’ouvre. Vous pouvez sélectionner Télécharger pour télécharger le fichier et visualiser son contenu localement.

Étapes suivantes

Dans cet article, vous avez appris à utiliser les fonctionnalités de téléchargement de fichier d’IoT Hub pour simplifier les chargements de fichiers à partir d’appareils. Vous pouvez approfondir cette fonctionnalité en lisant les articles suivants :

Share via