Freigeben über

Hochladen von Dateien mit IoT Hub

  • Artikel

In einigen Szenarien können Sie allerdings nicht einfach die Daten, die Ihre Geräte senden, den relativ kleinen Gerät-zu-Cloud-Nachrichten zuordnen, die IoT Hub akzeptiert. Beispiel: das Senden großer Mediendateien wie Video oder das Senden umfangreicher Telemetriebatches, die entweder von zeitweise verbundenen Geräten hochgeladen oder die aggregiert und komprimiert wurden, um Bandbreite zu sparen.

Wenn Sie derartig große Dateien von einem Gerät hochladen müssen, können Sie weiterhin die Sicherheit und Zuverlässigkeit des IoT Hub nutzen. Statt Nachrichten über IoT Hub selbst zu übertragen, fungiert IoT Hub stattdessen als Verteiler für ein zugeordnetes Azure-Speicher-Konto. IoT Hub kann auch Benachrichtigungen an Back-End-Dienste bereitstellen, wenn ein Gerät einen Dateiupload abschließt.

Wenn Sie Hilfe bei der Entscheidung benötigen, wann gemeldete Eigenschaften, Gerät-zu-Cloud (D2C)-Nachrichten oder Dateiuploads verwendet werden sollten, lesen Sie den Leitfaden zur D2C-Kommunikation.

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.

Übersicht über Dateiuploads

Ein IoT-Hub erleichtert Dateiuploads von verbundenen Geräten, indem er diesen SAS-URIs (Shared Access Signature) pro Upload für einen Blobcontainer und ein Azure-Speicherkonto bereitstellt, die mit dem Hub vorkonfiguriert wurden. Die Verwendung von Dateiuploads bei IoT Hub besteht aus drei Teilen: Vorkonfigurieren eines Azure-Speicherkontos und Blobcontainers auf Ihrem IoT-Hub, Hochladen von Dateien von Geräten und – optional – Benachrichtigen von Back-End-Diensten über abgeschlossene Dateiuploads.

Damit Sie die Dateiuploadfunktion in IoT Hub nutzen können, müssen Sie Ihrem IoT-Hub zuerst ein Azure-Speicherkonto und einen Blob-Container zuordnen. Sie können auch Einstellungen konfigurieren, die steuern, wie sich der IoT Hub bei Azure Storage authentifiziert und die die Gültigkeitsdauer (Time-to-Live, TTL) der SAS-URIs, die der IoT Hub an Geräte übermittelt, und Benachrichtigungen über Dateiuploads an Ihre Back-End-Dienste steuern. Für mehr Informationen siehe Zuordnen eines Azure-Speicher-Kontos zu einem IoT Hub.

Geräte führen einen dreistufigen Prozess aus, um eine Datei in den zugeordneten Blob-Container hochzuladen:

  1. Das Gerät initiiert den Dateiupload mit dem IoT Hub. Er übergibt den Namen eines Blobs in der Anfrage und ruft im Gegenzug einen SAS-URI und eine Korrelations-ID ab. Der SAS-URI enthält ein SAS-Token für Azure Storage, das dem Gerät Lese-/Schreibberechtigung für das angeforderte Blob im Blob-Container erteilt. Weitere Informationen finden Sie unter Gerät: Initialisieren eines Dateiuploads.

  2. Das Gerät verwendet den SAS-URI, um Azure-Blob-Speicher-APIs sicher aufzurufen, damit die Datei in den Blob-Container hochgeladen werden kann. Weitere Informationen finden Sie unter Gerät: Hochladen einer Datei mithilfe von Azure-Speicher-APIs.

  3. Wenn der Dateiupload abgeschlossen ist, benachrichtigt das Gerät den IoT Hub über den Abschlussstatus unter Verwendung der Korrelations-ID, die es von IoT Hub beim Initiieren des Uploads erhalten hat. Weitere Informationen finden Sie unter Gerät: Benachrichtigen von IoT Hub über einen abgeschlossenen Dateiupload.

