Crea e gestisci i comandi - AWS IoT Core
Crea una risorsa di comandoRecuperare informazioni su un comandoElenca i comandi nel tuo Account AWSAggiornare una risorsa di comandoDeprecare o ripristinare una risorsa di comandoEliminare una risorsa di comando

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Crea e gestisci i comandi

Usa AWS IoT Device Management i comandi per configurare azioni remote riutilizzabili o inviare istruzioni immediate ai dispositivi. Crea e gestisci i comandi dalla AWS IoT console o utilizzando. AWS CLI

Crea una risorsa di comando

Fornisci le seguenti informazioni durante la creazione di un comando:

  • Informazioni generali

    Fornisci un ID di comando univoco per identificare il comando quando lo esegui sui dispositivi di destinazione. Specificate facoltativamente un nome visualizzato, una descrizione e tag per la gestione.

  • Carico utile

    Per i comandi statici, fornite un payload che definisca le azioni del dispositivo. Specificate il tipo di formato Payload per una corretta interpretazione del dispositivo.

    Per i comandi dinamici, vedete l'attributo del modello Payload.

  • Modello di payload

    Per i comandi dinamici, fornisci un PayloadTemplate con segnaposto e parametri. Fornisci e condizioni opzionali. defaultValue AWS IoT Device Management I comandi sostituiscono i segnaposto in fase di esecuzione. I parametri mancanti utilizzano il loro DefaultValue. Tutti i valori devono soddisfare condizioni definite.

    Sono supportati i seguenti tipi di segnaposto con distinzione tra maiuscole e minuscole:

    • ${aws:iot:commandexecution::parameter:parameter1}— Un segnaposto per il valore di un parametro con il nome. parameter1

    • ${aws:iot:commandexecution::executionTimeoutSec}— Un segnaposto per il parametro di timeout di esecuzione del comando fornito in fase di esecuzione.

Comandi riservati Gli argomenti utilizzano un formato basato sul tipo di formato Payload.

  • Per i application/json nostri tipi di application/cbor contenuto, usa questo argomento della richiesta:

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

  • Per altri tipi di contenuto o formati non specificati, usa questo argomento della richiesta. Il formato Payload viene visualizzato nell'intestazione del messaggio MQTT.

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

L'argomento di risposta ai comandi utilizza json o cbor formatta indipendentemente dal tipo di payload. <PayloadFormat>deve essere json ocbor:

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

Le sezioni seguenti descrivono le considerazioni sul formato Payload e la creazione di comandi dalla console.

Formato statico del payload dei comandi

Il payload supporta qualsiasi formato fino a 32 KB. Specificate il tipo di formato Payload per un'interpretazione sicura e corretta del dispositivo.

Specificate il tipo di formato Payload utilizzando il type/subtype formato (ad esempio, application/json oapplication/cbor). Default: application/octet-stream. Vedi Tipi MIME comuni per i formati supportati.

Formato dinamico del payload dei comandi

Il PayloadTemplate deve essere un JSON valido con almeno un segnaposto, fino a 32 KB.

Per il AwsJsonSubstitution preprocessore, AWS IoT Device Management Commands invia notifiche in formato JSON o CBOR in base alla configurazione del preprocessore.

Come creare un comando (console)

Per creare un comando dalla console, vai su Command Hub e segui questi passaggi:

  1. Scegli il comando Crea.

  2. Specificate un ID di comando univoco.

  3. (Facoltativo) Specificate il nome visualizzato, la descrizione e i tag.

  4. Carica il file Payload contenente le azioni del dispositivo. Specificate il tipo di formato Payload per una corretta interpretazione del dispositivo.

  5. (Facoltativo) Per i modelli di payload JSON con segnaposto, i parametri vengono precompilati nella tabella in linea per la modifica.

  6. (Facoltativo) Configura il tipo di valore del parametro (obbligatorio), il valore predefinito e le condizioni.

  7. Scegliete il comando Crea.

