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 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 nello spazio dei AWS IoT nomi con le informazioni sul payload. All'avvio di Execution, il dispositivo elabora le istruzioni di Payload ed esegue azioni specificate. Vedi Crea una risorsa di comando per la creazione di comandi.

  • Il dispositivo è abbonato agli argomenti riservati di MQTT per i comandi. 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 client. <PayloadFormat>Valori supportati: JSON e CBOR. Per ulteriori informazioni, consulta Argomenti sui comandi.

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

    Per formati diversi da JSON/CBOR, usa questo formato Commands Topic<PayloadFormat>:

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

Specificare il dispositivo di destinazione per ricevere ed eseguire il comando. Usa un nome 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 cosa

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. Per i dettagli della registrazione, vedere Gestione degli elementi con il registro.

ID client

Per i dispositivi non registrati, usa l'ID client.

L'ID client è un identificatore univoco assegnato ai dispositivi. Definito nel protocollo MQTT, contiene caratteri alfanumerici, caratteri di sottolineatura o trattini. Ogni dispositivo a cui si connette AWS IoT necessita di un ID client univoco.

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.

Il Client ID è 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) con cui i dispositivi forniscono i risultati di esecuzione.

Dopo aver creato un'esecuzione, viene avviato un timer. Se il dispositivo va offline o non riporta i risultati entro il timeout, l'Esecuzione scade con lo statoTIMED_OUT.

Impostazione predefinita: 10 secondi. Massimo: 12 ore.

Valore del timeout e stato di TIMED_OUT esecuzione

Sia il cloud che il dispositivo possono segnalare il timeout.

Dopo aver inviato il comando, si avvia un timer. Se nessuna risposta del dispositivo arriva entro il timeout, il cloud imposta lo stato di esecuzione su TIMED_OUT con codice 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 persistenti MQTT da utilizzare con la funzionalità dei AWS IoT Device Management comandi. Questa funzionalità è particolarmente utile in casi come quando il dispositivo va offline e si desidera assicurarsi che il dispositivo riceva ancora 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 superiore a tale durata, le esecuzioni di 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 persistenti 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. Esamina le informazioni sul comando che hai creato, inclusi gli argomenti riservati MQTT e i parametri, se applicabile.

    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. Specificare il dispositivo di destinazione per ricevere ed eseguire il comando. Il dispositivo può essere specificato come AWS IoT oggetto se è stato registrato 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 StartCommandExecutionHTTP Data Plane API 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 hanno sottoscritto l'argomento relativo alla richiesta dei comandi, l'StartCommandExecutionAPI pubblicherà il messaggio di payload sull'argomento. Il payload può utilizzare qualsiasi formato di 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, di seguito viene illustrato il formato dell'argomento di 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 l'autorizzazione dell'utente a 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 dei due 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 AWS IoT thing-name o. 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 supportateStartCommandExecution, consulta Condition Keys for AWS IoT nella IAM User Guide.

Ottieni un endpoint del piano dati specifico dell'account

Prima di eseguire il comando API, è necessario ottenere l'URL dell'endpoint specifico dell'account per l'endpoint. Se utilizzi endpoint dual-stack (and), usa il. IPv4 IPv6 iot:Data-ATS L'iot:Jobsendpoint è solo per. IPv4 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 comando ()AWS CLI

L'esempio seguente mostra come iniziare l'esecuzione di un comando utilizzando il start-command-execution AWS CLI comando.

In questo esempio, sostituisci:

  • <command-arn>con l'ARN per il comando che si desidera 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 di destinazionemyRegisteredThing, usa. arn:aws:iot:region:account-id:thing/myRegisteredThing

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

  • (Facoltativo) È inoltre possibile specificare un parametro aggiuntivo quando si esegue 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 è impostato suCREATED, 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 che non hanno un valore DefaultValue impostato al momento della creazione del comando. Se un parametro ha un DefaultValue, il valore del parametro fornito qui ha la precedenza. Per i parametri per cui è impostato ValueConditions, 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 dei comandi.

Nota

Se il comando è 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 e aver sottoscritto gli argomenti di richiesta e risposta dei comandi. Per ulteriori informazioni, consulta Flusso di lavoro dei comandi di alto livello.

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

Prima di utilizzare questa operazione API, assicurati che la tua policy IAM autorizzi il tuo dispositivo a eseguire queste azioni. Di seguito è riportato un esempio di policy che autorizza il dispositivo a eseguire l'azione. Per ulteriori esempi di policy IAM che consentono l'autorizzazione dell'utente a 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 a cui 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 Flusso di lavoro dei comandi di alto livello.

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 l'IoT

Il codice seguente mostra un esempio di policy relativa ai dispositivi 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. Utilizza quindi l'UpdateCommandExecutionAPI per aggiornare lo stato e il risultato dell'esecuzione del comando in base 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>Possono essere JSON o CBOR.

Nota

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

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

Il dispositivo ha segnalato gli aggiornamenti dello stato di esecuzione

