服务端 API

消息推送支持通过 API 接口调用的方式实现极简推送、模板推送、批量推送、群发推送、消息撤回、使用分析、定时推送功能。消息推送支持即时推送、定时推送、循环推送三种不同推送策略,以满足您在不同场景下的推送需求,减少重复工作量。同时,提供短信补充服务,即通过短信通道进行消息补充,以提升消息触达率。

重要

厂商通道的参数特殊限制,请参考:

厂商通道

规则限制

华为

受限说明

接口文档

荣耀

推送数量管理细则

接口文档

鸿蒙

使用约束

接口文档

小米

推送消息规则

接口文档

OPPO

推送服务受限说明

接口文档

vivo

推送消息限制说明

接口文档

消息推送提供以下服务端 API,具体描述见下表。

API

描述

极简推送

对一个目标 ID 推送一条消息。

模板推送

对一个目标 ID 推送一条消息,消息通过模板创建。

批量推送

对多个目标 ID 推送不同消息。基于模板,为各推送 ID 配置不同的模板占位符内容,从而实现消息的个性化推送。

群发推送

对全网设备推送相同消息,消息通过模板进行创建。

消息撤回

对已推送的消息进行撤回。通过极简推送或模板推送方式推送的消息可通过消息 ID 撤回;通过批量推送和群发推送方式推送的消息可通过任务 ID 撤回。

使用分析

查询消息推送统计数据,包括总推送条数、推送成功数、推送到达数、消息打开数、消息忽略数等,通过控制台创建或通过调用 API 触发的批量推送任务和群发推送任务列表以及任务详情。

定时推送任务

支持查询定时推送任务列表、取消定时推送任务。定时推送任务分为定时推送和循环推送两种:

  • 定时推送:在指定时间推送消息。例如,指定在 6.19 日早上 8:00 推送消息。

  • 循环推送:在指定时间范围内重复推送消息,例如指定在 6.1 ~ 9.30 期间,每周五早上 8:00 推送消息。一个循环推送任务可能生成一个或多个定时推送任务。

SDK 准备

消息推送支持 Java、Python、Node.js、PHP 四种语言版本。针对不同的语言版本,在调用上述推送方式前,需要进行相应的推送准备。

下面分别对各个语言版本的 SDK 准备工作进行说明。

Java

说明

对于非金区(非金融区)用户,消息推送 SDK 最新版本为 3.0.10;对于金区用户,消息推送 SDK 最新版本为 2.1.9。

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>aliyun-java-sdk-mpaas</artifactId>
  <version>3.0.10</version>
</dependency>

<dependency>
<groupId>com.aliyun</groupId>
  <artifactId>aliyun-java-sdk-core</artifactId>
  <optional>true</optional>
  <version>[4.3.2,5.0.0)</version>
</dependency>

Python

执行以下命令添加 SDK 相关依赖。

## 阿里云SDK
pip install aliyun-python-sdk-core
## mpaas SDK 
pip install aliyun-python-sdk-mpaas

Node.js

执行以下命令添加 SDK 相关依赖。

npm i @alicloud/mpaas20190821

PHP

执行以下命令添加 SDK 相关依赖。

composer require alibabacloud/sdk

环境变量配置

配置环境变量 MPAAS_AK_ENV 和 MPAAS_SK_ENV。

  • Linux 和 macOS 系统配置方法执行以下命令:

    export MPAAS_AK_ENV=<access_key_id>
    export MPAAS_SK_ENV=<access_key_secret>
    说明

    access_key_id 替换为已准备好的 AccessKey ID,access_key_secret 替换为 AccessKey Secret。

  • Windows 系统配置方法

    1. 新建环境变量,添加环境变量 MPAAS_AK_ENV MPAAS_SK_ENV,并写入已准备好的 AccessKey ID 和 AccessKey Secret。

    2. 重启 Windows 系统。

极简推送

对一个推送 ID 推送一条消息。

在调用本接口之前,您需要引入依赖,详见 SDK 准备

请求参数

参数名称

类型

是否必填

示例

描述

classification

String

1

用于传递 vivo 推送通道的消息类型:

  • 0 - 运营类消息

  • 1 - 系统类消息

不填则默认为 1。

taskName

String

simpleTest

推送任务名称。

title

String

测试

消息的标题。

content

String

测试

消息的正文。

appId

String

ONEX570DA89211721

mPaaS App ID

workspaceId

String

test

mPaaS 工作空间

deliveryType

Long

3

目标 ID 类型,数值选择如下:

  • 1 - Android 设备维度

  • 2 - iOS 设备维度

  • 3 - 用户维度

  • 5 - 实时活动 pushToken

  • 6 - 实时活动 activityId

  • 7 - HarmonyOS 设备维度

targetMsgkey

String

{“user1024”:”1578807462788”}

推送目标,为 Map 形式:

  • key:为目标,配合 deliveryType

    • 如果 deliveryType 为 1 ,则 key 为 Android 设备 ID。

    • 如果 deliveryType 为 2,则 key 为 iOS 设备 ID。

    • 如果 deliveryType 为 3 ,则 key 为用户 ID,即用户调用绑定接口时传入的 userid 值。

    • 如果 deliveryType 为 7,则 key 为鸿蒙设备 ID。

  • value:消息业务 ID,用户自定义,必须保持唯一。

说明

推送目标不可以超过 10 个,即 targetMsgkey 参数最多可传入 10 个键值对。

expiredSeconds

Long

300

消息有效期,单位为秒。

pushStyle

Integer

0

推送样式:

  • 0 - 默认

  • 1 - 大文本

  • 2 - 图文消息

extendedParams

String

{“key1”:”value1”}

扩展参数,为 Map 形式。

pushAction

Long

0

单击消息后的跳转方式:

  • 0 - Web URL

  • 1 - Intent Activity

默认为 Web URL。

uri

String

http://www

单击消息后的跳转地址。

silent

Long

1

是否静默:

  • 1 - 静默

  • 0 - 非静默

notifyType

String

表示消息通道类型:

  • transparent - MPS 自建通道

  • notify - 默认通道

imageUrls

String

