使用 MQTT 通訊協定與 IoT 中樞通訊

本文說明裝置如何使用支援的 MQTT 行為來與 Azure IoT 中樞 通訊。 IoT 中樞 可讓裝置使用下列專案與 IoT 中樞 裝置端點通訊：

• TCP 連接埠 8883 上的 MQTT v3.1.1
• 透過 TCP 連接埠 443 上的 WebSocket 的 MQTT v3.1.1。

所有與 IoT 中樞的裝置通訊都必須使用 TLS/SSL 來保護。 因此，IoT 中樞 不支援透過 TCP 連接埠 1883 不安全的連線。

比較 IoT 中樞 和事件方格中的 MQTT 支援

IoT 中樞 不是功能完整的 MQTT 訊息代理程式，而且不支援 MQTT v3.1.1 標準中指定的所有行為。 如果您的解決方案需要 MQTT，建議您在 Azure 事件方格 中支援 MQTT。 事件方格會使用 pub-sub 傳訊模型，在彈性階層式主題上啟用 MQTT 用戶端之間的雙向通訊。 它也可讓您將 MQTT 訊息路由傳送至 Azure 服務或自定義端點，以便進一步處理。

下表說明這兩個服務之間的 MQTT 支援差異：

連線 至 IoT 中樞

裝置可以使用 MQTT 通訊協定，使用下列其中一個選項連線到 IoT 中樞：

• Azure IoT SDK。
• 直接使用 MQTT 通訊協定。

MQTT 埠 （TCP 埠 8883） 在許多公司和教育網路環境中遭到封鎖。 如果您無法在防火牆中開啟埠 8883，建議您透過 WebSocket 使用 MQTT。 透過 WebSocket 的 MQTT 會透過埠 443 進行通訊，這幾乎一律會在網路環境中開啟。 若要瞭解如何在使用 Azure IoT SDK 時透過 WebSocket 通訊協定指定 MQTT 和 MQTT，請參閱 使用裝置 SDK。

使用裝置 SDK

支援 MQTT 通訊協定的裝置 SDK 適用於 Java、Node.js、C、C#和 Python。 裝置 SDK 會使用所選 的驗證機制 來建立與 IoT 中樞的連線。 若要使用 MQTT 通訊協定，用戶端通訊協定參數必須設定為 MQTT。 您也可以在用戶端通訊協議參數中指定透過 WebSocket 的 MQTT。 根據預設，裝置 SDK 會連線到 IoT 中樞，並將 CleanSession 旗標設定為 0，並使用 QoS 1 與 IoT 中樞進行訊息交換。 雖然您可以將 QoS 0 設定為更快的訊息交換，但您應該注意傳遞不保證也不會認可。 因此， QoS 0 通常稱為「火災和忘記」。

當裝置連線到IoT中樞時，裝置SDK會提供方法，讓裝置能夠與IoT中樞交換訊息。

下表包含每個支援語言的程式代碼範例連結，並指定要用來使用 MQTT 或透過 WebSocket 通訊協定建立與 IoT 中樞 連線的參數。

下列片段顯示如何使用 Azure IoT Node.js SDK 時，透過 WebSockets 通訊協定指定 MQTT：

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').MqttWs;
var client = Client.fromConnectionString(deviceConnectionString, Protocol);

下列片段顯示如何使用 Azure IoT Python SDK 時，透過 WebSocket 通訊協定指定 MQTT：

from azure.iot.device.aio import IoTHubDeviceClient
device_client = IoTHubDeviceClient.create_from_connection_string(deviceConnectionString, websockets=True)

預設 keep-alive 逾時

為了確保用戶端/IoT 中樞 連線保持運作，服務與用戶端都會定期將保持保持運作的 Ping 傳送給彼此。 使用 IoT SDK 的用戶端會在下表中定義的間隔傳送 keep-alive：

