本文介紹如何以 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 系統配置方法
新建環境變量,添加環境變量 MPAAS_AK_ENV 和 MPAAS_SK_ENV,并寫入已準備好的 AccessKey ID 和 AccessKey Secret。
重啟 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 賬號進行應用級別的訪問控制。