Jak automatycznie migrować centrum IoT przy użyciu interfejsu wiersza polecenia platformy Azure

  • Artykuł

Użyj interfejsu wiersza polecenia platformy Azure, aby przeprowadzić migrację centrum IoT do nowego regionu, nowej warstwy lub nowej konfiguracji.

Kroki opisane w tym artykule są przydatne, jeśli chcesz:

  • Przeprowadź uaktualnienie z warstwy Bezpłatna do centrum IoT w warstwie Podstawowa lub Standardowa.
  • Przenieś centrum IoT do nowego regionu.
  • Wyeksportuj informacje o stanie centrum IoT, aby utworzyć kopię zapasową.
  • Zwiększ liczbę partycji dla centrum IoT.
  • Konfigurowanie centrum na potrzeby programowania, a nie środowiska produkcyjnego.

Porównanie kroków migracji automatycznej i ręcznej

Wynik tego artykułu jest podobny do tego, jak migrować centrum Azure IoT Hub przy użyciu szablonów usługi Azure Resource Manager, ale z innym procesem. Przed rozpoczęciem zdecyduj, który proces jest odpowiedni dla danego scenariusza.

  • Proces interfejsu wiersza polecenia platformy Azure (ten artykuł):

    • Migruje rejestr urządzeń, informacje o routingu i punkcie końcowym oraz inne szczegóły konfiguracji, takie jak wdrożenia IoT Edge lub konfiguracje automatycznego zarządzania urządzeniami.
    • Jest łatwiejsze w przypadku migrowania niewielkiej liczby urządzeń (na przykład do 10 000).
    • Nie wymaga konta usługi Azure Storage.
    • Zbiera parametry połączenia dla punktów końcowych routingu i przekazywania plików oraz dołącza je do danych wyjściowych szablonu usługi ARM.

  • Proces ręczny:

    • Migruje rejestr urządzeń oraz informacje o routingu i punkcie końcowym. Musisz ręcznie ponownie utworzyć inne szczegóły konfiguracji w nowym centrum IoT.
    • Migrowanie dużej liczby urządzeń (na przykład ponad 100 000).
    • Używa konta usługi Azure Storage do transferu rejestru urządzeń.
    • Czyści parametry połączenia routingu i przekazywania plików z danych wyjściowych szablonu usługi ARM i należy je ręcznie dodać.

Wymagania wstępne

  • Interfejs wiersza polecenia platformy Azure

    Funkcje opisane w tym artykule wymagają wersji 0.20.0 lub nowszej rozszerzenia azure-iot . Aby sprawdzić wersję rozszerzenia, uruchom polecenie az --version. Aby zaktualizować rozszerzenie, uruchom polecenie az extension update --name azure-iot.

    Jeśli nadal masz zainstalowane starsze rozszerzenie azure-cli-iot-ext , usuń to rozszerzenie przed dodaniem rozszerzenia azure-iot .

Stan centrum IoT

Gdy mówimy o migracji stanu centrum IoT, odwołujemy się do kombinacji trzech aspektów:

  • Zasoby usługi Azure Resource Manager (ARM). Ten aspekt jest wszystkim, co można zdefiniować w szablonie zasobu i jest tymi samymi informacjami, które można uzyskać w przypadku wyeksportowania szablonu zasobu z centrum IoT w Azure Portal. Informacje przechwycone w ramach aspektu usługi Azure Resource Manager obejmują:

    • Wbudowany czas przechowywania centrum zdarzeń
    • Certyfikaty
    • Właściwości chmury do urządzenia
    • Wyłączanie sygnatury dostępu współdzielonego urządzenia
    • Wyłączanie uwierzytelniania lokalnego
    • Włączanie powiadomień o przekazywaniu plików
    • Punkt końcowy magazynu przekazywania plików
    • Tożsamości
      • Tożsamości przypisane przez użytkownika
      • Tożsamości przypisane przez system (włączone lub wyłączone)
    • Zestawy reguł sieci
    • Routing
      • Niestandardowe punkty końcowe
      • Trasa powrotu
      • Trasy
    • Tagi

  • Konfiguracji. Ten aspekt dotyczy aspektów centrum IoT, które nie są reprezentowane w szablonie usługi ARM. W szczególności ten aspekt obejmuje konfiguracje automatycznego zarządzania urządzeniami i wdrożenia IoT Edge.

  • Urządzeń. Ten aspekt reprezentuje informacje w rejestrze urządzeń, w tym:

    • Tożsamości urządzeń i bliźniacze reprezentacje
    • Tożsamości modułów i bliźniacze reprezentacje