*C# SDK 會將 MQTT KeepAliveInSeconds 屬性的預設值定義為 300 秒。 事實上，SDK 會為每個保持運作持續時間設定四次傳送 Ping 要求。 換句話說，SDK 每隔 75 秒傳送一次保持運作 Ping。

在 MQTT v3.1.1 規格之後，IoT 中樞 的 keep-alive ping 間隔是用戶端 keep-alive 值的 1.5 倍;不過，IoT 中樞 將伺服器端逾時上限限製為 29.45 分鐘（1767 秒）。 此限制存在，因為所有 Azure 服務都會系結至 Azure 負載平衡器 TCP 閑置逾時，也就是 29.45 分鐘。

例如，使用 Java SDK 的裝置會傳送保持運作 Ping，然後失去網路連線能力。 230 秒後，裝置會因為離線而錯過保持運作的 Ping。 不過，IoT 中樞 不會立即關閉連線-它會在中斷裝置連線之前再等候幾秒鐘(230 * 1.5) - 230 = 115，並404104 Device 連線 ionClosedRemotely 中斷連線。

您可以設定 1767 / 1.5 = 1177 的最大用戶端保持運作值為秒。 任何流量會重設keep-alive。 例如，成功的共用存取簽章 （SAS） 令牌重新整理會重設keep-alive。

將裝置應用程式從AMQP移轉至 MQTT

如果您使用 裝置 SDK，從使用 AMQP 切換至 MQTT 需要變更用戶端初始化中的通訊協定參數，如先前所述。

這樣做時，請務必檢查下列專案：

• AMQP 會針對許多情況傳回錯誤，而 MQTT 會終止連線。 因此，您的例外狀況處理邏輯可能需要一些變更。

• MQTT 在接收雲端到裝置訊息時不支援拒絕作業。 如果您的後端應用程式需要從裝置應用程式接收回應，請考慮使用 直接方法。

• Python SDK 不支援AMQP。

直接使用 MQTT 通訊協定 （作為裝置）

如果裝置無法使用裝置 SDK，它仍然可以使用埠 8883 上的 MQTT 通訊協定連線到公用裝置端點。

在 CONNECT 封包中，裝置應該使用下列值：

• 針對 [ ClientId ] 字段，請使用 deviceId。

• 針對[ 使用者名稱] 欄位，使用 {iotHub-hostname}/{device-id}/?api-version=2021-04-12，其中 {iotHub-hostname} 是 IoT 中樞的完整 CName 。

  例如，如果 IoT 中樞的名稱是 contoso.azure-devices.net 且裝置的名稱是 MyDevice01，則完整的 [用戶名稱] 字段應該包含：

  contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

  建議您在 欄位中包含 api-version。 否則，它可能會導致非預期的行為。

• 針對 [ 密碼 ] 欄位，使用 SAS 令牌。 SAS 令牌的格式與 HTTPS 和 AMQP 通訊協定的格式相同：

  SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

  注意

  如果您使用 X.509 憑證驗證，則不需要 SAS 令牌密碼。 如需詳細資訊，請參閱教學課程：建立和上傳用於測試的憑證，並遵循 TLS/SSL 組態一節中的程式碼指示。

  如需如何產生 SAS 令牌的詳細資訊，請參閱使用共用存取簽章控制存取 IoT 中樞 的裝置一節。

  您也可以使用適用於 Visual Studio Code 的跨平臺 Azure IoT 中樞 延伸模組或 CLI 擴充功能命令 az iot hub generate-sas-token 來快速產生 SAS 令牌。 然後，您可以將 SAS 令牌複製並貼到您自己的程式代碼中，以供測試之用。

如需直接使用 MQTT 的教學課程，請參閱 不使用裝置 SDK 使用 MQTT 來開發 IoT 裝置用戶端。

使用適用於 Visual Studio Code 的 Azure IoT 中樞 延伸模組

1. 在側邊列中，展開 [Azure IoT 中樞] 區段底下的 [裝置] 節點。

