Direktnachrichten

AWS IoT Core unterstützt jetzt Direct Messaging. Sie können eine Nachricht über dessen MQTT-Client-ID an ein einzelnes verbundenes Gerät senden, ohne dass das Gerät ein Thema abonnieren muss.

Bisher erforderte das Senden einer Nachricht an ein bestimmtes Gerät die Veröffentlichung in einem Thema, das das Gerät abonniert hatte, ohne dass es eine integrierte Möglichkeit gab, die Zustellung zu bestätigen. Der Absender ruft die SendDirectMessage HTTP-API auf und gibt dabei die Client-ID des Empfängers und ein Zielthema an. Wannconfirmation=true, AWS IoT Core liefert bei QoS 1 und wartet auf den PUBACK des Empfängers, bevor eine erfolgreiche Antwort zurückgegeben wird. Auf diese Weise erhalten Sie eine umfassende Empfangsbestätigung. API-Antwort und CloudWatch Amazon-Logs bieten einen vollständigen Überblick über den Lieferstatus und die Gründe für Fehlschläge.

Direktnachrichten werden nicht nach AWS IoT Regeln für die Regelausführung verarbeitet, werden für Offline-Geräte nicht in die Warteschlange gestellt und unterstützen keine gespeicherten Nachrichten.

Voraussetzungen

Sowohl der Absender als auch der Empfänger benötigen spezifische Richtlinienaktionen, um Direktnachrichten verwenden zu können. Der Absender muss über eine iot:SendDirectMessage entsprechende Genehmigung verfügen. Die Ziel-Client-ID wird als Ressource angegeben, und der iot:Topic Bedingungsschlüssel (optional) schränkt ein, welche Themen ein Absender Direktnachrichten senden kann. Der Empfänger muss über iot:Receive Berechtigungen für das Zielthema verfügen. Der Empfänger benötigt keine iot:Subscribe Genehmigung — er AWS IoT Core übermittelt Direktnachrichten, ohne dass ein Themenabonnement erforderlich ist. Weitere Informationen und Beispielrichtlinien finden Sie unterBeispiele für Richtlinien für Direktnachrichten.

Informationen zu den Authentifizierungs- und Portzuordnungen, die von HTTP-Anforderungen verwendet werden, finden Sie unter Protokolle, Port-Zuweisungen und Authentifizierung.

SendDirectMessage API

Absender können Direktnachrichten senden, indem sie HTTP-POST-Anfragen an eine kundenspezifische URL stellen:

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

• IoT_data_endpointist der AWS IoT Endpunkt für Gerätedaten. Suchen Sie AWS IoT Gerätedaten und Dienstendpunkte nach Ihrem Endpunkt.

• client_idist die eindeutige Kennung des MQTT-Clients, an den die Nachricht gesendet werden soll. Client-IDs dürfen 128 Zeichen nicht überschreiten und dürfen nicht mit einem Dollarzeichen ($) beginnen. MQTT-Client-IDs müssen URL-kodiert (prozentkodiert) sein, wenn sie Zeichen enthalten, die in HTTP-Anfragen nicht gültig sind, wie Leerzeichen, Schrägstriche (/) und Zeichen. UTF-8 Weitere Informationen finden Sie unter Grenzwerte und Kontingente für AWS IoT Core Nachrichtenbroker und Protokolle.

• topic_nameist das Thema, zu dem der Empfänger die Nachricht erhält, URL-encoded. Darf nicht mit $ beginnen. Darf kein AWS IoT Core reserviertes Thema sein. Informationen zu Längen- und Tiefenbeschränkungen für das Thema finden Sie auf der Seite mit den AWS IoT Core Servicekontingenten. Weitere Informationen finden Sie unter AWS IoT Core Nachrichtenbroker und Protokollbeschränkungen und -kontingente.

• confirmationist ein boolescher Wert. Wenn auf gesetzttrue, übermittelt die API die Nachricht bei QoS 1 und wartet darauf, dass der MQTT-Client eine Zustellungsbestätigung (PUBACK) sendet, bevor sie eine erfolgreiche Antwort zurückgibt. Wenn die Zustellungsbestätigung nicht innerhalb des angegebenen Timeout-Zeitraums eingeht, gibt die API HTTP 504 zurück.

• timeoutist eine Ganzzahl, die die maximale Wartezeit in Sekunden auf eine Zustellungsbestätigung (PUBACK) vom empfangenden Client nach der Zustellung der Nachricht angibt. Dieser Parameter wird nur verwendet, wenn er auf true gesetzt confirmation ist. Wenn confirmation jafalse, wird dieser Parameter ignoriert. Die gesamte API-Antwortzeit kann aufgrund der internen Verarbeitung höher als dieser Wert sein. Setzen Sie Ihr HTTP-Client-Timeout auf einen Wert, der über diesem Parameter liegt.

Statuscodes für API-Antworten

In der folgenden Tabelle sind die von der SendDirectMessage API zurückgegebenen HTTP-Statuscodes sowie die jeweils empfohlenen Aktionen aufgeführt. Aktivieren Sie AWS IoT Core CloudWatch Protokolle, um detaillierte SendDirectMessage Ereignisprotokolle einschließlich des Felds „Grund“ für die programmatische Fehlerbehandlung anzuzeigen.

SendDirectMessage Statuscodes für API-Antworten

