Hochladen von Dateien von einem Gerät in die Cloud mit Azure IoT Hub

Artikel
12/20/2024

Dieser Artikel demonstriert Folgendes:

Verwenden Sie die Dateiuploadfunktionen von IoT Hub, um eine Datei mithilfe eines Azure IoT-Geräts und von Dienst-SDKs in Azure Blob Storage hochzuladen.
Benachrichtigen Sie IoT Hub, dass die Datei erfolgreich hochgeladen wurde, und erstellen Sie mithilfe der Azure IoT-Dienst-SDKs einen Back-End-Dienst, um Dateiuploadbenachrichtigungen von IoT Hub zu empfangen.

In einigen Szenarien können Sie nicht einfach die Daten, die Ihre Geräte senden, den relativ kleinen Gerät-zu-Cloud-Nachrichten zuordnen, die IoT Hub akzeptiert. Mit den Dateiuploadfunktionen in IoT Hub können Sie umfangreiche oder komplexe Daten in die Cloud verschieben. Zum Beispiel:

Videos
Große Dateien, die Bilder enthalten
Vibrationsdaten, die mit hoher Häufigkeit als Stichproben erfasst werden
Eine Form vorverarbeiteter Daten

Diese Dateien werden normalerweise als Batch in der Cloud mit Tools wie Azure Data Factory oder dem Hadoop-Stapel verarbeitet. Wenn Sie Dateien von einem Gerät hochladen müssen, können Sie weiterhin die Sicherheit und Zuverlässigkeit des IoT Hub nutzen. In diesem Artikel erfahren Sie, welche Schritte erforderlich sind.

Dieser Artikel soll die ausführbaren SDK-Beispiele ergänzen, auf die in diesem Artikel verwiesen wird.

Weitere Informationen finden Sie unter:

Wichtig

Die Funktion zum Hochladen von Dateien auf Geräten, die die Authentifizierung der X.509-Zertifizierungsstelle verwenden, befindet sich in der öffentlichen Vorschau, und der Vorschaumodus muss aktiviert werden. Sie ist allgemein verfügbar auf Geräten, die die Authentifizierung per X.509-Fingerabdruck oder den X.509-Zertifikatnachweis mit dem Azure Device Provisioning Service verwenden. Weitere Informationen zur X.509-Authentifizierung mit IoT Hub finden Sie unter Unterstützte X.509-Zertifikate.

Voraussetzungen

Einen IoT-Hub. Für einige SDK-Aufrufe ist die primäre IoT Hub-Verbindungszeichenfolge erforderlich. Notieren Sie sich daher die Verbindungszeichenfolge.
Ein registriertes Gerät. Für einige SDK-Aufrufe ist die primäre Geräteverbindungszeichenfolge erforderlich. Notieren Sie sich daher die Verbindungszeichenfolge.
IoT Hub-Berechtigung Dienstverbindung: Damit Ihr Back-End-Dienst Dateiuploadbenachrichtigungen empfangen kann, muss er über die Berechtigung Dienstverbindung verfügen. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit einer IoT Hub-Instanz.
Konfigurieren Sie den Dateiupload in Ihrem IoT-Hub, indem Sie ein Azure Storage-Konto und einen Azure Blob Storage-Container verknüpfen. Verwenden Sie zum Konfigurieren das Azure-Portal, die Azure CLI oder Azure PowerShell.

Übersicht

Diese Anleitung enthält zwei Abschnitte:

Hochladen einer Datei von einer Geräteanwendung
Empfangen einer Dateiuploadbenachrichtigung in einer Back-End-Anwendung

Hochladen einer Datei von einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Sie mithilfe der Klasse DeviceClient im Azure IoT SDK für .NET eine Datei von einem Gerät in einen IoT-Hub hochladen.

Gehen Sie wie folgt vor, um eine Datei von einem Gerät in einen IoT-Hub hochzuladen:

Herstellen einer Verbindung mit dem IoT-Hub
Abrufen eines SAS-URI vom IoT-Hub
Hochladen der Datei in Azure Storage
Benachrichtigen des IoT-Hubs über den Dateiuploadstatus

Verbinden eines Geräts mit IoT Hub

Eine Geräte-App kann sich mit den folgenden Methoden bei IoT Hub authentifizieren:

X.509-Zertifikat
Schlüssel für den gemeinsamen Zugriff

Authentifizierung mit einem X.509-Zertifikat

So verbinden Sie ein Gerät mithilfe eines X.509-Zertifikats mit IoT Hub

