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

Connecter un appareil à IoT Hub

Un appareil périphérique peut être authentifié auprès d’IoT Hub à l’aide des méthodes suivantes :

• Certificat X.509
• Clé d’accès partagé

S’authentifier à l’aide d’un certificat X.509

Pour connecter un appareil à IoT Hub à l’aide d’un certificat X.509 :

1. Utilisez DeviceAuthenticationWithX509Certificate pour créer un objet qui contient des informations sur l’appareil et le certificat. DeviceAuthenticationWithX509Certificate est passé en tant que deuxième paramètre à DeviceClient.Create (étape 2).

2. Utilisez DeviceClient.Create pour connecter l’appareil à IoT Hub à l’aide d’un certificat X.509.

Dans cet exemple, les informations sur l’appareil et le certificat sont renseignées dans l’objet auth DeviceAuthenticationWithX509Certificate passé à DeviceClient.Create.

Cet exemple montre les valeurs des paramètres d’entrée du certificat en tant que variables locales pour plus de clarté. Dans un système de production, stockez des paramètres d’entrée sensibles dans des variables d’environnement ou un autre emplacement de stockage plus sécurisé. Par exemple, utilisez cette option Environment.GetEnvironmentVariable("HOSTNAME") pour lire la variable d’environnement du nom d’hôte.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

Pour plus d’informations sur l’authentification par certificat, consultez :

• Authentifier des identités avec des certificats X.509
• Tutoriel : Créer et charger des certificats à des fins de test

Exemples de code

Pour obtenir des exemples de fonctionnement de l’authentification d’un appareil avec le certificat X.509, consultez :

• Se connecter avec un certificat X.509
• DeviceClientX509AuthenticationE2ETests
• Projet guidé : provisionner des appareils IoT en toute sécurité et à grande échelle avec le service IoT Hub Device Provisioning

S’authentifier à l’aide d’une clé d’accès partagé

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.

Ajouter un package NuGet de service

Les applications de service principal nécessitent le package NuGet Microsoft.Azure.Devices.

Se connecter au hub IoT

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

• Stratégie d’accès partagé
• Microsoft Entra

Se connecter à l’aide d’une stratégie d’accès partagé

Connectez une application back-end à un appareil à l’aide de CreateFromConnectionString. Votre application a besoin de l’autorisation de connexion de service. Fournissez cette chaîne de connexion de stratégie d’accès partagé en tant que paramètre pour fromConnectionString. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

Par exemple :

using Microsoft.Azure.Devices;
static ServiceClient serviceClient;
static string connectionString = "{Shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Se connecter à l’aide de Microsoft Entra

Une application back-end qui utilise Microsoft Entra doit s’authentifier et obtenir des informations d’identification de jeton de sécurité avant de se connecter à IoT Hub. Ce jeton est passé à une méthode de connexion IoT Hub. Pour obtenir des informations générales sur la configuration et l’utilisation de Microsoft Entra pour IoT Hub, consultez Contrôler l’accès à IoT Hub à l’aide de Microsoft Entra ID.

Configurer l’application Microsoft Entra

Vous devez configurer une application Microsoft Entra configurée pour vos informations d’identification d’authentification préférées. L’application contient des paramètres tels que la clé secrète client utilisée par l’application back-end pour s’authentifier. Les configurations d’authentification d’application disponibles sont les suivantes :

• Clè secrète client
• Certificat
• Informations d’identification d’identité fédérée

Les applications Microsoft Entra peuvent nécessiter des autorisations de rôle spécifiques en fonction des opérations effectuées. Par exemple, le Contributeur de jumeaux IoT Hub est nécessaire pour activer l’accès en lecture et en écriture à un appareil IoT Hub et à des jumeaux de module. Pour plus d’informations, consultez Gérer l’accès à IoT Hub à l’aide de l’attribution de rôle RBAC Azure.

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Par souci de simplicité, cette section décrit l’authentification à l’aide de DefaultAzureCredential et de la clé secrète client. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Conseils d’utilisation pour DefaultAzureCredential.

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Cette méthode tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’elle trouve des informations d’identification fonctionnelles.

