Pub - IoT Platform

使用說明

發送廣播訊息時：

相關Topic是在裝置開發時編碼定義的，無需控制台建立。
一個Topic預設最多可被1,000個裝置訂閱。若後續需要新增更多裝置訂閱自訂Topic的廣播訊息，可使用MQTT 5.0版本通訊協定進行通訊，通過設定自訂Topic支援保留訊息廣播和設定自訂Topic訊息為保留訊息來實現。使用說明，請參見UpdateTopicConfig。

使用限制

該介面不支援下發設定屬性和調用服務的指令。

設定屬性，請使用SetDeviceProperty或SetDevicesProperty。
調用服務，請使用InvokeThingService或InvokeThingsService。

QPS限制

單個阿里雲帳號調用該介面的每秒請求數（QPS）最大限制為1600。

說明單個阿里雲帳號下的所有RAM使用者共用該阿里雲帳號的配額。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

請求參數

名稱	類型	是否必選	樣本值	描述
Action	String	是	Pub	系統規定參數。取值：Pub。
ProductKey	String	是	a1Q5XoY****	要接收訊息的裝置所屬產品的ProductKey。
MessageContent	String	是	eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=	要發送的訊息內容。您需要將訊息原文轉換成位元據，並進行Base64編碼，從而產生訊息內容。說明物聯網平台會先對訊息內容進行Base64解碼，再將解碼後的對應訊息發送給裝置。裝置端無需進行Base64解碼。
TopicFullName	String	是	/a1Q5XoY****/device1/user/get	要接收訊息的裝置的自訂Topic。對於MQTT雲網關裝置，自訂Topic為裝置的原始自訂Topic。詳細內容，請參見Topic說明。對於非MQTT雲網關裝置，自訂Topic的格式支援為： `/${productKey}/${deviceName}/user/${TopicShortName}`：發送訊息到指定ProductKey的指定裝置。 `/broadcast/${productKey}/${自訂欄位}`：發送訊息到指定ProductKey下已訂閱該Topic的線上裝置。`${productKey}`是要接收廣播訊息的具體產品的ProductKey；`${自訂欄位}`為您自訂的任意欄位。重要 Topic的操作許可權必須為訂閱或發布和訂閱。調用該介面前，裝置必須已訂閱該Topic且未取消，否則無法接收本次發布的訊息。查詢自訂Topic方法：調用QueryProductTopic介面，查詢產品下的自訂Topic。在物聯網平台控制台產品詳情頁面的Topic類列表頁簽下，查詢產品下的自訂Topic。在物聯網平台控制台裝置詳情頁面的Topic列表頁簽下，查看裝置已訂閱的自訂Topic。
IotInstanceId	String	否	iot-cn-0pp1n8t****	執行個體ID。您可在物聯網平台控制台的執行個體概覽頁面，查看當前執行個體的ID。重要若有ID值，必須傳入該ID值，否則調用會失敗。若無執行個體概覽頁面或ID值，則無需傳入。執行個體的更多資訊，請參見執行個體概述。
Qos	Integer	否	0	指定訊息的發送方式。取值： 0：最多發送一次。 1：最少發送一次。如果QoS=1訊息未接收到PUBACK訊息，會在裝置重連時，重新推送給裝置。如果不傳入此參數，則使用預設值0。通訊訊息的更多使用說明，請參見使用限制的串連通訊。
ResponseTopic	String	否	/a1Q5XoY****/device1/user/update	使用MQTT 5.0版本通訊協定時，請求和響應模式中的響應主題，即通訊的Topic。更多訊息，請參見MQTT 5.0協議說明。
CorrelationData	String	否	aGVsbG8****	使用MQTT 5.0版本通訊協定時，請求和響應模式中的相關資料，使用者可自訂。訊息接收方可根據相關資料處理請求。說明您需要將相關資料轉換為位元據，並進行Base64編碼，從而產生String類型資料。
UserProp.N.Key	String	否	key1	使用MQTT 5.0版本通訊協定時，使用者自訂屬性的Key。需要與UserProp.N.Value成對使用。
UserProp.N.Value	String	否	value1	使用MQTT 5.0版本通訊協定時，使用者自訂屬性的Value。需要與UserProp.N.Key成對使用。
DeviceName	String	否	device1	MQTT雲網關裝置的名稱。重要僅當需要向指定MQTT雲網關裝置發布訊息時，需要傳入該參數。
ContentType	String	否	text	使用MQTT 5.0版本通訊協定時，發布訊息的內容類型。應用於存放MIME類型檔案，例如，文字檔類型：text、plain。
PayloadFormatIndicator	Integer	否	1	使用MQTT 5.0版本通訊協定時，發布訊息的有效載荷標識，可取值： 0：訊息是未確定的位元組資料。 1：訊息的有效載荷是UTF-8編碼的字元資料。
Retained	Boolean	否	true	使用MQTT 5.0版本通訊協定時，該欄位用於標識是否是保留訊息。 true：是。 false：否。
MessageExpiryInterval	Long	否	2	使用MQTT 5.0版本通訊協定時，訊息的到期時間，單位是秒。 QoS 0訊息支援的到期時間範圍：0~86400秒。 QoS 1訊息支援的到期時間範圍：0~604800秒。
TopicAlias	Integer	否	123	使用MQTT 5.0版本通訊協定時，可設定主題別名，用於減少裝置端和雲端的通訊流量。重要主題別名的實現依賴主題和別名的映射關係，裝置端和阿里雲物聯網平台都需要維護相應的映射關係。該映射關係會在初次使用別名時添加，並在串連斷開時刪除，因此重新串連的裝置需要重新完成主題和別名的映射。別名不能重複，Topic和別名是一一對應關係。如果使用主題別名，請勿並發發布訊息。否則，因為雲端分布式的特點，可能導致並發的訊息丟失。如果使用主題別名，需在每次調用Pub介面時，都傳入請求參數TopicAlias。每個裝置支援的主題別名數量最多為20，即每個裝置的下行訊息支援最多使用20個主題別名。主題別名的更多使用說明，請參見MQTT 5.0特性的主題別名。

