Caricare file da un dispositivo nel cloud con hub IoT di Azure

Panoramica

Questa procedura contiene due sezioni:

• Caricare un file da un'applicazione del dispositivo
• Ricevere una notifica di caricamento di file in un'applicazione back-end

Caricare un file da un'applicazione del dispositivo

Questa sezione descrive come caricare un file da un dispositivo in un hub IoT usando la classe DeviceClient in Azure IoT SDK per .NET.

Seguire questa procedura per caricare un file da un dispositivo all'hub IoT:

1. Connettersi all'hub IoT
2. Ottenere un URI di firma di accesso condiviso dall'hub IoT
3. Caricare il file in Archiviazione di Azure
4. Notificare all'hub IoT lo stato di caricamento del file

Connettere un dispositivo all'hub IoT

Un'app per dispositivi può eseguire l'autenticazione con hub IoT usando i metodi seguenti:

• Certificato X.509
• Chiave di accesso condiviso

Eseguire l'autenticazione con un certificato X.509

Per connettere un dispositivo a hub IoT usando un certificato X.509:

1. Usare DeviceAuthenticationWithX509Certificate per creare un oggetto contenente informazioni sul dispositivo e sul certificato. DeviceAuthenticationWithX509Certificate viene passato come secondo parametro a DeviceClient.Create (passaggio 2).

2. Usare DeviceClient.Create per connettere il dispositivo a hub IoT usando un certificato X.509.

In questo esempio le informazioni sul dispositivo e sul certificato vengono popolate nell'oggetto auth DeviceAuthenticationWithX509Certificate passato a DeviceClient.Create.

Questo esempio mostra i valori dei parametri di input del certificato come variabili locali per maggiore chiarezza. In un sistema di produzione archiviare i parametri di input sensibili nelle variabili di ambiente o in un altro percorso di archiviazione più sicuro. Ad esempio, usare Environment.GetEnvironmentVariable("HOSTNAME") per leggere la variabile di ambiente del nome host.

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

Per altre informazioni sull'autenticazione del certificato, vedere:

• Autenticare le identità con certificati X.509
• Esercitazione: Creare e caricare certificati per i test

Esempi di codice

Per esempi funzionanti di autenticazione del certificato X.509 del dispositivo, vedere:

• Connettersi con il certificato X.509
• DeviceClientX509AuthenticationE2ETests
• Progetto guidato- Effettuare il provisioning di dispositivi IoT in modo sicuro e su larga scala con hub IoT servizio Device Provisioning

Eseguire l'autenticazione con una chiave di accesso condiviso

Chiamare CreateFromConnectionString per connettersi al dispositivo. Passare il stringa di connessione primario del dispositivo.

AMQP è il protocollo di trasporto predefinito.

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

Ottenere un URI di firma di accesso condiviso dall'hub IoT

Chiama GetFileUploadSasUriAsync per ottenere i dettagli di caricamento dei file. L'URI di firma di accesso condiviso viene usato nel passaggio successivo per caricare un file da un dispositivo nell'archivio 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();

Caricare un file in Archiviazione di Azure

Per caricare un file in Archiviazione di Azure:

1. Creare un oggetto blockBlobClient , passando un URI di caricamento di file.

2. Usare il metodo UploadAsync per caricare un file nell'archivio BLOB, passando l'URI di firma di accesso condiviso. Facoltativamente, è possibile aggiungere opzioni di caricamento BLOB e parametri del token di annullamento.

Il client BLOB di Azure usa sempre HTTPS come protocollo per caricare il file in Archiviazione di Azure.

In questo esempio BlockBlobClient viene passato l'URI di firma di accesso condiviso per creare un client BLOB in blocchi Archiviazione di Azure e carica il file:

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

Notificare all'hub IoT lo stato di caricamento del file

Usare CompleteFileUploadAsync per notificare all'hub IoT che il client del dispositivo ha completato il caricamento, passando un oggetto FileUploadCompletionNotification . Il IsSuccess flag indica se il caricamento è riuscito o meno. Dopo la notifica, l'hub IoT rilascia le risorse associate al caricamento (URI di firma di accesso condiviso).

