调用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.JobKey String 否 123

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

PushTask.N.iOSSilentNotification Boolean 否 true

是否开启iOS静默通知。
PushTask.N.StoreOffline Boolean 否 true

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

若保存，在推送时候用户不在线，在过期时间（ExpireTime）内用户上线时会被再次发送。ExpireTime默认为72小时。iOS通知走APNs链路，不受StoreOffline影响。
PushTask.N.iOSSubtitle String 否 subtitle

iOS通知副标题内容（iOS 10+）。
PushTask.N.AndroidNotificationHuaweiChannel String 否 classification

设置Huawei通知消息分类importance参数，决定用户设备消息通知行为，取值如下：

  • LOW：资讯营销类消息
  • NORMAL：服务与通讯类消息

需要在Huawei平台申请，申请链接。

PushTask.N.AndroidNotificationChannel String 否 1

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

PushTask.N.iOSApnsEnv String 否 DEV

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

  • DEV：表示开发环境。
  • PRODUCT：表示生产环境。
PushTask.N.iOSBadgeAutoIncrement Boolean 否 true

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

说明 当该项为true时，iOSBadge必须为空。

角标自增功能由推送服务端维护每个设备的角标计数，需要用户使用V1.9.5以上版本的sdk，并且需要用户主动同步角标数字到服务端。
PushTask.N.AndroidXiaoMiNotifyTitle String 否 无

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

PushTask.N.AndroidNotificationXiaomiChannel String 否 michannel

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

PushTask.N.AndroidXiaoMiActivity String 否 无

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

PushTask.N.AndroidPopupTitle String 否 hello

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

长度限制：30字符。

如使用厂商通道，则需同时符合厂商通道的限制，具体内容参见：Android端辅助通道推送限制
PushTask.N.iOSRemindBody String 否 ios通知body

iOS消息转通知时使用的iOS通知内容，仅当iOSApnsEnv=PRODUCT && iOSRemind为true时有效。
PushTask.N.AndroidNotifyType String 否 VIBRATE

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

  • VIBRATE：振动（默认值）
  • SOUND：声音
  • BOTH：声音和振动
  • NONE：静音
PushTask.N.AndroidOpenUrl String 否 https://xxxx.xxx

Android收到推送后打开对应的url。仅当PushTask.N.AndroidOpenType=”URL”时传入。
PushTask.N.AndroidBigTitle String 否 示例长标题

长文本模式下的标题，长度限制：200个字节（1个汉字算作3字节）。

  • 当前仅支持华为通道EMUI11及以上版本。
  • 若长文本模式下未提供此参数，则从Title、AndroidPopupTitle里取第一个非空值。
PushTask.N.ExpireTime String 否 2019-02-20T00:00:00Z

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

时间格式按照ISO8601标准表示，并需要使用UTC时间，格式为YYYY-MM-DDThh:mm:ssZ，过期时间不能小于当前时间或者定时发送时间加上3秒（ExpireTime > PushTime+3秒），3秒是为了冗余网络和系统延迟造成的误差。建议单推不小于1分钟，全推、批量推送不少于10分钟。

PushTask.N.AndroidOpenType String 否 APPLICATION

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

  • APPLICATION：打开应用（默认值）
  • ACTIVITY：打开应用
  • AndroidActivityURL：打开URL
  • NONE：无跳转
PushTask.N.AndroidExtParameters String 否 {"key1":"value1","api_name":"PushNoticeToAndroidRequest"}

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

该参数要以Json map的格式传入，否则会解析出错。
PushTask.N.AndroidXiaoMiNotifyBody String 否 无

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

PushTask.N.AndroidXiaomiBigPictureUrl String 否 https://f6.market.xiaomi.com/download/MiPass/aaa/bbb.png

大图模式下的大图URL。大图模式下图片上传至小米推送后会返回一个图片URL，本参数内填写这个URL。
PushTask.N.iOSMusic String 否 ””

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

若指定为空串（””），通知为静音；若不设置，默认填充default为系统提示音。
PushTask.N.iOSRemind Boolean 否 true

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

说明 离线消息转通知仅适用于生产环境。
PushTask.N.iOSBadge Integer 否 0

iOS应用图标右上角角标。

说明 若iOSBadgeAutoIncrement设置为True，则此项必须为空。
PushTask.N.Title String 否 title

Android推送时通知/消息的标题以及iOS消息的标题（必填）。iOS 10+通知显示标题，（iOS 8.2 <= iOS系统 < iOS 10）替换通知应用名称（选填）。长度限制：200字节。
PushTask.N.AndroidMusic String 否 无

Android通知声音（保留参数，当前暂不起作用）。
PushTask.N.iOSNotificationCollapseId String 否 ZD2011

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

通知样式，取值为：

  • 0：标准模式（默认）
  • 1：长文本模式
  • 2：大图模式（仅支持小米）
说明 若使用长文本模式、大图模式，此参数必须提供。

当前支持：

  • 　华为：EMUI 9及以上
  • 　小米：MIUI10及以上
  • 　OPPO：ColorOS 5.0以上
  • 　魅族：Flyme
  • 　自有通道：安卓SDK3.6.0及以上
PushTask.N.iOSNotificationCategory String 否 ios

指定iOS通知Category（iOS 10+）。
PushTask.N.iOSNotificationThreadId String 否 abc

通过该属性对iOS的远程通知进行分组，标记折叠的组别识别名。仅支持iOS 12.0+版本。
PushTask.N.AndroidActivity String 否 com.alibaba.cloudpushdemo.bizactivity

设定通知打开的activity。

仅当PushTask.N.AndroidOpenType=”Activity”时传入，如：com.alibaba.cloudpushdemo.bizactivity。

