Hochladen von Dateien mit IoT Hub

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.

Ü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 Storage-Konto bereitstellt, die mit dem Hub vorkonfiguriert werden. Die Verwendung von Dateiuploads mit IoT Hub besteht aus drei Teilen:

• Konfigurieren eines Azure Storage-Kontos und eines Blobcontainers auf Ihrem IoT-Hub.
• Hochladen von Dateien von Geräten.
• Optional können Sie Back-End-Dienste über abgeschlossene Dateiuploads benachrichtigen.

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.

Die Azure IoT-Geräte- und Dienst-SDKs unterstützen den Dateiupload vollständig. 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.

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.

Der Dateiupload unterliegt den Firewalleinstellungen von Azure Storage. Sie müssen sicherstellen, dass Ihre Geräte basierend auf Ihrer Authentifizierungskonfiguration mit Azure Storage 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. Sie müssen Ihre Geräte weiterhin mithilfe des SAS-URI mit dem Speicher verbinden. Heutzutage wird der SAS-URI mithilfe einer Verbindungszeichenfolge generiert.

Informationen zum Konfigurieren des Dateiuploads zur Verwendung der identitätsbasierten Authentifizierung finden Sie unter Konfigurieren des Dateiuploads mit verwalteten Identitäten.

Dateiuploadeinstellungen

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

Einstellungen für Dateiuploadbenachrichtigungen

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

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.

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"
}

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"
}

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:

• Weitere Informationen zum Arbeiten mit Blobs in Azure-Speicher finden Sie in der Dokumentation zu Azure Blob Storage.

• Informationen zur Verwendung von Azure Storage-Client-SDKs zum Hochladen von Blobs finden Sie unter Azure Blob-Speicher-API-Referenz.

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"
}

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"
}

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

• Konfigurieren von Dateiuploads auf IoT Hub

• Konfigurieren von verwalteten Identitäten auf IoT Hub