Se le notifiche di caricamento dei file sono abilitate, l'hub IoT invia un messaggio di notifica di caricamento file ai servizi back-end configurati per la notifica di caricamento file.

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

Esempio di caricamento di file SDK

L'SDK include questo esempio di caricamento di file.

Ricevere una notifica di caricamento di file in un'applicazione back-end

È possibile creare un servizio back-end per ricevere messaggi di notifica di caricamento file dall'hub IoT.

La classe ServiceClient contiene metodi che i servizi possono usare per ricevere notifiche di caricamento file.

Aggiungere il pacchetto NuGet del servizio

Le applicazioni di servizio back-end richiedono il pacchetto NuGet Microsoft.Azure.Devices.

Connettersi all'hub IoT

È possibile connettere un servizio back-end a hub IoT usando i metodi seguenti:

• Criteri di accesso condiviso
• Microsoft Entra

Connettersi usando criteri di accesso condiviso

Connettere un'applicazione back-end a un dispositivo mediante CreateFromConnectionString. L'applicazione necessita dell'autorizzazione di connessione del servizio. Specificare questo criterio di accesso condiviso stringa di connessione come parametro a fromConnectionString. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

Ad esempio:

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

Connettersi con Microsoft Entra

Un'app back-end che usa Microsoft Entra deve eseguire correttamente l'autenticazione e ottenere le credenziali del token di sicurezza prima di connettersi a hub IoT. Questo token viene passato a un metodo di connessione hub IoT. Per informazioni generali sulla configurazione e l'uso di Microsoft Entra per hub IoT, vedere Controllare l'accesso alle hub IoT tramite Microsoft Entra ID.

Configurare l'app Microsoft Entra

È necessario configurare un'app Microsoft Entra configurata per le credenziali di autenticazione preferite. L'app contiene parametri come il segreto client usato dall'applicazione back-end per l'autenticazione. Le configurazioni di autenticazione delle app disponibili sono:

• Segreto client
• Certificate
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, hub IoT Collaboratore gemello è necessario per abilitare l'accesso in lettura e scrittura a un dispositivo e a moduli gemelli hub IoT. Per altre informazioni, vedere Gestire l'accesso alle hub IoT usando l'assegnazione di ruolo controllo degli accessi in base al ruolo di Azure.

Per altre informazioni sulla configurazione di un'app Microsoft Entra, vedere Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

Eseguire l'autenticazione con DefaultAzureCredential

Il modo più semplice per usare Microsoft Entra per autenticare un'applicazione back-end consiste nell'usare DefaultAzureCredential, ma è consigliabile usare un metodo diverso in un ambiente di produzione, incluso un oggetto specifico TokenCredential o ridotto.ChainedTokenCredential Per semplicità, questa sezione descrive l'autenticazione tramite DefaultAzureCredential e il segreto client. Per altre informazioni sui vantaggi e sui svantaggi dell'uso DefaultAzureCredentialdi , vedere Linee guida sull'utilizzo per DefaultAzureCredential.

DefaultAzureCredential supporta meccanismi di autenticazione diversi e determina il tipo di credenziale appropriato in base all'ambiente in cui è in esecuzione. Tenta di usare più tipi di credenziali in un ordine fino a quando non trova una credenziale funzionante.

Microsoft Entra richiede questi pacchetti NuGet e le istruzioni corrispondenti using :

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

In questo esempio, il segreto client di registrazione dell'app Microsoft Entra, l'ID client e l'ID tenant vengono aggiunti alle variabili di ambiente. Queste variabili di ambiente vengono usate da DefaultAzureCredential per autenticare l'applicazione. Il risultato di un'autenticazione di Microsoft Entra riuscita è una credenziale del token di sicurezza passata a un metodo di connessione hub IoT.

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

TokenCredential risultante può quindi essere passato a una connessione a un metodo di hub IoT per qualsiasi client SDK che accetta le credenziali di Microsoft Entra:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

In questo esempio viene passato a ServiceClient.Create per creare un oggetto connessione ServiceClient.TokenCredential

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

In questo esempio viene TokenCredential passato a RegistryManager.Create per creare un oggetto RegistryManager .

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

Esempio di codice

