Befehlsausführungen starten und überwachen

Wenn Sie den Befehl ausführen möchten, müssen Sie das Zielgerät angeben, das den Befehl empfangen und die angegebenen Anweisungen ausführen soll. Das Zielgerät kann entweder ein AWS IoT Ding oder die Client-ID sein, falls das Gerät nicht in der AWS IoT Registrierung registriert wurde. Nach Erhalt der Befehlspayload kann das Gerät mit der Ausführung des Befehls beginnen und die angegebenen Aktionen ausführen.

AWS IoT Sache

Das Zielgerät für den Befehl kann ein AWS IoT Ding sein, das Sie in der AWS IoT Ding-Registrierung registriert haben. Dinge AWS IoT , die darin enthalten sind, erleichtern die Suche und Verwaltung Ihrer Geräte.

Sie können Ihr Gerät als eine Sache registrieren, wenn Sie Ihr Gerät über die Seite „Gerät verbinden“ mit verbinden oder das verwenden CreateThingAPI. AWS IoT Sie finden ein vorhandenes Ding, für das Sie den Befehl ausführen möchten, auf der Thing Hub-Seite der AWS IoT Konsole oder mithilfe von DescribeThingAPI. Informationen dazu, wie Sie Ihr Gerät als AWS IoT Ding registrieren, finden Sie unter Dinge mit der Registrierung verwalten.

Client-ID

Wenn Ihr Gerät nicht als Ding bei registriert wurde AWS IoT, können Sie stattdessen die Client-ID verwenden.

Die Client-ID ist eine eindeutige Kennung, die Sie Ihrem Gerät oder Client zuweisen. Die Client-ID ist im MQTT Protokoll definiert und kann alphanumerische Zeichen, Unterstriche oder Bindestriche enthalten. Sie muss für jedes Gerät, mit dem eine Verbindung hergestellt wird, eindeutig sein. AWS IoT

Die Client-ID ist in der Regel die MQTT Client-ID, mit der Ihre Geräte eine Verbindung herstellen AWS IoT Core können. Diese ID wird verwendet AWS IoT , um jedes spezifische Gerät zu identifizieren und Verbindungen und Abonnements zu verwalten.

Das Timeout gibt die Dauer in Sekunden an, innerhalb derer Ihr Gerät das Ergebnis der Befehlsausführung bereitstellen kann.

Nachdem Sie eine Befehlsausführung erstellt haben, wird ein Timer gestartet. Wenn das Gerät offline gegangen ist oder das Ausführungsergebnis nicht innerhalb der Timeoutdauer gemeldet werden konnte, wird die Befehlsausführung unterbrochen und der Ausführungsstatus wird als TIMED_OUT angezeigt.

Dieses Feld ist optional und wird standardmäßig auf 10 Sekunden gesetzt, wenn Sie keinen Wert angeben. Sie können das Timeout auch auf einen Höchstwert von 12 Stunden konfigurieren.

Timeout-Wert und TIMED_OUT Ausführungsstatus

Ein Timeout kann sowohl von der Cloud als auch vom Gerät gemeldet werden.

Nachdem der Befehl an das Gerät gesendet wurde, startet ein Timer. Wenn innerhalb der angegebenen Timeout-Dauer keine Antwort vom Gerät empfangen wurde, wie oben beschrieben. In diesem Fall legt die Cloud den Befehlsausführungsstatus TIMED_OUT mit dem Ursachencode auf fest$NO_RESPONSE_FROM_DEVICE.

Dies kann in einem der folgenden Fälle passieren.

Wenn in diesem Fall der Ausführungsstatus von aus der Cloud gemeldet TIMED_OUT wird, erfolgt die Befehlsausführung nicht terminalgebunden. Ihr Gerät kann eine Antwort veröffentlichen, die den Status eines beliebigen Terminalstatus,SUCCEEDED, FAILED oder überschreibt. REJECTED Die Befehlsausführung erfolgt jetzt im 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, das statusReason Objekt wird TIMED_OUT jedoch auf der Grundlage der vom Gerät gemeldeten Informationen aktualisiert. Die Befehlsausführung wird nun zum Terminal und es werden keine weiteren Aktualisierungen akzeptiert.

Verwenden MQTT persistenter Sitzungen

Sie können MQTT persistente 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 der Ablauf einer MQTT persistenten 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 sie können fehlschlagen. Um Befehle auszuführen, die länger als 60 Minuten dauern, können Sie eine Verlängerung der Ablaufzeit für persistente Sitzungen beantragen.

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 die API Operation auf der StartCommandExecutionHTTPDatenebene, um eine Befehlsausführung zu starten. Die API Anfrage und die Antwort werden anhand der Befehlsausführungs-ID korreliert. 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, StartCommandExecution API wird die Payload-Meldung zum Thema veröffentlicht. 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 istCBOR, wird im Folgenden das Format des Themas zur Befehlsanfrage angezeigt.

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

