调用Pub通过自定义Topic向指定设备发布消息_物联网平台(IoT)-阿里云帮助中心

使用说明

发送广播消息时：

相关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托管形态设备和MQTT云网关设备，自定义Topic为设备的原始自定义Topic。详细内容，请参见Topic说明。对于非开源MQTT托管形态设备和非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
  }