Per un esempio funzionante dell'autenticazione del servizio Microsoft Entra, vedere Esempio di autenticazione basata su ruoli.

Ricevere una notifica di caricamento file

Per ricevere la notifica di caricamento file:

1. Creare un cancellationToken.
2. Chiamare GetFileNotificationReceiver per creare un ricevitore di notifica.
3. Usare un ciclo con ReceiveAsync per attendere la notifica di caricamento del file.

Ad esempio:

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

Esempio di ricevitore di caricamento file SDK

L'SDK include questo esempio di ricevitore di caricamento di file.

Panoramica

Questa procedura contiene due sezioni:

• Caricare un file da un'applicazione del dispositivo
• Ricevere una notifica di caricamento di file in un'applicazione back-end

Caricare un file da un'applicazione del dispositivo

Questa sezione descrive come caricare un file da un dispositivo in un hub IoT usando la classe DeviceClient di Azure IoT SDK per Java.

Seguire questa procedura per caricare un file da un dispositivo all'hub IoT:

1. Connettere il dispositivo a hub IoT
2. Ottenere un URI di firma di accesso condiviso dall'hub IoT
3. Caricare il file in Archiviazione di Azure
4. Inviare una notifica sullo stato di caricamento dei file all'hub IoT

Connettere un dispositivo all'hub IoT

Un'app per dispositivi può eseguire l'autenticazione con hub IoT usando i metodi seguenti:

• Certificato X.509
• Chiave di accesso condiviso

Eseguire l'autenticazione con un certificato X.509

Per connettere un dispositivo a hub IoT usando un certificato X.509:

1. Compilare l'oggetto SSLContext usando buildSSLContext.
2. Aggiungere le SSLContext informazioni a un oggetto ClientOptions .
3. Chiamare DeviceClient usando le ClientOptions informazioni per creare la connessione da dispositivo a hub IoT.

Questo esempio mostra i valori dei parametri di input del certificato come variabili locali per maggiore chiarezza. In un sistema di produzione archiviare i parametri di input sensibili nelle variabili di ambiente o in un altro percorso di archiviazione più sicuro. Ad esempio, usare Environment.GetEnvironmentVariable("PUBLICKEY") per leggere una variabile di ambiente della stringa di certificato a chiave pubblica.

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

Per altre informazioni sull'autenticazione del certificato, vedere:

• Autenticare le identità con certificati X.509
• Esercitazione: Creare e caricare certificati per i test

Esempi di codice

Per esempi funzionanti di autenticazione del certificato X.509 del dispositivo, vedere:

• Esempio di invio-ricezione x509
• Invia evento x509

Eseguire l'autenticazione con una chiave di accesso condiviso

Le operazioni di caricamento dei file usano sempre HTTPS, ma DeviceClient può definire IotHubClientProtocol per altri servizi, ad esempio telemetria, metodo del dispositivo e dispositivo gemello.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

Creare un'istanza di DeviceClient per connettersi al dispositivo usando il stringa di connessione primario del dispositivo.

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

Ottenere un URI di firma di accesso condiviso dall'hub IoT

Chiamare getFileUploadSasUri per ottenere un oggetto FileUploadSasUriResponse .

FileUploadSasUriResponse include questi metodi e valori restituiti. I valori restituiti possono essere passati ai metodi di caricamento dei file.

Ad esempio:

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

Caricare il file in Archiviazione di Azure

Passare l'endpoint URI BLOB a BlobClientBuilder.buildclient per creare l'oggetto BlobClient .

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

Chiamare uploadFromFile per caricare il file nell'archivio BLOB.

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

Inviare una notifica sullo stato di caricamento dei file all'hub IoT

Inviare una notifica di stato di caricamento all'hub IoT dopo un tentativo di caricamento di file.

Creare un oggetto FileUploadCompletionNotification . Passare lo stato di esito positivo del caricamento del correlationId file e isSuccess . Passare un isSuccess true valore quando il caricamento del file ha avuto esito positivo, false quando non lo è.

