全部产品
Search
文档中心

阿里云物联网平台:Pub

更新时间:Mar 07, 2024

调用该接口通过自定义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编码,从而生成消息内容。

说明 物联网平台会先对消息内容进行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类型文件,例如,文本文件类型:textplain

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
  }

错误码

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