Starten und Überwachen von Befehlsausführungen

Geben Sie das Zielgerät an, das den Befehl empfangen und ausführen soll. Verwenden Sie einen Dingnamen für registrierte Geräte oder eine Client-ID für nicht registrierte Geräte. Nach Erhalt der Payload führt das Gerät den Befehl aus und führt die angegebenen Aktionen aus.

AWS IoT Objekt

Zielgeräte können Dinge sein, die in der AWS IoT Registrierung registriert sind. Dinge vereinfachen die Gerätesuche und -verwaltung.

Registriere Geräte auf der Connect-Geräteseite oder mithilfe von „Dinge“ CreateThing. Finden Sie vorhandene Dinge über Thing Hub oder mithilfe von DescribeThing. Einzelheiten zur Registrierung finden Sie unter Dinge mit der Registrierung https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry 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 startet ein Timer. Wenn das Gerät offline geht oder innerhalb des Timeouts keine Ergebnisse meldet, wird für die Ausführung ein Timeout mit Status angezeigtTIMED_OUT.

Standard: 10 Sekunden. Maximum: 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:

In diesem Fall erfolgt die Befehlsausführung nicht TIMED_OUT terminalgesteuert, wenn der Ausführungsstatus von aus der Cloud gemeldet wird. Ihr Gerät kann eine Antwort veröffentlichen, die den Status für jeden der Terminalstatus außer Kraft setzt:SUCCEEDED, FAILED oder. REJECTED Die Befehlsausführung wird dann zum Terminal und akzeptiert keine weiteren Aktualisierungen.

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 Ausführungsstatus des Befehls unverändertTIMED_OUT, aber das statusReason Objekt wird auf der Grundlage der vom Gerät gemeldeten Informationen aktualisiert. Die Befehlsausführung wird dann abgeschlossen, und es werden keine weiteren Aktualisierungen akzeptiert.

Verwendung 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 beispielsweise offline geht und Sie sicherstellen möchten, dass das Gerät den Befehl auch dann empfängt, wenn es vor Ablauf der Zeitüberschreitung 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 schlagen fehl. Um Befehle auszuführen, die länger als 60 Minuten dauern, können Sie eine Verlängerung der Ablaufzeit der persistenten Sitzung anfordern.

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

Verwenden Sie die API-Operation für die StartCommandExecution HTTP-Datenebene, um eine Befehlsausführung zu starten. Die API-Anfrage und -Antwort werden durch die 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 zum Antwortthema des Befehls veröffentlicht. Bei einem benutzerdefinierten Antwortcode können Anwendungscodes, die Sie besitzen, die Antwortnachricht verarbeiten und das Ergebnis an senden AWS IoT.

Wenn Ihre Geräte das Thema für die Befehlsanfrage abonniert haben, veröffentlicht die StartCommandExecution API die Payload-Nachricht zum Thema. Die Payload kann ein beliebiges Format Ihrer Wahl verwenden. Weitere Informationen finden Sie unter Nutzlast des Befehls.

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

Wenn das Payload-Format nicht JSON oder CBOR ist, wird im Folgenden das Format des Anforderungsthemas für Befehle angezeigt.

$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 Berechtigung zum Ausführen der Aktion gewährt. 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 AWS IoT im IAM-Benutzerhandbuch unter Bedingungsschlüssel für. 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 (IPv4 und IPv6) verwenden, verwenden Sie die. iot:Data-ATS Der iot:Jobs Endpunkt ist nur für IPv4 vorgesehen. 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 Beispielantwort unten gezeigt.

{
    "endpointAddress":
    "<account-specific-prefix>-ats.iot.<region>.api.com"
}

Starten Sie ein Beispiel für die Befehlsausführung (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 Befehlsausführungsstatus, 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 zur Ausführung dieser Aktionen autorisiert. Im Folgenden wird eine Beispielrichtlinie gezeigt, die Ihr Gerät zur Ausführung der Aktion autorisiert. Weitere Beispiele für IAM-Richtlinien, die dem Benutzer die Berechtigung zum Ausführen der UpdateCommandExecution MQTT-Aktion gewä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 eine IoT-Sache

Der folgende Code zeigt ein Beispiel für eine Geräterichtlinie bei der Verwendung AWS IoT eines Dings.

Nachdem die Befehlsausführung im Anforderungsthema 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 das 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 jede der folgenden Statusaktualisierungen für die 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 finden Sie einige wichtige Überlegungen bei der Verwendung der UpdateCommandExecution API.

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, in diesem Fall beispielsweise 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 eine Befehlsausführung abzurufen. Sie müssen diesen Befehl bereits mit 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 Berechtigung zum Ausführen der Aktion gewährt. 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, wie Sie Informationen zu einem Befehl abrufen, der mit dem start-command-execution AWS CLI Befehl ausgeführt wurde. Das folgende Beispiel zeigt, wie Sie Informationen zu einem 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 den ARN der Befehlsausführung, den Ausführungsstatus und die Uhrzeit, zu der die Ausführung begonnen und abgeschlossen wurde, enthält. Es stellt auch ein statusReason Objekt bereit, das zusätzliche Informationen zum Status enthält. Weitere Informationen zu den verschiedenen Status und dem Grund für den Status finden Sie unterStatus der Befehlsausführung.

Der folgende Code zeigt ein Beispiel für eine Antwort auf die API-Anforderung.

{
    "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 sehen.

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 Berechtigung zum Ausführen der Aktion gewährt. ListCommandExecutions

Ersetzen Sie in diesem Beispiel:

{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

Beispiel für die Ausführung von Befehlen auflisten

Das folgende Beispiel zeigt Ihnen, wie Sie Befehlsausführungen in Ihrem auflisten. AWS-Konto

Wenn Sie den Befehl ausführen, müssen Sie angeben, ob die Liste so gefiltert werden soll, dass nur Befehlsausführungen angezeigt werden, die für ein bestimmtes Gerät mithilfe von 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, zu der die Ausführung der Ausführungen begonnen und abgeschlossen wurde, enthält. 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 dem Grund 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 wird eine Beispielrichtlinie gezeigt, 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, wie Sie einen Befehl mithilfe des delete-command AWS CLI Befehls löschen. Ersetzen Sie je nach Anwendung <execution-id> durch den Bezeichner für die Befehlsausführung, den Sie löschen, und den <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 existiert.