Interactie met de CommandRunner-functie van OSConfig en Azure IoT

De meeste apparaateigenschappen die door OSConfig worden weergegeven, zijn discreet en geabstraheerd op basis van implementatiedetails. Wanneer u bijvoorbeeld gebruikt HostName.desiredName om de hostnaam van een apparaat in te stellen, hoeft u zich geen zorgen te maken over de smaak van het besturingssysteem, over scriptafhankelijkheden van runtime of over timingnuances.

Soms wilt u echter eenvoud inruilen voor flexibiliteit. Bijvoorbeeld:

• U moet aangepaste gegevens ophalen van het apparaat, zoals het rapporteren van de resultaten van vanuit het perspectief van ping example.com het apparaat
• U moet iets configureren op het apparaat waar geen bestaande osconfig-gewenste/beschrijfbare eigenschap is

De CommandRunner-functie van OSConfig maakt aangepaste configuratie en rapportage mogelijk via shellopdrachten/scripts. Het omvat ook bepaalde vooraf gedefinieerde acties (afsluiten, opnieuw opstarten) waarvoor geen scripts hoeven te worden uitgevoerd.

Tip

In dit naslagartikel worden de concepten van CommandRunner, het interactiemodel, enzovoort beschreven. Zie voor concrete gebruiksvoorbeelden:

• Apparaten opnieuw opstarten of afsluiten met Azure IoT en OSConfig
• Aangepaste configuratie en rapportage met Azure IoT en OSConfig

Het interactiemodel en de belangrijkste eigenschappen/velden

Samenvatting van interactiemodel

Hoewel genuanceerd gebruik mogelijk is (en verderop in dit artikel wordt beschreven), is het basisinteractiemodel eenvoudig:

• U initieert een opdrachtaanvraag door te schrijven naar desired commandArguments in de dubbel.
• U krijgt de resultaten door de gerapporteerde commandStatus gegevens van de tweeling te lezen.

Belangrijk

De nettoladingen die in dit diagram worden weergegeven, worden verwijderd om de in-/uitstroom te benadrukken. Voor het volledige objectmodel, inclusief vereiste leden die hier niet worden weergegeven, raadpleegt u: Het volledige objectmodel

De retour-id is: commandId

In het bovenstaande diagram ziet u dat zowel commandArguments als commandStatus een veld met de naam commandIdbevatten. Dit is de retour-id-koppelingsaanvraag en het resultaat van deze asynchrone bewerking.

De aanroeper (beheer- of beheerhulpprogrammaketen) kiest de waarde commandId.

Tip

commandId is vereist in commandArguments. Bellers gebruiken doorgaans een van deze patronen bij het kiezen van waarden:

• Monotone waarden zoals '1' (voor eerste aanvraag), '2' (voor tweede aanvraag), enzovoort. of beschrijvende waarden zoals 'my_ping_command'

  Deze zijn goed geschikt voor ad-hoconderzoek; ze vereisen geen planning en kunnen eenvoudig worden getypt bij het bewerken van dubbelinhoud

• Hoge entropie automatisch gegenereerde waarden, zoals UUID's

  Deze zijn zeer geschikt voor grootschalige programmatische gebruik waarbij een back-end van een cloudoplossing programmatisch waarden maakt en bijhoudt

Een nieuwe waarde van commandId in commandArguments geeft aan dat dit een nieuwe aanvraag is. In de context van de dubbel van één apparaat is het vullen van een nieuwe commandId ongeveer vergelijkbaar met het invullen van 'Enter' in een shell-omgeving.

commandId Maakt het ook mogelijk om meerdere aanvragen bij te houden. CommandRunner op elk apparaat kan in de loop van de tijd meerdere aanvragen ontvangen (en de status hiervan rapporteren). Ondertussen kunnen de commandArguments onderdelen en commandStatus in de dubbel van elk apparaat slechts één aanvraag op elk moment beschrijven. commandId is de retour-id die de aanroeper in staat stelt om te begrijpen (en te bepalen) welke eerdere aanvraag momenteel wordt beschreven door commandStatus. In feite commandStatus communiceert 'voor uw aanvraag waarbij de id 'foo' was <, is de status ...>'.

Wanneer wordt commandStatus bijgewerkt?

Er zijn twee triggers voor CommandRunner op het apparaat om bij te werken commandStatus.

1. Achtergrond vernieuwen

   commandStatus wordt bijgewerkt met een regelmatig interval (de standaardwaarde is 30 seconden). Standaard zorgt deze achtergrondvernieuwing ervoor dat deze de status van de meest recente aanvraag weergeeft.

   In de praktijk betekent dit dat u na het indienen van een aanvraag via commandArguments na ongeveer 30-60 seconden de bijbehorende status in commandStatus kunt verwachten.