Usa il comando CreateCommandAPI o create-commandCLI per creare un comando.

Payload del comando

Fornisci un modello di payload o payload statico. I payload statici sono codificati in base 64. Per i modelli di payload, il payload finale viene generato in fase di esecuzione utilizzando i valori dei parametri. I dispositivi elaborano il payload ed eseguono azioni specificate. Specificate il tipo di contenuto Payload per la corretta ricezione del dispositivo.

Nota

I payload non possono essere modificati dopo la creazione del comando. Crea un nuovo comando per modificare il payload.

Policy IAM di esempio

Prima di utilizzare questa operazione API, assicurati che la tua policy IAM ti autorizzi a eseguire questa azione sul dispositivo. L'esempio seguente mostra una policy IAM che consente l'autorizzazione dell'utente a eseguire l'CreateCommandazione.

In questo esempio, sostituisci:

  • regioncon il tuo Regione AWS, ad esempious-east-1.

  • account-idcon il tuo Account AWS numero, ad esempio123456789012.

  • command-idcon un identificatore univoco per l'ID del AWS IoT comando, ad esempioLockDoor. Se desideri inviare più di un comando, puoi specificare questi comandi nella sezione Resource della policy IAM.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:CreateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Esempio di creazione di comandi statici

L'esempio seguente mostra come creare un comando statico. A seconda dell'applicazione, sostituisci:

  • <command-id>con un identificatore univoco per il comando. Ad esempio, per bloccare la porta di casa, puoi specificareLockDoor. Ti consigliamo di utilizzare l'UUID. Puoi anche usare caratteri alfanumerici, «-» e «_».

  • (Facoltativo) <display-name> e<description>, che sono campi facoltativi che è possibile utilizzare per fornire un nome descrittivo e una descrizione significativa per il comando, ad esempio. Lock the doors of my home

  • namespace, che è possibile utilizzare per specificare lo spazio dei nomi del comando. Deve esserlo. AWS-IoT Per informazioni sull'utilizzo di questa funzionalità per AWS IoT FleetWise, consulta Comandi remoti

  • payloadcontiene informazioni sul payload che si desidera utilizzare durante l'esecuzione del comando e sul tipo di contenuto.

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

L'esecuzione di questo comando genera una risposta che contiene l'ID e l'ARN (Amazon resource name) del comando. Ad esempio, se hai specificato il LockDoor comando durante la creazione, di seguito viene mostrato un esempio di output dell'esecuzione del comando.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor"
}

Esempio di creazione dinamica di comandi

L'esempio seguente mostra come creare un comando dinamico. A seconda dell'applicazione, sostituisci:

  • <command-id>con un identificatore univoco per il comando. Ad esempio, per impostare lo stato di alimentazione della luce, è possibile specificareLight_Power_Status. Ti consigliamo di utilizzare l'UUID. Puoi anche usare caratteri alfanumerici, «-» e «_».

  • (Facoltativo) <display-name> e<description>, che sono campi facoltativi che è possibile utilizzare per fornire un nome descrittivo e una descrizione significativa per il comando, ad esempio. Turn a light ON or OFF

  • namespace, che è possibile utilizzare per specificare lo spazio dei nomi del comando. Deve esserlo. AWS-IoT Per informazioni sull'utilizzo di questa funzionalità per AWS IoT FleetWise, consulta Comandi remoti

  • payloadTemplatecontiene il modello di playload in formato JSON con segnaposto.

  • preprocessorcontiene la configurazione per il preprocessore che determina come il PayloadTemplate deve essere elaborato.

  • mandatoryParametercontiene i parametri corrispondenti ai segnaposto nel PayloadTemplate, il loro tipo, i valori predefiniti e le condizioni.

aws iot create-command \
    --command-id Light_Power_Status \
    --description "Turn a light ON or OFF" \
    --namespace AWS-IoT \
    --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \
    --preprocessor awsJsonSubstitution={outputFormat=JSON} \
    --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]"

