Jak wchodzić w interakcję z funkcją CommandRunner konfiguracji systemu operacyjnego i usługi Azure IoT

Większość właściwości urządzenia uwidocznionych przez aplikację OSConfig jest dyskretna i abstrahowana od szczegółów implementacji. Jeśli na przykład używasz HostName.desiredName polecenia do ustawiania nazwy hosta urządzenia, nie musisz martwić się o smak systemu operacyjnego, zależności środowiska uruchomieniowego skryptów lub niuanse chronometrażu.

Czasami jednak możesz chcieć zamienić prostotę w celu zapewnienia elastyczności. Na przykład:

• Musisz pobrać informacje niestandardowe z urządzenia, takie jak raport dotyczący wyników z ping example.com perspektywy urządzenia
• Musisz skonfigurować coś na urządzeniu, na którym nie ma istniejącej właściwości żądanej/zapisywalnej OSConfig

Funkcja CommandRunner systemu operacyjnegoConfig umożliwia konfigurację niestandardową i raportowanie za pomocą poleceń/skryptów powłoki. Obejmuje również niektóre wstępnie zdefiniowane akcje (zamykanie, ponowne uruchamianie), które nie wymagają żadnych skryptów.

Model interakcji i kluczowe właściwości/pola

Podsumowanie modelu interakcji

Chociaż możliwe jest bardziej szczegółowe użycie (i opisane w dalszej części tego artykułu), podstawowy model interakcji jest prosty:

• Żądanie polecenia należy zainicjować, zapisując żądane commandArguments polecenie w bliźniaczej reprezentacji.
• Wyniki można uzyskać, odczytując raport z commandStatus bliźniaczej reprezentacji.

Identyfikator rundy to: commandId

Na powyższym diagramie zwróć uwagę, że zarówno pole commandArguments , jak i commandStatus zawiera pole o nazwie commandId. Jest to identyfikator rundy łączący żądanie i wynik w ramach tej operacji asynchronicznej.

Obiekt wywołujący (administrator lub łańcuch narzędzi administratora) wybiera wartość commandId.

Nowa wartość commandId w commandArguments sygnałach, że jest to nowe żądanie. W kontekście bliźniaczej reprezentacji pojedynczego urządzenia wypełnianie nowego commandId jest mniej więcej analogiczne do naciśnięcia klawisza "Enter" w środowisku powłoki.

commandId Umożliwia również śledzenie wielu żądań. Moduł CommandRunner na każdym urządzeniu może odbierać (i zgłaszać stan na) wiele żądań w czasie. Tymczasem commandArguments składniki i commandStatus w bliźniaczej reprezentacji urządzenia mogą opisywać tylko jedno żądanie w każdej chwili. commandId to identyfikator rundy, który umożliwia obiektowi wywołującego zrozumienie (i sterowanie), które poprzednie żądanie jest obecnie opisane przez commandStatuselement . W efekcie komunikuje się "dla żądania, commandStatus w którym identyfikator miał wartość foo, stan to <...>".

Kiedy jest commandStatus aktualizowana?

Na urządzeniu istnieją dwa wyzwalacze dla modułu uruchamiającego polecenia, aby zaktualizować commandStatuselement .

1. Odświeżanie tła

   commandStatus jest aktualizowany w regularnych odstępach czasu (wartość domyślna to 30 sekund). Domyślnie to odświeżanie w tle powoduje, że reprezentuje stan ostatniego żądania.

   W praktyce oznacza to, że po przesłaniu żądania za pomocą poleceniaArguments można oczekiwać, że odpowiedni stan w poleceniu CommandStatus będzie widoczny po około 30–60 sekundach.

2. refreshCommandStatus

   refreshCommandStatus to mechanizm, który dotyczy dwóch zaawansowanych przypadków użycia:

   1. Wydano wiele żądań w czasie za pośrednictwem polecenia commandArgumentsi chcesz zobaczyć stan określonego żądania, a nie ostatniego żądania
   2. Nie chcesz czekać na odświeżenie w tle, nawet jeśli interesuje Cię tylko najnowsze żądanie

   Aby wyzwolić ten mechanizm, zapoznaj się z poniższą dokumentacją modelu obiektów dla programu commandArguments.

Dobre rozwiązania dotyczące konfiguracji niestandardowej i raportowania za pomocą modułu CommandRunner

