BatchPub - IoT Platform

使用說明

單批次最多向同一產品下的100個裝置發送訊息。
調用本介面時，請求參數中TopicShortName與TopicTemplateName必須二選一使用。如果同時傳入TopicShortName和TopicTemplateName，則以TopicTemplateName為準。
不支援使用BatchPub介面下發設定屬性和調用服務的指令。設定屬性，請使用介面SetDeviceProperty或SetDevicesProperty；調用服務，請使用介面InvokeThingService或InvokeThingsService。

QPS限制

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

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

調試

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

請求參數

名稱	類型	是否必選	樣本值	描述
Action	String	是	BatchPub	系統規定參數。取值：BatchPub。
DeviceName.N	RepeatList	是	newdevice1	要接收訊息的裝置名稱。說明與ProductKey結合使用，傳入裝置必須屬於同一產品。單次調用，最多傳入100個裝置名稱，且裝置名稱不可重複。
MessageContent	String	是	eyJ0ZXN0IjoidGFzayBiYXRjaHB1YiBicm9hZGNhc3QifQ==	要發送的訊息內容。最大報文256 KB。您需要將訊息原文轉換成位元據，並進行Base64編碼，從而產生訊息內容。說明物聯網平台會先對訊息內容進行Base64解碼，再將解碼後的對應訊息發送給裝置。裝置端無需進行Base64解碼。
ProductKey	String	是	a1BwAGV****	要發送訊息的產品ProductKey。
IotInstanceId	String	否	iot-cn-0pp1n8t****	執行個體ID。您可在物聯網平台控制台的執行個體概覽頁面，查看當前執行個體的ID。重要若有ID值，必須傳入該ID值，否則調用會失敗。若無ID值，則無需傳入。執行個體的更多資訊，請參見執行個體概述。
Qos	Integer	否	0	指定訊息的發送方式。取值： 0（預設）：最多發送一次。 1：最少發送一次。如果QoS=1訊息未接收到PUBACK訊息，會在裝置重連時，重新推送給裝置。說明 QoS=1的訊息在物聯網平台中最多可以儲存7天。物聯網平台不儲存QoS=0的訊息。通訊訊息的更多使用說明，請參見使用限制的串連通訊。
TopicShortName	String	否	get	要發送訊息的自訂Topic的尾碼。自訂Topic的格式為`/${productKey}/${deviceName}/user/${TopicShortName}`，該參數傳入尾碼`${TopicShortName}`。該參數與TopicTemplateName二選一使用。如果同時傳入TopicShortName和TopicTemplateName，則以TopicTemplateName為準。說明指定Topic的操作許可權須為訂閱，或發布和訂閱，且所有裝置已訂閱該Topic。您可通過以下途徑查看自訂Topic：在產品詳情頁的Topic類列表頁簽下，查看產品下的自訂Topic。在裝置詳情頁的Topic列表頁簽下，查看裝置已訂閱的自訂Topic。調用QueryProductTopic介面查詢產品下的自訂Topic。
TopicTemplateName	String	否	/a1BwAGV****/${deviceName}/user/test	要發送訊息的自訂Topic的模板，自訂Topic的格式為`/${productKey}/${deviceName}/user/${TopicShortName}`。傳入該參數時`${productKey}`和`${TopicShortName}`需為具體值，例如`/a1BwAGV**/${deviceName}/user/test`。其中`${productKey}`值需與傳入的ProductKey參數值一致。該參數與TopicShortName二選一使用。如果同時傳入TopicShortName和TopicTemplateName，則以TopicTemplateName為準。說明指定Topic的操作許可權須為訂閱，或發布和訂閱，且所有裝置已訂閱該Topic。您可通過以下途徑查看自訂Topic：在產品詳情頁的Topic類列表頁簽下，查看產品下的自訂Topic。在裝置詳情頁的Topic列表**頁簽下，查看裝置已訂閱的自訂Topic。調用QueryProductTopic介面查詢產品下的自訂Topic。
ResponseTopicTemplateName	String	否	/a1BwAGV****/${deviceName}/user/update	如果需要裝置接收訊息返迴響應訊息，需設定返迴響應訊息的自訂Topic模板。Topic的格式為`/${productKey}/${deviceName}/user/${自訂名稱}`。傳入該參數時`${productKey}`和`${自訂名稱}`需為具體值，例如`/a1BwAGV**/${deviceName}/user/update`。其中`${productKey}`值需與傳入的ProductKey參數值一致。說明指定Topic的操作許可權須為發布，或發布和訂閱**。
UserProp.N.Key	String	否	key1	使用MQTT 5.0版本通訊協定時，使用者自訂屬性的Key。需要與UserProp.N.Value成對使用。
UserProp.N.Value	String	否	key1	使用MQTT 5.0版本通訊協定時，使用者自訂屬性的Value。需要與UserProp.N.Key成對使用。
CorrelationData	String	否	aGVsbG8%3D****	使用MQTT 5.0版本通訊協定時，請求和響應模式中的相關資料，使用者可自訂。訊息接收方可根據相關資料處理請求。說明您需要將相關資料轉換為位元據，並進行Base64編碼，從而產生String類型資料。
PayloadFormatIndicator	Integer	否	1	使用MQTT 5.0版本通訊協定時，發布訊息的有效載荷標識，可取值： 0：訊息是未確定的位元組資料。 1：訊息的有效載荷是UTF-8編碼的字元資料。
ContentType	String	否	text	使用MQTT 5.0版本通訊協定時，發布訊息的內容類型。應用於存放MIME類型檔案，例如，文字檔類型：text、plain。
MessageExpiryInterval	Long	否	2	使用MQTT 5.0版本通訊協定時，訊息的到期時間，單位是秒。 QoS 0訊息支援的到期時間範圍：0~86400秒。 QoS 1訊息支援的到期時間範圍：0~604800秒。
Retained	Boolean	否	true	使用MQTT 5.0版本通訊協定時，該欄位用於標識是否是保留訊息。 true：是。 false：否。

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

返回資料

名稱	類型	樣本值	描述
Code	String	iot.system.SystemException	調用失敗時，返回的錯誤碼。更多資訊，請參見錯誤碼。
ErrorMessage	String	系統異常	調用失敗時，返回的出錯資訊。
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	阿里雲為該請求產生的唯一識別碼。
Success	Boolean	true	表示是否調用成功。 true：調用成功。 false：調用失敗。

樣本

請求樣本

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=BatchPub
&DeviceName.1=newdevice1
&MessageContent=eyJ0ZXN0IjoidGFzayBiYXRjaHB1YiBicm9hZGNhc3QifQ==
&ProductKey=a1BwAGV****
&TopicShortName=get
&<公用請求參數>

正常返回樣本

XML格式

<BatchPubResponse>
  <RequestId>9E76053E-26ED-4AB4-AE58-8AFC3F1E7E8E</RequestId>
  <Success>true</Success>
</BatchPubResponse>

JSON格式

{
  "RequestId": "9E76053E-26ED-4AB4-AE58-8AFC3F1E7E8E",
  "Success": true
}

錯誤碼

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