BatchPub - 阿里云物联网平台

使用说明

单批次最多向同一产品下的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
}

错误码

访问错误中心查看更多错误码。