Interagera med CommandRunner-funktionen i OSConfig och Azure IoT

De flesta enhetsegenskaper som exponeras av OSConfig är diskreta och abstraherade från implementeringsinformation. När du till exempel använder HostName.desiredName för att ange en enhets värdnamn behöver du inte bekymra dig om operativsystemssmaken, om skriptkörningskörningsberoenden eller om tidsnanoder.

Ibland kan du dock vilja handla enkelhet för flexibilitet. Exempel:

• Du måste hämta anpassad information från enheten , till exempel att du vill rapportera om resultatet från ping example.com enhetens perspektiv
• Du måste konfigurera något på enheten där det inte finns någon befintlig önskad/skrivbar OSConfig-egenskap

Funktionen CommandRunner i OSConfig möjliggör anpassad konfiguration och rapportering via gränssnittskommandon/skript. Den innehåller även vissa fördefinierade åtgärder (avstängning, omstart) som inte kräver skript.

Tips

Den här referensartikeln beskriver CommandRunner-begrepp, interaktionsmodell osv. Konkreta användningsexempel finns i:

• Starta om eller stänga av enheter med Azure IoT och OSConfig
• Anpassad konfiguration och rapportering med Azure IoT och OSConfig

Interaktionsmodellen och viktiga egenskaper/fält

Sammanfattning av interaktionsmodell

Även om mer nyanserad användning är möjlig (och beskrivs senare i den här artikeln), är den grundläggande interaktionsmodellen enkel:

• Du initierar en kommandobegäran genom att skriva till önskad commandArguments i tvillingen.
• Du får resultaten genom att läsa rapporterade commandStatus från tvillingen.

Viktigt

De nyttolaster som visas i det här diagrammet tas bort för att framhäva in-/ut-flödet. Fullständig objektmodell, inklusive obligatoriska medlemmar som inte visas här, finns i: Den fullständiga objektmodellen

Rundresa-ID:et är: commandId

Observera i diagrammet ovan att både commandArguments och commandStatus innehåller ett fält med namnet commandId. Det här är tur och retur-ID:en som länkar begäran och resultat under den här asynkrona åtgärden.

Anroparen (administratörs- eller administratörsverktygskedjan) väljer värdet commandId.

Tips

commandId krävs i commandArguments. Anropare använder vanligtvis något av följande mönster när de väljer värden:

• Monotoniska värden som "1" (för första begäran), "2" (för andra begäran) osv. eller beskrivande värden som "my_ping_command"

  Dessa är väl lämpade för ad hoc-utforskning; de behöver inte planeras, och de kan skrivas enkelt när du redigerar tvillinginnehåll

• Höga autogenererade värden för entropy, till exempel UUID:ar

  De passar bra för storskalig programmatisk användning där en molnlösnings serverdel programmässigt skapar och håller koll på värden

Ett nytt värde för commandId i commandArguments signalerar att detta är en ny begäran. När det gäller en enskild enhets tvilling är det ungefär detsamma som att fylla i en ny commandId med "Retur" i en gränssnittsmiljö.

commandId gör det också möjligt att hålla reda på flera begäranden. CommandRunner på varje enhet kan ta emot (och rapportera status på) flera begäranden över tid. Under tiden kan komponenterna commandArguments och commandStatus i varje enhets tvilling bara beskriva en begäran när som helst. commandId är den tur och retur-ID som gör det möjligt för anroparen att förstå (och kontrollera) vilken tidigare begäran för närvarande beskrivs av commandStatus. I själva verket commandStatus kommunicerar "för din begäran där ID var "foo", statusen är <...>".

När uppdateras commandStatus ?

Det finns två utlösare för CommandRunner på enheten för att uppdatera commandStatus.

1. Bakgrundsuppdatering

   commandStatus uppdateras regelbundet (standardvärdet är 30 sekunder). Den här bakgrundsuppdateringen gör som standard att den representerar statusen för den senaste begäran.

   I praktiken innebär det att när du har skickat en begäran via commandArguments kan du förvänta dig att se motsvarande status i commandStatus efter cirka 30–60 sekunder.

