Opdrachten gebruiken in een Azure IoT Central-oplossing

Deze handleiding laat zien hoe u opdrachten gebruikt die zijn gedefinieerd in een apparaatsjabloon.

Een operator kan de IoT Central-gebruikersinterface gebruiken om een opdracht op een apparaat aan te roepen. Opdrachten bepalen het gedrag van een apparaat. Een operator kan bijvoorbeeld een opdracht aanroepen om een apparaat opnieuw op te starten of diagnostische gegevens te verzamelen.

Een apparaat kan:

• Reageer onmiddellijk op een opdracht.
• Reageer op IoT Central wanneer deze de opdracht ontvangt en informeer vervolgens later IoT Central wanneer de langlopende opdracht is voltooid.

Standaard verwachten opdrachten dat een apparaat is verbonden en mislukt als het apparaat niet kan worden bereikt. Als u de optie Wachtrij als offline selecteert in de gebruikersinterface van het apparaatsjabloon, kan een opdracht in de wachtrij worden geplaatst totdat een apparaat online is. Deze offlineopdrachten worden verderop in dit artikel beschreven in een aparte sectie.

Zie IoT Plug and Play-conventies voor meer informatie over de IoT Plug en Play-opdrachten.

Zie Telemetrie-, eigenschaps- en opdrachtpayloads voor meer informatie over de opdrachtgegevens die een apparaat met IoT Central uitwisselt.

Zie De Rest API van IoT Central gebruiken om apparaten te beheren voor meer informatie over het beheren van opdrachten met behulp van de REST API van IoT Central.

Zie Communiceren met een IoT-hub met behulp van het MQTT-protocol voor meer informatie over het implementeren van opdrachten op een apparaat zonder de apparaat-SDK's te gebruiken.

Uw opdrachten definiëren

Standaardopdrachten worden naar een apparaat verzonden om het apparaat te instrueren iets te doen. Een opdracht kan parameters bevatten met aanvullende informatie. Een opdracht voor het openen van een klep op een apparaat kan bijvoorbeeld een parameter hebben die aangeeft hoeveel de klep moet worden geopend. Opdrachten kunnen ook een retourwaarde ontvangen wanneer het apparaat de opdracht voltooit. Een opdracht waarmee een apparaat wordt gevraagd om bepaalde diagnostische gegevens uit te voeren, kan bijvoorbeeld een diagnostisch rapport ontvangen als retourwaarde.

Opdrachten worden gedefinieerd als onderdeel van een apparaatsjabloon. In de volgende schermopname ziet u de opdrachtdefinitie Max-Min rapport ophalen in de apparaatsjabloon Thermostaat . Deze opdracht heeft zowel aanvraag- als antwoordparameters:

In de volgende tabel ziet u de configuratie-instellingen voor een opdrachtmogelijkheid:

Veld	Description
Weergavenaam	De opdrachtwaarde die wordt gebruikt op dashboardtegels en apparaatformulieren.
Naam	De naam van de opdracht. IoT Central genereert een waarde voor dit veld op basis van de weergavenaam, maar u kunt indien nodig uw eigen waarde kiezen. Dit veld moet alfanumeriek zijn. De apparaatcode maakt gebruik van deze naamwaarde .
Mogelijkheidstype	Bevelen.
In de wachtrij plaatsen als offline	Of u deze opdracht een offlineopdracht wilt maken.
Description	Een beschrijving van de commando-functionaliteit.
Comment	Opmerkingen over de opdrachtmogelijkheid.
Aanvraag	De payload voor de apparaatopdracht.
Reactie	De belading van het antwoord op de apparaatopdracht.

Zie Opdrachten voor IoT Plug en Play >voor meer informatie over de Digital Twin Definition Language (DTDL) die Azure IoT Central gebruikt om opdrachten in een apparaatsjabloon te definiëren.

Met optionele velden, zoals weergavenaam en beschrijving, kunt u meer details toevoegen aan de interface en mogelijkheden.

Standaardopdrachten

Als u een standaardopdracht wilt afhandelen, verzendt een apparaat een antwoordwaarde zodra deze de opdracht van IoT Central ontvangt. U kunt de Azure IoT Device SDK gebruiken om standaardopdrachten te verwerken die worden aangeroepen door uw IoT Central-toepassing.

Zie zelfstudie: Een clienttoepassing maken en verbinden met uw Azure IoT Central-toepassing, bijvoorbeeld implementaties in meerdere talen.

In de volgende schermopname ziet u hoe het geslaagde opdrachtantwoord wordt weergegeven in de IoT Central-gebruikersinterface:

Opmerking

Voor standaardopdrachten is er een time-out van 30 seconden. Als een apparaat niet binnen 30 seconden reageert, gaat IoT Central ervan uit dat de opdracht is mislukt. Deze time-outperiode kan niet worden geconfigureerd.

Langlopende opdrachten