Back-End-Dienste können Dateiuploadbenachrichtigungen auf dem dienstseitigen Endpunkt für Dateiuploadbenachrichtigungen des IoT Hub abonnieren. Wenn Sie diese Benachrichtigungen auf Ihrem IoT Hub aktiviert haben, werden sie auf diesem Endpunkt übermittelt, wenn ein Gerät den Hub darüber informiert, dass ein Dateiupload abgeschlossen wurde. Dienste können diese Benachrichtigungen verwenden, um eine weitere Verarbeitung der Blobdaten einzuleiten. Weitere Informationen finden Sie unter Dienst: Benachrichtigungen zum Dateiupload.

Das Hochladen von Dateien wird von den Azure-IoT-Geräte- und Dienst-SDKs vollständig unterstützt. Weitere Informationen finden Sie unter Dateiupload mithilfe eines SDK.

Kontingente und Grenzwerte für Dateiuploads

IoT Hub erzwingt Drosselungsgrenzwerte für die Anzahl von Dateiuploads, die innerhalb eines bestimmten Zeitraums initiiert werden können. Der Schwellenwert basiert auf der SKU und der Anzahl der Einheiten Ihres IoT Hubs. Darüber hinaus ist jedes Gerät jeweils auf 10 gleichzeitige aktive Dateiuploads beschränkt. Weitere Informationen finden Sie unter IoT Hub-Kontingente und -Drosselung.

Zuordnen eines Azure-Speicher-Kontos zu einem IoT Hub

Damit Sie die Dateiuploadfeatures nutzen können, müssen Sie Ihrem IoT-Hub zuerst ein Azure-Speicherkonto und einen Blob-Container zuordnen. Alle Dateiuploads von Geräten, die bei Ihrem IoT Hub registriert sind, werden in diesen Container übertragen. Informationen zum Konfigurieren eines Speicherkontos und eines Blobcontainers in Ihrem IoT-Hub finden Sie unter Konfigurieren von IoT Hub-Dateiuploads im Azure-Portal, Konfigurieren von IoT Hub-Dateiuploads mithilfe der Azure CLI oder Konfigurieren von IoT Hub-Dateiuploads mithilfe von PowerShell. Sie können auch die IoT Hub-Verwaltungs-APIs verwenden, um Dateiuploads programmgesteuert zu konfigurieren.

Wenn Sie das Portal verwenden, können Sie während der Konfiguration ein Speicherkonto und einen Container erstellen. Informationen zum Erstellen eines Speicherkontos finden Sie andernfalls unter Erstellen eines Speicherkontos in der Azure Storage-Dokumentation. Sobald Sie ein Speicherkonto haben, können Sie in den Azure Blob Storage-Schnellstarts erfahren, wie ein Blobcontainer erstellt wird. Standardmäßig verwendet Azure IoT Hub schlüsselbasierte Authentifizierung zur Herstellung einer Verbindung mit und Autorisierung bei Azure Storage. Sie können auch benutzerseitig oder systemseitig zugewiesene verwaltete Identitäten konfigurieren, um Azure IoT Hub bei Azure Storage zu authentifizieren. Verwaltete Identitäten stellen für Azure-Dienste eine automatisch verwaltete Identität in Microsoft Entra ID auf sichere Weise bereit. Informationen zum Konfigurieren von verwalteten Identitäten finden Sie unter IoT Hub-Unterstützung für verwaltete Identitäten im Abschnitt Konfigurieren des Dateiuploads mit verwalteten Identitäten.

Der Dateiupload unterliegt den Firewalleinstellungen von Azure Storage. Basierend auf Ihrer Authentifizierungskonfiguration müssen Sie sicherstellen, dass Ihre Geräte mit Azure-Speicher kommunizieren können.

Es gibt mehrere andere Einstellungen, die den Ablauf von Dateiuploads und Dateiuploadbenachrichtigungen steuern. In den folgenden Abschnitten sind alle verfügbaren Einstellungen aufgeführt. Je nachdem, ob Sie das Azure-Portal, Azure CLI, PowerShell oder die Verwaltungs-APIs zum Konfigurieren von Dateiuploads verwenden, sind einige dieser Einstellungen möglicherweise nicht verfügbar. Stellen Sie sicher, dass Sie die Einstellung enableFileUploadNotifications (Dateiuploadbenachrichtigungen aktivieren) festlegen, wenn Benachrichtigungen an Ihre Back-End-Dienste gesendet werden sollen und wenn ein Dateiupload abgeschlossen ist.