L'esecuzione di questo comando genera una risposta che contiene l'ID e l'ARN (Amazon resource name) del comando. Ad esempio, se hai specificato il Light_Power_Status comando durante la creazione, di seguito viene mostrato un esempio di output dell'esecuzione del comando.

{
    "commandId": "Light_Power_Status",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status"
}

Recuperare informazioni su un comando

Dopo aver creato un comando, è possibile recuperare informazioni su di esso dalla AWS IoT console e utilizzare il. AWS CLIÈ possibile ottenere le seguenti informazioni.

  • L'ID del comando, il nome della risorsa Amazon (ARN), qualsiasi nome visualizzato e descrizione che hai specificato per il comando.

  • Lo stato del comando, che indica se un comando è disponibile per l'esecuzione sul dispositivo di destinazione o se è obsoleto o eliminato.

  • Il payload o il payloadTemplate che hai fornito.

  • Il preprocessore che hai fornito.

  • I parametri obbligatori che hai fornito.

  • L’ora in cui il comando è stato creato e aggiornato l’ultima volta.

Per recuperare un comando dalla console, vai al Command Hub della AWS IoT console, quindi scegli il comando che hai creato per visualizzarne i dettagli.

Oltre ai dettagli del comando, puoi visualizzare la cronologia dei comandi, che fornisce informazioni sulle esecuzioni del comando sul dispositivo di destinazione. Dopo aver eseguito questo comando sul dispositivo, puoi trovare informazioni sulle esecuzioni in questa scheda.

Utilizzate l'operazione API del piano di controllo GetCommandHTTP o il get-command AWS CLI comando per recuperare informazioni su una risorsa di comando. Devi aver già creato il comando utilizzando la richiesta CreateCommand API o la create-command CLI.

Policy IAM di esempio

Prima di utilizzare questa operazione API, assicurati che la tua policy IAM ti autorizzi a eseguire questa azione sul dispositivo. L'esempio seguente mostra una policy IAM che consente l'autorizzazione dell'utente a eseguire l'GetCommandazione.

In questo esempio, sostituisci:

  • regioncon il tuo Regione AWS, ad esempious-east-1.

  • account-idcon il tuo Account AWS numero, ad esempio123456789023.

  • command-idcon il tuo identificatore di comando AWS IoT univoco, ad esempio LockDoor oLight_Power_Status. Se desideri recuperare più di un comando, puoi specificare questi comandi nella sezione Resource della policy IAM.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:GetCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Recupera un esempio di comando ()AWS CLI

L'esempio seguente mostra come recuperare informazioni su un comando utilizzando il. get-command AWS CLI A seconda dell'applicazione, <command-id> sostituiscilo con l'identificatore del comando per il quale desideri recuperare le informazioni. È possibile ottenere queste informazioni dalla risposta della create-command CLI.

aws iot get-command --command-id <command-id>

L'esecuzione di questo comando genera una risposta che contiene informazioni sul comando, sul payload e sull'ora in cui è stato creato e aggiornato l'ultima volta. Fornisce inoltre informazioni che indicano se un comando è obsoleto o viene eliminato.

Ad esempio, il codice seguente mostra una risposta di esempio. 

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

Elenca i comandi nel tuo Account AWS

Dopo aver creato i comandi, puoi visualizzare i comandi che hai creato nel tuo account. Nell'elenco puoi trovare informazioni su:

  • L'ID del comando e l'eventuale nome visualizzato specificato per i comandi.

  • Il nome della risorsa Amazon (ARN) dei comandi.

  • Lo stato del comando che indica se i comandi sono disponibili per l'esecuzione sul dispositivo di destinazione o se sono obsoleti.

    Nota

    L'elenco non mostra quelli che vengono eliminati dal tuo account. Se i comandi sono in attesa di eliminazione, puoi comunque visualizzarne i dettagli utilizzando il relativo ID di comando.

  • L'ora in cui i comandi sono stati creati e aggiornati l'ultima volta.

