Automatisches Migrieren eines IoT-Hubs mithilfe der Azure CLI

  • Artikel

Hier erfahren Sie, wie Sie die Azure CLI verwenden, um einen IoT-Hub zu einer neuen Region, zu einem neuen Tarif oder zu einer neuen Konfiguration zu migrieren.

Die Schritte in diesem Artikel sind in folgenden Szenarien nützlich:

  • Upgraden eines IoT-Hubs vom Free-Tarif auf einen Basic- oder Standard-Tarif
  • Migrieren eines IoT-Hubs zu einer neuen Region
  • Exportieren von IoT-Hub-Zustandsinformationen, um sie zu sichern
  • Erhöhen der Anzahl von Partitionen für einen IoT-Hub
  • Einrichten eines Hubs für eine Entwicklungsumgebung (anstatt für eine Produktionsumgebung)

Gegenüberstellung der Schritte für eine automatische bzw. manuelle Migration

Das Ergebnis dieses Artikels ähnelt zwar dem des Artikels Manuelles Migrieren einer Azure IoT Hub-Instanz mithilfe einer Azure Resource Manager-Vorlage, der Prozess unterscheidet sich jedoch. Entscheiden Sie zunächst, welcher Prozess für Ihr Szenario der richtige ist.

  • Azure CLI-Prozess (dieser Artikel):

    • Bei diesem Prozess werden Ihre Geräteregistrierung, Ihre Routing- und Endpunktinformationen sowie andere Konfigurationsdetails wie IoT Edge-Bereitstellungen oder Konfigurationen für die automatische Geräteverwaltung migriert.
    • Einfachere Migration einer geringen Anzahl von Geräten (beispielsweise bis zu 10.000)
    • Erfordert kein Azure Storage-Konto.
    • Bei diesem Prozess werden Verbindungszeichenfolgen für Routing- und Dateiupload-Endpunkte erfasst und in die ARM-Vorlagenausgabe eingeschlossen.

  • Manueller Prozess:

    • Bei diesem Prozess werden Ihre Geräteregistrierung und Ihre Routing- und Endpunktinformationen migriert. Andere Konfigurationsdetails müssen im neuen IoT-Hub manuell neu erstellt werden.
    • Schnellere Migration einer größeren Anzahl von Geräten (beispielsweise mehr als 100.000)
    • Verwendet ein Azure Storage-Konto, um die Geräteregistrierung zu übertragen.
    • Entfernt Verbindungszeichenfolgen für Routing- und Dateiupload-Endpunkte aus der ARM-Vorlagenausgabe, sodass sie manuell wieder hinzugefügt werden müssen.

Voraussetzungen

  • Azure CLI

    Für die in diesem Artikel beschriebenen Features wird mindestens die Version 0.20.0 der Erweiterung azure-iot benötigt. Mit az --version können Sie die Version Ihrer Erweiterung überprüfen. Mit az extension update --name azure-iot können Sie Ihre Erweiterung aktualisieren.

    Sollte bei Ihnen noch die Legacyerweiterung azure-cli-iot-ext installiert sein, entfernen Sie diese Erweiterung, bevor Sie die Erweiterung azure-iot hinzufügen.

IoT-Hub-Zustand

Wenn von der Migration des Zustands eines IoT-Hubs die Rede ist, geht es um eine Kombination aus drei Aspekten:

  • ARM-Ressourcen (Azure Resource Manager): Dieser Aspekt beinhaltet alles, was in einer Ressourcenvorlage definiert werden kann. Diese Informationen erhalten Sie auch, wenn Sie die Ressourcenvorlage aus Ihrem IoT-Hub im Azure-Portal exportieren. Die Informationen, die im Rahmen des Azure Resource Manager-Aspekts erfasst werden, umfassen Folgendes:

    • Aufbewahrungsdauer des integrierten Event Hubs
    • Zertifikate
    • Cloud-zu-Gerät-Eigenschaften
    • Deaktivieren der Geräte-SAS
    • Deaktivieren der lokalen Authentifizierung
    • Aktivieren von Dateiuploadbenachrichtigungen
    • Speicherendpunkt für Dateiuploads
    • Identities
      • Benutzerseitig zugewiesene Identitäten
      • Systemseitig zugewiesene Identitäten (aktiviert oder deaktiviert)
    • Netzwerkregelsätze
    • Routing
      • Benutzerdefinierte Endpunkte
      • Fallbackroute
      • Routen
    • Tags

  • Konfigurationen. Dieser Aspekt umfasst Aspekte eines IoT-Hubs, die nicht in einer ARM-Vorlage dargestellt werden. Er deckt insbesondere Konfigurationen für die automatische Geräteverwaltung sowie IoT Edge-Bereitstellungen ab.

  • Geräte. Dieser Aspekt stellt die Informationen in Ihrer Geräteregistrierung dar, einschließlich:

    • Geräteidentitäten und -zwillinge
    • Modulidentitäten und -zwillinge

