Charger des fichiers depuis un appareil sur le cloud avec Azure IoT Hub

Vue d’ensemble

Cette procédure contient deux sections :

• Charger un fichier depuis une application d’appareil
• Recevoir une notification de chargement de fichier dans une application back-end

Charger un fichier depuis une application d’appareil

Cette section explique comment charger un fichier depuis un appareil vers un hub IoT en utilisant la classe DeviceClient du Kit de développement logiciel (SDK) Azure IoT pour .NET.

Suivez cette procédure pour charger un fichier depuis un appareil vers IoT Hub :

1. Se connecter au hub IoT
2. Obtenir un URI SAP auprès du hub IoT
3. Charger le fichier dans le stockage Azure
4. Informer le hub IoT de l’état de chargement du fichier

Se connecter à l’appareil

Appelez CreateFromConnectionString pour vous connecter à l’appareil. Passez la chaîne de connexion principale de l’appareil.

AMQP est le protocole de transport par défaut.

static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);

Obtenir un URI SAP auprès du hub IoT

Appelez GetFileUploadSasUriAsync pour obtenir les détails du chargement du fichier. L’URI SAP est utilisé à l’étape suivante pour charger un fichier depuis un appareil vers Stockage Blob.

const string filePath = "TestPayload.txt";
using var fileStreamSource = new FileStream(filePath, FileMode.Open);
var fileName = Path.GetFileName(fileStreamSource.Name);
var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest, System.Threading.CancellationToken cancellationToken = default);
Uri uploadUri = sasUri.GetBlobUri();

Charger un fichier dans le stockage Azure

Pour charger un fichier dans le stockage Azure :

1. Créez un objet blockBlobClient, en passant un URI de chargement de fichier.

2. Utilisez la méthode UploadAsync pour charger un fichier dans Stockage Blob, en passant l’URI SAP. Vous pouvez aussi ajouter des options de chargement d’objets blob et des paramètres de jeton d’annulation.

Le client Blob Azure utilise toujours HTTPS comme protocole pour charger le fichier dans le stockage Azure.

Dans cet exemple, BlockBlobClient reçoit l’URI SAP qui lui est passé pour créer un client Blob de blocs de stockage Azure et charge le fichier :

var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, null, null);

Informer le hub IoT de l’état de chargement du fichier

Utilisez CompleteFileUploadAsync pour informer le hub IoT que le client de l’appareil a terminé le chargement, en passant un objet FileUploadCompletionNotification. L’indicateur IsSuccess indique si le chargement a réussi ou non. Après avoir été notifié, le hub IoT libère les ressources associées au chargement (l’URI SAP).

Si les notifications de chargement de fichier sont activées, le hub IoT envoie un message de notification de chargement du fichier aux services back-ends configurés pour la notification de chargement de fichier.

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);

Exemple de chargement de fichier du Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) inclut cet exemple de chargement de fichier.

Recevoir une notification de chargement de fichier dans une application back-end

Vous pouvez créer un service back-end pour recevoir les messages de notification de chargement de fichier depuis le hub IoT.

La classe ServiceClient contient des méthodes que les services peuvent utiliser pour recevoir des notifications de chargement de fichier.

Pour recevoir une notification de chargement de fichier :

1. Appelez CreateFromConnectionString pour vous connecter au hub IoT. Passez la chaîne de connexion principale au hub IoT.
2. Créez un CancellationToken.
3. Appelez GetFileNotificationReceiver pour créer un récepteur de notifications.
4. Utilisez une boucle avec ReceiveAsync pour attendre la notification de chargement de fichier.

Par exemple :

using Microsoft.Azure.Devices;
static ServiceClient serviceClient;
static string connectionString = "{IoT hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

// Define the cancellation token
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;

// Create a notification receiver
var notificationReceiver = serviceClient.GetFileNotificationReceiver();
Console.WriteLine("\nReceiving file upload notification from service");

// Check for file upload notifications
while (true)
{
    var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);
    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);
}

Vue d’ensemble

Cette procédure contient deux sections :

• Charger un fichier depuis une application d’appareil
• Recevoir une notification de chargement de fichier dans une application back-end

Charger un fichier depuis une application d’appareil

