Freigeben über

Konfigurieren von IoT Hub-Dateiuploads mit der Azure CLI

  • Artikel

In diesem Artikel erfahren Sie, wie Sie Dateiuploads in Ihren IoT-Hub unter Verwendung der Azure CLI konfigurieren.

Damit Sie die Dateiuploadfunktion in IoT Hub nutzen können, müssen Sie Ihrem IoT-Hub zuerst ein Azure-Speicherkonto und einen Blobcontainer zuordnen. IoT Hub generiert automatisch SAS-URIs mit Schreibberechtigungen für diesen Blobcontainer, die Geräte beim Hochladen von Dateien verwenden können. Zusätzlich zum Speicherkonto und Blobcontainer können Sie die Gültigkeitsdauer (TTL) für den SAS-URI und den Authentifizierungstyp festlegen, der von IoT Hub für Azure Storage verwendet wird. Sie können auch Einstellungen für die optionalen Dateiuploadbenachrichtigungen konfigurieren, die IoT Hub an Back-End-Dienste übermitteln kann.

Voraussetzungen

  • Ein aktives Azure-Konto. Wenn Sie nicht über ein Konto verfügen, können Sie in nur wenigen Minuten ein kostenloses Konto erstellen.

  • Ein IoT Hub in Ihrem Azure-Abonnement. Wenn Sie noch keinen Hub haben, können Sie die Schritte unter Erstellen eines IoT-Hubs ausführen.

  • Ein Azure Storage-Konto mit einem Blobcontainer. Wenn Sie über kein Azure Storage Konto verfügen, können Sie über die Azure CLI ein Konto erstellen. Weitere Informationen finden Sie unter Erstellen eines Speicherkontos.

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Hinweis

In diesem Artikel wird die neueste Version der Azure IoT-Erweiterung namens azure-iot verwendet. Die Legacy-Version heißt azure-cli-iot-ext. Es sollte jedoch jeweils nur eine Version installiert sein. Sie können den Befehl az extension list verwenden, um die derzeit installierten Erweiterungen zu überprüfen.

Verwenden Sie az extension remove --name azure-cli-iot-ext, um die Legacy-Version der Erweiterung zu entfernen.

Verwenden Sie az extension add --name azure-iot, um die neue Version der Erweiterung hinzuzufügen.

Verwenden Sie az extension list, um die installierten Erweiterungen anzuzeigen.

Anmelden und Festlegen Ihres Azure-Kontos

Melden Sie sich bei Ihrem Azure-Konto an, und wählen Sie Ihr Abonnement aus. Wenn Sie Azure Cloud Shell verwenden, sollten Sie bereits angemeldet sein. Wenn Sie über mehrere Abonnements verfügen, müssen Sie aber möglicherweise weiterhin Ihr Azure-Abonnement auswählen.

  1. Führen Sie an der Eingabeaufforderung den Anmeldebefehl aus:

    az login

    Befolgen Sie die Anweisungen zur Authentifizierung mit dem Code, und melden Sie sich in einem Webbrowser bei Ihrem Azure-Konto an.

  2. Wenn Sie über mehrere Azure-Abonnements verfügen, erhalten Sie durch die Anmeldung bei Azure Zugriff auf alle Azure-Konten, die mit Ihren Anmeldeinformationen verknüpft sind. Führen Sie den folgenden Befehl aus, um eine Liste der Azure-Konten anzuzeigen, die Sie verwenden können:

    az account list

    Führen Sie den folgenden Befehl aus, um das Abonnement auszuwählen, das Sie zum Ausführen der Befehle zum Erstellen Ihres IoT Hubs verwenden möchten. Sie können entweder den Abonnementnamen oder die ID aus der Ausgabe des vorherigen Befehls verwenden:

    az account set --subscription {your subscription name or id}

Konfigurieren des Zugriffs auf das Speicherkonto

In den folgenden Schritten wird davon ausgegangen, dass Sie Ihr Speicherkonto mit dem Ressourcen-Manager-Bereitstellungsmodell und nicht mit dem klassischen Bereitstellungsmodell erstellt haben.

Um Dateiuploads von Ihren Geräten zu konfigurieren, müssen Sie Ihrem IoT-Hub Zugriffsberechtigungen für das Azure Storage-Konto erteilen. Das Speicherkonto muss sich in demselben Abonnement wie der IoT-Hub befinden. Sie benötigen auch den Name des Blobcontainers im Speicherkonto.