{\”defaultUrl\”:\”https://mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"oppoUrl\":\"https://mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"miuiUrl\":\"https://mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"fcmUrl\":\"https://mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"iosUrl\":\"https://mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\"}

大图链接(JSON 字符串),支持 OPPO、HMS、MIUI、FCM 和 iOS 推送通道,也可以使用 defaultUrl 作为默认值。

iconUrls

String

{\”defaultUrl\”:\”https://mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"hmsUrl\":\"https://mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"oppoUrl\":\"https://mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"miuiUrl\":\"https://mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\"}

图标链接(JSON 字符串),支持 OPPO、HMS、MIUI、FCM 和 iOS 推送通道,也可以使用 defaultUrl 作为默认值。

strategyType

Integer

1

推送策略类型:

  • 0 - 立即

  • 1 - 定时

  • 2 - 循环

不填则默认为 0。

StrategyContent

String

{\”fixedTime\”:1630303126000,\”startTime\”:1625673600000,\”endTime\”:1630303126000,\”circleType\”:1,\”circleValue\”:[1, 7],\”time\”:\”13:45:11\”}

推送策略详情(JSON 字符串)。strategyType 不等于 0 时必填。具体参数详见下方的 StrategyContent 字段说明

transparentMessagePayload

Map<String, JSONObject>

-

厂商透传消息体。

  • 键 key:厂商渠道类型

    • 华为通道为 hms

    • 荣耀通道为 honor

    • 谷歌 firebase 通道为 fcm

    • 鸿蒙通道为 harmonyos

  • value:透传消息体。推送给厂商的透传消息体使用该 value 值

透传消息体的格式如下:

{
    "data": "{\"name\":\"123hms\"}",
    "android":
    {
        "category": "VOIP",
        "ttl": "600s",
        "urgency": "HIGH"
    },
    "token":
    [
        "9912981981wqdq2112291fcm001saa222222222ggwerfwgsas2cc3"
    ]
}

transparentMessageUrgency

String

-

厂商透传消息优先级(transparentMessagePayload 有值时有效)。

目前仅华为、荣耀以及鸿蒙支持,有 HIGH/NORMAL 可选。

针对华为、荣耀而言:

  • HIGH:表示高优先透传

  • NORMAL:或者不传参表示普通透传

针对鸿蒙而言:

  • HIGH:当前消息是透传消息

  • NORMAL:当前消息是后台消息

smsStrategy

int

2

短信策略:

  • 0 - 无(默认)

  • 1 - 补发

  • 2 - 并发

smsSignName

String

mPaaS 测试

短信签名

smsTemplateCode

String

SMS_216070269

短信模板 ID

smsTemplateParam

String

{\"code\": 123456}

短信模板变量对应的实际值,JSON 格式。

thirdChannelCategory

Map

thirdChannelCategory: {

"hms": "9", //华为 FINANCE 财务类型消息

"vivo": "1"

//vivo IM 类型消息

}

用于传递华为消息分类以及 vivo 二级消息分类参数,详情请参见 厂商消息分类

miChannelId

String

"123321"

小米厂商推送渠道的 channelId

activityEvent

String

实时活动事件,可选 update/end:

  • update - 更新事件

  • end - 结束事件

activityContentState

JSONObject

实时活动消息的 content-state,需和客户端定义的参数保持一致。

dismissalDate

long

实时活动消息过期时间(秒级时间戳),可选字段,不传则按 iOS 系统默认失效时间 12h。

说明

关于 smsStrategy 参数:

  • 如果 smsStrategy 的值不为 0,则 smsSignNamesmsTemplateCodesmsTemplateParam 必填。

关于 activityEvent 参数:

  • activityEvent 为 end 事件时,dismissalDate 配置的过期时间才会生效。

  • activityEvent 为 update 事件时,dismissalDate 配置的过期时间不会生效。

  • 若传 end 事件但不传 dismissalDate,iOS 系统默认 4h 后结束实时活动。

StrategyContent 字段说明

JSON 格式转化为 String 传值。

参数名称

类型

是否必填

示例

描述

fixedTime

long

1630303126000

定时推送时间戳(单位:毫秒,精确到秒)。推送策略类型为定时(strategyType 值为 1)时,fixedTime 必填。

startTime

long

1640966400000

循环周期开始时间戳(单位:毫秒,精确到天)。推送策略类型为循环(strategyType 值为 2)时,startTime 必填。

endTime

long

1672416000000

循环周期结束时间戳(单位:毫秒,精确到天),循环结束时间不得超过当天后的 180 天。推送策略类型为循环(strategyType 值为 2)时,endTime 必填。

circleType

int

3

循环类型:

  • 1 - 每天

  • 2 - 每周

  • 3 - 每月

推送策略类型为循环(strategyType 值为 2)时,circleType 必填。

circleValue

int[]

[1,3]

循环值:

  • 若循环类型为每天:空

  • 若循环类型为每周:设置每周循环的时间,例如 [1,3] 表示每周 1 和周 3。

  • 若循环类型为每月:设置每月循环推送的时间,例如 [1,3] 表示每月 1 号和 3 号。

推送策略类型为循环(strategyType 值为 2)且循环类型(circleType)非每天时,circleValue 必填。

time

String

09:45:11

循环推送时间(时分秒,格式为 HH:mm:ss) 。推送策略类型为循环(strategyType 值为 2)时,time 必填。

说明
  • 未执行的定时或循环推送任务总数上限默认为 100 条。

  • 循环周期为开始时间的 0 点到结束时间的 24 点。

  • 循环开始时间和结束时间均不可早于当天 0 点,且结束时间不得早于开始时间。

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

PushResult

JSON

请求结果

Success

boolean

true

请求状态。Success 参数值包含在 PushRresult JSON 字符串中。

ResultMsg

String

param is invalid

请求错误内容。ResultMsg 参数值包含在 PushRresult JSON 字符串中。

Data

String

903bf653c1b5442b9ba07684767bf9c2

定时推送任务 ID。strategyType 不等于 0 时,该字段不为空。

代码示例

请确保您的 AccessKey 拥有 AliyunMPAASFullAccess 权限,详情请参考 对 RAM 账号进行应用级别的访问控制

Java 代码示例

单击此处 查看下方代码示例中 AccessKeyId 与 AccessKeySecret 的获取方式 。

 DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
        // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
        // 本示例以将AccessKey ID和AccessKey Secret保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里。
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 

        IAcsClient client = new DefaultAcsClient(profile);
        // Create an API request and set parameters
        PushSimpleRequest request = new PushSimpleRequest();
        request.setAppId("ONEX570DA89211721");
        request.setWorkspaceId("test");
        request.setTaskName("测试任务");
        request.setTitle("测试");
        request.setContent("测试");
        request.setDeliveryType(3L);
        Map<String,String> extendedParam = new HashMap<String, String>();
        extendedParam.put("key1","value1");
        request.setExtendedParams(JSON.toJSONString(extendedParam));
        request.setExpiredSeconds(300L);

        request.setPushStyle(2);
        String imageUrls = "{\"defaultUrl\":\"https://pre-mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"oppoUrl\":\"https://pre-mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"miuiUrl\":\"https://pre-mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"fcmUrl\":\"https://pre-mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"iosUrl\":\"https://pre-mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\"}";
        String iconUrls = "{\"defaultUrl\":\"https://pre-mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"hmsUrl\":\"https://pre-mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"oppoUrl\":\"https://pre-mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\",\"miuiUrl\":\"https://pre-mpaas.oss-cn-hangzhou.aliyuncs.com/tmp/test.png\"}";
        request.setImageUrls(imageUrls);
        request.setIconUrls(iconUrls);

        request.setStrategyType(2);
        request.setStrategyContent("{\"fixedTime\":1630303126000,\"startTime\":1625673600000,\"endTime\":1630303126000,\"circleType\":1,\"circleValue\":[1, 7],\"time\":\"13:45:11\"}");

        Map<String,String> target = new HashMap<String, String>();
        String msgKey = String.valueOf(System.currentTimeMillis());
        target.put("user1024",msgKey);
        request.setTargetMsgkey(JSON.toJSONString(target));
        // Initiate the request and handle the response or exceptions
        PushSimpleResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
        } catch (ClientException e) {
            e.printStackTrace();
        }

Python 代码示例

from aliyunsdkcore.client import AcsClient
from aliyunsdkmpaas.request.v20190821 import PushSimpleRequest
import json

        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
String accessKeyId = System.getenv("MPAAS_AK_ENV");
String accessKeySecret = System.getenv("MPAAS_SK_ENV");
# Initialize AcsClient instance
client = AcsClient(
"cn-hangzhou",
accessKeyId,      
accessKeySecret 
);

# Initialize a request and set parameters
request = PushSimpleRequest.PushSimpleRequest()
request.set_endpoint("mpaas.cn-hangzhou.aliyuncs.com")
request.set_AppId("ONEX570DA89211721")
request.set_WorkspaceId("test")
request.set_Title( "python测试")
request.set_Content( "测试2")
request.set_DeliveryType(3)
request.set_TaskName("python测试任务")
request.set_ExpiredSeconds(600)
target = {"user1024":str(time.time())}
request.set_TargetMsgkey(json.dumps(target))

# Print response
response = client.do_action_with_exception(request)
print response

Node.js 代码示例

const sdk = require('@alicloud/mpaas20190821');

const { default: Client, PushSimpleRequest } = sdk;
// 创建客户端
// 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
// 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
// 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
// 建议先完成环境变量配置
String accessKeyId = System.getenv("MPAAS_AK_ENV");
String accessKeySecret = System.getenv("MPAAS_SK_ENV");
const client = new Client({
  accessKeyId,      
  accessKeySecret, 
  endpoint: 'mpaas.cn-hangzhou.aliyuncs.com',
  apiVersion: '2019-08-21'
});
// 初始化 request
  const request = new PushSimpleRequest();
  request.appId = "ONEX570DA89211721";
  request.workspaceId = "test";
  request.title = "Node测试";
  request.content = "测试";
  request.deliveryType = 3;
  request.taskName = "Node测试任务";
  request.expiredSeconds=600;
  const extendedParam = {
    test: '自定义扩展参数'
  };
  request.extendedParams = JSON.stringify(extendedParam);
// value 为业务方消息id,请保持唯一
  const target = {
    "userid1024": String(new Date().valueOf())
  };
  request.targetMsgkey = JSON.stringify(target);

// 调用 API
try {
  client.pushSimple(request).then(res => {
    console.log('SUCCESS', res);
  }).catch(e => {
    console.log('FAIL', e);
  });
} catch(e) {
  console.log('ERROR', e);
}

PHP 代码示例

<?php

use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\MPaaS\MPaaS;
AlibabaCloud::accessKeyClient('accessKeyId', 'accessKeySecret')
    ->regionId('cn-hangzhou')
    ->asDefaultClient();

class Demo {
    public function run() {
        try {
               $this->simplePush();
        } catch (\Exception $e) {
        }
    }


    public function simplePush() {
        $request = MPaaS::v20190821()->pushSimple();
        $result = $request->withAppId("ONEX570DA89211721")
            ->withWorkspaceId("test")
            ->withTitle("PHP 测试")
            ->withContent("测试3")
            ->withDeliveryType(3)
            ->withTaskName("PHP 测试任务")
            ->withExpiredSeconds(600)
            ->withTargetMsgkey(
                json_encode(["userid1024" => "".time() ]
            ))
            // endpoint
            ->host("mpaas.cn-hangzhou.aliyuncs.com")
            // 是否开启 debug 模式
            ->debug(true)
            ->request();
    }
}

模板推送

模板推送指针对单个目标 ID 的消息推送,消息通过模板创建。多个 ID 可以使用同一个模板。

在调用本接口之前,确保已完成以下操作:

  • 在消息推送控制台上创建好目标模板,详细操作参见 创建模板

  • 引入 SDK 依赖,详见 SDK 准备

请求参数

参数名称

类型

是否必填

示例

描述

classification

String

1

用于传递 vivo 推送通道的消息类型:

  • 0 - 运营类消息

  • 1 - 系统类消息

不填则默认为 1。

taskName

String

模板测试

推送任务名称。

appId

String

ONEX570DA89211721

mPaaS App ID

workspaceId

String

test

mPaaS 工作空间

deliveryType

Long

3

目标 ID 类型,数值选择如下:

  • 1 - Android 设备维度

  • 2 - iOS 设备维度

  • 3 - 用户维度

  • 5 - 实时活动 pushToken

  • 6 - 实时活动 activityId

  • 7 - HarmonyOS 设备维度

targetMsgkey

String

{“user1024”:”1578807462788”}

推送目标,为 Map 形式:

  • key:为目标,配合 deliveryType

    • 如果 deliveryType 为 1 ,则 key 为 Android 设备 ID。

    • 如果 deliveryType 为 2,则 key 为 iOS 设备 ID。

    • 如果 deliveryType 为 3 ,则 key 为用户 ID,即用户调用绑定接口时传入的 userid 值。

    • 如果 deliveryType 为 7,则 key 为鸿蒙设备 ID。

  • value:消息业务 ID,用户自定义,必须保持唯一。

说明

推送目标不可以超过 10 个,即 targetMsgkey 参数最多可传入 10 个键值对。

expiredSeconds

Long

300

消息有效期,单位为秒。

templateName

String

测试模板

模板名称,在控制台创建模板。

templateKeyValue

String

{“money”:”200”,”name”:”张三”}

模板参数,为 map 格式,和 templateName 指定的模板对应,key 为占位符名称,value 为要替换的值,例如模板内容为(两个 # 之间为占位符名称) 恭喜#name#中了#money#元

extendedParams

String

{“key1”:”value1”}

扩展参数,为 Map 形式。

notifyType

String

表示消息通道类型:

  • transparent - MPS 自建通道

  • notify - 默认通道

strategyType

Integer

1

推送策略类型:

  • 0 - 立即

  • 1 - 定时

  • 2 - 循环

不填则默认为 0。

StrategyContent

String

{\”fixedTime\”:1630303126000,\”startTime\”:1625673600000,\”endTime\”:1630303126000,\”circleType\”:1,\”circleValue\”:[1, 7],\”time\”:\”13:45:11\”}

推送策略详情(JSON 字符串)。strategyType 不等于 0 时必填。具体参数详见下方的 StrategyContent 字段说明

transparentMessagePayload

Map<String, JSONObject>

-

厂商透传消息体。

  • 键 key:厂商渠道类型

    • 华为通道为 hms

    • 荣耀通道为 honor

    • 谷歌 firebase 通道为 fcm

    • 鸿蒙通道为 harmonyos

  • value:透传消息体。推送给厂商的透传消息体使用该 value 值

透传消息体的格式如下:

{
    "data": "{\"name\":\"123hms\"}",
    "android":
    {
        "category": "VOIP",
        "ttl": "600s",
        "urgency": "HIGH"
    },
    "token":
    [
        "9912981981wqdq2112291fcm001saa222222222ggwerfwgsas2cc3"
    ]
}

transparentMessageUrgency

String

-

厂商透传消息优先级(transparentMessagePayload 有值时有效)。

目前仅华为、荣耀以及鸿蒙支持,有 HIGH/NORMAL 可选。

针对华为、荣耀而言:

  • HIGH:表示高优先透传

  • NORMAL:或者不传参表示普通透传

针对鸿蒙而言:

  • HIGH:当前消息是透传消息

  • NORMAL:当前消息是后台消息

smsStrategy

int

2

短信策略:

  • 0 - 无(默认)

  • 1 - 补发

  • 2 - 并发

smsSignName

String

mPaaS 测试

短信签名

smsTemplateCode

String

SMS_216070269

短信模板 ID

smsTemplateParam

StringString

{\"code\": 123456}

短信模板变量对应的实际值,JSON 格式。

thirdChannelCategory

Map

thirdChannelCategory: {

"hms": "9", //华为 FINANCE 财务类型消息

"vivo": "1"

//vivo IM 类型消息

}

用于传递华为消息分类以及 vivo 二级消息分类参数,详情请参见 厂商消息分类

miChannelId

String

"123321"

小米厂商推送渠道的 channelId

activityEvent

String

实时活动事件,可选 update/end:

  • update - 更新事件

  • end - 结束事件

activityContentState

JSONObject

实时活动消息的 content-state,需和客户端定义的参数保持一致。

dismissalDate

long

实时活动消息过期时间(秒级时间戳),可选字段,不传则按 iOS 系统默认失效时间 12h。

说明

关于 smsStrategy 参数:

  • 如果 smsStrategy 的值不为 0,则 smsSignNamesmsTemplateCodesmsTemplateParam 必填。

关于 activityEvent 参数:

  • activityEvent 为 end 事件时,dismissalDate 配置的过期时间才会生效。

  • activityEvent 为 update 事件时,dismissalDate 配置的过期时间不会生效。

  • 若传 end 事件但不传 dismissalDate,iOS 系统默认 4h 后结束实时活动。

StrategyContent 字段说明

JSON 格式转化为 String 传值。

参数名称

类型

是否必填

示例

描述

fixedTime

long

1630303126000

定时推送时间戳(单位:毫秒,精确到秒)。推送策略类型为定时(strategyType 值为 1)时,fixedTime 必填。

startTime

long

1640966400000

循环周期开始时间戳(单位:毫秒,精确到天)。推送策略类型为循环(strategyType 值为 2)时,startTime 必填。

endTime

long

1672416000000

循环周期结束时间戳(单位:毫秒,精确到天),循环结束时间不得超过当天后的 180 天。推送策略类型为循环(strategyType 值为 2)时,endTime 必填。

circleType

int

3

循环类型:

  • 1 - 每天

  • 2 - 每周

  • 3 - 每月

推送策略类型为循环(strategyType 值为 2)时,circleType 必填。

circleValue

int[]

[1,3]

循环值:

  • 若循环类型为每天:空。

  • 若循环类型为每周:设置每周循环的时间,例如 [1,3] 表示每周 1 和周 3。

  • 若循环类型为每月:设置每月循环推送的时间,例如 [1,3] 表示每月 1 号和 3 号。

推送策略类型为循环(strategyType 值为 2)且循环类型(circleType)非每天时,circleValue 必填。

time

String

09:45:11

循环推送时间(时分秒,格式为 HH:mm:ss) 。推送策略类型为循环(strategyType 值为 2)时,time 必填。

说明
  • 未执行的定时或循环推送任务总数上限默认为 100 条。

  • 循环周期为开始时间的 0 点到结束时间的 24 点。

  • 循环开始时间和结束时间均不可早于当天 0 点,且结束时间不得早于开始时间。

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

PushResult

JSON

请求结果

Success

boolean

true

请求状态。Success 参数值包含在 PushRresult JSON 字符串中。

ResultMsg

String

param is invalid

请求错误内容。ResultMsg 参数值包含在 PushRresult JSON 字符串中。

Data

String

903bf653c1b5442b9ba07684767bf9c2

定时推送任务 ID。strategyType 不等于 0 时,该字段不为空。

代码示例

请确保您的 AccessKey 拥有 AliyunMPAASFullAccess 权限,详情请参考 对 RAM 账号进行应用级别的访问控制

Java 代码示例

单击此处 查看下方代码示例中 AccessKeyId 与 AccessKeySecret 的获取方式 。

 DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
        // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
        // 本示例以将AccessKey ID和AccessKey Secret保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里。
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 

        IAcsClient client = new DefaultAcsClient(profile);
        // Create an API request and set parameters
        PushTemplateRequest request = new PushTemplateRequest();
        request.setAppId("ONEX570DA89211721");
        request.setWorkspaceId("test");
        request.setTemplateName("测试模板");
        //你好#name#,恭喜中奖#money#元
        Map<String,String> templatekv = new HashMap<String, String>();
        templatekv.put("name","张三");
        templatekv.put("money","200");
        request.setTemplateKeyValue(JSON.toJSONString(templatekv));
        request.setExpiredSeconds(600L);
        request.setTaskName("模板测试");
        request.setDeliveryType(3L);
        Map<String,String> target = new HashMap<String, String>();
        String msgKey = String.valueOf(System.currentTimeMillis());
        target.put("userid1024",msgKey);
        request.setTargetMsgkey(JSON.toJSONString(target));

        request.setStrategyType(2);
        request.setStrategyContent("{\"fixedTime\":1630303126000,\"startTime\":1625673600000,\"endTime\":1630303126000,\"circleType\":1,\"circleValue\":[1, 7],\"time\":\"13:45:11\"}");

        PushTemplateResponse response;
        try {
            response = client.getAcsResponse(request);

            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
        } catch (ClientException e) {
            e.printStackTrace();
        }

Python 代码示例

from aliyunsdkcore.client import AcsClient
from aliyunsdkmpaas.request.v20190821 import PushTemplateRequest
import json
import time

        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
# Initialize AcsClient instance
String accessKeyId = System.getenv("MPAAS_AK_ENV");
String accessKeySecret = System.getenv("MPAAS_SK_ENV");
client = AcsClient(
accessKeyId,      
accessKeySecret, 
"cn-hangzhou"
);

# Initialize a request and set parameters
request = PushTemplateRequest.PushTemplateRequest()
request.set_endpoint("mpaas.cn-hangzhou.aliyuncs.com")
request.set_AppId("ONEX570DA89211721")
request.set_WorkspaceId("test")
request.set_TemplateName("template1024")
templatekv = {"name":"张三","money":"200"}
request.set_TemplateKeyValue(json.dumps(templatekv))
request.set_DeliveryType(3)
request.set_TaskName("python模板测试任务")
request.set_ExpiredSeconds(600)
target = {"userid1024":str(time.time())}
request.set_TargetMsgkey(json.dumps(target))

# Print response
response = client.do_action_with_exception(request)
print response

Node.js 代码示例

const sdk = require('@alicloud/mpaas20190821');

const { default: Client, PushTemplateRequest } = sdk;
// 创建客户端
// 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
// 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
// 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
// 建议先完成环境变量配置
String accessKeyId = System.getenv("MPAAS_AK_ENV");
String accessKeySecret = System.getenv("MPAAS_SK_ENV");
const client = new Client({
  accessKeyId,      
  accessKeySecret, 
  endpoint: 'mpaas.cn-hangzhou.aliyuncs.com',
  apiVersion: '2019-08-21'
});
// 初始化 request
  const request = new PushTemplateRequest();
  request.appId = "ONEX570DA89211721";
  request.workspaceId = "test";
  request.templateName= "template1024";
  const templatekv = {
    name: '张三',
    money:'300'
  };
  request.templateKeyValue = JSON.stringify(templatekv);
  request.deliveryType = 3;
  request.taskName = "Node测试任务";
  request.expiredSeconds=600;
  const extendedParam = {
    test: '自定义扩展参数'
  };
  request.extendedParams = JSON.stringify(extendedParam);
  const target = {
    "userid1024": String(new Date().valueOf())
  };
  request.targetMsgkey = JSON.stringify(target);

// 调用 API
try {
  client.pushTemplate(request).then(res => {
    console.log('SUCCESS', res);
  }).catch(e => {
    console.log('FAIL', e);
  });
} catch(e) {
  console.log('ERROR', e);
}

PHP 代码示例

<?php

use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\MPaaS\MPaaS;
AlibabaCloud::accessKeyClient('accessKeyId', 'accessKeySecret')
    ->regionId('cn-hangzhou')
    ->asDefaultClient();

class Demo {
    public function run() {
        try {
              $this->templatePush();
        } catch (\Exception $e) {
        }
    }

    public function templatePush() {
        $request = MPaaS::v20190821()->pushTemplate();
        $result = $request->host("mpaas.cn-hangzhou.aliyuncs.com")
            // 是否开启 debug 模式
            ->debug(true)
            ->withAppId("ONEX570DA89211721")
            ->withWorkspaceId("test")
            ->withTemplateName("template1024")
            ->withTemplateKeyValue(json_encode(["name" => "张三", "money" => "200"]))
            ->withDeliveryType(3)
            ->withTaskName("PHP 测试任务")
            ->withExpiredSeconds(600)
            ->withTargetMsgkey(
                json_encode(["userid1024" => "".time() ])
            )
            ->request();
    }
}

批量推送

对各个推送 ID 推送不同消息。通过替换模板占位符的方式,创建针对某一推送 ID 的个性化消息。与模板推送的区别在于,每一个推送 ID 可以收到内容不相同的消息。

重要

当推送目标为移动分析人群或自定义标签人群时,不支持定时和循环推送。

在调用本接口之前,确保已完成以下操作:

  • 在消息推送控制台上创建好目标模板,并确保模板中存在占位符,否则将无法实现消息的个性化推送(即对不同推送 ID 推送不同消息)。详细操作参见 创建模板

  • 引入 SDK 依赖,详见 SDK 准备

请求参数

参数名称

类型

是否必填

示例

描述

classification

String

1

用于传递 vivo 推送通道的消息类型:

  • 0 - 运营类消息

  • 1 - 系统类消息

不填则默认为 1。

taskName

String

批量测试

推送任务名称。

appId

String

ONEX570DA89211721

mPaaS App ID

workspaceId

String

test

mPaaS 工作空间

deliveryType

Long

3

目标 ID 类型,数值选择如下:

  • 1 - Android 设备维度

  • 2 - iOS 设备维度

  • 3 - 用户维度

  • 7 - HarmonyOS 设备维度

说明

用户维度和设备维度的目标最多可以传 100 个。

templateName

String

测试模板

模板名称,在控制台创建模板。

targetMsgs

List

targetMsgs 对象列表

目标对象列表,参数详见下方的 targetMsgs 对象说明

expiredSeconds

Long

300

消息有效期,单位为秒。

extendedParams

String

{“key1”:”value1”}

统一扩展参数,为 Map 形式。

notifyType

String

表示消息通道类型:

  • transparent - MPS 自建通道

  • notify - 默认通道

strategyType

Integer

1

推送策略类型:

  • 0 - 立即

  • 1 - 定时

  • 2 - 循环

不填则默认为 0。

StrategyContent

String

{\”fixedTime\”:1630303126000,\”startTime\”:1625673600000,\”endTime\”:1630303126000,\”circleType\”:1,\”circleValue\”:[1, 7],\”time\”:\”13:45:11\”}

推送策略详情(JSON 字符串)。strategyType 不等于 0 时必填。具体参数详见下方的 StrategyContent 字段说明

transparentMessagePayload

Map<String, JSONObject>

-

厂商透传消息体。

  • 键 key:厂商渠道类型

    • 华为通道为 hms

    • 荣耀通道为 honor

    • 谷歌 firebase 通道为 fcm

    • 鸿蒙通道为 harmonyos

  • value:透传消息体。推送给厂商的透传消息体使用该 value 值

透传消息体的格式如下:

{
	"data": "{\"name\":\"123hms\"}",
	"android": {
		"category": "VOIP",
		"ttl": "600s",
		"urgency": "HIGH"
	},
	"token": [
		"9912981981wqdq2112291fcm001saa222222222ggwerfw gsas2cc3"
	]
}

transparentMessageUrgency

String

-

厂商透传消息优先级(transparentMessagePayload 有值时有效)。

目前仅华为、荣耀以及鸿蒙支持,有 HIGH/NORMAL 可选。

针对华为、荣耀而言:

  • HIGH:表示高优先透传

  • NORMAL:或者不传参表示普通透传

针对鸿蒙而言:

  • HIGH:当前消息是透传消息

  • NORMAL:当前消息是后台消息

thirdChannelCategory

Map

thirdChannelCategory: {

"hms": "9", //华为 FINANCE 财务类型消息

"vivo": "1"

//vivo IM 类型消息

}

用于传递华为消息分类以及 vivo 二级消息分类参数,详情请参见 厂商消息分类

miChannelId

String

"123321"

小米厂商推送渠道的 channelId

activityEvent

String

实时活动事件,可选 update/end:

  • update - 更新事件

  • end - 结束事件

activityContentState

JSONObject

实时活动消息的 content-state,需和客户端定义的参数保持一致

dismissalDate

long

实时活动消息过期时间(秒级时间戳),可选字段,不传则按 iOS 系统默认失效时间 12h。

说明

关于 activityEvent 参数:

  • activityEvent 为 end 事件时,dismissalDate 配置的过期时间才会生效。

  • activityEvent 为 update 事件时,dismissalDate 配置的过期时间不会生效。

  • 若传 end 事件但不传 dismissalDate,iOS 系统默认 4h 后结束实时活动。

targetMsgs 对象说明

参数名称

类型

是否必填

示例

描述

target

String

userid1024

目标 ID,根据 deliveryType 类型填写。

msgKey

String

1578807462788

业务消息 ID,用于消息的排查。由用户定义,不可重复。

templateKeyValue

String

{“money”:”200”,”name”:”张三”}

模板参数,为 Map 形式,和 templateName 指定的模板对应,key 为占位符名称,value 为要替换的值,例如模板内容为(两个 # 之间为占位符名称) 恭喜#name#中了#money#元

extendedParams

String

{“key1”:”value1”}

扩展参数,为 map 形式,针对每条消息的不同扩展参数。

StrategyContent 字段说明

JSON 格式转化为 String 传值。

参数名称

类型

是否必填

示例

描述

fixedTime

long

1630303126000

定时推送时间戳(单位:毫秒,精确到秒)。推送策略类型为定时(strategyType 值为 1)时,fixedTime 必填。

startTime

long

1640966400000

循环周期开始时间戳(单位:毫秒,精确到天)。推送策略类型为循环(strategyType 值为 2)时,startTime 必填。

endTime

long

1672416000000

循环周期结束时间戳(单位:毫秒,精确到天),循环结束时间不得超过当天后的 180 天。推送策略类型为循环(strategyType 值为 2)时,endTime 必填。

circleType

int

3

循环类型:

  • 1 - 每天

  • 2 - 每周

  • 3 - 每月

推送策略类型为循环(strategyType 值为 2)时,circleType 必填。

circleValue

int[]

[1,3]

循环值:

  • 若循环类型为每天:空

  • 若循环类型为每周:设置每周循环的时间,例如 [1,3] 表示每周 1 和周 3。

  • 若循环类型为每月:设置每月循环推送的时间,例如 [1,3] 表示每月 1 号和 3 号。

推送策略类型为循环(strategyType 值为 2)且循环类型(circleType)非每天时,circleValue 必填。

time

String

09:45:11

循环推送时间(时分秒,格式为 HH:mm:ss) 。推送策略类型为循环(strategyType 值为 2)时,time 必填。

说明
  • 未执行的定时或循环推送任务总数上限默认为 100 条。

  • 循环周期为开始时间的 0 点到结束时间的 24 点。

  • 循环开始时间和结束时间均不可早于当天 0 点,且结束时间不得早于开始时间。

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

PushResult

JSON

请求结果

Success

boolean

true

请求状态。Success 参数值包含在返回的 PushRresult JSON 字符串中。

ResultMsg

String

param is invalid

请求错误内容。ResultMsg 参数值包含在返回的 PushRresult JSON 字符串中。

Data

String

903bf653c1b5442b9ba07684767bf9c2

定时推送任务 ID。strategyType 不等于 0 时,该字段不为空。

代码示例

请确保您的 AccessKey 拥有 AliyunMPAASFullAccess 权限,详情请参考 对 RAM 账号进行应用级别的访问控制

Java 代码示例

单击此处 查看下方代码示例中 AccessKeyId 与 AccessKeySecret 的获取方式。

 DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置。
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 

        IAcsClient client = new DefaultAcsClient(profile);
        // Create an API request and set parameters
        PushMultipleRequest request = new PushMultipleRequest();
        request.setAppId("ONEX570DA89211721");
        request.setWorkspaceId("test");
        request.setDeliveryType(3L);
        request.setTaskName("批量测试");
        request.setTemplateName("测试模板");
        //你好#name#,恭喜中奖#money#元
        List<PushMultipleRequest.TargetMsg> targetMsgs = new ArrayList<PushMultipleRequest.TargetMsg>();
        PushMultipleRequest.TargetMsg targetMsg = new PushMultipleRequest.TargetMsg();
        targetMsg.setTarget("userid1024");
        targetMsg.setMsgKey(String.valueOf(System.currentTimeMillis()));
        Map<String, String> templatekv = new HashMap<String, String>();
        templatekv.put("name", "张三");
        templatekv.put("money", "200");
        targetMsg.setTemplateKeyValue(JSON.toJSONString(templatekv));
        //目标数量不要超过 400 个
        targetMsgs.add(targetMsg);
        request.setTargetMsgs(targetMsgs);
        request.setExpiredSeconds(600L);

        request.setStrategyType(2);
        request.setStrategyContent("{\"fixedTime\":1630303126000,\"startTime\":1625673600000,\"endTime\":1630303126000,\"circleType\":1,\"circleValue\":[1, 7],\"time\":\"13:45:11\"}");

        PushMultipleResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
            System.out.println(response.getPushResult().getData());  // 推送任务 ID 或定时推送任务 ID
        } catch (ClientException e) {
            e.printStackTrace();
        }

Python 代码示例

# -*- coding: utf8 -*-

from aliyunsdkcore.client import AcsClient
from aliyunsdkmpaas.request.v20190821 import PushMultipleRequest
import json
import time

// 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
// 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
// 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
// 建议先完成环境变量配置
# Initialize AcsClient instance
String accessKeyId = System.getenv("MPAAS_AK_ENV");
String accessKeySecret = System.getenv("MPAAS_SK_ENV");
client = AcsClient(
accessKeyId,      
accessKeySecret,  
"cn-hangzhou"
);

# Initialize a request and set parameters
request = PushMultipleRequest.PushMultipleRequest()
request.set_endpoint("mpaas.cn-hangzhou.aliyuncs.com")
request.set_AppId("ONEX570DA89211721")
request.set_WorkspaceId("test")
request.set_TemplateName("template1024")
request.set_DeliveryType(3)
request.set_TaskName("python测试任务")
request.set_ExpiredSeconds(600)
msgkey = str(time.time())
targets = [
  {
    "Target": "user1024",
    "MsgKey": msgkey,
    "TemplateKeyValue": {
      "name": "张三",
      "money": "200"
    }
  }
]
request.set_TargetMsgs(targets)
# Print response
response = client.do_action_with_exception(request)
print response

Node.js 代码示例

const sdk = require('@alicloud/mpaas20190821');

const { default: Client, PushMultipleRequest,PushMultipleRequestTargetMsg } = sdk;
// 创建客户端
// 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
// 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
// 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
// 建议先完成环境变量配置
String accessKeyId = System.getenv("MPAAS_AK_ENV");
String accessKeySecret = System.getenv("MPAAS_SK_ENV");
const client = new Client({
  accessKeyId,      
  accessKeySecret, 
  endpoint: 'mpaas.cn-hangzhou.aliyuncs.com',
  apiVersion: '2019-08-21'
});
// 初始化 request
  const request = new PushMultipleRequest();
  request.appId = "ONEX570DA89211721";
  request.workspaceId = "test";
  request.templateName= "template1024";
  const templatekv = {
    name: '张三',
    money:'300'
  };
  //request.templateKeyValue = JSON.stringify(templatekv);

  request.deliveryType = 3;
  request.taskName = "Node 测试任务";
  request.expiredSeconds=600;
  const extendedParam = {
    test: '自定义扩展参数'
  };
  request.extendedParams = JSON.stringify(extendedParam);

  const targetMsgkey = new PushMultipleRequestTargetMsg();
  targetMsgkey.target = "userid1024";
  targetMsgkey.msgKey = String(new Date().valueOf());
  targetMsgkey.templateKeyValue = JSON.stringify(templatekv);;
  request.targetMsg = [targetMsgkey];

// 调用 API
try {
  client.pushMultiple(request).then(res => {
    console.log('SUCCESS', res);
  }).catch(e => {
    console.log('FAIL', e);
  });
} catch(e) {
  console.log('ERROR', e);
}

PHP 代码示例

<?php

use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\MPaaS\MPaaS;
AlibabaCloud::accessKeyClient('accessKeyId', 'accessKeySecret')
    ->regionId('cn-hangzhou')
    ->asDefaultClient();

class Demo {
    public function run() {
        try {
              $this->multiPush();
        } catch (\Exception $e) {
        }
    }


   public function multiPush() {
        $request = MPaaS::v20190821()->pushMultiple();
        $result = $request->host("mpaas.cn-hangzhou.aliyuncs.com")
            // 是否开启 debug 模式
            ->debug(true)
            ->withAppId("ONEX570DA89211721")
            ->withWorkspaceId("test")
            ->withTemplateName("template1024")
            ->withDeliveryType(3)
            ->withTaskName("PHP测试批量任务")
            ->withExpiredSeconds(600)
            ->withTargetMsg(
                [
                    [
                        "Target" => "userid1024",
                        "MsgKey" => "" . time(),
                        "TemplateKeyValue" => json_encode([
                            "name" => "张三",
                            "money" => "200",
                        ])
                    ]
                ]
            )
            ->request();
    }
}

群发推送

对全网设备推送相同消息,消息通过模板创建。

重要

当推送目标为移动分析人群或自定义标签人群时,不支持定时和循环推送。

在调用本接口之前,确保已完成以下操作:

  • 在消息推送控制台上创建好目标模板,并确保模板中存在占位符,否则将无法实现消息的个性化推送(即对不同推送 ID 推送不同消息)。详细操作参见 创建模板

  • 引入 SDK 依赖,详见 SDK 准备

请求参数

参数名称

类型

是否必填

示例

描述

classification

String

1

用于传递 vivo 推送通道的消息类型:

  • 0 - 运营类消息

  • 1 - 系统类消息

不填则默认为 1。

taskName

String

群发测试任务

推送任务名称。

appId

String

ONEX570DA89211721

mPaaS App ID

workspaceId

String

test

mPaaS 工作空间

deliveryType

Long

1

目标 ID 类型,数值选择:

  • 1 - Android 群发

  • 2 - iOS 群发

  • 7- HarmonyOS 群发

msgkey

String

1578807462788

业务方消息 ID,用户自定义,不可重复。

expiredSeconds

Long

300

消息有效期,单位为秒。

templateName

String

群发模板

模板名称,在控制台创建模板。

templateKeyValue

String

{“content”:”公告内容”}

模板参数,为 Map 格式,和 templateName 指定的模板对应,key 为占位符名称,value 为要替换的值。

pushStatus

Long

0

群发时,推送登录状态:

  • 0 - 绑定的用户(默认)

  • 1 - 所有用户(包括绑定和解绑的用户)

  • 2 - 解绑的用户

bindPeriod

Integer

登录时长,当 pushStatus 值为 0 时必填:

  • 1 - 7 天内绑定的用户

  • 2 - 15 天内绑定的用户

  • 3 - 60 天内绑定的用户

  • 4 - 永久

说明

bindPeriod 参数仅在非金环境中可配置。

unBindPeriod

Long

退出登录时长,当 pushStatus 值为 1 或 2 时必填:

  • 1 - 7 天内解绑的用户

  • 2 - 15 天内解绑的用户

  • 3 - 60 天内解绑的用户

  • 4 - 永久

androidChannel

Integer

安卓消息通道:

  • 1 - MPS 自建通道

  • 2 - 默认通道

strategyType

int

1

推送策略类型:

  • 0 - 立即

  • 1 - 定时

  • 2 - 循环

不填则默认为 0。

StrategyContent

String

{\”fixedTime\”:1630303126000,\”startTime\”:1625673600000,\”endTime\”:1630303126000,\”circleType\”:1,\”circleValue\”:[1, 7],\”time\”:\”13:45:11\”}

推送策略详情(JSON 字符串)。strategyType 不等于 0 时必填。具体参数详见下方的 StrategyContent 字段说明。

transparentMessagePayload

Map<String, JSONObject>

-

厂商透传消息体。

  • 键 key:厂商渠道类型

    • 华为通道为 hms

    • 荣耀通道为 honor

    • 谷歌 firebase 通道为 fcm

    • 鸿蒙通道为 harmonyos

  • value:透传消息体。推送给厂商的透传消息体使用该 value 值

透传消息体的格式如下:

{
	"data": "{\"name\":\"123hms\"}",
	"android": {
		"category": "VOIP",
		"ttl": "600s",
		"urgency": "HIGH"
	},
	"token": [
		"9912981981wqdq2112291fcm001saa222222222ggwerfw gsas2cc3"
	]
}

transparentMessageUrgency

String

-

厂商透传消息优先级(transparentMessagePayload 有值时有效)。

目前仅华为、荣耀以及鸿蒙支持,有 HIGH/NORMAL 可选。

针对华为、荣耀而言:

  • HIGH:表示高优先透传

  • NORMAL:或者不传参表示普通透传

针对鸿蒙而言:

  • HIGH:当前消息是透传消息

  • NORMAL:当前消息是后台消息

thirdChannelCategory

Map

thirdChannelCategory: {

"hms": "9", //华为 FINANCE 财务类型消息

"vivo": "1"

//vivo IM 类型消息

}

用于传递华为消息分类以及 vivo 二级消息分类参数,详情请参见 厂商消息分类

miChannelId

String

"123321"

小米厂商推送渠道的 channelId

StrategyContent 字段说明

JSON 格式转化为 String 传值。

参数名称

类型

是否必填

示例

描述

fixedTime

long

1630303126000

定时推送时间戳(单位:毫秒,精确到秒)。推送策略类型为定时(strategyType 值为 1)时,fixedTime 必填。

startTime

long

1640966400000

循环周期开始时间戳(单位:毫秒,精确到天)。推送策略类型为循环(strategyType 值为 2)时,startTime 必填。

endTime

long

1672416000000

循环周期结束时间戳(单位:毫秒,精确到天),循环结束时间不得超过当天后的 180 天。推送策略类型为循环(strategyType 值为 2)时,endTime 必填。

circleType

int

3

循环类型:

  • 1 - 每天

  • 2 - 每周

  • 3 - 每月

推送策略类型为循环(strategyType 值为 2)时,circleType 必填。

circleValue

int[]

[1,3]

循环值:

  • 若循环类型为每天:空

  • 若循环类型为每周:设置每周循环的时间,例如 [1,3] 表示每周 1 和周 3。

  • 若循环类型为每月:设置每月循环推送的时间,例如 [1,3] 表示每月 1 号和 3 号。

推送策略类型为循环(strategyType 值为 2)且循环类型(circleType)非每天时,circleValue 必填。

time

String

09:45:11

循环推送时间(时分秒,格式为 HH:mm:ss) 。推送策略类型为循环(strategyType 值为 2)时,time 必填。

说明
  • 未执行的定时或循环推送任务总数上限默认为 100 条。

  • 循环周期为开始时间的 0 点到结束时间的 24 点。

  • 循环开始时间和结束时间均不可早于当天 0 点,且结束时间不得早于开始时间。

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

PushResult

JSON

请求结果

Success

boolean

true

请求状态。Success 参数值包含在 PushRresult JSON 字符串中。

ResultMsg

String

param is invalid

请求错误内容。ResultMsg 参数值包含在 PushRresult JSON 字符串中。

Data

String

903bf653c1b5442b9ba07684767bf9c2

定时推送任务 ID。strategyType 不等于 0 时,该字段不为空。

代码示例

请确保您的 AccessKey 拥有 AliyunMPAASFullAccess 权限,详情请参考 对 RAM 账号进行应用级别的访问控制

Java 代码示例

单击此处 查看下方代码示例中 AccessKeyId 与 AccessKeySecret 的获取方式 。

DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 

        IAcsClient client = new DefaultAcsClient(profile);

        PushBroadcastRequest request = new PushBroadcastRequest();
        request.setAppId("ONEX570DA89211720");
        request.setWorkspaceId("test");
        request.setDeliveryType(2L);
        request.setMsgkey(String.valueOf(System.currentTimeMillis()));
        request.setExpiredSeconds(600L);
        request.setTaskName("群发任务");
        request.setTemplateName("群发测试");
        //这是一个公告:#content#
        Map<String, String> templatekv = new HashMap<String, String>();
        templatekv.put("content", "公告内容");
        request.setTemplateKeyValue(JSON.toJSONString(templatekv));

        request.setStrategyType(2);
        request.setStrategyContent("{\"fixedTime\":1630303126000,\"startTime\":1625673600000,\"endTime\":1630303126000,\"circleType\":1,\"circleValue\":[1, 7],\"time\":\"13:45:11\"}");    

        PushBroadcastResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
            System.out.println(response.getPushResult().getData());  // 推送任务 ID或定时推送任务 ID
        } catch (ClientException e) {
            e.printStackTrace();
        }

Python 代码示例

# -*- coding: utf8 -*-

from aliyunsdkcore.client import AcsClient
from aliyunsdkmpaas.request.v20190821 import PushBroadcastRequest
import json
import time

// 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
// 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
// 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
// 建议先完成环境变量配置
# Initialize AcsClient instance
String accessKeyId = System.getenv("MPAAS_AK_ENV");
String accessKeySecret = System.getenv("MPAAS_SK_ENV");
client = AcsClient(
accessKeyId,      
accessKeySecret, 
"cn-hangzhou"
);

# Initialize a request and set parameters
request = PushBroadcastRequest.PushBroadcastRequest()
request.set_endpoint("mpaas.cn-hangzhou.aliyuncs.com")
request.set_AppId("ONEX570DA89211720")
request.set_WorkspaceId("test")
request.set_TemplateName("broadcastTemplate")
templatekv = {"content":"这个一个公告"}
request.set_TemplateKeyValue(json.dumps(templatekv))
request.set_DeliveryType(1)
request.set_TaskName("python测试群发任务")
request.set_ExpiredSeconds(600)
request.set_Msgkey(str(time.time()))

# Print response
response = client.do_action_with_exception(request)
print response

Node.js 代码示例

const sdk = require('@alicloud/mpaas20190821');

const { default: Client, PushBroadcastRequest } = sdk;
// 创建客户端
// 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
// 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
// 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
// 建议先完成环境变量配置
String accessKeyId = System.getenv("MPAAS_AK_ENV");
String accessKeySecret = System.getenv("MPAAS_SK_ENV");
const client = new Client({
  accessKeyId,      
  accessKeySecret, 
  endpoint: 'mpaas.cn-hangzhou.aliyuncs.com',
  apiVersion: '2019-08-21'
});
// 初始化 request

  const request = new PushBroadcastRequest();
  request.appId = "ONEX570DA89211720";
  request.workspaceId = "test";
  request.templateName= "broadcastTemplate";
  const templatekv = {
    content: '这是公告哦',
  };
  request.templateKeyValue = JSON.stringify(templatekv);
  request.deliveryType = 1;
  request.taskName = "Node测试任务";
  request.expiredSeconds=600;
  const extendedParam = {
    test: '自定义扩展参数'
  };
  request.extendedParams = JSON.stringify(extendedParam);

  request.msgkey = String(new Date().valueOf())

// 调用 API
try {
  client.pushBroadcast(request).then(res => {
    console.log('SUCCESS', res);
  }).catch(e => {
    console.log('FAIL', e);
  });
} catch(e) {
  console.log('ERROR', e);
}

PHP 代码示例

<?php

use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\MPaaS\MPaaS;
AlibabaCloud::accessKeyClient('accessKeyId', 'accessKeySecret')
    ->regionId('cn-hangzhou')
    ->asDefaultClient();

class Demo {
    public function run() {
        try {
               $this->broadcastPush();
        } catch (\Exception $e) {
        }
    }


   public function broadcastPush(){
        $request = MPaaS::v20190821()->pushBroadcast();
        $result = $request->host("mpaas.cn-hangzhou.aliyuncs.com")
            // 是否开启 debug 模式
            ->debug(true)
            ->withAppId("ONEX570DA89211720")
            ->withWorkspaceId("test")
            ->withTemplateName("broadcastTemplate")
            ->withTemplateKeyValue(
                json_encode(["content" => "这是一个公告"])
            )
            ->withDeliveryType(1)
            ->withTaskName("PHP 测试群发任务")
            ->withExpiredSeconds(600)
            ->withMsgkey("". time())
            ->request();
    }
}

消息撤回

通过极简推送或模板推送方式推送的消息可通过消息 ID 撤回;通过批量推送和群发推送方式推送的消息可通过任务 ID 撤回。仅支持撤回最近 7 天内的消息。

通过消息 ID 撤回

支持撤回通过极简推送和模板推送发送的消息。

请求参数

参数名称

类型

是否必填

示例

描述

messageId

String

1578807462788

业务方消息 ID,用户自定义,用于在业务方系统中唯一标识消息。

targetId

String

user1024

目标 ID,若原消息以设备维度推送,则目标 ID 为设备 ID;若原消息以用户维度推送,则目标 ID 为用户 ID。

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

PushResult

JSON

请求结果

Success

boolean

true

请求状态。Success 参数值包含在 PushRresult JSON 字符串中。

ResultMsg

String

param is invalid

请求错误内容。ResultMsg 参数值包含在 PushRresult JSON 字符串中。

使用示例

DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 

        IAcsClient client = new DefaultAcsClient(profile);        

        RevokePushMessageRequest request = new RevokePushMessageRequest();
        request.setAppId("ONEX570DA89211720");
        request.setWorkspaceId("test");
        request.setMessageId("console_1624516744112");  // 业务方消息 ID
        request.setTargetId("mpaas_push_demo");         // 目标 ID

        RevokePushMessageResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
        } catch (ClientException e) {
            e.printStackTrace();
        }

通过任务 ID 撤回

支持撤回通过批量推送和群发推送发送的消息。

请求参数

参数名称

类型

是否必填

示例

描述

taskId

String

20842863

推送任务 ID,可在控制台推送任务列表中查询。

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

PushResult

JSON

请求结果

Success

boolean

true

请求状态。Success 参数值包含在 PushRresult JSON 字符串中。

ResultMsg

String

param is invalid

请求错误内容。ResultMsg 参数值包含在 PushRresult JSON 字符串中。

使用示例

DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 

        IAcsClient client = new DefaultAcsClient(profile);

        RevokePushTaskRequest request = new RevokePushTaskRequest();
        request.setAppId("ONEX570DA89211720");
        request.setWorkspaceId("test");
        request.setTaskId("20842863");     // 推送任务 ID

        RevokePushTaskResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
        } catch (ClientException e) {
            e.printStackTrace();
        }

使用分析

查询统计数据

查询消息推送统计数据,包括总推送条数、推送成功数、推送到达数、消息打开数、消息忽略数等数据。

请求参数

参数名称

类型

是否必填

示例

描述

appId

String

ONEX570DA89211721

mPaaS App ID

workspaceId

String

test

mPaaS 工作空间

startTime

long

1619798400000

要查询的时间范围的开始时间戳,以毫秒为单位,精确到天。

endTime

long

1624358433000

要查询的时间范围的结束时间戳,以毫秒为单位,精确到天。开始时间和结束时间间隔不能超过 90 天。

platform

String

ANDROID

平台,不传则表示查询全部。可选值:IOS,ANDROID,HARMONYOS

channel

String

ANDROID

推送通道,不传表示查询全部。可选值:IOS、FCM、HMS、MIUI、OPPO、VIVO、ANDROID(自建通道)、HARMONYOS

type

String

SIMPLE

推送类型,不传表示查询全部。可选值:SIMPLE、TEMPLATE、MULTIPLE、BROADCAST

taskId

String

20842863

推送任务 ID

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

ResultContent

JSON

响应内容

data

JSON

响应内容。该参数值包含在 ResultContent JSON 字符串中。

pushTotalNum

float

100

推送数

pushNum

float

100

推送成功数

arrivalNum

float

100

推送到达数

openNum

float

100

推送打开数

openRate

float

100

推送打开率

ignoreNum

float

100

推送忽略数

ignoreRate

float

100

推送忽略率

使用示例

DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 

        IAcsClient client = new DefaultAcsClient(profile);

        QueryPushAnalysisCoreIndexRequest request = new QueryPushAnalysisCoreIndexRequest();
        request.setAppId("ONEX570DA89211720");
        request.setWorkspaceId("test");
        request.setStartTime(Long.valueOf("1617206400000"));
        request.setEndTime(Long.valueOf("1624982400000"));
        request.setPlatform("ANDROID");
        request.setChannel("ANDROID");
        request.setType("SIMPLE");
        request.setTaskId("20842863");

        QueryPushAnalysisCoreIndexResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
        } catch (ClientException e) {
            e.printStackTrace();
        }

