Een IoT-hub automatisch migreren met behulp van de Azure CLI

  • Artikel

Gebruik de Azure CLI om een IoT-hub te migreren naar een nieuwe regio, een nieuwe laag of een nieuwe configuratie.

De stappen in dit artikel zijn handig als u het volgende wilt doen:

  • Upgrade van de gratis laag naar een Basic- of Standard-laag IoT-hub.
  • Een IoT-hub verplaatsen naar een nieuwe regio.
  • De statusgegevens van de IoT-hub exporteren om deze als back-up te gebruiken.
  • Verhoog het aantal partities voor een IoT-hub.
  • Stel een hub in voor een ontwikkelomgeving in plaats van een productieomgeving.

Automatische en handmatige migratiestappen vergelijken

Het resultaat van dit artikel is vergelijkbaar met Het migreren van een Azure IoT-hub met behulp van Azure Resource Manager-sjablonen, maar met een ander proces. Bepaal voordat u begint welk proces geschikt is voor uw scenario.

  • Het Azure CLI-proces (dit artikel):

    • Migreert uw apparaatregister, routerings- en eindpuntgegevens en andere configuratiegegevens, zoals IoT Edge implementaties of automatische configuraties voor apparaatbeheer.
    • Is eenvoudiger voor het migreren van kleine aantallen apparaten (bijvoorbeeld tot 10.000).
    • Hiervoor is geen Azure Storage-account vereist.
    • Verzamelt verbindingsreeksen voor routering en eindpunten voor het uploaden van bestanden en neemt deze op in de uitvoer van de ARM-sjabloon.

  • Het handmatige proces:

    • Migreert uw apparaatregister en uw routerings- en eindpuntgegevens. U moet andere configuratiegegevens handmatig opnieuw maken in de nieuwe IoT-hub.
    • Is sneller voor het migreren van grote aantallen apparaten (bijvoorbeeld meer dan 100.000).
    • Maakt gebruik van een Azure Storage-account om het apparaatregister over te dragen.
    • Hiermee verwijdert u verbindingsreeksen voor routering en eindpunten voor het uploaden van bestanden vanuit de uitvoer van de ARM-sjabloon. U moet deze handmatig opnieuw toevoegen.

Vereisten

  • Azure CLI

    Voor de functies die in dit artikel worden beschreven, is versie 0.20.0 of hoger van de extensie azure-iot vereist. Voer uit az --versionom uw extensieversie te controleren. Voer uit om uw extensie bij te werken az extension update --name azure-iot.

    Als u nog steeds de verouderde extensie azure-cli-iot-ext hebt geïnstalleerd, verwijdert u die extensie voordat u de extensie azure-iot toevoegt.

IoT-hubstatus

Wanneer we het hebben over het migreren van de status van een IoT-hub, verwijzen we naar een combinatie van drie aspecten:

  • Arm-resources (Azure Resource Manager). Dit aspect is alles wat kan worden gedefinieerd in een resourcesjabloon en is dezelfde informatie die u krijgt als u de resourcesjabloon uit uw IoT-hub in de Azure Portal exporteert. Informatie die is vastgelegd als onderdeel van het Azure Resource Manager-aspect omvat:

    • De retentietijd van de ingebouwde Event Hub
    • Certificaten
    • Cloud-naar-apparaat-eigenschappen
    • APPARAAT-SAS uitschakelen
    • Lokale verificatie uitschakelen
    • Uploadmeldingen voor bestanden inschakelen
    • Opslageindpunt voor bestandsupload
    • Identiteiten
      • Door de gebruiker toegewezen identiteiten
      • Door het systeem toegewezen identiteiten (ingeschakeld of uitgeschakeld)
    • Netwerkregelsets
    • Routering
      • Aangepaste eindpunten
      • Alternatieve route
      • Routes
    • Tags

  • Configuraties. Dit aspect geldt voor aspecten van een IoT-hub die niet worden weergegeven in een ARM-sjabloon. Dit aspect omvat met name automatische configuraties voor apparaatbeheer en IoT Edge implementaties.

  • Apparaten. Dit aspect vertegenwoordigt de informatie in uw apparaatregister, waaronder:

    • Apparaat-id's en dubbels
    • Module-identiteiten en -dubbels