2. 以滑鼠右鍵按下您的 IoT 裝置，然後從操作選單中選取 [為裝置 產生 SAS 令牌]。

3. 在輸入方塊中輸入 SAS 令牌的到期時間，以小時為單位，然後選取 Enter 金鑰。

4. SAS 令牌會建立並複製到剪貼簿。

   產生的 SAS 令牌具有下列結構：

   HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

   要作為 使用 MQTT 連線之 [密碼 ] 欄位的這個權杖部份為：

   SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

裝置應用程式可以在 CONNECT 封包中指定 Will 訊息。 裝置應用程式應該使用 或 作為Will主題名稱，以定義要轉送為遙測訊息的Will訊息。devices/{device-id}/messages/events/{property-bag}devices/{device-id}/messages/events/ 在此情況下，如果網路連線已關閉，但先前未從裝置接收 DISCONNECT 封包，則 IoT 中樞 將 CONNECT 封包中提供的 Will 訊息傳送至遙測通道。 遙測通道可以是預設事件端點或 IoT 中樞 路由所定義的自定義端點。 訊息具有 iothub-MessageType 屬性，其值為 Will 指派給它。

直接使用 MQTT 通訊協定 （作為模組）

您可以使用模組身分識別，透過 MQTT 連線到 IoT 中樞，類似於以裝置身分連線到 IoT 中樞。 如需透過 MQTT 作為裝置連線到 IoT 中樞 的詳細資訊，請參閱直接使用 MQTT 通訊協定（作為裝置）。 不過，您必須使用下列值：

• 將用戶端識別碼設定為 {device-id}/{module-id}。

• 如果使用使用者名稱和密碼進行驗證，請將使用者名稱設定為 <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 ，並使用與模組身分識別相關聯的 SAS 令牌作為密碼。

• 作為 devices/{device-id}/modules/{module-id}/messages/events/ 發佈遙測的主題。

• 使用 devices/{device-id}/modules/{module-id}/messages/events/ 作為WILL主題。

• 做 devices/{device-id}/modules/{module-id}/# 為接收訊息的主題。

• 模組和裝置的對應項 GET 和 PATCH 主題完全相同。

• 模組和裝置的對應項狀態主題完全相同。

如需搭配模組使用 MQTT 的詳細資訊，請參閱 使用 IoT Edge 發佈和訂閱，並深入瞭解 IoT Edge 中 樞 MQTT 端點。

在沒有 Azure IoT SDK 的情況下使用 MQTT 的範例

IoT MQTT 範例存放庫包含 C/C++、Python 和 CLI 範例，示範如何傳送遙測訊息、接收雲端到裝置訊息，以及在不使用 Azure 裝置 SDK 的情況下使用裝置對應項。

C/C++ 範例使用 Eclipse Mosquitto 連結庫、Python 範例使用 Eclipse Paho，而 CLI 範例則使用 mosquitto_pub。

若要深入瞭解，請參閱 教學課程 - 使用 MQTT 來開發 IoT 裝置用戶端。

TLS/SSL 組態

若要直接使用 MQTT 通訊協定，您的用戶端 必須 透過 TLS/SSL 連線。 嘗試略過此步驟失敗，併發生連線錯誤。

若要建立 TLS 連線，您可能需要下載並參考 Azure 所使用的 DigiCert 跟證書。 從 2023 年 2 月 15 日至 10 月 15 日，Azure IoT 中樞 會將其 TLS 跟證書從 DigiCert Baltimore 跟證書移轉至 DigiCert Global Root G2。 在移轉期間，您應該在裝置上擁有這兩個憑證，以確保連線能力。 如需移轉的詳細資訊，請參閱 將IoT資源遷移至新的TT000年的詳細資訊 ，請參閱 Digicert 的網站。

下列範例示範如何使用 Eclipse Foundation 的 Paho MQTT 連結庫 Python 版本來實作此組態。

首先，從命令行環境安裝Paho連結庫：

pip install paho-mqtt

然後，在 Python 腳本中實作用戶端。 取代下列代碼段中的這些佔位元：