2. refreshCommandStatus

   refreshCommandStatus is een mechanisme waarmee twee geavanceerde gebruiksvoorbeelden worden aangepakt:

   1. U hebt meerdere aanvragen in de loop van de tijd verzonden via commandArgumentsen u wilt de status van een specifieke aanvraag zien, niet de meest recente aanvraag
   2. U wilt niet wachten op het vernieuwen van de achtergrond, zelfs niet als u alleen geïnteresseerd bent in de meest recente aanvraag

   Als u dit mechanisme wilt activeren, raadpleegt u de documentatie van het objectmodel hieronder voor commandArguments.

Goede procedures voor aangepaste configuratie en rapportage met CommandRunner

1. Overwegingen over grootte

   Voor korte opdrachten/scripts en korte uitvoer kunt u rechtstreeks inline werken via de dubbel. Deze aanpak heeft voordelen, met name omdat er geen netwerk- of verificatieafhankelijkheid is buiten IoT Hub. Het belangrijkste nadeel van deze benadering is dat de invoer (inclusief de tekst van uw script/opdrachten) en uitvoer (inclusief vastgelegde console-uitvoer) elk beperkt zijn tot 4 kB.

   Voor langere scripts kunt u het script ergens anders opslaan (zoals GitHub) en dit aanroepen vanuit een minimale wrapper-opdracht die u via de dubbel doorgeeft aan OSConfig. Zie aangepaste configuratie en rapportage met Azure IoT en OSConfig voor voorbeelden. Onafhankelijk van de grootte kunt u uw scripts ook liever beheren in GitHub of iets dergelijks, waarbij de inhoud van de dubbels eenvoudigweg naar deze scripts verwijst.

   Voor scripts/opdrachten waarvan de console-uitvoer te groot is voor de dubbel, kunt u logica opnemen in het script om resultaten te verzenden naar on-premises of cloudopslag in plaats van naar stdout. Zie aangepaste configuratie en rapportage met Azure IoT en OSConfig voor voorbeelden.

2. Zelfstandige, niet-interactieve opdrachten/scripts gebruiken

   Minder retouren zijn beter, één retour is het beste. OSConfig en CommandRunner zijn geoptimaliseerd voor schaalaanpassing en niet voor interactiviteit. Hoewel het mogelijk is om CommandRunner serieel te gebruiken (de ene opdracht na de andere, vergelijkbaar met een live synchrone terminal), is de ervaring niet optimaal. Er is geen manier om interactieve shellprompts af te handelen, u moet een commandId toewijzen aan elke aanvraag, u moet wachten op dubbelsynchronisatie, enzovoort.

   Zie CommandRunner in plaats daarvan als een manier om aangepaste configuratie en rapportage op schaal te realiseren. U kunt een niet-interactief script (of een vooraf gedefinieerde actie zoals opnieuw opstarten) asynchroon distribueren naar één apparaat of miljoenen apparaten en u kunt de resultaten rapporteren, zelfs wanneer ze zich in de loop van de tijd ontwikkelen (bijvoorbeeld naarmate nieuwe apparaten aan het wagenpark worden toegevoegd).

   Met andere woorden, stel dat u vier opdrachten moet uitvoeren op alle huidige en toekomstige Ubuntu 20.04-apparaten in Spanje. Zie dat niet als 4 afzonderlijke opeenvolgende toepassingen van CommandRunner, zie het als één gebruik van CommandRunner waarbij de nettolading uw vier opdrachten bevat. Ondertussen kan een cloudwerkstroom zoals IoT Hub-configuraties ervoor zorgen dat dit wordt gedistribueerd naar alle huidige en toekomstige apparaten die binnen het bereik moeten vallen.

Het volledige objectmodel

Belangrijk

Versie 1.0.3 (gepubliceerd op 28 juni 2022) bevat wijzigingen die fouten veroorzaken in ledennamen die van invloed kunnen zijn op bestaande gebruikers. Zie voor meer informatie: Ledennamen gaan van PascalCase naar camelCase in versie 1.0.3

De volgende informatie is van toepassing op gewone gewenste/gerapporteerde weergaven van het objectmodel en verbeterde DTDL-weergaven. Zie What OSConfig users need know about 'plain desired/reported' vs 'DTDL enhanced' toolchains voor meer informatie.

commandArguments (ingesteld door beheerder)

• Beschrijving: invoer van beheerder, activeert een nieuwe opdrachtaanvraag of activeert vernieuwing van commandStatus.

• Pad: properties.desired.CommandRunner.commandArguments (CommandRunner onderdeel -->commandArguments beschrijfbare eigenschap)