Każda właściwość IoT Hub lub konfiguracja, która nie jest wymieniona w tym miejscu, może nie zostać wyeksportowana ani zaimportowana poprawnie.

Eksportowanie stanu centrum IoT

Użyj polecenia az iot hub state export , aby wyeksportować stan centrum IoT do pliku JSON.

Jeśli chcesz uruchomić kroki eksportowania i importowania w jednym poleceniu, zapoznaj się z sekcją w dalszej części tego artykułu w temacie Migrate an IoT Hub (Migrowanie centrum IoT Hub).

Podczas eksportowania stanu centrum IoT można wybrać aspekty do wyeksportowania.

Parametr Szczegóły
--aspects Aspekty stanu do wyeksportowania. Określ co najmniej jedną akceptowaną wartość: arm, konfiguracje lub urządzenia. Jeśli ten parametr zostanie pominięty, wszystkie trzy aspekty zostaną wyeksportowane.
--state-file -f Ścieżka do pliku, w którym zapisywane są informacje o stanie.
--replace -r Jeśli ten parametr jest dołączony, polecenie eksportu zastępuje zawartość pliku stanu.
--hub-name -n
Lub
--login -l		 Nazwa źródła centrum IoT (-n) lub parametry połączenia dla centrum IoT źródła (-l). Jeśli podano oba parametry połączenia, mają priorytet.
--resource-group -g Nazwa grupy zasobów dla centrum IoT pochodzenia.

Poniższy przykład eksportuje wszystkie aspekty stanu centrum IoT do pliku o nazwie myHub-state:

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

Poniższy przykład eksportuje tylko urządzenia i aspekty usługi Azure Resource Manager stanu centrum IoT i zastępują zawartość istniejącego pliku:

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

Eksportowanie punktów końcowych

Jeśli zdecydujesz się wyeksportować aspekt usługi Azure Resource Manager centrum IoT, polecenie eksportu pobierze parametry połączenia dla wszystkich punktów końcowych z uwierzytelnianiem opartym na kluczach i dołączy je do wyjściowego szablonu usługi ARM.

Polecenie eksportu sprawdza również wszystkie punkty końcowe, aby sprawdzić, czy zasób, z który nawiązuje połączenie, nadal istnieje. Jeśli nie, ten punkt końcowy i wszystkie trasy używające tego punktu końcowego nie są eksportowane.

Importowanie stanu centrum IoT

Użyj polecenia az iot hub state import , aby zaimportować informacje o stanie z wyeksportowanego pliku do nowego lub istniejącego centrum IoT.

Jeśli chcesz uruchomić kroki eksportowania i importowania w jednym poleceniu, zapoznaj się z sekcją w dalszej części tego artykułu w temacie Migrate an IoT Hub (Migrowanie centrum IoT Hub).

Parametr Szczegóły
--aspects Aspekty stanu do zaimportowania. Określ co najmniej jedną akceptowaną wartość: arm, konfiguracje lub urządzenia. Jeśli ten parametr zostanie pominięty, zostaną zaimportowane wszystkie trzy aspekty.
--state-file -f Ścieżka do wyeksportowanego pliku stanu.
--replace -r Jeśli ten parametr jest dołączony, polecenie importu usuwa bieżący stan centrum docelowego.
--hub-name -n
Lub
--login -l		 Nazwa docelowego centrum IoT (-n) lub parametry połączenia dla docelowego centrum IoT (-l). Jeśli podano oba parametry połączenia, mają priorytet.
--resource-group -g Nazwa grupy zasobów dla docelowego centrum IoT.

Poniższy przykład importuje wszystkie aspekty do nowego centrum IoT, które zostało utworzone, jeśli jeszcze nie istnieje:

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

Poniższy przykład importuje tylko aspekty urządzeń i konfiguracji do nowego centrum IoT, które musi już istnieć, i zastępuje wszystkie istniejące urządzenia i konfiguracje:

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

Tworzenie nowego centrum IoT z importem stanu

Możesz użyć az iot hub state import polecenia , aby utworzyć nowe centrum IoT lub zapisać w istniejącym centrum IoT.

Jeśli chcesz utworzyć nowy IoT Hub, musisz uwzględnić arm aspekt w poleceniu importu. Jeśli arm polecenie nie jest uwzględnione w poleceniu, a centrum docelowe nie istnieje, polecenie importowania kończy się niepowodzeniem.

Jeśli centrum docelowe nie istnieje, parametr --resource-group jest również wymagany dla polecenia importu.

