文档

Java SDK 接入

更新时间:

本文介绍如何以 Java SDK 的方式在服务端接入数据同步服务。

引入 Jar 包

完成 Maven 配置后,在主控 pom.xml 文件中引入如下依赖:

说明

对于非金区(非金融区)用户,消息推送 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>

环境变量配置

配置环境变量 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 系统。

接口说明

单数据同步接口

单数据同步接口是指同步数据到指定的用户或者设备。

参数说明

业务参数信息如下:

名称

类型

是否必须

示例

描述

appId

String

ONEX570DA892117

从 mPaaS 控制台获取的 App ID。

workspaceId

String

PROD

从 mPaaS 控制台获取的 Workspace ID。

bizType

String

UCHAT

在 mPaaS 控制台配置的同步标识,参见 控制台简介

linkToken

String

推送目标 ID,如果是基于用户推送,填入用户 ID。如果同步配置是基于设备推送,填入设备 ID。

payload

String

testtestatapalayd

实际业务消息体,自定义格式,长度不超过 4096。

thirdMsgId

String

1760339273

一次数据同步请求 ID。同一个同步标识内唯一,ID 重复的请求将会被忽略。须小于 100 Byte。

osType

String

iOS/Android

按手机平台过滤进行推送。默认情况下不传递参数,即不过滤,iOS 与 Android 平台均会推送。

appMinVersion

String

0.0.0.0

推送数据过滤客户端版本,仅向大于等于该版本号的客户端发送推送。

appMaxVersion

String

100.100.100.100

推送数据过滤客户端版本,仅向小于等于该版本号的客户端发送推送。

validTimeStart

String

1584448493913

当前时间大于等于 validTimeStart 时才会推送。

validTimeEnd

String

1584452093913

当前时间小于等于 validTimeEnd 时才会推送。

单条数据同步结果码

结果码

描述

解决方法

SUCCESS

成功

成功

ARGS_IS_NULL

必要参数为空

检查是否已完整按照非空逻辑传递参数。

PAYLOAD_LONG

PAYLOAD 消息体过长

检查 playload 属性参数长度是否超过限制。

THIRD_MSG_ID_LONG

三方业务 ID 过长

检查三方业务 ID 长度是否超过限制。

BIZ_NOT_ONLINE

业务场景同步标识未提交上线

前往 mPaaS 控制台 > 移动同步 检查 bizType 对应同步标识已配置并提交上线。

THIRD_MSG_ID_IS_NULL

三方业务 ID 为空

检查三方业务 ID 是否为空。

SYSTEM_ERROR

系统异常

联系技术支持确认系统异常原因。

INVALID_TENANT_ID

无效租户 ID

检查 appId 是否正确,是否有权限使用。

代码示例

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.mpaas.model.v20201028.CreateOpenSingleDataRequest;
import com.aliyuncs.mpaas.model.v20201028.CreateOpenSingleDataResponse;
import com.aliyuncs.profile.DefaultProfile;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;

public class MsyncPopDemo {

    public static void main(String[] args) {
        //请求信息,除 AccessKey ID  AccessKey Secret 外固定即可
        DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");

        // 阿里云账号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");

        // 创建 DefaultAcsClient 实例并初始化
        DefaultProfile profile = DefaultProfile.getProfile(
                "cn-hangzhou", // 地域 ID
                accessKeyId,   // RAM 账号的 AccessKey ID
                accessKeySecret);  // RAM 账号的 AccessKey Secret
        IAcsClient client = new DefaultAcsClient(profile);

        CreateOpenSingleDataRequest singleRequest = constructSingleRequest();

        CreateOpenSingleDataResponse singleDataResponse;
        try {
            singleDataResponse = client.getAcsResponse(singleRequest);
            System.out.println("singleDataResponse:" +
                    ToStringBuilder
                            .reflectionToString(singleDataResponse, ToStringStyle.SHORT_PREFIX_STYLE));

        } catch (Throwable throwable) {
            throwable.printStackTrace();
        }
    }

