Delen via

Aangepaste configuratie en rapportage met Azure IoT en OSConfig

  • Artikel

Belangrijk

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

Dit artikel is ontworpen ter ondersteuning van personen die apparaten inrichten of beheren met Azure IoT. Als dat niet lijkt op u, kunt u overwegen om doelgroepen te bekijken voor OSConfig-documentatie.

Met de functie CommandRunner -->RunCommand kunt u wat eenvoud wegruilen om flexibiliteit te verkrijgen. Wanneer dat nodig is, kunt u een abstractieniveau omlaag zetten om aangepaste rapportage en configuratie uit te voeren.

Veelvoorkomende voorbeelden van aangepaste rapportage en configuratie

  • Apparaatconnectiviteit met sleuteleindpunten controleren
  • Controleer of specifieke daemons worden uitgevoerd
  • Fouten opsporen of problemen met apparaten oplossen, bijvoorbeeld door logboekbestanden te verzamelen en te uploaden naar cloudopslag
  • Configureer alle apparaten voor het gebruik van de gewenste tijdzone bij het vastleggen van gegevens, het genereren van tijdstempels, enzovoort.
  • Rapporteren over (of configureren) uw eigen unieke apparaatonderdelen waarvan OSConfig anders nooit op de hoogte zou zijn
  • De mogelijkheden zijn eindeloos, bijna elke taak die u in een shell voor één apparaat kunt uitvoeren. U kunt dit doen met Azure IoT en OSConfig CommandRunner voor fleets of devices

Tip

Dit artikel is gericht op praktische voorbeelden met minimale uitleg. Zie voor technische achtergrond op CommandRunner: Werken met de CommandRunner-functie van OSConfig en Azure IoT.

Voorbeelden van use cases

Deze voorbeelden kunnen dienen als uitgangspunt om u aan te passen aan uw unieke omgeving.

Elk voorbeeld bevat stappen en schermopnamen voor het werken in de Azure Portal en voor het werken in bash met Azure CLI.

Elk voorbeeld bevat ook variaties voor één apparaat (bijvoorbeeld een scenario voor probleemoplossing) of voor veel apparaten (bijvoorbeeld een configuratie-inrichtings- of rapportagescenario).

Wat u kunt verwachten:

In de instructies voor één apparaat leest en schrijft u gerapporteerde en gewenste eigenschappen rechtstreeks in de OSConfig-dubbel voor een apparaat. In de instructies op schaal gebruikt u IoT Hub Configuraties (ook wel Bekend als Automatisch Apparaatbeheer of ADM) om gewenste eigenschappen naar veel tweelingen te pushen en IoT Hub Query's (onafhankelijk of gekoppeld aan configuraties als metrische gegevens) te gebruiken om de resultaten van apparaten te bekijken.

Vereisten voor de volgende voorbeelden

Als u dit artikel ter referentie gebruikt (u bent bijvoorbeeld hier om een eigenschapsnaam te kopiëren), zijn er geen vereisten.

Als u de voorbeelden op live systemen wilt proberen (aanbevolen), dan:

  1. U hebt een Azure-account met een IoT Hub

    In dit artikel wordt ervan uitgegaan dat u bekend bent met IoT Hub en gerelateerde hulpprogramma's. Er wordt bijvoorbeeld van uitgegaan dat u vertrouwd bent met het maken van IoT Hubs en het koppelen van apparaten. Als u liever een meer beschrijvende stapsgewijze inleiding tot het installeren en gebruiken van OSConfig helemaal zelf wilt gebruiken, raadpleegt u: Quickstart: Een enkel virtueel IoT-apparaat beheren met behulp van Azure CLI .

  2. U hebt ten minste één Linux-apparaat nodig waarop de OSConfig-agent is geïnstalleerd en verbonden met Azure IoT.

    Zie voor meer informatie: Hoe en waar de OSConfig-agent voor Linux moet worden geïnstalleerd.

  3. U gebruikt Azure Portal of Azure CLI om te communiceren met de apparaten via uw IoT Hub

    Voor verdere stappen kiest u de gewenste ervaring:

  1. Zorg ervoor dat u bent aangemeld bij Azure Portal en toegang hebt tot de overzichtspagina van uw IoT Hub met IoT Hub en apparaten in azure Portal

Tip