Microsoft Entra nécessite ces packages NuGet et les instructions using correspondantes :

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

Dans cet exemple, la clé secrète client d’inscription de l’application Microsoft Entra, l’ID client et l’ID de locataire sont ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par DefaultAzureCredential pour authentifier l’application. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à une méthode de connexion IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Le TokenCredential résultant peut ensuite être passé pour se connecter à une méthode IoT Hub pour n’importe quel client du Kit de développement logiciel (SDK) qui accepte les informations d’identification Microsoft Entra :

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

Dans cet exemple, TokenCredential est passé à ServiceClient.Create pour créer un objet de connexion ServiceClient.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Dans cet exemple, TokenCredential est passé à RegistryManager.Create pour créer un objet RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Exemple de code

Pour obtenir un exemple fonctionnel de l’authentification du service Microsoft Entra, consultez Exemple d’authentification basée sur les rôles.

Recevoir les notifications de chargement de fichier

Pour recevoir une notification de chargement de fichier :

1. Créez un CancellationToken.
2. Appelez GetFileNotificationReceiver pour créer un récepteur de notifications.
3. Utilisez une boucle avec ReceiveAsync pour attendre la notification de chargement de fichier.

Par exemple :

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

Exemple de récepteur de chargement de fichiers avec le Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) inclut cet exemple de récepteur de chargement de fichiers.

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. Connecter l’appareil à IoT Hub
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

Connecter un appareil à IoT Hub

Un appareil périphérique peut être authentifié auprès d’IoT Hub à l’aide des méthodes suivantes :

• Certificat X.509
• Clé d’accès partagé

S’authentifier à l’aide d’un certificat X.509

Pour connecter un appareil à IoT Hub à l’aide d’un certificat X.509 :

1. Générez l’objet SSLContextà l’aide de buildSSLContext.
2. Ajoutez les SSLContext informations à un objet ClientOptions.
3. Appelez DeviceClient à l’aide des ClientOptions informations pour créer la connexion device-to-IoT Hub.

Cet exemple montre les valeurs des paramètres d’entrée du certificat en tant que variables locales pour plus de clarté. Dans un système de production, stockez des paramètres d’entrée sensibles dans des variables d’environnement ou un autre emplacement de stockage plus sécurisé. Par exemple, utilisez Environment.GetEnvironmentVariable("PUBLICKEY") pour lire une variable d’environnement de chaîne du certificat de clé publique.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

Pour plus d’informations sur l’authentification par certificat, consultez :

• Authentifier des identités avec des certificats X.509
• Tutoriel : Créer et charger des certificats à des fins de test

Exemples de code

Pour obtenir des exemples de fonctionnement de l’authentification d’un appareil avec le certificat X.509, consultez :

• Exemple de réception et d’envoi x509
• Envoyer un événement x509

S’authentifier à l’aide d’une clé d’accès partagé

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;

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

Créer une application back-end

Cette section explique comment recevoir une notification de chargement de fichier dans une application back-end.

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

Ajouter des instructions import

Ajoutez ces instructions importer pour utiliser le Kit de développement logiciel (SDK) Java Azure IoT et le gestionnaire d’exceptions.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

Se connecter au hub IoT

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

• Stratégie d’accès partagé
• Microsoft Entra

Se connecter à l’aide d’une stratégie d’accès partagé

Définir le protocole de connexion

Utilisez IotHubServiceClientProtocol pour définir le protocole de couche application utilisé par le client de service pour communiquer avec un IoT Hub.

IotHubServiceClientProtocol accepte uniquement l’énumération AMQPS ou AMQPS_WS .

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Créer l’objet ServiceClient

Créez l’objet ServiceClient , en fournissant la chaîne de connexion et le protocole Iot Hub.

Pour charger un fichier sur un appareil vers IoT Hub, 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.

En tant que paramètre du constructeur ServiceClient, fournissez la stratégie d’accès partagé du service. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
private static final ServiceClient serviceClient (iotHubConnectionString, protocol);

Ouvrir la connexion entre l’application et IoT Hub

Ouvrir la connexion de l’expéditeur AMQP. Cette méthode crée la connexion entre l’application et IoT Hub.