查询推送任务列表

查询通过控制台创建或通过调用 API 触发的批量推送任务和群发推送任务信息。

请求参数

参数名称

类型

是否必填

描述

描述

appId

String

ONEX570DA89211721

mPaaS App ID

workspaceId

String

test

mPaaS 工作空间

startTime

long

1619798400000

开始时间戳,以毫秒为单位,精确到天。

taskId

String

20842863

推送任务 ID

taskName

String

测试任务

推送任务名称

pageNumber

int

1

页码,默认为 1。

pageSize

int

10

页数,默认为 500。

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

ResultContent

JSON

响应内容

data

JSONArray

响应内容。该参数值包含在 ResultContent JSON 字符串中。

taskId

String

20927873

任务 ID

taskName

String

测试任务

任务名称

templateId

String

9108

模板 ID

templateName

String

测试模板

模板名称

type

long

3

推送类型,其中:

  • 2 - 批量推送

  • 3 - 群发推送

gmtCreate

long

1630052750000

创建时间

使用示例

DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 

        IAcsClient client = new DefaultAcsClient(profile);

        QueryPushAnalysisTaskListRequest request = new QueryPushAnalysisTaskListRequest();
        request.setAppId("ONEX570DA89211721");
        request.setWorkspaceId("default");
        request.setStartTime(Long.valueOf("1617206400000"));
        request.setTaskId("20845212");
        request.setTaskName("测试任务");
        request.setPageNumber(1);
        request.setPageSize(10);

        QueryPushAnalysisTaskListResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
        } catch (ClientException e) {
            e.printStackTrace();
        }