FileUploadCompletionNotification deve essere chiamato anche quando il caricamento del file non riesce. L'hub IoT ha un numero fisso di URI di firma di accesso condiviso che può essere attivo in qualsiasi momento. Dopo aver completato il caricamento del file, è necessario liberare l'URI di firma di accesso condiviso in modo che possa essere generato un altro URI di firma di accesso condiviso. Se un URI di firma di accesso condiviso non viene liberato tramite questa API, alla fine viene liberato in base alla durata della configurazione degli URI di firma di accesso condiviso in un hub IoT.

In questo esempio viene passato uno stato di esito positivo.

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

Chiudere il client

Liberare le client risorse.

client.closeNow();

Creare un'applicazione back-end

Questa sezione descrive come ricevere una notifica di caricamento di file in un'applicazione back-end.

La classe ServiceClient contiene metodi che i servizi possono usare per ricevere notifiche di caricamento file.

Aggiungere le istruzioni di importazione

Aggiungere queste istruzioni import per utilizzare l'SDK di Azure IoT per Java e il gestore eccezioni.

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

Connettersi all'hub IoT

È possibile connettere un servizio back-end a hub IoT usando i metodi seguenti:

• Criteri di accesso condiviso
• Microsoft Entra

Connettersi usando criteri di accesso condiviso

Definire il protocollo di connessione

Utilizzare IotHubServiceClientProtocol per definire il protocollo a livello di applicazione che viene usato dal client del servizio per la comunicazione con un hub IoT.

IotHubServiceClientProtocol accetta solo l'enumerazione AMQPS o AMQPS_WS.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Creare l'oggetto ServiceClient

Creare l'oggetto ServiceClient, specificando la stringa di connessione e il protocollo dell'hub IoT.

Per caricare un file in un dispositivo in hub IoT, il servizio deve disporre dell'autorizzazione di connessione del servizio. Per impostazione predefinita, ogni hub IoT viene creato con un servizio con nome di criteri di accesso condiviso che concede tale autorizzazione.

Come parametro per il ServiceClient costruttore, specificare i criteri di accesso condiviso del servizio . Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

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

Aprire la connessione tra l'applicazione e l'hub IoT

Aprire la connessione del mittente AMQP. Questo metodo crea la connessione tra l'applicazione e l'hub IoT.

serviceClient.open();

Connettersi con Microsoft Entra

Un'app back-end che usa Microsoft Entra deve eseguire correttamente l'autenticazione e ottenere le credenziali del token di sicurezza prima di connettersi a hub IoT. Questo token viene passato a un metodo di connessione hub IoT. Per informazioni generali sulla configurazione e l'uso di Microsoft Entra per hub IoT, vedere Controllare l'accesso alle hub IoT tramite Microsoft Entra ID.

Per una panoramica dell'autenticazione di Java SDK, vedere Autenticazione di Azure con Java e Identità di Azure.

Per semplicità, questa sezione è incentrata sulla descrizione dell'autenticazione tramite il segreto client.

Configurare l'app Microsoft Entra

È necessario configurare un'app Microsoft Entra configurata per le credenziali di autenticazione preferite. L'app contiene parametri come il segreto client usato dall'applicazione back-end per l'autenticazione. Le configurazioni di autenticazione delle app disponibili sono:

• Segreto client
• Certificate
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, hub IoT Collaboratore gemello è necessario per abilitare l'accesso in lettura e scrittura a un dispositivo e a moduli gemelli hub IoT. Per altre informazioni, vedere Gestire l'accesso alle hub IoT usando l'assegnazione di ruolo controllo degli accessi in base al ruolo di Azure.

Per altre informazioni sulla configurazione di un'app Microsoft Entra, vedere Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

Eseguire l'autenticazione con DefaultAzureCredential

Il modo più semplice per usare Microsoft Entra per autenticare un'applicazione back-end consiste nell'usare DefaultAzureCredential, ma è consigliabile usare un metodo diverso in un ambiente di produzione, incluso un oggetto specifico TokenCredential o ridotto.ChainedTokenCredential Per altre informazioni sui vantaggi e sui svantaggi dell'uso DefaultAzureCredentialdi , vedere Catene di credenziali nella libreria client di Identità di Azure per Java.

DefaultAzureCredential supporta meccanismi di autenticazione diversi e determina il tipo di credenziale appropriato in base all'ambiente in cui è in esecuzione. Tenta di usare più tipi di credenziali in un ordine fino a quando non trova una credenziale funzionante.