Verwenden Sie DeviceAuthenticationWithX509Certificate, um ein Objekt zu erstellen, das Geräte- und Zertifikatinformationen enthält. DeviceAuthenticationWithX509Certificate wird als zweiter Parameter an DeviceClient.Create übergeben (Schritt 2).
Verwenden Sie DeviceClient.Create, um das Gerät mithilfe eines X.509-Zertifikats mit IoT Hub zu verbinden.

In diesem Beispiel werden die Geräte- und Zertifikatinformationen im auth DeviceAuthenticationWithX509Certificate-Objekt ausgefüllt, das an DeviceClient.Create übergeben wird.

In diesem Beispiel werden Eingabeparameterwerte für das Zertifikat zum besseren Verständnis als lokale Variablen dargestellt. Speichern Sie in einem Produktionssystem vertrauliche Eingabeparameter in Umgebungsvariablen oder an einem anderen sichereren Speicherort. Verwenden Sie z. B. Environment.GetEnvironmentVariable("HOSTNAME") zum Lesen der Umgebungsvariable mit dem Hostnamen.

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

Weitere Informationen zur Zertifikatauthentifizierung finden Sie unter:

Codebeispiele

Funktionierende Beispiele der Authentifizierung mit X.509-Zertifikaten für Geräte finden Sie unter:

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Rufen Sie CreateFromConnectionString- auf, um eine Verbindung mit dem Gerät herzustellen. Übergeben Sie die primäre Verbindungszeichenfolge für das Gerät.

AMQP ist das Standardtransportprotokoll.

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

Abrufen eines SAS-URI vom IoT-Hub

Rufen Sie GetFileUploadSasUriAsync- auf, um Dateiuploaddetails abzurufen. Der SAS-URI wird im nächsten Schritt verwendet, um eine Datei von einem Gerät in Blob Storage hochzuladen.

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

Hochladen einer Datei in Azure Storage

So laden Sie eine Datei in Azure Storage hoch

Erstellen Sie ein blockBlobClient-Objekt, und übergeben Sie einen Dateiupload-URI.
Verwenden Sie die Methode UploadAsync, um eine Datei in Blob Storage hochzuladen und den SAS-URI zu übergeben. Optional können Sie Blobuploadoptionen und Abbruchtokenparameter hinzufügen.

Der Azure-Blobclient verwendet immer HTTPS als Protokoll zum Hochladen der Datei in Azure Storage.

In diesem Beispiel wird der SAS-URI an BlockBlobClient übergeben, um einen Azure Storage-Blockblobclient zu erstellen, und die Datei hochgeladen:

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

Benachrichtigen des IoT-Hubs über den Dateiuploadstatus

Verwenden Sie CompleteFileUploadAsync, um den IoT-Hub zu benachrichtigen, dass der Geräteclient den Upload abgeschlossen hat, und übergeben Sie ein FileUploadCompletionNotification-Objekt. Das Flag IsSuccess gibt an, ob der Upload erfolgreich war. Nach der Benachrichtigung gibt der IoT-Hub Ressourcen frei, die dem Upload zugeordnet sind (SAS-URI).

Wenn Dateiuploadbenachrichtigungen aktiviert sind, sendet der IoT-Hub eine Benachrichtigung über den Dateiupload an Back-End-Dienste, die für die Dateiuploadbenachrichtigung konfiguriert sind.

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

SDK-Dateiuploadbeispiel

Das SDK enthält dieses Dateiuploadbeispiel.

Empfangen einer Dateiuploadbenachrichtigung in einer Back-End-Anwendung

Sie können einen Back-End-Dienst zum Empfangen von Dateiuploadbenachrichtigungen aus dem IoT-Hub erstellen.

Die ServiceClient-Klasse enthält Methoden, mit denen Dienste Dateiuploadbenachrichtigungen empfangen können.

Hinzufügen des NuGet-Dienstpakets

Back-End-Dienstanwendungen erfordern das NuGet-Paket Microsoft.Azure.Devices.

Herstellen einer Verbindung mit dem IoT-Hub

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

SAS-Richtlinie
Microsoft Entra

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verbinden Sie eine Back-End-Anwendung mit einem Gerät mithilfe von CreateFromConnectionString. Ihre Anwendung benötigt die Berechtigung Dienst verbinden. Geben Sie diese SAS-Richtlinie Verbindungszeichenfolge als Parameter an fromConnectionString. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

Zum Beispiel:

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

Verbinden mit Microsoft Entra

Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.

Konfigurieren der Microsoft Entra-App

Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:

Geheimer Clientschlüssel
Zertifikat
Anmeldeinformationen für Verbundidentität

Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential und den geheimen Clientschlüssel. Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential finden Sie unter Verwendungsleitfaden für DefaultAzureCredential.

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Es versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis sie eine funktionierende Anmeldeinformation findet.

