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

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

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

• Uaktualnij warstwę bezpłatną do centrum IoT w warstwie Podstawowa lub Standardowa.
• Przenieś centrum IoT do nowego regionu.
• Eksportowanie informacji o stanie centrum IoT w celu utworzenia kopii zapasowej.
• 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 sposobu migrowania 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 usługi IoT Edge lub konfiguracje automatycznego zarządzania urządzeniami.
  • Jest łatwiej migrować niewielką liczbę urządzeń (na przykład do 10 000).
  • Nie wymaga konta usługi Azure Storage.
  • Zbiera parametry połączenia na potrzeby routingu i przekazywania plików punktów końcowych korzystających z uwierzytelniania opartego na kluczach i uwzględnia je w 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 odtworzyć inne szczegóły konfiguracji w nowym centrum IoT.
  • Jest szybszy w przypadku migrowania dużej liczby urządzeń (na przykład ponad 100 000).
  • Używa konta usługi Azure Storage do transferu rejestru urządzeń.
  • Czyszczenie parametry połączenia dla punktów końcowych routingu i przekazywania plików, które używają uwierzytelniania opartego na kluczach z danych wyjściowych szablonu usługi ARM, i należy ręcznie dodać je z powrotem.

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, odnosimy 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 witrynie 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 lokalnego uwierzytelniania
  • Włączanie powiadomień dotyczących przekazywania 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ł sieciowych
  • Routingu
    • 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 automatyczne konfiguracje zarządzania urządzeniami i wdrożenia usługi IoT Edge.

• i stojaka (PRD). Ten aspekt reprezentuje informacje w rejestrze urządzeń, które obejmują:

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

Każda właściwość lub konfiguracja usługi IoT Hub, 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, aby przeprowadzić migrację centrum IoT.

Podczas eksportowania stanu centrum IoT można wybrać, które aspekty mają być eksportowane.

Parametr	Szczegóły
--aspects	Aspekty stanu do wyeksportowania. Określ co najmniej jedną zaakceptowaną wartość: arm, configurations lub devices. Jeśli ten parametr zostanie pominięty, zostaną wyeksportowane wszystkie trzy aspekty.
--state-file -f	Ścieżka do pliku, w którym są zapisywane informacje o stanie.
--replace -r	Jeśli ten parametr jest dołączony, polecenie eksportu zastępuje zawartość pliku stanu.
--hub-name -n or --login -l	Nazwa centrum IoT źródła (-n) lub parametry połączenia dla centrum IoT źródła (-l). Jeśli oba są podane, parametry połączenia ma 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 Hub 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órego nawiązuje połączenie, nadal istnieje. Jeśli nie, ten punkt końcowy i wszystkie trasy korzystające z 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, aby przeprowadzić migrację centrum IoT.

Parametr	Szczegóły
--aspects	Aspekty stanu do zaimportowania. Określ co najmniej jedną zaakceptowaną wartość: arm, configurations lub devices. 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 zostanie dołączony, polecenie importu usunie bieżący stan centrum docelowego.
--hub-name -n or --login -l	Nazwa docelowego centrum IoT (-n) lub parametry połączenia dla docelowego centrum IoT (-l). Jeśli oba są podane, parametry połączenia ma 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 importowaniem 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ć nową usługę IoT Hub, musisz uwzględnić arm aspekt w poleceniu importu. Jeśli arm nie znajduje się w poleceniu, a centrum docelowe nie istnieje, polecenie importu zakończy się niepowodzeniem.

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

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

Jeśli docelowe centrum IoT już istnieje, arm 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
• Przechowywanie danych
• Funkcje

Jeśli parametr --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 takiej samej nazwie jak ta, która już istnieje.

Jeśli flaga zostanie --replace uwzględniona w poleceniu 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 element etag.
• Urządzenia: wszystkie urządzenia i moduły, urządzenia brzegowe i inne niż brzegowe, są usuwane.
• Konfiguracje: wszystkie konfiguracje zarządzania urządzeniami i wdrożenia usługi 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 eksportowania i importowania do jednego polecenia, ale nie zawiera plików wyjściowych. Wszystkie wskazówki i ograniczenia opisane w sekcji 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że być ł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ą zaakceptowaną wartość: arm, configurations lub devices. Jeśli ten parametr zostanie pominięty, wszystkie trzy aspekty zostaną zmigrowane.
--replace -r	Jeśli ten parametr jest dołączony, polecenie migracji usuwa bieżący stan centrum docelowego.
--destination-hub --dh or --destination-hub-login --dl	Nazwa docelowego centrum IoT (--dh) lub parametry połączenia dla docelowego centrum IoT (--dl). Jeśli oba są podane, parametry połączenia ma priorytet.
--destination-resource-group --dg	Nazwa grupy zasobów dla docelowego centrum IoT. Docelowa grupa zasobów jest wymagana, jeśli centrum docelowe nie istnieje.
--origin-hub --oh or --origin-hub-login --ol	Nazwa centrum IoT źródła (--oh) lub parametry połączenia dla centrum IoT źródła (--ol). Jeśli oba są podane, parametry połączenia ma priorytet. Użyj parametry 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 pochodzenia 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 zweryfikowania dostępu jest uruchomienie az iot hub device-identity list poleceń lub az iot hub configuration list .

Jeśli polecenie zakończy się niepowodzeniem az iot hub state migrate , 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 Hub, zobacz Importowanie i eksportowanie tożsamości urządzeń usługi IoT Hub.