IoT-Hub-Eigenschaften oder Konfigurationen, die hier nicht aufgeführt sind, werden möglicherweise nicht ordnungsgemäß exportiert oder importiert.

Exportieren des Zustands eines IoT-Hubs

Verwenden Sie den Befehl az iot hub state export, um den Zustand eines IoT-Hubs in eine JSON-Datei zu exportieren.

Die Export- und Importschritte können auch in einem einzelnen Befehl ausgeführt werden. Weitere Informationen hierzu finden Sie weiter unten in diesem Artikel im Abschnitt Migrieren eines IoT-Hubs.

Wenn Sie den Zustand eines IoT-Hubs exportieren, können Sie wählen, welche Aspekte exportiert werden sollen.

Parameter Details
--aspects Die zu exportierenden Zustandsaspekte. Geben Sie mindestens einen der zulässigen Werte an: arm (ARM), configurations (Konfigurationen) oder devices (Geräte). Ohne Angabe dieses Parameters werden alle drei Aspekte exportiert.
--state-file -f Der Pfad zu der Datei, in die die Zustandsinformationen geschrieben werden.
--replace -r Bei Angabe dieses Parameters überschreibt der Exportbefehl den Inhalt der Zustandsdatei.
--hub-name -n
or
--login -l		 Der Name des Ursprungs-IoT-Hubs (-n) oder die Verbindungszeichenfolge für den Ursprungs-IoT-Hub (-l). Bei Angabe beider Optionen hat die Verbindungszeichenfolge Vorrang.
--resource-group -g Der Name der Ressourcengruppe für den Ursprungs-IoT-Hub.

Im folgenden Beispiel werden alle Aspekte des Zustands eines IoT-Hubs in eine Datei namens myHub-state exportiert:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

Im folgenden Beispiel werden nur die Aspekte „Geräte“ und „Azure Resource Manager“ eines IoT-Hubs exportiert, und der Inhalt der bereits vorhandenen Datei wird überschrieben:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

Exportieren von Endpunkten

Wenn Sie den Azure Resource Manager-Aspekt eines IoT-Hubs exportieren möchten, ruft der Exportbefehl die Verbindungszeichenfolgen für alle Endpunkte ab, die über eine schlüsselbasierte Authentifizierung verfügen, und schließt sie in die ARM-Vorlagenausgabe ein.

Der Exportbefehl überprüft auch alle Endpunkte, um sicherzustellen, dass die Ressource, mit der eine Verbindung hergestellt wird, weiterhin vorhanden ist. Falls nicht, werden dieser Endpunkt und alle Routen, die ihn verwenden, nicht exportiert.

Importieren des Zustands eines IoT-Hubs

Verwenden Sie den Befehl az iot hub state import, um Zustandsinformationen aus einer exportierten Datei in einen neuen oder bereits vorhandenen IoT-Hub zu importieren.

Die Export- und Importschritte können auch in einem einzelnen Befehl ausgeführt werden. Weitere Informationen hierzu finden Sie weiter unten in diesem Artikel im Abschnitt Migrieren eines IoT-Hubs.

Parameter Details
--aspects Die zu importierenden Zustandsaspekte. Geben Sie mindestens einen der zulässigen Werte an: arm (ARM), configurations (Konfigurationen) oder devices (Geräte). Ohne Angabe dieses Parameters werden alle drei Aspekte importiert.
--state-file -f Der Pfad zu der Datei mit dem exportierten Zustand.
--replace -r Bei Angabe dieses Parameters löscht der Importbefehl den aktuellen Zustand des Zielhubs.
--hub-name -n
or
--login -l		 Der Name des Ziel-IoT-Hubs (-n) oder die Verbindungszeichenfolge für den Ziel-IoT-Hub (-l). Bei Angabe beider Optionen hat die Verbindungszeichenfolge Vorrang.
--resource-group -g Der Name der Ressourcengruppe für den Ziel-IoT-Hub.

Im folgenden Beispiel werden alle Aspekte in einen neuen IoT-Hub importiert, und der IoT-Hub wird erstellt, falls er noch nicht vorhanden ist:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

Im folgenden Beispiel werden nur die Aspekte „Geräte“ und „Konfigurationen“ in einen neuen IoT-Hub importiert. Der IoT-Hub muss bereits vorhanden sein, und ggf. vorhandene Geräte und Konfigurationen werden überschrieben:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

Erstellen eines neuen IoT-Hubs mit „state import“

Der Befehl az iot hub state import kann verwendet werden, um einen neuen IoT-Hub zu erstellen oder in einen bereits vorhandenen IoT-Hub zu schreiben.

Wenn Sie einen neuen IoT-Hub erstellen möchten, müssen Sie den Aspekt arm in den Importbefehl einschließen. Wenn arm nicht im Befehl enthalten und der Zielhub nicht vorhanden ist, ist der Importbefehl nicht erfolgreich.

Wenn der Zielhub nicht vorhanden ist, ist der Parameter --resource-group auch für den Importbefehl erforderlich.

Aktualisieren eines vorhandenen IoT-Hubs mit „state import“