Microsoft Entra erfordert diese NuGet-Pakete und entsprechende using Anweisungen:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

In diesem Beispiel werden Clientschlüssel, Client-ID und Mandanten-ID der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.

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

Das resultierende TokenCredential kann dann an eine Verbindung mit der IoT Hub-Methode für jeden SDK-Client übergeben werden, der Microsoft Entra-Anmeldeinformationen akzeptiert:

In diesem Beispiel wird TokenCredential an ServiceClient.Create übergeben, um ein ServiceClient-Verbindungsobjekt zu erstellen.

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

In diesem Beispiel wird TokenCredential an RegistryManager.Create übergeben, um ein RegistryManager-Objekt zu erstellen.

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

Codebeispiel

Ein funktionierendes Beispiel für die Microsoft Entra-Dienstauthentifizierung finden Sie im Beispiel für die rollenbasierte Authentifizierung.

Empfangen von Dateiuploadbenachrichtigungen

So empfangen Sie Dateiuploadbenachrichtigungen

Erstellen Sie ein Abbruchtoken (CancellationToken).
Rufen Sie GetFileNotificationReceiver auf, um einen Benachrichtigungsempfänger zu erstellen.
Verwenden Sie eine Schleife mit ReceiveAsync, um auf die Dateiuploadbenachrichtigung zu warten.

Zum Beispiel:

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

Beispiel für den Empfang eines SDK-Dateiuploads

Das SDK enthält dieses Beispiel für den Empfang eines Dateiuploads.

Übersicht

Diese Anleitung enthält zwei Abschnitte:

Hochladen einer Datei von einer Geräteanwendung
Empfangen einer Dateiuploadbenachrichtigung in einer Back-End-Anwendung

Hochladen einer Datei von einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Sie mithilfe der Klasse DeviceClient im Azure IoT SDK für Java eine Datei von einem Gerät in einen IoT-Hub hochladen.

Gehen Sie wie folgt vor, um eine Datei von einem Gerät in einen IoT-Hub hochzuladen:

Verbinden des Geräts mit IoT Hub
Abrufen eines SAS-URI vom IoT-Hub
Hochladen der Datei in Azure Storage
Senden einer Benachrichtigung über den Dateiuploadstatus an den IoT-Hub

Verbinden eines Geräts mit IoT Hub

Eine Geräte-App kann sich mit den folgenden Methoden bei IoT Hub authentifizieren:

X.509-Zertifikat
Schlüssel für den gemeinsamen Zugriff

Authentifizierung mit einem X.509-Zertifikat

So verbinden Sie ein Gerät mithilfe eines X.509-Zertifikats mit IoT Hub

Erstellen Sie das SSLContext-Objekt mit buildSSLContext.
Fügen Sie die SSLContext-Informationen einem ClientOptions-Objekt hinzu.
Rufen Sie DeviceClient mithilfe der ClientOptions-Informationen auf, um die Verbindung zwischen Gerät und IoT Hub zu erstellen.

In diesem Beispiel werden Eingabeparameterwerte für das Zertifikat zum besseren Verständnis als lokale Variablen dargestellt. Speichern Sie in einem Produktionssystem vertrauliche Eingabeparameter in Umgebungsvariablen oder an einem anderen sichereren Speicherort. Verwenden Sie z. B. Environment.GetEnvironmentVariable("PUBLICKEY") zum Lesen der Umgebungsvariable mit der Zeichenfolge für das Zertifikat mit öffentlichem Schlüssel.

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

Weitere Informationen zur Zertifikatauthentifizierung finden Sie unter:

Codebeispiele

Funktionierende Beispiele der Authentifizierung mit X.509-Zertifikaten für Geräte finden Sie unter:

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Dateiuploadvorgänge verwende immer HTTPS, aber DeviceClient kann IotHubClientProtocol für andere Dienste wie Telemetrie, Gerätemethode und Gerätezwilling definieren.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

Instanziieren Sie DeviceClient, um unter Verwendung der primären Verbindungszeichenfolge des Geräts eine Verbindung mit dem Gerät herzustellen.

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

Abrufen eines SAS-URI vom IoT-Hub

Rufen Sie getFileUploadSasUri auf, um ein FileUploadSasUriResponse-Objekt abzurufen.

FileUploadSasUriResponse enthält diese Methoden und Rückgabewerte. Die Rückgabewerte können an Dateiuploadmethoden übergeben werden.

Methode	Rückgabewert
`getCorrelationId()`	Korrelations-ID
`getContainerName()`	Containername
`getBlobName()`	Blobname
`getBlobUri()`	Blob-URI

