Befehlsausführungen starten und überwachen

Nachdem Sie eine Befehlsressource erstellt haben, können Sie eine Befehlsausführung auf dem Zielfahrzeug starten. Sobald das Fahrzeug mit der Ausführung des Befehls beginnt, kann es damit beginnen, das Ergebnis der Befehlsausführung zu aktualisieren und Statusaktualisierungen und Ergebnisinformationen in den reservierten MQTT-Themen zu veröffentlichen. Sie können dann den Status der Befehlsausführung abrufen und den Status der Ausführungen in Ihrem Konto überwachen.

In diesem Thema wird gezeigt, wie Sie mithilfe der AWS CLI oder der AWS FleetWise IoT-Konsole einen Befehl an Ihr Fahrzeug senden können. Außerdem erfahren Sie, wie Sie den Status der Befehlsausführung überwachen und aktualisieren können.

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

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

aws iot-jobs-data start-command-execution \ 
    --command-arn command-arn \ 
    --target-arn target-arn \
    --execution-timeout-seconds 30 \
    --endpoint-url endpoint-url \ 
    --parameters '[
        {
            "name": name, 
            "value": value
        }
   ]'

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

timeout_ms: 9000000
issued_timestamp_ms: 1723847831317

Ergebnis der Befehlsausführung aktualisieren

Um den Status der Befehlsausführung zu aktualisieren, muss Ihr Gerät eine MQTT-Verbindung hergestellt und das folgende Thema zur Befehlsanfrage abonniert haben.

Ersetzen Sie in diesem Beispiel durch die eindeutige Kennung Ihres Zielgeräts, <device-id> bei der es sich um den Namen VehicleId oder den Namen der Sache handeln kann, und <execution-id> durch die Kennung für die Befehlsausführung.

// Request topic
$aws/devices/<DeviceID>/command_executions/+/request/protobuf

// Response topics (Optional)
$aws/devices/<DeviceID>/command_executions/<ExecutionId>/response/accepted/protobuf
$aws/devices/<DeviceID>/command_executions/<ExecutionId>/response/rejected/protobuf

Ihr Gerät kann eine Nachricht zum Thema Befehlsantwort veröffentlichen. Nach der Verarbeitung des Befehls wird eine protobuf-kodierte Antwort zu diesem Thema gesendet. Das <DeviceID> Feld muss mit dem entsprechenden Feld im Thema der Anfrage übereinstimmen.

$aws/devices/<DeviceID>/command_executions/<ExecutionId>/response/<PayloadFormat>

Nachdem Ihr Gerät eine Antwort zu diesem Thema veröffentlicht hat, können Sie die aktualisierten Statusinformationen mithilfe der GetCommandExecution API abrufen. Der Status der Befehlsausführung kann einer der hier aufgeführten sein.

Beachten Sie, dass es sich bei der Ausführung eines Befehls in einem der Status SUCCEEDEDFAILED, und um REJECTED ein Terminal handelt und der Status vom Gerät gemeldet wird. Wenn ein Befehl terminalförmig ausgeführt wird, bedeutet dies, dass der Status oder die zugehörigen Felder nicht weiter aktualisiert werden. Ein TIMED_OUT Status kann vom Gerät oder der Cloud gemeldet werden. Wenn es von der Cloud gemeldet wird, kann das Gerät später eine Aktualisierung des Felds für den Statusgrund vornehmen.

Im Folgenden wird beispielsweise eine MQTT-Beispielnachricht gezeigt, die vom Gerät veröffentlicht wurde.

{
    "deviceId": "",
    "executionId": "",
    "status": "CREATED",
    "statusReason": {
        "reasonCode": "",
        "reasonDescription": ""
    }
}

Ein Beispiel, das zeigt, wie Sie den AWS IoT Core MQTT-Testclient verwenden können, um die Themen zu abonnieren und die Meldungen zur Befehlsausführung zu sehen, finden Sie unter Befehlsaktualisierungen mit dem MQTT-Testclient anzeigen im AWS IoT Core Entwicklerhandbuch.

Holen Sie sich die Befehlsausführung

Sie können den API-Vorgang der GetCommandExecution AWS IoT Steuerungsebene verwenden, um Informationen über die Ausführung eines Befehls abzurufen. Sie müssen diesen Befehl bereits mithilfe der StartCommandExecution API-Operation ausgeführt haben.

Führen Sie den folgenden Befehl aus, um die Metadaten eines ausgeführten Befehls abzurufen.

aws iot get-command-execution --execution-id execution-id \ 
    --target-arn target-arn

Die GetCommandExecution API-Operation gibt eine Antwort zurück, die Informationen über den ARN der Befehlsausführung, den Ausführungsstatus und den Zeitpunkt enthält, zu dem der Befehl ausgeführt wurde und wann er abgeschlossen wurde. Der folgende Code zeigt eine Beispielantwort aus der API-Anfrage.

Um zusätzlichen Kontext zum Status der einzelnen Befehlsausführungen bereitzustellen, stellt die Befehlsfunktion ein statusReason Objekt bereit. Das Objekt enthält zwei Felder reasonCode undreasonDescription. Mithilfe dieser Felder können Ihre Geräte zusätzliche Informationen über den Status der Befehlsausführung bereitstellen. Diese Informationen überschreiben alle reasonCode StandardwertereasonDescription, die aus der Cloud gemeldet werden.

Um diese Informationen zu melden, können Ihre Geräte die aktualisierten Statusinformationen in der Cloud veröffentlichen. Wenn Sie dann den Status der Befehlsausführung mithilfe der GetCommandExecution API abrufen, werden Ihnen die neuesten Statuscodes angezeigt.

{
    "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/myFrontDoor",
    "status": "SUCCEEDED",
    "statusReason": {
        "reasonCode": "65536",
        "reasonDescription": "SUCCESS"
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "completedAt": "2024-03-23T00:50:10.095000-07:00",
    "Parameters": '{
         "$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode":          
         { "B": true }
    }' 
}

Listet die Befehlsausführungen in Ihrem Konto auf

Verwenden Sie den HTTP-API-Vorgang der ListCommandExecutions AWS IoT Core Steuerungsebene, um alle Befehlsausführungen in Ihrem Konto aufzulisten. Das Beispiel verwendet das AWS CLI.

Überlegungen beim Auflisten von Befehlsausführungen

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

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 über den 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"
        }
    ]
}

Löscht eine Befehlsausführung

Wenn Sie eine Befehlsausführung nicht mehr verwenden möchten, können Sie sie dauerhaft aus Ihrem Konto entfernen.

Das folgende Beispiel zeigt Ihnen, wie Sie eine Befehlsausführung mithilfe des delete-command-execution AWS CLI Befehls löschen. <execution-id>Ersetzen Sie es durch den Bezeichner der Befehlsausführung, die Sie löschen möchten.

aws iot delete-command-execution --execution-id <execution-id>

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.