View a markdown version of this page

Avvia e monitora le esecuzioni di comandi - AWS IoT Core
Avvia l'esecuzione di un comandoAggiorna il risultato dell’esecuzione di un comandoRecupera l'esecuzione di un comandoVisualizzazione degli aggiornamenti dei comandi utilizzando il client di test MQTTElenca le esecuzioni dei comandi nel tuo Account AWSEliminare l'esecuzione di un 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à.

Avvia e monitora le esecuzioni di comandi

Dopo aver creato un comando, avvia un'esecuzione sul dispositivo di destinazione. Il dispositivo aggiorna i risultati e pubblica lo stato negli argomenti riservati di MQTT. Recupera e monitora lo stato di esecuzione dal tuo account.

Avvia e monitora i comandi utilizzando la AWS IoT console o AWS CLI.

Avvia l'esecuzione di un comando

Importante

L'utente è l'unico responsabile della distribuzione dei comandi in modo sicuro e conforme alle leggi applicabili.

Prima di iniziare un'esecuzione, assicurati che:

  • Hai creato un comando nel AWS IoT namespace con le informazioni sul payload. All'avvio di Execution, il dispositivo elabora le istruzioni del Payload ed esegue le azioni specificate. Vedi Crea una risorsa di comando Creazione dei comandi.

  • Il tuo dispositivo è abbonato agli argomenti riservati per i comandi di MQTT. All'avvio di Execution, le informazioni sul payload vengono pubblicate in questo argomento di richiesta MQTT riservato:

    <devices>possono essere client Things o MQTT. <DeviceID>è il nome dell'oggetto o l'ID del cliente. <PayloadFormat>Valori supportati: JSON e CBOR. Per ulteriori informazioni, consulta Argomenti dei comandi.

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

    Per non- JSON/CBOR <PayloadFormat>, usa questo formato Commands Topic:

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

Specifica il dispositivo di destinazione per ricevere ed eseguire il comando. Utilizza un nome di oggetto per i dispositivi registrati o un ID client per i dispositivi non registrati. Dopo aver ricevuto il payload, il dispositivo esegue il comando ed esegue le azioni specificate.

AWS IoT thing

I dispositivi di destinazione possono essere oggetti registrati nel AWS IoT registro. Le cose semplificano la ricerca e la gestione dei dispositivi.

Registra i dispositivi come oggetti dalla pagina del dispositivo Connect o utilizzando CreateThing. Trova oggetti esistenti da Thing Hub o utilizzando DescribeThing. Vedi Gestire le cose con il registro per i dettagli sulla registrazione.

ID client

Per i dispositivi non registrati, utilizza il Client ID.

L'ID client è un identificatore univoco che assegni ai dispositivi. Definito nel protocollo MQTT, contiene caratteri alfanumerici, trattini bassi o trattini. Ogni dispositivo a cui si connette richiede un ID client univoco. AWS IoT

Nota

  • Per gli oggetti registrati, l'ID client può corrispondere al nome dell'oggetto.

  • Quando si sceglie come target un ID client specifico, i dispositivi devono connettersi AWS IoT utilizzando tale ID client per ricevere il Payload.

L'ID client è l'ID client MQTT utilizzato dai dispositivi per la connessione a. AWS IoT Core AWS IoT utilizza questo ID per identificare i dispositivi e gestire connessioni e abbonamenti.

Il timeout specifica la durata (in secondi) entro la quale i dispositivi forniscono i risultati di esecuzione.

Dopo aver creato un'esecuzione, viene avviato un timer. Se il dispositivo si disconnette o non riporta i risultati entro il timeout, lo stato TIMED_OUT di esecuzione scade.

Impostazione predefinita: 10 secondi. Massimo: 12 ore.

Valore di timeout e stato di esecuzione TIMED_OUT

Sia il cloud che il dispositivo possono segnalare il timeout.

Dopo aver inviato il comando, viene avviato un timer. Se nessuna risposta del dispositivo arriva entro il timeout, il cloud imposta lo stato di esecuzione TIMED_OUT con il codice del motivo. $NO_RESPONSE_FROM_DEVICE