Cette section explique comment charger un fichier depuis un appareil vers un hub IoT en utilisant la classe DeviceClient du Kit de développement logiciel (SDK) Azure IoT pour Java.

Suivez cette procédure pour charger un fichier depuis un appareil vers IoT Hub :

1. Se connecter à l’appareil
2. Obtenir un URI SAP auprès du hub IoT
3. Charger le fichier dans Stockage Azure
4. Envoyer une notification d’état du chargement de fichier au hub IoT

Protocole de connexion

Les opérations de chargement de fichier utilisent toujours HTTPS, mais DeviceClient peut définir le IotHubClientProtocol pour d’autres services, comme la télémétrie, la méthode d’appareil et le jumeau d’appareil.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

Se connecter à l’appareil

Instanciez le DeviceClient pour vous connecter à l’appareil en utilisant la chaîne de connexion principale de l’appareil.

String connString = "{IoT hub connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

Obtenir un URI SAP auprès du hub IoT

Appelez getFileUploadSasUri pour obtenir un objet FileUploadSasUriResponse.

FileUploadSasUriResponse inclut ces méthodes et valeurs de retour. Les valeurs de retour peuvent être passées aux méthodes de chargement de fichier.

Par exemple :

FileUploadSasUriResponse sasUriResponse = client.getFileUploadSasUri(new FileUploadSasUriRequest(file.getName()));

System.out.println("Successfully got SAS URI from IoT hub");
System.out.println("Correlation Id: " + sasUriResponse.getCorrelationId());
System.out.println("Container name: " + sasUriResponse.getContainerName());
System.out.println("Blob name: " + sasUriResponse.getBlobName());
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());

Charger le fichier dans Stockage Azure

Passez le point de terminaison de l’URI d’objet blob à BlobClientBuilder.buildclient pour créer l’objet BlobClient.

BlobClient blobClient =
    new BlobClientBuilder()
        .endpoint(sasUriResponse.getBlobUri().toString())
        .buildClient();

Appelez uploadFromFile pour charger le fichier dans Stockage Blob.

String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);

Envoyer une notification d’état du chargement de fichier au hub IoT

Envoyez une notification d’état du chargement au hub IoT après une tentative de chargement de fichier.

Créez un objet FileUploadCompletionNotification. Passez l’état de réussite du chargement du fichier correlationId et isSuccess. Passez une valeur isSuccess true quand le chargement du fichier a réussi ou false quand ce n’est pas le cas.

FileUploadCompletionNotification doit être appelée même en cas d’échec de chargement du fichier. Un nombre fixe d’URI SAP peuvent être actifs à un moment donné sur le hub IoT. Une fois le chargement du fichier terminé, vous devez libérer votre URI SAP pour que d’autres URI SAP puissent être générés. Si un URI SAP n’est pas libéré via cette API, il finit par se libérer lui-même en fonction de la durée de vie des URI SAP configurée sur un hub IoT.

Cet exemple passe un état de réussite.

FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);

Fermer le client

Libérez les ressources client.

client.closeNow();

Recevoir une notification de chargement de fichier dans une application back-end

Vous pouvez créer une application back-end pour recevoir des notifications de chargement de fichier.

Pour créer une application de notification de chargement de fichier :

1. Se connecter au client du service IoT Hub
2. Rechercher s’il y a une notification de chargement de fichier

La classe ServiceClient contient des méthodes que les services peuvent utiliser pour recevoir des notifications de chargement de fichier.

Se connecter au client du service IoT Hub

Créez un objet IotHubServiceClientProtocol. La connexion utilise le protocole AMQPS.

Appelez createFromConnectionString pour vous connecter au hub IoT. Passez la chaîne de connexion principale au hub IoT.

private static final String connectionString = "{IoT hub primary connection string}";
private static final IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;
ServiceClient sc = ServiceClient.createFromConnectionString(connectionString, protocol);

Vérifier l’état du chargement de fichier

Pour vérifier l’état du chargement de fichier :

