调用该接口通过自定义Topic向设备发布消息，支持向指定产品下订阅了指定自定义Topic的在线设备发送广播消息。

使用说明

发送广播消息时：

  • 相关Topic是在设备开发时编码定义的，无需控制台创建。
  • 一个Topic默认最多可被1,000个设备订阅。若后续需要新增更多设备订阅自定义Topic的广播消息，可使用MQTT 5.0版本通信协议进行通信，通过设置自定义Topic支持保留消息广播和设置自定义Topic消息为保留消息来实现。使用说明，请参见UpdateTopicConfig。

使用限制

该接口不支持下发设置属性和调用服务的指令。

QPS限制

单个阿里云账号调用该接口的每秒请求数（QPS）最大限制为1600。

说明 RAM用户共享阿里云账号配额。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String 是 Pub

系统规定参数。取值：Pub。
ProductKey String 是 a1Q5XoY****

要接收消息的设备所属产品的ProductKey。
MessageContent String 是 eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=

要发送的消息主体。

您需要将消息原文转换成二进制数据，并进行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云网关设备发布消息时，需要传入该参数。
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 系统异常

调用失败时，返回的出错信息。
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
  }

错误码

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