Charger des fichiers depuis un appareil sur le cloud avec Azure IoT Hub
Cet article montre comment :
- Utilisez les fonctionnalités de chargement de fichier d’IoT Hub pour charger un fichier sur Stockage Blob Azure en utilisant un appareil Azure IoT et les Kits de développement logiciel (SDK) du service.
- Informez IoT Hub que le fichier a été chargé correctement et créez un service back-end pour recevoir des notifications de chargement de fichier depuis IoT Hub en utilisant les Kits de développement logiciel (SDK) du service Azure IoT.
Dans certains scénarios, vous ne pouvez pas mapper facilement les données que vos appareils envoient dans les messages appareil-à-cloud relativement petits qui sont acceptés par IoT Hub. Les fonctionnalités de chargement de fichier dans IoT Hub vous permettent de déplacer des données volumineuses ou complexes vers le cloud. 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.
Cet article est destiné à compléter les exemples de SDK exécutables référencés à partir de cet article.
Pour plus d’informations, consultez l’article suivant :
- Vue d’ensemble des chargements de fichiers avec IoT Hub
- Présentation de Stockage Blob Azure
- Kits de développement logiciel (SDK) Azure IoT
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 hub IoT. Certains appels du Kit de développement logiciel (SDK) nécessitent la chaîne de connexion principale d’IoT Hub : prenez donc note de la chaîne de connexion.
Un appareil inscrit. Certains appels du Kit de développement logiciel (SDK) nécessitent la chaîne de connexion principale de l’appareil : prenez donc note de la chaîne de connexion.
Autorisation Connexion de service d’IoT Hub : pour recevoir les messages de notification de chargement de fichier, votre service back-end a besoin de l’autorisation 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 plus d’informations, consultez Se connecter un hub IoT.
Configurez le chargement de fichier dans votre hub IoT en liant un compte de stockage Azure et un conteneur Stockage Blob Azure. Vous pouvez les configurer en utilisant le portail Azure, Azure CLI ou Azure PowerShell.
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 :
- Se connecter au hub IoT
- Obtenir un URI SAP auprès du hub IoT
- Charger le fichier dans le stockage Azure
- 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 :
Créez un objet blockBlobClient, en passant un URI de chargement de fichier.
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 :
- Appelez CreateFromConnectionString pour vous connecter au hub IoT. Passez la chaîne de connexion principale au hub IoT.
- Créez un CancellationToken.
- Appelez GetFileNotificationReceiver pour créer un récepteur de notifications.
- 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 :
- Se connecter à l’appareil
- Obtenir un URI SAP auprès du hub IoT
- Charger le fichier dans Stockage Azure
- 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.
Method | Valeur retournée |
---|---|
getCorrelationId() |
ID de corrélation : |
getContainerName() |
Nom du conteneur |
getBlobName() |
Nom de l’objet blob |
getBlobUri() |
URI de l’objet blob |
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 :
- Se connecter au client du service IoT Hub
- 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 :
- Créez un objet getFileUploadNotificationReceiver.
- Utilisez open pour vous connecter au hub IoT.
- 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 :
- Se connecter à l’appareil
- Obtenir les informations du Stockage Blob
- Charger le fichier dans Stockage Blob
- 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 :
Appelez create_from_connection_string pour ajouter la chaîne de connexion principale de l’appareil.
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 :
- Utilisez from_blob_url pour créer un objet BlobClient à partir d’une URL de blob.
- 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 :
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 :
- Obtenir des signatures d’accès partagé de blob
- Charger le fichier dans Stockage Azure
- 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 :
- Créer un pipeline de flux
- Construire l’URL du blob
- Créer un BlockBlobClient pour le chargement de fichier dans Stockage Blob
- Appeler uploadFile pour charger le fichier dans Stockage Blob
- 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 :
- Se connecter au client du service IoT Hub
- 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 :
- 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.
- 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.