Ciò si verifica quando:

  • Il dispositivo è andato offline durante l'esecuzione.

  • Il dispositivo non è riuscito a completare l'esecuzione entro il timeout.

  • Il dispositivo non è riuscito a segnalare lo stato entro il timeout.

In questo caso, quando lo stato di esecuzione di TIMED_OUT viene segnalato dal cloud, l'esecuzione del comando non è terminale. Il dispositivo può pubblicare una risposta che sostituisce lo stato di uno qualsiasi degli stati del terminale:SUCCEEDED,, o. FAILED REJECTED L'esecuzione del comando diventa quindi terminale e non accetta ulteriori aggiornamenti.

Il dispositivo può anche aggiornare uno TIMED_OUT stato avviato dal cloud segnalando che si è verificato un timeout durante l'esecuzione del comando. In questo caso, lo stato di esecuzione del comando rimane invariatoTIMED_OUT, ma l'statusReasonoggetto viene aggiornato in base alle informazioni riportate dal dispositivo. L'esecuzione del comando diventa quindi terminale e non vengono accettati ulteriori aggiornamenti.

Utilizzo di sessioni persistenti MQTT

È possibile configurare le sessioni permanenti MQTT da utilizzare con la funzionalità dei AWS IoT Device Management comandi. Questa funzionalità è particolarmente utile in casi come quando il dispositivo è offline e si desidera assicurarsi che il dispositivo riceva comunque il comando quando torna online prima della durata del timeout ed esegua le istruzioni specificate.

Per impostazione predefinita, la scadenza della sessione persistente MQTT è impostata su 60 minuti. Se il timeout di esecuzione dei comandi è configurato su un valore che supera questa durata, le esecuzioni dei comandi che durano più di 60 minuti possono essere rifiutate dal broker di messaggi e avere esito negativo. Per eseguire comandi che durano più di 60 minuti, puoi richiedere un aumento del tempo di scadenza della sessione persistente.

Nota

Per assicurarti di utilizzare correttamente la funzionalità delle sessioni permanenti MQTT, imposta il flag Clean Start su zero. Per ulteriori informazioni, consulta Sessioni persistenti MQTT.

Per iniziare a eseguire il comando dalla console, vai alla pagina Command Hub della AWS IoT console ed esegui i seguenti passaggi.

  1. Per eseguire il comando che hai creato, scegli Esegui comando.

  2. Rivedi le informazioni sul comando che hai creato, inclusi gli argomenti riservati MQTT e i parametri, se applicabili.

    Per i comandi dinamici, inserite i valori dei parametri o lasciateli con i valori predefiniti. Per i parametri che non hanno un valore predefinito, è necessario fornire un valore da inviare come parte di questa esecuzione.

  3. Specifica il dispositivo di destinazione per ricevere ed eseguire il comando. Il dispositivo può essere specificato come AWS IoT oggetto se è stato registrato con AWS IoT o utilizzando l'ID client se il dispositivo non è ancora stato registrato. Per ulteriori informazioni, consulta Considerazioni sul dispositivo di destinazione

  4. (Facoltativo) Configurate un valore di timeout per il comando che determini la durata per la quale desiderate che il comando venga eseguito prima del timeout. Se il comando deve essere eseguito per più di 60 minuti, potrebbe essere necessario aumentare il tempo di scadenza delle sessioni persistenti MQTT. Per ulteriori informazioni, consulta Considerazioni sul timeout dell'esecuzione dei comandi.

  5. Seleziona Esegui comando.

Utilizzate l'operazione API StartCommandExecution HTTP data plane per avviare l'esecuzione di un comando. La richiesta e la risposta dell'API sono correlate dall'ID di esecuzione del comando. Una volta completata l'esecuzione del comando, il dispositivo può segnalare lo stato e il risultato dell'esecuzione al cloud pubblicando un messaggio nell'argomento di risposta ai comandi. Per un codice di risposta personalizzato, i codici applicativi di tua proprietà possono elaborare il messaggio di risposta e pubblicare il risultato su AWS IoT.

Se i tuoi dispositivi sono abbonati all'argomento di richiesta dei comandi, l'StartCommandExecutionAPI pubblicherà il messaggio di payload nell'argomento. Il payload può utilizzare qualsiasi formato a tua scelta. Per ulteriori informazioni, consulta Payload del comando.

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

