批量给不同的设备推送不同的消息/通知。
接口说明
请确保在使用该接口前,以充分了解EMAS移动推送产品的收费方式和价格。
在某种业务场景中,可能需要在极短时间内大量向不同设备单推不同消息,在设备数、消息数极大时,会产生较高QPS,达到我们单来源IP的QPS限制,造成部分推送失败。
本接口针对此问题设计。它支持单次调用最大传入100个独立的推送任务,通过聚合请求的方式有效降低QPS,提高大量单推的稳定性和成功率。批量推送单账号限制每秒500次调用。
每个独立推送任务仅支持根据设备/账号/别名三类推送目标,且暂不支持短信融合配置。
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代码示例。
授权信息
下表是API对应的授权信息,可以在RAM权限策略语句的Action
元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:
- 操作:是指具体的权限点。
- 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
- 资源类型:是指操作中支持授权的资源类型。具体说明如下:
- 对于必选的资源类型,用背景高亮的方式表示。
- 对于不支持资源级授权的操作,用
全部资源
表示。
- 条件关键字:是指云产品自身定义的条件关键字。
- 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
---|---|---|---|---|
mpush:MassPush |
|
| 无 |
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
AppKey | long | 是 | AppKey信息。 | 23267207 |
PushTask | object [] | 是 | 独立推送任务组成的数组。 | |
PushType | string | 是 | 推送类型。取值:
| MESSAGE |
DeviceType | string | 是 | 设备类型,取值范围为:
说明
该参数仅对旧的不分端app有意义。新的分端app下,该参数填写”ALL”或与app分端类型对应的值均可。
| ALL |
Target | string | 是 | 推送目标。可取值:
| DEVICE |
TargetValue | string | 是 | 根据Target来设定,多个值使用逗号分隔,超过限制需要分多次推送。
| deviceid1,deviceid2 |
StoreOffline | boolean | 否 | 离线消息/通知是否保存。StoreOffline默认设置为false。 若保存,在推送时候用户不在线,在过期时间(ExpireTime)内用户上线时会被再次发送。ExpireTime默认为72小时。iOS通知走APNs链路,不受StoreOffline影响。 | true |
SendChannels | string | 否 | 指定发送通道,取值如下:
说明
| accs,huawei,xiaomi |
PushTime | string | 否 | 用于定时发送。不设置缺省是立即发送。 时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为YYYY-MM-DDThh:mm:ssZ。 | 2019-02-20T00:00:00Z |
ExpireTime | string | 否 | 离线消息/通知的过期时间,和StoreOffline配合使用,过期则不会再被发送,最长保存72小时。默认为72小时。 时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为YYYY-MM-DDThh:mm:ssZ,过期时间不能小于当前时间或者定时发送时间加上3秒( | 2019-02-20T00:00:00Z |
JobKey | string | 否 | 推送任务自定义标识,当JobKey不为空时,回执日志中会附带该字段。查看回执日志参见回执日志。 | 123 |
Title | string | 否 | 推送时通知/消息的标题,长度限制:200字节。 在Android推送和iOS推送消息时必填;在iOS推送通知时非必填,如果填写,则:
| title |
Body | string | 是 | Android推送时通知的内容/消息的内容;iOS消息/通知内容,推送的内容大小是有限制的,参见产品限制。 | hello |
Trim | boolean | 否 | 是否自动对过长标题、内容进行截断。 注:仅支持明确限制标题、内容的厂商通道,对APNs、华为、荣耀通道等不限制标题、内容,只限制总请求体大小的不适用。 | false |
iOSApnsEnv | string | 否 | iOS的通知是通过APNs中心来发送的,需要填写对应的环境信息。
| DEV |
iOSRemind | boolean | 否 | 消息推送时设备不在线(即与移动推送的服务端的长连接通道不通),则这条推送会做为通知,通过苹果的APNs通道送达一次。 说明
离线消息转通知仅适用于生产环境。
| true |
iOSSubtitle | string | 否 | iOS通知副标题内容(iOS 10+)。 | subtitle |
iOSRemindBody | string | 否 | iOS消息转通知时使用的iOS通知内容,仅当iOSApnsEnv=PRODUCT && iOSRemind为true时有效。 | ios通知body |
iOSMusic | string | 否 | iOS通知声音。指定存放在app bundle或沙盒Library/Sounds目录下的音频文件名,请参见:iOS推送如何设定通知声音。 若指定为空串(””),通知为静音;若不设置,默认填充default为系统提示音。 | ”” |
iOSBadge | integer | 否 | iOS应用图标右上角角标。 说明
若iOSBadgeAutoIncrement设置为True,则此项必须为空。
| 0 |
iOSBadgeAutoIncrement | boolean | 否 | 是否开启角标自增功能,默认为false。 说明
当该项为true时,iOSBadge必须为空。
角标自增功能由推送服务端维护每个设备的角标计数,需要用户使用V1.9.5以上版本的SDK,并且需要用户主动同步角标数字到服务端。 | true |
iOSSilentNotification | boolean | 否 | 是否开启iOS静默通知。 | true |
iOSMutableContent | boolean | 否 | iOS通知处理扩展标记(iOS 10+)。如果设为true,则APNs推送的通知在弹出前,可先到达Extension进行处理。静默通知时,必须设为true。 | true |
iOSNotificationCategory | string | 否 | 指定iOS通知Category(iOS 10+)。 | ios |
iOSNotificationCollapseId | string | 否 | 设备收到有相同CollapseId的消息,会合并成一条。设备不在线,连续发相同CollapseId的消息,通知栏只会显示一条,iOS 10+支持设置此参数。 | ZD2011 |
iOSNotificationThreadId | string | 否 | 通过该属性对iOS的远程通知进行分组,标记折叠的组别识别名。仅支持iOS 12.0+版本。 | abc |
iOSInterruptionLevel | string | 否 | 中断级别,取值:
| active |
iOSRelevanceScore | double | 否 | 摘要突出显示分数。取值范围:[0,1]的浮点数。 | 0.01 |
iOSExtParameters | string | 否 | iOS通知的扩展属性。 iOS10+可以在此指定富媒体推送通知的资源Url: | {“attachment”: “https://xxxx.xxx/notification_pic.png"} |
AndroidNotifyType | string | 否 | 通知的提醒方式。可取值:
| VIBRATE |
AndroidRemind | boolean | 否 | 推送类型为消息时设备不在线,则这条推送会使用辅助弹窗功能。默认值为false,仅当PushType=MESSAGE时生效。 如果消息转通知推送成功,收到通知是展示的数据为服务端设置的AndroidPopupTitle和AndroidPopupBody参数值,点击通知在辅助弹窗的onSysNoticeOpened方法中获取到的数据是服务端设置的Title和Body参数值。 | true |
AndroidOpenType | string | 否 | 点击通知后动作。可取值:
| APPLICATION |
AndroidActivity | string | 否 | 设定通知打开的activity。 仅当PushTask.N.AndroidOpenType=”Activity”时传入,如: | com.alibaba.cloudpushdemo.bizactivity |
AndroidOpenUrl | string | 否 | Android收到推送后打开对应的url。仅当PushTask.N.AndroidOpenType=”URL”时传入。 | https://xxxx.xxx |
AndroidPopupTitle | string | 否 | 辅助弹窗模式下标题内容。AndroidPopupActivity参数不为空时,该参数必填。 长度限制:30字符。 如使用厂商通道,则需同时符合厂商通道的限制,具体内容参见:Android端辅助通道推送限制。 | hello |
AndroidPopupBody | string | 否 | 辅助弹窗模式下Body内容。AndroidPopupActivity参数不为空时,该参数必填。 长度限制:128字符。 如使用厂商通道,则需同时符合厂商通道的限制,具体内容参见:Android端辅助通道推送限制。 | hello |
AndroidPopupActivity | string | 否 | 指定点击通知后跳转的Activity。 | com.alibaba.cloudpushdemo.bizactivity |
AndroidRenderStyle | string | 否 | 通知样式,取值为:
说明
若使用长文本模式、大图模式,此参数必须提供。
当前支持:
| 1 |
AndroidBigTitle | string | 否 | 长文本模式下的标题,长度限制:200个字节(1个汉字算作3字节)。
| 示例长标题 |
AndroidBigBody | string | 否 | 长文本模式下的body,长度限制:1000字节(1个汉字算作3字节),发送时受具体厂商通道的限制。 当前支持:
若长文本模式下未提供此参数,则从Body、AndroidPopupBody里取第一个非空值。 | 示例长文本 |
AndroidBigPictureUrl | string | 否 | 大图模式下的图片URL,当前支持:自有通道:安卓SDK3.6.0及以上。 | https://imag.example.com/image.png |
AndroidXiaomiBigPictureUrl | string | 否 | 大图模式下的大图URL。大图模式下图片上传至小米推送后会返回一个图片URL,本参数内填写这个URL。 | https://f6.market.xiaomi.com/download/MiPass/aaa/bbb.png |
AndroidImageUrl | string | 否 | 大图标URL。当前支持:
| https://imag.example.com/image.png |
AndroidXiaomiImageUrl | string | 否 | 大图标URL。当前支持:小米MIUI12及以上(仅长文本模式下适用)。 说明
上传到小米服务器上,返回的图标URL。具体请参考:链接。
| https://imag.example.com/image.png |
AndroidInboxBody | string | 否 | Inbox模式下的正文,内容为合法的JSON Array,且元素不超过5个。当前支持:
| ["第一行","第二行"] |
AndroidNotificationBarType | integer | 否 | Android自定义通知栏样式,取值:1-100。 | 2 |
AndroidNotificationBarPriority | integer | 否 | Android通知在通知栏展示时排列位置的优先级。可取值: -2,-1,0,1,2。 | 0 |
AndroidNotificationNotifyId | integer | 否 | 标识每条消息在通知显示时的唯一标识,不同的通知栏消息可以相同的NotifyId,实现新的通知栏消息覆盖老的,当前支持除FCM通道外的其他厂商通道。 | 100001 |
AndroidNotificationChannel | string | 否 |
| 1 |
AndroidNotificationHuaweiChannel | string | 否 | LOW | |
AndroidNotificationHonorChannel | string | 否 | LOW | |
AndroidNotificationVivoChannel | string | 否 | 0 | |
AndroidNotificationXiaomiChannel | string | 否 | 设置小米通知类型的channelId,需要在小米平台申请,详见:申请链接。 | michannel |
AndroidNotificationGroup | string | 否 | 消息分组,同一组消息在通知栏里只显示最新一条和当前该组接受到的消息总数目,不会展示所有消息也无法展开。 | group-1 |
AndroidExtParameters | string | 否 | 设定通知的扩展属性。当推送类型PushType设置为MESSAGE消息类型时,该属性不生效。 该参数要以JSON map的格式传入,否则会解析出错。 | {"key1":"value1","api_name":"PushNoticeToAndroidRequest"} |
AndroidMessageHuaweiUrgency | string | 否 | HIGH | |
AndroidMessageHuaweiCategory | string | 否 | SUBSCRIPTION | |
AndroidMessageVivoCategory | string | 否 | vivo将消息分为:系统消息、运营消息两个类别进行管理。 系统消息:
运营消息:
说明
详细请参考分类说明
| TODO |
AndroidTargetUserType | integer | 否 | 设置厂商通道通知类型:
说明
| 1 |
AndroidHuaweiTargetUserType | integer | 否 | 设置华为通道通知类型:
说明
每个应用每日可发送该测试通知500条且不受每日单设备推送数量上限要求。
| 1 |
AndroidHonorTargetUserType | integer | 否 | 设置荣耀通道通知类型:
说明
每个应用每日可发送该测试通知1000条且不受每日单设备推送数量上限要求。
| 1 |
AndroidVivoPushMode | integer | 否 | 设置vivo通道通知类型:
说明
测试推送请事先在vivo控制台配置测试设备。测试设备RegId可在设备启动日志中搜索“onReceiveRegId regId”获得。
| 1 |
AndroidHuaweiReceiptId | string | 否 | 华为通道回执ID,该回执ID可以在华为通道推送运营平台的回执参数配置中查看。 | RCP4C123456 |
AndroidMusic | string | 否 | Android通知声音(保留参数,当前暂不起作用)。 | 无 |
SendSpeed | integer | 否 | 该参数已废弃。 | 0 |
AndroidXiaoMiNotifyTitle | string | 否 | 该参数已废弃,所有第三方辅助弹窗都由新参数AndroidPopupTitle统一支持。 | 无 |
AndroidXiaoMiNotifyBody | string | 否 | 该参数已废弃,所有第三方辅助弹窗都由新参数AndroidPopupBody统一支持。 | 无 |
AndroidXiaoMiActivity | string | 否 | 该参数已废弃,所有第三方辅助弹窗都由新参数AndroidPopupActivity统一支持。 | 无 |
返回参数
示例
正常返回示例
JSON
格式
{
"RequestId": "9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC",
"MessageIds": {
"MessageId": [
"501030"
]
}
}
错误码
HTTP status code | 错误码 | 错误信息 | 描述 |
---|---|---|---|
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. | 服务端错误,建议重试,仍然失败则提工单 |
访问错误中心查看更多错误码。
变更历史
变更时间 | 变更内容概要 | 操作 | ||||||
---|---|---|---|---|---|---|---|---|
2023-10-12 | OpenAPI 错误码发生变更 | 看变更集 | ||||||
| ||||||||
2023-03-15 | OpenAPI 错误码发生变更 | 看变更集 | ||||||
| ||||||||
2021-09-15 | OpenAPI 错误码发生变更 | 看变更集 | ||||||
|
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());