Jak pracovat s funkcí CommandRunner pro OSConfig a Azure IoT

Většina vlastností zařízení vystavených nástrojem OSConfig je diskrétní a abstrahuje se od podrobností implementace. Pokud například použijete HostName.desiredName k nastavení názvu hostitele zařízení, nemusíte si dělat starosti s charakterem operačního systému, se závislostmi skriptování modulu runtime nebo s nuancemi časování.

Někdy ale můžete chtít vyměnit jednoduchost za flexibilitu. Příklad:

• Potřebujete načíst vlastní informace ze zařízení – například chcete hlásit výsledky ping example.com z pohledu zařízení.
• Na zařízení musíte nakonfigurovat něco, kde neexistuje požadovaná nebo zapisovatelná vlastnost OSConfig.

Funkce CommandRunner nástroje OSConfig umožňuje vlastní konfiguraci a vytváření sestav prostřednictvím příkazů a skriptů prostředí. Zahrnuje také určité předdefinované akce (vypnutí, restartování), které nevyžadují žádné skriptování.

Tip

Tento referenční článek popisuje koncepty CommandRunneru, model interakce atd. Konkrétní příklady použití najdete tady:

• Restartování nebo vypnutí zařízení pomocí Azure IoT a OSConfig
• Vlastní konfigurace a vytváření sestav pomocí Azure IoT a OSConfig

Model interakce a klíčové vlastnosti/pole

Souhrn modelu interakce

I když je možné podrobnější využití (a popsáno dále v tomto článku), základní model interakce je jednoduchý:

• Žádost o příkaz zahájíte zápisem do požadovaného commandArguments dvojčete.
• Výsledky získáte tak, že si přečtete hlášené commandStatus z dvojčete.

Důležité

Datové části zobrazené v tomto diagramu jsou odstraněny, aby se zdůraznil tok příchozích a odchozích dat. Úplný objektový model včetně požadovaných členů, které tu nejsou uvedené, najdete v tématu: Úplný objektový model.

Identifikátor zpáteční cesty je: commandId

Ve výše uvedeném diagramu si všimněte, že obě commandArgumentscommandStatus a obsahují pole s názvem commandId. Toto je identifikátor odezvy, který propojuje požadavek a výsledek během této asynchronní operace.

Volající (sada nástrojů správce nebo správce) zvolí hodnotu commandId.

Tip

commandId je povinné v nástroji commandArguments. Volající při výběru hodnot obvykle používají jeden z těchto vzorů:

• Monotónní hodnoty jako "1" (pro první požadavek), "2" (pro druhý požadavek) atd. nebo popisné hodnoty jako "my_ping_command"

  Ty jsou vhodné pro ad hoc průzkum; nevyžadují plánování a při úpravách obsahu dvojčat je možné je snadno zadávat.

• Automaticky generované hodnoty s vysokou entropií, jako jsou identifikátory UUID

  Jsou vhodné pro rozsáhlé programové použití, kde back-end cloudového řešení programově vytvoří hodnoty a bude je sledovat.

Nová hodnota in commandIdcommandArguments signalizuje, že se jedná o nový požadavek. V kontextu dvojčete jednoho zařízení je naplnění nového commandId zhruba obdobou stisknutí klávesy Enter v prostředí prostředí.

commandId umožňuje také sledovat více požadavků. CommandRunner na každém zařízení může přijímat (a hlásit stav) více požadavků v průběhu času. Komponenty a commandStatus ve dvojčeti jednotlivých zařízení zatím commandArguments můžou v každém okamžiku popsat jenom jeden požadavek. commandId je identifikátor odezvy, který volajícímu umožňuje pochopit (a řídit), které předchozí žádosti aktuálně popisuje commandStatus. V důsledku toho commandStatus sdělí "pro vaši žádost, kde id bylo "foo", stav je <...>".

Kdy se commandStatus aktualizuje?

Na zařízení jsou k dispozici dva triggery pro CommandRunner, které aktualizují commandStatus.

1. Aktualizace na pozadí

   commandStatus se aktualizuje v pravidelném intervalu (výchozí hodnota je 30 sekund). Ve výchozím nastavení tato aktualizace na pozadí představuje stav posledního požadavku.

   V praxi to znamená, že po odeslání požadavku přes commandArguments můžete očekávat, že se odpovídající stav zobrazí v commandStatus přibližně po 30 až 60 sekundách.