È possibile autenticare le credenziali dell'app Microsoft Entra usando DefaultAzureCredentialBuilder. Salvare i parametri di connessione, ad esempio tenantID del segreto client, clientID e valori dei segreti client come variabili di ambiente. TokenCredential Una volta creato, passarlo a ServiceClient o ad altri generatori come parametro 'credential'.

In questo esempio tenta DefaultAzureCredentialBuilder di autenticare una connessione dall'elenco descritto in DefaultAzureCredential. Il risultato di un'autenticazione riuscita di Microsoft Entra è una credenziale del token di sicurezza passata a un costruttore, ad esempio ServiceClient.

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

Eseguire l'autenticazione con ClientSecretCredentialBuilder

È possibile usare ClientSecretCredentialBuilder per creare credenziali usando le informazioni sul segreto client. In caso di esito positivo, questo metodo restituisce un tokenCredential che può essere passato a ServiceClient o a un altro generatore come parametro 'credential'.

In questo esempio i valori del segreto client di registrazione dell'app Microsoft Entra, DELL'ID client e dell'ID tenant sono stati aggiunti alle variabili di ambiente. Queste variabili di ambiente vengono usate da ClientSecretCredentialBuilder per compilare le credenziali.

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

Altre classi di autenticazione

Java SDK include anche queste classi che autenticano un'app back-end con Microsoft Entra:

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

Esempi di codice

Per esempi di utilizzo dell'autenticazione del servizio Microsoft Entra, vedere Esempio di autenticazione basata sui ruoli.

Verificare lo stato di caricamento dei file

Per verificare lo stato di caricamento dei file:

1. Creare un oggetto getFileUploadNotificationReceiver .
2. Usare open per connettersi all'hub IoT.
3. Chiamare la ricezione per verificare lo stato di caricamento del file. Questo metodo restituisce un oggetto fileUploadNotification . Se viene ricevuto un avviso di caricamento, è possibile visualizzare i campi di stato di caricamento usando i metodi fileUploadNotification .

Ad esempio:

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

Esempi di caricamento di file SDK

Sono disponibili due esempi di caricamento di file Java.

Installare i pacchetti

Prima di chiamare qualsiasi codice correlato, è necessario installare la libreria azure-iot-device.

pip install azure-iot-device

Il pacchetto azure.storage.blob viene usato per eseguire il caricamento del file.

pip install azure.storage.blob

Caricare un file da un'applicazione del dispositivo

Questa sezione descrive come caricare un file da un dispositivo a un hub IoT usando la classe IoTHubDeviceClient di Azure IoT SDK per Python.

Importare le librerie

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

Connettere un dispositivo all'hub IoT

Un'app per dispositivi può eseguire l'autenticazione con hub IoT usando i metodi seguenti:

• Certificato X.509
• Chiave di accesso condiviso

Eseguire l'autenticazione con un certificato X.509

Per connettere un dispositivo a hub IoT usando un certificato X.509:

1. Usare create_from_x509_certificate per aggiungere i parametri del certificato X.509
2. Chiamare la connessione per connettere il client del dispositivo

Questo esempio mostra i valori dei parametri di input del certificato come variabili locali per maggiore chiarezza. In un sistema di produzione archiviare i parametri di input sensibili nelle variabili di ambiente o in un altro percorso di archiviazione più sicuro. Ad esempio, usare os.getenv("HOSTNAME") per leggere la variabile di ambiente del nome host.

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

Per altre informazioni sull'autenticazione del certificato, vedere:

• Autenticare le identità con certificati X.509
• Esercitazione: Creare e caricare certificati per i test

Esempi di codice

Per esempi di utilizzo dell'autenticazione del certificato X.509 del dispositivo, vedere gli esempi i cui nomi di file terminano in x509 negli scenari dell'hub asincrono.

Eseguire l'autenticazione con una chiave di accesso condiviso

Per connettere un dispositivo a hub IoT:

1. Chiamare create_from_connection_string per aggiungere il stringa di connessione primario del dispositivo.
2. Chiamare connect per connettere il client del dispositivo.

Ad esempio:

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

