View a markdown version of this page

直接傳訊 - AWS IoT Core
先決條件SendDirectMessage API接收者用戶端行為

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

直接傳訊

AWS IoT Core 現在支援直接傳訊。您可以依 MQTT 用戶端 ID 傳送訊息至單一連線裝置，而不需要裝置訂閱主題。

先前，將訊息傳送至需要發佈至裝置訂閱之主題的特定裝置，而沒有確認交付的內建方式。寄件者呼叫 SendDirectMessage HTTP API，指定接收者的用戶端 ID 和目標主題。當 時confirmation=true， 會在 QoS 1 AWS IoT Core 傳送並等待接收者的 PUBACK，然後再傳回成功的回應。這可為您提供end-to-end交付確認。API 回應和 Amazon CloudWatch Logs 提供交付狀態和失敗原因的完整可見性。

AWS IoT 規則不會處理規則執行的直接訊息，也不會為離線裝置排入佇列，也不支援保留的訊息。

先決條件

寄件者和接收者都需要特定的政策動作，才能使用直接傳訊。寄件者必須具有 iot:SendDirectMessage 許可。目標用戶端 ID 指定為 資源，條件iot:Topic索引鍵 （選用） 會限制寄件者可以傳送直接訊息的主題。接收者必須具有目標主題的iot:Receive許可。接收者不需要iot:Subscribe許可 - 無需主題訂閱即可 AWS IoT Core 傳遞直接訊息。如需詳細資訊和範例政策，請參閱 直接傳訊政策範例。

如需 HTTP 請求所使用的身分驗證和連接埠對應的相關資訊，請參閱 通訊協定、連接埠映射和身分驗證。

SendDirectMessage API

寄件者可以透過向用戶端特定的 URL 提出 HTTP POST 請求來傳送直接訊息：

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

  • IoT_data_endpoint 是 AWS IoT 裝置資料端點。請參閱 AWS IoT 裝置資料和服務端點 尋找您的端點。

  • client_id 是要傳送訊息之 MQTT 用戶端的唯一識別符。客戶 IDs 不得超過 128 個字元，且開頭不得為貨幣符號 ($)。當 MQTT 用戶端 IDs 包含 HTTP 請求中無效的字元時，例如空格、正斜線 (/) 和 UTF-8 字元，則必須使用 URL 編碼 （百分比編碼）。如需詳細資訊，請參閱AWS IoT Core 訊息中介裝置和通訊協定限制和配額。

  • topic_name 是接收者收到 URL 編碼訊息的主題。開頭不得為 $。不得為 AWS IoT Core 預留主題。如需主題長度和深度限制，請參閱 AWS IoT Core 服務配額頁面。如需詳細資訊，請參閱AWS IoT Core 訊息中介裝置和通訊協定限制和配額。

  • confirmation 是布林值。設為 時true，API 會在 QoS 1 傳送訊息，並等待 MQTT 用戶端傳送交付確認 (PUBACK)，再傳回成功回應。如果未在指定的逾時期間內收到交付確認，API 會傳回 HTTP 504。

  • 逾時是整數，代表訊息交付後等待來自接收用戶端的交付確認 (PUBACK) 的最長時間，以秒為單位。只有在 confirmation 設定為 時，才會使用此參數true。如果 confirmation是 false，則會忽略此參數。由於內部處理，總 API 回應時間可能高於此值。將您的 HTTP 用戶端逾時設定為大於此參數的值。

API 回應狀態碼

下表列出 SendDirectMessage API 傳回的 HTTP 狀態碼，以及每個 API 的建議動作。啟用 AWS IoT Core CloudWatch 日誌以查看詳細的 SendDirectMessage 事件日誌，包括程式設計錯誤處理的原因欄位。

SendDirectMessage API 回應狀態碼
HTTP 代碼 建議的動作
200 OK 如果使用 請求交付確認confirmation=true，這表示接收者已確認收到訊息。否則，這表示訊息已成功分派。
400 錯誤的請求 這表示其中一個參數無效。檢閱 HTTP 回應訊息或 CloudWatch 日誌，以識別特定失敗和修正。確保主題名稱和 Client-id 有效且 URL 編碼正確。
403 禁止 這表示寄件者的政策不會在目標用戶端和主題iot:SendDirectMessage上授予 ，或者接收者的政策不會在主題iot:Receive上授予 。檢閱 HTTP 回應訊息或 CloudWatch 日誌以識別特定失敗，並更新對應的政策。請參閱 直接傳訊政策範例。
404 找不到 這表示目標用戶端 ID 未連線 AWS IoT Core。基於特定原因檢閱 HTTP 回應訊息或 CloudWatch 日誌，確認接收器已連線，然後再試一次。如果回應訊息指出「目標用戶端 ID 未連線，但其具有作用中的持久性工作階段」，則目標用戶端具有未過期的持久性工作階段，但目前處於離線狀態。
413 承載過大 承載超過允許的大小上限。減少承載大小並重試。請參閱AWS IoT Core 服務配額。
429 太多請求 這表示帳戶已超過 SendDirectMessage requests-per-second數限制，或接收者連線已超過傳出發佈限制。檢閱 HTTP 回應訊息或 CloudWatch 日誌以了解特定原因、降低請求率並實作指數退避。請參閱AWS IoT Core 服務配額。
500 內部伺服器錯誤 這表示未預期的伺服器端錯誤。以指數退避重試請求。如果問題仍然存在，請聯絡 AWS Support with the traceId from the response。
504 閘道逾時 這表示接收者未在指定的逾時期間內傳送 PUBACK。增加逾時值、確認接收者的 MQTT 用戶端為 QoS 1 訊息傳送 PUBACK，或檢查接收者是否處理訊息緩慢。

範例

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

如果您使用的是第 2 AWS Command Line Interface 版，則需要 --cli-binary-format選項。若要讓此成為預設的設定，請執行 aws configure set cli-binary-format raw-in-base64-out。若要取得更多資訊，請參閱《AWS Command Line Interface 使用者指南第 2 版》中 AWS CLI 支援的全域命令列選項。

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"

接收者用戶端行為

直接傳訊會傳送訊息給 MQTT 用戶端 （接收者），而不需要主題訂閱。若要完全受益於直接傳訊，接收者必須支援下列行為：

  • 接收未明確訂閱主題的訊息 — 接收者的直接傳訊可以將訊息傳遞至接收者未明確訂閱的主題。不過，有些 MQTT 用戶端實作會篩選或捨棄未訂閱主題的訊息。如果您的用戶端捨棄這些訊息，則直接傳訊僅適用於接收者也訂閱的主題。若要接收任何主題的直接訊息，請確認用戶端的訊息處理常式處理訊息，無論訂閱狀態為何。

  • 處理 API 決定的 QoS — 交付訊息的 QoS 層級是由寄件者的 API 請求中的 confirmation 參數設定，而不是由接收者的訂閱設定。當 時confirmation=true，訊息到達 QoS 1，接收者的用戶端必須傳送 PUBACK 以確認傳遞。當 時confirmation=false，訊息會到達 QoS 0，而不需要確認。確保您的用戶端的 MQTT 實作正確處理 QoS 0 和 QoS 1 傳入訊息。