调用MassPush批量推送。

接口说明

在某种业务场景中,可能需要在极短时间内大量向不同设备单推不同消息,在设备数、消息数极大时,会产生较高QPS,达到我们单来源IP的QPS限制,造成部分推送失败。

本接口针对此问题设计。它支持单次调用最大传入100个独立的推送任务,通过聚合请求的方式有效降低QPS,提高大量单推的稳定性和成功率。批量推送单账号限制每分钟100000调用。

每个独立推送任务仅支持根据设备/账号/别名三类推送目标,且暂不支持短信融合配置。

说明 SDK需升级到3.11.0及以上版本。

PushTask属性

  • PushTask属性格式为:PushTask.N.Property。包含:
    • 推送目标(destination)
    • 推送配置(config)
    • iOS通知任务配置
    • Android通知任务配置
    • Android辅助弹窗功能配置
    • 推送控制(push control)
  • 每一个PushTask表示一个独立推送任务,最大支持100个,推送相关配置,和Push接口一致。
  • PushTask.N.Target参数只支持DEVICE、ACCOUNT、ALIAS三种类型。
  • PushTask不支持短信融合配置。
  • 父节点和子节点的乘积不能超过10000,否则视为参数无效。

调试

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

请求参数

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

系统规定参数。取值:MassPush。

AppKey Long 23267207

AppKey信息。

PushTask.N.Body String hello

Android推送时通知的内容/消息的内容;iOS消息/通知内容,推送的内容大小是有限制的,参见产品限制

PushTask.N.DeviceType String ALL

设备类型,取值范围为:

  • iOS:iOS设备
  • ANDROID:Android设备
  • ALL:全部类型设备
说明 该参数仅对旧的不分端App有意义。新的分端App下,该参数填写”ALL”或与App分端类型对应的值均可。
PushTask.N.PushType String MESSAGE

推送类型。取值:

  • MESSAGE:表示消息。
  • NOTICE:表示通知。
PushTask.N.Target String DEVICE

推送目标。可取值:

  • DEVICE:根据设备推送。
  • ACCOUNT:根据账号推送。
  • ALIAS:根据别名推送。
PushTask.N.TargetValue String deviceid1,deviceid2

根据Target来设定,多个值使用逗号分隔,超过限制需要分多次推送。

  • Target=DEVICE,值如deviceid1,deviceid2(最多支持1000个)。
  • Target=ACCOUNT,值如account1,account2(最多支持1000个)。
  • Target=ALIAS,值如alias1,alias2(最多支持1000个)。
PushTask.N.Title String title

Android推送时通知/消息的标题以及iOS消息的标题(必填)。iOS 10+通知显示标题,(iOS 8.2 <= iOS系统 < iOS 10)替换通知应用名称(选填)。长度限制:200字节。

PushTask.N.JobKey String 123

推送任务自定义标识,当JobKey不为空时,回执日志中会附带该字段。查看回执日志参见回执日志

PushTask.N.SendSpeed Integer 0

该参数已废弃。

PushTask.N.StoreOffline Boolean true

离线消息/通知是否保存。StoreOffline默认设置为false。

若保存,在推送时候用户不在线,在过期时间(ExpireTime)内用户上线时会被再次发送。ExpireTime默认为72小时。iOS通知走Apns链路,不受StoreOffline影响。

PushTask.N.PushTime String 2019-02-20T00:00:00Z

用于定时发送。不设置缺省是立即发送。

时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为YYYY-MM-DDThh:mm:ssZ。

PushTask.N.ExpireTime String 2019-02-20T00:00:00Z

离线消息/通知的过期时间,和StoreOffline配合使用,过期则不会再被发送,最长保存72小时。默认为72小时。

时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为YYYY-MM-DDThh:mm:ssZ,过期时间不能小于当前时间或者定时发送时间加上3秒(ExpireTime > PushTime+3秒),3秒是为了冗余网络和系统延迟造成的误差。

PushTask.N.iOSApnsEnv String DEV

iOS的通知是通过APNs中心来发送的,需要填写对应的环境信息。

  • DEV:表示开发环境。
  • PRODUCT:表示生产环境。