Ottenere informazioni sull'archiviazione BLOB

Chiamare get_storage_info_for_blob per ottenere informazioni da un hub IoT su un account Archiviazione di Azure collegato. Queste informazioni includono il nome host, il nome del contenitore, il nome del BLOB e un token di firma di accesso condiviso. Il get_storage_info_for_blob metodo restituisce anche un correlation_idoggetto , utilizzato nel notify_blob_upload_status metodo . correlation_id è hub IoT modo di contrassegnare il BLOB su cui si sta lavorando.

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

Caricare un file nell'archiviazione BLOB

Per caricare un file nell'archivio BLOB:

1. Usare from_blob_url per creare un oggetto BlobClient da un URL del BLOB.
2. Chiamare upload_blob per caricare il file nell'archivio BLOB.

In questo esempio viene analizzata la blob_info struttura per creare un URL usato per inizializzare un BLOBClient. Chiama quindi upload_blob per caricare il file nell'archiviazione 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)

Notifica allo stato di caricamento dell'hub IoT

Usare notify_blob_upload_status per notificare all'hub IoT lo stato dell'operazione di archiviazione BLOB. Passare l'oggetto correlation_id ottenuto dal get_storage_info_for_blob metodo . Viene correlation_id usato dall'hub IoT per notificare a qualsiasi servizio che potrebbe essere in ascolto di una notifica relativa allo stato dell'attività di caricamento file.

Questo esempio notifica all'hub IoT di un caricamento di file riuscito:

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

Arrestare il client del dispositivo

Arrestare il client. Una volta chiamato questo metodo, qualsiasi tentativo di chiamate client comporta la generazione di un clientError .

device_client.shutdown()

Esempi di caricamento di file SDK

L'SDK include due esempi di caricamento di file:

• Caricare nel BLOB
• Caricare nel BLOB usando un certificato X.509

Panoramica

Questo articolo descrive come usare Azure IoT SDK per Node.js per creare un'app per dispositivi per caricare un file e un'applicazione del servizio back-end riceve una notifica di caricamento file.

Creare un'applicazione per dispositivi

Questa sezione descrive come caricare un file da un dispositivo in un hub IoT usando il pacchetto azure-iot-device in Azure IoT SDK per Node.js.

Installare i pacchetti SDK

Eseguire questo comando per installare azure-iot-device device SDK, azure-iot-device-mqtt e i pacchetti @azure/storage-blob nel computer di sviluppo:

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

Il pacchetto azure-iot-device contiene oggetti che si interfacciano con i dispositivi IoT.

Seguire questa procedura per caricare un file da un dispositivo all'hub IoT:

1. Connettere il dispositivo a hub IoT
2. Ottenere un token di firma di accesso condiviso (SAS) BLOB da hub IoT
3. Caricare il file in Archiviazione di Azure
4. Inviare una notifica sullo stato di caricamento dei file all'hub IoT

Creare moduli

Creare moduli client, protocollo, errori e percorso usando i pacchetti installati.

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

Connettere un dispositivo all'hub IoT

Un'app per dispositivi può eseguire l'autenticazione con hub IoT usando i metodi seguenti:

• Certificato X.509
• Chiave di accesso condiviso

Eseguire l'autenticazione con un certificato X.509

Il certificato X.509 è collegato al trasporto di connessione da dispositivo a hub IoT.

Per configurare una connessione da dispositivo a hub IoT usando un certificato X.509:

1. Chiamare daConnectionString per aggiungere il dispositivo stringa di connessione e il tipo di trasporto. Aggiungere x509=true al dispositivo stringa di connessione per indicare che un certificato viene aggiunto a DeviceClientOptions. Ad esempio: HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true.
2. Configurare una variabile JSON con i dettagli del certificato e passarla a DeviceClientOptions.
3. Chiamare setOptions per aggiungere un certificato e una chiave X.509 (e, facoltativamente, passphrase) al trasporto client.
4. Chiamare open per aprire la connessione dal dispositivo per hub IoT.

Questo esempio mostra le informazioni di configurazione del certificato all'interno di una variabile JSON. La configurazione options di certificazione viene passata a setOptions e la connessione viene aperta usando open.

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

