Befehle erstellen und verwalten

Die reservierten Themen zu Befehlen verwenden ein Format, das vom Typ des Payload-Formats abhängt.

Das Antwortthema des Befehls gibt ein Format zurück, das den Payload-Formattyp verwendet json oder von diesem cbor unabhängig ist. Das Antwortthema verwendet das folgende Format, wobei der Wert json oder <PayloadFormat> cbor angegeben werden muss.

$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

In den folgenden Abschnitten erfahren Sie, was beim Format der Befehlspayload zu beachten ist und wie Sie Befehle von der Konsole aus erstellen.

Format der Befehls-Payload

Die Nutzlast kann ein beliebiges Format Ihrer Wahl verwenden. Die maximale Größe der Payload darf 32 KB nicht überschreiten. Um sicherzustellen, dass das Gerät die Payload sicher und korrekt interpretieren kann, empfehlen wir Ihnen, den Payload-Formattyp anzugeben.

Sie geben den Payload-Formattyp mithilfe des type/subtype Formats an, z. B. oder. application/json application/cbor Standardmäßig wird es als application/octet-stream festgelegt. Informationen zu Payload-Formaten, die Sie angeben können, finden Sie unter Allgemeine MIME Typen.

Wie erstelle ich einen Befehl (Konsole)

Um einen Befehl von der Konsole aus zu erstellen, rufen Sie den Command Hub der AWS IoT Konsole auf und führen Sie die folgenden Schritte aus.

In diesem Abschnitt werden die API Operation auf der HTTP Steuerungsebene und der entsprechende AWS CLI Befehl beschrieben create-command, den Sie ausführen können, um eine Befehlsressource zu erstellen. CreateCommand

Payload des Befehls

Bei der Erstellung des Befehls müssen Sie eine Payload angeben. Die von Ihnen bereitgestellte Nutzlast ist Base64-codiert. Wenn Ihre Geräte den Befehl empfangen, kann die geräteseitige Logik die Nutzlast verarbeiten und die angegebenen Aktionen ausführen. Um sicherzustellen, dass Ihre Geräte den Befehl und die Payload korrekt empfangen, empfehlen wir Ihnen, den Payload-Inhaltstyp anzugeben.

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 CreateCommand Aktion auszuführen.

Ersetzen Sie in diesem Beispiel:

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:CreateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"          
    }
}

Beispiel für einen Befehl erstellen

Das folgende Beispiel zeigt, wie Sie einen Befehl erstellen können. Ersetzen Sie je nach Anwendung:

aws iot create-command \ 
    --command-id <command-id> \
    --display-name <display-name> \
    --description <description> \ 
    --namespace AWS-IoT \ 
    --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}'

Die Ausführung dieses Befehls generiert eine Antwort, die die ID und 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:ap-south-1:123456789012:command/LockDoor"
}

Um einen Befehl von der Konsole abzurufen, gehen Sie zum Command Hub 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.

Verwenden Sie die API Operation auf der GetCommandHTTPSteuerungsebene oder den get-command AWS CLI Befehl, um Informationen über eine Befehlsressource abzurufen. Sie müssen den Befehl bereits mit der CreateCommand API Anfrage oder dem erstellt haben create-commandCLI.

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 GetCommand Aktion auszuführen.

Ersetzen Sie in diesem Beispiel:

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:GetCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>: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 <command-id> durch den Bezeichner für den Befehl, für den Sie Informationen abrufen möchten. Sie können diese Informationen der Antwort des entnehmen create-commandCLI.

aws iot get-command --command-id <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:<region>:<account>: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
}

In der AWS IoT Konsole finden Sie die Liste der Befehle, die Sie erstellt haben, und deren Details, indem Sie zum Command Hub gehen.

Um die Befehle aufzulisten, die Sie erstellt haben, verwenden Sie die ListCommandsAPIOperation oder die list-commandsCLI.

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 ListCommands Aktion auszuführen.

Ersetzen Sie in diesem Beispiel:

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:ListCommands",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/*"          
    }
}

Führen Sie Befehle in Ihrem Kontobeispiel auf

Der folgende Befehl zeigt, wie Sie Befehle in Ihrem Konto auflisten können.

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

Um einen Befehl von der Konsole aus zu aktualisieren, rufen Sie den Command Hub der AWS IoT Konsole auf und führen Sie die folgenden Schritte aus.

Verwenden Sie die API Operation auf der UpdateCommandSteuerungsebene oder die update-command AWS CLI , um eine Befehlsressource zu aktualisieren. Damit API können Sie:

IAMBeispiel für eine 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 UpdateCommand Aktion auszuführen.

Ersetzen Sie in diesem Beispiel:

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:UpdateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>: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 API damit eine Befehlsressource als veraltet markieren oder wiederherstellen können, finden Sie unter. Aktualisieren Sie eine Befehlsressource (CLI)

Das Beispiel zeigt, wie Sie den Anzeigenamen und die Beschreibung eines Befehls aktualisieren können. Je nach Anwendung <command-id> ersetzen Sie ihn durch den Bezeichner für den Befehl, für den Sie Informationen abrufen möchten.

aws iot update-command \ 
    --command-id <command-id>    
    --displayname <display-name> \
    --description <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 <LockDoor> \ 
    --displayname <Secondary lock door> \
    --description <Locks doors to my home>

Die Ausführung dieses Befehls generiert die folgende Antwort.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "displayName": "Secondary lock door",
    "description": "Locks doors to my home",
    "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00"
}

Um einen Befehl von der Konsole zu löschen, rufen Sie den Command Hub der AWS IoT Konsole auf und führen Sie die folgenden Schritte aus.

Der Befehl wird zum Löschen markiert und nach 12 Stunden dauerhaft aus Ihrem Konto entfernt.

Verwenden Sie die API Operation auf der DeleteCommand HTTP Steuerungsebene oder den delete-command AWS CLI Befehl, um eine Befehlsressource zu löschen. Wenn die Löschaktion erfolgreich ist, wird ein Wert HTTP statusCode von 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 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 DeleteCommand Aktion auszuführen.

Ersetzen Sie in diesem Beispiel:

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:DeleteCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>: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 <command-id> ersetzen Sie ihn durch den Bezeichner für den Befehl, den Sie löschen möchten.

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

Wenn die API Anfrage erfolgreich ist, generiert der Befehl den Statuscode 202 oder 204. Sie können den verwenden GetCommandAPI, um zu überprüfen, ob der Befehl in Ihrem Konto nicht mehr vorhanden ist.