Az OSConfig és az Azure IoT CommandRunner funkciójának használata

Az OSConfig által közzétett legtöbb eszköztulajdonság különálló és absztrakciós az implementáció részleteiből. Ha például egy eszköz gazdagépnevének beállítására használja HostName.desiredName , nem kell aggódnia az operációs rendszer ízével, a futtatókörnyezeti függőségek szkriptelésével vagy az időzítési árnyalatokkal.

Néha azonban érdemes lehet a rugalmasság érdekében egyszerűséggel kereskedni. Például:

• Egyéni adatokat kell lekérnie az eszközről – például jelentést szeretne készíteni az eszköz eredményeiről ping example.com
• Konfigurálnia kell valamit az eszközön, ahol nincs meglévő OSConfig kívánt/írható tulajdonság

Az OSConfig CommandRunner funkciója lehetővé teszi az egyéni konfigurációt és a jelentéskészítést rendszerhéjparancsokkal/szkriptekkel. Bizonyos előre definiált műveleteket (leállítás, újraindítás) is tartalmaz, amelyek nem igényelnek szkriptelést.

Tipp

Ez a referenciacikk a CommandRunner fogalmait, interakciós modelljét stb. ismerteti. Konkrét használati példákért lásd:

• Eszközök újraindítása vagy leállítása az Azure IoT és az OSConfig használatával
• Egyéni konfiguráció és jelentéskészítés az Azure IoT és az OSConfig használatával

Az interakciós modell és a kulcstulajdonságok/mezők

Az interakciós modell összefoglalása

Bár az árnyaltabb használat lehetséges (és ezt a cikk későbbi részében ismertetik), az alapvető interakciós modell egyszerű:

• A parancskérelem indításához írja be a kívánt commandArguments parancsot az ikerpéldányba.
• Az eredményeket az ikerpéldány jelentésének olvasásával commandStatus kaphatja meg.

Fontos

A diagramon látható hasznos adatok le vannak vetve, hogy hangsúlyozzák a be-/kimenő folyamatot. A teljes objektummodellhez, beleértve az itt nem látható kötelező tagokat is, lásd: A teljes objektummodell

Az oda-vissza út azonosítója a következő: commandId

A fenti ábrán vegye figyelembe, hogy a és commandStatus a mezőt commandIdis commandArguments tartalmazza. Ez az aszinkron művelet során a kérést és az eredményt összekapcsoló oda-vissza útazonosító.

A hívó (rendszergazda vagy rendszergazdai eszközlánc) kiválasztja a commandId értéket.

Tipp

commandId A kötelező a fájlban commandArguments. A hívók általában az alábbi minták egyikét használják az értékek kiválasztásakor:

• Monoton értékek, például "1" (első kérés esetén), "2" (második kérés esetén) stb. vagy leíró értékek, például "my_ping_command"

  Ezek kiválóan alkalmasak ad-hoc feltárásra; nem igényelnek tervezést, és könnyen beírhatók ikertartalmak szerkesztésekor

• Magas entrópia automatikusan generált értékek, például UUID-k

  Ezek kiválóan alkalmasak nagy léptékű programozott használatra, ahol egy felhőmegoldás háttérrendszere programozott módon hoz létre és követ nyomon értékeket

A jel új értéke commandIdcommandArguments , amely azt jelzi, hogy ez egy új kérés. Egyetlen eszköz ikerpéldányának kontextusában az újak commandId feltöltése nagyjából hasonló ahhoz, mint amikor egy rendszerhéj-környezetben lenyomja az Entert.

commandId lehetővé teszi több kérés nyomon követését is. A CommandRunner minden eszközön egyszerre több kérést is fogadhat (és jelentést készíthet az állapotáról). Eközben az commandArguments egyes eszközök ikerpéldányában lévő és commandStatus összetevők egyszerre csak egy kérést írnak le. commandIdA a hívó számára lehetővé tévő oda-vissza út azonosítója, amely lehetővé teszi a hívó számára, hogy megértse (és szabályozza), hogy melyik korábbi kérést írja le jelenleg.commandStatus Valójában a "kérés esetében, commandStatus ahol az azonosító "foo" volt, az állapot <...>".

Mikor frissül?commandStatus

A CommandRunner két eseményindítót tartalmaz az eszközön a frissítéshez commandStatus.

1. Háttérfrissítés

   commandStatus rendszeres időközönként frissül (az alapértelmezett érték 30 másodperc). Alapértelmezés szerint ez a háttérfrissítés a legutóbbi kérés állapotát jelzi.

   A gyakorlatban ez azt jelenti, hogy miután a commandArguments használatával elküldte a kérelmet, körülbelül 30–60 másodperc után számíthat a commandStatus megfelelő állapotára.