serviceClient.open();

Se connecter à l’aide de Microsoft Entra

Une application back-end qui utilise Microsoft Entra doit s’authentifier et obtenir des informations d’identification de jeton de sécurité avant de se connecter à IoT Hub. Ce jeton est passé à une méthode de connexion IoT Hub. Pour obtenir des informations générales sur la configuration et l’utilisation de Microsoft Entra pour IoT Hub, consultez Contrôler l’accès à IoT Hub à l’aide de Microsoft Entra ID.

Pour obtenir une vue d’ensemble de l’authentification à l’aide du kit SDK Java, consultez Authentification Azure avec Java et Azure Identity.

Par souci de simplicité, cette section se concentre sur la description de l’authentification à l’aide d’une clé secrète client.

Configurer l’application Microsoft Entra

Vous devez configurer une application Microsoft Entra configurée pour vos informations d’identification d’authentification préférées. L’application contient des paramètres tels que la clé secrète client utilisée par l’application back-end pour s’authentifier. Les configurations d’authentification d’application disponibles sont les suivantes :

• Clè secrète client
• Certificat
• Informations d’identification d’identité fédérée

Les applications Microsoft Entra peuvent nécessiter des autorisations de rôle spécifiques en fonction des opérations effectuées. Par exemple, le Contributeur de jumeaux IoT Hub est nécessaire pour activer l’accès en lecture et en écriture à un appareil IoT Hub et à des jumeaux de module. Pour plus d’informations, consultez Gérer l’accès à IoT Hub à l’aide de l’attribution de rôle RBAC Azure.

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour Java.

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Cette méthode tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’elle trouve des informations d’identification fonctionnelles.

Vous pouvez authentifier les informations d’identification de l’application Microsoft Entra en utilisant DefaultAzureCredentialBuilder. Enregistrez les paramètres de connexion tels que l’ID de locataire, l’ID client et les valeurs de la clé secrète client en tant que variables environnementales. Une fois TokenCredential créé, passez-le à ServiceClient ou à un autre générateur en tant que paramètre « credential ».

Dans cet exemple, DefaultAzureCredentialBuilder tente d’authentifier une connexion à partir de la liste décrite dans DefaultAzureCredential. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à un constructeur tel que ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

S’authentifier en utilisant ClientSecretCredentialBuilder

Vous pouvez utiliser ClientSecretCredentialBuilder pour créer des informations d’identification à l’aide des informations de la clé secrète client. Si cette méthode réussit, elle retourne un TokenCredential qui peut être passé à ServiceClient ou à un autre générateur en tant que paramètre « credential ».

Dans cet exemple, les valeurs de l’ID de locataire, de l’ID client et de la clé secrète client d’inscription de l’application Microsoft Entra ont été ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par ClientSecretCredentialBuilder pour générer les informations d’identification.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Autres classes d’authentification

Le kit SDK Java inclut également ces classes qui authentifient une application back-end auprès de Microsoft Entra :

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

Exemples de code

Pour obtenir des exemples fonctionnels d’authentification auprès du service Microsoft Entra, consultez Exemple d’authentification basée sur les rôles.

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 = serviceClient.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.

Importer des bibliothèques

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

Connecter un appareil à IoT Hub

Un appareil périphérique peut être authentifié auprès d’IoT Hub à l’aide des méthodes suivantes :

• Certificat X.509
• Clé d’accès partagé

S’authentifier à l’aide d’un certificat X.509

Pour connecter un appareil à IoT Hub à l’aide d’un certificat X.509 :

1. Utilisez create_from_x509_certificate pour ajouter les paramètres de certificat X.509
2. Appelez connect pour connecter le client d’appareil

Cet exemple montre les valeurs des paramètres d’entrée du certificat en tant que variables locales pour plus de clarté. Dans un système de production, stockez des paramètres d’entrée sensibles dans des variables d’environnement ou un autre emplacement de stockage plus sécurisé. Par exemple, utilisez cette option os.getenv("HOSTNAME") pour lire la variable d’environnement du nom d’hôte.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

Pour plus d’informations sur l’authentification par certificat, consultez :

