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 selecteert als offline in de gebruikersinterface van de 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 en Play conventies voor meer informatie over de IoT Pug- en Play-opdrachten.

Zie Nettoladingen telemetrie, eigenschap en opdracht voor meer informatie over de opdrachtgegevens die een apparaat uitwisselt met IoT Central.

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	Omschrijving
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 .
Type mogelijkheid	Opdracht.
Wachtrij als offline	Of u deze opdracht een offlineopdracht wilt maken.
Beschrijving	Een beschrijving van de opdrachtmogelijkheid.
Opmerking	Opmerkingen over de opdrachtmogelijkheid.
Aanvraag	De nettolading voor de apparaatopdracht.
Respons	De nettolading van het antwoord van de apparaatopdracht.

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

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 Bijvoorbeeld implementaties in meerdere talen een clienttoepassing maken en verbinden met uw Azure IoT Central-toepassing.

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

Notitie

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

In een langlopende opdracht wordt de opdracht niet onmiddellijk voltooid op een apparaat. 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.

Notitie

Langlopende opdrachten maken geen deel uit van de Conventies van IoT Plug en Play. 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:

Notitie

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 voor onDeviceMethod het instellen van de commandHandler methode. Deze opdrachthandler:

1. Controleert de naam van de opdracht.
2. Oproepen sendCommandResponse om het antwoord terug te sturen naar IoT Central. 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.

Notitie

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

Notitie

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 nettolading 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"}]}

Notitie

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 hebt geleerd hoe u opdrachten kunt gebruiken in uw Azure IoT Central-toepassing, raadpleegt u nettoladingen telemetrie, eigenschap en opdracht voor meer informatie over opdrachtparameters en maakt en verbindt u een clienttoepassing met uw Azure IoT Central-toepassing om volledige codevoorbeelden in verschillende talen te bekijken.