2. refreshCommandStatus

   refreshCommandStatus egy olyan mechanizmus, amely két speciális használati esetet kezel:

   1. Több kérést adott ki az használatával, commandArgumentsés egy adott kérelem állapotát szeretné megtekinteni, nem pedig a legutóbbi kérést
   2. Nem szeretne megvárni a háttérfrissítést, még akkor sem, ha csak a legújabb kérés érdekli

   A mechanizmus aktiválásához tekintse meg az alábbi objektummodell-dokumentációt a következőhöz: commandArguments.

Ajánlott eljárások egyéni konfiguráláshoz és jelentéskészítéshez a CommandRunnerrel

1. Mérettel kapcsolatos szempontok

   Rövid parancsok/szkriptek és rövid kimenetek esetén közvetlenül a szövegbe ágyazva dolgozhat az ikerpéldányon keresztül. Ez a megközelítés számos előnnyel jár, különösen, ha nincs hálózati vagy hitelesítési függőség a IoT Hub kívül. Ennek a megközelítésnek az elsődleges hátránya, hogy a bemenetek (beleértve a szkript/parancsok szövegét) és a kimenetek (beleértve a rögzített konzolkimeneteket) 4 KB-ra vannak korlátozva.

   Hosszabb szkriptek esetén a szkriptet máshol (például a GitHubon) tárolhatja, és meghívhatja egy minimális burkolóparancsból, amelyet átad az OSConfignak az ikerpéldányon keresztül. Példákért lásd: Egyéni konfiguráció és jelentéskészítés az Azure IoT és az OSConfig használatával. A méretétől függetlenül előfordulhat, hogy a szkripteket a GitHubon vagy hasonló módon szeretné kezelni– az ikertartalmak egyszerűen ezekre mutatnak.

   Olyan szkriptek/parancsok esetében, amelyek konzolkimenete túl nagy az ikerpéldány számára, a szkriptbe belefoglalhatja a logikát, hogy az eredményeket a helyszíni vagy a felhőbeli tárolóba küldje, nem pedig az stdoutra. Példákért lásd: Egyéni konfiguráció és jelentéskészítés az Azure IoT és az OSConfig használatával.

2. Önálló, nem interaktív parancsok/szkriptek használata

   Kevesebb oda-vissza út jobb, egy oda-vissza út a legjobb. Az OSConfig és a CommandRunner nem interaktivitási skálázásra van optimalizálva. Bár lehetőség van a CommandRunner soros használatára (egyik parancs a másik után, az élő szinkron terminálhoz hasonlóan), a felület nem optimális. Az interaktív rendszerhéj-kérések kezelésére nincs mód, minden kéréshez hozzá kell rendelnie egy-egy commandId parancsot, meg kell várnia az ikerpéldány-szinkronizálást stb.

   Ehelyett gondoljon a CommandRunnerre az egyéni konfiguráció és a nagy léptékű jelentéskészítés elérésének módjaként. Aszinkron módon eloszthat egy nem interaktív szkriptet (vagy egy előre meghatározott műveletet, például újraindítást) egy eszközre vagy több millió eszközre, és jelentést készíthet az eredményekről akkor is, amikor idővel fejlődnek (például amikor új eszközök csatlakoznak a flottához).

   Más szóval azt kell mondani, hogy négy parancsot kell futtatnia az összes jelenlegi és jövőbeli Ubuntu 20.04-es eszközön Spanyolországban. Ne gondoljon erre úgy, mint a CommandRunner 4 különálló szekvenciális használatára, gondoljon rá úgy, mint a CommandRunner egyetlen használatára, ahol a hasznos adat tartalmazza a négy parancsot. Eközben egy felhőbeli munkafolyamat, például a IoT Hub-konfigurációk biztosíthatják, hogy ez az összes jelenlegi és jövőbeli eszközre kiterjedjen, amelynek hatókörben kell lennie.

A teljes objektummodell

Fontos

Az 1.0.3-s verzió (2022. június 28-án jelent meg) a tagnevek kompatibilitástörő változásait tartalmazza, amelyek hatással lehetnek a meglévő felhasználókra. További információkért lásd: A tagok nevei átállnak a PascalCaseről a camelCase-ra az 1.0.3-es verzióban.

Az alábbi információk az objektummodell egyszerű kívánt/jelentett nézeteire, valamint a DTDL továbbfejlesztett nézeteire vonatkoznak. További információ: What OSConfig users need to know about "plain desired/reported" vs "DTDL enhanced" toolchains (Mit kell tudniuk az OSConfig-felhasználóknak az egyszerű célról/jelentésről) és a "DTDL enhanced" eszközláncokról.

commandArguments (rendszergazda által beállított)

• Leírás: A rendszergazda bemenete új parancskérelmet aktivál, vagy elindítja a commandStatus frissítését.

• Elérési út: properties.desired.CommandRunner.commandArguments (CommandRunner összetevő -->commandArguments írható tulajdonság)