Beispiel für eine Richtlinie IAM

Bevor Sie diesen API Vorgang verwenden, stellen Sie sicher, dass Ihre IAM Richtlinie Sie autorisiert, diese Aktion auf dem Gerät durchzuführen. Das folgende Beispiel zeigt eine IAM Richtlinie, die dem Benutzer die Erlaubnis erteilt, die StartCommandExecution Aktion auszuführen.

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

Besorgen Sie sich einen kontospezifischen Endpunkt auf der Datenebene

Bevor Sie den API Befehl ausführen, müssen Sie den kontospezifischen Endpunkt für den Endpunkt URL abrufen. iot:Jobs Wenn Sie z. B. den folgenden Befehl ausführen:

aws iot describe-endpoint --endpoint-type iot:Jobs

Es wird der kontospezifische Endpunkt zurückgegeben, URL wie in der folgenden Beispielantwort gezeigt.

{
    "endpointAddress": "<account-specific-prefix>.jobs.iot.<region>.amazonaws.com"
}

Beispiel für eine Befehlsausführung starten ()AWS CLI

Das folgende Beispiel zeigt Ihnen, wie Sie die Ausführung eines Befehls mithilfe des start-command-execution AWS CLI Befehls starten.

Ersetzen Sie in diesem Beispiel:

aws iot-jobs-data start-command-execution \ 
    --command-arn <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --executionTimeoutSeconds 900

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 Durchführung der Aktion autorisiert. Weitere IAM Beispielrichtlinien, die dem Benutzer die Erlaubnis geben, die UpdateCommandExecution Aktion auszuführen, finden Sie unterBeispiele zu den Verbinden- und Veröffentlichen-Richtlinien.

Ersetzen Sie in diesem Beispiel:

IAMBeispielrichtlinie für 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}"
    }
  ]
}

IAMBeispielrichtlinie für IoT-Sache

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

Nachdem die Befehlsausführung unter dem Thema der Anfrage eingegangen ist, verarbeitet das Gerät den Befehl. Anschließend aktualisiert es UpdateCommandExecution API den Status und das Ergebnis der Befehlsausführung auf das folgende Antwortthema.

$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 seinCBOR.

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

Das Gerät hat Aktualisierungen des Ausführungsstatus gemeldet

Ihre Geräte können den verwendenAPI, um jede 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 von UpdateCommandExecution API

Im Folgenden sind einige wichtige Überlegungen bei der Verwendung von aufgeführt UpdateCommandExecutionAPI.

UpdateCommandExecutionAPIBeispiel

Der folgende Code zeigt ein Beispiel dafür, wie Ihr Gerät den UpdateCommandExecution API Ausführungsstatus melden kann, das statusReason Feld, um zusätzliche Informationen über den 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 die HTTP API Operation auf der GetCommandExecution AWS IoT Core Steuerungsebene, um Informationen über die Ausführung eines Befehls abzurufen. Sie müssen diesen Befehl bereits mit der StartCommandExecution API Operation ausgeführt haben.

Beispiel für eine IAM Richtlinie

Bevor Sie diesen API Vorgang verwenden, stellen Sie sicher, dass Ihre IAM Richtlinie Sie autorisiert, diese Aktion auf dem Gerät durchzuführen. Das folgende Beispiel zeigt eine IAM Richtlinie, die dem Benutzer die Erlaubnis erteilt, die GetCommandExecution Aktion auszuführen.

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

Wenn Sie diesen Befehl ausführen, wird eine Antwort generiert, die Informationen über die Ausführung ARN des Befehls, den Ausführungsstatus und den Zeitpunkt enthält, zu dem die Ausführung gestartet und abgeschlossen wurde. 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 ein Beispiel für eine Antwort auf die API Anfrage.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:ap-south-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 die HTTP API Operation auf der ListCommandExecutions AWS IoT Core Steuerungsebene, um alle Befehlsausführungen in Ihrem Konto aufzulisten.

Beispiel für eine Richtlinie IAM

Bevor Sie diesen API Vorgang verwenden, stellen Sie sicher, dass Ihre IAM Richtlinie Sie autorisiert, diese Aktion auf dem Gerät durchzuführen. Das folgende Beispiel zeigt eine IAM Richtlinie, die dem Benutzer die Erlaubnis erteilt, die ListCommandExecutions Aktion auszuführen.

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 Durchfü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 ihn je nach Anwendung <execution-id> durch die Kennung für die Befehlsausführung, die Sie löschen, und <target-arn> durch die 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 den verwenden, GetCommandExecution API um zu überprüfen, ob die Befehlsausführung in Ihrem Konto nicht mehr vorhanden ist.