查询推送任务详情

查询通过控制台创建或通过调用 API 触发的批量推送任务和群发推送任务的任务详情。

请求参数

参数名称

类型

是否必填

示例

描述

appId

String

ONEX570DA89211721

mPaaS App ID

workspaceId

String

test

mPaaS 工作空间

taskId

String

20842863

推送任务 ID

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

ResultContent

JSON

响应内容

data

JSON

响应内容。该参数值包含在 ResultContent JSON 字符串中。

taskId

long

20927872

任务 ID

pushNum

float

10

推送数

pushSuccessNum

float

10

推送成功数

pushArrivalNum

float

10

推送到达数

startTime

long

1630052735000

开始时间(毫秒)

endTime

long

1630052831000

结束时间(毫秒)

duration

string

00 小时 01 分 36 秒

持续时间

使用示例

DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 

        IAcsClient client = new DefaultAcsClient(profile);

        QueryPushAnalysisTaskDetailRequest request = new QueryPushAnalysisTaskDetailRequest();
        request.setAppId("ONEXPREF4F5C52081557");
        request.setWorkspaceId("default");
        request.setTaskId("20845212");

        QueryPushAnalysisTaskDetailResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
        } catch (ClientException e) {
            e.printStackTrace();
        }

定时推送任务

查询定时推送任务列表