• Tagok

  Név	Típus	Jegyzetek
  commandId	sztring	• A hívó megadott kérésazonosítója; lásd fent a hátteret • a commandArguments figyelmen kívül lesz hagyva, ha a commandId üres • A commandId és a művelet közötti kölcsönhatásért lásd:
  action	enum/int	Az alábbiakat a commandId új értékével kell párosítani: • 1 (újraindítás) • 2 (leállítás) • 3 (runCommand); rendszerhéjparancsot/szkriptet kezdeményez egyéni konfigurációhoz vagy jelentéskészítéshez A következőket egy korábban használt CommandID azonosítóval kell összekapcsolni: • A 4 (refreshCommandStatus) miatt a commandStatus egy, a commandId által azonosított kérést ír le
  Érvek	sztring	• Ha a művelet 1 (újraindítás) vagy 2 (leállítás), a művelet elindítása előtt nem kötelező másodpercek száma • Ha a művelet 3 (RunCommand), a végrehajtandó parancssor, például ping -c 2 example.com • Bármely más művelettípus esetén figyelmen kívül hagyva • A commandArguments (általában argumentumok szövege által dominált) mérete az Azure IoT-ikerpéldányokban, legfeljebb 4 KB-ban; a hosszabb szkriptekért lásd: Ajánlott eljárások
  singleLineTextResult	boolean	• Ha a művelet 3 (RunCommand), opcionális kapcsolóval megadhatja, hogy az új vonalakat le kell-e venni a konzol kimenetéről • Bármely más művelettípus esetén figyelmen kívül hagyva
  timeout	int	• Ha a művelet 3 (runCommand), a hosszú ideig futó kérések ennyi másodperc után leállnak • Nem kötelező (az alapértelmezett érték 30) • Bármely más művelettípus esetén figyelmen kívül hagyva

• Példák IoT Hub és valós eszközökről

  • Újraindítási kérelem:

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

  • Egyéni konfigurációs (időzóz) kérelem:

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

  • További példákért lásd:

    • Eszközök újraindítása vagy leállítása az Azure IoT és az OSConfig használatával
    • Egyéni konfiguráció és jelentéskészítés az Azure IoT és az OSConfig használatával

commandArguments (nyugtázás az eszközről)

• Leírás: Ez az OSConfig-ügynök nyugtázása az eszközön, amely megkapta a commandArguments értéket a rendszergazdai oldalról

• Elérési út: properties.reported.CommandRunner.commandArguments (az írható tulajdonság eszköz nyugtázási commandArguments része)

• Tagok:

  Név	Típus	Jegyzetek
  érték	map	Tükröznie properties.desired.CommandRunner.commandArgumentskell a elemet, jelezve az eszközt az interneten, és megkapta a kérést
  Ac	int	Állapotkód, névleges eset értéke 200

commandStatus

• Leírás: A commandArguments használatával korábban elküldött kérés állapotát és kimenetét adja meg

• Elérési út: properties.reported.CommandRunner.commandStatus (CommandRunner összetevő -->commandStatus írásvédett tulajdonság)

• Tagok

  Név	Típus	Jegyzetek
  commandId	sztring	• Azonosítja, hogy a Commandstatus jelenleg melyik korábban fogadott kérést írja le • Alapértelmezés szerint a legutóbbi kérés jelenik meg • A hívó módosíthatja ezt a fókuszt egy adott kérés leírására a fent leírt refreshCommandStatus mechanizmuson keresztül
  resultCode	int	A kért parancs kilépési kódja. Hasonló a bash-hez echo $?
  currentState	enum/int	• Névleges eset értéke 2 (succeeded) • A lehetséges értékek teljes listájáért tekintse meg a metaadatokat
  textResult	sztring	• A kért parancs konzolkimenete • A commandStatus (általában textResult összetevő által uralt) mérete az Azure IoT-ikerpéldányokban legfeljebb 4 KB-ban; a hosszabb kimenetekért lásd: Ajánlott eljárások

• Példák IoT Hub és valós eszközökről

  • Újraindítás eredménye

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

  • Egyéni konfiguráció (időzóta) eredménye:

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

  • További példákért lásd:

    • Eszközök újraindítása vagy leállítása az Azure IoT és az OSConfig használatával
    • Egyéni konfiguráció és jelentéskészítés az Azure IoT és az OSConfig használatával

Fontos

Az 1.0.3-s verzió (2022. június 28-án jelent meg) a tagnevek kompatibilitástörő változásait tartalmazza, amelyek hatással lehetnek a meglévő felhasználókra. További információkért lásd: A tagok nevei átállnak a PascalCaseről a camelCase-ra az 1.0.3-es verzióban.

Következő lépések

Az OSConfig forgatókönyveinek és képességeinek áttekintéséért lásd:

• Mi az az OSconfig for IoT?

Konkrét gyakorlati példákért lásd:

• OSConfig -tesztkörnyezet létrehozása (Azure IoT-vel) 5 perc alatt
• Rövid útmutató: Példák lekérdezésére az OSConfig és az Azure IoT használatának első lépéseihez
• Mit építhetek ki és kezelhetek?