Nella AWS IoT console, puoi trovare l'elenco dei comandi che hai creato e i relativi dettagli accedendo al Command Hub.

Per elencare i comandi che hai creato, utilizza l'operazione ListCommandsAPI o la list-commandsCLI.

Policy IAM di esempio

Prima di utilizzare questa operazione API, assicurati che la tua policy IAM ti autorizzi a eseguire questa azione sul dispositivo. L'esempio seguente mostra una policy IAM che consente l'autorizzazione dell'utente a eseguire l'ListCommandsazione.

In questo esempio, sostituisci:

  • regioncon il tuo Regione AWS, ad esempious-east-1.

  • account-idcon il tuo Account AWS numero, ad esempio123456789012.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:ListCommands",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/*"
    }
}

Elenca i comandi nell'esempio del tuo account

Il comando seguente mostra come elencare i comandi nel tuo account.

aws iot list-commands --namespace "AWS-IoT"

L'esecuzione di questo comando genera una risposta che contiene un elenco di comandi creati dall'utente, l'ora in cui i comandi sono stati creati e l'ultimo aggiornamento. Fornisce inoltre informazioni sullo stato del comando, che indicano se un comando è obsoleto o è disponibile per l'esecuzione sul dispositivo di destinazione. Per ulteriori informazioni sui diversi stati e sul motivo dello stato, vedere. Stato di esecuzione del comando

Aggiornare una risorsa di comando

Dopo aver creato un comando, è possibile aggiornare il nome visualizzato e la descrizione del comando.

Nota

Il payload del comando non può essere aggiornato. Per aggiornare queste informazioni o utilizzare un payload modificato, è necessario creare un nuovo comando.

Per aggiornare un comando dalla console, vai al Command Hub della AWS IoT console ed esegui i seguenti passaggi.

  1. Per aggiornare una risorsa di comando esistente, scegli il comando che desideri aggiornare, quindi in Azioni scegli Modifica.

  2. Specificate il nome visualizzato e la descrizione che desiderate utilizzare e tutte le coppie nome-valore come tag per il comando.

  3. Scegliete Modifica per salvare il comando con le nuove impostazioni.

Utilizza l'operazione API del piano di UpdateCommandcontrollo o update-command AWS CLI per aggiornare una risorsa di comando. Utilizzando questa API, puoi:

  • Modificare il nome visualizzato e la descrizione di un comando creato.

  • Deprecate una risorsa di comando o ripristinate un comando che è già stato obsoleto.

Policy IAM di esempio

Prima di utilizzare questa operazione API, assicurati che la tua policy IAM ti autorizzi a eseguire questa azione sul dispositivo. L'esempio seguente mostra una policy IAM che consente l'autorizzazione dell'utente a eseguire l'UpdateCommandazione.

In questo esempio, sostituisci:

  • regioncon il tuo Regione AWS, ad esempious-east-1.

  • account-idcon il tuo Account AWS numero, ad esempio123456789012.

  • command-idcon il tuo identificatore di comando AWS IoT univoco, ad esempioLockDoor. Se desideri recuperare più di un comando, puoi specificare questi comandi nella sezione Resource della policy IAM.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:UpdateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Aggiorna le informazioni su un comando examples ()AWS CLI

L'esempio seguente mostra come aggiornare le informazioni su un comando utilizzando il update-command AWS CLI comando. Per informazioni su come utilizzare questa API per deprecare o ripristinare una risorsa di comando, consulta. Aggiornare una risorsa di comando (CLI)

L'esempio mostra come aggiornare il nome visualizzato e la descrizione di un comando. A seconda dell'applicazione, <command-id> sostituiscilo con l'identificatore del comando per il quale desideri recuperare le informazioni.

aws iot update-command \ 
    --command-id <command-id>    
    --displayname <display-name> \
    --description <description>

L'esecuzione di questo comando genera una risposta che contiene le informazioni aggiornate sul comando e l'ora dell'ultimo aggiornamento. Il codice seguente mostra un esempio di richiesta e risposta per l'aggiornamento del nome visualizzato e della descrizione di un comando che spegne l'AC.