2. refreshCommandStatus

   refreshCommandStatus är en mekanism som hanterar två avancerade användningsfall:

   1. Du har utfärdat flera begäranden över tid via commandArgumentsoch du vill se status för en specifik begäran, inte den senaste begäran
   2. Du vill inte vänta på bakgrundsuppdateringen, även om du bara är intresserad av den senaste begäran

   Information om hur du utlöser den här mekanismen finns i dokumentationen för objektmodellen nedan för commandArguments.

Bra metoder för anpassad konfiguration och rapportering med CommandRunner

1. Överväganden gällande storlek

   För korta kommandon/skript och korta utdata kan du arbeta direkt infogat via tvillingen. Den här metoden har fördelar, särskilt att inte ha något nätverks- eller autentiseringsberoende utanför IoT Hub. Den främsta nackdelen med den här metoden är att indata (inklusive text för skript/kommandon) och utdata (inklusive insamlade konsolutdata) var och en är begränsade till 4 KB.

   För längre skript kan du lagra skriptet någon annanstans (till exempel GitHub) och anropa det från ett minimalt omslutningskommando som du skickar till OSConfig över tvillingen. Exempel finns i: Anpassad konfiguration och rapportering med Azure IoT och OSConfig. Oberoende av storlek kanske du också föredrar att hantera dina skript i GitHub eller liknande, med tvillinginnehåll som bara pekar på dem.

   För skript/kommandon vars konsolutdata är för stora för tvillingen kan du inkludera logik i skriptet för att skicka resultat till lokal lagring eller molnlagring i stället för till stdout. Exempel finns i: Anpassad konfiguration och rapportering med Azure IoT och OSConfig.

2. Använda fristående, icke-interaktiva kommandon/skript

   Färre tur- och returresor är bättre, en tur och retur är bäst. OSConfig och CommandRunner är optimerade för skalning, inte interaktivitet. Även om det är möjligt att använda CommandRunner seriellt (ett kommando efter ett annat, liknande en synkron liveterminal) är upplevelsen inte optimal. Det finns inget sätt att hantera interaktiva gränssnittsprompter, du måste tilldela en commandId till varje begäran, du måste vänta på tvillingsynkronisering osv.

   Tänk i stället på CommandRunner som ett sätt att uppnå anpassad konfiguration och rapportering i stor skala. Du kan asynkront distribuera ett icke-interaktivt skript (eller en fördefinierad åtgärd som omstart) till en enhet eller miljontals enheter och kan rapportera resultaten även när de utvecklas över tid (till exempel när nya enheter ansluter till flottan).

   Anta med andra ord att du måste köra fyra kommandon på alla nuvarande och framtida Ubuntu 20.04-enheter i Spanien. Tänk inte på det som 4 diskreta sekventiella användningar av CommandRunner, tänk på det som en enda användning av CommandRunner där nyttolasten innehåller dina fyra kommandon. Under tiden kan ett molnarbetsflöde, till exempel IoT Hub Configurations, se till att detta distribueras till alla aktuella och framtida enheter som ska finnas i omfånget.

Den fullständiga objektmodellen

Viktigt

Version 1.0.3 (publicerad 28 juni 2022) innehåller icke-bakåtkompatibla ändringar av medlemsnamn som kan påverka befintliga användare. Mer information finns i: Medlemsnamn övergår från PascalCase till camelCase i version 1.0.3

Följande information gäller för oformaterade önskade/rapporterade vyer av objektmodellen samt förbättrade DTDL-vyer. Mer information finns i Vad OSConfig-användare behöver veta om verktygskedjorna "plain desired/reported" eller "DTDL enhanced".

commandArguments (anges av administratör)

• Beskrivning: Indata från administratör, utlöser ny kommandobegäran eller utlöser uppdatering av commandStatus.

• Sökväg: properties.desired.CommandRunner.commandArguments (CommandRunner komponent –>commandArguments skrivbar egenskap)

