IoT 中樞 資料平面 MQTT 5 API 參考 （已淘汰）
本檔定義 2.0 版（api-version： 2020-10-01-preview） IoT 中樞 數據平面 API 中可用的作業。
注意
IoT 中樞 中的 MQTT 5 支援已被取代，且 IoT 中樞 對 MQTT 的功能支援有限。 如果您的解決方案需要 MQTT v3.1.1 或 v5 支援，建議使用 Azure 事件方格中的 MQTT 支援。 如需詳細資訊，請參閱 比較 IoT 中樞和事件方格中的 MQTT 支援。
Operations
取得對應項
取得對應項狀態
Request
主題名稱： $iothub/twin/get
屬性：無
承載：空白
成功回應
屬性：無
承載：對應項
替代回應
| 狀態 | 名稱 | 描述 |
|---|---|---|
| 0100 | 不正確的要求 | 作業訊息的格式不正確且無法處理。 |
| 0101 | 未獲授權 | 用戶端未獲授權執行作業。 |
| 0102 | 不允許 | 不允許作業。 |
| 0501 | 調整執行速度 | 每個 SKU 的要求速率太高 |
| 0502 | 超過配額 | 超過每個目前 SKU 的每日配額 |
| 0601 | 伺服器錯誤 | 內部伺服器錯誤 |
| 0602 | Timeout | 作業在完成之前逾時 |
| 0603 | 伺服器忙碌 | 伺服器忙碌中 |
虛擬程式代碼範例
-> PUBLISH
QoS: 0
Topic: $iothub/twin/get
<- PUBLISH
QoS: 0
Topic: $iothub/responses
修補程式對應項報告
修補程式對應項的報告狀態
Request
主題名稱： $iothub/twin/patch/reported
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| if-version | u64 | 否 |
Payload：TwinState
成功回應
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| version | u64 | 是 | 套用修補程式之後的報告狀態版本 |
承載：空白
替代回應
| 狀態 | 名稱 | 描述 |
|---|---|---|
| 0104 | 先決條件失敗 | 不符合前置條件，導致要求遭到取消 |
| 0100 | 不正確的要求 | 作業訊息的格式不正確且無法處理。 |
| 0101 | 未獲授權 | 用戶端未獲授權執行作業。 |
| 0102 | 不允許 | 不允許作業。 |
| 0501 | 調整執行速度 | 每個 SKU 的要求速率太高 |
| 0502 | 超過配額 | 超過每個目前 SKU 的每日配額 |
| 0601 | 伺服器錯誤 | 內部伺服器錯誤 |
| 0602 | Timeout | 作業在完成之前逾時 |
| 0603 | 伺服器忙碌 | 伺服器忙碌中 |
虛擬程式代碼範例
-> PUBLISH
QoS: 0
Topic: $iothub/twin/patch/reported
[if-version: <u64>]
<- PUBLISH
QoS: 0
Topic: $iothub/responses
接收命令
接收和處理命令
訊息
主題名稱： $iothub/commands
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| sequence-no | u64 | 是 | 訊息的序號 |
| enqueued-time | time | 是 | 訊息進入系統時的時間戳 |
| delivery-count | u32 | 是 | 嘗試傳遞訊息的次數 |
| creation-time | time | 否 | 訊息建立時的時間戳（由寄件者提供） |
| message-id | string | 否 | 郵件身分識別（寄件者提供） |
| user-id | 字串 | 否 | 使用者身分識別（由寄件者提供） |
| correlation-id | string | 否 | 相互關聯身分識別（寄件者提供） |
| 內容類型 | 字串 | 否 | 決定承載的內容類型 |
| content-encoding | 字串 | 否 | 決定承載的內容編碼 |
承載：任何位元組序列
成功通知
表示用戶端已接受命令來處理
屬性：無
承載：空白
替代通知
| 原因代碼 | 狀態 | 名稱 | 描述 |
|---|---|---|---|
| 131 | 0603 | 放棄 | 表示目前不會處理命令，而且未來應該重新傳遞。 |
| 131 | 0100 | 拒絕 | 表示客戶端已拒絕命令，且不應該再次嘗試。 |
虛擬程式代碼範例
-> SUBSCRIBE
- Topic: $iothub/commands
QoS: 1
<- PUBLISH
QoS: 1
Topic: $iothub/commands
sequence-no: <u64>enqueued-time: <time>delivery-count: <u32>[creation-time: <time>][message-id: <string>][user-id: <string>][correlation-id: <string>][Content Type: <string>][content-encoding: <string>]
Payload: ...
-> PUBACK
接收直接方法
接收和處理直接方法呼叫
Request
主題名稱： $iothub/methods/{name}
屬性：無
承載：任何位元組序列
成功回應
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| response-code | u32 | 是 |
承載：任何位元組序列
替代回應
| 狀態 | 名稱 | 描述 |
|---|---|---|
| 06A0 | [無法使用] | 表示無法透過此連線連線連線連線來連線用戶端。 |
虛擬程式代碼範例
-> SUBSCRIBE
- Topic: methods/{name}
QoS: 0
<- SUBACK
<- PUBLISH
QoS: 0
Topic: $iothub/methods/{name}
-> PUBLISH
QoS: 0
Topic: $iothub/responses
接收對應項預期狀態變更
接收對應項所需狀態的更新
訊息
主題名稱： $iothub/twin/patch/desired
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| version | u64 | 是 | 符合此更新所需狀態的版本 |
Payload：TwinState
虛擬程式代碼範例
-> SUBSCRIBE
- Topic: $iothub/twin/patch/desired
QoS: 0
<- PUBLISH
QoS: 0
Topic: $iothub/twin/patch/desired
version: <u64>
Payload: ...
傳送遙測
將訊息張貼至遙測通道 - 根據預設，事件中樞或其他端點會透過路由設定。
訊息
主題名稱： $iothub/telemetry
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| 內容類型 | 字串 | 否 | 會轉譯為 content-type 張貼訊息上的系統屬性 |
| content-encoding | 字串 | 否 | 會轉譯為 content-encoding 張貼訊息上的系統屬性 |
| message-id | string | 否 | 會轉譯為 message-id 張貼訊息上的系統屬性 |
| user-id | 字串 | 否 | 會轉譯為 user-id 張貼訊息上的系統屬性 |
| correlation-id | string | 否 | 會轉譯為 correlation-id 張貼訊息上的系統屬性 |
| creation-time | time | 否 | 會轉譯為 iothub-creation-time-utc 張貼訊息上的屬性 |
提示
的格式 creation-time 必須是UTC，且沒有時區資訊。 例如，2021-04-21T11:30:16Z 為有效，而 2021-04-21T11:30:16-07:00 為無效。
承載：任何位元組序列
成功通知
已成功將訊息張貼至遙測通道
屬性：無
承載：空白
替代通知
| 原因代碼 | 狀態 | 名稱 | 描述 |
|---|---|---|---|
| 131 | 0100 | 不正確的要求 | 作業訊息的格式不正確且無法處理。 |
| 135 | 0101 | 未獲授權 | 用戶端未獲授權執行作業。 |
| 131 | 0102 | 不允許 | 不允許作業。 |
| 131 | 0601 | 伺服器錯誤 | 內部伺服器錯誤 |
| 151 | 0501 | 調整執行速度 | 每個 SKU 的要求速率太高 |
| 151 | 0502 | 超過配額 | 超過每個目前 SKU 的每日配額 |
| 131 | 0602 | Timeout | 作業在完成之前逾時 |
| 131 | 0603 | 伺服器忙碌 | 伺服器忙碌中 |
虛擬程式代碼範例
-> PUBLISH
QoS: 1
Topic: $iothub/telemetry
[Content Type: <string>]
[content-encoding: <string>]
[message-id: <string>]
[user-id: <string>]
[correlation-id: <string>]
[creation-time: <time>]
<- PUBACK
回覆
不正確的要求
作業訊息的格式不正確且無法處理。
原因碼： 131
地位： 0100
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| reason | 字串 | 否 | 包含有關訊息特定無效的資訊 |
承載：空白
衝突
作業與另一個進行中的作業發生衝突。
原因碼： 131
地位： 0103
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| trace-id | 字串 | 否 | 追蹤標識碼，用於與其他錯誤的診斷相互關聯 |
| reason | 字串 | 否 | 包含有關訊息特定無效的資訊 |
承載：空白
不允許
不允許作業。
原因碼： 131
地位： 0102
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| reason | 字串 | 否 | 包含有關訊息特定無效的資訊 |
承載：空白
未獲授權
用戶端未獲授權執行作業。
原因碼： 135
地位： 0101
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| trace-id | 字串 | 否 | 追蹤標識碼，用於與其他錯誤的診斷相互關聯 |
承載：空白
找不到
要求的資源不存在
原因碼： 131
地位： 0504
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| reason | 字串 | 否 | 包含有關訊息特定無效的資訊 |
承載：空白
未修改
資源未根據提供的前置條件進行修改。
原因碼： 0
地位： 0001
屬性：無
承載：空白
先決條件失敗
不符合前置條件，導致要求遭到取消
原因碼： 131
地位： 0104
屬性：無
承載：空白
超過配額
超過每個目前 SKU 的每日配額
原因碼： 151
地位： 0502
屬性：無
承載：空白
資源用盡
資源沒有容量可完成作業
原因碼： 131
地位： 0503
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| reason | 字串 | 否 | 包含有關訊息特定無效的資訊 |
承載：空白
伺服器忙碌
伺服器忙碌中
原因碼： 131
地位： 0603
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| trace-id | 字串 | 否 | 追蹤標識碼，用於與其他錯誤的診斷相互關聯 |
承載：空白
伺服器錯誤
內部伺服器錯誤
原因碼： 131
地位： 0601
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| trace-id | 字串 | 否 | 追蹤標識碼，用於與其他錯誤的診斷相互關聯 |
承載：空白
目標失敗
目標已回應，但回應無效或格式不正確
原因碼： 131
地位： 06A2
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| reason | 字串 | 否 | 包含有關訊息特定無效的資訊 |
承載：空白
目標逾時
等候目標完成要求的逾時
原因碼： 131
地位： 06A1
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| trace-id | 字串 | 否 | 追蹤標識碼，用於與其他錯誤的診斷相互關聯 |
| reason | 字串 | 否 | 包含有關訊息特定無效的資訊 |
承載：空白
目標無法使用
無法連線到目標以完成要求
原因碼： 131
地位： 06A0
屬性：無
承載：空白
調整執行速度
每個 SKU 的要求速率太高
原因碼： 151
地位： 0501
屬性：無
承載：空白
Timeout
作業在完成之前逾時
原因碼： 131
地位： 0602
Property：
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
| trace-id | 字串 | 否 | 追蹤標識碼，用於與其他錯誤的診斷相互關聯 |
承載：空白