2. refreshCommandStatus

   refreshCommandStatus je mechanismus, který řeší dva pokročilé případy použití:

   1. V průběhu času jste prostřednictvím commandArgumentsnástroje vydali více požadavků a chcete zobrazit stav konkrétního požadavku, nikoli nejnovějšího požadavku.
   2. Nechcete čekat na aktualizaci na pozadí, i když vás zajímá jenom nejnovější žádost

   Pokud chcete tento mechanismus aktivovat, projděte si následující dokumentaci k objektovém commandArgumentsmodelu.

Osvědčené postupy pro vlastní konfiguraci a vytváření sestav pomocí CommandRunneru

1. Informace o velikosti

   Pro krátké příkazy/skripty a krátké výstupy můžete pracovat přímo prostřednictvím dvojčete. Tento přístup má výhody, zejména bez závislosti na síti nebo ověřování mimo IoT Hub. Hlavní nevýhodou tohoto přístupu je, že vstupy (včetně textu skriptu nebo příkazů) a výstupy (včetně jakéhokoli zachyceného výstupu konzoly) jsou omezeny na 4 kB.

   U delších skriptů můžete skript uložit jinam (například GitHub) a volat ho z minimálního příkazu obálky, který předáte do OSConfig přes dvojče. Příklady najdete v tématu Vlastní konfigurace a vytváření sestav pomocí Azure IoT a OSConfig. Bez ohledu na velikost můžete také upřednostňovat správu skriptů na GitHubu nebo podobně– s obsahem dvojčat, který na tyto skripty jednoduše odkazuje.

   U skriptů nebo příkazů, jejichž výstup konzoly je pro dvojče příliš velký, můžete do skriptu zahrnout logiku, která místo do stdoutu odesílá výsledky do místního nebo cloudového úložiště. Příklady najdete v tématu Vlastní konfigurace a vytváření sestav pomocí Azure IoT a OSConfig.

2. Použití samostatných neinteraktivních příkazů nebo skriptů

   Méně zpátečních jízd je lepší, nejlepší je jedno kolo. OSConfig a CommandRunner jsou optimalizované pro škálování, nikoli pro interaktivitu. I když je možné používat CommandRunner sériově (jeden příkaz za druhým, podobně jako živý synchronní terminál), prostředí není optimální. Neexistuje žádný způsob, jak zpracovat výzvy interaktivního prostředí, musíte každému požadavku přiřadit commandId příkaz, počkat na synchronizaci dvojčat atd.

   Místo toho si CommandRunner představte jako způsob, jak dosáhnout vlastní konfigurace a vytváření sestav ve velkém měřítku. Neinteraktivní skript (nebo předdefinované akce, jako je restartování) můžete asynchronně distribuovat na jedno zařízení nebo miliony zařízení a můžete hlásit výsledky, i když se v průběhu času vyvíjejí (například když se k vozovému parku připojují nová zařízení).

   Jinými slovy, řekněme, že potřebujete spustit čtyři příkazy na všech současných a budoucích zařízeních s Ubuntu 20.04 ve Španělsku. Nemyslete si to jako 4 diskrétní sekvenční použití CommandRunneru, představte si to jako jedno použití CommandRunneru, kde datová část obsahuje vaše čtyři příkazy. Cloudový pracovní postup, jako je IoT Hub Konfigurace, může zajistit distribuci do všech současných a budoucích zařízení, která by měla být v rozsahu.

Úplný objektový model

Důležité

Verze 1.0.3 (publikovaná 28. června 2022) obsahuje zásadní změny názvů členů, které můžou ovlivnit stávající uživatele. Další informace najdete v tématu Přechod názvů členů z PascalCase na camelCase ve verzi 1.0.3.

Následující informace se týkají prostých požadovaných nebo hlášených zobrazení objektového modelu a rozšířených zobrazení DTDL. Další informace najdete v tématu Co uživatelé OSConfig potřebují vědět o "prostých požadovaných/hlášených" a "vylepšených" nástrojích DTDL.

commandArguments (nastavený správcem)

• Popis: Vstup od správce, aktivuje novou žádost o příkaz nebo aktivuje aktualizaci commandStatus.

• Cesta: properties.desired.CommandRunner.commandArguments (CommandRunner komponenta -->commandArguments zapisovatelná vlastnost)