PushTask.N.iOSRemind Boolean true

消息推送时设备不在线(既与移动推送的服务端的长连接通道不通),则这条推送会做为通知,通过苹果的APNs通道送达一次。

说明 离线消息转通知仅适用于生产环境。
PushTask.N.iOSRemindBody String ios通知body

iOS消息转通知时使用的iOS通知内容,仅当iOSApnsEnv=PRODUCT && iOSRemind为true时有效。

PushTask.N.iOSBadge Integer 0

iOS应用图标右上角角标。

说明 若iOSBadgeAutoIncrement设置为True,则此项必须为空。
PushTask.N.iOSBadgeAutoIncrement Boolean true

是否开启角标自增功能,默认为false。

当该项为true时,iOSBadge必须为为空。角标自增功能由推送服务端维护每个设备的角标计数,需要用户使用1.9.5以上版本的sdk,并且需要用户主动同步角标数字到服务端。

PushTask.N.iOSSilentNotification Boolean true

是否开启iOS静默通知。

PushTask.N.iOSMusic String ””

iOS通知声音。指定存放在app bundle或沙盒Library/Sounds目录下的音频文件名,请参见:iOS推送如何设定通知声音。

若指定为空串(””),通知为静音;若不设置,默认填充default为系统提示音。

PushTask.N.iOSSubtitle String subtitle

iOS通知副标题内容(iOS 10+)。

PushTask.N.iOSNotificationCategory String ios

指定iOS通知Category(iOS 10+)。

PushTask.N.iOSMutableContent Boolean true

是否使能iOS通知扩展处理(iOS 10+)。