aws iot update-command \ 
    --command-id <LockDoor> \ 
    --displayname <Secondary lock door> \
    --description <Locks doors to my home>

L'esecuzione di questo comando genera la seguente risposta.

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

Deprecare o ripristinare una risorsa di comando

Dopo aver creato un comando, se non si desidera più continuare a utilizzarlo, è possibile contrassegnarlo come obsoleto. Quando si depreca un comando, tutte le esecuzioni di comandi in sospeso continueranno a essere eseguite sul dispositivo di destinazione fino a quando non raggiungono lo stato di terminale. Una volta che un comando è diventato obsoleto, se si desidera utilizzarlo, ad esempio per inviare una nuova esecuzione di comando al dispositivo di destinazione, è necessario ripristinarlo.

Nota

Non è possibile modificare un comando obsoleto o eseguire nuove esecuzioni per esso. Per eseguire nuovi comandi sul dispositivo, è necessario ripristinarlo in modo che lo stato del comando passi a Disponibile.

Per ulteriori informazioni sulla deprecazione e il ripristino di un comando e sulle relative considerazioni, vedere. Deprecare una risorsa di comando

Eliminare una risorsa di comando

Se non desideri più utilizzare un comando, puoi rimuoverlo definitivamente dal tuo account. Se l'operazione di eliminazione ha esito positivo:

  • Se il comando è obsoleto per una durata superiore al timeout massimo di 12 ore, il comando verrà eliminato immediatamente.

  • Se il comando non è obsoleto o lo è stato per una durata inferiore al timeout massimo, il comando sarà in uno stato. pending deletion Verrà rimosso automaticamente dal tuo account dopo il timeout massimo di 12 ore.

Nota

Il comando potrebbe essere eliminato anche se sono presenti esecuzioni di comandi in sospeso. Il comando sarà in sospeso di eliminazione e verrà rimosso automaticamente dal tuo account.

Per eliminare un comando dalla console, accedi al Command Hub della AWS IoT console ed esegui i seguenti passaggi.

  1. Scegli il comando che desideri eliminare, quindi in Azioni scegli Elimina.

  2. Conferma di voler eliminare il comando, quindi scegli Elimina.

Il comando verrà contrassegnato per l'eliminazione e rimosso definitivamente dal tuo account dopo 12 ore.

Utilizzate l'operazione API del piano di controllo DeleteCommand HTTP o il delete-command AWS CLI comando per eliminare una risorsa di comando. Se l'operazione di eliminazione ha esito positivo, vedrai un HTTP statusCode di 204 o 202 e il comando verrà eliminato automaticamente dal tuo account dopo la durata massima del timeout di 12 ore. Nel caso dello stato 204, indica che il comando è stato eliminato.

Policy IAM di esempio

Prima di utilizzare questa operazione API, assicurati che la tua policy IAM ti autorizzi a eseguire questa azione sul dispositivo. L'esempio seguente mostra una policy IAM che consente l'autorizzazione dell'utente a eseguire l'DeleteCommandazione.

In questo esempio, sostituisci:

  • regioncon il tuo Regione AWS, ad esempious-east-1.

  • account-idcon il tuo Account AWS numero, ad esempio123456789012.

  • command-idcon il tuo identificatore di comando AWS IoT univoco, ad esempioLockDoor. Se desideri recuperare più di un comando, puoi specificare questi comandi nella sezione Resource della policy IAM.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:DeleteCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Eliminare un esempio di comando ()AWS CLI

Gli esempi seguenti mostrano come eliminare un comando utilizzando il delete-command AWS CLI comando. A seconda dell'applicazione, <command-id> sostituiscilo con l'identificatore del comando che stai eliminando.

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

Se la richiesta API ha esito positivo, il comando genera un codice di stato di 202 o 204. Puoi utilizzare l'GetCommandAPI per verificare che il comando non esista più nel tuo account.