Per altre informazioni sull'autenticazione del certificato, vedere:

• Autenticare le identità con certificati X.509
• Creare e caricare certificati per i test

Esempio di codice

Per un esempio funzionante dell'autenticazione del certificato X.509 del dispositivo, vedere Dispositivo di esempio semplice X.509.

Eseguire l'autenticazione con una chiave di accesso condiviso

Scegliere un protocollo di trasporto

L'oggetto Client supporta i protocolli seguenti:

• Amqp
• Http: quando si usa Http, l'istanza Client verifica con scarsa frequenza la presenza di messaggi provenienti dall'hub IoT (almeno ogni 25 minuti).
• Mqtt
• MqttWs
• AmqpWs

Installare i protocolli di trasporto necessari nel computer di sviluppo.

Ad esempio, questo comando installa il protocollo Amqp:

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

Per altre informazioni sulle differenze tra il supporto di MQTT, AMQP e HTTPS, vedere Linee guida per le comunicazioni da cloud a dispositivo e Scegliere un protocollo di comunicazione.

Creare un oggetto client

Creare un Client oggetto usando il pacchetto installato.

Ad esempio:

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

Creare un oggetto protocollo

Creare un Protocol oggetto usando un pacchetto di trasporto installato.

In questo esempio viene assegnato il protocollo AMQP:

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

Aggiungere la stringa di connessione del dispositivo e il protocollo di trasporto

Chiamare fromConnectionString per specificare i parametri di connessione del dispositivo:

• connStr: stringa di connessione del dispositivo.
• transportCtor: protocollo di trasporto.

Questo esempio usa il protocollo di trasporto Amqp:

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

Aprire la connessione all'hub IoT

Usare il metodo open per aprire la connessione tra un dispositivo IoT e hub IoT.

Ad esempio:

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

Ottenere un token di firma di accesso condiviso dall'hub IoT

Usare getBlobSharedAccessSignature per ottenere il token di firma di accesso condiviso dell'account di archiviazione collegato dall'hub IoT.

Ad esempio:

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

Caricare il file nell'hub IoT

Per caricare un file da un dispositivo all'hub IoT:

1. Creare una pipeline di flusso
2. Costruire l'URL del BLOB
3. Creare un blockBlobClient per il caricamento di file nell'archiviazione BLOB
4. Chiamare uploadFile per caricare il file nell'archivio BLOB
5. Chiamare notifyBlobUploadStatus per notificare all'hub IoT che il caricamento ha avuto esito positivo o negativo

Ad esempio:

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

Caricare il file locale nell'archivio BLOB

È possibile caricare un file locale nell'archivio BLOB da un computer

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

Esempio di caricamento di file SDK

L'SDK include un esempio avanzato di caricamento nel BLOB.

Creare un'applicazione back-end

Questa sezione descrive come ricevere notifiche di caricamento di file in un'applicazione back-end.

La classe ServiceClient contiene metodi che i servizi possono usare per ricevere notifiche di caricamento file.

Installare il pacchetto SDK del servizio

Eseguire questo comando per installare azure-iothub nel computer di sviluppo:

npm install azure-iothub --save

Connettersi all'hub IoT

È possibile connettere un servizio back-end a hub IoT usando i metodi seguenti:

• Criteri di accesso condiviso
• Microsoft Entra

Connettersi usando criteri di accesso condiviso

Usare fromConnectionString per connettersi all'hub IoT.

Per caricare un file da un dispositivo, il servizio deve disporre dell'autorizzazione di connessione del servizio. Per impostazione predefinita, ogni hub IoT viene creato con un servizio con nome di criteri di accesso condiviso che concede tale autorizzazione.

Come parametro di CreateFromConnectionString, specificare i criteri di accesso condiviso del servizio stringa di connessione. Per altre informazioni sui criteri di accesso condiviso, vedere Controllare l'accesso alle hub IoT con firme di accesso condiviso.

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

Connettersi con Microsoft Entra

Un'app back-end che usa Microsoft Entra deve eseguire correttamente l'autenticazione e ottenere le credenziali del token di sicurezza prima di connettersi a hub IoT. Questo token viene passato a un metodo di connessione hub IoT. Per informazioni generali sulla configurazione e l'uso di Microsoft Entra per hub IoT, vedere Controllare l'accesso alle hub IoT tramite Microsoft Entra ID.