查询已创建的定时推送任务列表,包括定时推送任务和循环推送任务。

请求参数

参数名称

类型

是否必填

示例

描述

appId

String

ONEX570DA89211721

mPaaS App ID

workspaceId

String

test

mPaaS 工作空间

startTime

long

1619798400000

触发定时推送的开始时间戳,并非定时推送任务的创建时间。

endtTime

long

1630425600000

触发定时推送的结束时间戳。

type

int

0

推送方式,其中:

  • 0 - 极简推送

  • 1 - 模板推送

  • 2 - 批量推送

  • 3 - 群发推送

uniqueId

String

49ec0ed5a2a642bcbe139a2d7a419d6d

定时推送任务的唯一 ID。若传主任务 ID,则返回主任务下的所有子任务的信息;若传子任务 ID,则返回子任务的信息。

pageNumber

int

1

页码,默认为 1。

pageSize

int

10

分页大小,默认为 500。

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

ResultContent

JSON

响应内容

data

JSON

响应内容。该参数值包含在 ResultContent JSON 字符串中。

totalCount

int

10

总数

list

JSONArray

任务数组

uniqueId

String

56918166720e46e1bcc40195c9ca71db

定时推送任务的唯一 ID。

  • strategyType 值为 1,表示定时推送任务主 ID。

  • strategyType 值为 2,表示循环任务子 ID。