• <local path to digicert.cer> 是本機檔案的路徑，其中包含 DigiCert 跟證書。 您可以從適用於 C 的 Azure IoT SDK 中的 certs.c 複製憑證資訊來建立此檔案。請包含行-----BEGIN CERTIFICATE-----和 -----END CERTIFICATE-----，移除每一行開頭和結尾的標記，以及移除"\r\n每一行結尾的字元。

• <device id from device registry> 是您新增至IoT中樞之裝置的標識碼。

• <generated SAS token> 是建立之裝置的 SAS 令牌，如本文先前所述。

• <iot hub name> IoT 中樞的名稱。

from paho.mqtt import client as mqtt
import ssl

path_to_root_cert = "<local path to digicert.cer file>"
device_id = "<device id from device registry>"
sas_token = "<generated SAS token>"
iot_hub_name = "<iot hub name>"


def on_connect(client, userdata, flags, rc):
    print("Device connected with result code: " + str(rc))


def on_disconnect(client, userdata, rc):
    print("Device disconnected with result code: " + str(rc))


def on_publish(client, userdata, mid):
    print("Device sent message")


client = mqtt.Client(client_id=device_id, protocol=mqtt.MQTTv311)

client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_publish = on_publish

client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=sas_token)

client.tls_set(ca_certs=path_to_root_cert, certfile=None, keyfile=None,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)
client.tls_insecure_set(False)

client.connect(iot_hub_name+".azure-devices.net", port=8883)

client.publish("devices/" + device_id + "/messages/events/", '{"id":123}', qos=1)
client.loop_forever()

若要使用裝置憑證進行驗證，請使用下列代碼段中指定的變更來更新先前的代碼段。 如需如何準備憑證型驗證的詳細資訊，請參閱使用 X.509 CA 憑證來驗證裝置的 X.509 CA 憑證一節。

# Create the client as before
# ...

# Set the username but not the password on your client
client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=None)

# Set the certificate and key paths on your client
cert_file = "<local path to your certificate file>"
key_file = "<local path to your device key file>"
client.tls_set(ca_certs=path_to_root_cert, certfile=cert_file, keyfile=key_file,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)

# Connect as before
client.connect(iot_hub_name+".azure-devices.net", port=8883)

傳送裝置到雲端訊息

裝置連線之後，可以使用 或 devices/{device-id}/messages/events/{property-bag} 作為主題名稱，將訊息傳送至 IoT 中樞devices/{device-id}/messages/events/。 元素 {property-bag} 可讓裝置以 URL 編碼格式傳送具有其他屬性的訊息。 例如：

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…

下列清單描述 IoT 中樞 特定實作行為：

• IoT 中樞 不支援QoS 2訊息。 如果裝置應用程式發佈具有 QoS 2 的訊息，IoT 中樞 關閉網路連線。

• IoT 中樞 不會保存保留訊息。 如果裝置傳送的訊息，並將 RETAIN 旗標設為 1，IoT 中樞 將 mqtt-retain 應用程式屬性新增至訊息。 在此情況下，IoT 中樞 傳遞至後端應用程式，而不是保存保留訊息。

• IoT 中樞僅支援每台裝置一個作用中的 MQTT 連線。 任何代表相同裝置標識碼的新 MQTT 聯機會導致 IoT 中樞 卸除現有的連線，400027 連線 ionForcefullyClosedOnNew 連線 ion 會登入 IoT 中樞 記錄

• 若要根據訊息本文路由傳送訊息，您必須先將屬性 『contentType』 （ct） 新增至 MQTT 主題結尾，並將其值設定為 ， application/json;charset=utf-8 如下列範例所示。 如需根據訊息屬性或訊息本文路由訊息的詳細資訊，請參閱 IoT 中樞 訊息路由查詢語法檔。

  devices/{device-id}/messages/events/$.ct=application%2Fjson%3Bcharset%3Dutf-8

