Freigeben über

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

In dieser Anleitung erfahren Sie, wie Sie Befehle verwenden, die in einer Gerätevorlage definiert sind.

Ein Operator kann die IoT Central UI verwenden, um einen Befehl auf einem Gerät aufzurufen. Befehle steuern das Verhalten eines Geräts. Beispielsweise kann ein Operator einen Befehl aufrufen, um ein Gerät neu zu starten oder Diagnosedaten zu sammeln.

Ein Gerät kann:

  • Reagieren Sie sofort 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 erwarten Befehle, dass ein Gerät verbunden ist und fehlschlägt, wenn das Gerät nicht erreicht werden kann. Wenn Sie die Option "Bei Offline-Zustand in die Warteschlange einreihen" auswählen, kann in der Gerätevorlagen-UI ein Befehl in die Warteschlange gestellt werden, bis ein Gerät online geht. Diese Offlinebefehle werden weiter unten in diesem Artikel in einem separaten Abschnitt beschrieben.

Informationen zu den IoT-Pug- und Play-Befehlskonventionen finden Sie unter IoT Plug and Play-Konventionen.

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

Informationen zum Verwalten von Befehlen mithilfe der IoT Central REST-API finden Sie unter Verwendung 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 von Befehlen

Standardbefehle werden an ein Gerät gesendet, um das Gerät anzuweisen, etwas auszuführen. Ein Befehl kann Parameter mit zusätzlichen Informationen enthalten. Beispielsweise könnte ein Befehl zum Öffnen eines Ventils auf einem Gerät einen Parameter haben, der angibt, wie viel das Ventil öffnen soll. Befehle können auch einen Rückgabewert empfangen, wenn das Gerät den Befehl abgeschlossen hat. Beispielsweise könnte ein Befehl, der ein Gerät auffordern, einige Diagnosen auszuführen, einen Diagnosebericht als Rückgabewert erhalten.

Befehle werden als Teil einer Gerätevorlage definiert. Der folgende Screenshot zeigt die Befehlsdefinition „Max-Min-Bericht abrufen“ in der Vorlage „Thermostat“. Dieser Befehl hat sowohl Anforderungs- als auch Antwortparameter:

Screenshot des Befehls

Die folgende Tabelle zeigt die Konfigurationseinstellungen für eine Befehlsfunktion:

Feld Description
Anzeigename Der Befehlswert, der auf Dashboardkacheln und Geräteformularen verwendet wird.
Name Der Name des Befehls. IoT Central generiert einen Wert für dieses Feld aus dem Anzeigenamen, Aber Sie können bei Bedarf Ihren eigenen Wert auswählen. Dieses Feld muss alphanumerisch sein. Der Gerätecode verwendet diesen Name-Wert .
Fähigkeitstyp Befehl
Warteschlange (wenn offline) Gibt an, ob dieser Befehl ein Offlinebefehl ist.
Description Eine Beschreibung der Befehlsfunktion.
Kommentar Alle Kommentare zur Befehlsfunktion.
Anfrage Die Nutzlast 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 and Play Conventions > Commands.

Optionale Felder, z. B. Anzeigename und Beschreibung, ermöglichen es Ihnen, weitere Details zu der Schnittstelle und den Funktionen hinzuzufügen.

Standardbefehle

Um einen Standardbefehl zu verarbeiten, sendet ein Gerät einen Antwortwert, sobald er 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 im Lernprogramm: Erstellen und Verbinden einer Clientanwendung mit Ihrer Azure IoT Central-Anwendung.

Der folgende Screenshot zeigt, wie die erfolgreiche Befehlsantwort auf der Zentralen IoT-Benutzeroberfläche angezeigt wird:

Screenshot, der zeigt, wie Befehlsnutzlast für einen Standardbefehl angezeigt wird.

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.

Lang laufende Befehle

Bei einem lang ausgeführten 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 länger andauernden Vorgang abschließen, ohne die Verbindung zu IoT Central offen zu halten.

Hinweis

Lang andauernde Befehle sind nicht Teil der IoT Plug and Play-Konventionen. IoT Central verfügt über eine eigene Konvention zum Implementieren von langwierigen Befehlen.

In diesem Abschnitt wird gezeigt, wie ein Gerät das Senden einer Bestätigung, dass der Befehl abgeschlossen wurde, verzögern kann.

Der folgende Codeausschnitt zeigt, wie ein Gerät einen befehl mit langer Ausführung implementieren kann:

Hinweis

In diesem Artikel wird Node.js aus Gründen der Einfachheit 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;
  }
};

Der Aufruf von onDeviceMethod richtet die commandHandler Methode ein. Dieser Befehlshandler:

  1. Überprüft den Namen des Befehls.
  2. Ruft sendCommandResponse auf, um die Antwort an IoT Central zu senden. Diese Antwort enthält den 202 Antwortcode, der auf ausstehende Ergebnisse hinweist.
  3. Schließt den lang andauernden Vorgang ab.
  4. Verwendet eine gemeldete Eigenschaft mit demselben Namen wie der Befehl, um IoT Central mitzuteilen, dass der Befehl abgeschlossen wurde.

Der folgende Screenshot zeigt die IoT Central UI, wenn sie das Eigenschaftenupdate empfängt, das angibt, dass der Befehl abgeschlossen ist:

Screenshot, der zeigt, dass ein langjähriger Befehl abgeschlossen wurde.

Offline-Befehle

In diesem Abschnitt wird gezeigt, wie ein Gerät einen Offlinebefehl behandelt. Wenn ein Gerät online ist, kann es den Offlinebefehl verarbeiten, sobald es empfangen wird. Wenn ein Gerät offline ist, verarbeitet es den Offlinebefehl, wenn es als Nächstes eine Verbindung mit IoT Central herstellt. Geräte können keinen Rückgabewert als Reaktion auf einen Offlinebefehl senden.

Hinweis

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

Hinweis

In diesem Artikel wird Node.js aus Gründen der Einfachheit verwendet.

Der folgende Screenshot zeigt einen Offlinebefehl namens GenerateDiagnostics. Der Anforderungsparameter ist ein Objekt mit der Datetime-Eigenschaft "StartTime " und einer ganzzahligen Enumerationseigenschaft namens "Bank":

Screenshot der Benutzeroberfläche für einen Offlinebefehl.

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 aus dem vorherigen Codeausschnitt zeigt die Nutzdaten mit den Werten "StartTime" und "Bank". Die Eigenschaftenliste enthält den Befehlsnamen im Listenelement "Methodenname ":

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

Hinweis

Die Standardzeit für Offlinebefehle beträgt 24 Stunden, nach denen die Nachricht abläuft.

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 " zum Gerät, wählen Sie " 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, der ein Beispiel für das Aufrufen eines Befehls auf einem nicht zugewiesenen Gerät zeigt.

Nächste Schritte

Nachdem Sie nun wissen, wie Sie Befehle in Ihrer Azure IoT Central-Anwendung verwenden können, lesen Sie Telemetrie, Eigenschaft und Befehlsnutzlast, um mehr über Befehlsparameter zu erfahren und eine Clientanwendung mit Ihrer Azure IoT Central-Anwendung zu erstellen und zu verbinden , um vollständige Codebeispiele in verschiedenen Sprachen anzuzeigen.

  • Last updated on