Sie können die schlüsselbasierte oder identitätsbasierte Authentifizierung verwenden, um Zugriffsberechtigungen bereitzustellen. Microsoft empfiehlt die identitätsbasierte Authentifizierung, da sie eine sicherere Option darstellt.

Schlüsselbasierte Authentifizierung

Geben Sie für die schlüsselbasierte Authentifizierung die Verbindungszeichenfolge für Ihr Speicherkonto an. Verwenden Sie den Befehl az storage account show-connection-string, um Ihre Speicherkontoschlüssel abzurufen.

Notieren Sie sich den Wert für connectionString. Die Verbindungszeichenfolge sieht ähnlich wie die folgende Ausgabe aus:

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your_storage_account_name};AccountKey={your_storage_account_key}"
}

Identitätsbasierte Authentifizierung

Sie können systemseitig zugewiesene verwaltete Identitäten oder benutzerseitig zugewiesene verwaltete Identitäten für die identitätsbasierte Authentifizierung verwenden. Weitere Informationen finden Sie unter IoT Hub-Unterstützung für verwaltete Identitäten.

Verwenden Sie den Befehl az role assignment create, um Ihrer verwalteten Identität eine Rolle zuzuweisen. Weitere Informationen finden Sie unter Zuweisen einer Azure-Rolle für den Zugriff auf Blobdaten.

Konfigurieren Ihres IoT-Hubs

Sie können nun Ihren IoT Hub so konfigurieren, dass er die Möglichkeit zum Hochladen von Dateien auf den IoT Hub unter Verwendung Ihrer Speicherkontodetails bietet.

Die Konfiguration erfordert die folgenden Werte:

  • Speichercontainer: Ein Blobcontainer in einem Azure-Speicherkonto Ihres aktuellen Azure-Abonnements, der Ihrer IoT Hub-Instanz zugeordnet werden soll. Sie haben die erforderlichen Speicherkontoinformationen im vorherigen Abschnitt abgerufen. IoT Hub generiert automatisch SAS-URIs mit Schreibberechtigungen für diesen Blobcontainer, die Geräte beim Hochladen von Dateien verwenden können.

  • Benachrichtigungen für hochgeladene Dateien empfangen: Aktivieren oder deaktivieren Sie Benachrichtigungen zum Hochladen von Dateien.

  • SAS-TTL: Diese Einstellung dient zum Festlegen der Gültigkeitsdauer der SAS-URIs, die von IoT Hub an das Gerät zurückgegeben werden. Standardmäßig auf 1 Stunde festgelegt.

  • Standard-TTL für Dateibenachrichtigungseinstellungen: Die Gültigkeitsdauer einer Dateiuploadbenachrichtigung (Zeit bis zum Ablauf). Standardmäßig auf 1 Tag festgelegt.

  • Anzahl maximaler Zustellungen für Dateibenachrichtigungen: Gibt an, wie oft IoT Hub versucht, eine Dateiuploadbenachrichtigung zu senden. Standardmäßig auf 10 festgelegt.

  • Dauer der Dateibenachrichtigungssperre: Die Sperrdauer für die Dateibenachrichtigungswarteschlange. Standardmäßig auf 60 Sekunden festgelegt.

  • Authentifizierungstyp: Die Art der Authentifizierung für IoT Hub zur Verwendung mit Azure Storage. Diese Einstellung bestimmt, wie sich Ihr IoT-Hub authentifiziert und bei Azure Storage autorisiert. Der Standard ist die schlüsselbasierte Authentifizierung. Die Optionen der systemseitig zugewiesenen oder benutzerseitig zugewiesenen verwalteten Identitätsauthentifizierung werden jedoch empfohlen. Verwaltete Identitäten stellen für Azure-Dienste eine automatisch verwaltete Identität in Microsoft Entra ID auf sichere Weise bereit.

    Hinweis

    Mit der Einstellung für den Authentifizierungstyp wird konfiguriert, wie sich Ihr IoT-Hub bei Ihrem Azure Storage-Konto authentifiziert. Geräte authentifizieren sich bei Azure Storage immer mithilfe des SAS-URI, den sie vom IoT-Hub abrufen.

