SpringBoot 对接飞书多维表格事件回调监听流程分析_Java

一、前言

在上一篇【微服务】java 对接飞书多维表格使用详解，分享了基于飞书开放平台对接多维表的过程，紧接着上一篇，本文将分享如何通过飞书提供的事件订阅机制，并集成到springboot项目中对多维表数据的记录变更进行对接的详细流程。

二、前置准备

2.1 创建一个应用

参考上一篇创建应用的详细过程，后面在程序代码中调用api的前提都是基于创建的应用产生的信息。

2.2 准备一张测试使用的多维表

创建一张测试使用的多维表，将这个多维表的权限授权给上一步添加的应用，并提前为多维表添加几条数据

2.3 获取对接文档

通过飞书的开放平台找到事件与订阅部分的对接文档，文档链接：https://open.feishu.cn/document/server-docs/event-subscription-guide/overview

2.4 工程中添加sdk

如果在上一篇对接中添加了，可以忽略，以java为例，在pom文件中添加如下依赖

<dependency>
    <groupid>com.larksuite.oapi</groupid>
    <artifactid>oapi-sdk</artifactid>
    <version>2.3.6</version>
</dependency>

三、对接过程

接下来按照平台文档提供的操作步骤进行对接

3.1 配置encrypt key 和 verification token

这两个参数，官方文档说明是可选项，即可以不配，不配的话平台会默认生成两个参数，但如果你对数据传输安全性要求比较高的话，建议做一下配置（参数的位置，我的应用 —> 事件与回调 —> 加密策略）

3.2 配置订阅方式

这一步，表示后续在应用程序中通过哪种方式接收飞书平台的事件消息，平台提供了2种方式：

将事件发送至开发者服务器
- 这种方式需要开发者按照平台的要求，开发一个webhook接口，部署到ipv4类型服务器上，并在平台的控制台进行配置；
使用长连接接收事件
- 该方式是飞书 sdk 内提供的能力，你可以通过集成飞书 sdk 与开放平台建立一条 websocket 全双工通道（你的服务器需要能够访问公网）。后续当应用订阅的事件发生时，开放平台会通过该通道向你的服务器发送消息。
- 这也是官方推荐的一种配置方式；

点击进入到我的应用控制台，在订阅方式这里选择 ”长连接” 的方式

3.3 添加事件

这一步表示你需要对接哪些事件，是订阅多维表记录变更的事件？部门员工移除事件？还是一个审批通过的事件呢？即需要为当前应用关联需要处理的事件，这样飞书平台才能在后续将此类变更事件推送到应用程序。

添加事件入口如下，进入到我的应用之后，在事件与回调中，在上一步的基础上，点击右侧的添加事件，选择你要对接的事件进行添加，比如我这里选择的是多维表记录变更的事件。

3.4 申请权限

做完上面添加的监听事件之后，需要重新发布一下应用才能生效

选择版本管理，新增一个版本并点击发布，等待管理员审批通过即可

3.5 编写订阅代码

接下来，需要在代中编写监听程序，从而监听订阅的事件的数据变更，通过平台提供的示例代码直接拿来使用，简单修改下参数，然后运行起来即可，平台提供的参考代码链接：https://open.feishu.cn/document/server-docs/event-subscription-guide/event-subscription-configure-/request-url-configuration-case

完整的参考代码如下，代码中几个核心参数文档上面有描述，这里再单独说明一下：

appid
- 上一篇中创建应用后产生的那个 appid ；
appsecret
- 上一篇中创建应用后产生的那个 appsecret ；
encrypt key
- 事件与回调控制台上面那个参数，为空就不填；
verification token
- 事件与回调控制台上面那个参数，为空就不填；

package com.congge.web;
import com.lark.oapi.core.request.eventreq;
import com.lark.oapi.core.utils.jsons;
import com.lark.oapi.event.customeventhandler;
import com.lark.oapi.event.eventdispatcher;
import com.lark.oapi.service.im.imservice;
import com.lark.oapi.service.im.v1.model.p2messagereceivev1;
import com.lark.oapi.ws.client;
import java.nio.charset.standardcharsets;
public class sample {
    // onp2messagereceivev1 为接收消息 v2.0；oncustomizedevent 内的 message 为接收消息 v1.0。
    private static final eventdispatcher event_handler = eventdispatcher.newbuilder("7zcxxffbxscjua2j0mpfctyilkfjxagg", "")
            .onp2messagereceivev1(new imservice.p2messagereceivev1handler() {
                @override
                public void handle(p2messagereceivev1 event) throws exception {
                    system.out.printf("[ onp2messagereceivev1 access ], data: %s\n", jsons.default.tojson(event.getevent()));
                }
            })
            .oncustomizedevent("drive.file.bitable_record_changed_v1", new customeventhandler() {
                @override
                public void handle(eventreq event) throws exception {
                    system.out.printf("[ oncustomizedevent access ], type: message, data: %s\n", new string(event.getbody(), standardcharsets.utf_8));
                }
            })
            .build();
    public static void main(string[] args) {
        string appid = "你的appid ";
        string appsecret = "你的appsecret ";
        client cli = new client.builder(appid, appsecret)
                .eventhandler(event_handler)
                .build();
        cli.start();
    }
}

代码运行起来之后，通过控制台输出日志可以看到已经与平台建立了通信

3.6 订阅文档事件

为了能让你的代码与平台给你正常推送事件消息匹配，还需手动在这里调用一下订阅文档事件的接口，官方客服解释说，只有调用一次，平台才知道后续是针对哪个事件的文档？哪个事件的多维表给你推送事件消息。

api控制台操作文档链接：

https://open.feishu.cn/document/server-docs/docs/drive-v1/event/subscribe?appid=cli_a79f0662f9bd500c

以本次测试使用的多维表为例进行说明，此处控制台中在调试时的几个参数至关重要，这里单独说明：

authorization
- 这里的token使用用户的token，不要使用tenant的那个token；
file_type
- 这里取值为 bitable；
file_token
- 即多维表格类型的那个token，在上一步中有提到；
- 即这里的file_token取值为下图中的obj_token值，这个切记；

3.7 效果测试

上述都做完之后，然后回到多维表，删除下面这条数据

很快，在控制台上就能看到这个事件被捕获到了，相关的参数日志信息也输出出来了，后续程序中就可以基于这个输出的事件参数，做进一步的参数解析，从而进行后续的数据和逻辑处理了

四、在springboot工程中集成

细心的伙伴不难发现，官方提供的示例程序是一个main入口的演示代码，在真实的工程中集成时，这种方式肯定是不行的，下面来看怎么在springbooot工程中进行集成使用。

4.1 导入基础以依赖

依赖包含了飞书的sdk以及springboot运行所需的基础依赖

<dependency>
    <groupid>com.alibaba</groupid>
    <artifactid>fastjson</artifactid>
    <version>2.0.35</version>
</dependency>
<dependency>
    <groupid>com.squareup.okhttp3</groupid>
    <artifactid>okhttp</artifactid>
    <version>4.12.0</version>
</dependency>
<dependency>
    <groupid>com.larksuite.oapi</groupid>
    <artifactid>oapi-sdk</artifactid>
    <version>2.3.6</version>
</dependency>
<dependency>
    <groupid>org.springframework.boot</groupid>
    <artifactid>spring-boot-starter-web</artifactid>
</dependency>
<dependency>
    <groupid>org.projectlombok</groupid>
    <artifactid>lombok</artifactid>
    <scope>provided</scope>
</dependency>

4.2 自定义一个配置类

该类模拟示例代码中的main程序，相当于是通过这个自定义的类启动一个异步任务，完整代码如下：

package com.congge.config;
import com.lark.oapi.core.request.eventreq;
import com.lark.oapi.core.utils.jsons;
import com.lark.oapi.event.customeventhandler;
import com.lark.oapi.event.eventdispatcher;
import com.lark.oapi.service.im.imservice;
import com.lark.oapi.service.im.v1.model.p2messagereceivev1;
import com.lark.oapi.ws.client;
import jakarta.annotation.postconstruct;
import org.springframework.stereotype.component;
import java.nio.charset.standardcharsets;
@component
public class samplelistenertask {
    @postconstruct
    public void start(){
        string appid = "你的appid ";
        string appsecret = "你的appsecret ";
        client cli = new client.builder(appid, appsecret)
                .eventhandler(event_handler)
                .build();
        cli.start();
        system.out.println("监听飞书多维表程序启动...");
    }
    // onp2messagereceivev1 为接收消息 v2.0；oncustomizedevent 内的 message 为接收消息 v1.0。
    private static final eventdispatcher event_handler = eventdispatcher.newbuilder("7zcxxffbxscjua2j0mpfctyilkfjxagg", "")
            .onp2messagereceivev1(new imservice.p2messagereceivev1handler() {
                @override
                public void handle(p2messagereceivev1 event) throws exception {
                    system.out.printf("[ onp2messagereceivev1 access ], data: %s\n", jsons.default.tojson(event.getevent()));
                }
            })
            .oncustomizedevent("drive.file.bitable_record_changed_v1", new customeventhandler() {
                @override
                public void handle(eventreq event) throws exception {
                    system.out.printf("[ oncustomizedevent access ], type: message, data: %s\n", new string(event.getbody(), standardcharsets.utf_8));
                }
            })
            .build();
}