開發前準備
使用Java SDK調用服務端API前，請確保通過正規途徑獲取了嘟哩接入商ID（AppId）、金鑰（AppSecret）以及企業編碼（EnterpriseId），安裝了JDK和Java SDK。 本檔案介紹使用Java SDK開發前的準備工作。
獲取接入商ID/金鑰
協力廠商應用主動調用介面時，需帶上AccessToken參數。 AccessToken參數由EnterpriseID，AppID，AppSecret獲取。
具體需要以下步驟：
1.以組織管理員身份登入後臺--開放平臺--接入商管理，並獲取EnterpriseID，AppID及AppSecret等資訊；
2.通過EnterpriseID，AppID及AppSecret獲取AccessToken；
3.通過AccessToken調用相關介面。
獲取AppID & AppSecret
登入管理後臺並登入後臺--開放平臺--接入商管理新增接入商。 創建成功後，可以在清單，找到對應的應用，點擊會彈出下圖的資訊框，AppID及AppSecret。
準備開發環境
- 檢查Java版本
首先，你需要確認本地是否已經安裝了合適的JDK版本。可以通過在終端或命令提示符中執行以下命令來檢查：
java -version如果顯示的版本號是1.8（也表示為8）或更高，則說明已滿足最低要求。如果沒有安裝或者版本較低，則需要下載並安裝最新版本的JDK。 - 下載並安裝JDK
訪問官方網站：前往Oracle JDK或其他開源JDK提供商如AdoptOpenJDK下載適合你操作系統的JDK版本。
選擇合適的版本：根據你的需求選擇最新的穩定版或是特定的版本（例如Java 11 LTS, Java 17 LTS等） - 配置環境變數
安裝完成後，需要配置一些環境變數以便系統能夠識別javac（編譯器）和java（運行時）命令。
Windows：
• 右鍵點擊“此電腦”，選擇“屬性”->“高級系統設置”->“環境變數”。
• 在“系統變數”部分找到Path變數，編輯它，並添加JDK的bin目錄路徑（例如：C:\Program Files\Java\jdk-11.0.11\bin）。
macOS/Linux：
• 編輯/.bashrc、/.zshrc或相應的shell配置文件，添加如下行（假設使用的是zsh並且JDK安裝在/Library/Java/JavaVirtualMachines/jdk-11.0.11.jdk/Contents/Home）：
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.11.jdk/Contents/Home
export PATH=JAVAHOME/bin:PATH• 使用source ~/.zshrc使更改生效。 - 驗證安裝
重新打開一個終端窗口或命令提示符，再次運行java -version和javac -version以驗證安裝是否成功以及正確的版本是否被使用。
安裝 Java SDK
1.下載Jar包
確保你已經從可靠的來源下載了你需要的Java SDK的jar包。
2.安裝Jar包
（到本地Maven倉庫,如果你使用Maven管理項目）：
打開命令行工具（如cmd或PowerShell）。
使用mvn install:install-file
命令將jar包安裝到你的本地Maven倉庫。你需要提供jar包的文件路徑和pom文件（如果可用）的路徑。例如：
mvn install:install-file -Dfile=path/to/your-sdk.jar -DpomFile=path/to/your-sdk.pom.xml如果沒有pom文件，你可能需要手動創建一個，或者省略-DpomFile參數（但這通常不推薦，因為pom文件包含了jar包的依賴信息和版本信息）。
2.添加項目構建路徑
（如果你不使用Maven或需要手動添加jar包）：
將下載的jar包復製到你的Java項目的libs目錄（或任何你選擇的目錄）。
在你的IDE（如Eclipse、IntelliJ IDEA等）中，將jar包添加到項目的構建路徑。具體步驟取決於你使用的IDE，但通常可以通過項目屬性或項目結構設置來完成。
調用服務端API
本檔案介紹如何通過Java SDK，構建API Client用戶端、構造API請求並成功調用服務端介面。 你可以通過查閱嘟哩開放平臺API調用指南，配合本檔案完成調用。
構建API Client用戶端
通過SDK調用嘟哩開放平臺介面前，你需要先在程式碼中創建一個API Client。
示例配寘：
Client client = Client.newBuilder("$enterpriseId","$appId","$appSecret").build();
構造API請求
創建好一個API Client後，即可開始調用嘟哩開放平臺。 SDK使用client. 業務名. 方法名稱來定位具體的API方法。
如下程式碼示例，你可通過client調用用戶業務的getUser方法，獲取用戶資訊。
import com.ddm.openplate.client.Client;
import com.ddm.openplate.service.user.v1.rep.GetUserRep;
import com.ddm.openplate.service.user.v1.req.GetUserReq;
import com.ddm.openplate.util.JacksonTools;
public class App {
public static void main(String[] args) throws Exception {
String enterpriseId = "604300";//企業編號示例
String appId = "1000167027";//接入商Id示例
String appSecret = "YZFG5PLKC95Y0F9F";//接入商密钥示例
// 构建client
Client client = Client.newBuilder(enterpriseId,appId,appSecret).build();
//構建請求體
String type = "id";//査詢類型示例
String query = "10000001";//查詢準則示例
GetUserReq request = GetUserReq.newBuilder()
.type(type)
.query(query)
.build();
//發起請求
GetUserRep response = client.userService().getUser(request);
// 處理服務端錯誤
if (!"1".equals(response.getCode())) {
System.out.println(String.format("code:%s,msg:%s,createTime:%s"
, response.getCode(), response.getMsg(), response.getCreateTime()));
return;
}
// 業務資料處理
System.out.println(JacksonTools.obj2Json(response.getData()));
}
}
你也可以通過自定義構造來請求對應的api介面，如下程式碼示例：
import com.ddm.openplate.client.Client;
import com.ddm.openplate.common.BaseResponse;
import com.ddm.openplate.common.RequestOption;
import com.ddm.openplate.common.constants.ModelConstant;
import com.ddm.openplate.common.constants.RequestType;
import com.ddm.openplate.util.JacksonTools;
import java.util.HashMap;
import java.util.Map;
public class App {
public static void main(String[] args) throws Exception {
String enterpriseId = "604300“；//企業編號示例String appId =”1000167027“；// 接入商Id示例String appSecret =“YZFG5PLKC95Y0F9F”；// 接入商金鑰示例//構建client Client client = Client.newBuilder（enterpriseId，appId，appSecret）.build（）；
String model = ModelConstant.USER;//模塊示例：用戶模塊//構建請求體RequestOption request = new RequestOption（）；
Map requestMap = new HashMap<>();
requestMap.put("type","id");//査詢類型示例requestMap.put（“query”，“1000001”）；// 查詢準則示例request.setRequestType（RequestType.GET）；// 設定請求類型request.setRequestBody（requestMap）；
//發起請求BaseResponse response = client.service（model）.doAction（“/get_user”，request）；// 根據api檔案介面地址//處理服務端錯誤if（！“1”.equals（response.getCode（）））{
System.out.println(String.format("code:%s,msg:%s,createTime:%s" , response.getCode(), response.getMsg(), response.getCreateTime()));
return;
}
// 業務資料處理 System.out.println(JacksonTools.obj2Json(response.getData()));
}
}
執行程式碼
當完成以上程式後，即可執行程式碼調用獲取用戶資訊API。 當請求成功時，預計將返回以下數據； 當請求失敗，則返回錯誤碼以及錯誤資訊，具體參攷嘟哩開放平臺API檔案。
{
"code": "1",
"data": {
"account_id": "10000001",
"account": "example01",
"nick_name": “示例1”，
"phone": "13000000001",
"status": 1,
"is_online": 1,
"mobile_prefix": "86",
"avatar": "/chat/avatar/test-1734074129056.jpeg",
"gender": 1,
"extenal": [
{
"org": “示例組織”,
"org_id": "100000",
"email": "1111@qq.com"，
"dept_list": [
{
"dept_name": “示例部門”,
"dept_id": 1
}
]
}
]
},
"message": "ok",
"createTime": "2025-01-03 11:02:54"
}
示例代碼
修改群組名稱
import com.ddm.openplate.client.Client;
import com.ddm.openplate.service.group.v1.rep.UpdateGroupNameRep;
import com.ddm.openplate.service.group.v1.req.UpdateGroupNameReq;
import com.ddm.openplate.util.JacksonTools;
public class Sample {
public static UpdateGroupNameRep updateGroupName(Client client) throws Exception {
//構建請求體
String groupId = "$group_id";//群組id示例
UpdateGroupNameReq request = UpdateGroupNameReq.newBuilder()
.groupId(groupId)//必填
.build();
//修改群組名稱
UpdateGroupNameRep response = client.groupService().updateGroupName(request);
//服務端錯誤處理
if (!"1".equals(response.getCode())){
System.out.println(String.format("code:%s,msg:%s,createTime:%s"
, response.getCode(), response.getMsg(), response.getCreateTime()));
return response;
}
System.out.println(JacksonTools.obj2Json(response.getData()));
return response;
}
}
創建用戶並修改狀態
import com.ddm.openplate.client.Client;
import com.ddm.openplate.service.user.v1.rep.CreateUserRep;
import com.ddm.openplate.service.user.v1.req.CreateUserReq;
import com.ddm.openplate.util.JacksonTools;
public class Sample {
public static CreateUserRep createUser(Client client) throws Exception {
//构建请求体
String orgId = "100000";//組織id示例
String account = "abcd123456";//組織id示例
String nickName = "测试A";//組織id示例
String phone = "13300000000";//手機號示例
CreateUserReq request = CreateUserReq.newBuilder()
.orgId(orgId) //必填資訊
.account(account)
.nickName(nickName)
.phone(phone)
.build();
//创建用户
CreateUserRep response = client.userService().createUser(request);
//服務端錯誤處理
if (!"1".equals(response.getCode())){
System.out.println(String.format("code:%s,msg:%s,createTime:%s"
, response.getCode(), response.getMsg(), response.getCreateTime()));
return response;
}
System.out.println(JacksonTools.obj2Json(response.getData()));
return response;
}
}