調用API時，除了本文介紹的該API的特有請求參數，還需傳入公用請求參數。公用請求參數說明，請參見公用參數文檔。

返回資料

名稱	類型	樣本值	描述
Code	String	iot.system.SystemException	調用失敗時，返回的錯誤碼。更多資訊，請參見錯誤碼。
ErrorMessage	String	系統異常	調用失敗時，返回的出錯資訊。
MessageId	String	889455942124347329	成功發送訊息後，雲端產生的訊息ID，用於標識該訊息。
RequestId	String	BB71E443-4447-4024-A000-EDE09922891E	阿里雲為該請求產生的唯一識別碼。
Success	Boolean	true	是否調用成功。 true：調用成功。 false：調用失敗。

樣本

請求樣本

https://iot.cn-shanghai.aliyuncs.com/?Action=Pub
&ProductKey=a1Q5XoY****
&TopicFullName=/a1Q5XoY****/device1/user/get
&MessageContent=eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=
&Qos=0
&ResponseTopic=/a1Q5XoY****/device1/user/update
&CorrelationData=aGVsbG8%3D****
&UserProp.1.Key=k1&UserProp.1.Value=v1
&<公用請求參數>

正常返回樣本

XML格式

<PubResponse>
    <RequestId>BB71E443-4447-4024-A000-EDE09922891E</RequestId>
    <Success>true</Success>
    <MessageId>889455942124347329</MessageId>
</PubResponse>

JSON格式

{
      "RequestId":"BB71E443-4447-4024-A000-EDE09922891E",
      "Success":true,
      "MessageId":889455942124347329
  }

錯誤碼

訪問錯誤中心查看更多錯誤碼。