Se il formato del payload non è JSON o CBOR, quanto segue mostra il formato dell'argomento della richiesta dei comandi.

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

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 all'utente il permesso di eseguire l'StartCommandExecutionazione.

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 il AWS IoT comando, ad esempioLockDoor. Se desideri inviare più di un comando, puoi specificare questi comandi nella policy IAM.

  • devicescon uno thing o client a seconda che i tuoi dispositivi siano stati registrati come AWS IoT oggetti o siano specificati come client MQTT.

  • device-idcon il tuo o. AWS IoT thing-name client-id

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Per visualizzare un elenco delle chiavi di condizione supportate perStartCommandExecution, consulta Condition Keys for AWS IoT nella IAM User Guide.

Ottieni un endpoint del data plane specifico per l'account

Prima di eseguire il comando API, è necessario ottenere l'URL dell'endpoint specifico dell'account per l'endpoint. Se utilizzi endpoint dual-stack (IPv4 e IPv6), usa il. iot:Data-ATS L'endpoint è solo per IPv4. iot:Jobs Ad esempio, se si esegue questo comando:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

Restituisce l'URL dell'endpoint specifico dell'account, come mostrato nella risposta di esempio riportata di seguito.

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

Avvia un esempio di esecuzione di un comando (AWS CLI)

L'esempio seguente mostra come iniziare a eseguire un comando utilizzando il start-command-execution AWS CLI comando.

In questo esempio, sostituisci:

  • <command-arn>con l'ARN del comando che desideri eseguire. È possibile ottenere queste informazioni dalla risposta del comando create-command CLI. Ad esempio, se stai eseguendo il comando per cambiare la modalità del volante, usaarn:aws:iot:region:account-id:command/SetComfortSteeringMode.

  • <target-arn>con il Thing ARN per il dispositivo di destinazione, che può essere un oggetto IoT o un client MQTT, per il quale si desidera eseguire il comando. Ad esempio, se stai eseguendo il comando per il dispositivo myRegisteredThing di destinazione, usa. arn:aws:iot:region:account-id:thing/myRegisteredThing

  • <endpoint-url>con l'endpoint specifico dell'account che hai ottenutoOttieni un endpoint del data plane specifico per l'account, preceduto da. https:// Ad esempio, https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com.

  • (Facoltativo) Puoi anche specificare un parametro aggiuntivo quando esegui executionTimeoutSeconds l'operazione API. StartCommandExecution Questo campo opzionale specifica il tempo in secondi entro il quale il dispositivo deve completare l'esecuzione del comando. Per impostazione predefinita, il valore è 10 secondi. Quando lo stato di esecuzione del comando èCREATED, viene avviato un timer. Se il risultato dell'esecuzione del comando non viene ricevuto prima della scadenza del timer, lo stato cambia automaticamente inTIMED_OUT.

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

  • (Facoltativo) Per i comandi dinamici, specificate i parametri e i relativi valori da utilizzare per la sostituzione. È necessario fornire un valore per i parametri per i quali non è impostato un valore predefinito al momento della creazione del comando. Se un parametro ha un valore predefinito, il valore del parametro fornito qui ha la precedenza. Per i parametri con ValueConditions impostato, il valore del parametro fornito qui deve soddisfare la condizione.

    Basato su un esempio di comando Light_Power_Status dinamico:

  • aws iot-jobs-data start-command-execution \
    --command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status  \
    --target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \
    --endpoint <endpoint-url> \
    --execution-timeout-seconds 900 \
    --parameters "powerStatus={S=ON}"

L'esecuzione di questo comando restituisce un ID di esecuzione del comando. È possibile utilizzare questo ID per interrogare lo stato di esecuzione del comando, i dettagli e la cronologia di esecuzione del comando.

Nota

Se il comando è stato dichiarato obsoleto, la richiesta StartCommandExecution API avrà esito negativo con un'eccezione di convalida. Per correggere questo errore, ripristina prima il comando utilizzando l'UpdateCommandAPI, quindi esegui la richiesta. StartCommandExecution

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

