View a markdown version of this page

Messaggistica diretta - AWS IoT Core
PrerequisitiSendDirectMessage APIComportamento del client ricevente

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à.

Messaggistica diretta

AWS IoT Core ora supporta la messaggistica diretta. È possibile inviare un messaggio a un singolo dispositivo connesso tramite il relativo ID client MQTT, senza che il dispositivo debba iscriversi a un argomento.

In precedenza, l'invio di un messaggio a un dispositivo specifico richiedeva la pubblicazione su un argomento a cui il dispositivo era abbonato, senza alcun metodo integrato per confermare la consegna. Il mittente chiama l'API SendDirectMessage HTTP, specificando l'ID client del destinatario e un argomento di destinazione. Quandoconfirmation=true, AWS IoT Core consegna a QoS 1 e attende il PUBACK del destinatario prima di restituire una risposta positiva. Questo ti dà una conferma di consegna end-to-end. La risposta dell'API e Amazon CloudWatch Logs forniscono una visibilità completa sullo stato della consegna e sui motivi dell'errore.

I messaggi diretti non vengono elaborati dalle AWS IoT regole per l'esecuzione delle regole, non vengono messi in coda per i dispositivi offline e non supportano i messaggi conservati.

Prerequisiti

Sia il mittente che il destinatario richiedono azioni politiche specifiche per utilizzare la messaggistica diretta. Il mittente deve disporre iot:SendDirectMessage dell'autorizzazione. L'ID del client di destinazione è specificato come risorsa e la chiave di iot:Topic condizione (opzionale) limita gli argomenti che un mittente può inviare messaggi diretti. Il destinatario deve disporre iot:Receive dell'autorizzazione sull'argomento di destinazione. Il destinatario non necessita di iot:Subscribe autorizzazione: AWS IoT Core invia messaggi diretti senza richiedere l'iscrizione all'argomento. Per maggiori dettagli ed esempi di policy, consultaEsempi di policy sulla messaggistica diretta.

Per l'autenticazione e i mapping delle porte utilizzati dalle richieste HTTP, consulta Protocolli, mappature delle porte e autenticazione.

SendDirectMessage API

I mittenti possono inviare messaggi diretti effettuando richieste HTTP POST a un URL specifico del cliente:

https://IoT_data_endpoint/connections/client_id/messages?topic=topic_name&confirmation=true&timeout=10

  • IoT_data_endpointè l'endpoint dei dati del AWS IoT dispositivo. Verifica AWS IoT dati del dispositivo ed endpoint di servizio per trovare il tuo endpoint.

  • client_idè l'identificatore univoco del client MQTT a cui inviare il messaggio. Gli ID client non devono superare i 128 caratteri e non possono iniziare con il simbolo del dollaro ($). Gli ID client MQTT devono essere codificati in URL (con codifica percentuale) quando contengono caratteri non validi nelle richieste HTTP, come spazi, barre (/) e caratteri. UTF-8 Per ulteriori informazioni, vedere Limiti e quote del broker di AWS IoT Core messaggi e del protocollo.

  • topic_nameè l'argomento su cui il destinatario riceve il messaggio, URL-encoded. Non deve iniziare con $. Non deve essere un argomento AWS IoT Core riservato. Fai riferimento alla pagina delle quote AWS IoT Core di servizio per i limiti di lunghezza e profondità degli argomenti. Per ulteriori informazioni, consulta Limiti e quote di protocollo e broker di AWS IoT Core messaggi.

  • confirmationè un valore booleano. Se impostata sutrue, l'API recapita il messaggio in QoS 1 e attende che il client MQTT invii una conferma di consegna (PUBACK) prima di restituire una risposta positiva. Se la conferma di consegna non viene ricevuta entro il periodo di timeout specificato, l'API restituisce HTTP 504.

  • timeoutè un numero intero che rappresenta il tempo massimo, in secondi, di attesa di una conferma di consegna (PUBACK) dal client ricevente dopo la consegna del messaggio. Questo parametro viene utilizzato solo se confirmation è impostato su. true In caso confirmation false affermativo, questo parametro viene ignorato. Il tempo totale di risposta dell'API potrebbe essere superiore a questo valore a causa dell'elaborazione interna. Imposta il timeout del tuo client HTTP su un valore maggiore di questo parametro.

Codici di stato delle risposte API

La tabella seguente elenca i codici di stato HTTP restituiti dall' SendDirectMessage API e le azioni consigliate per ciascuno di essi. Abilita AWS IoT Core CloudWatch i registri per visualizzare i registri SendDirectMessage degli eventi dettagliati, incluso il campo del motivo per la gestione degli errori programmatici.