Een IoT Hub eigenschap of configuratie die hier niet wordt vermeld, wordt mogelijk niet juist geëxporteerd of geïmporteerd.

De status van een IoT-hub exporteren

Gebruik de opdracht az iot hub state export om de status van een IoT-hub te exporteren naar een JSON-bestand.

Als u zowel de export- als importstappen in één opdracht wilt uitvoeren, raadpleegt u de sectie een IoT-hub migreren verderop in dit artikel.

Wanneer u de status van een IoT-hub exporteert, kunt u kiezen welke aspecten u wilt exporteren.

Parameter Details
--aspects De statusaspecten die moeten worden geëxporteerd. Geef een of meer van de geaccepteerde waarden op: arm, configuraties of apparaten. Als deze parameter wordt weggelaten, worden alle drie de aspecten geëxporteerd.
--state-file -f Het pad naar het bestand waarin de statusinformatie wordt geschreven.
--replace -r Als deze parameter is opgenomen, overschrijft de exportopdracht de inhoud van het statusbestand.
--hub-name -n
or
--login -l		 De naam van de oorspronkelijke IoT-hub (-n) of de connection string voor de oorspronkelijke IoT-hub (-l). Als beide zijn opgegeven, heeft de connection string prioriteit.
--resource-group -g De naam van de resourcegroep voor de oorspronkelijke IoT-hub.

In het volgende voorbeeld worden alle aspecten van de status van een IoT-hub geëxporteerd naar een bestand met de naam myHub-state:

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

In het volgende voorbeeld worden alleen de apparaten en Azure Resource Manager aspecten van de status van een IoT-hub geëxporteerd en wordt de inhoud van het bestaande bestand overschreven:

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

Eindpunten exporteren

Als u ervoor kiest om het Azure Resource Manager aspect van een IoT-hub te exporteren, worden met de exportopdracht de verbindingsreeksen opgehaald voor alle eindpunten met verificatie op basis van sleutels en worden deze opgenomen in de ARM-uitvoersjabloon.

De exportopdracht controleert ook alle eindpunten om te controleren of de resource waarmee deze verbinding maakt, nog steeds bestaat. Als dat niet het geval is, worden dat eindpunt en eventuele routes die dat eindpunt gebruiken, niet geëxporteerd.

De status van een IoT-hub importeren

Gebruik de opdracht az iot hub state import om statusgegevens uit een geëxporteerd bestand te importeren in een nieuwe of bestaande IoT-hub.

Als u zowel de export- als importstappen in één opdracht wilt uitvoeren, raadpleegt u de sectie een IoT-hub migreren verderop in dit artikel.

Parameter Details
--aspects De statusaspecten die moeten worden geïmporteerd. Geef een of meer van de geaccepteerde waarden op: arm, configuraties of apparaten. Als deze parameter wordt weggelaten, worden alle drie de aspecten geïmporteerd.
--state-file -f Het pad naar het geëxporteerde statusbestand.
--replace -r Als deze parameter is opgenomen, verwijdert de importopdracht de huidige status van de doelhub.
--hub-name -n
or
--login -l		 De naam van de doel-IoT-hub (-n) of de connection string voor de doel-IoT-hub (-l). Als beide zijn opgegeven, heeft de connection string prioriteit.
--resource-group -g De naam van de resourcegroep voor de doel-IoT-hub.

In het volgende voorbeeld worden alle aspecten geïmporteerd in een nieuwe IoT-hub, die wordt gemaakt als deze nog niet bestaat:

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

In het volgende voorbeeld worden alleen de aspecten van apparaten en configuraties geïmporteerd in een nieuwe IoT-hub, die al moet bestaan, en worden alle bestaande apparaten en configuraties overschreven:

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

Een nieuwe IoT-hub maken met statusimport

U kunt de az iot hub state import opdracht gebruiken om een nieuwe IoT-hub te maken of om naar een bestaande IoT-hub te schrijven.

Als u een nieuwe IoT Hub wilt maken, moet u het arm aspect opnemen in de importopdracht. Als arm niet is opgenomen in de opdracht en de doelhub niet bestaat, mislukt de importopdracht.

Als de doelhub niet bestaat, is de --resource-group parameter ook vereist voor de importopdracht.

