Starten und Überwachen von Befehlsausführungen

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 als Dinge oder verwenden Sie CreateThing. Finden Sie vorhandene Dinge über Thing Hub oder mithilfe von DescribeThing. Einzelheiten zur Registrierung finden Sie unter Dinge mit der Registrierung verwalten.

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.

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.

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 angezeigtTIMED_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:

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ändertTIMED_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.

Um mit der Ausführung des Befehls von der Konsole aus zu beginnen, rufen Sie die Command Hub-Seite der AWS IoT Konsole auf und führen Sie die folgenden Schritte aus.

Verwenden Sie den API-Vorgang für die StartCommandExecutionHTTP-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.

$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

Wenn das Payload-Format nicht JSON oder CBOR ist, wird im Folgenden das Format des Themas der Befehlsanfrage dargestellt.

$aws/commands/<devices>/<DeviceID>/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:

{
  "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 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":
    "<account-specific-prefix>-ats.iot.<region>.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:

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.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

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

Ersetzen Sie in diesem Beispiel:

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.

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.

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/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

In diesem Beispiel <DeviceID> ist dies die eindeutige Kennung Ihres Zielgeräts und <execution-id> die Kennung der Befehlsausführung auf dem Zielgerät. Das <PayloadFormat> kann JSON oder CBOR sein.

$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

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 unterStatus der Befehlsausführung.

Weitere Informationen zum TIMED_OUT Status finden Sie unterTimeout-Wert und TIMED_OUT Ausführungsstatus.

Überlegungen bei der Verwendung der UpdateCommandExecution API

Im Folgenden sind einige wichtige Überlegungen zur Verwendung der UpdateCommandExecution API aufgeführt.

UpdateCommandExecutionAPI-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"
        }
    }
}

Sie können eine Befehlsausführung mit einer der folgenden Methoden von der Konsole abrufen.

Verwenden Sie den HTTP-API-Vorgang der GetCommandExecution 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:

{
  "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:

aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <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 unterStatus der Befehlsausführung.

Der folgende Code zeigt eine Beispielantwort aus der API-Anfrage.

{
    "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"    
}

Sie können alle Befehlsausführungen von der Konsole aus mit einer der folgenden Methoden anzeigen.

Verwenden Sie den HTTP-API-Vorgang der ListCommandExecutions 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:

{
  "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 wurdentargetArn, oder Ausführungen für einen bestimmten Befehl, der mit dem angegeben wurde. commandArn

Ersetzen Sie in diesem Beispiel:

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<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 unterStatus der Befehlsausführung.

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:

{
  "Effect": "Allow",
  "Action": [
      "iot:DeleteCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Das folgende Beispiel zeigt Ihnen, wie Sie einen Befehl mithilfe des delete-command AWS CLI Befehls löschen. Ersetzen Sie je nach Anwendung <execution-id> durch die Kennung für die Befehlsausführung, die Sie löschen, und dann <target-arn> durch den ARN Ihres Zielgeräts.

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <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.