• Leden

  Naam	Type	Opmerkingen
  commandId	tekenreeks	• Beller opgegeven aanvraag-id; zie hierboven voor achtergrond • commandArguments wordt genegeerd wanneer commandId leeg is • Zie het volgende voor interactie tussen commandId en actie
  action	enum/int	Het volgende moet worden gekoppeld aan een nieuwe waarde van commandId: • 1 (opnieuw opstarten) • 2 (afsluiten) • 3 (runOpdracht); initieert shell-opdracht/-script voor aangepaste configuratie of rapportage Het volgende moet worden gekoppeld aan een eerder gebruikte CommandID: • 4 (refreshCommandStatus) zorgt ervoor dat commandStatus een specifieke aanvraag beschrijft die wordt geïdentificeerd door commandId
  Argumenten	tekenreeks	• Wanneer actie 1 (opnieuw opstarten) of 2 (afsluiten) is, kunt u een optioneel aantal seconden vertragen voordat de actie wordt geactiveerd • Wanneer actie 3 is (Opdracht uitvoeren), moet de opdrachtregel worden uitgevoerd, bijvoorbeeld ping -c 2 example.com • Genegeerd voor elk ander actietype • Grootte van opdrachtArgumenten (meestal gedomineerd door argumenttekst) in Azure IoT-dubbels in beperkt tot 4 kB; Zie Good practices voor langere scripts
  singleLineTextResult	booleaans	• Wanneer actie 3 is (Opdracht uitvoeren), optionele wisselknop om aan te geven of nieuwe regels moeten worden verwijderd uit console-uitvoer • Genegeerd voor elk ander actietype
  timeout	int	• Wanneer actie 3 is (runCommand), worden langlopende aanvragen na dit aantal seconden beëindigd • Optioneel (standaard is 30) • Genegeerd voor elk ander actietype

• Voorbeelden van IoT Hub en echte apparaten

  • Aanvraag voor opnieuw opstarten:

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

  • Aanvraag voor aangepaste configuratie (tijdzone):

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

  • Zie voor meer voorbeelden:

    • Apparaten opnieuw opstarten of afsluiten met Azure IoT en OSConfig
    • Aangepaste configuratie en rapportage met Azure IoT en OSConfig

commandArguments (bevestiging van apparaat)

• Beschrijving: dit is de bevestiging van de OSConfig-agent op het apparaat dat deze de waarde commandArguments van de beheerderszijde heeft ontvangen

• Pad: properties.reported.CommandRunner.commandArguments (het bevestigingsgedeelte van het apparaat van commandArguments de beschrijfbare eigenschap)

• Leden:

  Naam	Type	Opmerkingen
  waarde	map	Moet spiegelen properties.desired.CommandRunner.commandArguments, waarmee wordt aangegeven dat het apparaat online is en de aanvraag heeft ontvangen
  Ac	int	Statuscode, nominale hoofdletter is waarde 200

commandStatus

• Beschrijving: geeft de status en uitvoer van een aanvraag die eerder is ingediend via commandArguments

• Pad: properties.reported.CommandRunner.commandStatus (CommandRunner onderdeel -->commandStatus eigenschap Alleen-lezen)

• Leden

  Naam	Type	Opmerkingen
  commandId	tekenreeks	• Geeft aan welke eerder ontvangen aanvraag momenteel wordt beschreven door Commandstatus • Standaard wordt de meest recente aanvraag weergegeven • Beller kan deze focus wijzigen om een specifieke aanvraag te beschrijven via het hierboven beschreven mechanisme refreshCommandStatus
  resultCode	int	De afsluitcode van de aangevraagde opdracht. Vergelijkbaar echo $? met in bash
  currentState	enum/int	• Nominale hoofdletter is waarde 2 (succeeded) • Bekijk de metagegevens voor een volledige lijst met mogelijke waarden
  textResult	tekenreeks	• De console-uitvoer van de aangevraagde opdracht • Grootte van commandStatus (meestal gedomineerd door het textResult-onderdeel) in Azure IoT-dubbels in beperkt tot 4 kB; Zie Goede procedures voor langere uitvoer

• Voorbeelden van IoT Hub en echte apparaten

  • Resultaat van opnieuw opstarten

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

  • Resultaat van aangepaste configuratie (tijdzone):

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

  • Zie voor meer voorbeelden:

    • Apparaten opnieuw opstarten of afsluiten met Azure IoT en OSConfig
    • Aangepaste configuratie en rapportage met Azure IoT en OSConfig

Belangrijk

Versie 1.0.3 (gepubliceerd op 28 juni 2022) bevat wijzigingen die fouten veroorzaken in ledennamen die van invloed kunnen zijn op bestaande gebruikers. Zie voor meer informatie: Ledennamen gaan van PascalCase naar camelCase in versie 1.0.3

Volgende stappen

Zie voor een overzicht van OSConfig-scenario's en -mogelijkheden:

• Wat is OSconfig voor IoT?

Zie voor specifieke praktijkvoorbeelden:

• In 5 minuten een OSConfig-testomgeving (met Azure IoT) maken
• Quickstart: Queryvoorbeelden om aan de slag te gaan met OSConfig en Azure IoT
• Wat kan ik inrichten en beheren?