IoT Hub-Speicher und -Authentifizierungseinstellungen

Die folgenden Einstellungen ordnen Ihrem IoT Hub ein Speicherkonto und einen Container zu und steuern, wie sich Ihr Hub bei Azure Storage authentifiziert. Diese Einstellungen wirken sich nicht auf die Authentifizierung von Geräten bei Azure-Speicher aus. Geräte authentifizieren sich immer mit dem SAS-Token, das im SAS-URI angezeigt wird, der aus dem IoT Hub abgerufen wurde.

Eigenschaft BESCHREIBUNG Bereich und Standardwert
storageEndpoints.$default.authenticationType Steuert, wie sich der IoT Hub bei Azure Storage authentifiziert. Mögliche Werte sind keyBased und identityBased. Standardwert: keyBased.
storageEndpoints.$default.connectionString Die Verbindungszeichenfolge für das Azure-Speicherkonto, das für Dateiuploads verwendet werden soll. Standard: leere Zeichenfolge.
storageEndpoints.$default.containerName Der Name des Containers, in den Daten hochgeladen werden sollen. Standard: leere Zeichenfolge.
storageEndpoints.$default.identity Die verwaltete Identität, die für die identitätsbasierte Authentifizierung verwendet werden soll. Mögliche Werte sind [system] für die vom System zugewiesene verwaltete Identität oder eine Ressourcen-ID für eine vom Benutzer zugewiesene verwaltete Identität. Der Wert wird nicht für die schlüsselbasierte Authentifizierung verwendet. Standard: NULL

Dateiuploadeinstellungen

Die folgenden Einstellungen steuern das Hochladen von Dateien vom Gerät.

Eigenschaft BESCHREIBUNG Bereich und Standardwert
storageEndpoints.$default.ttlAsIso8601 Standard-Gültigkeitsdauer für SAS-URIs, die von IoT Hub generiert werden. ISO_8601-Intervall bis zu 48 Stunden (mindestens eine Minute). Standard: eine Stunde.

Einstellungen für Dateiuploadbenachrichtigungen

Mit den folgenden Einstellungen werden Dateiuploadbenachrichtigungen an Back-End-Dienste gesteuert.

Eigenschaft BESCHREIBUNG Bereich und Standardwert
enableFileUploadNotifications Steuert, ob Dateiuploadbenachrichtigungen in den Endpunkt für Dateibenachrichtigungen geschrieben werden. Bool. Standardwert: False.
fileNotifications.ttlAsIso8601 Standardgültigkeitsdauer für Dateiuploadbenachrichtigungen. ISO_8601-Intervall bis zu 48 Stunden (mindestens eine Minute). Standard: eine Stunde.
fileNotifications.lockDuration Sperrdauer für die Warteschlange der Dateiuploadbenachrichtigungen. Möglicher Bereich: zwischen fünf und 300 Sekunden. Standardwert: 60 Sekunden.
fileNotifications.maxDeliveryCount Maximale Übermittlungsanzahl für die Warteschlange der Dateiuploadbenachrichtigungen. 1 bis 100. Standardwert: 10

Dateiupload mithilfe eines SDK

Die folgenden Schrittanleitungen enthalten eine vollständige Schritt-für-Schritt-Anleitung zum Hochladen von Dateien mithilfe der Azure IoT-Geräte- und Dienst-SDKs. Die Leitfäden zeigen, wie Sie ein Speicherkonto über das Azure-Portal einem IoT-Hub zuordnen können. Sie enthalten auch Codeschnipsel oder verweisen auf Beispiele, die Sie durch einen Uploadvorgang führen.

Schrittanleitung Geräte-SDK Beispiel Dienst-SDK Beispiel
.NET Ja Ja
Java Ja Ja
Node.js Ja Ja
Python Ja Nein (Nicht unterstützt)

Hinweis

