模板

应用创建

自建应用

添加机器人

开放接入

开发前准备

使用Java SDK 调用服务端 API前，请确保通过正规途径获取了嘟哩接入商ID（AppId）、密钥（AppSecret）以及企业编码（EnterpriseId），安装了JDK和Java SDK。本文档介绍使用 Java SDK 开发前的准备工作。

获取接入商ID/密钥

第三方应用主动调用接口时，需带上AccessToken 参数。AccessToken 参数由 EnterpriseID，AppID，AppSecret 获取。

具体需要以下步骤：

以组织管理员身份登录后台--开放平台--接入商管理，并获取 EnterpriseID，AppID 及AppSecret 等信息；
通过 EnterpriseID，AppID 及AppSecret 获取 AccessToken；
通过 AccessToken 调用相关接口。

获取 AppID & AppSecret

登录管理后台并登录后台--开放平台--接入商管理新增接入商。创建成功后，可以在列表，找到对应的应用，点击会弹出下图的信息框，AppID 及 AppSecret 。

准备开发环境

1. 检查Java版本

首先，你需要确认本地是否已经安装了合适的JDK版本。可以通过在终端或命令提示符中执行以下命令来检查：

java -version

如果显示的版本号是1.8（也表示为8）或更高，则说明已满足最低要求。如果没有安装或者版本较低，则需要下载并安装最新版本的JDK。

2. 下载并安装JDK

访问官方网站：前往Oracle JDK或其他开源JDK提供商如AdoptOpenJDK下载适合你操作系统的JDK版本。

选择合适的版本：根据你的需求选择最新的稳定版或是特定的版本（例如Java 11 LTS, Java 17 LTS等）

3. 配置环境变量

安装完成后，需要配置一些环境变量以便系统能够识别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=$JAVA_HOME/bin:$PATH

使用source ~/.zshrc使更改生效。

4. 验证安装

重新打开一个终端窗口或命令提示符，再次运行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;
    }

}