全部產品
Search
文件中心

ApsaraMQ for MQTT:保留訊息

更新時間:Dec 05, 2025

本文為您介紹MQTT特性保留訊息。

功能介紹

保留訊息(Retained Message)是指用戶端在某個主題上發布一條訊息時,指定該訊息被伺服器保留,

後續訂閱該主題的新用戶端都將立即接收到這條保留訊息,而無需等待新的訊息發布。

使用限制

  • 目前僅專業版和鉑金版支援該功能,且需要提交工單申請。

  • 同一個主題下只能存在一條保留訊息,新發布的保留訊息會覆蓋之前的保留訊息。

  • 使用萬用字元訂閱時,限制最多模糊比對父、子Topic的數量上限為100個。

  • QoS為1或2時,用戶端串連服務端訂閱有保留訊息的主題時,保留訊息至多重試1次。用戶端串連並訂閱主題後,服務端會正常推送1次保留訊息,若服務端逾時未收到訊息確認,會重試推送,若該次重試推送仍未得到確認,則本次串連服務端不再重試推送保留訊息,直至該用戶端下一次重新串連並訂閱主題。

使用情境

  • 狀態更新:在IoT應用中,裝置可以定期更新其狀態,例如溫度、濕度等,並將該訊息保留。當新的用戶端串連並訂閱時,將立即得到裝置的最新狀態。

  • 系統配置:系統發行就緒包含某種配置資訊的保留訊息,新加入的裝置可以直接擷取最新配置資訊。

  • 最後已知值:在股票交易或者報價情境下,最後的報價可作為保留訊息發送,以確保所有新的訂閱者都可以直接擷取到最後一個交易價。

  • 歡迎資訊:例如,新客訂閱某個聊天室主題,可以立即收到該聊天室的歡迎訊息。

訊息樣本

例如,你有一個氣象站的裝置,它定期將溫度資料發布到主題"weather/station1/temperature"上。發布時,設定了保留標誌,將該訊息指定為保留訊息。

PUBLISH
Topic: weather/station1/temperature
Payload: 24.5
QoS: 1
Retain: 1 // 指示代理保留這條訊息

此後,即便這個裝置沒有發布新的溫度資料,當有新客訂閱"weather/station1/temperature"時,如下:

SUBSCRIBE
Topic Filter: weather/station1/temperature
QoS: 1

那麼,該用戶端將立刻接收到氣象站最後發布的溫度資料(即保留訊息):

PUBLISH
Topic: weather/station1/temperature
Payload: 24.5
QoS: 1
Retain: 1 // 用戶端會被告知這是一個保留的訊息

通過保留訊息,新用戶端可以立即獲得溫度狀態,而不需要等待下一次更新。這增加了系統的響應能力並為新參與者提供了即時的上下文環境。