调用MassPush批量推送。
接口说明
在某种业务场景中,可能需要在极短时间内大量向不同设备单推不同消息,在设备数、消息数极大时,会产生较高QPS,达到我们单来源IP的QPS限制,造成部分推送失败。
本接口针对此问题设计。它支持单次调用最大传入100个独立的推送任务,通过聚合请求的方式有效降低QPS,提高大量单推的稳定性和成功率。批量推送单账号限制每分钟100000调用。
每个独立推送任务仅支持根据设备/账号/别名三类推送目标,且暂不支持短信融合配置。
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 |
设备类型,取值范围为:
说明 该参数仅对旧的不分端App有意义。新的分端App下,该参数填写”ALL”或与App分端类型对应的值均可。
|
PushTask.N.PushType | String | 是 | MESSAGE |
推送类型。取值:
|
PushTask.N.Target | String | 是 | DEVICE |
推送目标。可取值:
|
PushTask.N.TargetValue | String | 是 | deviceid1,deviceid2 |
根据Target来设定,多个值使用逗号分隔,超过限制需要分多次推送。
|
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秒( |
PushTask.N.iOSApnsEnv | String | 否 | DEV |
iOS的通知是通过APNs中心来发送的,需要填写对应的环境信息。
|
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: |
PushTask.N.AndroidNotifyType | String | 否 | VIBRATE |
通知的提醒方式。可取值:
|
PushTask.N.AndroidOpenType | String | 否 | APPLICATION |
点击通知后动作。可取值:
|
PushTask.N.AndroidActivity | String | 否 | com.alibaba.cloudpushdemo.bizactivity |
设定通知打开的activity。 仅当AndroidOpenType=”Activity”时传入,如: |
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());
在文档使用中是否遇到以下问题
更多建议
匿名提交