1. Créez un objet getFileUploadNotificationReceiver.
2. Utilisez open pour vous connecter au hub IoT.
3. Appelez receive pour vérifier l’état du chargement de fichier. Cette méthode retourne un objet fileUploadNotification. Si une notification de chargement est reçue, vous pouvez visualiser les champs d’état du chargement en utilisant des méthodes fileUploadNotification.

Par exemple :

FileUploadNotificationReceiver receiver = sc.getFileUploadNotificationReceiver();
receiver.open();
FileUploadNotification fileUploadNotification = receiver.receive(2000);

if (fileUploadNotification != null)
{
    System.out.println("File Upload notification received");
    System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
    System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
    System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
    System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
    System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
    System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
}
else
{
    System.out.println("No file upload notification");
}

// Close the receiver object
receiver.close();

Exemples de chargement de fichier du Kit de développement logiciel (SDK)

Il existe deux exemples de chargement de fichier Java.

Installer des packages

La bibliothèque azure-iot-device doit être installée avant d’appeler du code associé.

pip install azure-iot-device

Le package azure.storage.blob est utilisé pour effectuer le chargement du fichier.

pip install azure.storage.blob

Charger un fichier depuis une application d’appareil

Cette section explique comment charger un fichier depuis un appareil vers un hub IoT en utilisant la classe IoTHubDeviceClient du Kit de développement logiciel (SDK) Azure IoT pour Python.

Suivez cette procédure pour charger un fichier depuis un appareil vers IoT Hub :

1. Se connecter à l’appareil
2. Obtenir les informations du Stockage Blob
3. Charger le fichier dans Stockage Blob
4. Informer le hub IoT de l’état du chargement

Importer des bibliothèques

import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient

Se connecter à l’appareil

Pour vous connecter à l’appareil :

1. Appelez create_from_connection_string pour ajouter la chaîne de connexion principale de l’appareil.

2. Appelez connect pour connecter le client d’appareil.

Par exemple :

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Obtenir les informations du Stockage Blob

Appelez get_storage_info_for_blob pour obtenir auprès d’un hub IoT des informations sur un compte de stockage Azure lié. Ces informations incluent le nom d’hôte, le nom du conteneur, le nom de l’objet Blob et un jeton SAP. La méthode get_storage_info_for_blob retourne également un correlation_id, qui est utilisé dans la méthode notify_blob_upload_status. Le correlation_id est le moyen utilisé par IoT Hub pour marquer l’objet blob sur lequel vous travaillez.

# Get the storage info for the blob
PATH_TO_FILE = "{Full path to local file}"
blob_name = os.path.basename(PATH_TO_FILE)
blob_info = device_client.get_storage_info_for_blob(blob_name)

Charger un fichier dans Stockage Blob

Pour charger un fichier dans Stockage Blob :

1. Utilisez from_blob_url pour créer un objet BlobClient à partir d’une URL de blob.
2. Appelez upload_blob pour charger le fichier dans Stockage Blob.

Cet exemple analyse la structure blob_info pour créer une URL qu’il utilise pour initialiser un BlobClient. Il appelle ensuite upload_blob pour charger le fichier dans Stockage Blob.

try:
    sas_url = "https://{}/{}/{}{}".format(
        blob_info["hostName"],
        blob_info["containerName"],
        blob_info["blobName"],
        blob_info["sasToken"]
    )

    print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))

    # Upload the specified file
    with BlobClient.from_blob_url(sas_url) as blob_client:
        with open(file_name, "rb") as f:
            result = blob_client.upload_blob(f, overwrite=True)
            return (True, result)

except FileNotFoundError as ex:
    # catch file not found and add an HTTP status code to return in notification to IoT hub
    ex.status_code = 404
    return (False, ex)

except AzureError as ex:
    # catch Azure errors that might result from the upload operation
    return (False, ex)

Informer le hub IoT de l’état du chargement

Utilisez notify_blob_upload_status pour informer le hub IoT de l’état de l’opération de Stockage Blob. Passez le correlation_id obtenu par la méthode get_storage_info_for_blob. Le correlation_id est utilisé par le hub IoT pour informer un service qui pourrait être à l’écoute d’une notification sur l’état de la tâche de chargement de fichier.

Cet exemple informe le hub IoT d’un chargement de fichier réussi :

device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)

Arrêter le client d’appareil