Er zijn twee dingen die u moet weten over CommandRunner-gedrag om succesvol te zijn met behulp van deze voorbeelden:

  • Zoals in de voorbeelden is gedemonstreerd, moet elke nieuwe aanvraag een nieuwe waarde bevatten voor commandId (dit kan elke tekenreeks zijn, bijvoorbeeld 'MyCmd01', 'MyCmd02').
  • Het proces is asynchroon, zodat de resultaten niet onmiddellijk beschikbaar zijn. De eenvoudigste procedure is om ongeveer één minuut te wachten nadat u een CommandRunner-aanvraag hebt gestart. Na die minuut, zonder extra stappen van uw kant, zijn de resultaten beschikbaar in properties.reported.CommandRunner.commandStatus. Zie voor meer informatie over vernieuwingsgedrag, asynchrone statusupdates, enzovoort: Werken met de CommandRunner-functie van OSConfig en Azure IoT.

Voorbeeld 1. Apparaatconnectiviteit met specifieke eindpunten controleren

In dit voorbeeld vragen we de apparaten om www.github.com drie keer te pingen. We bekijken de afsluitcode van ping (geslaagd of mislukt) en we kunnen de tekstuele uitvoer van de ping-opdracht observeren.

  1. Navigeer vanaf de portalpagina van uw IoT Hub naar de OSConfig-moduledubbel voor het apparaat dat u wilt beheren. Voeg vervolgens het volgende toe aan de properties.desired sectie (gevolgd door een komma om deze te scheiden van het volgende item in properties.desired).

      "CommandRunner": {
             "__t": "c",
             "commandArguments": {
                 "commandId": "pingcmd",
                 "arguments": "ping -c 3 www.github.com",
                 "timeout": 120,
                 "singleLineTextResult": false,
                 "action": 3
             }
         }

    Schermopname met de gewenste inhoud van een dubbel voor een ping-opdracht met behulp van de OSConfig-module voor één apparaat vanuit De Azure-portal

  2. U kunt de connectiviteit van het apparaat controleren door het antwoord op de pingopdracht van de OSConfig-moduledubbel zelf te controleren. Schuif omlaag in de moduledubbel om gerapporteerde eigenschappen voor CommandRunner te zoeken. Controleer op resultCode: 0 , wat aangeeft dat de opdracht is geslaagd en textResult die de uitvoer van de ping-opdracht weergeeft.

    Schermopname met gerapporteerde dubbelinhoud voor een pingopdracht met behulp van osconfig-module voor één apparaat vanuit De Azure-portal

Voorbeeld 2. Inhoud van /etc/ssh/sshd_config ophalen

In dit voorbeeld gebruiken we CommandRunner om de inhoud van een bestand van elk apparaat vast te leggen. In dit voorbeeld uploaden we het bestand niet expliciet naar een cloudopslagservice, maar leggen we gewoon de inhoud ervan vast in de dubbel.

Belangrijk

Updates van eigenschappen van dubbels zijn beperkt tot 4 kB. De methode die hier wordt weergegeven, legt de bestandsinhoud (van cat) inline vast in de dubbel. Voor zeer kleine bestanden heeft deze methode het voordeel dat er geen externe opslagservices of referenties nodig zijn. Voor grotere bestanden is deze methode niet van toepassing. In plaats daarvan zou u logica opnemen in uw script/opdracht om het bestand naar on-premises of cloudopslag van uw keuze te uploaden. U kunt bijvoorbeeld verbinding maken met een cifs-share en het bestand daar kopiëren of de bestandsinhoud naar Azure Storage pushen.

  1. Ga op de portalpagina van uw IoT Hub naar de OSConfig-dubbel voor het apparaat dat u wilt beheren. Voeg vervolgens het volgende toe aan de properties.desired sectie (gevolgd door een komma om deze te scheiden van het volgende item in properties.desired). U kunt de bestandsnaam van uw keuze vervangen in het onderstaande argumentenveld .

      "CommandRunner": {
             "__t": "c",
             "commandArguments": {
                 "commandId": "sshdconfig",
                 "arguments": "cat /etc/ssh/sshd_config",
                 "timeout": 30,
                 "singleLineTextResult": false,
                 "action": 3
             }
         }

    Schermopname die laat zien hoe u de gewenste eigenschap van OSConfig-moduledubbel instelt om de bestandsinhoud van één apparaat te lezen met behulp van de OSConfig-module vanuit Azure Portal

  2. U kunt de bestandsinhoud van de moduledubbel zelf zien. Schuif omlaag in de moduledubbel om commandStatus te vinden onder gerapporteerde eigenschappen voor CommandRunner. Hier ziet u dit in de textResult. Controleer op resultCode: 0 , waarmee wordt aangegeven dat de opdracht is geslaagd en textResult waarmee de gewenste bestandsinhoud wordt weergegeven.

    "CommandRunner": {
             "__t": "c",
             "commandStatus": {
                 "commandId": "sshdconfig",
                 "resultCode": 0,
                 "textResult": "<sshd_config_file_contents>",
                 "currentState": 2
             }
          }

    Schermopname met osConfig-moduledubbel met de aangevraagde bestandsinhoud van één apparaat vanuit De Azure-portal