Zum Beispiel:

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

Hochladen der Datei in Azure Storage

Übergeben Sie den Blob-URI-Endpunkt an BlobClientBuilder.buildclient, um das BlobClient-Objekt zu erstellen.

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

Rufen Sie uploadFromFile auf, um die Datei in Blob Storage hochzuladen.

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

Senden einer Benachrichtigung über den Dateiuploadstatus an den IoT-Hub

Senden Sie nach einem Dateiuploadversuch eine Uploadstatusbenachrichtigung an den IoT-Hub.

Erstellen Sie ein FileUploadCompletionNotification-Objekt. Übergeben Sie die Korrelations-ID (correlationId) und den Erfolgsstatus für den Dateiupload (isSuccess). Übergeben Sie den Wert true für isSuccess, wenn der Dateiupload erfolgreich war, und false, wenn er nicht erfolgreich war.

FileUploadCompletionNotification muss auch aufgerufen werden, wenn der Dateiupload nicht erfolgreich war. Der IoT-Hub verfügt über eine feste Anzahl von SAS-URIs, die zu einem bestimmten Zeitpunkt aktiv sein dürfen. Nachdem das Hochladen der Datei abgeschlossen ist, sollten Sie Ihren SAS-URI freigeben, damit ein weiterer SAS-URI generiert werden kann. Wenn ein SAS-URI nicht über diese API freigegeben wird, gibt er sich schließlich basierend auf der Dauer selbst frei, die für seine aktive Phase auf einem IoT-Hub konfiguriert wurde.

In diesem Beispiel wird der Status „Erfolgreich“ übergeben.

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

Schließen des Clients

Geben Sie die client-Ressourcen frei.

client.closeNow();

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie Sie eine Dateiuploadbenachrichtigung in einer Back-End-Anwendung empfangen.

Die ServiceClient-Klasse enthält Methoden, mit denen Dienste Dateiuploadbenachrichtigungen empfangen können.

Hinzufügen von Importanweisungen

Fügen Sie diese import-Anweisungen hinzu, um das Azure IoT Java SDK und den Ausnahmehandler zu verwenden.

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

Herstellen der Verbindung mit dem IoT Hub

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

SAS-Richtlinie
Microsoft Entra

Wichtig

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Definieren des Verbindungsprotokolls

Verwenden Sie IotHubServiceClientProtocol, um das vom Dienstclient für die Kommunikation mit IoT Hub verwendete Anwendungsschichtprotokoll zu definieren.

IotHubServiceClientProtocol akzeptiert nur die AMQPS- oder AMQPS_WS-Enumeration.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Erstellen des ServiceClient-Objekts

Erstellen Sie das ServiceClient-Objekt, und stellen Sie die IoT Hub-Verbindungszeichenfolge und das Protokoll bereit.

Um eine Datei von einem Gerät in IoT Hub hochzuladen, benötigt Ihr Dienst die Berechtigung Dienst verbinden. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt.

Geben Sie als Parameter für den ServiceClient-Konstruktor die SAS-Richtlinie für den Dienst an. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

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

Öffnen der Verbindung zwischen Anwendung und IoT Hub

Öffnen Sie die AMQP-Absenderverbindung. Mit dieser Methode wird die Verbindung zwischen der Anwendung und IoT Hub hergestellt.

serviceClient.open();

Verbinden mit Microsoft Entra

Eine Übersicht über die Java SDK-Authentifizierung finden Sie unter Azure-Authentifizierung mit Java und Azure Identität.

Der Einfachheit halber konzentriert sich dieser Abschnitt auf die Beschreibung der Authentifizierung mithilfe des geheimen Clientschlüssels.

Konfigurieren der Microsoft Entra-App

Geheimer Clientschlüssel
Zertifikat
Anmeldeinformationen für Verbundidentität

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Weitere Informationen zu den Vor- und Nachteilen der Verwendung DefaultAzureCredentialfinden Sie unter Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für Java.

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Er versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis er eine funktionierende Anmeldeinformation findet.

Sie können Microsoft Entra-App-Anmeldeinformationen mithilfe von DefaultAzureCredentialBuilderauthentifizieren. Speichern Sie Verbindungsparameter wie geheime Clientschlüssel-Mandanten-ID, Client-ID und geheime Clientschlüsselwerte als Umgebungsvariablen. Nachdem die TokenCredential Datei erstellt wurde, übergeben Sie sie an ServiceClient oder einen anderen Generator als Parameter Anmeldeinformationen.

