通过

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

使用 Azure 事件网格通过 HTTP 发布 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 否 [默认值 = 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] 格式指示器
有效负载 字节 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 吞吐量配额。 监视使用情况以避免超出限制。

相关内容

  • Last updated on