Aggiorna il risultato dell’esecuzione di un comando

Utilizzate l'operazione API del piano dati UpdateCommandExecution MQTT per aggiornare lo stato o il risultato dell'esecuzione di un comando.

Nota

Prima di utilizzare questa API:

  • Il dispositivo deve aver stabilito una connessione MQTT ed essere iscritto agli argomenti di richiesta e risposta dei comandi. Per ulteriori informazioni, consulta High-level flusso di lavoro dei comandi.

  • È necessario aver già eseguito questo comando utilizzando l'StartCommandExecutionoperazione API.

Prima di utilizzare questa operazione API, assicurati che la tua policy IAM autorizzi il tuo dispositivo a eseguire queste azioni. Di seguito viene mostrato un esempio di policy che autorizza il dispositivo a eseguire l'azione. Per ulteriori esempi di policy IAM che consentono all'utente il permesso di eseguire l'azione UpdateCommandExecution MQTT, vedere. Esempi di policy di connessione e pubblicazione

In questo esempio, sostituisci:

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

  • AccountIDcon il tuo Account AWS numero, ad esempio123456789012.

  • ThingNamecon il nome dell' AWS IoT oggetto per il quale intendi eseguire il comando, ad esempiomyRegisteredThing.

  • commands-request-topice commands-response-topic con i nomi degli argomenti di richiesta e risposta dei AWS IoT comandi. Per ulteriori informazioni, consulta High-level flusso di lavoro dei comandi.

Esempio di policy IAM per l'ID client MQTT

Il codice seguente mostra un esempio di policy del dispositivo quando si utilizza l'ID client MQTT.

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

Esempio di policy IAM per IoT Thing

Il codice seguente mostra un esempio di policy del dispositivo quando si utilizza un AWS IoT oggetto.

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

Dopo aver ricevuto l'esecuzione del comando nell'argomento della richiesta, il dispositivo elabora il comando. Quindi utilizza l'UpdateCommandExecutionAPI per aggiornare lo stato e il risultato dell'esecuzione del comando al seguente argomento di risposta.

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

In questo esempio, <DeviceID> è l'identificatore univoco del dispositivo di destinazione ed <execution-id> è l'identificatore dell'esecuzione del comando sul dispositivo di destinazione. <PayloadFormat>Può essere JSON o CBOR.

Nota

Se non hai registrato il tuo dispositivo con AWS IoT, puoi utilizzare l'ID del cliente come identificatore anziché il nome di un oggetto.

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

Il dispositivo ha segnalato aggiornamenti dello stato di esecuzione

I tuoi dispositivi possono utilizzare l'API per segnalare uno dei seguenti aggiornamenti di stato dell'esecuzione del comando. Per ulteriori informazioni su questi stati, consultaStato di esecuzione del comando.

  • IN_PROGRESS: Quando il dispositivo inizia a eseguire il comando, può aggiornare lo stato aIN_PROGRESS.

  • SUCCEEDED: Quando il dispositivo elabora correttamente il comando e completa l'esecuzione, può pubblicare un messaggio nell'argomento della risposta comeSUCCEEDED.

  • FAILED: se il dispositivo non è riuscito a eseguire il comando, può pubblicare un messaggio nell'argomento della risposta comeFAILED.

  • REJECTED: se il dispositivo non è riuscito ad accettare il comando, può pubblicare un messaggio nell'argomento della risposta comeREJECTED.

  • TIMED_OUT: lo stato di esecuzione del comando può cambiare a TIMED_OUT causa di uno dei seguenti motivi.

    • Il risultato dell'esecuzione del comando non è stato ricevuto. Ciò può accadere perché l'esecuzione non è stata completata entro la durata specificata o se il dispositivo non è riuscito a pubblicare le informazioni sullo stato nell'argomento della risposta.

    • Il dispositivo segnala che si è verificato un timeout durante il tentativo di esecuzione del comando.

Per ulteriori informazioni sullo TIMED_OUT stato, vedereValore di timeout e stato di esecuzione TIMED_OUT.

Considerazioni sull'utilizzo dell'API UpdateCommandExecution