I tuoi dispositivi possono utilizzare l'API per segnalare uno dei seguenti aggiornamenti di stato all'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 di risposta comeSUCCEEDED.

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

  • REJECTED: Se il dispositivo non accetta il comando, può pubblicare un messaggio nell'argomento di risposta comeREJECTED.

  • TIMED_OUT: Lo stato di esecuzione del comando può cambiare in 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 di risposta.

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

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

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 dispositivi forniscono questo oggetto, il reasonCode campo dell'oggetto è obbligatorio, ma il reasonDescription campo è facoltativo.

  • Quando i dispositivi utilizzano l'statusReasonoggetto, reasonCode devono utilizzare lo schema [A-Z0-9_-]+ e non superare i 64 caratteri di lunghezza. Se lo forniscireasonDescription, 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 fornite ilresult, deve essere necessario inserire 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 visualizzare l'errore nel gruppo di AWSIoTLogsV2 log di Amazon CloudWatch. Per informazioni sull'abilitazione della registrazione e sulla visualizzazione dei log, consulta. Configurare la registrazione AWS IoT

UpdateCommandExecutionEsempio di API

Il codice seguente mostra un esempio di come il dispositivo può utilizzare l'UpdateCommandExecutionAPI per segnalare lo stato di 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"
        }
    }
}

Recupera l'esecuzione di un comando

Dopo aver eseguito un comando, è possibile recuperare informazioni sull'esecuzione del comando dalla AWS IoT console e utilizzare il. 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 di 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 si è scelto un AWS IoT oggetto come dispositivo di destinazione durante l'esecuzione del comando, è possibile visualizzare i dettagli di esecuzione dalla pagina Thing hub.

    1. Vai alla pagina Thing Hub nella AWS IoT console e scegli l'oggetto per cui 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.

Utilizzate 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 l'autorizzazione dell'utente a 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 uno dei due 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 AWS IoT thing-name o. 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 comando

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

In questo esempio, sostituisci:

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

  • <target-arn>con l'Amazon Resource Number (ARN) del dispositivo a cui stai indirizzando l'esecuzione. È possibile ottenere queste informazioni dalla risposta del comando start-command-execution CLI.

  • Facoltativamente, se i dispositivi hanno utilizzato l'UpdateCommandExectionAPI per fornire il risultato dell'esecuzione, è possibile specificare se includere il risultato dell'esecuzione del comando nella risposta dell'API che utilizza l'GetCommandExecutionGetCommandExecutionAPI.

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 in cui è iniziata l'esecuzione e quando è stata completata. 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 di un terminale al cloud. Nel caso dello TIMED_OUT status, 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, consultaConsiderazioni 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 ha sottoscritto l'argomento di richiesta riservata MQTT per i comandi, viene visualizzato il messaggio di payload pubblicato su questo argomento.

Il dispositivo riceve quindi le istruzioni per il payload ed esegue le operazioni specificate sul dispositivo. AWS IoT Utilizza quindi 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 archivia le informazioni aggiornate e pubblica i log su 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 AWS IoT console.

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

    Nota

    Puoi trovare il nome dell'oggetto per il tuo dispositivo nella pagina Thing Hub della AWS IoT console. Se non hai registrato il 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 Iscriviti.

    $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 di richiesta a cui il dispositivo è abbonato,. $aws/commands/things/<thingId>/executions/+/request Nel client di test MQTT, dovresti vedere il payload del comando che contiene le istruzioni per l'elaborazione del comando da parte del dispositivo.

  5. Dopo l'avvio dell'esecuzione del comando, il dispositivo può pubblicare aggiornamenti di stato al seguente argomento di risposta riservato MQTT per i comandi.

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

    Ad esempio, prendete in considerazione un comando che avete eseguito per accendere l'aria condizionata dell'auto per ridurre la temperatura al valore desiderato. Il codice JSON seguente mostra un messaggio di esempio pubblicato dal veicolo nell'argomento di 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 utilizzare 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 vedere 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 si è scelto un AWS IoT oggetto come dispositivo di destinazione durante l'esecuzione del comando e si sono create più esecuzioni di comandi per un singolo dispositivo, è possibile 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 di esecuzioni che hai creato per il dispositivo.

Utilizza l'operazione API HTTP del piano di ListCommandExecutions AWS IoT Core controllo per elencare tutte le esecuzioni di 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 l'autorizzazione dell'utente a 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 di comandi in. Account AWS

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

In questo esempio, sostituisci:

  • <target-arn>con l'Amazon Resource Number (ARN) del dispositivo a cui stai indirizzando l'esecuzione, ad esempio. arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f

  • <target-arn>con l'Amazon Resource Number (ARN) del dispositivo a cui stai indirizzando l'esecuzione, 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 create e l'ora in cui le esecuzioni hanno iniziato l'esecuzione 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 terminaleSUCCEEDED, ad esempioFAILED, 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 è riportato 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 uno dei due 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 AWS IoT thing-name o. 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, <execution-id> sostituiscilo con l'identificatore per l'esecuzione del comando che stai eliminando e poi <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.