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

CoderSharry2023-12-23 4:38

文章目录

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

以下是示例代码：

java 复制代码 
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

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

调用代码示例

java 复制代码 
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

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

调用代码示例

java 复制代码 
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

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

调用代码示例

java 复制代码 
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

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

调用代码示例

java 复制代码 
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：

java 复制代码 
/**
 * 飞书应用权限工具类
 * @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 业务实战

这一小节记录我个人的业务实战代码示例，仅供参考，代码已脱敏。

其中，有了上面章节单条新增的基础，实际业务中我们可以使用批量接口来提高效率。一次调用，多处更新。

java 复制代码 
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工具处理

参考资料

相关推荐
mixboot3 小时前
飞书 富文本（Markdown）
飞书
小华同学ai3 小时前
wflow-web：开源啦 ，高仿钉钉、飞书、企业微信的审批流程设计器，轻松打造属于你的工作流设计器
前端·钉钉·飞书
千年死缓17 小时前
gin中间件
中间件·gin
General_G2 天前
FastDDS服务发现之PDP和EDP的收发
数据库·中间件·服务发现·fast dds·rtps
萤火夜3 天前
Linux之信号量
中间件
idealzouhu4 天前
【Canal 中间件】Canal 实现 MySQL 增量数据的异步缓存更新
mysql·缓存·中间件·canal
乄bluefox4 天前
学习RocketMQ（记录了个人艰难学习RocketMQ的笔记）
java·spring boot·中间件·rocketmq
橘色的喵5 天前
Iceoryx2：高性能进程间通信框架(中间件)
中间件·rust·高性能·iceoryx·iceoryx2
栀夏6135 天前
Ceph 学习指南 集群部署【 cephadm 】
中间件·存储
热门推荐
01【HarmonyOS】HUAWEI DevEco Studio 下载地址汇总02(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明03组基轨迹建模 GBTM的介绍与实现（Stata 或 R）04【AIGC】重塑未来的科技巨轮05全面解析：构建基于深度学习的安全帽检测系统（UI界面+YOLO代码+数据集）06【经验分享】Ubuntu22.04安装微信(linux官方版)07基于YOLOv10深度学习的CT扫描图像肾结石智能检测系统【python源码+Pyqt5界面+数据集+训练代码】深度学习实战、目标检测08Ubuntu 20.04使用Livox mid 360 测试 FAST_LIO09RAG 实践- Ollama+RagFlow 部署本地知识库10红米手机使用google play