Di seguito sono riportate alcune considerazioni importanti sull'utilizzo dell'UpdateCommandExecutionAPI.

  • I tuoi dispositivi possono utilizzare un statusReason oggetto opzionale per fornire informazioni aggiuntive sull'esecuzione. Se i tuoi dispositivi forniscono questo oggetto, il reasonCode campo dell'oggetto è obbligatorio, ma il reasonDescription campo è facoltativo.

  • Quando i dispositivi utilizzano l'statusReasonoggetto, reasonCode devono utilizzare il modello [A-Z0-9_-]+ e non superare i 64 caratteri di lunghezza. Se fornisci ilreasonDescription, assicurati che non superi i 1.024 caratteri di lunghezza. Può utilizzare qualsiasi carattere tranne i caratteri di controllo come le nuove righe.

  • I dispositivi possono utilizzare un result oggetto opzionale per fornire informazioni sul risultato dell'esecuzione del comando, ad esempio il valore restituito da una chiamata di funzione remota. Se si fornisce ilresult, deve richiedere almeno una voce.

  • Nel result campo, si specificano le voci come coppie chiave-valore. Per ogni voce, è necessario specificare le informazioni sul tipo di dati come stringa, booleana o binaria. Un tipo di dati stringa deve utilizzare la chiaves, un tipo di dati booleano utilizza la chiave b e un tipo di dati binario deve utilizzare la chiave. bin Assicurati che queste chiavi siano minuscole.

  • Se riscontri un errore durante l'esecuzione dell'UpdateCommandExecutionAPI, puoi visualizzarlo nel gruppo di AWSIoTLogsV2 log in Amazon. CloudWatch Per informazioni su come abilitare la registrazione e la visualizzazione dei log, consultaConfigura AWS IoT logging.

UpdateCommandExecutionEsempio di API

Il codice seguente mostra un esempio di come il dispositivo può utilizzare l'UpdateCommandExecutionAPI per segnalare lo stato dell'esecuzione, il statusReason campo per fornire informazioni aggiuntive sullo stato e il campo dei risultati per fornire informazioni sul risultato dell'esecuzione, ad esempio la percentuale della batteria dell'auto in questo caso.

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}
Nota

Quando la richiesta UpdateCommandExecution MQTT fallisce, il servizio pubblica una risposta di errore sull'argomento. /rejected Per un elenco completo dei codici di errore e una guida alla risoluzione dei problemi, vedere. AWS IoT Comandi e risoluzione dei problemi

Recupera l'esecuzione di un comando

Dopo aver eseguito un comando, è possibile recuperare informazioni sull'esecuzione del comando dalla AWS IoT console e utilizzando. AWS CLIÈ possibile ottenere le seguenti informazioni.

Nota

Per recuperare lo stato di esecuzione del comando più recente, il dispositivo deve pubblicare le informazioni sullo stato nell'argomento della risposta utilizzando l'API UpdateCommandExecution MQTT, come descritto di seguito. Fino a quando il dispositivo non pubblicherà questo argomento, l'GetCommandExecutionAPI riporterà lo stato come o. CREATED TIMED_OUT

Ogni esecuzione di comando creata avrà:

  • Un ID di esecuzione, che è un identificatore univoco dell’esecuzione del comando.

  • Lo stato dell’esecuzione del comando. Quando si esegue il comando sul dispositivo di destinazione, l’esecuzione del comando entra in uno stato CREATED. Può quindi passare ad altri stati di esecuzione dei comandi come descritto di seguito.

  • Il risultato dell'esecuzione del comando.

  • L’ID di comando univoco e il dispositivo di destinazione per il quale sono state create le esecuzioni.

  • La data di inizio, che indica l’ora in cui è stata creata l’esecuzione del comando.

