通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Azure 事件网格发布 MQTT 消息（预览版）

Azure 事件网格 MQTT 代理 HTTP 发布 API 使客户能够使用标准 HTTP 请求发布消息队列遥测传输（MQTT）消息。 此功能补充了直接 MQTT 客户端连接。 它为首选 HTTP 的服务器端系统提供简单且可缩放的选项，用于服务器到设备命令和控制、更新或保留的消息管理。

注释

此功能目前处于预览状态。

主要优势：

  • 允许后端服务发送 MQTT 消息，而不会使持久 MQTT 会话保持打开状态。
  • 通过限制每客户端 MQTT 会话来帮助保护代理稳定性。
  • 确保针对源自 MQTT 和 HTTP 的消息进行一致的处理。

何时使用 HTTP 发布

请考虑在以下情况下使用 HTTP 发布：

  • 后端服务是 HTTP 本机服务，需要通过 MQTT 发送设备命令或更新。
  • 你希望在不打开 MQTT 连接的情况下管理保留的消息。
  • 你需要在不耗尽会话限制的情况下纵向扩展发布容量。

工作原理

  1. HTTP 客户端发出包含 MQTT 发布详细信息的 HTTP POST 请求。
  2. 事件网格将 HTTP 请求部分映射到标准 MQTT PUBLISH 数据包属性。
  3. 消息流经事件网格路由和扩充管道，确保传递保证并应用任何扩充或转换。

示例：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 否 [default = 1] 服务质量（QoS）级别
RETAIN 旗 0 或 1 查询 retain 或标头 mqtt-retain 否 [default = 0] 是否保留消息
响应主题 百分比编码字符串 页眉 mqtt-response-topic 否 如果需要，响应主题
相关数据 Base64 字符串 页眉 mqtt-correlation-data 否 用于跟踪的额外数据
用户属性 Base64 JSON 数组 页眉 mqtt-user-properties 否 自定义用户属性
内容类型 字符串 页眉 content-type 否 有效负载类型
消息过期间隔 无符号整数 页眉 mqtt-message-expiry 否 保留期（以秒为单位）
有效负载格式指示器 0 或 1 页眉 mqtt-payload-format-indicator 否 [default = 0] 格式指示器
有效负载 字节 HTTP 正文 否 消息正文

Notes:

  • 如果两者都存在，查询参数值将替代标头值。
  • 主题和响应主题需要百分比编码。
  • 相关数据必须经过 Base64 编码。

使用 HTTP 发布的高级步骤

  1. 准备Microsoft Entra ID 持有者令牌进行身份验证。
  2. 构造对事件网格 MQTT 代理终结点的 HTTP POST 请求。
  3. 包括所需的查询参数，如主题。
  4. 为 QoS、标志、 RETAIN 响应主题和用户属性添加可选标头。
  5. 将有效负载添加为 HTTP 正文。
  6. 发送请求。
  7. 在事件网格门户中通过日志和指标确认传递。

身份验证和授权

  • HTTP 发布使用 Microsoft Entra ID 进行身份验证。
  • 授权标头中需要持有者令牌。
  • Microsoft Entra 对象 ID 将成为 MQTT 客户端 ID。
  • AuthN/AuthZ 模型与标准 MQTT 连接保持一致。

路由和可观测性

指标和日志包括：

  • 协议： http-publish
  • 请求编号
  • 主题
  • 来源 IP地址
  • 授权主体

最佳做法

  • 尽可能使用小写标头键。 HTTP/2 标头密钥不区分大小写。
  • 监视吞吐量，因为 HTTP 消息往往大于直接 MQTT 消息。
  • 请注意，HTTP 发布与直接 MQTT 发布的消息共享吞吐量限制。

限制

HTTP 发布计入整个 MQTT 吞吐量配额。 监视使用情况以避免超出限制。

相关内容