• Authentifier des identités avec des certificats X.509
• Tutoriel : Créer et charger des certificats à des fins de test

Exemples de code

Pour obtenir des exemples de fonctionnement de l’authentification par certificat X.509 de l’appareil, consultez les exemples dont les noms de fichiers se terminent par x509 dans les scénarios de hub asynchrone.

S’authentifier à l’aide d’une clé d’accès partagé

Pour connecter un appareil à IoT Hub :

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

Cet article explique comment utiliser le Kit de développement logiciel (SDK) Azure IoT pour Node.js afin de créer une application d’appareil pour charger un fichier et une application de service back-end pour recevoir une notification de chargement de fichier.

Créer 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 IoT Hub :

1. Connecter l’appareil à IoT Hub
2. Obtenir un jeton de signature d’accès partagé d’objet blob à partir d’IoT Hub
3. Charger le fichier dans Stockage Azure
4. 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 Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

Connecter un appareil à IoT Hub

Un appareil périphérique peut être authentifié auprès d’IoT Hub à l’aide des méthodes suivantes :

• Certificat X.509
• Clé d’accès partagé

S’authentifier à l’aide d’un certificat X.509

Le certificat X.509 est attaché au transport de connexion appareil-à-IoT Hub.

Pour configurer une connexion appareil-à-IoT Hub à l’aide d’un certificat X.509 :

1. Appelez fromConnectionString pour ajouter la chaîne de connexion de l’appareil et le type de transport. Ajoutez x509=true à la chaîne de connexion de l’appareil pour indiquer qu’un certificat est ajouté à DeviceClientOptions. Par exemple : HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true.
2. Configurez une variable JSON avec les détails du certificat et transmettez-la à DeviceClientOptions.
3. Appelez setOptions pour ajouter un certificat et une clé X.509 (et éventuellement, phrase secrète) au transport client.
4. Appelez Open pour ouvrir la connexion à partir de l’appareil vers IoT Hub.

Cet exemple montre des informations de configuration de certificat dans une variable JSON. La configuration options de certification est transmise à setOptionset la connexion est ouverte à l’aide de open.

var options = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }
 client.setOptions(options, callback);
 client.open(connectCallback);

Pour plus d’informations sur l’authentification par certificat, consultez :

• Authentifier des identités avec des certificats X.509
• Créer et charger des certificats à des fins de test

Exemple de code

Pour obtenir un exemple de fonctionnement de l’authentification de certificat X.509 de l’appareil, consultez l’exemple simple d’appareil X.509.

S’authentifier à l’aide d’une clé d’accès partagé

Choisir un protocole de transport

L’objet Client prend en charge ces protocoles :

• Amqp
• Http - Lors de l'utilisation de Http, l'instance Client vérifie rarement les messages provenant d'IoT Hub (au minimum toutes les 25 minutes).
• Mqtt
• MqttWs
• AmqpWs

Installez les protocoles de transport nécessaires sur votre ordinateur de développement.

Par exemple, cette commande installe le protocole Amqp :

npm install azure-iot-device-amqp --save

Pour plus d’informations sur les différences de prise en charge entre MQTT, AMQP et HTTPS, consultez Conseils sur les communications cloud-à-appareil et Choisir un protocole de communication.

Créer un objet client

Créer un objet Client à l’aide du package installé.

Par exemple :

const Client = require('azure-iot-device').Client;

Créer un objet de protocole

Créez un objet Protocol à l’aide d’un package de transfert installé.

Cet exemple affecte le protocole AMQP :

const Protocol = require('azure-iot-device-amqp').Amqp;

Ajouter la chaîne de connexion d’appareil et le protocole de transfert

Appelez fromConnectionString pour fournir des paramètres de connexion d’appareil :

• connStr : chaîne de connexion de l’appareil.
• transportCtor : protocole de transport.

Cet exemple utilise le protocole de transfert Amqp :

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Ouvrir la connexion à IoT Hub

Utilisez la méthode open pour ouvrir la connexion entre un appareil IoT et IoT Hub.

Par exemple :

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Obtenir un jeton SAS à partir d’IoT Hub