Per una panoramica dell'autenticazione Node.js SDK, vedere:

• Introduzione all'autenticazione utente in Azure
• Libreria client di Identità di Azure per JavaScript

Configurare l'app Microsoft Entra

È necessario configurare un'app Microsoft Entra configurata per le credenziali di autenticazione preferite. L'app contiene parametri come il segreto client usato dall'applicazione back-end per l'autenticazione. Le configurazioni di autenticazione delle app disponibili sono:

• Segreto client
• Certificate
• Credenziali di identità federate

Le app Microsoft Entra possono richiedere autorizzazioni di ruolo specifiche a seconda delle operazioni eseguite. Ad esempio, hub IoT Collaboratore gemello è necessario per abilitare l'accesso in lettura e scrittura a un dispositivo e a moduli gemelli hub IoT. Per altre informazioni, vedere Gestire l'accesso alle hub IoT usando l'assegnazione di ruolo controllo degli accessi in base al ruolo di Azure.

Per altre informazioni sulla configurazione di un'app Microsoft Entra, vedere Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

Eseguire l'autenticazione con DefaultAzureCredential

Il modo più semplice per usare Microsoft Entra per autenticare un'applicazione back-end consiste nell'usare DefaultAzureCredential, ma è consigliabile usare un metodo diverso in un ambiente di produzione, incluso un oggetto specifico TokenCredential o ridotto.ChainedTokenCredential Per semplicità, questa sezione descrive l'autenticazione tramite DefaultAzureCredential e il segreto client. Per altre informazioni sui vantaggi e sui svantaggi dell'uso DefaultAzureCredentialdi , vedere Catene di credenziali nella libreria client di Identità di Azure per JavaScript

DefaultAzureCredential supporta meccanismi di autenticazione diversi e determina il tipo di credenziale appropriato in base all'ambiente in cui è in esecuzione. Tenta di usare più tipi di credenziali in un ordine fino a quando non trova una credenziale funzionante.

Microsoft Entra richiede questo pacchetto:

npm install --save @azure/identity

In questo esempio, il segreto client di registrazione dell'app Microsoft Entra, l'ID client e l'ID tenant sono stati aggiunti alle variabili di ambiente. Queste variabili di ambiente vengono usate da DefaultAzureCredential per autenticare l'applicazione. Il risultato di un'autenticazione di Microsoft Entra riuscita è una credenziale del token di sicurezza passata a un metodo di connessione hub IoT.

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

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

Il token delle credenziali risultante può quindi essere passato a fromTokenCredential per connettersi a hub IoT per qualsiasi client SDK che accetta le credenziali di Microsoft Entra:

• Registro
• Client
• JobClient

fromTokenCredential richiede due parametri:

• URL del servizio di Azure: l'URL del servizio di Azure deve essere nel formato {Your Entra domain URL}.azure-devices.net senza un https:// prefisso. Ad esempio: MyAzureDomain.azure-devices.net.
• Token delle credenziali di Azure

In questo esempio, le credenziali di Azure vengono ottenute usando DefaultAzureCredential. L'URL e le credenziali del dominio di Azure vengono quindi forniti per Registry.fromTokenCredential creare la connessione a hub IoT.

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

Esempi di codice

Per esempi di utilizzo dell'autenticazione del servizio Microsoft Entra, vedere Esempi di identità di Azure.

Creare un ricevitore di callback di notifica di caricamento file

Per creare un ricevitore di callback di notifica di caricamento file:

1. Chiamare getFileNotificationReceiver. Specificare il nome di un metodo di callback di caricamento file chiamato quando vengono ricevuti i messaggi di notifica.
2. Elaborare le notifiche di caricamento dei file nel metodo di callback.

In questo esempio viene configurato un receiveFileUploadNotification ricevitore di callback di notifica. Il ricevitore interpreta le informazioni sullo stato di caricamento del file e stampa un messaggio di stato nella 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');
      }
    });
  });
}

Esempio di notifica di caricamento di file SDK

L'SDK include un esempio di caricamento di file.