Das C-Geräte-SDK verwendet einen einzelnen Befehl auf dem Geräteclient, um Dateiuploads durchzuführen. Weitere Informationen finden Sie unter IoTHubDeviceClient_UploadToBlobAsync() und IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Diese Funktionen führen sämtliche Aspekte des Dateiuploads in einem einzigen Aufruf aus: Initiieren des Uploads, Hochladen der Daten in Azure-Speicher und Benachrichtigen von IoT Hub, wenn der Vorgang abgeschlossen ist. Diese Interaktion bedeutet: Das Gerät muss zusätzlich zu dem Protokoll, das es für die Kommunikation mit IoT Hub verwendet, auch über HTTPS mit Azure-Speicher kommunizieren können, da diese Funktionen die Azure-Speicher-APIs aufrufen.

Gerät: Initialisieren eines Dateiuploads

Das Gerät ruft die REST-API zum Erstellen von Dateiuploads SAS-URI\ oder die entsprechende API in einem der Geräte-SDKs auf, um einen Dateiupload zu initiieren.

Unterstützte Protokolle: HTTPS
Endpunkt: {iot hub}.azure-devices.net/devices/{deviceId}/files
Methode: POST

{
    "blobName":"myfile.txt"
}
Eigenschaft BESCHREIBUNG
Blob-Name Der Name des Blobs, für das der SAS-URI generiert werden soll.

Der IoT Hub antwortet mit einer Korrelations-ID und den Elementen eines SAS-URI, die das Gerät für die Authentifizierung bei Azure Storage verwenden kann. Diese Antwort unterliegt den Drosselungsgrenzwerten und Uploadlimits pro Gerät des IoT Hub-Ziels.

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.windows.net",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}
Eigenschaft BESCHREIBUNG
correlationId Die Kennung für das Gerät, die beim Senden der Benachrichtigung über den abgeschlossenen Dateiupload an den IoT Hub verwendet werden soll.
hostName Der Hostname des Azure-Speicherkontos für das Speicherkonto, das auf dem IoT Hub konfiguriert ist.
containerName Der Name des Blob-Containers, der auf dem IoT Hub konfiguriert ist.
Blob-Name Der Speicherort, an dem das Blob im Container gespeichert wird. Der Name weist folgendes Format auf: {device ID of the device making the request}/{blobName in the request}
sasToken> Ein SAS-Token, das Lese-/Schreibzugriff auf das Blob bei Azure Storage gewährt. Das Token wird von IoT Hub generiert und signiert.

Wenn die Antwort empfangen wird, macht das Gerät Folgendes:

  • Es speichert die Korrelations-ID, die in die Benachrichtigung über den abgeschlossenen Dateiupload an den IoT Hub eingefügt werden soll, wenn der Upload abgeschlossen ist.

  • Es verwendet andere Eigenschaften, um einen SAS-URI für das Blob zu erstellen, das für die Authentifizierung bei Azure Storage verwendet wird. Der SAS-URI enthält den Ressourcen-URI für das angeforderte Blob und das SAS-Token. Sie hat folgende Form: https://{hostName}/{containerName}/{blobName}{sasToken} (Die sasToken Eigenschaft in der Antwort enthält ein vorangestelltes "?"-Zeichen.) Die Klammern sind nicht enthalten.

    Beispielsweise lautet der SAS-URI für die im vorstehenden Beispiel zurückgegebenen Werte gleich https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw.

    Weitere Informationen zum SAS-URI und SAS-Token finden Sie unter Erstellen einer Dienst-SAS in der Azure Storage-Dokumentation.

Gerät: Datei mit Hilfe von Azure Speicher-APIs hochladen

Das Gerät verwendet die Azure Blob Storage-REST-APIs oder entsprechende Azure-Speicher-SDK-APIs zum Hochladen der Datei in das Blob in Azure-Speicher.

Unterstützte Protokolle: HTTPS

Das folgende Beispiel zeigt eine Blob-Setzen-Anfrage zum Erstellen oder Aktualisieren eines kleinen Blockblobs. Beachten Sie, dass der für diese Anforderung verwendete URI der SAS-URI ist, der von IoT Hub im vorherigen Abschnitt zurückgesandt wurde. Der x-ms-blob-type Header gibt an, dass diese Anfrage für ein Blockblob gilt. Wenn die Anfrage erfolgreich ist, gibt Azure Storage einen 201 Created zurück.

PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob

