Så här migrerar du automatiskt en IoT-hubb med Hjälp av Azure CLI

Artikel
04/16/2023

Använd Azure CLI för att migrera en IoT-hubb till en ny region, en ny nivå eller en ny konfiguration.

Stegen i den här artikeln är användbara om du vill:

Uppgradera från den kostnadsfria nivån till en IoT-hubb på basic- eller standardnivå.
Flytta en IoT-hubb till en ny region.
Exportera IoT Hub-tillståndsinformation som ska ha som en säkerhetskopia.
Öka antalet partitioner för en IoT-hubb.
Konfigurera en hubb för en utvecklingsmiljö i stället för en produktionsmiljö.

Jämför automatiska och manuella migreringssteg

Resultatet av den här artikeln liknar hur du migrerar en Azure IoT-hubb med hjälp av Azure Resource Manager-mallar, men med en annan process. Innan du börjar ska du bestämma vilken process som passar ditt scenario.

Azure CLI-processen (den här artikeln):
- Migrerar ditt enhetsregister, din routnings- och slutpunktsinformation och annan konfigurationsinformation som IoT Edge distributioner eller konfigurationer för automatisk enhetshantering.
- Är enklare att migrera ett litet antal enheter (till exempel upp till 10 000).
- Kräver inget Azure Storage-konto.
- Samlar in anslutningssträngar för routning och filuppladdningsslutpunkter och inkluderar dem i ARM-mallens utdata.
Den manuella processen:
- Migrerar ditt enhetsregister och din routnings- och slutpunktsinformation. Du måste återskapa annan konfigurationsinformation manuellt i den nya IoT-hubben.
- Går snabbare att migrera ett stort antal enheter (till exempel mer än 100 000).
- Använder ett Azure Storage-konto för att överföra enhetsregistret.
- Rensar anslutningssträngar för routning och filuppladdningsslutpunkter från ARM-mallens utdata, och du måste lägga till dem manuellt igen.

Förutsättningar

Azure CLI

Funktionerna som beskrivs i den här artikeln kräver version 0.20.0 eller senare av azure-iot-tillägget . Kontrollera tilläggsversionen genom att köra az --version. Om du vill uppdatera tillägget kör du az extension update --name azure-iot.

Om du fortfarande har det äldre azure-cli-iot-ext-tillägget installerat tar du bort tillägget innan du lägger till azure-iot-tillägget .

IoT-hubbtillstånd

När vi talar om att migrera tillståndet för en IoT-hubb refererar vi till en kombination av tre aspekter:

Azure Resource Manager-resurser (ARM). Den här aspekten är allt som kan definieras i en resursmall och är samma information som du skulle få om du exporterade resursmallen från din IoT-hubb i Azure Portal. Information som samlas in som en del av Azure Resource Manager aspekten omfattar:
- Inbyggd kvarhållningstid för händelsehubben
- Certifikat
- Egenskaper för moln till enhet
- Inaktivera enhets-SAS
- Inaktivera lokal autentisering
- Aktivera meddelanden om filuppladdning
- Lagringsslutpunkt för filuppladdning
- Identiteter
  - Användartilldelade identiteter
  - Systemtilldelade identiteter (aktiverade eller inaktiverade)
- Nätverksregeluppsättningar
- Routning
  - Anpassade slutpunkter
  - Återställningsväg
  - Vägar
- Taggar
Konfigurationer. Den här aspekten gäller aspekter av en IoT-hubb som inte visas i en ARM-mall. Mer specifikt omfattar den här aspekten automatiska enhetshanteringskonfigurationer och IoT Edge distributioner.
Enheter. Den här aspekten representerar informationen i enhetsregistret, som omfattar:
- Enhetsidentiteter och tvillingar
- Modulidentiteter och tvillingar

Alla IoT Hub egenskapen eller konfigurationen som inte visas här kan inte exporteras eller importeras korrekt.

Exportera tillståndet för en IoT-hubb

Använd kommandot az iot hub state export för att exportera tillståndet för en IoT-hubb till en JSON-fil.

Om du vill köra både export- och importstegen i ett kommando läser du avsnittet senare i den här artikeln till Migrera en IoT-hubb.

När du exporterar tillståndet för en IoT-hubb kan du välja vilka aspekter som ska exporteras.

Parameter	Information
`--aspects`	Tillståndsaspekterna som ska exporteras. Ange ett eller flera av de godkända värdena: arm, konfigurationer eller enheter. Om den här parametern utelämnas exporteras alla tre aspekterna.
`--state-file -f`	Sökvägen till filen där tillståndsinformationen skrivs.
`--replace -r`	Om den här parametern ingår skriver exportkommandot över innehållet i tillståndsfilen.
`--hub-name -n` Eller `--login -l`	Namnet på ursprungs-IoT-hubben (`-n`) eller anslutningssträngen för ursprungs-IoT-hubben (`-l`). Om båda anges prioriteras anslutningssträngen.
`--resource-group -g`	Namnet på resursgruppen för ursprungs-IoT-hubben.

I följande exempel exporteras alla aspekter av en IoT-hubbs tillstånd till en fil med namnet myHub-state:

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

I följande exempel exporteras endast enheterna och Azure Resource Manager aspekter av en IoT-hubbs tillstånd och skriver över innehållet i den befintliga filen:

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

Exportera slutpunkter

Om du väljer att exportera Azure Resource Manager aspekten av en IoT-hubb hämtar exportkommandot anslutningssträngarna för alla slutpunkter som har nyckelbaserad autentisering och inkluderar dem i ARM-utdatamallen.