È possibile recuperare l'esecuzione di un comando dalla console utilizzando uno dei seguenti metodi.

  • Dalla pagina Command hub

    Vai alla pagina Command Hub della AWS IoT console ed esegui questi passaggi.

    1. Scegli il comando per il quale hai creato un'esecuzione sul dispositivo di destinazione.

    2. Nella pagina dei dettagli del comando, nella scheda Cronologia dei comandi, vedrai le esecuzioni che hai creato. Scegli l'esecuzione per la quale desideri recuperare le informazioni.

    3. Se i tuoi dispositivi hanno utilizzato l'UpdateCommandExecutionAPI per fornire le informazioni sui risultati, puoi trovare queste informazioni nella scheda Risultati di questa pagina.

  • Dalla pagina Thing hub

    Se hai scelto un AWS IoT oggetto come dispositivo di destinazione durante l'esecuzione del comando, puoi visualizzare i dettagli di esecuzione dalla pagina Thing hub.

    1. Vai alla pagina Thing Hub nella AWS IoT console e scegli l'oggetto per il quale hai creato l'esecuzione del comando.

    2. Nella pagina dei dettagli dell'oggetto, nella cronologia dei comandi, vedrai le esecuzioni che hai creato. Scegli l'esecuzione per la quale desideri recuperare le informazioni.

    3. Se i tuoi dispositivi hanno utilizzato l'UpdateCommandExecutionAPI per fornire le informazioni sui risultati, puoi trovare queste informazioni nella scheda Risultati di questa pagina.

Usa l'operazione API HTTP del piano di GetCommandExecution AWS IoT Core controllo per recuperare informazioni sull'esecuzione di un comando. È necessario aver già eseguito questo comando utilizzando l'operazione StartCommandExecution API.

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 all'utente il permesso di eseguire l'GetCommandExecutionazione.

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 AWS IoT comando univoco, ad esempioLockDoor.

  • devicescon thing o client a seconda che i tuoi dispositivi siano stati registrati come AWS IoT oggetti o siano specificati come client MQTT.

  • device-idcon il tuo o. AWS IoT thing-name client-id

