MassPush - 批量推送

批量给不同的设备推送不同的消息/通知。

接口说明

请确保在使用该接口前,已充分了解 EMAS 移动推送产品的收费方式和价格

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

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

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

说明 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代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
mpush:MassPushnone
  • 全部资源
    *

请求参数

名称类型必填描述示例值
AppKeylong

AppKey 信息。

23267207
PushTaskarray<object>

独立推送任务组成的数组。

object

独立推送任务。

PushTypestring

推送类型。取值:

  • MESSAGE:表示消息。
  • NOTICE:表示通知。
MESSAGE
DeviceTypestring

设备类型,取值范围为:

  • HARMONY:鸿蒙设备
  • iOS:iOS 设备
  • ANDROID:Android 设备
  • ALL:当 AppKey 为旧版本双端应用时,代表同时推送 Android 和 iOS 设备;当 AppKey 为新版本单端应用时,效果和指定该应用类型对应的设备类型一样。
HARMONY
Targetstring

推送目标。可取值:

  • DEVICE:根据设备推送。
  • ACCOUNT:根据账号推送。
  • ALIAS:根据别名推送。
DEVICE
TargetValuestring

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

  • Target=DEVICE,值如deviceid1,deviceid2(最多支持 1000 个)。
  • Target=ACCOUNT,值如account1,account2(最多支持 1000 个)。
  • Target=ALIAS,值如alias1,alias2(最多支持 1000 个)。
deviceid1,deviceid2
StoreOfflineboolean

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

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

true
SendChannelsstring

指定发送通道,取值如下:

  • accs:阿里云自有通道
  • huawei:华为通道
  • honor:荣耀通道
  • xiaomi:小米通道
  • oppo:OPPO 通道
  • vivo:vivo 通道
  • meizu:魅族通道
  • gcm:谷歌 GCM 通道(旧版 HTTP)
  • fcm: 谷歌 Firebase 通道(HTTP v1 API)
  • apns:APNs 通道
  • harmony: 鸿蒙通道