• Medlemmar

  Namn	Typ	Kommentarer
  commandId	sträng	• Uppringarens angivna begärande-ID; se ovan för bakgrund • commandArguments ignoreras när commandId är tomt • För samspel mellan commandId och åtgärd, se följande
  åtgärd	uppräkning/int	Följande bör kopplas till ett nytt värde för commandId: • 1 (omstart) • 2 (avstängning) • 3 (runCommand); initierar shell-kommando/skript för anpassad konfiguration eller rapportering Följande bör kopplas till ett tidigare använt CommandID: • 4 (refreshCommandStatus) gör att commandStatus beskriver en specifik begäran som identifierats av commandId
  Argument	sträng	• När åtgärden är 1 (omstart) eller 2 (avstängning), ett valfritt antal sekunder att fördröja innan åtgärden utlöses • När åtgärden är 3 (RunCommand), kommandoraden som ska köras, till exempel ping -c 2 example.com • Ignoreras för andra åtgärdstyper • Storleken på commandArguments (vanligtvis domineras av argumenttext) i Azure IoT-tvillingar i begränsat till 4 KB; för längre skript se Bra metoder
  singleLineTextResult	boolean	• När åtgärden är 3 (RunCommand) kan du välja att ange om nya linjer ska tas bort från konsolutdata • Ignoreras för andra åtgärdstyper
  timeout	int	• När åtgärden är 3 (runCommand) avlivas tidskrävande begäranden efter så här många sekunder • Valfritt (standard är 30) • Ignoreras för andra åtgärdstyper

• Exempel från IoT Hub och verkliga enheter

  • Omstartsbegäran:

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

  • Begäran om anpassad konfiguration (tidszon):

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

  • Ytterligare exempel finns i:

    • Starta om eller stänga av enheter med Azure IoT och OSConfig
    • Anpassad konfiguration och rapportering med Azure IoT och OSConfig

commandArguments (bekräftelse från enheten)

• Beskrivning: Det här är bekräftelsen från OSConfig-agenten på enheten som den har tagit emot kommandotArguments-värdet från administratörssidan

• Sökväg: properties.reported.CommandRunner.commandArguments (enhetens bekräftelsedel av commandArguments skrivbar egenskap)

• Medlemmar:

  Namn	Typ	Kommentarer
  värde	map	Ska spegla properties.desired.CommandRunner.commandArguments, som anger att enheten är online och har tagit emot begäran
  Ac	int	Statuskod, nominellt skiftläge är värde 200

commandStatus

• Beskrivning: Ger status och utdata för en begäran som tidigare skickats via commandArguments

• Sökväg: properties.reported.CommandRunner.commandStatus (CommandRunner komponent –>commandStatus skrivskyddad egenskap)

• Medlemmar

  Namn	Typ	Kommentarer
  commandId	sträng	• Identifierar vilken tidigare mottagen begäran som för närvarande beskrivs av Commandstatus • Som standard representeras den senaste begäran • Uppringaren kan ändra det här fokuset för att beskriva en specifik begäran via mekanismen refreshCommandStatus som beskrivs ovan
  resultCode	int	Slutkoden för det begärda kommandot. Analogt med echo $? i bash
  currentState	uppräkning/int	• Nominellt skiftläge är värde 2 (succeeded) • Se metadata för en fullständig lista över möjliga värden
  textResult	sträng	• Konsolens utdata från det begärda kommandot • Storleken på commandStatus (domineras vanligtvis av textResult-komponent) i Azure IoT-tvillingar i begränsad till 4 KB; för längre utdata se Bra metoder

• Exempel från IoT Hub och verkliga enheter

  • Omstartsresultat

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

  • Resultat för anpassad konfiguration (tidszon):

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

  • Ytterligare exempel finns i:

    • Starta om eller stänga av enheter med Azure IoT och OSConfig
    • Anpassad konfiguration och rapportering med Azure IoT och OSConfig

Viktigt

Version 1.0.3 (publicerad 28 juni 2022) innehåller icke-bakåtkompatibla ändringar av medlemsnamn som kan påverka befintliga användare. Mer information finns i: Medlemsnamn övergår från PascalCase till camelCase i version 1.0.3

Nästa steg

En översikt över OSConfig-scenarier och -funktioner finns i:

• Vad är OSconfig för IoT

Specifika praktiska exempel finns i:

• Skapa en OSConfig-labbmiljö (med Azure IoT) på 5 minuter
• Snabbstart: Frågeexempel för att komma igång med OSConfig och Azure IoT
• Vad kan jag etablera och hantera?