Charger des fichiers sur le cloud à partir de votre appareil à l’aide d’Azure IoT Hub (.NET)

Article
03/19/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 un appareil Azure IoT .NET et les SDK de service.

Le démarrage rapide Envoyer des données de télémétrie d’un appareil vers un hub IoT et l’article 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. L’article 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. Si vous avez besoin de charger des fichiers à partir d’un appareil, vous pouvez toujours exploiter la sécurité et la fiabilité d’IoT Hub. Cet article vous montre comment procéder.

À la fin de cet article, vous exécutez deux applications de console .NET :

FileUploadSample. Cet appareil charge un fichier de stockage à l’aide d’un URI SAP fourni par votre IoT Hub. Cet exemple provient du référentiel Kit de développement logiciel (SDK) C# Azure IoT que vous téléchargez dans les conditions préalables.
ReadFileUploadNotification. Cette application de service reçoit les notifications de chargement de fichier à partir de votre hub IoT. Vous créez cette application.

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 votre appareil dans le portail Azure.
Les exemples d’applications que vous exécutez dans cet article sont écrits à l’aide de C# avec .NET Core.

Téléchargez le Kit SDK .NET Core pour plusieurs plateformes sur .NET.

Vérifiez la version actuelle du SDK .NET Core sur votre machine de développement à l’aide de la commande suivante :
```
dotnet --version
```
Téléchargez le Kit de développement logiciel (SDK) C# Azure IoT à partir des exemples à télécharger et décompressez l’archive ZIP.
Le port 8883 doit être ouvert dans votre pare-feu. L’exemple 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 cet article, vous allez utiliser un exemple du référentiel du Kit de développement logiciel (SDK) C# Azure IoT que vous avez téléchargé précédemment en tant qu’application d’appareil. Vous pouvez ouvrir les fichiers ci-dessous à l’aide de Visual Studio, Visual Studio Code ou un éditeur de texte de votre choix.

L’exemple se trouve dans le azure-iot-sdk-csharp/iothub/device/samples/getting started/FileUploadSample dans le dossier dans lequel vous avez extrait les Kit de développement logiciel (SDK) C# Azure IoT.

Examinez le code dans FileUpLoadSample.cs. Ce fichier contient l’exemple de logique principale. Après la création d’un client de périphérique IoT Hub, il suit la procédure en trois parties standard pour le téléchargement de fichiers à partir d’un appareil :

Le code appelle la méthode GetFileUploadSasUriAsync sur le client de l’appareil pour obtenir un URI SAS à partir du Hub IOT :

var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

// Lines removed for clarity

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
Uri uploadUri = sasUri.GetBlobUri();

Le code utilise l’URI SAS pour télécharger le fichier dans le stockage Azure. Dans cet exemple, il utilise l’URI SAS pour créer un client d’objet blob de blocs Azure Storage et charge le fichier :
```
var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());
```

Le code informe l’IoT Hub qu’il a terminé le téléchargement. Cela indique à IoT Hub qu’il peut libérer les ressources associées au téléchargement (l’URI SAS). Si les notifications de téléchargement de fichier sont activées, IoT Hub envoie un message de notification aux services principaux.

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 vous examinez le fichier parameter.cs, vous voyez que :

L’exemple requiert que vous passiez un paramètre, p, qui prend une chaîne de connexion d’appareil.
Par défaut, l’exemple d’appareil utilise le protocole MQTT pour communiquer avec IoT Hub. Vous pouvez utiliser le paramètre t pour modifier ce protocole de transport. Indépendamment de cette sélection, le client d’objet blob Azure utilise toujours HTTPS comme protocole pour télécharger le fichier de stockage Azure.

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 votre hub IoT. 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 C# qui reçoit des messages de notification de chargement de fichiers envoyés par votre Hub IoT.

Ouvrez une fenêtre de commande et accédez au dossier où vous voulez créer le projet. Créez un dossier nommé ReadFileUploadNotifications et modifiez les répertoires de ce dossier.
```
mkdir ReadFileUploadNotification
cd ReadFileUploadNotification
```
Exécutez la commande suivante pour créer un projet de console C#. Une fois la commande exécutée, le dossier contient un fichier Program.cs et un fichier ReadFileUploadNotification. csproj .
```
dotnet new console --language c#
```
Exécutez la commande suivante pour ajouter le package Microsoft. Azure.Devices au fichier projet. Ce package est le kit de développement logiciel (SDK) du service Azure IoT.NET.
```
dotnet add package Microsoft.Azure.Devices
```
Ouvrez le fichiezProgram.cs et spécifiez au début de celui-ci les instructions suivantes :
```
using Microsoft.Azure.Devices;
```
Ajoutez les champs suivants à la classe Program . Remplacez la valeur de l’espace réservé {iot hub connection string} par la chaîne de connexion de l’IoT Hub que vous avez précédemment copiée dans Obtention de la chaîne de connexion de l’IoT Hub :
```
static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";
```

Ajoutez la méthode suivante à la classe 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);
    }
}

Notez que ce modèle de réception est le même que celui utilisé pour recevoir des messages cloud-à-appareil à partir de l’application de l’appareil.

Enfin, remplacez les lignes de la méthode Main par les éléments suivants :

Console.WriteLine("Receive file upload notifications\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
ReceiveFileUploadNotificationAsync();
Console.WriteLine("Press Enter to exit\n");
Console.ReadLine();

Exécution des applications

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

Tout d’abord, exécutez l’application de service pour recevoir des notifications de téléchargement de fichier à partir d’IoT Hub. Depuis votre invite de commandes, dans le dossier ReadFileUploadNotification, exécutez les commandes suivantes :
```
dotnet restore
dotnet run
```
L’application démarre et attend une notification de téléchargement de fichier à partir de votre IoT Hub :
```
Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit
```
Ensuite, exécutez l’application de l’appareil pour télécharger le fichier dans le stockage Azure. Ouvrez une nouvelle invite de commandes et modifiez les dossiers azure-iot-sdk-csharp\iothub\device\samples\getting started\FileUploadSample sous le dossier dans lequel vous avez développé les Kit de développement logiciel (SDK) C# Azure IoT. Exécutez les commandes suivantes : Remplacez la valeur de l'espace réservé {Your device connection string} dans la deuxième commande par la chaîne de connexion de l'appareil que vous avez vue lorsque vous avez enregistré un appareil dans le concentrateur IoT.
```
dotnet restore
dotnet run --p "{Your device connection string}"
```
La sortie suivante provient de l’application d’appareil une fois le téléchargement terminé :
```
  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.
```

Notez que l’application de service indique qu’elle a reçu la notification de téléchargement de fichier :

Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

Received file upload notification: myDeviceId/TestPayload.txt

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 nommé TestPayload.txt.
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 :