hello world

Die Arbeit mit den Azure-Speicher-APIs würde den Rahmen dieses Abschnitts sprengen. Zusätzlich zu den REST-APIs für den Azure Blob Storage, die zuvor in diesem Abschnitt verknüpft wurden, können Sie die folgende Dokumentation lesen, um Ihnen den Einstieg zu erleichtern:

Gerät: Benachrichtigen des IoT Hubs über einen abgeschlossenen Dateiupload

Das Gerät ruft die REST-API zum Aktualisieren des Dateiuploadstatus oder die entsprechende API in einem der Geräte-SDKs auf, wenn es den Dateiupload zum Abschluss bringt. Das Gerät sollte den Dateiuploadstatus mit IoT Hub aktualisieren, unabhängig davon, ob der Upload erfolgreich war oder fehlgeschlagen ist.

Unterstützte Protokolle: HTTPS
Endpunkt: {iot hub}.azure-devices.net/devices/{deviceId}/files
Methode: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}
Eigenschaft BESCHREIBUNG
correlationId Die Korrelations-ID, die in der ersten SAS-URI-Anforderung empfangen wurde.
IsSuccess Ein boolescher Wert, der angibt, ob der Dateiupload erfolgreich war.
statusCode Eine ganze Zahl, die den Statuscode des Dateiuploads darstellt. In der Regel drei Ziffern; zum Beispiel 200 oder 201.
statusDescription Eine Beschreibung des Dateiuploadstatus.

Wenn eine Benachrichtigung über den abgeschlossenen Dateiupload vom Gerät empfangen wird, gibt es folgende Aktionen des IoT Hubs:

  • Löst eine Dateiuploadbenachrichtigung an Back-End-Dienste aus, wenn Dateiuploadbenachrichtigungen konfiguriert sind.

  • Gibt die dem Dateiupload zugeordneten Ressourcen frei. Wenn der IoT Hub keine Benachrichtigung empfängt, verwaltet er die Ressourcen, bis die dem Upload zugeordnete SAS-URI-Gültigkeitsdauer (Time-to-Live, TTL) abläuft.

Service: Benachrichtigungen zum Dateiupload

Wenn auf Ihrem IoT-Hub Benachrichtigungen zum Dateiupload aktiviert sind, generiert der Hub eine Benachrichtigungsmeldung für Back-End-Dienste, wenn er von einem Gerät eine Benachrichtigung darüber empfängt, dass ein Dateiupload abgeschlossen wurde. IoT Hub übermittelt diese Dateiuploadbenachrichtigungen über einen dienstseitigen Endpunkt. Die Empfangssemantik für Dateiuploadbenachrichtigungen entspricht der Empfangssemantik für C2D-Nachrichten und weist den gleichen Nachrichtenlebenszyklus auf. Die Dienst-SDKs machen APIs verfügbar, um Dateiuploadbenachrichtigungen zu verarbeiten.

Unterstützte Protokolle: AMQP, AMQP-WS
Endpunkt: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Methode: GET

Jede Nachricht, die vom Endpunkt für Dateiuploadbenachrichtigungen abgerufen wird, ist ein JSON-Datensatz mit den folgenden Eigenschaften:

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}
Eigenschaft BESCHREIBUNG
EnqueuedTimeUtc Zeitstempel, der die Erstellung der Benachrichtigung angibt.
deviceId Die Geräte-ID des Geräts, das die Datei hochgeladen hat.
BlobUri Der URI der hochgeladenen Datei.
Blob-Name Der Name der hochgeladenen Datei. Der Name weist folgendes Format auf: {device ID of the device}/{name of the blob}
lastUpdatedTime Zeitstempel, der die letzte Aktualisierung der Datei angibt.
BlobSizeInBytes Eine ganze Zahl, die die Größe der hochgeladenen Datei in Bytes darstellt.

Dienste können Benachrichtigungen zum Verwalten von Uploads verwenden. Beispielsweise können sie ihre eigene Verarbeitung der Blobdaten auslösen, die Verarbeitung der Blobdaten mit anderen Azure-Diensten auslösen oder die Dateiuploadbenachrichtigung zur späteren Überprüfung protokollieren.

Nächste Schritte