parentId

String

56918166720e46e1bcc40195c9ca71db

定时推送任务主 ID。

  • strategyType 值为 1,表示定时推送任务主 ID;

  • strategyType 值为 2,表示循环任务主 ID。

pushTime

Date

1630486972000

预计推送时间

pushTitle

String

测试标题

通知标题

pushContent

String

测试正文

通知内容

type

int

0

推送方式,其中:

  • 0 - 极简推送

  • 1 - 模板推送

  • 2 - 批量推送

  • 3 - 群发推送

deliveryType

int

1

推送类型,其中:

  • 1 - Android

  • 2 - iOS

  • 3 - UserId

  • 7 - HarmonyOS

strategyType

int

1

推送策略类型,其中:

  • 1 - 定时

  • 2 - 循环

executedStatus

int

0

是否执行,其中:

  • 0 - 未执行

  • 1 - 已执行

createType

int

0

创建方式,其中:

  • 0 - API

  • 1 - 控制台

gmtCreate

Date

1629971346000

创建时间

使用示例

DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 
        IAcsClient client = new DefaultAcsClient(profile);

        QueryPushSchedulerListRequest request = new QueryPushSchedulerListRequest();
        request.setAppId("ONEXPREF4F5C52081557");
        request.setWorkspaceId("default");
        request.setStartTime(Long.valueOf("1625068800000"));
        request.setEndTime(Long.valueOf("1630425600000"));
        request.setType(0);
        request.setUniqueId("49ec0ed5a2a642bcbe139a2d7a419d6d");
        request.setPageNumber(1);
        request.setPageSize(10);

        QueryPushSchedulerListResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
        } catch (ClientException e) {
            e.printStackTrace();
        }