In diesem Beispiel versucht DefaultAzureCredentialBuilder eine Verbindung aus der in DefaultAzureCredential beschriebenen Liste zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstokenanmeldeinformation, die an einen Konstruktor wie ServiceClientübergeben wird.

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

Authentifizieren mit ClientSecretCredentialBuilder

Sie können ClientSecretCredentialBuilder verwenden, um eine Anmeldeinformation mithilfe von geheimen Clientinformationen zu erstellen. Bei erfolgreicher Ausführung gibt die Methode eine TokenCredential zurück, die als Parameter "Anmeldeinformationen" an ServiceClient oder einen anderen Generator übergeben werden kann.

In diesem Beispiel wurden Clientschlüssel, Client-ID und Mandanten-ID-Werte der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von ClientSecretCredentialBuilderverwendet, um die Anmeldeinformationen zu erstellen.

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

Andere Authentifizierungsklassen

Das Java SDK enthält auch diese Klassen, die eine Back-End-App mit Microsoft Entra authentifizieren:

Codebeispiele

Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie im Beispielfür die rollenbasierte Authentifizierung.

Überprüfen des Dateiuploadstatus

So überprüfen Sie den Status für den Dateiupload

Erstellen Sie ein getFileUploadNotificationReceiver-Objekt.
Stellen Sie mithilfe von open eine Verbindung mit dem IoT-Hub her.
Rufen Sie receive auf, um den Dateiuploadstatus zu überprüfen. Diese Methode gibt ein fileUploadNotification-Objekt zurück. Wenn eine Uploadbenachrichtigung empfangen wird, können Sie die Statusfelder für den Upload mithilfe von fileUploadNotification-Methoden anzeigen.

Zum Beispiel:

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

SDK-Dateiuploadbeispiele

Es gibt zwei Beispiele für den Java-Dateiupload.

Installieren von Paketen

Vor dem Aufrufen des zugehörigen Codes muss die Bibliothek „azure-iot-device“ installiert werden.

pip install azure-iot-device

Das Paket azure.storage.blob wird verwendet, um den Dateiupload durchzuführen.

pip install azure.storage.blob

Hochladen einer Datei von einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Sie mithilfe der Klasse IoTHubDeviceClient im Azure IoT SDK für Python eine Datei von einem Gerät in einen IoT-Hub hochladen.

Importbibliotheken

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

Verbinden eines Geräts mit IoT Hub

Eine Geräte-App kann sich mit den folgenden Methoden bei IoT Hub authentifizieren:

X.509-Zertifikat
Schlüssel für den gemeinsamen Zugriff

Authentifizierung mit einem X.509-Zertifikat

So verbinden Sie ein Gerät mithilfe eines X.509-Zertifikats mit IoT Hub

Verwenden von create_from_x509_certificate zum Hinzufügen der X.509-Zertifikatparameter
Aufrufen von connect zum Herstellen einer Verbindung mit dem Geräteclient

In diesem Beispiel werden Eingabeparameterwerte für das Zertifikat zum besseren Verständnis als lokale Variablen dargestellt. Speichern Sie in einem Produktionssystem vertrauliche Eingabeparameter in Umgebungsvariablen oder an einem anderen sichereren Speicherort. Verwenden Sie z. B. os.getenv("HOSTNAME") zum Lesen der Umgebungsvariable mit dem Hostnamen.

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

Weitere Informationen zur Zertifikatauthentifizierung finden Sie unter:

Codebeispiele

Beispiele für die X.509-Zertifikatauthentifizierung von Geräten finden Sie in den asynchronen Hubszenarien in den Beispielen, deren Dateinamen auf „x509“ enden.

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

So verbinden Sie ein Gerät mit IoT Hub

Rufen Sie create_from_connection_string auf, um die primäre Verbindungszeichenfolge des Geräts hinzuzufügen.
Rufen Sie connect auf, um eine Verbindung mit dem Geräteclient herzustellen.

Zum Beispiel:

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

Abrufen der Blob Storage-Informationen

Rufen Sie get_storage_info_for_blob auf, um Informationen von einem IoT-Hub zu einem verknüpften Azure Storage-Konto abzurufen. Zu diesen Informationen gehören der Hostname, der Containername, der Blobname und ein SAS-Token. Die get_storage_info_for_blob-Methode gibt außerdem eine Korrelations-ID (correlation_id) zurück, die in der notify_blob_upload_status-Methode verwendet wird. Über correlation_id gibt IoT Hub an, an welchem Blob Sie arbeiten.

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

Hochladen einer Datei in Blob Storage

So laden Sie eine Datei in Blob Storage hoch

Verwenden Sie from_blob_url, um ein BlobClient-Objekt aus einer Blob-URL zu erstellen.
Rufen Sie upload_blob auf, um die Datei in Blob Storage hochzuladen.

