Verwenden von Befehlen in einer Azure IoT Central-Lösung

  • Artikel

In dieser Schrittanleitung erfahren Sie, wie Sie Befehle verwenden können, die in einer Gerätevorlage definiert sind.

Ein Operator kann über die Benutzeroberfläche von IoT Central einen Befehl auf einem Gerät aufrufen. Befehle steuern das Verhalten eines Geräts. Beispielsweise kann ein Operator einen Befehl zum Neustarten eines Geräts oder zum Sammeln von Diagnosedaten aufrufen.

Ein Gerät kann Folgendes durchführen:

  • Sofortiges Reagieren auf einen Befehl
  • Benachrichtigen von IoT Central beim Empfangen des Befehls und späteres Informieren von IoT Central über den Abschluss eines zeitintensiven Befehls

Standardmäßig wird in Befehlen erwartet, dass ein Gerät verbunden ist. Sie führen daher zu einem Fehler, wenn das Gerät nicht erreicht werden kann. Wenn Sie auf der Benutzeroberfläche der Gerätevorlage die Option Warteschlange (falls offline) auswählen, kann ein Befehl in die Warteschlange eingereiht werden, bis ein Gerät online geschaltet wird. Diese Offlinebefehle werden in einem separaten Abschnitt weiter unten in diesem Artikel beschrieben.

Weitere Informationen zu den IoT Plug & Play-Befehlskonventionen finden Sie unter IoT Plug & Play-Konventionen.

Weitere Informationen zu den Befehlsdaten, die ein Gerät mit IoT Central austauscht, finden Sie unter Telemetrie-, Eigenschaften- und Befehlsnutzlasten.

Informationen zum Verwalten von Befehlen mithilfe der IoT Central REST-API finden Sie unter Verwenden der IoT Central REST-API zum Steuern von Geräten..

Informationen zum Implementieren von Befehlen in einem Gerät ohne Verwendung der Geräte-SDKs finden Sie unter Kommunizieren mit einem IoT-Hub mithilfe des MQTT-Protokolls.

Definieren Ihrer Befehle

Standardbefehle werden an ein Gerät gesendet, um das Gerät anzuweisen, eine Aktion auszuführen. Ein Befehl kann Parameter mit zusätzlichen Informationen enthalten. So könnte ein Befehl zum Öffnen eines Ventils auf einem Gerät z. B. einen Parameter enthalten, der angibt, wie weit das Ventil geöffnet werden soll. Befehle können auch einen Rückgabewert empfangen, wenn das Gerät den Befehl abschließt. Beispielsweise kann ein Befehl, der ein Gerät anweist, einige Diagnosen auszuführen, einen Diagnosebericht als Rückgabewert erhalten.

Befehle werden als Teil einer Gerätevorlage definiert. Der folgende Screenshot zeigt die Definition des Befehls Get Max-Min report in der Gerätevorlage Thermostat. Dieser Befehl weist sowohl Anforderungs- als auch Antwortparameter auf:

Screenshot showing Get Max Min Report command in Thermostat device template.

In der folgenden Tabelle sind die Konfigurationseinstellungen für eine Befehlsfunktion angegeben:

Feld Beschreibung
Anzeigename Der auf Dashboardkacheln und Geräteformularen verwendete Befehlswert.
Name Der Name des Befehls. IoT Central generiert einen Wert für dieses Feld aus dem Anzeigenamen, Sie können aber ggf. einen eigenen Wert auswählen. Dieses Feld muss alphanumerisch sein. Der Wert von Name wird im Gerätecode verwendet.
Funktionstyp Befehl.
Warteschlange (wenn offline) Gibt an, ob dieser Befehl als Offlinebefehl ausgeführt werden soll.
Beschreibung Eine Beschreibung der Befehlsfunktion.
Kommentar Beliebige Kommentare zur Befehlsfunktion.
Anfordern Die Nutzdaten für den Gerätebefehl
Antwort Die Nutzdaten der Antwort auf den Gerätebefehl

Informationen zur Digital Twin Definition Language (DTDL), die Azure IoT Central zum Definieren von Befehlen in einer Gerätevorlage verwendet, finden Sie unter IoT Plug & Play-Konventionen > Befehle.

Über optionale Felder, z. B. Anzeigename und Beschreibung, können Sie der Schnittstelle und den Funktionen weitere Details hinzufügen.

Standardbefehle

Um einen Standardbefehl zu verarbeiten, sendet ein Gerät einen Antwortwert, sobald es den Befehl von IoT Central empfängt. Sie können das Azure IoT-Geräte-SDK verwenden, um Standardbefehle zu verarbeiten, die von Ihrer IoT Central-Anwendung aufgerufen werden.

Beispielimplementierungen in mehreren Sprachen finden Sie unter Erstellen und Verbinden einer Clientanwendung mit Ihrer Azure IoT Central-Anwendung.

Der folgende Screenshot zeigt, wie die Antwort bei einer erfolgreichen Befehlsausführung auf der Benutzeroberfläche von IoT Central angezeigt wird:

Screenshot showing how to view command payload for a standard command.

Hinweis

Für Standardbefehle gibt es ein Timeout von 30 Sekunden. Wenn ein Gerät nicht innerhalb von 30 Sekunden reagiert, geht IoT Central davon aus, dass der Befehl fehlgeschlagen ist. Dieser Timeoutzeitraum kann nicht konfiguriert werden.

Befehle mit langer Ausführungsdauer

Bei einem lang laufenden Befehl schließt ein Gerät den Befehl nicht sofort ab. Stattdessen bestätigt das Gerät den Empfang des Befehls und bestätigt später, dass der Befehl abgeschlossen wurde. Mit diesem Ansatz kann ein Gerät einen lang laufenden Vorgang abschließen, ohne die Verbindung mit IoT Central offen zu halten.

Hinweis

Lang laufende Befehle sind nicht Teil der IoT Plug & Play-Konventionen. IoT Central verfügt über eine eigene Konvention zum Implementieren von lang laufenden Befehlen.

In diesem Abschnitt wird gezeigt, wie ein Gerät das Senden einer Bestätigung zum Befehlsabschluss verzögern kann.

Der folgende Codeausschnitt zeigt, wie ein Gerät einen zeitintensiven Befehl implementieren kann:

Hinweis

In diesem Artikel wird der Einfachheit halber „Node.js“ verwendet.

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;
  }
};

Mit dem Aufruf von onDeviceMethod wird die commandHandler-Methode eingerichtet. Dieser Befehlshandler führt Folgendes aus:

  1. Er überprüft den Namen des Befehls.
  2. Er ruft sendCommandResponse auf, um die Antwort zurück an IoT Central zu senden. Diese Antwort enthält den Antwortcode 202, der ausstehende Ergebnisse anzeigt.
  3. Er schließt den zeitintensiven Vorgang ab.
  4. Er informiert IoT Central mit einer gemeldeten Eigenschaft, die denselben Namen wie der Befehl hat, dass der Befehl abgeschlossen wurde.

Der folgende Screenshot zeigt die Benutzeroberfläche von IoT Central, wenn der Dienst als Update der Eigenschaft die Angabe empfängt, dass der Befehl abgeschlossen wurde:

Screenshot that shows long-running command finished.

Offlinebefehle

In diesem Abschnitt wird gezeigt, wie Geräte Offlinebefehle verarbeiten. Wenn ein Gerät online ist, kann es einen Offlinebefehl direkt beim Empfang verarbeiten. Ist das Gerät jedoch offline, verarbeitet es den Offlinebefehl erst, wenn es das nächste Mal eine Verbindung mit IoT Central herstellt. Geräte können keinen Rückgabewert als Antwort auf einen Offlinebefehl senden.

Hinweis

Offlinebefehle sind nicht Teil der IoT Plug & Play-Konventionen. IoT Central verfügt über eine eigene Konvention zum Implementieren von Offlinebefehlen.

Hinweis

In diesem Artikel wird der Einfachheit halber „Node.js“ verwendet.

Der folgende Screenshot zeigt den Offlinebefehl GenerateDiagnostics. Der Anforderungsparameter ist ein Objekt mit der DateTime-Eigenschaft StartTime und der ganzzahligen Enumerationseigenschaft Bank:

Screenshot that shows the UI for an offline command.

Der folgende Codeausschnitt zeigt, wie ein Client auf Offlinebefehle lauschen und den Nachrichteninhalt anzeigen kann:

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');
    }
  });
});

Die Ausgabe vom vorherigen Codeausschnitt zeigt die Nutzdaten mit den Werten für StartTime und Bank. Die Eigenschaftenliste enthält den Befehlsnamen im Listenelement method-name:

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

Hinweis

Die standardmäßige Gültigkeitsdauer für Offlinebefehle beträgt 24 Stunden. Danach läuft die Nachricht ab.

Befehle auf nicht zugewiesenen Geräten

Sie können Befehle auf einem Gerät aufrufen, das keiner Gerätevorlage zugewiesen ist. Um einen Befehl auf einem nicht zugewiesenen Gerät aufzurufen, navigieren Sie im Abschnitt Geräte zu dem Gerät und wählen Gerät verwalten und dann Befehl aus. Geben Sie den Methodennamen, die Nutzlast und alle anderen erforderlichen Werte ein. Der folgende Screenshot zeigt die Benutzeroberfläche, die Sie zum Aufrufen eines Befehls verwenden:

Screenshot that shows an example of calling a command on an unassigned device.

Nächste Schritte

Nachdem Sie gelernt haben, wie Sie Befehle in Azure IoT Central-Anwendungen verwenden, finden Sie unter Telemetrie-, Eigenschafts- und Befehlsnutzlasten weitere Informationen zu Befehlsparametern und unter Erstellen einer Clientanwendung und Verbinden dieser Anwendung mit Ihrer Azure IoT Central-Anwendung umfassende Codebeispiele in verschiedenen Programmiersprachen.