Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # AWS IoT Device Management befehle **Wichtig** In dieser Dokumentation wird beschrieben, wie Sie die [Befehlsfunktion in](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#command-iot-namespace) verwenden können AWS IoT Device Management. Informationen zur Verwendung dieser Funktion für finden Sie AWS IoT FleetWise unter [Fernbefehle](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html). Sie sind allein dafür verantwortlich, Befehle auf sichere und gesetzeskonforme Weise bereitzustellen. Weitere Informationen zu Ihren Pflichten finden Sie in den [AWS Servicebedingungen für AWS IoT Dienste](https://aws.amazon.com/service-terms/). Verwenden Sie AWS IoT Device Management Befehle, um eine Anweisung aus der Cloud an ein Gerät zu senden, mit dem eine Verbindung besteht AWS IoT. Befehle zielen jeweils auf ein Gerät ab und können für Anwendungen mit niedriger Latenz und hohem Durchsatz verwendet werden, z. B. zum Abrufen von geräteseitigen Protokollen oder zum Initiieren einer Änderung des Gerätestatus. Der *Befehl* ist eine wiederverwendbare Ressource, die von verwaltet wird. AWS IoT Device Management Er enthält Konfigurationen, die angewendet werden, bevor sie auf dem Gerät veröffentlicht werden. Sie können eine Reihe von Befehlen für bestimmte Anwendungsfälle vordefinieren, z. B. das Einschalten einer Glühbirne oder das Entriegeln einer Fahrzeugtür. Mit der AWS IoT Befehlsfunktion können Sie: + Erstellen Sie wiederverwendbare Befehlsvorlagen mit statischen oder dynamischen Payloads und führen Sie sie dann auf bestimmten Geräten aus. + Als AWS IoT Dinge registrierte Zielgeräte oder nicht registrierte MQTT-Clients. + Führen Sie mehrere Befehle gleichzeitig auf demselben Gerät aus. + Aktivieren Sie Ereignisbenachrichtigungen und verfolgen Sie den Ausführungsstatus, während Geräte Befehle verarbeiten. In den folgenden Themen erfahren Sie, wie Sie Befehle erstellen, sie an Ihr Gerät senden und den vom Gerät gemeldeten Status abrufen. **Topics** + [Schnellstart](iot-commands-quickstart.md) + [Befehle, Konzepte und Status](iot-remote-command-concepts.md) + [Arbeitsablauf für Befehle auf hoher Ebene](iot-remote-command-workflow.md) + [Erstellen und Verwalten von Befehlen](iot-remote-command-create-manage.md) + [Starten und Überwachen von Befehlsausführungen](iot-remote-command-execution-start-monitor.md) + [Kennzeichnen einer Befehlsressource als veraltet](iot-remote-command-deprecate.md) # Schnellstart Gehen Sie wie folgt vor, um Ihren ersten Befehl zu senden: 1. **Voraussetzungen** — Stellen Sie sicher, dass Sie mit IoT Core, einem mit IoT Core verbundenen Gerät, IAM-Berechtigungen für Commands API-Operationen und einer auf Ihrem Gerät installierten MQTT-Clientbibliothek angemeldet sind. 1. Befehl **erstellen — Definieren Sie einen Befehl** mit einer statischen Payload oder einer Payload-Vorlage, die Geräteaktionen spezifiziert. Siehe [Erstellen Sie eine Befehlsressource](iot-remote-command-create-manage.md#iot-remote-command-create). 1. **Identifizieren Sie Ihr Gerät** — Registrieren Sie Ihr Gerät als IoT-Ding oder notieren Sie sich seine MQTT-Client-ID. Siehe [Überlegungen zum Zielgerät](iot-remote-command-execution-start-monitor.md#iot-command-execution-target). 1. **Berechtigungen konfigurieren** — Richten Sie IAM-Richtlinien ein, die es Ihrem Gerät ermöglichen, Befehle zu empfangen und Antworten zu veröffentlichen. 1. **Themen abonnieren** — Konfigurieren Sie Ihr Gerät so, dass es Themen zur Anforderung und Beantwortung von Befehlen abonniert. Siehe [Wählen Sie das Zielgerät für Ihre Befehle und abonnieren Sie MQTT-Themen](iot-remote-command-workflow.md#command-choose-target). 1. **Befehl ausführen** — Startet die Befehlsausführung auf Ihrem Zielgerät. Siehe [Starten Sie die Ausführung eines BefehlsStarten Sie die Ausführung eines Befehls (Konsole)Starten Sie die Ausführung eines Befehls ()AWS CLI](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-start). **Häufige Anwendungsfälle:** + *Ferndiagnose* — Rufen Sie Protokolle ab, führen Sie Diagnosen durch, überprüfen Sie den Gerätezustand + *Konfigurationsupdates* — Einstellungen ändern, Parameter aktualisieren, Funktionen umschalten + *Gerätesteuerung* -Lock/unlock, power on/off, Modusänderungen # Befehle, Konzepte und Status Verwenden Sie AWS IoT Befehle, um Anweisungen aus der Cloud an verbundene Geräte zu senden. Um dieses Feature zu verwenden: 1. Erstellen Sie einen Befehl mit einer Nutzlast, die die für die Ausführung auf dem Gerät erforderlichen Konfigurationen enthält. 1. Geben Sie das Zielgerät an, das die Payload empfängt und die Aktionen ausführt. 1. Führen Sie den Befehl auf dem Zielgerät aus und rufen Sie Statusinformationen ab. Informationen zur Behebung von Problemen finden Sie in den CloudWatch Protokollen. Weitere Informationen zu diesem Workflow finden Sie unter [Arbeitsablauf für Befehle auf hoher Ebene](iot-remote-command-workflow.md). **Topics** + [Befehle und wichtige Konzepte](#iot-command-concepts) + [Befehlsstatus](#iot-command-states) + [Status der Befehlsausführung](#iot-command-execution-status) ## Befehle und wichtige Konzepte Die folgenden Schlüsselkonzepte helfen Ihnen, die Befehlsfunktion zu verstehen. Begriffe werden in dieser Dokumentation einheitlich verwendet: + *Befehl* — Eine wiederverwendbare Vorlage, die Geräteanweisungen definiert + *Ausführung* — Eine Instanz eines Befehls, der auf einem Gerät ausgeführt wird + *Name der Sache* — Kennung für Geräte, die in der IoT-Registrierung registriert sind + *Client-ID* — MQTT-Kennung für nicht registrierte Geräte + *Payload* — Die an Geräte gesendeten Befehlsdaten + *Thema* — MQTT-Kanal für die Befehlskommunikation **Befehle** Befehle sind Anweisungen, die von der Cloud als MQTT-Nachrichten an Ihre IoT-Geräte gesendet werden. Nach dem Empfang der Nutzdaten verarbeiten die Geräte die Anweisungen und ergreifen entsprechende Aktionen, z. B. das Ändern der Konfigurationseinstellungen, das Übertragen von Sensormesswerten oder das Hochladen von Protokollen. Die Geräte senden dann die Ergebnisse an die Cloud zurück und ermöglichen so die Fernüberwachung und -steuerung. **Namespace** Wenn Sie einen Befehl erstellen, geben Sie seinen Namespace an. Verwenden Sie für AWS IoT Device Management Befehle den `AWS-IoT` Standard-Namespace und geben Sie entweder eine Payload oder PayloadTemplate an. Verwenden Sie für AWS IoT FleetWise Befehle den Namespace. `AWS-IoT-FleetWise` Weitere Informationen finden Sie unter [Remote-Befehle](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) im *AWS IoT FleetWise Entwicklerhandbuch*. **Nutzlast** Geben Sie bei der Erstellung eines Befehls eine statische Nutzlast an, die die Aktionen definiert, die das Gerät ausführen muss. Die Payload kann jedes unterstützte Format verwenden. Um sicherzustellen, dass Geräte die Payload korrekt interpretieren, empfehlen wir, den Payload-Formattyp anzugeben. Geräte, die das MQTT5 Protokoll verwenden, können zur Identifizierung des Formats dem MQTT-Standard folgen. Formatindikatoren für JSON oder CBOR sind im Thema Befehlsanfrage verfügbar. **Payload-Vorlage** Eine Payload-Vorlage definiert eine Befehls-Payload mit Platzhaltern, die zur Laufzeit auf der Grundlage der von Ihnen angegebenen Parameterwerte unterschiedliche Payloads generieren. Anstatt beispielsweise separate Payloads für verschiedene Temperaturwerte zu erstellen, erstellen Sie eine Vorlage mit einem Temperatur-Platzhalter und geben Sie den Wert während der Ausführung an. Dadurch entfällt die Verwaltung mehrerer ähnlicher Payloads. **Zielgerät** Um einen Befehl auszuführen, geben Sie ein Zielgerät entweder mit seinem Ding-Namen (für registrierte Geräte AWS IoT) oder seiner MQTT-Client-ID (für nicht registrierte Geräte) an. Die Client-ID ist eine eindeutige Kennung, die in dem [MQTT](mqtt.md) Protokoll definiert ist, mit dem Geräte verbunden werden. AWS IoT Details hierzu finden Sie unter [Überlegungen zum Zielgerät](iot-remote-command-execution-start-monitor.md#iot-command-execution-target). **Themen zu Befehlen** Vor der Ausführung eines Befehls müssen Geräte das Thema zur Befehlsanforderung abonnieren. Wenn Sie einen Befehl ausführen, wird die Payload zu diesem Thema an das Gerät gesendet. Nach der Ausführung veröffentlichen die Geräte die Ergebnisse und den Status im Antwortthema des Befehls. Weitere Informationen finden Sie unter [Themen zu Befehlen](reserved-topics.md#reserved-topics-commands). **Ausführung von Befehlen** Eine Ausführung ist eine Instanz eines Befehls, der auf einem Zielgerät ausgeführt wird. Wenn Sie eine Ausführung starten, wird die Nutzlast an das Gerät übermittelt und eine eindeutige Ausführungs-ID wird generiert. Das Gerät führt den Befehl aus und meldet den Fortschritt an. AWS IoT Die geräteseitige Logik bestimmt das Ausführungsverhalten und die Statusberichterstattung für reservierte Themen. ### Bedingungen für Parameterwerte Definieren Sie beim Erstellen von Befehlen mit Payload-Vorlagen Wertbedingungen, um Parameterwerte vor der Ausführung zu validieren. Wertbedingungen stellen sicher, dass die Parameter die Anforderungen erfüllen, und verhindern so ungültige Ausführungen. **Unterstützte Operatoren nach Typ [CommandParameterValue](https://docs.aws.amazon.com//iot/latest/apireference/API_CommandParameterValue.html)** **Numerische Typen (INTEGER, LONG, DOUBLE, UNSIGNEDLONG)** + `EQUALS`- Der Wert muss der angegebenen Zahl entsprechen + `NOT_EQUALS`- Der Wert darf nicht der angegebenen Zahl entsprechen + `GREATER_THAN`- Der Wert muss größer als die angegebene Zahl sein + `GREATER_THAN_EQUALS`- Der Wert muss größer oder gleich der angegebenen Zahl sein + `LESS_THAN`- Der Wert muss kleiner als die angegebene Zahl sein + `LESS_THAN_EQUALS`- Der Wert muss kleiner oder gleich der angegebenen Zahl sein + `IN_RANGE`- Der Wert muss innerhalb des angegebenen Bereichs (einschließlich) liegen + `NOT_IN_RANGE`- Der Wert muss außerhalb des angegebenen Bereichs (einschließlich) liegen + `IN_SET`- Der Wert muss mit einer der angegebenen Zahlen übereinstimmen + `NOT_IN_SET`- Der Wert darf mit keiner der angegebenen Zahlen übereinstimmen **Zeichenfolgentyp (STRING)** + `EQUALS`- Der Wert muss der angegebenen Zeichenfolge entsprechen + `NOT_EQUALS`- Der Wert darf nicht der angegebenen Zeichenfolge entsprechen + `IN_SET`- Der Wert muss mit einer der angegebenen Zeichenketten übereinstimmen + `NOT_IN_SET`- Der Wert darf mit keiner der angegebenen Zeichenketten übereinstimmen **Boolescher Typ** + Wertbedingungen werden nicht unterstützt **Binärer Typ** + Wertbedingungen werden nicht unterstützt **Beispiel: Befehl zur Temperatursteuerung** ``` { "commandId": "SetTemperature", "namespace": "AWS-IoT", "payloadTemplate": "{\"temperature\": \"${aws:iot:commandexecution::parameter:temperature}\"}", "parameters": [ { "name": "temperature", "type": "INTEGER", "valueConditions": [ { "comparisonOperator": "IN_RANGE", "operand": { "numberRange": { "min": "60", "max": "80" } } } ] } ] } ``` In diesem Beispiel muss der `temperature` Parameter zwischen 60 und 80 (einschließlich) liegen. Ausführungsanforderungen mit Werten außerhalb dieses Bereichs schlagen bei der Überprüfung fehl. **Anmerkung** Wertbedingungen werden beim Aufruf der [StartCommandExecution API](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartCommandExecution.html) ausgewertet. Fehlgeschlagene Validierungen geben einen Fehler zurück und verhindern die Erstellung der Ausführung. ### Priorität und Bewertung des Parameterwerts Beim Starten von Befehlsausführungen mit Payload-Vorlagen werden Parameterwerte mit der folgenden Priorität aufgelöst: 1. **Parameter für die Ausführungsanforderung** — Die in der `StartCommandExecution` Anforderung angegebenen Werte haben höchste Priorität 1. **Standardwerte für Befehle** — Wenn ein Parameter in der Ausführungsanforderung nicht angegeben wird, `defaultValue` wird der des Parameters verwendet 1. **Kein Wert** — Wenn keiner von beiden angegeben wird, schlägt die Ausführung fehl, da der Parameter für die Generierung der Ausführungsanforderung erforderlich ist Die Wertbedingungen werden anhand des endgültigen Parameterwerts bewertet, der oben anhand der Priorität abgeleitet wurde, und zwar vor der Erstellung der Ausführung. Schlägt die Überprüfung fehl, gibt die Ausführungsanforderung einen Fehler zurück. **Beispiel: SetTemperature Befehl mit `defaultValue`** ``` { "parameters": [ { "name": "temperature", "type": "INTEGER", "defaultValue": {"I": 72}, "valueConditions": [ { "comparisonOperator": "IN_RANGE", "operand": {"numberRange": {"min": "60", "max": "80"}} } ] } ] } ``` Beim Starten der Ausführung: + Wenn Sie `"temperature": {"I": 75}` in der Anfrage angeben, wird 75 verwendet + Wenn Sie den Temperaturparameter weglassen, wird der Standardwert 72 verwendet + Beide Werte werden anhand der Bereichsbedingung [60,80] validiert ## Befehlsstatus *Befehle in Ihrem AWS-Konto können sich in einem von drei Status befinden: *Verfügbar*, *Veraltet oder Ausstehende Löschung*.* **Verfügbar** Nach erfolgreicher Erstellung befindet sich ein Befehl im Status Verfügbar und kann auf Geräten ausgeführt werden. **Als veraltet gekennzeichnet** Kennzeichnet Befehle als veraltet, wenn sie nicht mehr benötigt werden. Veraltete Befehle können keine neuen Ausführungen starten, aber ausstehende Ausführungen werden bis zum Abschluss fortgesetzt. Um neue Ausführungen zu ermöglichen, setzen Sie den Befehl auf den Status Verfügbar zurück. **Löschen ausstehend** Wenn Sie einen Befehl zum Löschen markieren, wird er automatisch gelöscht, wenn er länger als das maximale Timeout (Standard: 12 Stunden) veraltet ist. Diese Aktion ist permanent. Wenn der Befehl nicht oder für weniger als das Timeout veraltet ist, wechselt er in den Status Ausstehende Löschung und wird nach Ablauf des Timeouts entfernt. ## Status der Befehlsausführung Wenn Sie eine Ausführung auf einem Zielgerät starten, geht es in den `CREATED` Status über und kann auf der Grundlage von Geräteberichten in einen anderen Status übergehen. Sie können Statusinformationen abrufen und Ausführungen nachverfolgen. **Anmerkung** Sie können mehrere Befehle gleichzeitig auf einem Gerät ausführen. Verwenden Sie die Parallelitätssteuerung, um die Ausführungen pro Gerät zu begrenzen und eine Überlastung zu verhindern. [Informationen zur maximalen Anzahl gleichzeitiger Ausführungen pro Gerät finden Sie unter Befehlsquoten.AWS IoT Device Management](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits) Die folgende Tabelle zeigt den Ausführungsstatus und die zugehörigen Übergänge auf der Grundlage des Ausführungsfortschritts. **Status und Quelle der Befehlsausführung** | Status der Befehlsausführung | Vom Gerät/der Cloud initiiert? | Ausführung im Terminal? | Zulässige Statusübergänge | | --- | --- | --- | --- | | CREATED | Cloud | Nein | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/iot-remote-command-concepts.html) | | IN\$1PROGRESS | Gerät | Nein | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/iot-remote-command-concepts.html) | | TIMED\$1OUT | Gerät und Cloud | Nein | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/iot-remote-command-concepts.html) | | SUCCEEDED | Gerät | Ja | Nicht zutreffend | | FAILED | Gerät | Ja | Nicht zutreffend | | REJECTED | Gerät | Ja | Nicht zutreffend | Geräte können Status- und Ergebnisaktualisierungen jederzeit mithilfe von Befehlen veröffentlichen, die MQTT-Themen vorbehalten sind. Um zusätzlichen Kontext bereitzustellen, können Geräte `reasonDescription` Felder im `statusReason` Objekt verwenden`reasonCode`. Das folgende Diagramm zeigt die Übergänge beim Ausführungsstatus. ![\[Das Bild zeigt, wie der Ausführungsstatus eines Befehls zwischen verschiedenen Status wechselt.\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/images/command-execution-status-transitions.png) **Anmerkung** Wenn AWS IoT festgestellt wird, dass das Gerät innerhalb des Timeout-Zeitraums nicht reagiert, wird es `TIMED_OUT` als temporärer Status festgelegt, sodass Wiederholungsversuche und Statusänderungen möglich sind. Wenn Ihr Gerät dies explizit meldet`TIMED_OUT`, wird dies zu einem Terminalstatus ohne weitere Übergänge. Weitere Informationen finden Sie unter [Befehlsausführungen außerhalb des Terminals](#iot-command-execution-status-nonterminal). In den folgenden Abschnitten werden Ausführungen am Terminal und an anderen Endgeräten sowie deren Status beschrieben. **Topics** + [Befehlsausführungen außerhalb des Terminals](#iot-command-execution-status-nonterminal) + [Ausführung von Terminal-Befehlen](#iot-command-execution-status-terminal) ### Befehlsausführungen außerhalb des Terminals Eine Ausführung ist kein Terminal, wenn sie Updates von Geräten annehmen kann. *Ausführungen, die kein Terminal sind, werden als aktiv betrachtet.* Die folgenden Status sind nicht terminal: + **CREATED** Wenn Sie eine Ausführung von der AWS IoT Konsole aus starten oder die `StartCommandExecution` API verwenden, ändert sich der Status erfolgreicher Anfragen in. `CREATED` Von diesem Status aus können Ausführungen in jeden anderen Status übergehen, der kein Terminal oder ein Terminal ist. + **IN\$1PROGRESS** Nach Erhalt der Nutzdaten können die Geräte mit der Ausführung von Anweisungen und der Ausführung bestimmter Aktionen beginnen. Während der Ausführung können Geräte Antworten auf das Antwortthema der Befehle veröffentlichen und den `IN_PROGRESS` Status aktualisieren. Von aus `IN_PROGRESS` können Ausführungen in einen beliebigen Terminal- oder Nicht-Terminal-Status übergehen, außer. `CREATED` **Anmerkung** Die `UpdateCommandExecution` API kann mehrfach mit Status aufgerufen werden. `IN_PROGRESS` Geben Sie mithilfe des `statusReason` Objekts zusätzliche Ausführungsdetails an. + **TIMED\$1OUT** Sowohl die Cloud als auch das Gerät können diesen Status auslösen. Ausführungen in unserem `CREATED` `IN_PROGRESS` Status können aus den folgenden `TIMED_OUT` Gründen auf geändert werden: + Nach dem Senden des Befehls wird ein Timer gestartet. Wenn das Gerät nicht innerhalb der angegebenen Dauer reagiert, ändert sich der Status der Cloud in`TIMED_OUT`. In diesem Fall erfolgt die Ausführung nicht terminalgebunden. + Das Gerät kann den Status eines beliebigen Terminalstatus außer Kraft setzen oder einen Timeout melden und den Status auf setzen. `TIMED_OUT` In diesem Fall bleibt der Status bestehen`TIMED_OUT`, aber die `StatusReason` Objektfelder ändern sich je nach Geräteinformation. Die Ausführung wird zum Terminal. Weitere Informationen finden Sie unter [Timeout-Wert und `TIMED_OUT` Ausführungsstatus](iot-remote-command-execution-start-monitor.md#iot-command-execution-timeout-status). ### Ausführung von Terminal-Befehlen Eine Ausführung wird zum Terminal, wenn sie keine Updates von Geräten mehr akzeptiert. Bei den folgenden Status handelt es sich um einen Terminalstatus. Ausführungen können von jedem Status, der kein Terminal ist, in einen Terminalstatus übergehen:`CREATED`, oder. `IN_PROGRESS` `TIMED_OUT` + **SUCCEEDED** Wenn das Gerät die Ausführung erfolgreich abgeschlossen hat, kann es eine Antwort auf das Antwortthema des Befehls veröffentlichen und den Status für aktualisieren. `SUCCEEDED` + **FEHLGESCHLAGEN** Wenn ein Gerät die Ausführung nicht abschließen kann, kann es eine Antwort auf die Befehle Response Topic und Update Status to veröffentlichen`FAILED`. Verwenden Sie die `reasonDescription` Felder `reasonCode` und im `statusReason` Objekt oder in den CloudWatch Protokollen, um Fehler zu beheben. + **ABGELEHNT** Wenn ein Gerät eine ungültige oder inkompatible Anfrage erhält, kann es die `UpdateCommandExecution` API mit Status `REJECTED` aufrufen. Verwenden Sie die `reasonDescription` Felder `reasonCode` und im `statusReason` Objekt oder in den CloudWatch Protokollen, um Probleme zu beheben. # Arbeitsablauf für Befehle auf hoher Ebene Dieser Workflow zeigt, wie Geräte mit AWS IoT Device Management Befehlen interagieren. Alle HTTP-API-Anfragen verwenden [Sigv4-Anmeldeinformationen](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) zum Signieren. ![\[Überblick über den High-Level-Workflow für AWS IoT Device Management Gerätebefehle.\]](http://docs.aws.amazon.com/de_de/iot/latest/developerguide/images/device-command-workflow.png) **Topics** + [Erstellen und Verwalten von Befehlen](#command-create-command) + [Wählen Sie das Zielgerät für Ihre Befehle und abonnieren Sie MQTT-Themen](#command-choose-target) + [Starten und überwachen Sie die Befehlsausführungen für Ihr Zielgerät](#command-command-executions) + [(Optional) Aktivieren Sie Benachrichtigungen für Befehlsereignisse](#iot-remote-command-commands-notifications) ## Erstellen und Verwalten von Befehlen Gehen Sie wie folgt vor, um Befehle für Ihre Geräte zu erstellen und zu verwalten. 1. **Erstellen Sie eine Befehlsressource** Erstellen Sie einen Befehl über den [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) oder mithilfe der [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html)API. 1. **Geben Sie die Nutzlast an** Stellen Sie eine Nutzlast in einem beliebigen Format bereit. Geben Sie den Inhaltstyp an, um eine korrekte Interpretation durch das Gerät sicherzustellen. Bei dynamischen Befehlen mit Payload-Vorlagen wird die endgültige Payload zur Laufzeit anhand der von Ihnen angegebenen Parameter generiert. Vorlagen unterstützen nur das JSON-Format, aber die generierte Nutzlast kann als JSON oder CBOR gesendet werden. 1. **(Optional) Verwalte die erstellten Befehle** Aktualisieren Sie den Anzeigenamen und die Beschreibung nach der Erstellung. Markieren Sie Befehle als veraltet, wenn sie nicht mehr benötigt werden, oder löschen Sie sie dauerhaft. Um die Payload-Informationen zu ändern, erstellen Sie einen neuen Befehl. ## Wählen Sie das Zielgerät für Ihre Befehle und abonnieren Sie MQTT-Themen Wählen Sie Ihr Zielgerät und konfigurieren Sie MQTT-Themen für den Empfang von Befehlen und das Veröffentlichen von Antworten. 1. **Wählen Sie das Zielgerät für Ihren Befehl** Wählen Sie ein Zielgerät aus, um den Befehl zu empfangen und auszuführen. Verwenden Sie einen Ding-Namen für registrierte Geräte oder eine Client-ID für nicht registrierte Geräte. Weitere Informationen finden Sie unter [Überlegungen zum Zielgerät](iot-remote-command-execution-start-monitor.md#iot-command-execution-target). 1. **Konfigurieren Sie die AWS IoT Geräterichtlinie** Konfigurieren Sie eine IAM-Richtlinie, die Berechtigungen zum Empfangen von Ausführungen und zum Veröffentlichen von Updates gewährt. Beispiele [Beispiel einer IAM-Richtlinie](iot-remote-command-execution-start-monitor.md#iot-remote-command-execution-update-policy) für Richtlinien finden Sie unter. 1. **Stellen Sie eine MQTT-Verbindung her** Verbinden Sie Geräte mit dem Message Broker und abonnieren Sie Request and Response Topics. Geräte benötigen eine `iot:Connect` Genehmigung. Finden Sie Ihren Datenebenen-Endpunkt mit dem `DescribeEndpoint` API- oder `describe-endpoint` CLI-Befehl: ``` aws iot describe-endpoint --endpoint-type iot:Data-ATS ``` Wenn Sie diesen Befehl ausführen, wird der kontospezifische Endpunkt der Datenebene zurückgegeben, wie unten gezeigt. ``` account-specific-prefix.iot.region.amazonaws.com ``` 1. **Abonnieren Sie die Themen zu Befehlen** Abonnieren Sie das Thema „Befehlsanfrage“. Wenn Sie eine Ausführung starten, veröffentlicht der Message Broker die Payload zu diesem Thema. Ihr Gerät empfängt und verarbeitet den Befehl. (Optional) Abonnieren Sie die Antwortthemen (`accepted`oder`rejected`), um eine Bestätigung zu erhalten, ob der Cloud-Dienst die Geräteantwort akzeptiert oder abgelehnt hat. Ersetzen Sie in diesem Beispiel: + *``*mit `thing` oder `client` abhängig davon, ob das Gerät, auf das Sie abzielen, als IoT-Ding registriert oder als MQTT-Client spezifiziert wurde. + *``*mit der eindeutigen Kennung Ihres Zielgeräts. Diese ID kann die eindeutige MQTT-Client-ID oder ein Ding-Name sein. **Anmerkung** Wenn der Payload-Typ nicht JSON oder CBOR ist, ist das ** Feld möglicherweise nicht im Thema der Befehlsanfrage vorhanden. Um das Payload-Format abzurufen, empfehlen wir, die Formatinformationen aus den MQTT-Nachrichtenkopfzeilen abzurufen. MQTT5 Weitere Informationen finden Sie unter [Themen zu Befehlen](reserved-topics.md#reserved-topics-commands). ``` $aws/commands///executions/+/request/ $aws/commands///executions/+/response/accepted/ $aws/commands///executions/+/response/rejected/ ``` ## Starten und überwachen Sie die Befehlsausführungen für Ihr Zielgerät Nachdem Sie die Befehle erstellt und die Ziele für den Befehl angegeben haben, können Sie die Ausführung auf dem Zielgerät starten, indem Sie die folgenden Schritte ausführen. 1. **Starten Sie die Befehlsausführung auf dem Zielgerät** Starten Sie die Ausführung vom [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) aus oder verwenden Sie die `StartCommandExecution` API mit Ihrem kontospezifischen Endpunkt. Verwenden Sie es `iot:Data-ATS` für Dual-Stack (IPv4/IPv6) oder `iot:Jobs` nur für. IPv4 Die API veröffentlicht den Payload im Thema Commands Request. **Anmerkung** Wenn das Gerät offline ist und persistente MQTT-Sitzungen verwendet, wartet der Befehl beim Message Broker. Wenn das Gerät vor dem Timeout wieder eine Verbindung herstellt, kann es den Befehl verarbeiten und Ergebnisse veröffentlichen. Wenn das Timeout abläuft, wird das Timeout bei der Ausführung überschritten und die Nutzdaten werden verworfen. 1. **Aktualisieren Sie das Ergebnis der Befehlsausführung** Das Gerät empfängt die Payload, verarbeitet den Befehl, führt die angegebenen Aktionen aus und veröffentlicht die Ergebnisse mithilfe einer `UpdateCommandExecution` MQTT-basierten API im Antwortthema „Befehle“. Wenn das Gerät akzeptierte und abgelehnte Themen abonniert hat, erhält es eine Bestätigung, ob der Cloud-Dienst die Antwort akzeptiert oder abgelehnt hat. Je nachdem, was Sie im Thema der Anfrage angegeben haben, ** kann es sich entweder um Dinge oder Clients handeln, und es ** kann sich AWS IoT dabei um Ihren Dingnamen oder die MQTT-Client-ID handeln. **Anmerkung** Das ** kann im Antwortthema der Befehle nur JSON oder CBOR sein. ``` $aws/commands///executions//response/ ``` 1. **(Optional) Rufen Sie das Ergebnis der Befehlsausführung ab** Rufen Sie die Ausführungsergebnisse von der AWS IoT Konsole ab oder verwenden Sie`GetCommandExecution`. Das Gerät muss die Ergebnisse unter dem Thema Commands Response veröffentlichen, um aktuelle Informationen zu erhalten. Sehen Sie sich zusätzliche Details an, einschließlich Uhrzeit der letzten Aktualisierung, Ergebnis und Abschlusszeit. ## (Optional) Aktivieren Sie Benachrichtigungen für Befehlsereignisse Abonnieren Sie Befehlsereignisse, um Benachrichtigungen zu erhalten, wenn sich der Ausführungsstatus ändert. Ausführliche Informationen zu Ereignissen bei der Befehlsausführung, einschließlich des Formats der Ereignismeldungen und der Nutzdatenattribute, finden Sie unter[Ereignisse bei der Ausführung von Befehlen](command-events.md). 1. **Erstellen einer Themenregel** Abonnieren Sie das Thema Befehlsereignisse für Benachrichtigungen über Statusänderungen. Erstellen Sie eine Themenregel, um Gerätedaten mithilfe der AWS IoT Konsole oder [Eine AWS IoT Regel erstellen](iot-create-rule.md) an andere AWS IoT Dienste wie AWS Lambda Amazon SQS und AWS Step Functions weiterzuleiten. Ersetzen Sie in diesem Beispiel `` durch die ID des Befehls, für den Sie Benachrichtigungen erhalten möchten, und `` durch den Status der Befehlsausführung. ``` $aws/events/commandExecution// ``` **Anmerkung** Um Benachrichtigungen für alle Befehle und den Status der Befehlsausführung zu erhalten, können Sie Platzhalterzeichen verwenden und das folgende Thema abonnieren. ``` $aws/events/commandExecution/+/# ``` 1. **Befehlsereignisse empfangen und verarbeiten** Verwalten Sie Push-Benachrichtigungen für Befehle und erstellen Sie Anwendungen mithilfe der abonnierten Ereignisse. Der folgende Code zeigt eine Beispiel-Payload für die Benachrichtigungen über Befehlsereignisse, die Sie erhalten werden. ``` { "executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554", "status":"FAILED", "statusReason": { "reasonCode": "DEVICE_TOO_BUSY", "reasonDescription": "" }, "eventType": "COMMAND_EXECUTION", "commandArn":"arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086", "targetArn":"arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd", "timestamp":1717708862107 } ``` # Erstellen und Verwalten von Befehlen Verwenden Sie AWS IoT Device Management Befehle, um wiederverwendbare Fernaktionen zu konfigurieren oder sofortige Anweisungen an Geräte zu senden. Erstellen und verwalten Sie Befehle von der AWS IoT Konsole aus oder verwenden Sie die AWS CLI. **Topics** + [Erstellen Sie eine Befehlsressource](#iot-remote-command-create) + [Ruft Informationen zu einem Befehl ab](#iot-remote-command-get) + [Listen Sie Befehle in Ihrem auf AWS-Konto](#iot-remote-command-list) + [Aktualisieren Sie eine Befehlsressource](#iot-remote-command-update) + [Eine Befehlsressource verwerfen oder wiederherstellen](#iot-remote-command-deprecatecmd) + [Löschen Sie eine Befehlsressource](#iot-remote-command-delete) ## Erstellen Sie eine Befehlsressource Geben Sie beim Erstellen eines Befehls die folgenden Informationen an: + **Allgemeine Informationen** Geben Sie eine eindeutige Befehls-ID an, um den Befehl zu identifizieren, wenn er auf Zielgeräten ausgeführt wird. Geben Sie optional einen Anzeigenamen, eine Beschreibung und Tags für die Verwaltung an. + **Nutzlast** Geben Sie für statische Befehle eine Payload an, die Geräteaktionen definiert. Geben Sie den Payload-Formattyp für eine korrekte Geräteinterpretation an. Dynamische Befehle finden Sie im Payload-Vorlagenattribut. + **Payload-Vorlage** Stellen Sie für dynamische Befehle ein PayloadTemplate mit Platzhaltern und Parametern bereit. Geben Sie optional Bedingungen an`defaultValue`. AWS IoT Device Management Befehle ersetzen Platzhalter zur Laufzeit. Fehlende Parameter verwenden ihren defaultValue. Alle Werte müssen definierte Bedingungen erfüllen. Die folgenden Platzhaltertypen, bei denen Groß- und Kleinschreibung beachtet wird, werden unterstützt: + `${aws:iot:commandexecution::parameter:parameter1}`— Ein Platzhalter für den Wert eines Parameters mit dem Namen. `parameter1` + `${aws:iot:commandexecution::executionTimeoutSec}`— Ein Platzhalter für den zur Laufzeit bereitgestellten Timeout-Parameter für die Befehlsausführung. ### Themen zu Payload und Befehlen Vorbehaltene Befehle Themen verwenden ein Format, das auf dem Payload-Formattyp basiert. + Verwenden Sie für `application/json` `application/cbor` unsere Inhaltstypen dieses Anforderungsthema: ``` $aws/commands///executions/+/request/ ``` + Verwenden Sie für andere Inhaltstypen oder ein nicht spezifiziertes Format dieses Anforderungsthema. Das Payload-Format erscheint im MQTT-Nachrichtenkopf. ``` $aws/commands///executions/+/request ``` Das Antwortthema „Befehle“ verwendet `json` unser `cbor` Format unabhängig vom Payload-Typ. **muss sein `json` oder`cbor`: ``` $aws/commands///executions//response/ ``` ### Erstellen Sie eine Befehlsressource (Konsole) In den folgenden Abschnitten werden Überlegungen zum Payload-Format und die Befehlserstellung über die Konsole beschrieben. **Topics** + [Format der statischen Befehls-Payload](#iot-commands-payload-format) + [Payload-Format für dynamische Befehle](#iot-commands-dynamic-payload-format) + [Wie erstelle ich einen Befehl (Konsole)](#iot-commands-console-how) #### Format der statischen Befehls-Payload Die Payload unterstützt jedes Format bis zu 32 KB. Geben Sie den Payload-Formattyp für eine sichere und korrekte Geräteinterpretation an. Geben Sie den Payload-Formattyp mithilfe des `type/subtype` Formats an (z. B. `application/json` oder`application/cbor`). Standard: `application/octet-stream`. Informationen zu den unterstützten Formaten finden Sie unter [Allgemeine MIME-Typen](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types). #### Payload-Format für dynamische Befehle Das PayloadTemplate muss ein gültiges JSON-Format mit mindestens einem Platzhalter (bis zu 32 KB) sein. Für `AwsJsonSubstitution` Präprozessoren sendet AWS IoT Device Management Commands Benachrichtigungen im JSON- oder CBOR-Format, basierend auf der Präprozessorkonfiguration. #### Wie erstelle ich einen Befehl (Konsole) Um einen Befehl von der Konsole aus zu erstellen, gehen Sie zu [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) und gehen Sie wie folgt vor: 1. Wählen Sie **Befehl erstellen**. 1. Geben Sie eine eindeutige Befehls-ID an. 1. (Optional) Geben Sie den Anzeigenamen, die Beschreibung und die Tags an. 1. Laden Sie die Payload-Datei mit den Geräteaktionen hoch. Geben Sie den Payload-Formattyp für eine korrekte Geräteinterpretation an. 1. (Optional) Bei JSON-Payload-Vorlagen mit Platzhaltern werden die Parameter zur Bearbeitung vorab in die Inline-Tabelle eingetragen. 1. (Optional) Konfigurieren Sie den Parameterwerttyp (erforderlich), den Standardwert und die Bedingungen. 1. Wählen Sie den **Befehl Create**. ### Erstellen Sie eine Befehlsressource (CLI) Verwenden Sie den [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html)API- oder [https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html)CLI-Befehl, um einen Befehl zu erstellen. **Topics** + [Payload des Befehls](#iot-commands-payload) + [Beispiel einer IAM-Richtlinie](#iot-remote-command-create-iam) + [Beispiel für die Erstellung eines statischen Befehls](#iot-remote-command-create-example) + [Beispiel für die dynamische Befehlserstellung](#iot-remote-dynamic-command-create-example) #### Payload des Befehls Stellen Sie eine statische Payload- oder Payload-Vorlage bereit. Statische Payloads sind Base64-codiert. Bei Payload-Vorlagen wird die endgültige Payload zur Laufzeit mithilfe von Parameterwerten generiert. Geräte verarbeiten die Payload und führen bestimmte Aktionen aus. Geben Sie den Payload-Inhaltstyp für den korrekten Geräteempfang an. **Anmerkung** Payloads können nach der Befehlserstellung nicht geändert werden. Erstellen Sie einen neuen Befehl, um die Payload zu ändern. #### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Sie autorisiert, diese Aktion auf dem Gerät auszuführen. Das folgende Beispiel zeigt eine IAM-Richtlinie, die dem Benutzer die Erlaubnis erteilt, die Aktion auszuführen. `CreateCommand` Ersetzen Sie in diesem Beispiel: + `region`mit Ihrem AWS-Region, wie `us-east-1` zum Beispiel. + `account-id`mit deiner AWS-Konto Nummer, wie`123456789012`. + `command-id`mit einer eindeutigen Kennung für Ihre AWS IoT Befehls-ID, z. `LockDoor` B. Wenn Sie mehr als einen Befehl senden möchten, können Sie diese Befehle in der IAM-Richtlinie im Abschnitt *Ressource* angeben. **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:CreateCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### Beispiel für die Erstellung eines statischen Befehls Das folgende Beispiel zeigt, wie Sie einen statischen Befehl erstellen können. Ersetzen Sie je nach Anwendung: + *``*mit einer eindeutigen Kennung für den Befehl. Um beispielsweise die Tür Ihres Hauses zu verriegeln, können Sie Folgendes angeben*`LockDoor`*. Wir empfehlen die Verwendung von UUID. Sie können auch alphanumerische Zeichen, „-“ und „\$1“ verwenden. + (Optional) *``* und. *``* Dabei handelt es sich um optionale Felder, die Sie verwenden können, um einen benutzerfreundlichen Namen und eine aussagekräftige Beschreibung für den Befehl anzugeben, z. B. *`Lock the doors of my home`* + `namespace`, mit denen Sie den Namespace des Befehls angeben können. Das muss es sein. `AWS-IoT` Informationen zur Verwendung dieser Funktion finden Sie AWS IoT FleetWise unter [Fernbefehle](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) + `payload`enthält Informationen über die Payload, die Sie bei der Ausführung des Befehls verwenden möchten, und deren Inhaltstyp. ``` aws iot create-command \ --command-id \ --display-name \ --description \ --namespace AWS-IoT \ --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}' ``` Die Ausführung dieses Befehls generiert eine Antwort, die die ID und den ARN (Amazon-Ressourcenname) des Befehls enthält. Wenn Sie den `LockDoor` Befehl beispielsweise bei der Erstellung angegeben haben, zeigt das Folgende ein Beispiel für die Ausgabe der Ausführung des Befehls. ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor" } ``` #### Beispiel für die dynamische Befehlserstellung Das folgende Beispiel zeigt, wie Sie einen dynamischen Befehl erstellen können. Ersetzen Sie je nach Anwendung: + *``*mit einer eindeutigen Kennung für den Befehl. Um beispielsweise den Energiestatus der Leuchte festzulegen, können Sie Folgendes *`Light_Power_Status`* angeben: Wir empfehlen die Verwendung von UUID. Sie können auch alphanumerische Zeichen, „-“ und „\$1“ verwenden. + (Optional) *``* und. *``* Dabei handelt es sich um optionale Felder, die Sie verwenden können, um einen benutzerfreundlichen Namen und eine aussagekräftige Beschreibung für den Befehl anzugeben, z. B. *`Turn a light ON or OFF`* + `namespace`, mit denen Sie den Namespace des Befehls angeben können. Das muss es sein. `AWS-IoT` Informationen zur Verwendung dieser Funktion finden Sie AWS IoT FleetWise unter [Fernbefehle](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) + `payloadTemplate`enthält die JSON-formatierte Playoad-Vorlage mit Platzhaltern. + `preprocessor`enthält die Konfiguration für den Präprozessor, die bestimmt, wie das PayloadTemplate verarbeitet werden muss. + `mandatoryParameter`enthält die Parameter, die den Platzhaltern im PayloadTemplate entsprechen, deren Typ, Standardwerte und Bedingungen. ``` aws iot create-command \ --command-id Light_Power_Status \ --description "Turn a light ON or OFF" \ --namespace AWS-IoT \ --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \ --preprocessor awsJsonSubstitution={outputFormat=JSON} \ --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]" ``` Die Ausführung dieses Befehls generiert eine Antwort, die die ID und den ARN (Amazon-Ressourcenname) des Befehls enthält. Wenn Sie den `Light_Power_Status` Befehl beispielsweise bei der Erstellung angegeben haben, zeigt das Folgende ein Beispiel für die Ausgabe der Ausführung des Befehls. ``` { "commandId": "Light_Power_Status", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status" } ``` ## Ruft Informationen zu einem Befehl ab Nachdem Sie einen Befehl erstellt haben, können Sie Informationen dazu von der AWS IoT Konsole abrufen und den verwenden AWS CLI. Sie können die folgenden Informationen abrufen. + Die Befehls-ID, der Amazon-Ressourcenname (ARN), ein beliebiger Anzeigename und eine Beschreibung, die Sie für den Befehl angegeben haben. + Der Befehlsstatus, der angibt, ob ein Befehl für die Ausführung auf dem Zielgerät verfügbar ist oder ob er veraltet oder gelöscht ist. + Die Payload oder PayloadTemplate, die Sie bereitgestellt haben. + Der Präprozessor, den Sie bereitgestellt haben. + Die von Ihnen angegebenen obligatorischen Parameter. + Die Uhrzeit, zu der der Befehl erstellt und zuletzt aktualisiert wurde. ### Rufen Sie eine Befehlsressource (Konsole) ab Um einen Befehl von der Konsole abzurufen, gehen Sie zum [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) der AWS IoT Konsole und wählen Sie dann den Befehl aus, den Sie erstellt haben, um dessen Details anzuzeigen. Zusätzlich zu den Befehlsdetails können Sie den Befehlsverlauf einsehen, der Informationen über die Ausführung des Befehls auf dem Zielgerät enthält. Nachdem Sie diesen Befehl auf dem Gerät ausgeführt haben, finden Sie auf dieser Registerkarte Informationen zu den Ausführungen. ### Rufen Sie eine Befehlsressource (CLI) ab Verwenden Sie den API-Vorgang der [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html)HTTP-Steuerungsebene oder den [https://docs.aws.amazon.com/cli/latest/reference/get-command.html](https://docs.aws.amazon.com/cli/latest/reference/get-command.html) AWS CLI Befehl, um Informationen über eine Befehlsressource abzurufen. Sie müssen den Befehl bereits mit der `CreateCommand` API-Anfrage oder der `create-command` CLI erstellt haben. #### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Sie autorisiert, diese Aktion auf dem Gerät auszuführen. Das folgende Beispiel zeigt eine IAM-Richtlinie, die dem Benutzer die Erlaubnis erteilt, die Aktion auszuführen. `GetCommand` Ersetzen Sie in diesem Beispiel: + `region`mit Ihrem AWS-Region, wie `us-east-1` zum Beispiel. + `account-id`mit deiner AWS-Konto Nummer, wie`123456789023`. + `command-id`mit Ihrer AWS IoT eindeutigen Befehlskennung, z. B. `LockDoor` oder`Light_Power_Status`. Wenn Sie mehr als einen Befehl abrufen möchten, können Sie diese Befehle in der IAM-Richtlinie im Abschnitt „*Ressourcen*“ angeben. **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:GetCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### Beispiel für einen Befehl abrufen ()AWS CLI Das folgende Beispiel zeigt Ihnen, wie Sie Informationen zu einem Befehl mit dem abrufen können `get-command` AWS CLI. Ersetzen Sie je nach Anwendung *``* durch den Bezeichner für den Befehl, für den Sie Informationen abrufen möchten. Sie können diese Informationen der Antwort der `create-command` CLI entnehmen. ``` aws iot get-command --command-id ``` Wenn Sie diesen Befehl ausführen, wird eine Antwort generiert, die Informationen über den Befehl, die Nutzlast und den Zeitpunkt der Erstellung und letzten Aktualisierung enthält. Es enthält auch Informationen, die angeben, ob ein Befehl veraltet ist oder gelöscht wird. Der folgende Code zeigt beispielsweise eine Beispielantwort. ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:::command/LockDoor", "namespace": "AWS-IoT", "payload":{ "content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=", "contentType": "application/json" }, "createdAt": "2024-03-23T00:50:10.095000-07:00", "lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00", "deprecated": false, "pendingDeletion": false } ``` ## Listen Sie Befehle in Ihrem auf AWS-Konto Nachdem Sie Befehle erstellt haben, können Sie sich die Befehle ansehen, die Sie in Ihrem Konto erstellt haben. In der Liste finden Sie Informationen zu: + Die Befehls-ID und alle Anzeigenamen, die Sie für die Befehle angegeben haben. + Der Amazon-Ressourcenname (ARN) der Befehle. + Der Befehlsstatus, der angibt, ob die Befehle für die Ausführung auf dem Zielgerät verfügbar sind oder ob sie veraltet sind. **Anmerkung** In der Liste wird nicht angezeigt, welche aus Ihrem Konto gelöscht werden. Wenn die Befehle noch nicht gelöscht werden müssen, können Sie die Details zu diesen Befehlen immer noch anhand ihrer Befehls-ID anzeigen. + Der Zeitpunkt, zu dem die Befehle erstellt und zuletzt aktualisiert wurden. ### Befehle in Ihrem Konto (Konsole) auflisten In der AWS IoT Konsole finden Sie die Liste der Befehle, die Sie erstellt haben, und deren Details, indem Sie zum [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) gehen. ### Befehle in Ihrem Konto auflisten (CLI) Verwenden Sie den [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html)API-Vorgang oder die [https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html)CLI, um die von Ihnen erstellten Befehle aufzulisten. #### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Sie autorisiert, diese Aktion auf dem Gerät auszuführen. Das folgende Beispiel zeigt eine IAM-Richtlinie, die dem Benutzer die Erlaubnis erteilt, die Aktion auszuführen. `ListCommands` Ersetzen Sie in diesem Beispiel: + `region`mit Ihrem AWS-Region, wie `us-east-1` zum Beispiel. + `account-id`mit deiner AWS-Konto Nummer, wie`123456789012`. **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:ListCommands", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/*" } } ``` #### Führen Sie Befehle in Ihrem Kontobeispiel auf Der folgende Befehl zeigt, wie Sie Befehle in Ihrem Konto auflisten. ``` aws iot list-commands --namespace "AWS-IoT" ``` Wenn Sie diesen Befehl ausführen, wird eine Antwort generiert, die eine Liste von Befehlen enthält, die Sie erstellt haben, sowie den Zeitpunkt, zu dem die Befehle erstellt wurden und wann sie zuletzt aktualisiert wurden. Er stellt auch Informationen zum Befehlsstatus bereit, die angeben, ob ein Befehl veraltet ist oder auf dem Zielgerät ausgeführt werden kann. Weitere Informationen zu den verschiedenen Status und den Gründen für den Status finden Sie unter. [Status der Befehlsausführung](iot-remote-command-concepts.md#iot-command-execution-status) ## Aktualisieren Sie eine Befehlsressource Nachdem Sie einen Befehl erstellt haben, können Sie den Anzeigenamen und die Beschreibung des Befehls aktualisieren. **Anmerkung** Die Payload für den Befehl kann nicht aktualisiert werden. Um diese Informationen zu aktualisieren oder eine geänderte Payload zu verwenden, müssen Sie einen neuen Befehl erstellen. ### Aktualisieren Sie eine Befehlsressource (Konsole) Um einen Befehl von der Konsole aus zu aktualisieren, rufen Sie den [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) der AWS IoT Konsole auf und führen Sie die folgenden Schritte aus. 1. Um eine vorhandene Befehlsressource zu aktualisieren, wählen Sie den Befehl aus, den Sie aktualisieren möchten, und klicken Sie dann unter **Aktionen** auf **Bearbeiten**. 1. Geben Sie den Anzeigenamen und die Beschreibung an, die Sie verwenden möchten, sowie alle Name-Wert-Paare als Tags für Ihren Befehl. 1. Wählen Sie **Bearbeiten**, um den Befehl mit den neuen Einstellungen zu speichern. ### Aktualisieren Sie eine Befehlsressource (CLI) Verwenden Sie den API-Vorgang der [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html)Steuerungsebene oder die [https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html) AWS CLI , um eine Befehlsressource zu aktualisieren. Mit dieser API können Sie: + Bearbeiten Sie den Anzeigenamen und die Beschreibung eines von Ihnen erstellten Befehls. + Verwerfen Sie eine Befehlsressource oder stellen Sie einen Befehl wieder her, der bereits als veraltet gilt. #### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Sie autorisiert, diese Aktion auf dem Gerät auszuführen. Das folgende Beispiel zeigt eine IAM-Richtlinie, die dem Benutzer die Erlaubnis erteilt, die Aktion auszuführen. `UpdateCommand` Ersetzen Sie in diesem Beispiel: + `region`mit Ihrem AWS-Region, wie `us-east-1` zum Beispiel. + `account-id`mit deiner AWS-Konto Nummer, wie`123456789012`. + `command-id`mit Ihrer AWS IoT eindeutigen Befehlskennung, z. `LockDoor` B. Wenn Sie mehr als einen Befehl abrufen möchten, können Sie diese Befehle in der IAM-Richtlinie im Abschnitt „*Ressourcen*“ angeben. **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:UpdateCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### Informationen zu einem Befehl aktualisieren — Beispiele ()AWS CLI Das folgende Beispiel zeigt Ihnen, wie Sie Informationen zu einem Befehl mithilfe des `update-command` AWS CLI Befehls aktualisieren. Hinweise dazu, wie Sie diese API verwenden können, um eine Befehlsressource als veraltet zu kennzeichnen oder wiederherzustellen, finden Sie unter. [Aktualisieren Sie eine Befehlsressource (CLI)](iot-remote-command-deprecate.md#iot-remote-command-deprecate-cli) Das Beispiel zeigt, wie Sie den Anzeigenamen und die Beschreibung eines Befehls aktualisieren können. Je nach Anwendung *``* ersetzen Sie ihn durch den Bezeichner für den Befehl, für den Sie Informationen abrufen möchten. ``` aws iot update-command \ --command-id --displayname \ --description ``` Wenn Sie diesen Befehl ausführen, wird eine Antwort generiert, die die aktualisierten Informationen über den Befehl und den Zeitpunkt der letzten Aktualisierung enthält. Der folgende Code zeigt eine Beispielanforderung und -antwort für die Aktualisierung des Anzeigenamens und der Beschreibung eines Befehls, der die Klimaanlage ausschaltet. ``` aws iot update-command \ --command-id \ --displayname \ --description ``` Die Ausführung dieses Befehls generiert die folgende Antwort. ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor", "displayName": "Secondary lock door", "description": "Locks doors to my home", "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00" } ``` ## Eine Befehlsressource verwerfen oder wiederherstellen Wenn Sie einen Befehl erstellt haben und ihn nicht mehr weiter verwenden möchten, können Sie ihn als veraltet markieren. Wenn Sie einen Befehl als veraltet markieren, werden alle ausstehenden Befehlsausführungen auf dem Zielgerät weiterlaufen, bis sie den Terminalstatus erreichen. Wenn ein Befehl als veraltet gilt und Sie ihn beispielsweise zum Senden einer neuen Befehlsausführung an das Zielgerät verwenden möchten, müssen Sie ihn wiederherstellen. **Anmerkung** Sie können einen veralteten Befehl nicht bearbeiten oder neue Ausführungen für ihn ausführen. *Um neue Befehle auf dem Gerät auszuführen, müssen Sie es wiederherstellen, sodass der Befehlsstatus auf Verfügbar geändert wird.* Weitere Informationen zum Verwerfen und Wiederherstellen eines Befehls sowie zu diesbezüglichen Überlegungen finden Sie unter. [Kennzeichnen einer Befehlsressource als veraltet](iot-remote-command-deprecate.md) ## Löschen Sie eine Befehlsressource Wenn Sie einen Befehl nicht mehr verwenden möchten, können Sie ihn dauerhaft aus Ihrem Konto entfernen. Wenn die Löschaktion erfolgreich ist: + Wenn der Befehl für eine Dauer, die länger als das maximale Timeout von 12 Stunden ist, als veraltet gilt, wird der Befehl sofort gelöscht. + Wenn der Befehl nicht veraltet ist oder für eine Dauer, die kürzer als das maximale Timeout ist, als veraltet gilt, befindet sich der Befehl in einem Status. `pending deletion` Er wird nach Ablauf des maximalen Timeouts von 12 Stunden automatisch aus Ihrem Konto entfernt. **Anmerkung** Der Befehl kann gelöscht werden, auch wenn noch ausstehende Befehlsausführungen vorliegen. Der Befehl befindet sich im Status Ausstehende Löschung und wird automatisch aus Ihrem Konto entfernt. ### Löschen Sie eine Befehlsressource (Konsole) Um einen Befehl von der Konsole zu löschen, rufen Sie den [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) der AWS IoT Konsole auf und führen Sie die folgenden Schritte aus. 1. Wählen Sie den Befehl aus, den Sie löschen möchten, und wählen Sie dann unter **Aktionen** die Option **Löschen** aus. 1. Bestätigen Sie, dass Sie den Befehl löschen möchten, und wählen Sie dann **Löschen** aus. Der Befehl wird zum Löschen markiert und nach 12 Stunden dauerhaft aus Ihrem Konto entfernt. ### Löschen Sie eine Befehlsressource (CLI) Verwenden Sie den API-Vorgang der `DeleteCommand` HTTP-Steuerungsebene oder den `delete-command` AWS CLI Befehl, um eine Befehlsressource zu löschen. Wenn die Löschaktion erfolgreich ist, wird `statusCode` der HTTP-Wert 204 oder 202 angezeigt, und der Befehl wird nach Ablauf der maximalen Timeoutdauer von 12 Stunden automatisch aus Ihrem Konto gelöscht. Im Fall des Status 204 bedeutet dies, dass der Befehl gelöscht wurde. #### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Sie autorisiert, diese Aktion auf dem Gerät auszuführen. Das folgende Beispiel zeigt eine IAM-Richtlinie, die dem Benutzer die Erlaubnis erteilt, die Aktion auszuführen. `DeleteCommand` Ersetzen Sie in diesem Beispiel: + `region`mit Ihrem AWS-Region, wie `us-east-1` zum Beispiel. + `account-id`mit deiner AWS-Konto Nummer, wie`123456789012`. + `command-id`mit Ihrer AWS IoT eindeutigen Befehlskennung, z. `LockDoor` B. Wenn Sie mehr als einen Befehl abrufen möchten, können Sie diese Befehle in der IAM-Richtlinie im Abschnitt „*Ressourcen*“ angeben. **** ``` { "Version":"2012-10-17", "Statement": { "Action": "iot:DeleteCommand", "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id" } } ``` #### Beispiel für einen Befehl löschen ()AWS CLI Die folgenden Beispiele zeigen Ihnen, wie Sie einen Befehl mithilfe des `delete-command` AWS CLI Befehls löschen. Je nach Anwendung *``* ersetzen Sie ihn durch den Bezeichner für den Befehl, den Sie löschen möchten. ``` aws iot delete-command --command-id ``` Wenn die API-Anfrage erfolgreich ist, generiert der Befehl den Statuscode 202 oder 204. Sie können die `GetCommand` API verwenden, um zu überprüfen, ob der Befehl in Ihrem Konto nicht mehr vorhanden ist. # Starten und Überwachen von Befehlsausführungen Nachdem Sie einen Befehl erstellt haben, starten Sie eine Ausführung auf dem Zielgerät. Das Gerät aktualisiert die Ergebnisse und veröffentlicht den Status in reservierten MQTT-Themen. Rufen Sie den Ausführungsstatus von Ihrem Konto ab und überwachen Sie ihn. Starten und überwachen Sie Befehle über die AWS IoT Konsole oder AWS CLI. **Topics** + [Starten Sie die Ausführung eines Befehls](#iot-remote-command-execution-start) + [Aktualisieren des Ergebnisses einer Befehlsausführung](#iot-remote-command-execution-update) + [Rufen Sie die Ausführung eines Befehls ab](#iot-remote-command-execution-get) + [Befehlsaktualisierungen mit dem MQTT-Testclient anzeigen](#iot-remote-command-execution-update-mqtt) + [Listet die Befehlsausführungen in Ihrem auf AWS-Konto](#iot-remote-command-execution-list) + [Löschen Sie die Ausführung eines Befehls](#iot-remote-command-execution-delete) ## Starten Sie die Ausführung eines Befehls **Wichtig** Sie sind allein dafür verantwortlich, Befehle auf sichere und gesetzeskonforme Weise bereitzustellen. Bevor Sie mit einer Ausführung beginnen, stellen Sie Folgendes sicher: + Sie haben im AWS IoT Namespace einen Befehl mit Payload-Informationen erstellt. Beim Starten der Ausführung verarbeitet das Gerät die Payload-Anweisungen und führt die angegebenen Aktionen aus. Informationen [Erstellen Sie eine Befehlsressource](iot-remote-command-create-manage.md#iot-remote-command-create) zur Befehlserstellung finden Sie unter. + Ihr Gerät hat für MQTT reservierte Themen für Befehle abonniert. Wenn Sie die Ausführung starten, werden die Payload-Informationen zu dieser reservierten MQTT-Anforderung veröffentlicht. Thema: **können Things- oder MQTT-Clients sein. **ist der Name des Dings oder die Client-ID. Unterstützte ** Werte: JSON und CBOR. Weitere Informationen finden Sie unter [Themen zu Befehlen](reserved-topics.md#reserved-topics-commands). ``` $aws/commands///executions/+/request/ ``` Verwenden Sie für andere Befehle als JSON/CBOR das folgende Format für ** Befehlsthemen: ``` $aws/commands///executions/+/request ``` ### Überlegungen zum Zielgerät Geben Sie das Zielgerät an, das den Befehl empfangen und ausführen soll. Verwenden Sie einen Ding-Namen für registrierte Geräte oder eine Client-ID für nicht registrierte Geräte. Nach dem Empfang der Payload führt das Gerät den Befehl aus und führt die angegebenen Aktionen aus. #### AWS IoT Sache Zielgeräte können Dinge sein, die in der AWS IoT Registrierung registriert sind. Dinge vereinfachen die Gerätesuche und -verwaltung. Registrieren Sie Geräte über die [Connect-Geräteseite](https://console.aws.amazon.com/iot/home#/connect-overview) als Dinge oder verwenden Sie [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html). Finden Sie vorhandene Dinge über [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) oder mithilfe von [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html). Einzelheiten zur Registrierung finden Sie unter [Dinge mit der Registrierung verwalten](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry). #### Client-ID Verwenden Sie für nicht registrierte Geräte die Client-ID. Die Client-ID ist eine eindeutige Kennung, die Sie Geräten zuweisen. Sie ist im MQTT-Protokoll definiert und enthält alphanumerische Zeichen, Unterstriche oder Bindestriche. Jedes Gerät, mit dem eine Verbindung hergestellt wird, AWS IoT benötigt eine eindeutige Client-ID. **Anmerkung** Bei registrierten Dingen kann die Client-ID mit dem Namen des Dings übereinstimmen. Beim Targeting auf eine bestimmte Client-ID müssen Geräte AWS IoT über diese Client-ID eine Verbindung herstellen, um die Payload zu empfangen. Die Client-ID ist die MQTT-Client-ID, mit der Geräte eine Verbindung herstellen. AWS IoT Core AWS IoT verwendet diese ID, um Geräte zu identifizieren und Verbindungen und Abonnements zu verwalten. ### Überlegungen zum Timeout bei der Befehlsausführung Timeout gibt die Dauer (in Sekunden) an, für die Geräte Ausführungsergebnisse bereitstellen. Nach dem Erstellen einer Ausführung wird ein Timer gestartet. Wenn das Gerät offline geht oder innerhalb des Timeouts keine Ergebnisse meldet, wird bei der Ausführung ein Timeout mit Status angezeigt`TIMED_OUT`. Standard: 10 Sekunden. Maximal: 12 Stunden. #### Timeout-Wert und `TIMED_OUT` Ausführungsstatus Sowohl die Cloud als auch das Gerät können einen Timeout melden. Nach dem Senden des Befehls startet ein Timer. Wenn innerhalb des Timeouts keine Geräteantwort eingeht, setzt die Cloud den Ausführungsstatus auf `TIMED_OUT` mit Ursachencode`$NO_RESPONSE_FROM_DEVICE`. Dies tritt auf, wenn: + Das Gerät ist während der Ausführung offline gegangen. + Das Gerät konnte die Ausführung nicht innerhalb des Timeouts abschließen. + Das Gerät konnte den Status nicht innerhalb des Timeouts melden. Wenn in diesem Fall der Ausführungsstatus von aus der Cloud gemeldet `TIMED_OUT` wird, erfolgt die Befehlsausführung nicht über ein Terminal. Ihr Gerät kann eine Antwort veröffentlichen, die den Status eines beliebigen Terminalstatus außer Kraft setzt:`SUCCEEDED`, `FAILED` oder. `REJECTED` Die Befehlsausführung wird dann zum Terminal und akzeptiert keine weiteren Updates. Ihr Gerät kann auch einen von der Cloud initiierten `TIMED_OUT` Status aktualisieren, indem es meldet, dass bei der Ausführung des Befehls ein Timeout aufgetreten ist. In diesem Fall bleibt der Status der Befehlsausführung unverändert`TIMED_OUT`, das `statusReason` Objekt wird jedoch auf der Grundlage der vom Gerät gemeldeten Informationen aktualisiert. Die Befehlsausführung wird dann zum Terminal, und es werden keine weiteren Aktualisierungen akzeptiert. #### Verwenden persistenter MQTT-Sitzungen Sie können persistente MQTT-Sitzungen für die Verwendung mit der AWS IoT Device Management Befehlsfunktion konfigurieren. Diese Funktion ist besonders nützlich, wenn Ihr Gerät offline geht und Sie sicherstellen möchten, dass das Gerät den Befehl auch dann empfängt, wenn es vor Ablauf des Timeouts wieder online ist und die angegebenen Anweisungen ausführt. Standardmäßig ist die Ablaufzeit einer persistenten MQTT-Sitzung auf 60 Minuten festgelegt. Wenn Ihr Timeout für die Befehlsausführung auf einen Wert konfiguriert ist, der diese Dauer überschreitet, können Befehlsausführungen, die länger als 60 Minuten dauern, vom Message Broker abgelehnt werden und fehlschlagen. Um Befehle auszuführen, die länger als 60 Minuten dauern, können Sie eine Verlängerung der Ablaufzeit der persistenten Sitzung anfordern. **Anmerkung** Um sicherzustellen, dass Sie die Funktion für persistente MQTT-Sitzungen korrekt verwenden, setzen Sie das Clean Start-Flag auf Null. Weitere Informationen finden Sie unter [Persistente MQTT-Sitzungen](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-persistent-sessions). ### Starten Sie die Ausführung eines Befehls (Konsole) Um mit der Ausführung des Befehls von der Konsole aus zu beginnen, rufen Sie die [Command Hub-Seite](https://console.aws.amazon.com/iot/home#/commandHub) der AWS IoT Konsole auf und führen Sie die folgenden Schritte aus. 1. Um den Befehl auszuführen, den Sie erstellt haben, wählen Sie **Befehl ausführen**. 1. Lesen Sie die Informationen zu dem Befehl, den Sie erstellt haben, einschließlich der reservierten MQTT-Themen und Parameter, falls zutreffend. Geben Sie für dynamische Befehle die Parameterwerte ein oder belassen Sie sie bei den Standardwerten. Für Parameter, die keinen Standardwert haben, müssen Sie einen Wert angeben, der im Rahmen dieser Ausführung gesendet werden soll. 1. Geben Sie das Zielgerät an, das den Befehl empfangen und ausführen soll. Das Gerät kann als AWS IoT Ding angegeben werden, wenn es registriert wurde AWS IoT, oder mithilfe der Client-ID, falls Ihr Gerät noch nicht registriert wurde. Weitere Informationen finden Sie unter [Überlegungen zum Zielgerät](#iot-command-execution-target). 1. (Optional) Konfigurieren Sie einen Timeout-Wert für den Befehl, der die Dauer festlegt, für die der Befehl ausgeführt werden soll, bevor das Timeout eintritt. Wenn Ihr Befehl länger als 60 Minuten ausgeführt werden muss, müssen Sie möglicherweise die Ablaufzeit für persistente MQTT-Sitzungen erhöhen. Weitere Informationen finden Sie unter [Überlegungen zum Timeout bei der Befehlsausführung](#iot-command-execution-timeout). 1. Wählen Sie **Befehl ausführen** aus. ### Starten Sie die Ausführung eines Befehls ()AWS CLI Verwenden Sie den API-Vorgang für die [https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html)HTTP-Datenebene, um die Ausführung eines Befehls zu starten. Die API-Anforderung und -Antwort korrelieren anhand der Befehlsausführungs-ID. Nachdem das Gerät die Ausführung des Befehls abgeschlossen hat, kann es den Status und das Ausführungsergebnis an die Cloud melden, indem es eine Nachricht im Antwortthema des Befehls veröffentlicht. Bei einem benutzerdefinierten Antwortcode können Anwendungscodes, deren Eigentümer Sie sind, die Antwortnachricht verarbeiten und das Ergebnis an sie senden AWS IoT. Wenn Ihre Geräte das Thema für die Befehlsanfrage abonniert haben, veröffentlicht die `StartCommandExecution` API die Payload-Meldung zum Thema. Die Payload kann ein beliebiges Format Ihrer Wahl verwenden. Weitere Informationen finden Sie unter [Payload des Befehls](iot-remote-command-create-manage.md#iot-commands-payload). ``` $aws/commands///executions/+/request/ ``` Wenn das Payload-Format nicht JSON oder CBOR ist, wird im Folgenden das Format des Themas der Befehlsanfrage dargestellt. ``` $aws/commands///executions/+/request ``` #### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Sie autorisiert, diese Aktion auf dem Gerät auszuführen. Das folgende Beispiel zeigt eine IAM-Richtlinie, die dem Benutzer die Erlaubnis erteilt, die Aktion auszuführen. `StartCommandExecution` Ersetzen Sie in diesem Beispiel: + `region`mit Ihrem AWS-Region, wie `us-east-1` zum Beispiel. + `account-id`mit deiner AWS-Konto Nummer, wie`123456789012`. + `command-id`mit einer eindeutigen Kennung für Ihren AWS IoT Befehl, wie `LockDoor` z. Wenn Sie mehr als einen Befehl senden möchten, können Sie diese Befehle in der IAM-Richtlinie angeben. + `devices`entweder `thing` oder `client` je nachdem, ob Ihre Geräte als AWS IoT Dinge registriert wurden oder ob sie als MQTT-Clients spezifiziert sind. + `device-id`mit deinem AWS IoT `thing-name` oder`client-id`. ``` { "Effect": "Allow", "Action": [ "iot:StartCommandExecution" ], "Resource": [ "arn:aws:iot:region:account-id:command/command-id", "arn:aws:iot:region:account-id:devices/device-id" ] } ``` Eine Liste der unterstützten Bedingungsschlüssel finden Sie unter [Bedingungsschlüssel für AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-policy-keys) im *IAM-Benutzerhandbuch*. `StartCommandExecution` #### Rufen Sie den kontospezifischen Endpunkt auf der Datenebene ab Bevor Sie den API-Befehl ausführen, müssen Sie die kontospezifische Endpunkt-URL für den Endpunkt abrufen. Wenn Sie Dual-Stack-Endpunkte (IPv4und IPv6) verwenden, verwenden Sie den. `iot:Data-ATS` Der `iot:Jobs` Endpunkt ist nur für IPv4 . Wenn Sie z. B. den folgenden Befehl ausführen: ``` aws iot describe-endpoint --endpoint-type iot:Data-ATS ``` Es gibt die kontospezifische Endpunkt-URL zurück, wie in der folgenden Beispielantwort gezeigt. ``` { "endpointAddress": "-ats.iot..api.com" } ``` #### Beispiel für eine Befehlsausführung starten ()AWS CLI Das folgende Beispiel zeigt, wie die Ausführung eines Befehls mithilfe des `start-command-execution` AWS CLI Befehls gestartet wird. Ersetzen Sie in diesem Beispiel: + *``*mit dem ARN für den Befehl, den Sie ausführen möchten. Sie können diese Informationen aus der Antwort des `create-command` CLI-Befehls abrufen. Wenn Sie beispielsweise den Befehl zum Ändern des Lenkradmodus ausführen, verwenden Sie`arn:aws:iot:region:account-id:command/SetComfortSteeringMode`. + *``*mit dem Thing-ARN für das Zielgerät, das ein IoT-Ding oder ein MQTT-Client sein kann, für den Sie den Befehl ausführen möchten. Wenn Sie beispielsweise den Befehl für das Zielgerät ausführen`myRegisteredThing`, verwenden Sie`arn:aws:iot:region:account-id:thing/myRegisteredThing`. + *``*mit dem kontospezifischen Endpunkt, den Sie in abgerufen haben[Rufen Sie den kontospezifischen Endpunkt auf der Datenebene ab](#iot-remote-command-execution-start-endpoint), mit dem Präfix. `https://` Beispiel, `https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com`. + (Optional) Sie können bei der Ausführung des API-Vorgangs auch einen zusätzlichen Parameter angeben. `executionTimeoutSeconds` `StartCommandExecution` Dieses optionale Feld gibt die Zeit in Sekunden an, innerhalb derer das Gerät die Ausführung des Befehls abschließen muss. Standardmäßig ist der Wert 10 Sekunden. Wenn der Status der Befehlsausführung lautet`CREATED`, wird ein Timer gestartet. Wenn das Ergebnis der Befehlsausführung nicht vor Ablauf des Timers eingeht, ändert sich der Status automatisch auf`TIMED_OUT`. + ``` aws iot-jobs-data start-command-execution \ --command-arn \ --target-arn \ --endpoint \ --execution-timeout-seconds 900 ``` + (Optional) Geben Sie für dynamische Befehle die Parameter und ihre Werte an, die als Ersatz verwendet werden sollen. Sie müssen einen Wert für Parameter angeben, für die bei der Befehlserstellung kein defaultValue festgelegt wurde. Wenn ein Parameter einen defaultValue hat, hat der hier angegebene Parameterwert Vorrang. Bei Parametern, für die ValueConditions gesetzt ist, muss der hier angegebene Parameterwert die Bedingung erfüllen. Basierend auf einem Beispiel für einen `Light_Power_Status` dynamischen Befehl: + ``` aws iot-jobs-data start-command-execution \ --command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status \ --target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \ --endpoint \ --execution-timeout-seconds 900 \ --parameters "powerStatus={S=ON}" ``` Wenn Sie diesen Befehl ausführen, wird eine Befehlsausführungs-ID zurückgegeben. Sie können diese ID verwenden, um den Status der Befehlsausführung, die Details und den Verlauf der Befehlsausführung abzufragen. **Anmerkung** Wenn der Befehl veraltet ist, schlägt die `StartCommandExecution` API-Anfrage mit einer Validierungsausnahme fehl. Um diesen Fehler zu beheben, stellen Sie zuerst den Befehl mithilfe der `UpdateCommand` API wieder her und führen Sie dann die `StartCommandExecution` Anfrage aus. ``` { "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542" } ``` ## Aktualisieren des Ergebnisses einer Befehlsausführung Verwenden Sie den API-Vorgang der `UpdateCommandExecution` MQTT-Datenebene, um den Status oder das Ergebnis einer Befehlsausführung zu aktualisieren. **Anmerkung** Bevor Sie diese API verwenden: Ihr Gerät muss eine MQTT-Verbindung hergestellt und die Themen Commands Request und Response abonniert haben. Weitere Informationen finden Sie unter [Arbeitsablauf für Befehle auf hoher Ebene](iot-remote-command-workflow.md). Sie müssen diesen Befehl bereits mithilfe der `StartCommandExecution` API-Operation ausgeführt haben. ### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Ihr Gerät autorisiert, diese Aktionen auszuführen. Im Folgenden finden Sie ein Beispiel für eine Richtlinie, die Ihr Gerät zur Ausführung der Aktion autorisiert. Weitere Beispiele für IAM-Richtlinien, die dem Benutzer die Erlaubnis geben, die `UpdateCommandExecution` MQTT-Aktion auszuführen, finden Sie unter. [Beispiele zu den Verbinden- und Veröffentlichen-Richtlinien](connect-and-pub.md) Ersetzen Sie in diesem Beispiel: + `Region`mit Ihrem AWS-Region, wie zum Beispiel. `us-east-1` + `AccountID`mit deiner AWS-Konto Nummer, wie*`123456789012`*. + `ThingName`mit dem Namen Ihres AWS IoT Dings, für das Sie die Befehlsausführung anvisieren, wie *`myRegisteredThing`* z. + `commands-request-topic`und `commands-response-topic` mit den Namen der Anfrage- und Antwortthemen Ihrer AWS IoT Befehle. Weitere Informationen finden Sie unter [Arbeitsablauf für Befehle auf hoher Ebene](iot-remote-command-workflow.md). #### Beispiel für eine IAM-Richtlinie für die MQTT-Client-ID Der folgende Code zeigt ein Beispiel für eine Geräterichtlinie bei Verwendung der MQTT-Client-ID. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Publish", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json" ] }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}" } ] } ``` #### Beispiel für eine IAM-Richtlinie für das IoT-Ding Der folgende Code zeigt ein Beispiel für eine Geräterichtlinie bei der Verwendung AWS IoT eines Dings. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Publish", "Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response" }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json" ] }, { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}" } ] } ``` ### Wie benutzt man die `UpdateCommandExecution` API Nachdem die Befehlsausführung unter dem Thema der Anfrage eingegangen ist, verarbeitet das Gerät den Befehl. Anschließend verwendet es die `UpdateCommandExecution` API, um den Status und das Ergebnis der Befehlsausführung auf das folgende Antwortthema zu aktualisieren. ``` $aws/commands///executions//response/ ``` In diesem Beispiel *``* ist dies die eindeutige Kennung Ihres Zielgeräts und *``* die Kennung der Befehlsausführung auf dem Zielgerät. Das ** kann JSON oder CBOR sein. **Anmerkung** Wenn Sie Ihr Gerät nicht bei registriert haben AWS IoT, können Sie die Client-ID anstelle eines Dingnamens als Kennung verwenden. ``` $aws/commands/clients//executions//response/ ``` #### Das Gerät hat Aktualisierungen des Ausführungsstatus gemeldet Ihre Geräte können die API verwenden, um alle der folgenden Statusaktualisierungen zur Befehlsausführung zu melden. Weitere Informationen zu diesen Status finden Sie unter[Status der Befehlsausführung](iot-remote-command-concepts.md#iot-command-execution-status). + `IN_PROGRESS`: Wenn das Gerät mit der Ausführung des Befehls beginnt, kann es den Status auf `IN_PROGRESS` aktualisieren. + `SUCCEEDED`: Wenn das Gerät den Befehl erfolgreich verarbeitet und die Ausführung abgeschlossen hat, kann das Gerät eine Nachricht im Antwortthema als veröffentlichen`SUCCEEDED`. + `FAILED`: Wenn das Gerät den Befehl nicht ausführen konnte, kann es eine Nachricht im Antwortthema als veröffentlichen`FAILED`. + `REJECTED`: Wenn das Gerät den Befehl nicht akzeptiert hat, kann es eine Nachricht im Antwortthema als veröffentlichen`REJECTED`. + `TIMED_OUT`: Der Status der Befehlsausführung kann sich `TIMED_OUT` aus einem der folgenden Gründe auf ändern. + Das Ergebnis der Befehlsausführung wurde nicht empfangen. Dies kann passieren, weil die Ausführung nicht innerhalb der angegebenen Dauer abgeschlossen wurde oder wenn das Gerät die Statusinformationen nicht im Antwortthema veröffentlicht hat. + Das Gerät meldet, dass beim Versuch, den Befehl auszuführen, ein Timeout aufgetreten ist. Weitere Informationen zum `TIMED_OUT` Status finden Sie unter[Timeout-Wert und `TIMED_OUT` Ausführungsstatus](#iot-command-execution-timeout-status). #### Überlegungen bei der Verwendung der `UpdateCommandExecution` API Im Folgenden sind einige wichtige Überlegungen zur Verwendung der `UpdateCommandExecution` API aufgeführt. + Ihre Geräte können ein optionales `statusReason` Objekt verwenden, um zusätzliche Informationen zur Ausführung bereitzustellen. Wenn Ihre Geräte dieses Objekt bereitstellen, ist das `reasonCode` Feld des Objekts erforderlich, aber das `reasonDescription` Feld ist optional. + Wenn Ihre Geräte das `statusReason` Objekt verwenden, `reasonCode` müssen sie das Muster verwenden `[A-Z0-9_-]+` und dürfen nicht länger als 64 Zeichen sein. Wenn Sie das angeben`reasonDescription`, stellen Sie sicher, dass es nicht länger als 1.024 Zeichen ist. Es können alle Zeichen außer Steuerzeichen wie Zeilenumbrüchen verwendet werden. + Ihre Geräte können ein optionales `result` Objekt verwenden, um Informationen über das Ergebnis der Befehlsausführung bereitzustellen, z. B. den Rückgabewert eines Remote-Funktionsaufrufs. Wenn Sie das angeben`result`, muss mindestens ein Eintrag erforderlich sein. + In dem `result` Feld geben Sie die Einträge als Schlüssel-Wert-Paare an. Für jeden Eintrag müssen Sie die Datentypinformationen als Zeichenfolge, boolescher Wert oder Binärwert angeben. Ein Zeichenkettendatentyp muss den Schlüssel verwenden`s`, ein boolescher Datentyp verwendet den Schlüssel `b` und ein binärer Datentyp muss den Schlüssel verwenden. `bin` Stellen Sie sicher, dass diese Schlüssel in Kleinbuchstaben geschrieben sind. + Wenn Sie beim Ausführen der `UpdateCommandExecution` API auf einen Fehler stoßen, können Sie den Fehler in der `AWSIoTLogsV2` Protokollgruppe in Amazon anzeigen CloudWatch. Informationen zum Aktivieren der Protokollierung und zum Anzeigen der Protokolle finden Sie unter[Konfigurieren Sie die AWS IoT Protokollierung](configure-logging.md). #### `UpdateCommandExecution`API-Beispiel Der folgende Code zeigt ein Beispiel dafür, wie Ihr Gerät die `UpdateCommandExecution` API verwenden kann, um den Ausführungsstatus zu melden, das `statusReason` Feld, um zusätzliche Informationen zum Status bereitzustellen, und das Ergebnisfeld, um Informationen über das Ergebnis der Ausführung bereitzustellen, wie in diesem Fall den Prozentsatz der Autobatterie. ``` { "status": "IN_PROGRESS", "statusReason": { "reasonCode": "200", "reasonDescription": "Execution_in_progress" }, "result": { "car_battery": { "s": "car battery at 50 percent" } } } ``` ## Rufen Sie die Ausführung eines Befehls ab Nachdem Sie einen Befehl ausgeführt haben, können Sie Informationen über die Befehlsausführung von der AWS IoT Konsole abrufen und den AWS CLI Sie können die folgenden Informationen abrufen. **Anmerkung** Um den aktuellen Status der Befehlsausführung abzurufen, muss Ihr Gerät die Statusinformationen mithilfe der `UpdateCommandExecution` MQTT-API im Antwortthema veröffentlichen, wie unten beschrieben. Bis das Gerät zu diesem Thema veröffentlicht, meldet die `GetCommandExecution` API den Status als `CREATED` oder`TIMED_OUT`. Jede Befehlsausführung, die Sie erstellen, hat: + eine **Ausführungs-ID**, die eine eindeutige Kennung der Befehlsausführung darstellt. + den **Status** der Befehlsausführung. Wenn Sie den Befehl auf dem Zielgerät ausführen, geht die Befehlsausführung in den Zustand `CREATED` über. Sie kann dann in andere Befehlsausführungsstatus übergehen, wie unten beschrieben. + Das **Ergebnis** der Befehlsausführung. + Die eindeutige **Befehls-ID** und das Zielgerät, für das Ausführungen erstellt wurden. + Das **Startdatum**, das die Uhrzeit angibt, zu der die Befehlsausführung erstellt wurde. ### Rufen Sie eine Befehlsausführung ab (Konsole) Sie können eine Befehlsausführung mit einer der folgenden Methoden von der Konsole abrufen. + **Von der Command-Hub-Seite** Gehen Sie zur [Command Hub-Seite](https://console.aws.amazon.com/iot/home#/commandHub) der AWS IoT Konsole und führen Sie diese Schritte aus. 1. Wählen Sie den Befehl aus, für den Sie eine Ausführung auf dem Zielgerät erstellt haben. 1. Auf der Seite mit den Befehlsdetails auf der Registerkarte **Befehlsverlauf** sehen Sie die Ausführungen, die Sie erstellt haben. Wählen Sie die Ausführung aus, für die Sie Informationen abrufen möchten. 1. Wenn Ihre Geräte die `UpdateCommandExecution` API zur Bereitstellung der Ergebnisinformationen verwendet haben, finden Sie diese Informationen dann auf der Registerkarte **Ergebnisse** auf dieser Seite. + **Auf der Thing-Hub-Seite** Wenn Sie bei der Ausführung des Befehls ein AWS IoT Ding als Zielgerät ausgewählt haben, können Sie die Ausführungsdetails auf der Thing-Hub-Seite einsehen. 1. Gehen Sie in der AWS IoT Konsole zur [Thing Hub-Seite](https://console.aws.amazon.com/iot/home#/thinghub) und wählen Sie das Ding aus, für das Sie die Befehlsausführung erstellt haben. 1. Auf der Seite mit den Ding-Details im **Befehlsverlauf** sehen Sie die Ausführungen, die Sie erstellt haben. Wählen Sie die Ausführung aus, für die Sie Informationen abrufen möchten. 1. Wenn Ihre Geräte die `UpdateCommandExecution` API zur Bereitstellung der Ergebnisinformationen verwendet haben, finden Sie diese Informationen dann auf der Registerkarte **Ergebnisse** auf dieser Seite. ### Rufen Sie eine Befehlsausführung ab (CLI) Verwenden Sie den HTTP-API-Vorgang der [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT Core Steuerungsebene, um Informationen über die Ausführung eines Befehls abzurufen. Sie müssen diesen Befehl bereits mithilfe der `StartCommandExecution` API-Operation ausgeführt haben. #### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Sie autorisiert, diese Aktion auf dem Gerät auszuführen. Das folgende Beispiel zeigt eine IAM-Richtlinie, die dem Benutzer die Erlaubnis erteilt, die Aktion auszuführen. `GetCommandExecution` Ersetzen Sie in diesem Beispiel: + `region`mit Ihrem AWS-Region, wie `us-east-1` zum Beispiel. + `account-id`mit deiner AWS-Konto Nummer, wie`123456789012`. + `command-id`mit Ihrer eindeutigen AWS IoT Befehlskennung, z. `LockDoor` B. + `devices`entweder `thing` oder `client` je nachdem, ob Ihre Geräte als AWS IoT Dinge registriert wurden oder als MQTT-Clients spezifiziert sind. + `device-id`mit deinem AWS IoT `thing-name` oder`client-id`. ``` { "Effect": "Allow", "Action": [ "iot:GetCommandExecution" ], "Resource": [ "arn:aws:iot:region:account-id:command/command-id", "arn:aws:iot:region:account-id:devices/device-id" ] } ``` #### Rufen Sie ein Beispiel für die Befehlsausführung ab Das folgende Beispiel zeigt Ihnen, wie Sie Informationen über einen Befehl abrufen, der mit dem `start-command-execution` AWS CLI Befehl ausgeführt wurde. Das folgende Beispiel zeigt, wie Sie Informationen über einen Befehl abrufen können, der ausgeführt wurde, um den Lenkradmodus auszuschalten. Ersetzen Sie in diesem Beispiel: + *``*mit der Kennung für die Befehlsausführung, für die Sie Informationen abrufen möchten. + *``*mit der Amazon-Ressourcennummer (ARN) des Geräts, für das Sie die Ausführung anstreben. Sie können diese Informationen aus der Antwort des `start-command-execution` CLI-Befehls abrufen. + Wenn Ihre Geräte die `UpdateCommandExection` API zur Bereitstellung des Ausführungsergebnisses verwendet haben, können Sie optional angeben, ob das Ergebnis der Befehlsausführung in die Antwort der `GetCommandExecution` API über die `GetCommandExecution` API aufgenommen werden soll. ``` aws iot get-command-execution --execution-id \ --target-arn \ --include-result ``` Die Ausführung dieses Befehls generiert eine Antwort, die Informationen über den ARN der Befehlsausführung, den Ausführungsstatus und den Zeitpunkt des Beginns und des Abschlusses der Ausführung enthält. Es stellt auch ein `statusReason` Objekt bereit, das zusätzliche Informationen über den Status enthält. Weitere Informationen zu den verschiedenen Status und den Gründen für den Status finden Sie unter[Status der Befehlsausführung](iot-remote-command-concepts.md#iot-command-execution-status). Der folgende Code zeigt eine Beispielantwort aus der API-Anfrage. **Anmerkung** Das `completedAt` Feld in der Ausführungsantwort entspricht dem Zeitpunkt, zu dem das Gerät einen Terminalstatus an die Cloud meldet. Im Fall des `TIMED_OUT` Status wird dieses Feld nur gesetzt, wenn das Gerät einen Timeout meldet. Wenn der `TIMED_OUT` Status von der Cloud festgelegt wird, wird der `TIMED_OUT` Status nicht aktualisiert. Weitere Informationen zum Timeout-Verhalten finden Sie unter[Überlegungen zum Timeout bei der Befehlsausführung](#iot-command-execution-timeout). ``` { "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor", "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/myRegisteredThing", "status": "SUCCEEDED", "statusReason": { "reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED", "reasonDescription": "SUCCESS" }, "result": { "sn": { "s": "ABC-001" }, "digital": { "b": true } }, "createdAt": "2024-03-23T00:50:10.095000-07:00", "completedAt": "2024-03-23T00:50:10.095000-07:00" } ``` ## Befehlsaktualisierungen mit dem MQTT-Testclient anzeigen Sie können den MQTT-Testclient verwenden, um sich den Nachrichtenaustausch über MQTT anzusehen, wenn Sie die Befehlsfunktion verwenden. Nachdem Ihr Gerät eine MQTT-Verbindung mit hergestellt hat AWS IoT, können Sie einen Befehl erstellen, die Nutzlast angeben und ihn dann auf dem Gerät ausführen. Wenn Sie den Befehl ausführen und Ihr Gerät das MQTT-Request-Thema für Befehle abonniert hat, wird die zu diesem Thema veröffentlichte Payload-Meldung angezeigt. Das Gerät empfängt dann die Payload-Anweisungen und führt die angegebenen Operationen auf dem Gerät aus. AWS IoT Anschließend verwendet es die `UpdateCommandExecution` API, um das Ergebnis der Befehlsausführung und die Statusinformationen in den MQTT-Antwortthemen zu veröffentlichen, die für Befehle reserviert sind. AWS IoT Device Management hört sich Updates zu den Antwortthemen an, speichert die aktualisierten Informationen und veröffentlicht Protokolle an AWS CloudTrail und Amazon CloudWatch. Sie können dann die neuesten Informationen zur Befehlsausführung von der Konsole oder mithilfe der `GetCommandExecution` API abrufen. Die folgenden Schritte zeigen, wie Sie den MQTT-Testclient verwenden, um Nachrichten zu beobachten. 1. Öffnen Sie den [MQTT-Testclient](https://console.aws.amazon.com/iot/home#/test) in der AWS IoT Konsole. 1. Geben Sie auf der Registerkarte **Abonnieren** das folgende Thema ein und wählen Sie dann **Abonnieren** aus. Dabei ** steht der Name des Geräts, mit AWS IoT dem Sie sich registriert haben. **Anmerkung** Den Ding-Namen für Ihr Gerät finden Sie auf der [Thing Hub-Seite](https://console.aws.amazon.com/iot/home#/thinghub) der AWS IoT Konsole. Wenn Sie Ihr Gerät nicht als Ding registriert haben, können Sie das Gerät registrieren, wenn Sie eine Verbindung zu AWS IoT herstellen auf der [Seite Gerät Connect](https://console.aws.amazon.com/iot/home#/connect-overview). ``` $aws/commands/things//executions/+/request ``` 1. (Optional) Auf der Registerkarte **Abonnieren** können Sie auch die folgenden Themen eingeben und **Abonnieren** auswählen. ``` $aws/commands/things/+/executions/+/response/accepted/json $aws/commands/things/+/executions/+/response/rejected/json ``` 1. Wenn Sie die Ausführung eines Befehls starten, wird die Payload der Nachricht an das Gerät gesendet, wobei das Anforderungsthema verwendet wird, das das Gerät abonniert hat. `$aws/commands/things//executions/+/request` Im MQTT-Testclient sollten Sie die Befehls-Payload sehen, die die Anweisungen für das Gerät zur Verarbeitung des Befehls enthält. 1. Nachdem das Gerät mit der Ausführung des Befehls begonnen hat, kann es Statusaktualisierungen zum folgenden MQTT-Antwortthema veröffentlichen, das für Befehle reserviert ist. ``` $aws/commands///executions//response/json ``` Stellen Sie sich zum Beispiel einen Befehl vor, den Sie ausgeführt haben, um die Klimaanlage Ihres Autos einzuschalten und die Temperatur auf einen gewünschten Wert zu senken. Die folgende JSON-Datei zeigt eine Beispielnachricht, die das Fahrzeug im Antwortthema veröffentlicht hat und aus der hervorgeht, dass der Befehl nicht ausgeführt werden konnte. ``` { "deviceId": "My_Car", "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542", "status": "FAILED", "statusReason": { "reasonCode": "CAR_LOW_ON_BATTERY", "reasonDescription": "Car battery is lower than 5 percent" } } ``` In diesem Fall können Sie die Batterie Ihres Autos aufladen und den Befehl dann erneut ausführen. ## Listet die Befehlsausführungen in Ihrem auf AWS-Konto Nachdem Sie einen Befehl ausgeführt haben, können Sie Informationen über die Befehlsausführung von der AWS IoT Konsole abrufen und den AWS CLI Sie können die folgenden Informationen abrufen. + eine **Ausführungs-ID**, die eine eindeutige Kennung der Befehlsausführung darstellt. + den **Status** der Befehlsausführung. Wenn Sie den Befehl auf dem Zielgerät ausführen, geht die Befehlsausführung in den Zustand `CREATED` über. Sie kann dann in andere Befehlsausführungsstatus übergehen, wie unten beschrieben. + Die eindeutige **Befehls-ID** und das Zielgerät, für das Ausführungen erstellt wurden. + Das **Startdatum**, das die Uhrzeit angibt, zu der die Befehlsausführung erstellt wurde. ### Listet die Befehlsausführungen in Ihrem Konto (Konsole) auf Sie können alle Befehlsausführungen von der Konsole aus mit einer der folgenden Methoden anzeigen. + **Auf der Command-Hub-Seite** Gehen Sie zur [Command Hub-Seite](https://console.aws.amazon.com/iot/home#/commandHub) der AWS IoT Konsole und führen Sie diese Schritte aus. 1. Wählen Sie den Befehl aus, für den Sie eine Ausführung auf dem Zielgerät erstellt haben. 1. Gehen Sie auf der Seite mit den Befehlsdetails zur Registerkarte **Befehlsverlauf**. Dort wird eine Liste der von Ihnen erstellten Ausführungen angezeigt. + **Von der Thing-Hub-Seite** Wenn Sie bei der Ausführung des Befehls ein AWS IoT Ding als Zielgerät ausgewählt und mehrere Befehlsausführungen für ein einzelnes Gerät erstellt haben, können Sie die Ausführungen für das Gerät auf der Thing-Hub-Seite anzeigen. 1. Gehen Sie in der AWS IoT Konsole zur [Thing Hub-Seite](https://console.aws.amazon.com/iot/home#/thinghub) und wählen Sie das Ding aus, für das Sie die Ausführungen erstellt haben. 1. Auf der Seite mit den Ding-Details sehen Sie im **Befehlsverlauf** eine Liste der Ausführungen, die Sie für das Gerät erstellt haben. ### Befehlsausführungen in Ihrem Konto auflisten (CLI) Verwenden Sie den HTTP-API-Vorgang der [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html) AWS IoT Core Steuerungsebene, um alle Befehlsausführungen in Ihrem Konto aufzulisten. #### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Sie autorisiert, diese Aktion auf dem Gerät auszuführen. Das folgende Beispiel zeigt eine IAM-Richtlinie, die dem Benutzer die Erlaubnis erteilt, die Aktion auszuführen. `ListCommandExecutions` Ersetzen Sie in diesem Beispiel: + `region`mit Ihrem AWS-Region, wie `us-east-1` zum Beispiel. + `account-id`mit deiner AWS-Konto Nummer, wie`123456789012`. + `command-id`mit Ihrer eindeutigen AWS IoT Befehlskennung, z. `LockDoor` B. ``` { "Effect": "Allow", "Action": "iot:ListCommandExecutions", "Resource": * } ``` #### Beispiel für Befehlsausführungen auflisten Das folgende Beispiel zeigt Ihnen, wie Sie Befehlsausführungen in Ihrem auflisten. AWS-Konto Bei der Ausführung des Befehls müssen Sie angeben, ob die Liste so gefiltert werden soll, dass nur Befehlsausführungen angezeigt werden, die mit dem für ein bestimmtes Gerät erstellt wurden`targetArn`, oder Ausführungen für einen bestimmten Befehl, der mit dem angegeben wurde. `commandArn` Ersetzen Sie in diesem Beispiel: + *``*mit der Amazon-Ressourcennummer (ARN) des Geräts, für das Sie die Ausführung planen, z. `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f` B. + *``*mit der Amazon-Ressourcennummer (ARN) des Geräts, für das Sie die Ausführung planen, z. `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f` B. + *``*mit der Zeit, nach der Sie die Ausführungen auflisten möchten, die erstellt wurden, zum Beispiel. `2024-11-01T03:00` ``` aws iot list-command-executions \ --target-arn \ --started-time-filter '{after=}' \ --sort-order "ASCENDING" ``` Wenn Sie diesen Befehl ausführen, wird eine Antwort generiert, die eine Liste der von Ihnen erstellten Befehlsausführungen sowie die Uhrzeit enthält, zu der die Ausführung begonnen und abgeschlossen wurde. Es enthält auch Statusinformationen und das `statusReason` Objekt, das zusätzliche Informationen zum Status enthält. ``` { "commandExecutions": [ { "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002", "executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24", "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f", "status": "TIMED_OUT", "createdAt": "2024-11-24T14:39:25.791000-08:00", "startedAt": "2024-11-24T14:39:25.791000-08:00" }, { "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002", "executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f", "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f", "status": "IN_PROGRESS", "createdAt": "2024-11-24T14:05:36.021000-08:00", "startedAt": "2024-11-24T14:05:36.021000-08:00" } ] } ``` Weitere Informationen zu den verschiedenen Status und den Gründen für den Status finden Sie unter[Status der Befehlsausführung](iot-remote-command-concepts.md#iot-command-execution-status). ## Löschen Sie die Ausführung eines Befehls Wenn Sie eine Befehlsausführung nicht mehr verwenden möchten, können Sie sie dauerhaft aus Ihrem Konto entfernen. **Anmerkung** Eine Befehlsausführung kann nur gelöscht werden, wenn sie einen Terminalstatus wie `SUCCEEDED``FAILED`, oder erreicht hat`REJECTED`. Dieser Vorgang kann nur mit der AWS IoT Core API oder der ausgeführt werden AWS CLI. Er ist nicht über die Konsole verfügbar. ### Beispiel einer IAM-Richtlinie Bevor Sie diesen API-Vorgang verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie Ihr Gerät autorisiert, diese Aktionen auszuführen. Im Folgenden finden Sie ein Beispiel für eine Richtlinie, die Ihr Gerät zur Ausführung der Aktion autorisiert. Ersetzen Sie in diesem Beispiel: + `Region`mit Ihrem AWS-Region, wie `us-east-1` zum Beispiel. + `AccountID`mit deiner AWS-Konto Nummer, wie*`123456789012`*. + `CommandID`mit der Kennung des Befehls, für den Sie die Ausführung löschen möchten. + `devices`entweder `thing` oder `client` je nachdem, ob Ihre Geräte als AWS IoT Dinge registriert wurden oder als MQTT-Clients spezifiziert sind. + `device-id`mit deinem AWS IoT `thing-name` oder`client-id`. ``` { "Effect": "Allow", "Action": [ "iot:DeleteCommandExecution" ], "Resource": [ "arn:aws:iot:region:account-id:command/command-id", "arn:aws:iot:region:account-id:devices/device-id" ] } ``` ### Löschen Sie ein Beispiel für die Befehlsausführung Das folgende Beispiel zeigt Ihnen, wie Sie einen Befehl mithilfe des `delete-command` AWS CLI Befehls löschen. Ersetzen Sie je nach Anwendung *``* durch die Kennung für die Befehlsausführung, die Sie löschen, und dann *``* durch den ARN Ihres Zielgeräts. ``` aws iot delete-command-execution \ --execution-id \ --target-arn ``` Wenn die API-Anfrage erfolgreich ist, generiert die Befehlsausführung den Statuscode 200. Sie können die `GetCommandExecution` API verwenden, um zu überprüfen, ob die Befehlsausführung in Ihrem Konto nicht mehr vorhanden ist. # Kennzeichnen einer Befehlsressource als veraltet Verwerfen Sie Befehle, um darauf hinzuweisen, dass sie veraltet sind und nicht verwendet werden sollten. Beispielsweise veraltete Befehle, die nicht mehr aktiv verwaltet werden, oder wenn neuere Befehle mit derselben ID, aber unterschiedlichen Payloads erstellt werden. ## Wesentliche Überlegungen Wichtige Überlegungen bei der Ablehnung von Befehlen: + Wenn Sie einen Befehl als veraltet markieren, wird er nicht gelöscht. Sie können den Befehl anhand seiner ID abrufen und zur Wiederverwendung wiederherstellen. + Der Versuch, neue Ausführungen mit veralteten Befehlen zu starten, generiert einen Fehler, wodurch die Verwendung veralteter Befehle verhindert wird. + Um einen veralteten Befehl auszuführen, müssen Sie ihn zunächst wiederherstellen. Nach der Wiederherstellung steht der Befehl für die reguläre Verwendung und Ausführung auf Zielgeräten zur Verfügung. + Wenn Sie einen Befehl während der Ausführung als veraltet markieren, werden diese weiterhin ausgeführt, bis sie abgeschlossen sind. Sie können den Ausführungsstatus immer noch abrufen. ## Eine Befehlsressource (Konsole) als veraltet kennzeichnen Um einen Befehl aus der Konsole als veraltet zu kennzeichnen, gehen Sie zum [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) der AWS IoT Konsole und führen Sie die folgenden Schritte aus. 1. **Wählen Sie den Befehl aus, den Sie verwerfen möchten, und wählen Sie dann unter **Aktionen** die Option Veraltet aus.** 1. **Bestätigen Sie, dass Sie den Befehl als veraltet markieren möchten, und wählen Sie dann Veraltet aus.** ## Eine Befehlsressource (CLI) als veraltet kennzeichnen Markieren Sie Befehle mithilfe der CLI als veraltet. `update-command` Sie müssen einen Befehl vor dem Löschen als veraltet markieren. Um einen veralteten Befehl zu verwenden, stellen Sie ihn zuerst wieder her. ``` aws iot update-command \ --command-id \ --deprecated ``` Wenn Sie beispielsweise den `ACSwitch` Befehl, den Sie im obigen Beispiel aktualisiert haben, als veraltet eingestuft haben, zeigt der folgende Code eine Beispielausgabe für die Ausführung des Befehls. ``` { "commandId": "turnOffAc", "deprecated": true, "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00" } ``` ## Überprüfen Sie den Zeitpunkt und den Status der Deprecation Verwenden Sie die `GetCommand` API, um festzustellen, ob ein Befehl veraltet ist und wann er zuletzt veraltet war. ``` aws iot get-command --command-id ``` Dieser Befehl generiert eine Antwort mit Befehlsinformationen, einschließlich Zeitstempeln für Erstellung und Verfall aus dem Feld mit der letzten Aktualisierung. Dies hilft dabei, die Gültigkeitsdauer eines Befehls zu bestimmen und festzustellen, ob er gelöscht oder wiederverwendet werden soll. Im Folgenden finden Sie ein Beispiel für eine Antwort auf den `turnOffAc` Befehl: ``` { "commandId": "turnOffAC", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/turnOffAC", "namespace": "AWS-IoT", "payload": { "content": "testPayload.json", "contentType": "application/json" }, "createdAt": "2024-03-23T00:50:10.095000-07:00", "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00", "deprecated": false } ``` ## Stellen Sie eine Befehlsressource wieder her Um den `ACSwitch` Befehl zu verwenden oder an Ihr Gerät zu senden, stellen Sie ihn zunächst wieder her. Um einen Befehl von der Konsole wiederherzustellen, rufen Sie den [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) der AWS IoT Konsole auf, wählen Sie den Befehl aus, den Sie wiederherstellen möchten, und wählen Sie dann unter **Aktionen** die Option **Wiederherstellen** aus. Verwenden Sie den AWS IoT Core API-Vorgang oder die `update-command` CLI AWS CLI, um einen Befehl mithilfe der `UpdateCommand` API oder der wiederherzustellen. Der folgende Code zeigt ein Beispiel für eine Anfrage und eine Antwort. ``` aws iot update-command \ --command-id --no-deprecated ``` Der folgende Code zeigt eine Beispielausgabe. ``` { "commandId": "ACSwitch", "deprecated": false, "lastUpdatedAt": "2024-05-09T23:17:21.954000-07:00" } ```