In diesem Beispiel wird die blob_info-Struktur geparst, um eine URL zu erstellen, die zum Initialisieren von BlobClient verwendet wird. Anschließend wird upload_blob aufgerufen, um die Datei in Blob Storage hochzuladen.

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)

Benachrichtigen des IoT-Hubs über den Uploadstatus

Verwenden Sie notify_blob_upload_status, um den IoT-Hub über den Status des Blob Storage-Vorgangs zu benachrichtigen. Übergeben Sie die von der get_storage_info_for_blob-Methode abgerufene Korrelations-ID (correlation_id). Mit correlation_id benachrichtigt der IoT-Hub Dienste, die möglicherweise auf eine Benachrichtigung über den Status der Dateiuploadaufgabe lauschen.

In diesem Beispiel wird der IoT-Hub über einen erfolgreichen Dateiupload benachrichtigt:

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

Herunterfahren des Geräteclients

Fahren Sie den Client herunter. Sobald diese Methode aufgerufen wird, führt jeder Versuch weiterer Clientaufrufe zur Auslösung von ClientError.

device_client.shutdown()

SDK-Dateiuploadbeispiele

Das SDK enthält zwei Dateiuploadbeispiele:

Übersicht

In diesem Artikel wird beschrieben, wie Sie das Azure IoT SDK für Node.js verwenden, um eine Geräte-App zum Hochladen einer Datei und eine Back-End-Dienstanwendung zum Empfangen von Dateiuploadbenachrichtigungen erstellen.

Erstellen einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Sie mithilfe des Pakets azure-iot-device im Azure IoT SDK für Node.js eine Datei von einem Gerät in einen IoT-Hub hochladen.

Installieren der SDK-Pakete

Führen Sie den folgenden Befehl aus, um das Geräte-SDK azure-iot-device sowie die Pakete azure-iot-device-mqtt und @azure/storage-blob auf dem Entwicklungscomputer zu installieren:

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

Das Paket azure-iot-device enthält Objekte, die über eine Schnittstelle mit IoT-Geräten verfügen.

Gehen Sie wie folgt vor, um eine Datei von einem Gerät in einen IoT-Hub hochzuladen:

Verbinden des Geräts mit IoT Hub
Abrufen eines SAS-Tokens (Shared Access Signature) für ein Blob von IoT Hub
Hochladen der Datei in Azure Storage
Senden einer Benachrichtigung über den Dateiuploadstatus an den IoT-Hub

Erstellen von Modulen

Erstellen Sie Client-, Protokoll-, Fehler- und Pfadmodule mithilfe der installierten Pakete.

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

Verbinden eines Geräts mit IoT Hub

Eine Geräte-App kann sich mit den folgenden Methoden bei IoT Hub authentifizieren:

X.509-Zertifikat
Schlüssel für den gemeinsamen Zugriff

Authentifizierung mit einem X.509-Zertifikat

Das X.509-Zertifikat wird an die Übertragung über die Verbindung zwischen Gerät und IoT Hub angefügt.

So konfigurieren Sie eine Verbindung zwischen einem Gerät und IoT Hub mit einem X.509-Zertifikat

Rufen Sie fromConnectionString auf, um die Geräteverbindungszeichenfolge und den Transporttyp hinzuzufügen. Fügen Sie der Geräteverbindungszeichenfolge x509=true hinzu, um anzugeben, dass DeviceClientOptions ein Zertifikat hinzugefügt wird. Beispiel: HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Konfigurieren Sie eine JSON-Variable mit Zertifikatdetails, und übergeben Sie sie an DeviceClientOptions.
Rufen Sie setOptions auf, um dem Clienttransport ein X.509-Zertifikat und einen Schlüssel (und optional eine Passphrase) hinzuzufügen.
Rufen Sie open auf, um die Verbindung vom Gerät zu IoT Hub zu öffnen.

Das folgende Beispiel zeigt Zertifikatkonfigurationsinformationen in einer JSON-Variable. Die Zertifizierungskonfiguration options wird an setOptions übergeben und die Verbindung wird mit open geöffnet.

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

Weitere Informationen zur Zertifikatauthentifizierung finden Sie unter:

Codebeispiel

Ein funktionierendes Beispiel für die Authentifizierung mit X.509-Zertifikaten finden Sie unter Einfaches Gerätebeispiel (X.509).

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Auswählen eines Transportprotokolls

Das Client-Objekt unterstützt die folgenden Protokolle:

Amqp
Http: Bei Verwendung von Http führt die Client-Instanz selten eine Überprüfung auf Nachrichten von IoT Hub durch (mindestens alle 25 Minuten).
Mqtt
MqttWs
AmqpWs

Installieren Sie die erforderlichen Transportprotokolle auf Ihrem Computer.

Mit diesem Befehl wird beispielsweise das Amqp-Protokoll installiert:

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

Weitere Informationen zu den Unterschieden zwischen der Unterstützung für MQTT, AMQP und HTTPS finden Sie unter Leitfaden zur C2D-Kommunikation und Auswählen eines Kommunikationsprotokolls.

Erstellen eines Clientobjekts

Erstellen Sie ein Client-Objekt mithilfe des installierten Pakets.

Zum Beispiel:

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

Erstellen eines Protokollobjekts

Erstellen Sie ein Protocol-Objekt mithilfe eines installierten Transportpakets.

In diesem Beispiel wird das AMQP-Protokoll zugewiesen:

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

Fügen Sie die Verbindungszeichenfolge des Geräts und das Transportprotokoll hinzu

Rufen Sie fromConnectionString auf, um Verbindungsparameter für das Gerät zu liefern:

connStr: die Verbindungszeichenfolge für das Gerät
transportCtor: Das Transportprotokoll

In diesem Beispiel wird das Amqp-Transportprotokoll verwendet:

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

Öffnen der Verbindung mit IoT Hub

Verwenden Sie die open-Methode, um eine Verbindung zwischen einem IoT-Gerät und IoT Hub zu öffnen.

Zum Beispiel:

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

Abrufen eines SAS-Tokens von IoT Hub

Verwenden Sie getBlobSharedAccessSignature, um das SAS-Token des verknüpften Speicherkontos vom IoT-Hub abzurufen.

Zum Beispiel:

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

Hochladen der Datei in den IoT-Hub

So laden Sie eine Datei von einem Gerät in den IoT-Hub hoch

Erstellen Sie eine Streampipeline.
Erstellen Sie die Blob-URL.
Erstellen Sie ein BlockBlobClient-Objekt für den Dateiupload in Blob Storage.
Rufen Sie uploadFile auf, um die Datei in Blob Storage hochzuladen.
Rufen Sie notifyBlobUploadStatus auf, um den IoT-Hub zu benachrichtigen, dass der Upload erfolgreich oder nicht erfolgreich war.

Zum Beispiel:

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

Hochladen der lokalen Datei in Blob Storage

Sie können eine lokale Datei von einem Computer in Blob Storage hochladen.

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

SDK-Dateiuploadbeispiel

Das SDK enthält ein Beispiel für den erweiterten Upload in Blobs.

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie Sie Dateiuploadbenachrichtigungen in einer Back-End-Anwendung empfangen.

Die ServiceClient-Klasse enthält Methoden, mit denen Dienste Dateiuploadbenachrichtigungen empfangen können.

Dienst-SDK-Paket installieren

Führen Sie diesen Befehl aus, um azure-iothub auf Ihrem Computer zu installieren:

npm install azure-iothub --save

Herstellen einer Verbindung mit dem IoT-Hub

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

SAS-Richtlinie
Microsoft Entra

Wichtig

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verwenden Sie fromConnectionString, um eine Verbindung mit dem IoT-Hub herzustellen.

Um eine Datei von einem Gerät hochzuladen, benötigt Ihr Dienst die Berechtigung Dienst verbinden. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt.

Geben Sie als Parameter für CreateFromConnectionString die Verbindungszeichenfolge der SAS-Richtlinie für den Dienst an. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

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

Verbinden mit Microsoft Entra

Eine Übersicht über Node.js SDK-Authentifizierung finden Sie unter:

Konfigurieren der Microsoft Entra-App

Geheimer Clientschlüssel
Zertifikat
Anmeldeinformationen für Verbundidentität

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Microsoft Entra erfordert dieses Paket:

npm install --save @azure/identity

In diesem Beispiel wurden Clientschlüssel, Client-ID und Mandanten-ID der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.

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

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

Das resultierende Anmeldeinformationstoken kann dann an fromTokenCredential übergeben werden, um eine Verbindung mit IoT Hub für jeden SDK-Client herzustellen, der Microsoft Entra-Anmeldeinformationen akzeptiert:

fromTokenCredential erfordert zwei Parameter:

Die Azure-Dienst-URL – Die Azure-Dienst-URL sollte im Format {Your Entra domain URL}.azure-devices.net ohne ein https://-Präfix vorliegen. Beispiel: MyAzureDomain.azure-devices.net.
Das Azure-Anmeldeinformationstoken