HTTP-Code	Empfohlene Aktion
200 OK	Wenn eine Zustellungsbestätigung mit angefordert wurdeconfirmation=true, bedeutet dies, dass der Empfänger den Empfang der Nachricht bestätigt hat. Andernfalls bedeutet dies, dass die Nachricht erfolgreich versendet wurde.
400 Bad Request (400 Ungültige Anfrage)	Das bedeutet, dass einer der Parameter ungültig ist. Überprüfen Sie die HTTP-Antwortnachricht oder die CloudWatch Protokolle, um einen bestimmten Fehler zu identifizieren und ihn zu beheben. Stellen Sie sicher, dass der Name und Client-id die Themen gültig und URL-encoded korrekt sind.
403 Forbidden	Das bedeutet, dass die Richtlinie des Absenders für den Zielclient und das Zielthema keinen Zuschlag gewährtiot:SendDirectMessage, oder dass die Richtlinie des Empfängers für das iot:Receive Thema keinen Zuschlag gewährt. Überprüfen Sie die HTTP-Antwortnachricht oder die CloudWatch Protokolle, um einen bestimmten Fehler zu identifizieren, und aktualisieren Sie die entsprechende Richtlinie. Siehe Beispiele für Richtlinien für Direktnachrichten.
404 Not Found (404 Nicht gefunden)	Das bedeutet, dass mit der Ziel-Client-ID keine Verbindung besteht AWS IoT Core. Überprüfen Sie die HTTP-Antwortnachricht oder die CloudWatch Protokolle auf den spezifischen Grund, stellen Sie sicher, dass der Empfänger verbunden ist, und versuchen Sie es erneut. Wenn in der Antwortnachricht steht: „Die Ziel-Client-ID ist nicht verbunden, aber sie hat eine aktive persistente Sitzung“, hat der Zielclient eine noch nicht abgelaufene persistente Sitzung, ist aber derzeit offline.
4.1.3 Die Nutzlast ist zu groß	Die Nutzlast überschreitet die maximal zulässige Größe. Reduzieren Sie die Größe der Nutzlast und versuchen Sie es erneut. Siehe AWS IoT Core -Servicekontingente.
429 Zu viele Anfragen	Das bedeutet, dass das Konto das Limit für SendDirectMessage Anfragen pro Sekunde überschritten hat oder dass die Empfängerverbindung das Limit für ausgehende Veröffentlichungen überschritten hat. Überprüfen Sie die HTTP-Antwortnachricht oder die CloudWatch Protokolle auf den spezifischen Grund, reduzieren Sie die Anforderungsrate und implementieren Sie exponentielles Backoff. Siehe AWS IoT Core -Servicekontingente.
500 Internal Server Error	Dies deutet auf einen unerwarteten serverseitigen Fehler hin. Wiederholen Sie die Anfrage mit exponentiellem Backoff. Wenn das Problem weiterhin besteht, wenden Sie sich mit der traceId aus der Antwort an den AWS Support.
504 Gateway-Timeout	Das bedeutet, dass der Empfänger PUBACK nicht innerhalb des angegebenen Timeout-Zeitraums gesendet hat. Erhöhen Sie den Timeout-Wert, stellen Sie sicher, dass der MQTT-Client des Empfängers PUBACK für QoS 1-Nachrichten sendet, oder überprüfen Sie, ob der Empfänger Nachrichten langsam verarbeitet.

Beispiele

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

Die --cli-binary-format Option ist erforderlich, wenn Sie Version 2 verwenden. AWS Command Line Interface Um dies zur Standardeinstellung zu machen, führen Sie aws configure set cli-binary-format raw-in-base64-out aus. Weitere Informationen finden Sie unter Von AWS CLI unterstützte globale Befehlszeilenoptionen im AWS Command Line Interface -Benutzerhandbuch für Version 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"

Verhalten des Receiver-Clients

Direct Messaging übermittelt Nachrichten an MQTT-Clients (Empfänger), ohne dass ein Themenabonnement erforderlich ist. Um Direct Messaging in vollem Umfang nutzen zu können, muss der Empfänger die folgenden Verhaltensweisen unterstützen:

• Empfangen von Nachrichten zu Themen, die nicht ausdrücklich abonniert wurden — Das Direct Messaging des Empfängers kann Nachrichten zu Themen zustellen, die der Empfänger nicht ausdrücklich abonniert hat. Einige MQTT-Client-Implementierungen filtern oder verwerfen jedoch Nachrichten zu Themen, die nicht abonniert wurden. Wenn Ihr Client diese Nachrichten verwirft, funktionieren Direktnachrichten nur für Themen, die der Empfänger auch abonniert hat. Um Direktnachrichten zu einem beliebigen Thema zu erhalten, stellen Sie sicher, dass der Nachrichtenhandler Ihres Kunden Nachrichten unabhängig vom Abonnementstatus verarbeitet.

• Von der API festgelegte QoS verarbeiten — Die QoS-Stufe der zugestellten Nachricht wird durch den confirmation Parameter in der API-Anfrage des Absenders festgelegt, nicht durch das Abonnement des Empfängers. Wenn confirmation=true die Nachricht bei QoS 1 eingeht und der Client des Empfängers ein PUBACK senden muss, um die Zustellung zu bestätigen. Wannconfirmation=false, die Nachricht kommt bei QoS 0 an, ohne dass eine Bestätigung erforderlich ist. Stellen Sie sicher, dass die MQTT-Implementierung Ihres Kunden eingehende QoS 0- und QoS 1-Nachrichten korrekt verarbeitet.