Bij een langlopende opdracht voltooit een apparaat de opdracht niet onmiddellijk. In plaats daarvan bevestigt het apparaat de ontvangst van de opdracht en bevestigt later dat de opdracht is voltooid. Met deze methode kan een apparaat een langdurige bewerking voltooien zonder de verbinding met IoT Central open te houden.

Opmerking

Langlopende opdrachten maken geen deel uit van de IoT Plug en Play-conventies. IoT Central heeft een eigen conventie voor het implementeren van langlopende opdrachten.

In deze sectie ziet u hoe een apparaat het verzenden van een bevestiging kan vertragen dat de opdracht is voltooid.

In het volgende codefragment ziet u hoe een apparaat een langlopende opdracht kan implementeren:

Opmerking

In dit artikel wordt Node.js gebruikt om het eenvoudig te maken.

client.onDeviceMethod('rundiagnostics', commandHandler);

// ...

const commandHandler = async (request, response) => {
  switch (request.methodName) {
  case 'rundiagnostics': {
    console.log('Starting long-running diagnostics run ' + request.payload);
    await sendCommandResponse(request, response, 202, 'Diagnostics run started');

    // Long-running operation here
    // ...

    const patch = {
      rundiagnostics: {
        value: 'Diagnostics run complete at ' + new Date().toLocaleString()
      }
    };

    deviceTwin.properties.reported.update(patch, function (err) {
      if (err) throw err;
      console.log('Properties have been reported for component');
    });
    break;
  }
  default:
    await sendCommandResponse(request, response, 404, 'unknown method');
    break;
  }
};

De aanroep van onDeviceMethod stelt de commandHandler methode in. Deze opdrachthandler:

1. Controleert de naam van de opdracht.
2. Roept sendCommandResponse aan om het antwoord naar IoT Central terug te sturen. Dit antwoord bevat de 202 antwoordcode om openstaande resultaten aan te geven.
3. Voltooit de langdurige bewerking.
4. Gebruikt een gerapporteerde eigenschap met dezelfde naam als de opdracht om IoT Central te laten weten dat de opdracht is voltooid.

In de volgende schermopname ziet u de Gebruikersinterface van IoT Central wanneer deze de update van de eigenschap ontvangt die aangeeft dat de opdracht is voltooid:

Offlineopdrachten

In deze sectie ziet u hoe een apparaat een offlineopdracht verwerkt. Als een apparaat online is, kan het de offlineopdracht verwerken zodra het is ontvangen. Als een apparaat offline is, wordt de offlineopdracht verwerkt wanneer het vervolgens verbinding maakt met IoT Central. Apparaten kunnen geen retourwaarde verzenden als reactie op een offlineopdracht.

Opmerking

Offlineopdrachten maken geen deel uit van de IoT Plug en Play-conventies. IoT Central heeft een eigen conventie voor het implementeren van offlineopdrachten.

Opmerking

In dit artikel wordt Node.js gebruikt om het eenvoudig te maken.

In de volgende schermopname ziet u een offlineopdracht met de naam GenerateDiagnostics. De aanvraagparameter is een object met de eigenschap DateTime met de naam StartTime en een eigenschap voor een geheel getal met de naam Bank:

In het volgende codefragment ziet u hoe een client naar offlineopdrachten kan luisteren en de inhoud van het bericht kan weergeven:

client.on('message', function (msg) {
  console.log('Body: ' + msg.data);
  console.log('Properties: ' + JSON.stringify(msg.properties));
  client.complete(msg, function (err) {
    if (err) {
      console.error('complete error: ' + err.toString());
    } else {
      console.log('complete sent');
    }
  });
});

De uitvoer van het vorige codefragment toont de payload met de waarden StartTime en Bank. De eigenschappenlijst bevat de opdrachtnaam in het lijstitem method-name :

Body: {"StartTime":"2021-01-06T06:00:00.000Z","Bank":2}
Properties: {"propertyList":[{"key":"iothub-ack","value":"none"},{"key":"method-name","value":"GenerateDiagnostics"}]}

Opmerking

De standaard time-to-live voor offlineopdrachten is 24 uur, waarna het bericht verloopt.

Opdrachten op niet-toegewezen apparaten

U kunt opdrachten aanroepen op een apparaat dat niet is toegewezen aan een apparaatsjabloon. Als u een opdracht wilt aanroepen op een niet-toegewezen apparaat, gaat u naar het apparaat in de sectie Apparaten , selecteert u Apparaat beheren en vervolgens Opdracht. Voer de naam van de methode, nettolading en eventuele andere vereiste waarden in. In de volgende schermopname ziet u de gebruikersinterface die u gebruikt om een opdracht aan te roepen:

Volgende stappen

Nu u weet hoe u opdrachten kunt gebruiken in uw Azure IoT Central-toepassing, raadpleegt u telemetrie-, eigenschaps- en opdrachtenpayloads voor meer informatie over de parameters van opdrachten en maakt u een clienttoepassing en verbindt u deze met uw Azure IoT Central-toepassing om volledige codevoorbeelden in verschillende talen te zien.