1. Istotne zagadnienia dotyczące rozmiaru

   W przypadku krótkich poleceń/skryptów i krótkich danych wyjściowych można pracować bezpośrednio w tekście za pośrednictwem bliźniaczej reprezentacji. Takie podejście ma zalety, zwłaszcza brak zależności sieci ani uwierzytelniania poza IoT Hub. Podstawową wadą tego podejścia jest to, że dane wejściowe (w tym tekst skryptu/poleceń) i dane wyjściowe (w tym wszystkie przechwycone dane wyjściowe konsoli) są ograniczone do 4 KB.

   W przypadku dłuższych skryptów można przechowywać skrypt w innym miejscu (np. GitHub) i wywołać go za pomocą minimalnej otoki polecenia przekazywanego do aplikacji OSConfig za pośrednictwem bliźniaczej reprezentacji. Przykłady można znaleźć w temacie: Konfiguracja niestandardowa i raportowanie przy użyciu usług Azure IoT i OSConfig. Niezależnie od rozmiaru możesz również preferować zarządzanie skryptami w usłudze GitHub lub podobne — z zawartością bliźniaczej reprezentacji po prostu wskazującą te skrypty.

   W przypadku skryptów/poleceń, których dane wyjściowe konsoli są zbyt duże dla bliźniaczej reprezentacji, można dołączyć logikę do skryptu w celu wysyłania wyników do magazynu lokalnego lub magazynu w chmurze, a nie do stdout. Przykłady można znaleźć w temacie: Konfiguracja niestandardowa i raportowanie przy użyciu usług Azure IoT i OSConfig.

2. Używanie samodzielnych, nieinterakcyjnych poleceń/skryptów

   Mniejsza liczba rund jest lepsza, jedna runda jest najlepsza. OSConfig i CommandRunner są zoptymalizowane pod kątem skalowania, a nie interakcyjności. Chociaż można użyć modułu commandrunner szeregowo (jedno polecenie po drugim, podobne do terminalu synchronicznego na żywo), środowisko nie jest optymalne. Nie ma możliwości obsługi interakcyjnych monitów powłoki, musisz przypisać element commandId do każdego żądania, musisz poczekać na synchronizację bliźniaczej reprezentacji itp.

   Zamiast tego należy traktować moduł CommandRunner jako sposób osiągnięcia niestandardowej konfiguracji i raportowania na dużą skalę. Możesz asynchronicznie dystrybuować skrypt nieinterakcyjny (lub wstępnie zdefiniowaną akcję, taką jak ponowny rozruch), na jedno urządzenie lub miliony urządzeń i raportować wyniki nawet w miarę ich rozwoju w miarę upływu czasu (na przykład gdy nowe urządzenia dołączają do floty).

   Innymi słowy, powiedzmy, że musisz uruchomić cztery polecenia na wszystkich bieżących i przyszłych urządzeniach z systemem Ubuntu 20.04 w Hiszpanii. Nie myśl o tym jako o 4 dyskretnych sekwencyjnych zastosowaniach modułu CommandRunner, pomyśl o tym jako o jednym użyciu modułu CommandRunner, w którym ładunek zawiera cztery polecenia. Tymczasem przepływ pracy w chmurze, taki jak IoT Hub Konfiguracje, może zapewnić, że jest on dystrybuowany do wszystkich bieżących i przyszłych urządzeń, które powinny znajdować się w zakresie.

Pełny model obiektów