    private static CreateOpenSingleDataRequest constructSingleRequest() {

        CreateOpenSingleDataRequest singleRequest
                = new CreateOpenSingleDataRequest();
        //*************必要属性*************/

        //mPaaS 控制台获取的 APPID
        singleRequest.setAppId("xxxxxxx");
        //mPaaS 控制台获取的 WorkspaceId
        singleRequest.setWorkspaceId("xxxxxxxx");
        //mPaaS 控制台移动同步中配置的同步标识
        singleRequest.setBizType("TEST-SYNC");
        //需要推送的用户 ID 或者设备 ID(UTDID)
        singleRequest.setLinkToken("testUserId");
        //实际业务消息体,自定义长度不超过 4096
        singleRequest.setPayload("testPayload");
        //业务 ID,保证唯一,长度不超过 100
        singleRequest.setThirdMsgId("test_third_msg_id_" + System.currentTimeMillis());

        //************非必要属性*************/

        //推送目标设备的操作系统 iOS 或 Android 为空时不限制操作系统
        singleRequest.setOsType("IOS");
        //持的最小客户端版本号,如:8.6.0.0.9999 ,可为空,为空将不限制最小版本号
        singleRequest.setAppMinVersion("0.0.0.0");
        //支持的最大客户端版本号,如:9.0.0.0.9999,可为空,为空将不限制最大版本号
        singleRequest.setAppMaxVersion("100.100.100.100");
        //有效期开始,可为空,为空时不限制有效起始时间
        singleRequest.setValidTimeStart(System.currentTimeMillis());
        //有效期结束,可为空,为空时不限制有效结束时间 最长有效期为 30 天
        singleRequest.setValidTimeEnd(System.currentTimeMillis() + (1000 * 3600));

        return singleRequest;

    }
重要

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

全局(网)数据同步接口

全局(网)数据同步是指将数据同步到所有设备。

参数说明

业务参数信息如下:

名称

类型

是否必须

示例

描述

appId

String

ONEX570DA892117

从 mPaaS 控制台获取的 App ID。

workspaceId

String

PROD

从 mPaaS 控制台获取的 Workspace ID。

bizType

String

UCHAT

在 mPaaS 控制台配置的同步标识,参见 控制台简介

payload

String

testtestatapalayd

实际业务消息体,自定义格式,长度不超过 4096。

thirdMsgId

String

1760339273

一次数据同步请求 ID。同一个同步标识内唯一,ID 重复的请求将会被忽略。须小于 100 字节。

osType

String

IOS/ANDROID/HARMONY

按手机平台进行推送。默认情况下不传递参数,即不过滤,iOS、Android 和 HarmonyOS 平台均会推送。

appMinVersion

String

0.0.0.0

推送数据过滤客户端版本,仅向大于等于该版本号的客户端发送推送。

appMaxVersion

String

100.100.100.100

推送数据过滤客户端版本,仅向小于等于该版本号的客户端发送推送。

validTimeStart

String

1584448493913

当前时间大于等于 validTimeStart 时才会推送。

validTimeEnd

String

1584452093913

当前时间小于等于 validTimeEnd 时才会推送。

maxUid

Long

99

同步范围区间最大 Uid(用户 ID 或设备 ID 倒数第 2、3 位),如果非字母,需转化为 ASCII 码。

minUid

Long

00

同步范围区间最小 Uid(用户 ID 或设备 ID 倒数第 2、3 位),如果非字母,需转化为 ASCII 码。

uids

String

01,02,99

优先级高于 maxUid 及 minUid。离散的用户 ID 段(用户 ID 或设备 ID 倒数第 2、3 位),如果非字母,需转化为 ASCII 码。

全局(网)数据同步结果码

结果码

简述

解决方案

SUCCESS

成功

成功

ARGS_IS_NULL

必要参数为空

检查是否已完整按照非空逻辑传递参数。

PAYLOAD_LONG

PAYLOAD 消息体过长

检查 playload 属性参数长度是否超过限制。

THIRD_MSG_ID_LONG

三方业务 ID 过长

检查三方业务 ID 长度是否超过限制。

BIZ_NOT_ONLINE

业务场景同步标识未提交上线

前往 mPaaS 控制台 > 数据同步 检查 bizType 对应同步标识已配置并提交上线。

THIRD_MSG_ID_IS_NULL

三方业务 ID 为空

检查三方业务 ID 是否为空。

SYSTEM_ERROR

系统异常

联系技术支持确认系统异常原因。

NOT_SUPPORT_GLOBAL

不支持全局业务同步标识调用

根据 BizType,前往 mPaaS 控制台 > 数据同步 检查同步标识是否为指定用户或者指定设备推送类型。

INVALID_TENANT_ID

无效租户 ID

检查 appId 是否正确,是否有权限使用。

代码示例

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.mpaas.model.v20201028.CreateOpenGlobalDataRequest;
import com.aliyuncs.mpaas.model.v20201028.CreateOpenGlobalDataResponse;
import com.aliyuncs.profile.DefaultProfile;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;

public class MsyncPopDemo {