Een bestaande IoT-hub bijwerken met statusimport

Als de doel-IoT-hub al bestaat, is het arm aspect niet vereist voor de az iot hub state import opdracht. Als u het arm aspect opneemt, worden alle resource-eigenschappen overschreven, met uitzondering van de volgende eigenschappen die niet kunnen worden gewijzigd nadat de hub is gemaakt:

  • Locatie
  • SKU
  • Aantal ingebouwde Event Hubs-partities
  • Gegevenslocatie
  • Functies

Als de --resource-group is opgegeven in de importopdracht en verschilt van de huidige resourcegroep van IoT Hub, mislukt de opdracht omdat wordt geprobeerd een nieuwe hub te maken met dezelfde naam als de hub die al bestaat.

Als u de --replace vlag opneemt in de importopdracht, worden de volgende IoT-hub-aspecten verwijderd uit de doelhub voordat de hubstatus wordt geüpload:

  • ARM: alle geüploade certificaten op de doelhub worden verwijderd. Als een certificaat aanwezig is, moet er een etag worden bijgewerkt.
  • Apparaten: alle apparaten en modules, edge en niet-edge, worden verwijderd.
  • Configuraties: alle ADM-configuraties en IoT Edge implementaties worden verwijderd.

Een IoT-hub migreren

Gebruik de opdracht az iot hub state migrate om de status van een IoT-hub te migreren naar een nieuwe of bestaande IoT-hub.

Met deze opdracht worden de export- en importstappen verpakt in één opdracht, maar er zijn geen uitvoerbestanden. Alle richtlijnen en beperkingen die worden beschreven in de secties De status van een IoT-hub exporteren en De status van een IoT-hub importeren zijn ook van toepassing op de state migrate opdracht.

Als u een apparaatregister migreert met veel apparaten (bijvoorbeeld een paar honderd of een paar duizend), vindt u het mogelijk gemakkelijker en sneller om de export- en importopdrachten afzonderlijk uit te voeren in plaats van de migratieopdracht uit te voeren.

Parameter Details
--aspects De statusaspecten die moeten worden gemigreerd. Geef een of meer van de geaccepteerde waarden op: arm, configuraties of apparaten. Als deze parameter wordt weggelaten, worden alle drie de aspecten gemigreerd.
--replace -r Als deze parameter is opgenomen, verwijdert de migratieopdracht de huidige status van de doelhub.
--destination-hub --dh
or
--destination-hub-login --dl		 De naam van de doel-IoT-hub (--dh) of de connection string voor de doel-IoT-hub (--dl). Als beide zijn opgegeven, heeft de connection string prioriteit.
--destination-resource-group --dg Naam van de resourcegroep voor de doel-IoT-hub. De doelresourcegroep is vereist als de doelhub niet bestaat.
--origin-hub --oh
or
--origin-hub-login --ol		 De naam van de oorspronkelijke IoT-hub (--oh) of de connection string voor de oorspronkelijke IoT-hub (--ol). Als beide zijn opgegeven, heeft de connection string prioriteit. Gebruik de connection string om te voorkomen dat u zich moet aanmelden bij de Azure CLI-sessie.
--origin-resource-group --og De naam van de resourcegroep voor de oorspronkelijke IoT-hub.

In het volgende voorbeeld worden alle aspecten van de oorspronkelijke hub gemigreerd naar de doelhub, die wordt gemaakt als deze niet bestaat:

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

Problemen met een migratie oplossen

Als u geen apparaten of configuraties kunt exporteren of importeren, controleert u of u toegang hebt tot deze eigenschappen. Een manier om uw toegang te controleren, is door de az iot hub device-identity list opdrachten of az iot hub configuration list uit te voeren.

Als de az iot hub state migrate opdracht mislukt, voert u de export- en importopdrachten afzonderlijk uit. De twee opdrachten resulteren in dezelfde functionaliteit als de migratieopdracht alleen, maar door ze afzonderlijk uit te voeren, kunt u de statusbestanden controleren die zijn gemaakt met de exportopdracht.

Volgende stappen

Zie Import and export IoT Hub device identities (IoT Hub apparaatidentiteiten importeren en exporteren) voor meer informatie over het uitvoeren van bulkbewerkingen op het identiteitsregister in een IoT-hub.