PushTask.N.AndroidBigBody String 否 示例长文本

长文本模式下的body，长度限制：1000字节（1个汉字算作3字节），发送时受具体厂商通道的限制。

当前支持：

  • 　华为：EMUI10及以上
  • 　小米：MIUI10及以上
  • 　OPPO：ColorOS5.0以上
  • 　魅族：Flyme
  • 　自有通道：安卓SDK3.6.0及以上

若长文本模式下未提供此参数，则从Body、AndroidPopupBody里取第一个非空值。
PushTask.N.iOSMutableContent Boolean 否 true

是否使能iOS通知扩展处理（iOS 10+）。
PushTask.N.AndroidNotificationNotifyId Integer 否 100001

标识每条消息在通知显示时的唯一标识，不同的通知栏消息可以相同的NotifyId，实现新的通知栏消息覆盖老的，当前支持除vivo通道外的其他厂商通道。
PushTask.N.AndroidNotificationVivoChannel String 否 classification

设置vivo通知消息分类，取值为：

  • 0：运营类消息（默认）
  • 1：系统类消息

需要在vivo平台申请，详见：申请链接。

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

指定点击通知后跳转的Activity。
PushTask.N.AndroidRemind Boolean 否 true

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

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

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

长度限制：128字符。

如使用厂商通道，则需同时符合厂商通道的限制，具体内容参见：Android端辅助通道推送限制
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.AndroidNotificationBarPriority Integer 否 0

Android通知在通知栏展示时排列位置的优先级。可取值： -2，-1，0，1，2。
PushTask.N.AndroidNotificationBarType Integer 否 2

Android自定义通知栏样式，取值：1-100。
PushTask.N.SendSpeed Integer 否 0

该参数已废弃。
PushTask.N.PushTime String 否 2019-02-20T00:00:00Z

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

时间格式按照ISO8601标准表示，并需要使用UTC时间，格式为YYYY-MM-DDThh:mm:ssZ。
PushTask.N.AndroidBigPictureUrl String 否 https://imag.example.com/image.png

大图模式下的图片URL，当前支持：自有通道：安卓SDK3.6.0及以上。
PushTask.N.AndroidInboxBody String 否 ["第一行","第二行"]

Inbox模式下的正文，内容为合法的JSON Array，且元素不超过5个。当前支持：

  • 华为：EMUI9及以上
  • 自有通道：安卓SDK3.6.0及以上
PushTask.N.AndroidImageUrl String 否 https://imag.example.com/image.png

大图标URL。当前支持：

  • 华为EMUI（仅长文本模式、Inbox模式下适用）
  • 自有通道：安卓SDK3.5.0及以上
PushTask.N.AndroidXiaomiImageUrl String 否 https://imag.example.com/image.png

大图标URL。当前支持：小米MIUI12及以上（仅长文本模式下适用）。

说明 上传到小米服务器上，返回的图标URL。具体请参考：链接。
PushTask.N.AndroidMessageHuaweiUrgency String 否 HIGH

华为通道透传消息投递优先级，取值如下：

  • HIGH
  • NORMAL

需要申请权限，具体请参见：申请链接。

PushTask.N.AndroidMessageHuaweiCategory String 否 VOIP

华为通道标识高优先级透传消息的特殊场景，取值如下：

  • PLAY_VOICE：语音播报
  • VOIP：VoIP电话

需申请特殊权限，详见：链接。

PushTask.N.SendChannels String 否 accs,huawei,xiaomi

指定发送通道（测试中功能，仅可用于纯安卓应用），取值如下：

  • accs：阿里自有通道
  • huawei：华为通道
  • xiaomi：小米通道
  • meizu：魅族通道
  • vivo：vivo通道
  • oppo：OPPO通道

返回数据

名称 类型 示例值 描述
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"
  ]
}

错误码

HttpCode 错误码 错误信息 描述
400 Invalid%s.Format The specified %s format is invalid. 参数格式错误。
400 AccountDisabled Your account is not enabled. 功能未启用。
400 FileNotExist The specified file does not exist. 指定的文件不存在。
400 IncorrectPassword The password is incorrect. 密码错误。
400 NotApnsCertificate The Certificate is not an APNs certificate. 不是APNs证书。
400 PermissionDenied The specified AppKey is not authorized. 您没有访问该app的权限，请您检查Appkey参数是否属于该账户。
400 SendSpeedNotSupported SendSpeed is not supported for specified Target. 制定目标不支持SendSpeed参数。
400 SmsProfileConfigFailed Failed to configure SMS profile. SMS配置失败。
400 SmsProfileGetFailed Failed to get SMS profile. SMS配置获取失败。
400 SmsRoleAuthorizeFailed Failed to authorize SMS role. SMS角色授权失败。
400 SmsRoleUnauthorized The SMS role is unauthorized. SMS角色没有授权。
400 TagsNumberBeyondLimit The number of tags bound to this app exceeds the limit. 当前app绑定的tag数量超过限制。
400 TargetNotSupported Target is not supported for batch push. 批量推送不支持的Target。
400 Invalid%s.LengthExceed The specified %s length cannot be greater than %s. 参数长度超限。
400 Invalid%s.BytesExceed The specified %s exceeds the %s bytes limit. 参数的字节数超限。
400 Invalid%s.Empty The specified %s cannot be empty. 参数不能为空。
400 Invalid.Parameter The specified parameter is invalid: %s. 参数%s无效。
500 InternalError The request processing has failed due to some unknown error. Please try again. If the error still exists, submit a ticket. 服务端错误，建议重试，仍然失败则提工单

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

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());