如需詳細資訊，請參閱使用 IoT 中樞 傳送裝置到雲端和雲端到裝置訊息。

接收雲端到裝置訊息

若要從 IoT 中樞 接收訊息，裝置應該使用 devices/{device-id}/messages/devicebound/# 作為主題篩選來訂閱。 主題篩選中的多層級通配符 # 只會用來允許裝置在主題名稱中接收更多屬性。 IoT 中樞 不允許使用 # 或 ? 通配符來篩選子主題。 由於 IoT 中樞 不是一般用途的pub-sub訊息代理程式，因此它只支援記載的主題名稱和主題篩選。 裝置一次只能訂閱五個主題。

裝置在成功訂閱由主題篩選所代表的裝置特定端點之前，不會收到來自 IoT 中樞的任何devices/{device-id}/messages/devicebound/#訊息。 建立訂用帳戶之後，裝置會收到在訂用帳戶之後傳送到它的雲端到裝置訊息。 如果裝置連線到設定為 0 的 CleanSession 旗標，訂用帳戶會跨不同的會話保存。 在此情況下，下次裝置與 CleanSession 0 連線時，會在中斷連線時收到傳送給它的任何未完成訊息。 不過，如果裝置使用設定為 1 的 CleanSession 旗標，則在訂閱其裝置端點之前，它不會收到來自 IoT 中樞 的任何訊息。

IoT 中樞 使用 傳遞訊息主題名稱devices/{device-id}/messages/devicebound/，或devices/{device-id}/messages/devicebound/{property-bag}有訊息屬性時。 {property-bag} 包含訊息屬性的 URL 編碼索引鍵/值組。 屬性包中只會包含應用程式屬性和用戶可設定的系統屬性（例如 messageId 或 correlationId）。 系統屬性名稱具有前置詞 $，應用程式屬性會使用沒有前置詞的原始屬性名稱。 如需屬性包格式的詳細資訊，請參閱 傳送裝置到雲端訊息。

在雲端到裝置訊息中，屬性包中的值如下表所示：

下列範例顯示包含三個應用程式屬性的屬性包： prop1 ，值為 null; prop2，空字串串 （“”）：和 prop3 ，其值為 “a string”。

/?prop1&prop2=&prop3=a%20string

當裝置應用程式訂閱 QoS 2 的主題時，IoT 中樞 在 SUBACK 封包中授與最大 QoS 層級 1。 之後，IoT 中樞 使用QoS 1將訊息傳遞至裝置。

擷取裝置對應項的屬性

首先，裝置會 $iothub/twin/res/#訂閱 ，以接收作業的回應。 然後，它會將空白訊息傳送至主題$iothub/twin/GET/?$rid={request id}，並填入要求標識碼的值。 接著，服務會使用與要求相同的要求標識符，傳送回應訊息，其中包含主題$iothub/twin/res/{status}/?$rid={request-id}上的裝置對應項數據。

要求標識碼可以是訊息屬性值的任何有效值，而狀態會驗證為整數。 如需詳細資訊，請參閱使用 IoT 中樞 傳送裝置到雲端和雲端到裝置訊息。

回應本文包含裝置對應項的屬性區段，如下列回應範例所示：

{
    "desired": {
        "telemetrySendFrequency": "5m",
        "$version": 12
    },
    "reported": {
        "telemetrySendFrequency": "5m",
        "batteryLevel": 55,
        "$version": 123
    }
}

可能的狀態代碼如下：

如需詳細資訊，請參閱瞭解和使用 IoT 中樞 中的裝置對應項。

更新裝置對應項的報告屬性

若要更新報告的屬性，裝置會透過指定的 MQTT 主題發出透過發行集 IoT 中樞 的要求。 IoT 中樞 處理要求之後，它會透過發行集回應更新作業的成功或失敗狀態給另一個主題。 裝置可以訂閱本主題，以通知其對應項更新要求的結果。 為了在 MQTT 中實作這種類型的要求/回應互動，我們會使用裝置最初在其更新要求中提供的要求標識碼概念。$rid 此要求標識碼也會包含在來自 IoT 中樞 的回應中，以允許裝置將回應與其特定先前的要求相互關聯。