取消定时推送任务

取消未执行的定时推送任务(包括循环推送任务),支持批量取消。

请求参数

参数名称

类型

是否必填

示例

描述

appId

String

ONEX570DA89211721

mPaaS App ID

workspaceId

String

test

mPaaS 工作空间

type

int

0

定时推送任务 ID 类型,默认为 0。

  • 0 - 主任务 ID,对应 parentId

  • 1 - 子任务 ID,对应uniqueId

uniqueIds

String

714613eb,714613ec,714613ed

定时推送任务的唯一 ID,多个 ID 以“,”分隔,上限为 30 个。

返回参数

参数名称

类型

示例

描述

RequestId

String

B589F4F4-CD68-3CE5-BDA0-6597F33E23916512

请求 ID

ResultCode

String

OK

请求结果码

ResultMessage

String

param is invalid

请求错误描述

ResultContent

String

{714613eb=1,714613ed=0}

取消结果,1 表示成功,0 表示失败。

使用示例

DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");
        // 创建 DefaultAcsClient 实例并初始化
        // 阿里云账号 AccessKey 拥有所有 API 的访问权限,风险很高。强烈建议您创建并使用 RAM 用户进行 API 访问或日常运维,请登录 RAM 控制台创建 RAM 用户
        // 此处以把 AccessKey 和 AccessKeySecret 保存在环境变量为例说明。您也可以根据业务需要,保存到配置文件里
        // 强烈建议不要把 AccessKey 和 AccessKeySecret 保存到代码里,会存在密钥泄漏风险
        // 建议先完成环境变量配置
        String accessKeyId = System.getenv("MPAAS_AK_ENV");
        String accessKeySecret = System.getenv("MPAAS_SK_ENV");
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",          // 地域 ID
            accessKeyId,      
            accessKeySecret); 
        IAcsClient client = new DefaultAcsClient(profile);

