Azure 事件方格 MQTT 代理程式 HTTP 發佈 API 可讓客戶使用標準 HTTP 要求來發佈訊息佇列遙測傳輸 (MQTT) 訊息。 此功能補充了直接 MQTT 用戶端連線。 它為那些偏好使用 HTTP 進行伺服器到裝置命令和控制、更新或保留訊息管理的伺服器端系統提供了一個簡單且可調整的選項。
備註
此功能目前為預覽狀態。
主要優點：
- 容許後端服務傳送 MQTT 訊息，而無需保持續性的 MQTT 工作階段開啟。
- 透過限制每個用戶端的 MQTT 工作階段數，來協助保護代理程式的穩定性。
- 確保對源自 MQTT 和 HTTP 的訊息進行一致的處理。
何時使用 HTTP 發佈
在以下情況下考慮使用 HTTP 發佈：
- 您的後端服務是原生 HTTP 服務，且需要透過 MQTT 傳送裝置命令或更新。
- 您希望在不開啟 MQTT 連線的情況下管理保留的訊息。
- 您需要在不超出工作階段限制的情況下擴大發佈容量。
運作方式
- HTTP 用戶端會發出包含 MQTT 發佈詳細資料的 HTTP
POST要求。 - 事件方格會將 HTTP 要求部分對應到標準的 MQTT PUBLISH 封包屬性。
- 訊息會流經事件方格路由和擴充管線，以確保傳遞保證並套用任何擴充或轉換。
範例：MQTT 發佈等效項
PUBLISH Topic Name: devices/CXa-23112/prompt
QoS: 1
RETAIN: 0
Response Topic: devices/CXa-23112/reply
Correlation Data: >U±¶¶»/
User Property: Urgency = alert
User Property: RequestId = 55f4a7ee-b0b4-4d7f-8eb5-2edba2ced5d7
Payload: Please accept terms of licensing and agreement
範例：HTTP 發佈要求
POST /mqtt/messages?topic=devices%2FCXa-23112%2Fprompt&api-version=2025-02-15-preview HTTP/1.1
Host: nsname.westus3-1.ts.eventgrid.azure.net
Authorization: Bearer <ENTRA_TOKEN_HERE>
mqtt-qos: 1
mqtt-retain: 0
mqtt-response-topic: devices%2FCXa-23112%2Freply
mqtt-correlation-data: PlXCscK2wrbCuy8=
mqtt-user-properties: W3siVXJnZW5jeSI6ImFsZXJ0In0seyJSZXF1ZXN0SWQiOiI1NWY0YTdlZS1iMGI0LTRkN2YtOGViNS0yZWRiYTJjZWQ1ZDcifV0=
Content-Type: text/plain;charset=UTF-8
Date: Sun, 06 Nov 1994 08:49:37 GMT
Content-Length: 46
Please accept terms of licensing and agreement
要求參數
下表說明了 HTTP 要求部分如何對應到 MQTT PUBLISH 封包屬性。 如需完整詳細資料，請參閱原始文件。
| MQTT 發佈部分 | 類型/值 | 地點 | 為必填項目 | Description |
|---|---|---|---|---|
| 主題名稱 | 百分比編碼的字串 | 查詢 topic |
是的 | 要發佈的 MQTT 主題 |
| QoS | 0 或 1 | 查詢 qos 或標頭 mqtt-qos |
否 [預設值 = 1] | 服務品質 (QoS) 層級 |
RETAIN 旗標 |
0 或 1 | 查詢 retain 或標頭 mqtt-retain |
否 [預設值 = 0] | 是否保留訊息 |
| 回應主題 | 百分比編碼的字串 | 標頭 mqtt-response-topic |
否 | 回應主題 (若需要的話) |
| 相互關聯資料 | Base64 字串 | 標頭 mqtt-correlation-data |
否 | 用於追蹤的額外資料 |
| 使用者屬性 | Base64 JSON 陣列 | 標頭 mqtt-user-properties |
否 | 自訂使用者屬性 |
| 內容類型 | 繩子 | 標頭 content-type |
否 | 承載類型 |
| 訊息到期間隔 | 不帶正負號的整數 | 標頭 mqtt-message-expiry |
否 | 保留期間 (以秒為單位) |
| 承載格式指示器 | 0 或 1 | 標頭 mqtt-payload-format-indicator |
否 [預設值 = 0] | 格式指示器 |
| 承載 | Bytes | HTTP 主體 | 否 | 訊息內文 |
Notes:
- 查詢參數值會覆寫標頭值 (若兩項都存在的話)。
- 主題和回應主題必須使用百分比編碼。
- 相互關聯資料必須以 Base64 格式編碼。
使用 HTTP 發佈的高階步驟
- 準備您的 Microsoft Entra ID 持有人權杖來進行驗證。
- 建構傳送到事件方格 MQTT 代理程式端點的 HTTP
POST要求。 - 包含必要的查詢參數，例如 topic。
- 新增 QoS、
RETAIN旗標、回應主題和使用者屬性的選用標頭。 - 將您的承載新增為 HTTP 主體。
- 傳送要求。
- 透過事件方格入口網站中的記錄和計量確認傳遞狀態。
身份驗證與授權
- HTTP 發佈會使用 Microsoft Entra ID 來進行驗證。
- 授權標頭中需要持有人權杖。
- Microsoft Entra 物件識別碼會變成 MQTT 用戶端識別碼。
- AuthN/AuthZ 模型與標準 MQTT 連線一致。
路由傳送和可檢視性
計量和記錄包括：
- 通訊協定：
http-publish - 請求編號
- 主題
- 來源 IP
- 授權主體
最佳做法
- 盡可能使用小寫的標頭索引鍵。 HTTP/2 標頭索引鍵不區分大小寫。
- 監視傳輸量，因為 HTTP 訊息通常比直接的 MQTT 訊息大。
- 請注意，HTTP 發佈會與直接的 MQTT 發佈訊息共用輸送量限制。
節流
HTTP 發佈會計入您的整體 MQTT 輸送量配額。 監視您的使用量以避免超過限制量。