In diesem Beispiel werden die Azure-Anmeldeinformationen mithilfe von DefaultAzureCredential erlangt. Die Azure-Domänen-URL und Anmeldeinformationen werden dann an Registry.fromTokenCredential bereitgestellt, um die Verbindung mit IoT Hub zu erstellen.

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

Codebeispiele

Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie in Azure-Identitätsbeispielen.

Erstellen eines Rückrufempfängers für Dateiuploadbenachrichtigungen

So erstellen Sie einen Rückrufempfänger für Dateiuploadbenachrichtigungen

Rufen Sie getFileNotificationReceiver auf. Geben Sie den Namen einer Rückrufmethode für den Dateiupload an, die aufgerufen wird, wenn Benachrichtigungen empfangen werden.
Verarbeiten Sie Dateiuploadbenachrichtigungen in der Rückrufmethode.

In diesem Beispiel wird der Empfänger receiveFileUploadNotification für den Benachrichtigungsrückruf eingerichtet. Der Empfänger interpretiert die Informationen zum Dateiuploadstatus und gibt eine Statusmeldung in der Konsole aus.

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

Beispiel für eine SDK-Dateiuploadbenachrichtigung

Das SDK enthält ein Beispiel für Dateiuploads.

Freigeben über

Hochladen von Dateien von einem Gerät in die Cloud mit Azure IoT Hub

Voraussetzungen

Übersicht

Hochladen einer Datei von einer Geräteanwendung

Verbinden eines Geräts mit IoT Hub

Authentifizierung mit einem X.509-Zertifikat

Codebeispiele

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Abrufen eines SAS-URI vom IoT-Hub

Hochladen einer Datei in Azure Storage

Benachrichtigen des IoT-Hubs über den Dateiuploadstatus

SDK-Dateiuploadbeispiel

Empfangen einer Dateiuploadbenachrichtigung in einer Back-End-Anwendung

Hinzufügen des NuGet-Dienstpakets

Herstellen einer Verbindung mit dem IoT-Hub

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verbinden mit Microsoft Entra

Konfigurieren der Microsoft Entra-App

Authentifizieren mithilfe von DefaultAzureCredential

Codebeispiel

Empfangen von Dateiuploadbenachrichtigungen

Beispiel für den Empfang eines SDK-Dateiuploads

Übersicht

Hochladen einer Datei von einer Geräteanwendung

Verbinden eines Geräts mit IoT Hub

Authentifizierung mit einem X.509-Zertifikat

Codebeispiele

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Abrufen eines SAS-URI vom IoT-Hub

Hochladen der Datei in Azure Storage

Senden einer Benachrichtigung über den Dateiuploadstatus an den IoT-Hub

Schließen des Clients

Erstellen einer Back-End-Anwendung

Hinzufügen von Importanweisungen

Herstellen der Verbindung mit dem IoT Hub

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Definieren des Verbindungsprotokolls

Erstellen des ServiceClient-Objekts

Öffnen der Verbindung zwischen Anwendung und IoT Hub

Verbinden mit Microsoft Entra

Konfigurieren der Microsoft Entra-App

Authentifizieren mithilfe von DefaultAzureCredential

Authentifizieren mit ClientSecretCredentialBuilder

Andere Authentifizierungsklassen

Codebeispiele

Überprüfen des Dateiuploadstatus

SDK-Dateiuploadbeispiele

Installieren von Paketen

Hochladen einer Datei von einer Geräteanwendung

Importbibliotheken

Verbinden eines Geräts mit IoT Hub

Authentifizierung mit einem X.509-Zertifikat

Codebeispiele

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Abrufen der Blob Storage-Informationen

Hochladen einer Datei in Blob Storage

Benachrichtigen des IoT-Hubs über den Uploadstatus

Herunterfahren des Geräteclients

SDK-Dateiuploadbeispiele

Übersicht

Erstellen einer Geräteanwendung

Installieren der SDK-Pakete

Erstellen von Modulen

Verbinden eines Geräts mit IoT Hub

Authentifizierung mit einem X.509-Zertifikat

Codebeispiel

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Auswählen eines Transportprotokolls

Erstellen eines Clientobjekts

Erstellen eines Protokollobjekts

Fügen Sie die Verbindungszeichenfolge des Geräts und das Transportprotokoll hinzu

Öffnen der Verbindung mit IoT Hub

Abrufen eines SAS-Tokens von IoT Hub

Hochladen der Datei in den IoT-Hub

Hochladen der lokalen Datei in Blob Storage

SDK-Dateiuploadbeispiel

Erstellen einer Back-End-Anwendung

Dienst-SDK-Paket installieren

Herstellen einer Verbindung mit dem IoT-Hub