Arrêtez le client. Une fois cette méthode appelée, toute tentative d’appels supplémentaires du client provoque une ClientError.

device_client.shutdown()

Exemples de chargement de fichier du Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) inclut deux exemples de chargement de fichier :

• Charger dans un blob
• Charger dans un blob en utilisant un certificat X.509

Vue d’ensemble

Cette procédure contient deux sections :

• Charger un fichier depuis une application d’appareil
• Recevoir une notification de chargement de fichier dans une application back-end

Charger un fichier depuis une application d’appareil

Cette section explique comment charger un fichier depuis un appareil vers un hub IoT en utilisant le package azure-iot-device du Kit de développement logiciel (SDK) Azure IoT pour Node.js.

Installer les packages du Kit de développement logiciel (SDK)

Exécutez cette commande pour installer le Kit de développement logiciel (SDK) d’appareil azure-iot-device et les packages azure-iot-device-mqtt et @azure/storage-blob sur votre machine de développement :

npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save

Le package azure-iot-device contient des objets qui s’interfacent avec les appareils IoT.

Suivez cette procédure pour charger un fichier depuis un appareil vers un hub IoT :

1. Obtenir des signatures d’accès partagé de blob
2. Charger le fichier dans Stockage Azure
3. Envoyer une notification d’état du chargement de fichier au hub IoT

Créer des modules

Créez des modules Client, Protocole, Erreurs et Chemins d’accès en utilisant les packages installés.

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');

Obtenir un URI SAP auprès du hub IoT

Utilisez getBlobSharedAccessSignature pour obtenir auprès du hub IoT le jeton SAP du compte de stockage lié. Comme décrit dans les prérequis, le hub IoT est lié au stockage Blob.

Par exemple :

// make sure you set these environment variables prior to running the sample.
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);
const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
if (!blobInfo) {
throw new errors.ArgumentError('Invalid upload parameters');
}

Charger le fichier dans le hub IoT

Pour charger un fichier depuis un appareil dans un hub IoT :

1. Créer un pipeline de flux
2. Construire l’URL du blob
3. Créer un BlockBlobClient pour le chargement de fichier dans Stockage Blob
4. Appeler uploadFile pour charger le fichier dans Stockage Blob
5. Appeler notifyBlobUploadStatus pour informer le hub IoT que le chargement a réussi ou a échoué

Par exemple :

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

// Construct the blob URL
const { hostName, containerName, blobName, sasToken } = blobInfo;
const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

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

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

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

  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);
  }

// Send file upload status notification to IoT hub
await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);

Recevoir une notification de chargement de fichier dans une application back-end

Vous pouvez créer une application back-end pour vérifier auprès du client de service du hub IoT s’il y a des notifications de chargement de fichier d’appareil.

Pour créer une application de notification de chargement de fichier :

1. Se connecter au client du service IoT Hub
2. Rechercher s’il y a une notification de chargement de fichier

Se connecter au client du service IoT Hub

La classe ServiceClient contient des méthodes que les services peuvent utiliser pour recevoir des notifications de chargement de fichier.

Connectez-vous au hub IoT en utilisant fromConnectionString. Passez la chaîne de connexion principale au hub IoT.

const Client = require('azure-iothub').Client;
const connectionString = "{IoT hub primary connection string}";
const serviceClient = Client.fromConnectionString(connectionString);

Ouvrez la connexion au hub IoT.

//Open the connection to IoT hub
serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');

Rechercher s’il y a une notification de chargement de fichier

Pour vérifier s’il y a des notifications de téléchargement de fichier :

1. Appelez getFileNotificationReceiver. Indiquez le nom d’une méthode de rappel de chargement de fichier qui est appelée quand des messages de notification sont reçus.
2. Traitez les notifications de chargement de fichier dans la méthode de rappel.

Cet exemple configure un récepteur de rappel de notification receiveFileUploadNotification. Le récepteur interprète les informations d’état de chargement de fichier et affiche un message d’état sur la console.

//Set up the receiveFileUploadNotification notification message callback receiver
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');
      }
    });
  });
}

Exemple de chargement de fichier du Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) inclut un exemple de chargement avancé dans un blob.