SendDirectMessage Codici di stato delle risposte API
Codice HTTP Azione consigliata
200 OK Se la conferma di consegna è stata richiesta conconfirmation=true, ciò indica che il destinatario ha confermato la ricezione del messaggio. Altrimenti, indica che il messaggio è stato inviato con successo.
400 Richiesta non valida Ciò significa che uno dei parametri non è valido. Esamina il messaggio o CloudWatch i log di risposta HTTP per identificare l'errore specifico e correggerlo. Verifica che il nome e l'argomento Client-id siano validi e URL-encoded corretti.
403 Non consentito Ciò significa che la politica del mittente non concede concessioni iot:SendDirectMessage sul client e sull'argomento di destinazione, oppure la politica del destinatario non concede iot:Receive concessioni sull'argomento. Esamina il messaggio o CloudWatch i log di risposta HTTP per identificare un errore specifico e aggiorna la politica corrispondente. Consulta Esempi di policy sulla messaggistica diretta.
404 Not Found (404 Non trovato) Ciò significa che l'ID del client di destinazione non è connesso a AWS IoT Core. Esamina il messaggio o CloudWatch i log di risposta HTTP per il motivo specifico, verifica che il ricevitore sia connesso e riprova. Se il messaggio di risposta indica «L'ID del client di destinazione non è connesso, ma ha una sessione persistente attiva», il client di destinazione ha una sessione persistente non scaduta ma è attualmente offline.
4.1.3 Payload troppo grande Il carico utile supera la dimensione massima consentita. Riduci le dimensioni del payload e riprova. Vedere Quote di servizio AWS IoT Core.
429 Troppe richieste Ciò significa che l'account ha superato il limite di SendDirectMessage richieste al secondo o che la connessione del destinatario ha superato il limite di pubblicazione in uscita. Esamina il messaggio o i CloudWatch log di risposta HTTP per il motivo specifico, riduci il tasso di richieste e implementa il backoff esponenziale. Vedere Quote di servizio AWS IoT Core.
500 - Errore interno del server Ciò indica un errore imprevisto sul lato server. Riprova la richiesta con un backoff esponenziale. Se il problema persiste, contatta l' AWS assistenza con il TraceID indicato nella risposta.
504 Gateway Timeout Ciò significa che il destinatario non ha inviato PUBACK entro il periodo di timeout specificato. Aumenta il valore di timeout, verifica che il client MQTT del destinatario invii messaggi PUBACK for QoS 1 o controlla se il ricevitore sta elaborando i messaggi lentamente.

Esempi

AWS CLI
aws iot-data send-direct-message \
    --client-id myDevice \
    --topic commands/reboot \
    --confirmation \
    --timeout 10 \
    --payload '{"action": "reboot"}' \
    --cli-binary-format raw-in-base64-out \
    --region us-west-2 \
    --endpoint-url https://IoT_data_endpoint

L'--cli-binary-formatopzione è obbligatoria se si utilizza la versione 2. AWS Command Line Interface Per rendere questa impostazione come predefinita, esegui aws configure set cli-binary-format raw-in-base64-out. Per ulteriori informazioni, consulta la pagina AWS CLI supported global command line options nella Guida per l'utente di AWS Command Line Interface versione 2.

curl (X.509 client certificate, port 8443)
curl --tlsv1.2 \
    --cacert Amazon-root-CA-1.pem \
    --cert device.pem.crt \
    --key private.pem.key \
    --request POST \
    --data '{"action": "reboot"}' \
    "https://IoT_data_endpoint:8443/connections/myDevice/messages?topic=commands%2Freboot&confirmation=true&timeout=10"

Comportamento del client ricevente

Direct Messaging invia messaggi ai client MQTT (ricevitori) senza richiedere un abbonamento all'argomento. Per beneficiare appieno della messaggistica diretta, il destinatario deve supportare i seguenti comportamenti:

  • Ricevi messaggi su argomenti a cui non è stato sottoscritto esplicitamente: la messaggistica diretta del destinatario può recapitare messaggi ad argomenti a cui il destinatario non si è iscritto esplicitamente. Tuttavia, alcune implementazioni del client MQTT filtrano o eliminano i messaggi sugli argomenti non sottoscritti. Se il cliente ignora questi messaggi, la messaggistica diretta funzionerà solo sugli argomenti a cui è iscritto anche il destinatario. Per ricevere messaggi diretti su qualsiasi argomento, verifica che il gestore dei messaggi del cliente elabori i messaggi indipendentemente dallo stato dell'abbonamento.

  • Gestisci il QoS determinato dall'API: il livello QoS del messaggio recapitato è impostato dal confirmation parametro nella richiesta API del mittente, non dall'abbonamento del destinatario. Quandoconfirmation=true, il messaggio arriva a QoS 1 e il client del destinatario deve inviare un PUBACK per confermare la consegna. Quandoconfirmation=false, il messaggio arriva a QoS 0 senza che sia richiesta alcuna conferma. Assicurati che l'implementazione MQTT del tuo cliente gestisca correttamente i messaggi in arrivo QoS 0 e QoS 1.