Exportkommandot kontrollerar även alla slutpunkter för att kontrollera att resursen som den ansluter till fortfarande finns. Annars exporteras inte slutpunkten och eventuella vägar som använder slutpunkten.

Importera tillståndet för en IoT-hubb

Använd kommandot az iot hub state import för att importera tillståndsinformation från en exporterad fil till en ny eller befintlig IoT-hubb.

Om du vill köra både export- och importstegen i ett kommando läser du avsnittet senare i den här artikeln till Migrera en IoT-hubb.

Parameter	Information
`--aspects`	Tillståndsaspekterna som ska importeras. Ange ett eller flera av de godkända värdena: arm, konfigurationer eller enheter. Om den här parametern utelämnas importeras alla tre aspekterna.
`--state-file -f`	Sökvägen till den exporterade tillståndsfilen.
`--replace -r`	Om den här parametern ingår tar importkommandot bort målhubbens aktuella tillstånd.
`--hub-name -n` Eller `--login -l`	Namnet på mål-IoT-hubben (`-n`) eller anslutningssträngen för mål-IoT-hubben (`-l`). Om båda anges prioriteras anslutningssträngen.
`--resource-group -g`	Namnet på resursgruppen för mål-IoT-hubben.

I följande exempel importeras alla aspekter till en ny IoT-hubb, som skapas om den inte redan finns:

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

I följande exempel importeras endast enhets- och konfigurationsaspekterna till en ny IoT-hubb, som redan måste finnas, och skriver över alla befintliga enheter och konfigurationer:

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

Skapa en ny IoT-hubb med tillståndsimport

Du kan använda az iot hub state import kommandot för att skapa en ny IoT-hubb eller för att skriva till en befintlig IoT-hubb.

Om du vill skapa en ny IoT Hub måste du inkludera aspekten arm i importkommandot. Om arm inte ingår i kommandot och målhubben inte finns misslyckas importkommandot.

Om målhubben inte finns krävs även parametern --resource-group för importkommandot.

Uppdatera en befintlig IoT-hubb med tillståndsimport

Om mål-IoT-hubben redan finns krävs inte aspekten armaz iot hub state import för kommandot. Om du inkluderar aspekten arm skrivs alla resursegenskaper över förutom följande egenskaper som inte kan ändras när hubben har skapats:

Location
SKU
Inbyggt antal Event Hubs-partitioner
Dataplacering
Funktioner

--resource-group Om anges i importkommandot och skiljer sig från IoT Hubs aktuella resursgrupp misslyckas kommandot eftersom det försöker skapa en ny hubb med samma namn som den som redan finns.

Om du inkluderar --replace flaggan i importkommandot tas följande IoT Hub-aspekter bort från målhubben innan hubbens tillstånd laddas upp:

ARM: Alla uppladdade certifikat på målhubben tas bort. Om ett certifikat finns måste en etag uppdateras.
Enheter: Alla enheter och moduler, gränsenheter och icke-gränsenheter, tas bort.
Konfigurationer: Alla ADM-konfigurationer och IoT Edge distributioner tas bort.

Migrera en IoT-hubb

Använd kommandot az iot hub state migrate för att migrera tillståndet för en IoT-hubb till en ny eller befintlig IoT-hubb.

Det här kommandot omsluter export- och importstegen till ett enda kommando, men har inga utdatafiler. Alla riktlinjer och begränsningar som beskrivs i avsnittet Exportera tillståndet för en IoT-hubb och Importera tillståndet för en IoT Hub gäller även för state migrate kommandot.

Om du migrerar ett enhetsregister med många enheter (till exempel några hundra eller några tusen) kan det vara enklare och snabbare att köra export- och importkommandona separat i stället för att köra migreringskommandot.

Parameter	Information
`--aspects`	Tillståndsaspekterna som ska migreras. Ange ett eller flera av de godkända värdena: arm, konfigurationer eller enheter. Om den här parametern utelämnas migreras alla tre aspekterna.
`--replace -r`	Om den här parametern ingår tar kommandot migrering bort målhubbens aktuella tillstånd.
`--destination-hub --dh` Eller `--destination-hub-login --dl`	Namnet på mål-IoT-hubben (`--dh`) eller anslutningssträngen för mål-IoT-hubben (`--dl`). Om båda anges prioriteras anslutningssträngen.
`--destination-resource-group --dg`	Namnet på resursgruppen för mål-IoT-hubben. Målresursgruppen krävs om målhubben inte finns.
`--origin-hub --oh` Eller `--origin-hub-login --ol`	Namnet på ursprungs-IoT-hubben (`--oh`) eller anslutningssträngen för ursprungs-IoT-hubben (`--ol`). Om båda anges prioriteras anslutningssträngen. Använd anslutningssträngen för att undvika att behöva logga in på Azure CLI-sessionen.
`--origin-resource-group --og`	Namnet på resursgruppen för ursprungs-IoT-hubben.

I följande exempel migreras alla aspekter av ursprungshubben till målhubben, som skapas om den inte finns:

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

Felsöka en migrering

Om du inte kan exportera eller importera enheter eller konfigurationer kontrollerar du att du har åtkomst till dessa egenskaper. Ett sätt att verifiera din åtkomst är genom att köra kommandona az iot hub device-identity list eller az iot hub configuration list .

Om kommandot az iot hub state migrate misslyckas kan du prova att köra export- och importkommandona separat. De två kommandona resulterar i samma funktioner som enbart migreringskommandot, men genom att köra dem separat kan du granska tillståndsfilerna som skapas från exportkommandot.

Nästa steg

Mer information om hur du utför massåtgärder mot identitetsregistret i en IoT-hubb finns i Importera och exportera IoT Hub enhetsidentiteter.

Dela via