下列順序說明裝置如何更新裝置對應項中的報告屬性，IoT 中樞：

1. 裝置必須先訂閱$iothub/twin/res/#主題，才能從 IoT 中樞 接收作業的回應。

2. 裝置會將包含裝置對應項更新的 $iothub/twin/PATCH/properties/reported/?$rid={request-id} 訊息傳送至主題。 此訊息包含 要求識別碼 值。

3. 接著，服務會傳送回應訊息，其中包含主題 $iothub/twin/res/{status}/?$rid={request-id}上報告屬性集合的新ETag值。 此回應消息會使用與要求相同的 要求標識碼 。

要求訊息本文包含 JSON 檔，其中包含報告屬性的新值。 JSON 檔中的每個成員都會更新或新增裝置對應項檔中的對應成員。 要從包含物件中刪除成員的成員集 null 。 例如：

{
    "telemetrySendFrequency": "35m",
    "batteryLevel": 60
}

可能的狀態代碼如下：

下列 Python 代碼段示範使用 Paho MQTT 用戶端透過 MQTT 的對應項報告屬性更新程式：

from paho.mqtt import client as mqtt

# authenticate the client with IoT Hub (not shown here)

client.subscribe("$iothub/twin/res/#")
rid = "1"
twin_reported_property_patch = "{\"firmware_version\": \"v1.1\"}"
client.publish("$iothub/twin/PATCH/properties/reported/?$rid=" +
               rid, twin_reported_property_patch, qos=0)

在先前代碼段中成功報告對應項屬性更新程式時，來自 IoT 中樞 的發行集訊息具有下列主題：$iothub/twin/res/204/?$rid=1&$version=6，其中 204 是指出成功的狀態代碼，$rid=1會對應至程式碼中裝置所提供的要求標識符，並$version對應至更新後裝置對應項的回報屬性區段版本。

如需詳細資訊，請參閱瞭解和使用 IoT 中樞 中的裝置對應項。

接收所需的屬性更新通知

當裝置連線時，IoT 中樞 傳送通知至主題 $iothub/twin/PATCH/properties/desired/?$version={new-version}，其中包含解決方案後端所執行更新的內容。 例如：

{
    "telemetrySendFrequency": "5m",
    "route": null,
    "$version": 8
}

至於屬性更新， null 值表示正在刪除 JSON 對象成員。 此外， $version 表示對應項之所需屬性區段的新版本。

如需詳細資訊，請參閱瞭解和使用 IoT 中樞 中的裝置對應項。

回應直接方法

首先，裝置必須訂閱 $iothub/methods/POST/#。 IoT 中樞 使用有效的 JSON 或空白主體，將方法要求傳送至主題$iothub/methods/POST/{method-name}/?$rid={request-id}。

為了回應，裝置會將具有有效 JSON 或空白本文的訊息傳送至主題 $iothub/methods/res/{status}/?$rid={request-id}。 在此訊息中 ，要求標識碼 必須符合要求訊息中的標識碼，而 狀態 必須是整數。

如需詳細資訊，請參閱瞭解並叫用來自 IoT 中樞 的直接方法。

下一步

若要深入瞭解如何使用 MQTT，請參閱：

• MQTT 檔
• 使用 MQTT 在不使用裝置 SDK 的情況下開發 IoT 裝置用戶端
• MQTT 應用程式範例

若要深入瞭解如何使用IoT裝置 SDKS，請參閱：

• Azure IoT SDK

若要深入瞭解規劃您的 IoT 中樞 部署，請參閱：

• 如何使用 IoT Edge 裝置作為閘道
• 將 IoT 裝置 連線 至 Azure：IoT 中樞 和事件中樞
• 選擇適合您解決方案的 IoT 中樞層