CancelPushSchedulerRequest request = new CancelPushSchedulerRequest();
        request.setAppId("ONEXPREF4F5C52081557");
        request.setWorkspaceId("default");
        request.setUniqueIds("49ec0ed5a2a642bcbe139a2d7a419d6d, 49ec0ed5a2a642bcbe139a2d7a419d6c");

        CancelPushSchedulerResponse response;
        try {
            response = client.getAcsResponse(request);
            System.out.println(response.getResultCode());
            System.out.println(response.getResultMessage());
        } catch (ClientException e) {
            e.printStackTrace();
        }

扩展参数

扩展参数会跟随消息体到达客户端,供用户自定义处理。

扩展参数包含以下三类:

  • 系统扩展参数

    这些扩展参数被系统占用,注意不要修改此类参数的 value 值。系统扩展参数包括 notifyTypeactionsilentpushTypetemplateCodechanneltaskId

  • 系统具有一定意义的扩展参数

    这些扩展参数被系统占用,且具有一定的意义,您可以配置此类扩展参数的 value 值。系统具有一定意义的扩展参数及其说明参见下表。

    Key

    说明

    sound

    自定义铃声,参数值配置为铃声的路径,本参数仅对小米和苹果手机有效。

    badge

    应用图标角标,参数值配置为具体数值。本扩展参数会跟随消息体到达客户端。

    • 对于 Android 手机,您需要处理角标的实现逻辑。

    • 对于苹果手机,手机系统将自动实现角标。消息推送至目标手机后,应用图标的角标即会显示为参数值中配置的数值。

    mutable-content

    APNs 自定义推送标识,推送的时候携带本参数即表示支持 iOS 10 的 UNNotificationServiceExtension;若不携带本参数,则为普通推送。参数值配置为 1。

    badge_add_num

    华为通道推送角标增加数。

    badge_class

    华为通道桌面图标对应的应用入口 Activity 类。

    big_text

    大文本样式,value 固定为 1,填写其他值无效。本参数仅对小米和华为手机有效。

  • 用户自定义扩展参数

    除了系统扩展参数和系统具有一定意义的扩展参数,其他的参数 key 都属于用户扩展参数。用户自定义扩展参数会随消息体中的扩展参数到达客户端,供用户自定义处理。

API 调用结果码

结果码

结果消息

说明

100

SUCCESS

成功。

-1

SIGNATURE_MISMATCH

签名不匹配。

3001

NEED_DELIVERYTOKEN

deliveryToken 为空。

3002

NEED_FILE

文件为空。

3003

NEED_APPID_WORKSPACEID

appid 或 workspace 为空。

3007

APPID_WRONG

appid 或 workspace 不合法。

3008

OS_TYPE_NOT_SUPPORTED

推送平台类型不支持。

3009

DELIVERY_TYPE_NOT_SUPPORTED

目标 ID 类型不支持。

3012

NEED_USERID

UserId 为空。

3019

TASKNAME_NULL

任务名称为空。

3020

EXPIREDSECONDS_WRONG

消息超时时间非法。

3021

TOKEN_OR_USERID_NULL

目标为空。

3022

TEMPLATE_NOT_EXIST

模板不存在。

3023

TEMPLATEKV_NOT_ENOUGH

模板参数不匹配。

3024

PAYLOAD_NOT_ENOUGH

标题或内容为空。

3025

NEED_TEMPLATE

模板为空。

3026

EXPIREDTIME_TOO_LONG

消息有效期过长。

3028

INVALID_PARAM

参数非法。

3029

SINGLE_PUSH_TARGET_TOO_MUCH

推送目标过多。

3030

BROADCAST_ONLY_SUPPORT_BY_DEVICE

仅支持设备维度的群发。

3031

REQUEST_SHOULD_BE_UTF8

请求体编码需为 UTF-8。

3032

REST_API_SWITCH_NOT_OPEN

推送 API 接口关闭。

3033

UNKNOWN_REST_SIGN_TYPE

签名类型不支持。

3035

EXTEND_PARAM_TO_MUCH

扩展字段太多,不能超过 20 个。

3036

TEMPLATE_ALREADY_EXIST

模板已存在。

3037

TEMPLATE_NAME_NULL

模板名称为空。

3038

TEMPLATE_NAME_INVALID

模板名称非法。

3039

TEMPLATE_CONTENT_INVALID

模板内容非法。

3040

TEMPLATE_TITLE_INVALID

模板标题非法。

3041

TEMPLATE_DESC_INFO_INVALID

模板描述非法。

3042

TEMPLATE_URI_INVALID

模板 URI 非法。

3043

SINGLE_PUSH_CONTENT_TOO_LONG

消息体过长。

3044

INVALID_EXTEND_PARAM

扩展参数非法。

3049

MULTIPLE_INNER_EXTEND_PARAM_TO_MUCH

批量推送内部扩展参数需小于 10 个。

3050

MSG_PAYLOAD_TOO_LONG

消息体太长。

3051

BROADCAST_ALL_USER_NEED_UNBIND_PERIOD

群发推送针对所有用户(登录用户 + 登出用户),必须传解绑参数。

3052

BROADCAST_ALL_USER_UNBIND_PERIOD_INVALID

群发解绑参数非法。

3053

BROADCAST_ALL_USER_NOT_SUPPORT_SELFCHANNEL_ANDROID

群发所有用户,不支持自建通道群发。

3054

DELIVERYTOKEN_INVALID

自建通道 token 非法。

3055

MULTIPLE_TARGET_NUMBER_TOO_MUCH

批量推送目标过多。

3056

TEMPLATE_NUM_TOO_MUCH

模板数量过多。

3057

ANDROID_CHANNEL_PARAM_INVALID

androidChannel 参数非法。

3058

BADGE_ADD_NUM_INVALID

角标参数非法。

3059

BADGE_ADD_NUM_NEED_BADGE_CLASS

badge_add_num 参数需要 badge_class 参数。

8014

ACCOUNT_NO_PERMISSION

账号无权限。请检查 AK/SK 与 appId 和 workspaceId 是否一致。

9000

SYSTEM_ERROR

系统错误。