{
  "Effect": "Allow",
  "Action": [
      "iot:GetCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Recupera un esempio di esecuzione di un comando

L'esempio seguente mostra come recuperare informazioni su un comando eseguito utilizzando il start-command-execution AWS CLI comando. L'esempio seguente mostra come recuperare informazioni su un comando eseguito per disattivare la modalità volante.

In questo esempio, sostituisci:

  • <execution-id>con l'identificatore dell'esecuzione del comando per il quale si desidera recuperare le informazioni.

  • <target-arn>con l'Amazon Resource Number (ARN) del dispositivo per il quale intendi eseguire. Puoi ottenere queste informazioni dalla risposta del comando start-command-execution CLI.

  • Facoltativamente, se i tuoi dispositivi hanno utilizzato l'UpdateCommandExectionAPI per fornire il risultato dell'esecuzione, puoi specificare se includere il risultato dell'esecuzione del comando nella risposta dell'GetCommandExecutionAPI utilizzando l'GetCommandExecutionAPI.

aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <target-arn> \
    --include-result

L'esecuzione di questo comando genera una risposta che contiene informazioni sull'ARN dell'esecuzione del comando, sullo stato dell'esecuzione e sull'ora di inizio e di completamento dell'esecuzione. Fornisce inoltre un statusReason oggetto che contiene informazioni aggiuntive sullo stato. Per ulteriori informazioni sui diversi stati e sul motivo dello stato, vedereStato di esecuzione del comando.

Il codice seguente mostra un esempio di risposta dalla richiesta API.

Nota

Il completedAt campo nella risposta di esecuzione corrisponde all'ora in cui il dispositivo segnala lo stato del terminale al cloud. Nel caso dello TIMED_OUT stato, questo campo verrà impostato solo quando il dispositivo segnala un timeout. Quando lo TIMED_OUT stato è impostato dal cloud, lo TIMED_OUT stato non viene aggiornato. Per ulteriori informazioni sul comportamento del timeout, vedereConsiderazioni sul timeout dell'esecuzione dei comandi.

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

Visualizzazione degli aggiornamenti dei comandi utilizzando il client di test MQTT

È possibile utilizzare il client di test MQTT per visualizzare lo scambio di messaggi su MQTT quando si utilizza la funzionalità dei comandi. Dopo che il dispositivo ha stabilito una connessione MQTT con AWS IoT, è possibile creare un comando, specificare il payload e quindi eseguirlo sul dispositivo. Quando si esegue il comando, se il dispositivo è iscritto all'argomento di richiesta riservata MQTT per i comandi, viene visualizzato il messaggio di payload pubblicato in questo argomento.

Il dispositivo riceve quindi le istruzioni sul payload ed esegue le operazioni specificate sul dispositivo. AWS IoT Quindi utilizza l'UpdateCommandExecutionAPI per pubblicare il risultato dell'esecuzione del comando e le informazioni sullo stato negli argomenti di risposta riservati MQTT per i comandi. AWS IoT Device Management ascolta gli aggiornamenti sugli argomenti di risposta e memorizza le informazioni aggiornate e pubblica i log su e Amazon. AWS CloudTrail CloudWatch È quindi possibile recuperare le informazioni più recenti sull'esecuzione dei comandi dalla console o utilizzando l'API. GetCommandExecution

I passaggi seguenti mostrano come utilizzare il client di test MQTT per osservare i messaggi.

  1. Aprire il client di test MQTT nella console. AWS IoT

  2. Nella scheda Iscriviti, inserisci il seguente argomento e poi scegli Iscriviti, dove <thingId> è il nome dell'oggetto del dispositivo con cui ti sei registrato. AWS IoT

    Nota

    Puoi trovare il nome dell'oggetto per il tuo dispositivo nella pagina Thing Hub della AWS IoT console. Se non hai registrato il tuo dispositivo come oggetto, puoi registrarlo al momento della connessione AWS IoT dalla pagina Connect device.

    $aws/commands/things/<thingId>/executions/+/request

  3. (Facoltativo) Nella scheda Iscriviti, puoi anche inserire i seguenti argomenti e scegliere Abbonati.

    $aws/commands/things/+/executions/+/response/accepted/json
$aws/commands/things/+/executions/+/response/rejected/json

  4. Quando si avvia l'esecuzione di un comando, il payload del messaggio verrà inviato al dispositivo utilizzando l'argomento della richiesta a cui il dispositivo è abbonato,. $aws/commands/things/<thingId>/executions/+/request Nel client di test MQTT, dovresti vedere il payload dei comandi che contiene le istruzioni per l'elaborazione del comando da parte del dispositivo.

  5. Dopo che il dispositivo ha iniziato a eseguire il comando, può pubblicare aggiornamenti di stato al seguente argomento di risposta riservata MQTT per i comandi.

    $aws/commands/<devices>/<device-id>/executions/<executionId>/response/json

    Ad esempio, considera un comando che hai eseguito per accendere l'aria condizionata della tua auto per ridurre la temperatura al valore desiderato. Il seguente JSON mostra un messaggio di esempio che il veicolo ha pubblicato nell'argomento della risposta, che mostra che non è riuscito a eseguire il comando.

    {
  "deviceId": "My_Car",
  "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
  "status": "FAILED",
  "statusReason": {
    "reasonCode": "CAR_LOW_ON_BATTERY",
    "reasonDescription": "Car battery is lower than 5 percent"
  }
}

    In questo caso, puoi caricare la batteria dell'auto e quindi eseguire nuovamente il comando.

Elenca le esecuzioni dei comandi nel tuo Account AWS

Dopo aver eseguito un comando, è possibile recuperare informazioni sull'esecuzione del comando dalla AWS IoT console e utilizzando il. AWS CLIÈ possibile ottenere le seguenti informazioni.

  • Un ID di esecuzione, che è un identificatore univoco dell’esecuzione del comando.

  • Lo stato dell’esecuzione del comando. Quando si esegue il comando sul dispositivo di destinazione, l’esecuzione del comando entra in uno stato CREATED. Può quindi passare ad altri stati di esecuzione dei comandi come descritto di seguito.

  • L’ID di comando univoco e il dispositivo di destinazione per il quale sono state create le esecuzioni.

  • La data di inizio, che indica l’ora in cui è stata creata l’esecuzione del comando.

Puoi visualizzare tutte le esecuzioni dei comandi dalla console utilizzando uno dei seguenti metodi.

  • Dalla pagina Command hub

    Vai alla pagina Command Hub della AWS IoT console ed esegui questi passaggi.

    1. Scegli il comando per il quale hai creato un'esecuzione sul dispositivo di destinazione.

    2. Nella pagina dei dettagli del comando, vai alla scheda Cronologia dei comandi e vedrai un elenco delle esecuzioni che hai creato.

  • Dalla pagina Thing hub

    Se hai scelto un AWS IoT oggetto come dispositivo di destinazione durante l'esecuzione del comando e hai creato più esecuzioni di comandi per un singolo dispositivo, puoi visualizzare le esecuzioni per il dispositivo dalla pagina Thing hub.

    1. Vai alla pagina Thing Hub nella AWS IoT console e scegli l'oggetto per cui hai creato le esecuzioni.

    2. Nella pagina dei dettagli dell'oggetto, nella cronologia dei comandi, vedrai un elenco delle esecuzioni che hai creato per il dispositivo.

Usa l'operazione API HTTP del piano di ListCommandExecutions AWS IoT Core controllo per elencare tutte le esecuzioni dei comandi nel tuo account.

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 all'utente il permesso di eseguire l'ListCommandExecutionsazione.

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 AWS IoT comando univoco, ad esempioLockDoor.

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

Elenca un esempio di esecuzione di comandi

L'esempio seguente mostra come elencare le esecuzioni dei comandi nel tuo. Account AWS

Quando si esegue il comando, è necessario specificare se filtrare l'elenco per visualizzare solo le esecuzioni di comando create per un particolare dispositivo utilizzando iltargetArn, o le esecuzioni per un particolare comando specificato utilizzando il. commandArn

In questo esempio, sostituisci:

  • <target-arn>con l'Amazon Resource Number (ARN) del dispositivo per il quale intendi eseguire, ad esempio. arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f

  • <target-arn>con l'Amazon Resource Number (ARN) del dispositivo per il quale intendi eseguire, ad esempio. arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f

  • <after>con il tempo dopo il quale desideri elencare le esecuzioni che sono state create, ad esempio,. 2024-11-01T03:00

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<after>}' \
--sort-order "ASCENDING"

L'esecuzione di questo comando genera una risposta che contiene un elenco di esecuzioni di comandi che hai creato e l'ora in cui le esecuzioni sono iniziate e quando sono state completate. Fornisce inoltre informazioni sullo stato e l'statusReasonoggetto che contiene informazioni aggiuntive sullo stato.

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

Per ulteriori informazioni sui diversi stati e sul motivo dello stato, vedereStato di esecuzione del comando.

Eliminare l'esecuzione di un comando

Se non desideri più utilizzare l'esecuzione di un comando, puoi rimuoverla definitivamente dal tuo account.

Nota

  • L'esecuzione di un comando può essere eliminata solo se è entrato in uno stato di terminale, ad esempioSUCCEEDED,FAILED, oREJECTED.

  • Questa operazione può essere eseguita solo utilizzando l' AWS IoT Core API o il AWS CLI. Non è disponibile dalla console.

Prima di utilizzare questa operazione API, assicurati che la tua policy IAM autorizzi il tuo dispositivo a eseguire queste azioni. Di seguito viene mostrato un esempio di policy che autorizza il dispositivo a eseguire l'azione.

In questo esempio, sostituisci:

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

  • AccountIDcon il tuo Account AWS numero, ad esempio123456789012.

  • CommandIDcon l'identificatore del comando di cui si desidera eliminare l'esecuzione.

  • devicescon thing o client a seconda che i dispositivi siano stati registrati come AWS IoT oggetti o siano specificati come client MQTT.

  • device-idcon il tuo o. AWS IoT thing-name client-id

{
  "Effect": "Allow",
  "Action": [
      "iot:DeleteCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

L'esempio seguente mostra come eliminare un comando utilizzando il delete-command AWS CLI comando. A seconda dell'applicazione, sostituiscilo <execution-id> con l'identificatore dell'esecuzione del comando che stai eliminando e <target-arn> con l'ARN del dispositivo di destinazione. 

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

Se la richiesta API ha esito positivo, l'esecuzione del comando genera un codice di stato 200. Puoi utilizzare l'GetCommandExecutionAPI per verificare che l'esecuzione del comando non esista più nel tuo account.