Utilisez getBlobSharedAccessSignature pour obtenir auprès du hub IoT le jeton SAP du compte de stockage lié.

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

Charger le fichier local dans le stockage d’objets blob

Vous pouvez charger un fichier local dans le stockage Blob à partir d’un ordinateur

const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

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.

Créer une application back-end

Cette section explique comment recevoir des notifications de chargement de fichiers dans une application back-end.

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

Installer le package de Kit de développement logiciel (SDK) de service

Exécutez cette commande pour installer azure-iothub sur votre machine de développement :

npm install azure-iothub --save

Se connecter au hub IoT

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

• Stratégie d’accès partagé
• Microsoft Entra

Se connecter à l’aide d’une stratégie d’accès partagé

Utilisez fromConnectionString pour vous connecter au hub IoT Hub.

Pour charger un fichier à partir d’un appareil, 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.

En tant que paramètre dans CreateFromConnectionString, fournissez la chaîne de connexion de stratégie d’accès partagé du service. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

Se connecter à l’aide de Microsoft Entra

Une application back-end qui utilise Microsoft Entra doit s’authentifier et obtenir des informations d’identification de jeton de sécurité avant de se connecter à IoT Hub. Ce jeton est passé à une méthode de connexion IoT Hub. Pour obtenir des informations générales sur la configuration et l’utilisation de Microsoft Entra pour IoT Hub, consultez Contrôler l’accès à IoT Hub à l’aide de Microsoft Entra ID.

Pour obtenir une vue d’ensemble de l’authentification à l’aide du kit SDK Node.js, consultez :

• Bien démarrer avec l’authentification utilisateur sur Azure
• Bibliothèque cliente Azure Identity pour JavaScript

Configurer l’application Microsoft Entra

Vous devez configurer une application Microsoft Entra configurée pour vos informations d’identification d’authentification préférées. L’application contient des paramètres tels que la clé secrète client utilisée par l’application back-end pour s’authentifier. Les configurations d’authentification d’application disponibles sont les suivantes :

• Clè secrète client
• Certificat
• Informations d’identification d’identité fédérée

Les applications Microsoft Entra peuvent nécessiter des autorisations de rôle spécifiques en fonction des opérations effectuées. Par exemple, le Contributeur de jumeaux IoT Hub est nécessaire pour activer l’accès en lecture et en écriture à un appareil IoT Hub et à des jumeaux de module. Pour plus d’informations, consultez Gérer l’accès à IoT Hub à l’aide de l’attribution de rôle RBAC Azure.

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Par souci de simplicité, cette section décrit l’authentification à l’aide de DefaultAzureCredential et de la clé secrète client. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour JavaScript.

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Cette méthode tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’elle trouve des informations d’identification fonctionnelles.

Microsoft Entra nécessite ce package :

npm install --save @azure/identity

Dans cet exemple, l’ID de locataire, l’ID client et la clé secrète client d’inscription de l’application Microsoft Entra ont été ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par DefaultAzureCredential pour authentifier l’application. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à une méthode de connexion IoT Hub.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Le jeton d’informations d’identification résultant peut ensuite être passé à fromTokenCredential pour se connecter à IoT Hub pour n’importe quel client du kit SDK qui accepte les informations d’identification Microsoft Entra :

• Registre
• Client
• JobClient

fromTokenCredential nécessite deux paramètres :

• URL du service Azure : l’URL du service Azure doit être au format {Your Entra domain URL}.azure-devices.net sans préfixe https://. Par exemple : MyAzureDomain.azure-devices.net.
• Jeton d’informations d’identification Azure

Dans cet exemple, les informations d’identification Azure sont obtenues en utilisant DefaultAzureCredential. L’URL et les informations d’identification du domaine Azure sont ensuite fournies à Registry.fromTokenCredential pour créer la connexion à IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Exemples de code

Pour obtenir des exemples fonctionnels d’authentification auprès du service Microsoft Entra, consultez Exemples d’identité Azure.

Créer un récepteur de rappel de notification de chargement de fichier

Pour créer un récepteur de rappel de notification de 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 notification de chargement de fichier SDK

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