• Členové

  Název	Typ	Poznámky
  Commandid	řetězec	• ZADANÉ ID požadavku volajícího; viz výše pro pozadí • příkaz commandArguments je ignorován, pokud je commandId prázdné. • Informace o vzájemné souhře mezi commandId a action najdete v následujících tématech.
  action	enum/int	Následující hodnota by měla být spojená s novou hodnotou commandId: • 1 (restartování) • 2 (vypnutí) • 3 (runCommand); inicializuje příkaz nebo skript prostředí pro vlastní konfiguraci nebo generování sestav. S dříve použitým CommandID by mělo být spojeno následující: • 4 (refreshCommandStatus) způsobí, že commandStatus popisuje konkrétní požadavek identifikovaný pomocí commandId.
  Argumenty	řetězec	• Pokud je akce 1 (restartování) nebo 2 (vypnutí), volitelný počet sekund před aktivací akce • Pokud je akce 3 (RunCommand), příkazový řádek, který se má spustit, například ping -c 2 example.com • Ignorováno pro jakýkoli jiný typ akce • Velikost commandArguments (obvykle dominuje text argumentů) ve dvojčatech Azure IoT v omezené velikosti 4 kB; Delší skripty najdete v tématu Osvědčené postupy.
  singleLineTextResult	boolean	• Pokud je akce 3 (RunCommand), volitelný přepínač určující, jestli mají být nové linky odstraněny z výstupu konzoly. • Ignorováno pro jakýkoli jiný typ akce
  timeout	int	• Pokud je akce 3 (runCommand), dlouhotrvající požadavky se po tomto počtu sekund ukončí. • Volitelné (výchozí hodnota je 30) • Ignorováno pro jakýkoli jiný typ akce

• Příklady z IoT Hub a skutečných zařízení

  • Žádost o restartování:

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

  • Požadavek na vlastní konfiguraci (časové pásmo):

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

  • Další příklady najdete tady:

    • Restartování nebo vypnutí zařízení pomocí Azure IoT a OSConfig
    • Vlastní konfigurace a vytváření sestav pomocí Azure IoT a OSConfig

commandArguments (potvrzení ze zařízení)

• Popis: Toto je potvrzení od agenta OSConfig na zařízení, že přijalo hodnotu commandArguments ze strany správce.

• Cesta: properties.reported.CommandRunner.commandArguments (část commandArguments zapisovatelné vlastnosti pro potvrzení zařízení)

• Členové:

  Název	Typ	Poznámky
  hodnota	mapa	Měl by zrcadlit properties.desired.CommandRunner.commandArguments, což znamená, že zařízení je online a přijalo žádost
  Ac	int	Stavový kód, nominální velikost písmen je hodnota 200

commandStatus

• Popis: Poskytuje stav a výstup požadavku odeslaného dříve prostřednictvím commandArguments.

• Cesta: properties.reported.CommandRunner.commandStatus (CommandRunner komponenta -->commandStatus vlastnost jen pro čtení)

• Členové

  Název	Typ	Poznámky
  Commandid	řetězec	• Určuje, který dříve přijatý požadavek je aktuálně popsán commandstatus. • Ve výchozím nastavení je reprezentován nejnovější požadavek. • Volající může změnit tento fokus tak, aby popisoval konkrétní požadavek prostřednictvím výše popsaného mechanismu refreshCommandStatus.
  resultCode	int	Ukončovací kód požadovaného příkazu. Obdobou v echo $? Bash
  currentState	enum/int	• Nominální velikost písmen je hodnota 2 (succeeded) • Úplný seznam možných hodnot najdete v metadatech .
  textResult	řetězec	• Výstup konzoly požadovaného příkazu • Velikost commandStatus (obvykle dominuje komponenta textResult) ve dvojčatech Azure IoT v omezené velikosti 4 kB; Delší výstupy najdete v tématu Osvědčené postupy.

• Příklady z IoT Hub a skutečných zařízení

  • Výsledek restartování

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

  • Výsledek vlastní konfigurace (časové pásmo):

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

  • Další příklady najdete tady:

    • Restartování nebo vypnutí zařízení pomocí Azure IoT a OSConfig
    • Vlastní konfigurace a vytváření sestav pomocí Azure IoT a OSConfig

Důležité

Verze 1.0.3 (publikovaná 28. června 2022) obsahuje zásadní změny názvů členů, které můžou ovlivnit stávající uživatele. Další informace najdete v tématu Přechod názvů členů z PascalCase na camelCase ve verzi 1.0.3.

Další kroky

Přehled scénářů a možností OSConfig najdete tady:

• Co je OSconfig pro IoT

Konkrétní praktické příklady najdete tady:

• Vytvoření testovacího prostředí OSConfig (s Azure IoT) za 5 minut
• Rychlý start: Příklady dotazů pro zahájení práce s OSConfig a Azure IoT
• Co můžu zřídit a spravovat?