PushTask.N.iOSExtParameters String {“attachment”: “https://xxxx.xxx/notification_pic.png"}

iOS通知的扩展属性。

iOS10+可以在此指定富媒体推送通知的资源Url:{“attachment”: “https://xxxx.xxx/notification_pic.png"} 。该参数要以Json map的格式传入,否则会解析出错。

PushTask.N.AndroidNotifyType String VIBRATE

通知的提醒方式。可取值:

  • VIBRATE:振动(默认值)
  • SOUND:声音
  • BOTH:声音和振动
  • NONE:静音
PushTask.N.AndroidOpenType String APPLICATION

点击通知后动作。可取值:

  • APPLICATION:打开应用(默认值)
  • ACTIVITY:打开应用
  • AndroidActivityURL:打开URL
  • NONE:无跳转
PushTask.N.AndroidActivity String com.alibaba.cloudpushdemo.bizactivity

设定通知打开的activity。

仅当AndroidOpenType=”Activity”时传入,如:com.alibaba.cloudpushdemo.bizactivity

PushTask.N.AndroidMusic String

Android通知声音(保留参数,当前暂不起作用)。

PushTask.N.AndroidOpenUrl String https://xxxx.xxx

Android收到推送后打开对应的url。仅当AndroidOpenType=”URL”时传入。

PushTask.N.AndroidXiaoMiActivity String

该参数已废弃,所有第三方辅助弹窗都由新参数AndroidPopupActivity统一支持。

PushTask.N.AndroidXiaoMiNotifyTitle String

该参数已废弃,所有第三方辅助弹窗都由新参数AndroidPopupTitle统一支持。

PushTask.N.AndroidXiaoMiNotifyBody String

该参数已废弃,所有第三方辅助弹窗都由新参数AndroidPopupBody统一支持。

PushTask.N.AndroidPopupActivity String com.alibaba.cloudpushdemo.bizactivity

指定点击通知后跳转的Activity。

PushTask.N.AndroidPopupTitle String hello

辅助弹窗模式下标题内容。AndroidPopupActivity参数不为空时,该参数必填。

长度限制:30字符。

如使用厂商通道,则需同时符合厂商通道的限制,具体内容参见:Android端辅助通道推送限制

PushTask.N.AndroidPopupBody String hello

辅助弹窗模式下Body内容。AndroidPopupActivity参数不为空时,该参数必填。

长度限制:128字符。

如使用厂商通道,则需同时符合厂商通道的限制,具体内容参见:Android端辅助通道推送限制

PushTask.N.AndroidNotificationBarType Integer 2

Android自定义通知栏样式,取值:1-100。

PushTask.N.AndroidNotificationBarPriority Integer 0

Android通知在通知栏展示时排列位置的优先级。可取值: -2,-1,0,1,2。

PushTask.N.AndroidExtParameters String {"key1":"value1","api_name":"PushNoticeToAndroidRequest"}

设定通知的扩展属性。当推送类型PushType设置为MESSAGE消息类型时,该属性不生效。

该参数要以Json map的格式传入,否则会解析出错。

PushTask.N.AndroidRemind Boolean true

推送类型为消息时设备不在线,则这条推送会使用辅助弹窗功能。默认值为false,仅当PushType=MESSAGE时生效。

如果消息转通知推送成功,收到通知是展示的数据为服务端设置的AndroidPopupTitle和AndroidPopupBody参数值,点击通知在辅助弹窗的onSysNoticeOpened方法中获取到的数据是服务端设置的Title和Body参数值。

PushTask.N.AndroidNotificationChannel String 1

设置NotificationChannel参数,具体用途请参见常见问题:Android 8.0以上设备通知接收不到

PushTask.N.AndroidNotificationXiaomiChannel String michannel

设置小米通知类型的channelId,需要在小米平台申请,详见:申请链接

PushTask.N.AndroidNotificationVivoChannel String classification

设置vivo通知类型的classification,需要在vivo平台申请,详见:申请链接

PushTask.N.AndroidNotificationHuaweiChannel String classification

设置Huawei通知类型的classification,需要在Huawei平台申请,详见:申请链接

PushTask.N.AndroidNotificationNotifyId Integer 100001

标识每条消息在通知显示时的唯一标识,不同的通知栏消息可以相同的NotifyId,实现新的通知栏消息覆盖老的,当前支持小米和华为通道。

PushTask.N.iOSNotificationCollapseId String ZD2011

设备收到有相同CollapseId的消息,会合并成一条。设备不在线,连续发相同CollapseId的消息,通知栏只会显示一条,iOS 10+支持设置此参数。

返回数据

名称 类型 示例值 描述
MessageIds List 501030

标志批量推送的消息ID列表,每个ID对应传入的PushTask的推送结果。

RequestId String 9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC

请求ID。

示例

请求示例

http(s)://cloudpush.aliyuncs.com/?Action=MassPush
&AppKey=23267207
&PushTask.1.Body=hello
&PushTask.1.DeviceType=ALL
&PushTask.1.PushType=MESSAGE
&PushTask.1.Target=DEVICE
&PushTask.1.TargetValue=deviceid1,deviceid2
&<公共请求参数>

正常返回示例

XML格式

<MassPushResponse>
    <RequestId>9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC</RequestId>
    <MessageIds>
        <MessageId>501030</MessageId>
        <MessageId>501031</MessageId>
        <MessageId>501032</MessageId>
    </MessageIds>
</MassPushResponse>

JSON格式

{
  "RequestId": "9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC",
  "MessageIds": [
    "501030",
    "501031",
    "501031"
  ]
}

错误码

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

Java示例代码


MassPushRequest massPushRequest = new MassPushRequest();
massPushRequest.setAppKey(appKey);
List<MassPushRequest.PushTask> pushTasks = new ArrayList<>();
for (int i = 0; i < 100; i++) {
    MassPushRequest.PushTask pushTask = new MassPushRequest.PushTask();
    // 推送目标
    pushTask.setTarget("DEVICE"); //推送目标: DEVICE:推送给设备; ACCOUNT:推送给指定帐号,TAG:推送给自定义标签; ALIAS: 按别名推送; ALL: 全推
    pushTask.setTargetValue("device1,device2,device3"); //根据Target来设定,如Target=DEVICE, 则对应的值为 设备id1,设备id2. 多个值使用逗号分隔.(帐号与设备有一次最多100个的限制)
    pushTask.setDeviceType("iOS"); // 设备类型deviceType, iOS设备: "iOS"; Android设备: "ANDROID"; 全部: "ALL", 这是默认值.
    // 推送配置
    pushTask.setPushType("MESSAGE"); // MESSAGE:表示消息(默认), NOTICE:表示通知
    pushTask.setTitle("Hello-" + i); // 消息的标题
    pushTask.setBody("PushRequest body" + i); // 消息的内容
    // 推送配置: iOS
    pushTask.setIOSBadge(5); // iOS应用图标右上角角标
    pushTask.setIOSMusic("default"); // iOS通知声音
    pushTask.setIOSApnsEnv("PRODUCT");//iOS的通知是通过APNs中心来发送的,需要填写对应的环境信息。'DEV': 表示开发环境 'PRODUCT': 表示生产环境
    pushTask.setIOSRemind(true); //  消息推送时设备不在线(既与移动推送的服务端的长连接通道不通),则这条推送会做为通知,通过苹果的APNs通道送达一次。注意:**离线消息转通知仅适用于`生产环境`**
    pushTask.setIOSRemindBody("PushRequest summary"); // iOS消息转通知时使用的iOS通知内容,仅当iOSApnsEnv=`PRODUCT` && iOSRemind为true时有效
    pushTask.setIOSExtParameters("{\"k1\":\"ios\",\"k2\":\"v2\"}"); //通知的扩展属性(注意 : 该参数要以json map的格式传入,否则会解析出错)
    // 推送配置: Android
    pushTask.setAndroidOpenType("ACTIVITY"); // 点击通知后动作 'APPLICATION': 打开应用 'ACTIVITY': 打开应用AndroidActivity 'URL': 打开URL 'NONE': 无跳转
    pushTask.setAndroidNotifyType("SOUND"); // 通知的提醒方式 ‘VIBRATE': 振动  'SOUND': 声音 'DEFAULT': 声音和振动 'NONE': 不做处理,用户自定义
    pushTask.setAndroidOpenUrl("http://www.alibaba.com");
    pushTask.setAndroidMusic("default"); // Android通知声音
    pushTask.setAndroidActivity("com.alibaba.push.PushActivity"); // Android收到推送后打开对应的ACTIVITY,仅当`AndroidOpenType="ACTIVITY"`有效
    pushTask.setAndroidPopupActivity("com.alibaba.push.PopupActivity"); //设置该参数后启动辅助弹窗功能, 此处指定通知点击后跳转的Activity(辅助弹窗的前提条件:1. 集成第三方辅助通道;2. StoreOffline参数设为true)
    pushTask.setAndroidPopupTitle("Popup Title"); //设置辅助弹窗通知的标题
    pushTask.setAndroidPopupBody("Popup Body"); //设置辅助弹窗通知的内容
    pushTask.setAndroidNotificationBarType(50); //Android自定义通知栏样式,取值:1-100
    pushTask.setAndroidNotificationBarPriority(2); //Android通知在通知栏展示时排列位置的优先级 -2 -1 0 1 2
    pushTask.setAndroidExtParameters("{\"k1\":\"android\",\"k2\":\"v2\"}"); //设定通知的扩展属性。(注意 : 该参数要以 json map 的格式传入,否则会解析出错)
    // 推送控制
    final Date pushDate = new Date(System.currentTimeMillis() + 3600 * 1000); //用于定时发送。不设置缺省是立即发送。时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为`YYYY-MM-DDThh:mm:ssZ`。
    final String pushTime = ParameterHelper.getISO8601Time(pushDate);
    pushTask.setPushTime(pushTime); // 延后推送。可选,如果不设置表示立即推送
    pushTask.setStoreOffline(true); // 离线消息是否保存,若保存, 在推送时候,用户即使不在线,下一次上线则会收到
    final String expireTime = ParameterHelper.getISO8601Time(new Date(System.currentTimeMillis() + 12 * 3600 * 1000)); // 12小时后消息失效, 不会再发送
    pushTask.setExpireTime(expireTime);
    pushTasks.add(pushTask);
}
massPushRequest.setPushTasks(pushTasks);
MassPushResponse massPushResponse = client.getAcsResponse(massPushRequest);
System.out.printf("RequestId: %s, MessageIds: %s\n", massPushResponse.getRequestId(), massPushResponse.getMessageIds().toString());