Die folgenden Befehle zeigen, wie Sie die Einstellungen für Dateiuploads für Ihren IoT-Hub konfigurieren. Diese Befehle werden aus Gründen der Übersichtlichkeit separat angezeigt, aber in der Regel würden Sie einen einzelnen Befehl mit allen erforderlichen Parametern für Ihr Szenario ausführen. Fügen Sie Anführungszeichen ein, wenn sie in der Befehlszeile angezeigt werden. Fügen Sie keine geschweiften Klammern ein. Weitere Informationen zu den einzelnen Parametern finden Sie in der Azure CLI-Dokumentation für den Befehl az iot hub update.

Mit dem folgenden Befehl werden das Speicherkonto und der Blobcontainer konfiguriert.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}"

Mit dem folgenden Befehl wird der TTL-Wert für den SAS-URI auf den Standardwert (eine Stunde) festgelegt.

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1

Der folgende Befehl aktiviert Dateibenachrichtigungen und legt die Dateibenachrichtigungseigenschaften auf ihre Standardwerte fest. (Der TTL-Wert für Dateiuploadbenachrichtigungen wird auf eine Stunde und die Sperrdauer auf 60 Sekunden festgelegt.)

az iot hub update --name {your iot hub name} \
    --fileupload-notifications true  \
    --fileupload-notification-max-delivery-count 10 \
    --fileupload-notification-ttl 1 \
    --fileupload-notification-lock-duration 60

Der folgende Befehl konfiguriert die schlüsselbasierte Authentifizierung:

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

Der folgende Befehl konfiguriert die Authentifizierung mithilfe der systemseitig zugewiesenen verwalteten Identität des IoT-Hubs. Bevor Sie diesen Befehl ausführen können, müssen Sie die systemseitig zugewiesene verwaltete Identität für Ihren IoT-Hub aktivieren und ihr die richtige rollenbasierte Zugriffssteuerungsrolle für Ihr Azure Storage-Konto zuweisen. Weitere Informationen hierzu finden Sie unter IoT Hub-Unterstützung für verwaltete Identitäten.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system]

Die folgenden Befehle rufen die benutzerseitig zugewiesenen verwalteten Identitäten ab, die für Ihren IoT-Hub konfiguriert sind, und konfigurieren die Authentifizierung mit einer dieser Identitäten. Bevor Sie eine benutzerseitig zugewiesene verwaltete Identität für die Authentifizierung verwenden können, müssen Sie die Identität für Ihren IoT-Hub konfigurieren und ihr eine geeignete rollenbasierte Zugriffssteuerungsrolle für Ihr Azure Storage-Konto zuweisen. Weitere Einzelheiten und Schritte finden Sie unter IoT Hub-Unterstützung für verwaltete Identitäten.

Verwenden Sie den Befehl az iot hub identity show, um die benutzerseitig zugewiesenen verwalteten Identitäten für Ihren IoT-Hub abzufragen.

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

Der Befehl gibt eine Sammlung der benutzerseitig zugewiesenen verwalteten Identitäten zurück, die für Ihren IoT-Hub konfiguriert sind. Die folgende Ausgabe zeigt eine Sammlung, die eine einzelne benutzerseitig zugewiesene verwaltete Identität enthält.

{
  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}": 
  {
    "clientId": "<client ID GUID>",
    "principalId": "<principal ID GUID>"
  }
}

Mit dem folgenden Befehl wird die Authentifizierung so konfiguriert, dass die oben aufgeführte benutzerseitig zugewiesene Identität verwendet wird.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}"

Sie können die Einstellungen für Ihren IoT-Hub mithilfe des folgenden Befehls überprüfen:

az iot hub show --name {your iot hub name}

Verwenden Sie den folgenden Befehl, um nur die Einstellungen für den Dateiupload zu überprüfen:

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

In den meisten Fällen ist die Verwendung der benannten Parameter in Azure CLI-Befehlen am einfachsten. Sie können die Einstellungen für den Dateiupload aber auch mit dem Parameter --set konfigurieren. Die folgenden Befehle können zu einem besseren Verständnis beitragen.

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.connectionString="{your storage account connection string}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.containerName="{your storage container name}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.sasTtlAsIso8601=PT1H0M0S

az iot hub update --name {your iot hub name} \
  --set properties.enableFileUploadNotifications=true

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.maxDeliveryCount=10

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.ttlAsIso8601=PT1H0M0S

Nächste Schritte