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

Artikel
12/11/2024

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:

Voer een upgrade uit van de gratis laag naar een IoT-hub met een Basic- of Standard-laag.
Een IoT-hub verplaatsen naar een nieuwe regio.
Gegevens over ioT-hubstatussen exporteren als back-up.
Verhoog het aantal partities voor een IoT-hub.
Stel een hub in voor een ontwikkeling, in plaats van 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. Voordat u begint, moet u bepalen welk proces geschikt is voor uw scenario.

Het Azure CLI-proces (dit artikel):
- Migreert uw apparaatregister, uw 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 verbindingsreeks s voor routerings- en bestandsuploadeindpunten die gebruikmaken van verificatie op basis van sleutels en deze bevat in de uitvoer van de ARM-sjabloon.
Het handmatige proces:
- Hiermee worden uw apparaatregister en uw routerings- en eindpuntgegevens gemigreerd. U moet handmatig andere configuratiegegevens 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.
- Scrubs verbindingsreeks s voor routerings- en bestandsuploadeindpunten die gebruikmaken van verificatie op basis van sleutels uit de uitvoer van de ARM-sjabloon. U moet ze handmatig opnieuw toevoegen.

Vereisten

Azure-CLI

Voor de functies die in dit artikel worden beschreven, is versie 0.20.0 of hoger van de azure-iot-extensie vereist. Voer de extensieversie uit az --versionom de extensieversie te controleren. Als u de extensie wilt bijwerken, voert u het volgende uit az extension update --name azure-iot.

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

IoT Hub-status

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 Azure Portal hebt geëxporteerd. Informatie die is vastgelegd als onderdeel van het azure Resource Manager-aspect omvat:
- Ingebouwde retentietijd van Event Hub
- Certificaten
- Cloud-naar-apparaat-eigenschappen
- APPARAAT-SAS uitschakelen
- Lokale verificatie uitschakelen
- Meldingen voor het uploaden van bestanden inschakelen
- Opslageindpunt voor het uploaden van bestanden
- 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 is bedoeld 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.
(P.R.D). Dit aspect vertegenwoordigt de informatie in het 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 correct 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 verderop in dit artikel om een IoT-hub te migreren.

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 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 ioT-hub (`-n`) of de verbindingsreeks voor de oorspronkelijke IoT-hub (`-l`). Als beide worden opgegeven, heeft de verbindingsreeks 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, haalt de exportopdracht de verbindingsreeks s op voor eindpunten die verificatie op basis van sleutels hebben en deze opnemen in de ARM-uitvoersjabloon.

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

De status van een IoT-hub importeren

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

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

Parameter	DETAILS
`--aspects`	De statusaspecten die moeten worden geïmporteerd. Geef een of meer 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 ioT-doelhub (`-n`) of de verbindingsreeks voor de doel-IoT-hub (`-l`). Als beide worden opgegeven, heeft de verbindingsreeks 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 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 naar een bestaande IoT-hub te schrijven.

Als u een nieuwe IoT Hub wilt maken, moet u het arm aspect in de importopdracht opnemen. Als arm deze 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 ioT-doelhub al bestaat, is het arm aspect niet vereist voor de az iot hub state import opdracht. Als u het arm aspect wel opneemt, worden alle resource-eigenschappen overschreven, met uitzondering van de volgende eigenschappen die niet kunnen worden gewijzigd nadat de hub is gemaakt:

Locatie
SKU
Ingebouwd aantal Event Hubs-partities
Gegevensresidentie
Functies

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

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

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

Een IoT-hub migreren

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

Met deze opdracht worden de export- en importstappen in één opdracht verpakt, maar er zijn geen uitvoerbestanden. Alle richtlijnen en beperkingen die worden beschreven in de secties Exporteren van 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), is het eenvoudiger en sneller om de opdrachten voor exporteren en importeren 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 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 ioT-doelhub (`--dh`) of de verbindingsreeks voor de doel-IoT-hub (`--dl`). Als beide worden opgegeven, heeft de verbindingsreeks 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 ioT-hub (`--oh`) of de verbindingsreeks voor de oorspronkelijke IoT-hub (`--ol`). Als beide worden opgegeven, heeft de verbindingsreeks prioriteit. Gebruik de verbindingsreeks 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 origin-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 apparaten of configuraties niet 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 of az iot hub configuration list opdrachten uit te voeren.

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

Volgende stappen

Zie IoT Hub-apparaatidentiteiten importeren en exporteren voor meer informatie over het uitvoeren van bulkbewerkingen op basis van het identiteitsregister in een IoT-hub.

Delen via