Wenn der Ziel-IoT-Hub bereits vorhanden ist, ist der Aspekt arm für den Befehl az iot hub state import nicht erforderlich. Bei Angabe des Aspekts arm werden alle Ressourceneigenschaften überschrieben. Hiervon sind lediglich folgende Eigenschaften ausgenommen, die nach der Huberstellung nicht mehr geändert werden können:

  • Standort
  • SKU
  • Anzahl von Partitionen der integrierten Event Hubs
  • Datenresidenz
  • Features

Wenn die Ressourcengruppe (--resource-group) im Importbefehl angegeben wird und sich von der aktuellen Ressourcengruppe des IoT-Hubs unterscheidet, ist der Befehl nicht erfolgreich, da versucht wird, einen neuen Hub mit einem Namen zu erstellen, der mit dem Namen des bereits vorhandenen Hubs identisch ist.

Wenn Sie das Flag --replace in den Importbefehl einschließen, werden die folgenden IoT-Hub-Aspekte vor dem Hochladen des Hubzustands aus dem Zielhub entfernt:

  • ARM: Alle ggf. hochgeladenen Zertifikate auf dem Zielhub werden gelöscht. Ist ein Zertifikat vorhanden, benötigt es ein ETag, um aktualisiert zu werden.
  • Geräte: Alle Geräte und Module werden gelöscht. Das gilt sowohl für Edgegeräte/-module als auch für Nicht-Edgegeräte/-module.
  • Konfigurationen: Alle ADM-Konfigurationen und IoT Edge-Bereitstellungen werden gelöscht.

Migrieren eines IoT-Hubs

Verwenden Sie den Befehl az iot hub state migrate, um den Zustand eines IoT-Hubs zu einem neuen oder bereits vorhandenen IoT-Hub zu migrieren.

Dieser Befehl schließt die Export- und Importschritte in einen einzelnen Befehl ein, verfügt aber über keine Ausgabedateien. Alle Informationen und Einschränkungen, die in den Abschnitten Exportieren des Zustands eines IoT-Hubs und Importieren des Zustands eines IoT-Hubs beschrieben werden, gelten auch für den Befehl state migrate.

Wenn Sie eine Geräteregistrierung mit zahlreichen Geräten migrieren (etwa mit mehreren hundert oder tausend Geräten), ist es ggf. einfacher und schneller, die Export- und Importbefehle separat auszuführen, anstatt den Befehl „migrate“ zu verwenden.

Parameter Details
--aspects Die zu migrierenden Zustandsaspekte. Geben Sie mindestens einen der zulässigen Werte an: arm (ARM), configurations (Konfigurationen) oder devices (Geräte). Ohne Angabe dieses Parameters werden alle drei Aspekte migriert.
--replace -r Bei Angabe dieses Parameters löscht der Migrationsbefehl den aktuellen Zustand des Zielhubs.
--destination-hub --dh
or
--destination-hub-login --dl		 Der Name des Ziel-IoT-Hubs (--dh) oder die Verbindungszeichenfolge für den Ziel-IoT-Hub (--dl). Bei Angabe beider Optionen hat die Verbindungszeichenfolge Vorrang.
--destination-resource-group --dg Der Name der Ressourcengruppe für den Ziel-IoT-Hub. Die Zielressourcengruppe ist erforderlich, wenn der Zielhub nicht vorhanden ist.
--origin-hub --oh
or
--origin-hub-login --ol		 Der Name des Ursprungs-IoT-Hubs (--oh) oder die Verbindungszeichenfolge für den Ursprungs-IoT-Hub (--ol). Bei Angabe beider Optionen hat die Verbindungszeichenfolge Vorrang. Verwenden Sie die Verbindungszeichenfolge, um die Anmeldung bei der Azure CLI-Sitzung zu vermeiden.
--origin-resource-group --og Der Name der Ressourcengruppe für den Ursprungs-IoT-Hub.

Im folgenden Beispiel werden alle Aspekte des Ursprungshubs zum Zielhub migriert, und dieser wird erstellt, falls er nicht vorhanden ist:

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

Problembehandlung bei einer Migration

Wenn Sie keine Geräte oder Konfigurationen exportieren oder importieren können, überprüfen Sie, ob Sie Zugriff auf diese Eigenschaften haben. Zur Überprüfung Ihres Zugriffs können Sie beispielsweise den Befehl az iot hub device-identity list bzw. az iot hub configuration list ausführen.

Ist der Befehl az iot hub state migrate nicht erfolgreich, versuchen Sie, die Export- und Importbefehle separat auszuführen. Die beiden Befehle haben zwar die gleiche Funktion wie der Migrationsbefehl, bei separater Ausführung können Sie jedoch die Zustandsdateien überprüfen, die durch den Exportbefehl erstellt werden.

Nächste Schritte

Weitere Informationen zum Ausführen von Massenvorgängen für die Identitätsregistrierung in einem IoT-Hub finden Sie unter Importieren und Exportieren von IoT Hub-Geräteidentitäten per Massenvorgang.