说明
  • 如果未配置此参数,则代表所有通道均可使用。
  • 如果配置了此参数,则严格使用参数中的通道。
  • 如果配置的通道和发送策略冲突(如 iOS 通知仅走 APNs 通道,但本参数中不包含 apns),则不实施发送。
  • 若配置 gcm,则可以走谷歌 GCM 和 FCM 通道,若配置 fcm,则只能走谷歌 FCM 通道。
  • accs,huawei,xiaomi
    PushTimestring

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

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

    2019-02-20T00:00:00Z
    ExpireTimestring

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

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

    2019-02-20T00:00:00Z
    JobKeystring

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

    123
    Titlestring

    推送时通知/消息的标题,长度限制:200 字节。 在 Android 推送和 Harmony 推送时必填;在 iOS 推送通知时非必填,如果填写,则:

    • iOS 10+通知显示标题。
    • iOS 8.2 <= iOS 系统 < iOS 10:替换通知应用名称。
    title
    Bodystring

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

    hello
    Trimboolean

    是否自动对过长标题、内容进行截断。 注:仅支持明确限制标题、内容的厂商通道,对 APNs、华为、荣耀通道等不限制标题、内容,只限制总请求体大小的不适用。

    false
    iOSApnsEnvstring

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

    • DEV:表示开发环境。
    • PRODUCT:表示生产环境。
    DEV
    iOSRemindboolean

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

    说明 离线消息转通知仅适用于生产环境。
    true
    iOSSubtitlestring

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

    subtitle
    iOSRemindBodystring

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

    ios通知body
    iOSMusicstring

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

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

    ””
    iOSBadgeinteger

    iOS 应用图标右上角角标。

    说明 若 iOSBadgeAutoIncrement 设置为 True,则此项必须为空。
    0
    iOSBadgeAutoIncrementboolean

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

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

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

    true
    iOSSilentNotificationboolean

    是否开启 iOS 静默通知。

    true
    iOSMutableContentboolean

    iOS 通知处理扩展标记(iOS 10+)。如果设为 true,则 APNs 推送的通知在弹出前,可先到达 Extension 进行处理。静默通知时,必须设为 true。

    true
    iOSNotificationCategorystring

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

    ios
    iOSNotificationCollapseIdstring

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

    ZD2011
    iOSNotificationThreadIdstring

    通过该属性对 iOS 的远程通知进行分组,标记折叠的组别识别名。仅支持 iOS 12.0+版本。

    abc
    iOSInterruptionLevelstring

    中断级别,取值:

    • passive:系统在不点灯、不播放声音的情况下将通知添加到通知列表中。

    • active:系统立即显示通知,点亮屏幕,并可以播放声音。

    • time-sensitive:系统立即呈现通知,点亮屏幕,并可以播放声音,但不会突破系统通知控制。

    • critical:系统立即显示通知,屏幕亮起,并绕过静音开关播放声音。

    active
    iOSRelevanceScoredouble

    摘要突出显示分数。取值范围:[0,1]的浮点数。

    0.01
    iOSExtParametersstring

    iOS 通知的扩展属性。

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

    {"attachment": "https://xxxx.xxx/notification_pic.png"}
    AndroidNotifyTypestring

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

    • VIBRATE:振动(默认值)
    • SOUND:声音
    • BOTH:声音和振动
    • NONE:静音
    VIBRATE
    AndroidRemindboolean

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

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

    true
    AndroidOpenTypestring

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

    • APPLICATION:打开应用(默认值)
    • ACTIVITY:打开应用 AndroidActivity
    • URL:打开 URL
    • NONE:无跳转
    APPLICATION
    AndroidActivitystring

    设定通知打开的 activity。

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

    com.alibaba.cloudpushdemo.bizactivity
    AndroidOpenUrlstring

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

    https://xxxx.xxx
    AndroidPopupActivitystring

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

    com.alibaba.cloudpushdemo.bizactivity
    AndroidPopupTitlestring

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

    长度限制:30 字符。

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

    hello
    AndroidPopupBodystring

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

    长度限制:128 字符。

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

    hello
    AndroidRenderStylestring

    通知样式,取值为:

    • 0:标准模式(默认)
    • 1:长文本模式(支持华为、荣耀、小米、OPPO、魅族、自有通道)
    • 2:大图模式(仅支持小米)
    • 3:列表模式(支持华为、荣耀、小米、OPPO、自有通道)
    说明 若使用非标准模式,此参数必须提供。
    1
    AndroidBigTitlestring

    长文本模式下的标题,长度限制:200 个字节(1 个汉字算作 3 字节)。

    • 当前仅支持荣耀通道和华为通道 EMUI11 及以上版本。

    • 若长文本模式下未提供此参数,则从 Title、AndroidPopupTitle 里取第一个非空值。

    示例长标题
    AndroidBigBodystring

    长文本模式下的 body,长度限制:1000 字节(1 个汉字算作 3 字节),发送时受具体厂商通道的限制。

    当前支持:

    •  华为:EMUI10 及以上
    •  荣耀:Magic UI 4.0 及以上
    •  小米:MIUI10 及以上
    •  OPPO:ColorOS5.0 以上
    •  魅族:Flyme
    •  自有通道:安卓 SDK3.6.0 及以上

    若长文本模式下未提供此参数,则从 Body、AndroidPopupBody 里取第一个非空值。

    示例长文本
    AndroidBigPictureUrlstring

    大图模式下的图片 URL,当前支持:自有通道:安卓 SDK3.6.0 及以上。

    https://imag.example.com/image.png
    AndroidXiaomiBigPictureUrlstring

    大图模式下的大图 URL。大图模式下图片上传至小米推送后会返回一个图片 URL,本参数内填写这个 URL。

    https://f6.market.xiaomi.com/download/MiPass/aaa/bbb.png
    AndroidImageUrlstring

    大图标 URL。当前支持:

    • 华为 EMUI(仅长文本模式、Inbox 模式下适用)
    • 荣耀 Magic UI(仅长文本模式下适用)
    • 自有通道:安卓 SDK3.5.0 及以上
    https://imag.example.com/image.png
    AndroidXiaomiImageUrlstring

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

    说明 上传到小米服务器上,返回的图标 URL。具体请参考:链接
    https://imag.example.com/image.png
    AndroidInboxBodystring

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

    • 华为:EMUI9 及以上
    • 荣耀:Magic UI 4.0 及以上
    • 小米:MIUI10 及以上
    • OPPO:ColorOS 5.0 以上
    • 自有通道:安卓 SDK3.6.0 及以上
    ["第一行","第二行"]
    AndroidNotificationBarTypeinteger

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

    2
    AndroidNotificationBarPriorityinteger

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

    0
    AndroidNotificationNotifyIdinteger

    标识每条消息在通知显示时的唯一标识,不同的通知栏消息可以相同的 NotifyId,实现新的通知栏消息覆盖老的,当前支持除 FCM 通道外的其他厂商通道。

    100001
    AndroidNotificationChannelstring

    Android app 的 channelId,需要与 app 中的 channelId 能对应上。

    • 设置 NotificationChannel 参数,具体用途请参见常见问题:Android 8.0 以上设备通知接收不到
    • 因 OPPO 通知私信通道的 channel_id 与 app 的 channelId,故 OPPO 通道推送时,channel_id 取此值。
    • 华为、FCM、阿里云自有通道推送中,channel_id 取此值。
    1
    AndroidNotificationHuaweiChannelstring

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

    • LOW:资讯营销类消息
    • NORMAL:服务与通讯类消息
    说明
  • 当前华为通道建议使用 AndroidMessageHuaweiCategory 进行通知分类,可不再使用 AndroidNotificationHuaweiChannel。
  • 需要在 Huawei 平台申请,申请链接
  • LOW
    AndroidNotificationHonorChannelstring

    设置荣耀通知消息分类 importance 参数,决定用户设备消息通知行为,取值如下:

    • LOW:资讯营销类消息

    • NORMAL:服务与通讯类消息

    需要在荣耀平台申请,申请链接

    LOW
    AndroidNotificationXiaomiChannelstring

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

    说明
  • 小米通道单个应用最多可申请 8 个 channel,请提前做好规划。
  • michannel
    AndroidNotificationVivoChannelstring

    设置 vivo 通知消息分类,取值为:

    • 0:运营类消息(默认)
    • 1:系统类消息
    说明
  • 当前 vivo 通道建议使用 AndroidMessageVivoCategory 进行通知分类,可不再使用 AndroidNotificationVivoChannel。
  • 需要在 vivo 平台申请,详见:申请链接
  • 0
    AndroidNotificationGroupstring

    消息分组,同一组消息在通知栏里只显示最新一条和当前该组接受到的消息总数目,不会展示所有消息也无法展开。当前支持:

    • 华为
    • 荣耀
    • 自有通道
    group-1
    AndroidNotificationThreadIdstring

    消息分组,同一组消息在通知栏里折叠展示,可展开,不同组通知分开展示。当前支持:

    • 自有通道 安卓 SDK3.9.2 及以上
    thread-1
    AndroidExtParametersstring

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

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

    {"key1":"value1","api_name":"PushNoticeToAndroidRequest"}
    AndroidMessageHuaweiUrgencystring

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

    • HIGH

    • NORMAL

    需要申请权限,具体请参见:申请链接

    HIGH
    AndroidMessageHuaweiCategorystring

    作用一:完成自分类权益申请后,用于标识消息类型,确定消息提醒方式,对特定类型消息加快发送,取值请参考华为推送官方文档的消息分类标准,填写文档表格中的“云端通知 category 取值”或“本地通知 category 取值”。

    作用二:申请特殊权限后,用于标识高优先级透传场景,取值如下:

    • VOIP:音视频通话
    • PLAY_VOICE:语音播报
    说明 对于“云端通知 category 取值”为“不涉及”的一概走阿里云自有通道,对于“本地通知 category 取值”为“不涉及”的一概走华为通道。
    SUBSCRIPTION
    AndroidMessageOppoCategorystring

    OPPO 将消息分类:通讯与服务、内容与营销两个类别进行管理。

    通讯与服务(需申请权限):

    • IM:即时聊天、音频、视频通话
    • ACCOUNT:个人账号与资产变化
    • DEVICE_REMINDER:个人设备提醒
    • ORDER:个人订单/物流状态变化
    • TODO:个人日程/待办
    • SUBSCRIPTION:个人订阅

    内容与营销:

    • NEWS:新闻资讯
    • CONTENT:内容推荐
    • MARKETING:平台活动
    • SOCIAL:社交动态

    详细请参考 OPUSH 消息分类细则

    MARKETING
    AndroidMessageOppoNotifyLevelinteger

    OPPO 通道通知栏消息提醒等级。可取值为:

    • 1:通知栏
    • 2:通知栏+锁屏(通讯与服务类消息默认通知级别)
    • 16:通知栏+锁屏+横幅+震动+铃声(需申请权限)
    说明 使用 AndroidMessageOppoNotifyLevel 参数时,必须同时传 AndroidMessageOppoCategory 参数。
    1
    AndroidMessageVivoCategorystring

    vivo 将消息分为:系统消息、运营消息两个类别进行管理。

    系统消息:

    • IM:即时消息
    • ACCOUNT:账号与资产
    • TODO:日程待办
    • DEVICE_REMINDER:设备信息
    • ORDER:订单与物流
    • SUBSCRIPTION:订阅提醒

    运营消息:

    • NEWS:新闻
    • CONTENT:内容推荐
    • MARKETING:运营活动
    • SOCIAL:社交动态
    说明 详细请参考分类说明
    TODO
    AndroidTargetUserTypeinteger

    设置厂商通道通知类型:

    • 0:正式通知(默认)。
    • 1:测试通知。
    说明
  • 本参数配置后等价于同时配置 AndroidHuaweiTargetUserType、AndroidHonorTargetUserType、AndroidVivoPushMode 三个参数,具体厂商通道的对应参数能覆盖本参数。
  • 当前支持:华为通道、荣耀通道、vivo 通道。
  • 1
    AndroidHuaweiTargetUserTypeinteger

    设置华为通道通知类型:

    • 0:正式通知(默认)。
    • 1:测试通知。
    说明 每个应用每日可发送该测试通知 500 条且不受每日单设备推送数量上限要求。
    1
    AndroidHonorTargetUserTypeinteger

    设置荣耀通道通知类型:

    • 0:正式通知(默认)。
    • 1:测试通知。
    说明 每个应用每日可发送该测试通知 1000 条且不受每日单设备推送数量上限要求。
    1
    AndroidVivoPushModeinteger

    设置 vivo 通道通知类型:

    • 0:正式推送(默认)。
    • 1:测试推送。
    说明 测试推送请事先在 vivo 控制台配置测试设备。测试设备 RegId 可在设备启动日志中搜索“onReceiveRegId regId”获得。
    1
    AndroidHuaweiReceiptIdstring

    华为通道回执 ID,该回执 ID 可以在华为通道推送运营平台的回执参数配置中查看。

    说明 如果在华为通道推送运营平台配置的默认回执配置是阿里云回执,则无需提供,如果不是,建议优先在阿里云 EMAS 移动推送控制台中配置华为通道默认回执 ID。
    RCP4C123456
    AndroidVivoReceiptIdstring

    vivo 通道回执 ID,该回执 ID 可以在 vivo 开放平台推送服务的应用信息中查看。

    说明 如果在 vivo 开放平台配置的默认回执配置是阿里云回执,则无需提供,如果不是,建议优先在阿里云 EMAS 移动推送控制台中配置 vivo 通道默认回执 ID。
    123
    AndroidBadgeClassstring

    角标设置应用入口 Activity 的全类名

    说明 仅华为/荣耀产商通道推送时有效
    com.alibaba.cloudpushdemo.bizactivity
    AndroidBadgeAddNuminteger

    设置角标累加值,在原角标的基础上进行累加

    说明 仅华为/荣耀厂商通道推送时有效。AndroidBadgeAddNum 与 AndroidBadgeSetNum 同时存在时,以 AndroidBadgeSetNum 为准
    1
    AndroidBadgeSetNuminteger

    设置角标数字固定值

    说明 仅华为,荣耀,阿里云通道推送时生效。 在小米机型上自有通道推送时为当前通知的 messageCount 的值
    5
    AndroidMusicstring

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

    HarmonyRemindboolean

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

    如果消息转通知推送成功,收到通知是展示的数据为服务端设置的 HarmonyRemindTitle 和 HarmonyRemindBody 参数值。

    false
    HarmonyRemindTitlestring

    Harmony 消息转通知时使用的 Harmony 通知标题,仅当 HarmonyRemind 为 true 时有效。

    新消息
    HarmonyRemindBodystring

    Harmony 消息转通知时使用的 Harmony 通知内容,仅当 HarmonyRemind 为 true 时有效。

    您有一条新消息,请查收
    HarmonyCategorystring

    通知消息类别。完成申请通知消息自分类权益后,用于标识消息类型,不同的通知消息类型影响消息展示和提醒方式。取值如下:

    • IM:即时聊天
    • VOIP:音视频通话
    • SUBSCRIPTION:订阅
    • TRAVEL:出行
    • HEALTH:健康
    • WORK:工作事项提醒
    • ACCOUNT:账号动态
    • EXPRESS:订单&物流
    • FINANCE:财务
    • DEVICE_REMINDER:设备提醒
    • MAIL:邮件
    • CUSTOMER_SERVICE:客服消息
    • MARKETING:新闻、内容推荐、社交动态、产品促销、财经动态、生活资讯、调研、功能推荐、运营活动(仅对内容进行标识,不会加快消息发送),统称为资讯营销类消息

    详情参见鸿蒙官网 Notification.category

    IM
    HarmonyNotificationSlotTypestring

    使用指定类型的通知渠道。仅在阿里云自有通道在线时有效。

    • SOCIAL_COMMUNICATION: 社交通信。
    • SERVICE_INFORMATION: 服务提醒。
    • CONTENT_INFORMATION: 内容资讯。
    • CUSTOMER_SERVICE: 客服消息。该类型用于用户与商家之间的客服消息,需由用户主动发起。
    • OTHER_TYPES: 其他。

    详情参见鸿蒙官网 SlotType

    SOCIAL_COMMUNICATION
    HarmonyNotifyIdinteger

    每条消息在通知显示时的唯一标识。不携带时,推送服务自动为每条消息生成一个唯一标识;不同的通知消息可以拥有相同的 notifyId,实现新消息覆盖旧消息功能。

    详情参见鸿蒙官网 Notification.notifyId

    0
    HarmonyActionTypestring

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

    • APP_HOME_PAGE:打开应用首页
    • APP_CUSTOM_PAGE:打开应用自定义页面
    APP_HOME_PAGE
    HarmonyActionstring

    应用内置页面 ability 对应的 action。

    注意 当 HarmonyActionType 为 APP_CUSTOM_PAGE 时,字段 HarmonyUri 和 HarmonyAction 至少填写一个。

    详情参见鸿蒙官网 ClickAction.action

    com.example.action
    HarmonyUristring

    应用内置页面 ability 对应的 uri。

    注意 当 HarmonyActionType 为 APP_CUSTOM_PAGE 时,字段 HarmonyUri 和 HarmonyAction 至少填写一个。当存在多个 Ability 时,分别填写不同 Ability 的 action 和 uri,优先使用 action 查找对应的应用内置页面。

    详情参见鸿蒙官网 ClickAction.uri

    https://www.example.com:8080/push/example
    HarmonyRenderStylestring

    通知消息样式:

    • NORMAL: 普通通知(默认值)
    • MULTI_LINE: 多行文本样式
    NORMAL
    HarmonyImageUrlstring

    通知右侧大图标 URL,URL 使用的协议必须是 HTTPS 协议。

    说明 支持图片格式为 png、jpg、jpeg、heif、gif、bmp,图片长*宽<25000 像素。

    详情参见鸿蒙官网 Notification.image

    https://example.com/xxx.png
    HarmonyInboxContentstring

    多行文本样式的内容,当 HarmonyRenderStyle 为 MULTI_LINE 时,本字段必填,最多支持 3 条内容。

    ["1.content1","2.content2","3.content3"]
    HarmonyExtParametersstring

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

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

    {"key1":"value1","api_name":"PushNoticeToAndroidRequest"}
    HarmonyTestMessageboolean

    测试消息标识:

    • false:正常消息(默认值)
    • true:测试消息

    详情参见鸿蒙官网 pushOptions.testMessage

    true
    HarmonyReceiptIdstring

    鸿蒙通道回执 ID,该回执 ID 可以在鸿蒙通道推送运营平台的回执参数配置中查看。

    说明 如果在鸿蒙通道推送运营平台配置的默认回执配置是阿里云回执,则无需提供,如果不是,建议优先在阿里云 EMAS 移动推送控制台中配置鸿蒙通道默认回执 ID。

    详情参见鸿蒙官网 pushOptions.receiptId

    RCPB***DFD5
    HarmonyExtensionPushboolean

    PushType 为 NOTICE 时,是否为鸿蒙通知扩展消息。

    • true:发送通知扩展消息
    • false:发送普通通知

    通知扩展消息需要先在鸿蒙侧申请权限才能发送,相关内容请参考鸿蒙文档发送通知扩展消息
    鸿蒙 SDK1.2.0 版本开始支持。

    true
    HarmonyExtensionExtraDatastring

    通知扩展消息的额外数据。
    发送鸿蒙通知扩展消息时有效。
    概念上等同鸿蒙通知扩展消息的 extraData 字段,具体定义参考鸿蒙 ExtensionPayload 说明
    鸿蒙 SDK1.2.0 版本开始支持。

    示例额外数据
    HarmonyBadgeAddNuminteger

    鸿蒙应用角标累加数字。参考鸿蒙角标 addNum 字段说明
    鸿蒙 SDK1.2.0 版本开始支持。

    1
    HarmonyBadgeSetNuminteger

    鸿蒙应用角标设置数字。参考鸿蒙角标 setNum 字段说明
    鸿蒙 SDK1.2.0 版本开始支持。

    1
    SendSpeeddeprecatedinteger

    该参数已废弃。

    0
    AndroidXiaoMiNotifyTitledeprecatedstring

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

    AndroidXiaoMiNotifyBodydeprecatedstring

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

    AndroidXiaoMiActivitydeprecatedstring

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

    返回参数

    名称类型描述示例值
    object
    MessageIdsarray

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

    MessageIdstring

    消息 ID

    501030
    RequestIdstring

    请求 ID。

    9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC

    示例

    正常返回示例

    JSON格式

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

    错误码

    HTTP status code错误码错误信息描述
    400Invalid%s.FormatThe specified %s format is invalid.参数格式错误。
    400AccountDisabledYour account is not enabled.功能未启用。
    400FileNotExistThe specified file does not exist.指定的文件不存在。
    400IncorrectPasswordThe password is incorrect.密码错误。
    400NotApnsCertificateThe Certificate is not an APNs certificate.不是APNs证书。
    400PermissionDeniedThe specified AppKey is not authorized.您没有访问该app的权限,请您检查Appkey参数是否属于该账户。
    400SendSpeedNotSupportedSendSpeed is not supported for specified Target.制定目标不支持SendSpeed参数。
    400SmsProfileConfigFailedFailed to configure SMS profile.SMS配置失败。
    400SmsProfileGetFailedFailed to get SMS profile.SMS配置获取失败。
    400SmsRoleAuthorizeFailedFailed to authorize SMS role.SMS角色授权失败。
    400SmsRoleUnauthorizedThe SMS role is unauthorized.SMS角色没有授权。
    400TagsNumberBeyondLimitThe number of tags bound to this app exceeds the limit.当前app绑定的tag数量超过限制。
    400TargetNotSupportedTarget is not supported for batch push.批量推送不支持的Target。
    400Invalid%s.LengthExceedThe specified %s length cannot be greater than %s.参数长度超限。
    400Invalid%s.BytesExceedThe specified %s exceeds the %s bytes limit.参数的字节数超限。
    400Invalid%s.EmptyThe specified %s cannot be empty.参数不能为空。
    400Invalid.ParameterThe specified parameter is invalid: %s.参数%s无效。
    500InternalErrorThe request processing has failed due to some unknown error. Please try again. If the error still exists, submit a ticket.服务端错误,建议重试,仍然失败则提工单
    500TimeoutThe request processing is timeout.请求处理超时。

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

    变更历史

    变更时间变更内容概要操作
    2024-10-10OpenAPI 错误码发生变更查看变更详情
    2024-08-07OpenAPI 错误码发生变更查看变更详情
    2024-06-25OpenAPI 错误码发生变更查看变更详情
    2024-01-22OpenAPI 错误码发生变更查看变更详情
    2023-12-18OpenAPI 错误码发生变更查看变更详情
    2023-10-12OpenAPI 错误码发生变更查看变更详情
    2023-03-15OpenAPI 错误码发生变更查看变更详情
    2021-09-15OpenAPI 错误码发生变更查看变更详情

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