    public static void main(String[] args) {
        //请求信息,除 AccessKey ID  AccessKey Secret 外固定即可
        DefaultProfile.addEndpoint("cn-hangzhou", "mpaas", "mpaas.cn-hangzhou.aliyuncs.com");

        // 阿里云账号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");

        // 创建 DefaultAcsClient 实例并初始化
        DefaultProfile profile = DefaultProfile.getProfile(
                "cn-hangzhou", // 地域 ID
                accessKeyId,   // RAM 账号的 AccessKey ID
                accessKeySecret);  // RAM 账号的 AccessKey Secret
        IAcsClient client = new DefaultAcsClient(profile);

        CreateOpenGlobalDataRequest globalDataRequest = constuctGlobelRequest();

        CreateOpenGlobalDataResponse globalDataResponse;
        try {
            globalDataResponse = client.getAcsResponse(globalDataRequest);
            System.out.println("globalDataResponse:" +
                    ToStringBuilder
                            .reflectionToString(globalDataResponse, ToStringStyle.SHORT_PREFIX_STYLE));

        } catch (Throwable throwable) {
            throwable.printStackTrace();
        }
    }

    private static CreateOpenGlobalDataRequest constuctGlobelRequest() {

        CreateOpenGlobalDataRequest globalRequest
                = new CreateOpenGlobalDataRequest();

        //************必要属性*************/
        //mPaaS 控制台获取的 APPID
        globalRequest.setAppId("BE9C457161429");
        //mPaaS 控制台获取的 WorkspaceId
        globalRequest.setWorkspaceId("sit");
        //mPaaS 控制台移动同步中配置的同步标识
        globalRequest.setBizType("test-global");
        //实际业务消息体,自定义长度不超过 4096
        globalRequest.setPayload("testtestata");
        //业务 ID,保证唯一,长度不超过 100
        globalRequest.setThirdMsgId("test_third_msg_id_" + System.currentTimeMillis());

        //************非必要属性*************/

        //推送目标设备的操作系统 iOS 或 Android 为空时不限制操作系统
        globalRequest.setOsType("IOS");
        //持的最小客户端版本号,如:8.6.0.0.9999 ,可为空 为空将不限制最小版本号
        globalRequest.setAppMinVersion("0.0.0.0");
        //支持的最大客户端版本号,如:9.0.0.0.9999,可为空 为空将不限制最大版本号

        globalRequest.setAppMaxVersion("100.100.100.100");
        //最大 Uid
        globalRequest.setMaxUid(Long.valueOf(99));
        //最小 Uid
        globalRequest.setMinUid(Long.valueOf(1));
        //需要推送的灰度 Uid 00~99,字符串数组
        globalRequest.setUids("01,02,99");

        globalRequest.setValidTimeStart(System.currentTimeMillis());
        globalRequest.setValidTimeEnd(System.currentTimeMillis() + (1000 * 3600));

        return globalRequest;

    }

}
重要

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