Poniższe informacje dotyczą zwykłych widoków żądanych/zgłoszonych modelu obiektów, a także rozszerzonych widoków JĘZYKA DTDL. Aby uzyskać więcej informacji, zobacz What OSConfig users need to know about "plain desired/reported" vs "DTDL enhanced" toolchains (Co użytkownicy konfiguracji systemu operacyjnego muszą wiedzieć o "zwykłych żądanych/zgłoszonych" vs "rozszerzonych" łańcuchach narzędzi DTDL.

commandArguments (ustawiane przez administratora)

• Opis: Dane wejściowe od administratora, wyzwala nowe żądanie polecenia lub wyzwala odświeżanie poleceniaStatus.

• Ścieżka: properties.desired.CommandRunner.commandArguments (CommandRunner składnik ->commandArguments właściwość zapisywalna)

• Elementy członkowskie

  Nazwa	Typ	Uwagi
  Commandid	ciąg	• Identyfikator określonego żądania przez obiekt wywołujący; zobacz powyżej, aby zapoznać się z tłami • argument commandArguments jest ignorowany, gdy identyfikator commandId jest pusty • Aby uzyskać wzajemne współdziałanie między identyfikatorem commandId i akcją, zobacz następujące elementy
  action	wyliczenie/int	Następujące elementy powinny być powiązane z nową wartością commandId: • 1 (ponowny rozruch) • 2 (zamknięcie) • 3 (runCommand); inicjuje polecenie/skrypt powłoki na potrzeby konfiguracji niestandardowej lub raportowania W połączeniu z wcześniej używanym identyfikatorem CommandID należy utworzyć następujące elementy: • 4 (refreshCommandStatus) powoduje, że polecenieStatus opisuje określone żądanie zidentyfikowane przez commandId
  Argumenty	ciąg	• Gdy akcja to 1 (ponowne uruchomienie) lub 2 (zamknięcie), opcjonalna liczba sekund opóźnienia przed wyzwoleniem akcji • Gdy akcja to 3 (UruchomPolecenie), wiersz polecenia do wykonania, na przykład ping -c 2 example.com • Ignorowane dla dowolnego innego typu akcji • Rozmiar poleceńArguments (zwykle zdominowany przez tekst argumentów) w bliźniaczych reprezentacjach usługi Azure IoT w zakresie ograniczonym do 4 KB; aby uzyskać więcej skryptów, zobacz Dobre rozwiązania
  singleLineTextResult	boolean	• Gdy akcja to 3 (UruchomPolecenie), opcjonalny przełącznik, aby określić, czy nowe linie powinny zostać usunięte z danych wyjściowych konsoli • Ignorowane dla dowolnego innego typu akcji
  timeout	int	• Gdy akcja wynosi 3 (uruchomPolecenie), długotrwałe żądania są zabijane po tej liczbie sekund • Opcjonalne (wartość domyślna to 30) • Ignorowane dla dowolnego innego typu akcji

• Przykłady z IoT Hub i rzeczywistych urządzeń

  • Żądanie ponownego uruchomienia:

    "CommandRunner": {
       "__t": "c",
       "commandArguments": {
          "commandId": "my_reboot_cmd",
          "arguments": "",
          "timeout": 30,
          "singleLineTextResult": false,
          "action": 1
       }
    }
    

  • Żądanie konfiguracji niestandardowej (strefa czasowa):

    "CommandRunner": {
       "__t": "c",
       "commandArguments": {
          "commandId": "my_timezone_cmd",
          "arguments": "timedatectl set-timezone Etc/UTC; timedatectl | grep Time",
          "timeout": 30,
          "singleLineTextResult": false,
          "action": 3
       }
    }
    

  • Aby uzyskać dodatkowe przykłady, zobacz:

    • Ponowne uruchamianie lub zamykanie urządzeń za pomocą usługi Azure IoT i aplikacji OSConfig
    • Konfiguracja niestandardowa i raportowanie przy użyciu usług Azure IoT i OSConfig

commandArguments (potwierdzenie z urządzenia)

• Opis: Jest to potwierdzenie agenta OSConfig na urządzeniu, które otrzymało wartość commandArguments po stronie administratora

• Ścieżka: properties.reported.CommandRunner.commandArguments (część commandArguments właściwości zapisywalnej potwierdzania urządzenia)

• Członkowie:

  Nazwa	Typ	Uwagi
  wartość	map (mapa)	Powinna dublować properties.desired.CommandRunner.commandArgumentselement wskazujący urządzenie w trybie online i odebrał żądanie
  Ac	int	Kod stanu, przypadek nominalny to wartość 200

commandStatus

• Opis: podaje stan i dane wyjściowe żądania przesłanego wcześniej za pośrednictwem poleceniaArguments

• Ścieżka: properties.reported.CommandRunner.commandStatus (CommandRunner składnik ->commandStatus właściwość tylko do odczytu)

• Elementy członkowskie

  Nazwa	Typ	Uwagi
  Commandid	ciąg	• Określa, które wcześniej odebrane żądanie zostało obecnie opisane przez polecenie Commandstatus • Domyślnie najnowsze żądanie jest reprezentowane • Obiekt wywołujący może zmienić ten fokus, aby opisać określone żądanie za pomocą mechanizmu refreshCommandStatus opisanego powyżej
  resultCode	int	Kod zakończenia żądanego polecenia. Podobnie jak echo $? w powłoce bash
  currentState	wyliczenie/int	• Przypadek nominalny to wartość 2 (succeeded) • Zobacz metadane, aby uzyskać pełną listę możliwych wartości
  textResult	ciąg	• Dane wyjściowe konsoli żądanego polecenia • Rozmiar parametru commandStatus (zwykle zdominowany przez składnik textResult) w bliźniaczych reprezentacjach usługi Azure IoT w zakresie ograniczonym do 4 KB; aby uzyskać dłuższe dane wyjściowe, zobacz Dobre rozwiązania

• Przykłady z IoT Hub i rzeczywistych urządzeń

  • Wynik ponownego rozruchu

    "CommandRunner": {
        "__t": "c",
        "commandStatus": {
           "commandId": "my_reboot_cmd",
           "resultCode": 0,
           "textResult": "",
           "currentState": 2
        }
    }
    

  • Wynik konfiguracji niestandardowej (strefa czasowa):

    "CommandRunner": {
       "__t": "c",
       "commandStatus": {
          "commandId": "my_timezone_cmd",
          "testResult": "Time zone: UTC",
          "statusCode": 0
       }
    }
    

  • Aby uzyskać dodatkowe przykłady, zobacz:

    • Ponowne uruchamianie lub zamykanie urządzeń za pomocą usługi Azure IoT i aplikacji OSConfig
    • Konfiguracja niestandardowa i raportowanie przy użyciu usług Azure IoT i OSConfig

Następne kroki

Aby zapoznać się z omówieniem scenariuszy i możliwości konfiguracji systemu operacyjnego, zobacz:

• Co to jest konfiguracja systemu operacyjnego dla IoT

Aby zapoznać się z konkretnymi praktycznymi przykładami, zobacz:

• Tworzenie środowiska laboratoryjnego OSConfig (za pomocą usługi Azure IoT) w ciągu 5 minut
• Szybki start: przykłady zapytań dotyczących rozpoczynania pracy z aplikacją OSConfig i usługą Azure IoT
• Co mogę aprowizować i zarządzać nimi?