全部产品
Search
文档中心

阿里云物联网平台:BatchPub

更新时间:Jan 15, 2024

调用接口BatchPub通过自定义Topic,向指定产品下的多个设备,批量发送消息。

使用说明

  • 单批次最多向同一产品下的100个设备发送消息。
  • 调用本接口时,请求参数中TopicShortNameTopicTemplateName必须二选一使用。如果同时传入TopicShortNameTopicTemplateName,则以TopicTemplateName为准。
  • 不支持使用BatchPub接口下发设置属性和调用服务的指令。设置属性,请使用接口SetDevicePropertySetDevicesProperty;调用服务,请使用接口InvokeThingServiceInvokeThingsService

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二选一使用。如果同时传入TopicShortNameTopicTemplateName,则以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二选一使用。如果同时传入TopicShortNameTopicTemplateName,则以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
}

错误码

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