Voorbeeld 3. Een eenvoudig inlinescript implementeren om de tijdzone in te stellen op UTC en rapporteren over tijdzone

In dit voorbeeld ziet u een eenvoudige use-case waarbij zowel het script als de resultaten inline kunnen worden verwerkt als onderdeel van de dubbel. In het voorbeeld wordt de tijdzone ingesteld op UTC en wordt vervolgens een query uitgevoerd op de tijdzone zodra deze is ingesteld.

  1. Navigeer vanaf de portalpagina van uw IoT Hub naar de OSConfig-dubbel voor het apparaat dat u wilt beheren en voeg het volgende toe aan de properties.desired sectie, gevolgd door een komma om deze te scheiden van het volgende item in properties.desired. action=3 hieronder geeft de actie RunCommand op.

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

    Schermopname die laat zien hoe u de gewenste eigenschap instelt om de tijdzone op een apparaat bij te werken met behulp van de OSConfig-module vanuit Azure Portal

  2. Zodra de opdracht is uitgevoerd, schuift u omlaag naar de moduledubbel om commandStatus te vinden onder gerapporteerde eigenschappen voor CommandRunner. Hier ziet u de tekstResult de huidige tijdzone die is ingesteld op het apparaat.

    "CommandRunner": {
   "__t": "c",
   "commandStatus": {
      "commandId": "settimezonecmd",
      "resultCode": 0,
      "textResult": " Time zone: Etc/UTC (UTC, +0000)",
      "currentState": 2
   }
}

    Schermopname met het antwoord van het instellen van de tijdzoneopdracht op één apparaat vanuit Azure Portal

Voorbeeld 4. Een aangepast rapportagescript implementeren vanuit een onlineopslagplaats

In dit voorbeeld ziet u hoe u een script aanroept dat zich buiten de tweeling bevindt. U kunt bijvoorbeeld uw scripts in GitHub plaatsen. Dit patroon kan uit noodzaak ontstaan (script is te groot voor dubbel) of uit voorkeur. De opdracht in de dubbel is een eenvoudige wrapper. Het hoofdscript wordt gedownload en uitgevoerd.

Belangrijk

Ter ondersteuning van dit document hebben we een voorbeeldscript gepubliceerd. Dit voorbeeldscript wordt geleverd als een stand-in voor uw eigen script in GitHub of ergens anders. Er worden enkele gegevenspunten verzameld van het apparaat, waaronder een tijdstempel, daemonstatus en vrije schijfruimte. Controleer scripts van internet, inclusief deze, voordat u ze op uw apparaten uitvoert.

  1. Navigeer vanaf de portalpagina van uw IoT Hub naar de OSConfig-dubbel voor het apparaat dat u wilt beheren en voeg het volgende toe aan de properties.desired sectie, gevolgd door een komma om deze te scheiden van het volgende item inproperties.desired.

    "CommandRunner": {
    "__t": "c",
   "commandArguments": {
      "commandId": "runcustomscript",
      "arguments": "curl -s -L https://learn.microsoft.com/azure/osconfig/samples/report-multiple-datapoints-from-device.sh | tr -d \r| bash",
      "timeout": 60,
      "singleLineTextResult": false,
      "action": 3
   }
}

    Schermopname die laat zien hoe u dubbelinhoud bijwerkt om een aangepast script uit te voeren op één apparaat met behulp van Azure Portal

  2. Schuif omlaag in de moduledubbel om CommandRunner -->commandStatus te vinden in de sectie gerapporteerde eigenschappen van de dubbel. Controleer op resultCode: 0 , wat aangeeft dat de opdracht is geslaagd en textResult met de uitvoer van het script dat is uitgevoerd. Hier volgt een voorbeeld van uitvoer van de OSConfig-dubbel van een apparaat:

    "CommandRunner": {
   "__t": "c",
   "commandStatus": {
      "commandId": "runcustomscript",
      "resultCode": 0,
      "textResult": "+TIMESTAMP: 'Fri Jul  8 19:01:15 UTC 2022'  +DAEMON_STATUS: 'Active: active (running) since Mon 2022-06-27 19:02:46 UTC; 1 weeks 3 days ago'  +FREE_SPACE: '/dev/sda1       30309264 8811724  21481156  30% /'"
      "currentState": 2
   },
}

    Schermopname die laat zien hoe u dubbelinhoud controleert nadat een aangepast script is uitgevoerd op één apparaat met behulp van Azure Portal

Volgende stappen

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

Zie voor specifieke praktische voorbeelden: