【工具与中间件】通过飞书应用操作云文档

文章目录

前言
1. 准备工作
- 1.1 创建应用
- 1.2 创建文件夹
2. 测试租户/个人版实践
- 2.1 权限配置
- 2.2 控制台调试
- 2.3 协作文档添加应用
- 2.4 CRUD
- - 2.4.1 根据文档描述选择token并生成
  - 2.4.2 新增多维表格数据API
  - 2.4.3 删除多维表格数据API
  - 2.4.4 查询多维表格数据API
  - 2.4.5 修改多维表格数据API
3. 项目实战
- 3.1 工具类
- 3.2 业务实战
4. 总结
参考资料

飞书应用接入飞书云文档

前言

自从团队接入飞书之后，我们许多应用及数据都要接入或迁移至飞书。不久之前，我就承接并完成了一个监控信息接入飞书机器人实时通知的需求。上次接入的直接体验：飞书文档详略得当，简单易入手。

需求描述

创建飞书应用，配置权限等，通过该应用调用飞书云文档API
调用飞书云文档API，实现业务数据可及时同步到飞书云文档
定时任务执行：将业务本身的数据更新同步到飞书云文档，并将云文档的更改同步到数据库。

学习目标

结合官方文档，参考本次分享的经历，实现业务数据通过飞书应用接入飞书云文档。
学习并练习基于Java的 Http 请求及响应处理方式。
期望本文可作为有类似需求读者实现类似业务的参考，希望可以突出重点。

实操准备
若读者要随着本文进行实操，需要事先准备如下：

个人或企业飞书账号，并确保拥有创建应用等权限
有一个基础项目，语言不限，可以通过这个项目发送 Http 请求。本文是以 Java Spring 项目为例。

下面我们开始！

1. 准备工作

这一小节我们一起做一些准备工作：创建应用、创建目标文档。

1.1 创建应用

为了不影响公司数据，我们先在飞书个人版创建应用，并编写Demo代码测试。但是要注意，截止至发文日期，飞书个人版并不存在管理后台，因此在个人版申请的应用目前用完后无法停用与删除。因此若是有和我一样的强迫症读者，可以自己创建一个企业账户进行实践。为了方便权限管理，以下实践基于我个人创建的测试企业租户。当然个人版的流程我也走了一遍，过程是几乎一样的，供读者参考。

我们的目的是要通过飞书应用来进行飞书云文档的操作。那么第一步就是要创建应用。创建飞书应用一方面可以直接在开发者后台进行API调试，另一方面我们需要拿到这个应用的一些key来在代码层面调用API。

首先，我们进入开发者后台：
飞书开放平台-开发者后台

登录后，我们可以选择创建应用，如图所示：

1.2 创建文件夹

我们的目标是要进行云文件操作，首先要有一个文件夹。我们创建该文件夹并复制链接：

复制链接是为了拿到API所需的文件夹信息。我们可以先在某个地方保存这个路径，待会会用到。

准备工作完成，接下来，我们就可以对飞书API进行实践了！

2. 测试租户/个人版实践

2.1 权限配置

为了避免读者在第一次调试的时候就反复跳转开通权限，由于小编本人已事先读过官方文档，这里建议追求省时间的读者先开通所需权限，再进行API控制台调试。

权限配置是我们做飞书应用接入业务的重要一环。当然也要注意，由于租户隔离，自己的个人应用目前是无法调用企业云文档的。

在接下来的学习与调试中，若飞书API返回结果报权限错误，那么就需要我们重新关注权限，并重复权限配置这一环节了。

2.2 控制台调试

调试第一步，我们可以先在控制台调试。我们打开飞书官方文档并翻出在上一小节复制的文件夹地址，其中包含folder_token，来进行控制台调试:

其中，folder_token 参数在链接最后获取（详情见官方文档）。注意，飞书多维表格相关API很多参数都是在对应的云文档链接获取的。

还有一个注意点：飞书主要提供2种token：user_access_token 与 tenant_access_token . 分别对应以用户还是以租户身份操作，两者权限不同。在控制台调试阶段，我们可以先用简单一些的 user_access_token 调通。如截图所示，我个人演示用的是tenant_access_token，可以在控制台进行切换。

如果调用成功，那么我们应该可以在刚才创建的文件夹里找到这个文件。

2.3 协作文档添加应用

我们需要在写作文档中将应用添加进去，并将应用开启机器人能力，这样，接下来我们就可以使用tenant_access_token进行API调用了！

2.4 CRUD

这一小节我们来调用增删查改 API 来实现飞书云文档的增删查改基础功能吧 !

在开始之前，我们还要重复复制文件等步骤获取所需的key，以及关注 tenant_access_token 的生成。

同时，这一小节我们可以在自己的项目调用这里举例的官方 CRUD API代码示例来进行操作。

2.4.1 根据文档描述选择token并生成

官方提供了https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal接口为我们生成调用 API 必需的token。

以下是示例代码：

public static String getAccessToken(String appId, String appSecret) throws Exception {
		String res = null;
		// 创建一个 URL 对象
		URL url = new URL("https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal");
		// 打开一个 HTTP 连接
		HttpURLConnection connection = (HttpURLConnection) url.openConnection();
		// 设置连接超时时间
		connection.setConnectTimeout(5000);
		// 设置读取超时时间
		connection.setReadTimeout(5000);
		// 设置请求方法为 POST
		connection.setRequestMethod("POST");
		// 设置 doOutput 属性为 true
		connection.setDoOutput(true);
		// 设置通用的请求属性
		connection.setRequestProperty("Content-Type", "application/json;charset=UTF-8");

		// 设置请求体
		JSONObject jsonObject = new JSONObject();
		jsonObject.put("app_id", appId);
		jsonObject.put("app_secret", appSecret);
		connection.getOutputStream().write(jsonObject.toJSONString().getBytes());
		// 发送请求
		connection.connect();
		// 获取响应码
		int responseCode = connection.getResponseCode();

		// 如果响应码为 200，则表示请求成功
		if (responseCode == 200) {
			// 获取响应内容
			BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
			String line;
			StringBuilder response = new StringBuilder();
			while ((line = reader.readLine()) != null) {
				response.append(line);
			}
			reader.close();
			res = response.toString();
		} else {
			// 请求失败
			log.info("请求失败，响应码{}",responseCode);
		}
		// 关闭连接
		connection.disconnect();
		return res;
	}

至于 appId、appSecret，点击我们的应用，在醒目的地方有显示。

2.4.2 新增多维表格数据API

官方文档链接
新增多维表格数据

调用代码示例

package com.lark.oapi.sample.apiall.bitablev1;
import com.lark.oapi.Client;
import com.lark.oapi.core.utils.Jsons;
import com.lark.oapi.service.bitable.v1.model.*;
import java.util.HashMap;
import com.lark.oapi.core.request.RequestOptions;

// SDK 使用文档：https://github.com/larksuite/oapi-sdk-java/tree/v2_main
// 开发者复制该Demo后，需要修改Demo里面的"appID", "appSecret"为自己应用的appId,appSecret.
public class CreateAppTableRecordSample {

	public static void main(String arg[]) throws Exception {
		// 构建client
		Client client = Client.newBuilder("appId", "appSecret")
			.disableTokenCache() //如需SDK自动管理租户Token的获取与刷新,可删除该行
			.build();

		// 创建请求对象
		CreateAppTableRecordReq req = CreateAppTableRecordReq.newBuilder()
			.appToken("")
			.tableId("")
			.userIdType("")
			.clientToken("")
			.appTableRecord(AppTableRecord.newBuilder()
				.fields()
				.build())
			.build();

		// 发起请求
		// 如开启了Sdk的token管理功能，就无需调用 RequestOptions.newBuilder().tenantAccessToken("t-xxx").build()来设置租户token了
		CreateAppTableRecordResp resp = client.bitable().appTableRecord().create(req, RequestOptions.newBuilder()
			.tenantAccessToken("")
			.build());

		// 处理服务端错误
		if(!resp.success()) {
			System.out.println(String.format("code:%s,msg:%s,reqId:%s", resp.getCode(), resp.getMsg(), resp.getRequestId()));
			return;
		}

		// 业务数据处理
		System.out.println(Jsons.DEFAULT.toJson(resp.getData()));
	}
}

2.4.3 删除多维表格数据API

官方文档链接
删除多维表格数据

调用代码示例

package com.lark.oapi.sample.apiall.bitablev1;
import com.lark.oapi.Client;
import com.lark.oapi.core.utils.Jsons;
import com.lark.oapi.service.bitable.v1.model.*;
import java.util.HashMap;
import com.lark.oapi.core.request.RequestOptions;

// SDK 使用文档：https://github.com/larksuite/oapi-sdk-java/tree/v2_main
// 开发者复制该Demo后，需要修改Demo里面的"appID", "appSecret"为自己应用的appId,appSecret.
public class DeleteAppTableRecordSample {

	public static void main(String arg[]) throws Exception {
		// 构建client
		Client client = Client.newBuilder("appId", "appSecret")
			.disableTokenCache() //如需SDK自动管理租户Token的获取与刷新,可删除该行
			.build();

		// 创建请求对象
		// 发起请求
		// 如开启了Sdk的token管理功能，就无需调用 RequestOptions.newBuilder().tenantAccessToken("t-xxx").build()来设置租户token了
		DeleteAppTableRecordResp resp = client.bitable().appTableRecord().delete(RequestOptions.newBuilder()
			.tenantAccessToken("")
			.build());

		// 处理服务端错误
		if(!resp.success()) {
			System.out.println(String.format("code:%s,msg:%s,reqId:%s", resp.getCode(), resp.getMsg(), resp.getRequestId()));
			return;
		}

		// 业务数据处理
		System.out.println(Jsons.DEFAULT.toJson(resp.getData()));
	}
}

2.4.4 查询多维表格数据API

官方文档链接
多维表格数据列表

调用代码示例

package com.lark.oapi.sample.apiall.bitablev1;
import com.lark.oapi.Client;
import com.lark.oapi.core.utils.Jsons;
import com.lark.oapi.service.bitable.v1.model.*;
import java.util.HashMap;
import com.lark.oapi.core.request.RequestOptions;

// SDK 使用文档：https://github.com/larksuite/oapi-sdk-java/tree/v2_main
// 开发者复制该Demo后，需要修改Demo里面的"appID", "appSecret"为自己应用的appId,appSecret.
public class ListAppTableRecordSample {

	public static void main(String arg[]) throws Exception {
		// 构建client
		Client client = Client.newBuilder("appId", "appSecret")
			.disableTokenCache() //如需SDK自动管理租户Token的获取与刷新,可删除该行
			.build();

		// 创建请求对象
		// 发起请求
		// 如开启了Sdk的token管理功能，就无需调用 RequestOptions.newBuilder().tenantAccessToken("t-xxx").build()来设置租户token了
		ListAppTableRecordResp resp = client.bitable().appTableRecord().list(RequestOptions.newBuilder()
			.tenantAccessToken("")
			.build());

		// 处理服务端错误
		if(!resp.success()) {
			System.out.println(String.format("code:%s,msg:%s,reqId:%s", resp.getCode(), resp.getMsg(), resp.getRequestId()));
			return;
		}

		// 业务数据处理
		System.out.println(Jsons.DEFAULT.toJson(resp.getData()));
	}
}

2.4.5 修改多维表格数据API

官方文档链接
更新多维表格数据

调用代码示例

package com.lark.oapi.sample.apiall.bitablev1;
import com.lark.oapi.Client;
import com.lark.oapi.core.utils.Jsons;
import com.lark.oapi.service.bitable.v1.model.*;
import java.util.HashMap;
import com.lark.oapi.core.request.RequestOptions;

// SDK 使用文档：https://github.com/larksuite/oapi-sdk-java/tree/v2_main
// 开发者复制该Demo后，需要修改Demo里面的"appID", "appSecret"为自己应用的appId,appSecret.
public class UpdateAppTableRecordSample {

	public static void main(String arg[]) throws Exception {
		// 构建client
		Client client = Client.newBuilder("appId", "appSecret")
			.disableTokenCache() //如需SDK自动管理租户Token的获取与刷新,可删除该行
			.build();

		// 创建请求对象
		UpdateAppTableRecordReq req = UpdateAppTableRecordReq.newBuilder()
			.appToken("")
			.tableId("")
			.recordId("")
			.userIdType("")
			.appTableRecord(AppTableRecord.newBuilder()
				.fields()
				.build())
			.build();

		// 发起请求
		// 如开启了Sdk的token管理功能，就无需调用 RequestOptions.newBuilder().tenantAccessToken("t-xxx").build()来设置租户token了
		UpdateAppTableRecordResp resp = client.bitable().appTableRecord().update(req, RequestOptions.newBuilder()
			.tenantAccessToken("")
			.build());

		// 处理服务端错误
		if(!resp.success()) {
			System.out.println(String.format("code:%s,msg:%s,reqId:%s", resp.getCode(), resp.getMsg(), resp.getRequestId()));
			return;
		}

		// 业务数据处理
		System.out.println(Jsons.DEFAULT.toJson(resp.getData()));
	}
}

3. 项目实战

3.1 工具类

先封装通用工具类，以及时获取必须的Token：


/**
 * 飞书应用权限工具类
 * @author: Sharry
 * @createTime: 2023-12-21 10:29
 * @version: Version-1.0
 */
public class FeiShuUtils {

	public static String getAccessToken(String appId, String appSecret) throws Exception {
		String res = null;
		// 创建一个 URL 对象
		URL url = new URL("https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal");
		// 打开一个 HTTP 连接
		HttpURLConnection connection = (HttpURLConnection) url.openConnection();
		// 设置连接超时时间
		connection.setConnectTimeout(5000);
		// 设置读取超时时间
		connection.setReadTimeout(5000);
		// 设置请求方法为 POST
		connection.setRequestMethod("POST");
		// 设置 doOutput 属性为 true
		connection.setDoOutput(true);
		// 设置通用的请求属性
		connection.setRequestProperty("Content-Type", "application/json;charset=UTF-8");
		// 设置请求体
		JSONObject jsonObject = new JSONObject();
		jsonObject.put("app_id", appId);
		jsonObject.put("app_secret", appSecret);
		connection.getOutputStream().write(jsonObject.toJSONString().getBytes());
		// 发送请求
		connection.connect();
		// 获取响应码
		int responseCode = connection.getResponseCode();
		// 如果响应码为 200，则表示请求成功
		if (responseCode == 200) {
			// 获取响应内容
			BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
			String line;
			StringBuilder response = new StringBuilder();
			while ((line = reader.readLine()) != null) {
				response.append(line);
			}
			reader.close();
			// 打印响应内容
			res = response.toString();
		} else {
		}
		// 关闭连接
		connection.disconnect();
		return res;
	}

    /**
    * 获取租户 tenant_access_token
    */
	public static String getAppAccessToken(String appId, String appSecret) throws Exception {
		JSONObject jsonObject = JSONObject.parseObject(getAccessToken(appId, appSecret));
		return jsonObject.getString("tenant_access_token");
	}

}

3.2 业务实战

这一小节记录我个人的业务实战代码示例，仅供参考，代码已脱敏。
其中，有了上面章节单条新增的基础，实际业务中我们可以使用批量接口来提高效率。一次调用，多处更新。

import com.larksuite.oapi.service.bitable.v2.BitableService;
import com.larksuite.oapi.service.bitable.v2.model.BatchUpdateAppTableRecordReq;
import com.larksuite.oapi.service.bitable.v2.model.BatchUpdateAppTableRecordResp;
import com.larksuite.oapi.service.bitable.v2.model.AppTableRecord;
import com.larksuite.oapi.service.bitable.v2.model.RequestOptions;

import java.util.HashMap;
import java.util.Map;

public class BatchUpdateAppTableRecord {

    public static void batchUpdateAppTableRecord(String appId, String appSecret) 
        throws Exception {
        // Create a client
        Client client = Client.newBuilder("appId", "appSecret")
            .disableTokenCache() 
            .build();

        // Create a request
        BatchUpdateAppTableRecordReq req = BatchUpdateAppTableRecordReq.newBuilder()
            .batchUpdateAppTableRecordReqBody(BatchUpdateAppTableRecordReqBody.newBuilder()
                .records(new AppTableRecord[] {
                    AppTableRecord.newBuilder()
                        .fields(new HashMap < String, Object > () {})
                        .recordId("reclAqylTN")
                        .build()
                })
                .build())
            .build();

        // Schedule the task
        BatchUpdateAppTableRecordResp resp = client.bitable().appTableRecord().batchUpdate(req, RequestOptions.newBuilder()
            .tenantAccessToken("")
            .build());

        // Handle the response
        if (!resp.success()) {
            System.out.println(String.format("code:%s,msg:%s,reqId:%s", resp.getCode(), resp.getMsg(), resp.getRequestId()));
            return;
        }

        // Do something with the response data
        log.info("{}",Jsons.DEFAULT.toJson(resp.getData()));
    }
}

4. 总结

总结
本文通过我个人实际工作的需求，记录了通过飞书官方文档，创建企业应用并将业务接入到飞书云文档并使用的过程。通过本文的记录，我们一起学习了：

飞书应用的创建及相关配置
通过应用调用飞书API，实现数据及时更新到飞书云文档
调用API的本质是HTTP请求，我们又复习了一遍日常生活中如何发起HTTP请求并根据文档接收数据

注意点
有几个值得注意的点

1. Token 的选用，一是要参考官方文档的建议，二是可以根据 “appId”、“appSecret” 调用官方 token_access_token 接口，结合权限情况及实际具体需求使用
1. 权限：权限很重要，一定要仔细阅读官方文档的同时，和团队、领导等及时沟通，及时申请权限。否则，就算本地调试再6，生产环境没有权限也是不行的
1. 文档 token：文档的 token 在文档链接中，许多 API 都会直接用到，非常重要。需要在浏览器打开等方式在 url 等获取相关token
1. 多维表格新增的字段一定要严格和该表格字段对应，否则新增的一行在文档无法正常显示，只能在后台通过删除API删除。推荐用Json工具处理