Aktualizowanie istniejącego centrum IoT przy użyciu importowania stanu

Jeśli docelowe centrum IoT już istnieje, arm aspekt nie jest wymagany dla az iot hub state import polecenia. Jeśli uwzględnisz arm aspekt, wszystkie właściwości zasobu zostaną zastąpione z wyjątkiem następujących właściwości, których nie można zmienić po utworzeniu centrum:

  • Lokalizacja
  • SKU
  • Wbudowana liczba partycji usługi Event Hubs
  • Rezydencja danych
  • Funkcje

Jeśli element --resource-group jest określony w poleceniu importu i różni się od bieżącej grupy zasobów centrum IoT Hub, polecenie kończy się niepowodzeniem, ponieważ próbuje utworzyć nowe centrum o tej samej nazwie co ta, która już istnieje.

Jeśli flaga --replace zostanie dołączona do polecenia importu, następujące aspekty centrum IoT zostaną usunięte z centrum docelowego przed przekazaniem stanu centrum:

  • ARM: Wszystkie przekazane certyfikaty w centrum docelowym są usuwane. Jeśli certyfikat jest obecny, musi zostać zaktualizowany tag etag.
  • Urządzenia: wszystkie urządzenia i moduły, brzegowe i inne niż brzegowe, są usuwane.
  • Konfiguracje: wszystkie konfiguracje usługi ADM i wdrożenia IoT Edge są usuwane.

Migrowanie centrum IoT

Użyj polecenia az iot hub state migrate , aby przeprowadzić migrację stanu jednego centrum IoT do nowego lub istniejącego centrum IoT.

To polecenie opakowuje kroki eksportu i importowania do jednego polecenia, ale nie zawiera plików wyjściowych. Wszystkie wskazówki i ograniczenia opisane w artykule Eksportowanie stanu centrum IoT i Importowanie stanu centrum IoT mają zastosowanie również do state migrate polecenia.

Jeśli migrujesz rejestr urządzeń z wieloma urządzeniami (na przykład kilkaset lub kilka tysięcy), możesz łatwiej i szybciej uruchomić polecenia eksportu i importu zamiast uruchamiać polecenie migracji.

Parametr Szczegóły
--aspects Aspekty stanu do migracji. Określ co najmniej jedną akceptowaną wartość: arm, konfiguracje lub urządzenia. Jeśli ten parametr zostanie pominięty, wszystkie trzy aspekty zostaną zmigrowane.
--replace -r Jeśli ten parametr zostanie uwzględniony, polecenie migracji usunie bieżący stan centrum docelowego.
--destination-hub --dh
Lub
--destination-hub-login --dl		 Nazwa docelowego centrum IoT (--dh) lub parametry połączenia dla docelowego centrum IoT (--dl). Jeśli podano oba parametry połączenia, mają priorytet.
--destination-resource-group --dg Nazwa grupy zasobów docelowej centrum IoT. Docelowa grupa zasobów jest wymagana, jeśli centrum docelowe nie istnieje.
--origin-hub --oh
Lub
--origin-hub-login --ol		 Nazwa źródła centrum IoT (--oh) lub parametry połączenia dla źródła centrum IoT (--ol). Jeśli podano oba parametry połączenia, mają priorytet. Użyj parametrów połączenia, aby uniknąć konieczności logowania się do sesji interfejsu wiersza polecenia platformy Azure.
--origin-resource-group --og Nazwa grupy zasobów dla centrum IoT pochodzenia.

W poniższym przykładzie wszystkie aspekty centrum początkowego są migrowane do centrum docelowego, które jest tworzone, jeśli nie istnieje:

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

Rozwiązywanie problemów z migracją

Jeśli nie możesz eksportować ani importować urządzeń lub konfiguracji, sprawdź, czy masz dostęp do tych właściwości. Jednym ze sposobów weryfikacji dostępu jest uruchomienie az iot hub device-identity list poleceń lub az iot hub configuration list .

az iot hub state migrate Jeśli polecenie zakończy się niepowodzeniem, spróbuj uruchomić polecenia eksportu i importu oddzielnie. Dwa polecenia powodują takie same funkcje, jak tylko polecenie migracji, ale uruchamiając je oddzielnie, można przejrzeć pliki stanu utworzone na podstawie polecenia eksportu.

Następne kroki

Aby uzyskać więcej informacji na temat wykonywania operacji zbiorczych względem rejestru tożsamości w centrum IoT, zobacz Importowanie i eksportowanie tożsamości urządzeń IoT Hub.