Java 對(duì)接飛書(shū)多維表格使用詳解(微服務(wù))
一、前言
飛書(shū)通過(guò)多維表格提供了強(qiáng)大的數(shù)據(jù)支撐能力,借助飛書(shū)開(kāi)放平臺(tái),應(yīng)用程序可以通過(guò)飛書(shū)平臺(tái)提供的開(kāi)放API能力操作多維表格,以滿足業(yè)務(wù)靈活的數(shù)據(jù)處理需要。本文將詳細(xì)介紹如何基于飛書(shū)開(kāi)放平臺(tái),在微服務(wù)項(xiàng)目中打通對(duì)飛書(shū)多維表的數(shù)據(jù)操作流程。
二、前置操作
2.1 開(kāi)通企業(yè)飛書(shū)賬戶
默認(rèn)情況下,你在公司的組織機(jī)構(gòu)下,直接使用你的賬號(hào)激活并登錄的賬戶即可
2.2 確保賬戶具備多維表操作權(quán)限
由于后文會(huì)對(duì)一些多維表做數(shù)據(jù)測(cè)試,因此再正式開(kāi)始之前,選擇你需要操作的多維表,并提前開(kāi)通操作權(quán)限
2.3 創(chuàng)建一張測(cè)試用的多維表
在飛書(shū)的知識(shí)庫(kù)中創(chuàng)建一個(gè)測(cè)試用的多維數(shù)據(jù)表,如下,并提前初始化幾條數(shù)據(jù)
2.4 獲取飛書(shū)開(kāi)放平臺(tái)文檔
百度搜索:飛書(shū)開(kāi)放平臺(tái),地址:https://open.feishu.cn/ ,通過(guò) ” 開(kāi)發(fā)文檔 ”進(jìn)入
2.5 獲取Java SDK
在后文中,需要通過(guò)程序代碼操作多維表,因此需要在代碼中導(dǎo)入飛書(shū)開(kāi)放平臺(tái)提供的SDK,官方給出了2種使用方式,通過(guò)SDK提供的API調(diào)用,或者通過(guò)傳統(tǒng)的HTTP方式調(diào)用,以Java語(yǔ)言為例進(jìn)行說(shuō)明,git對(duì)應(yīng)的SDK獲取地址:SDK鏈接
三、應(yīng)用App相關(guān)操作
應(yīng)用程序?qū)︼w書(shū)提供的各類(lèi)能力的操作,均以應(yīng)用的維度為前提,所以在對(duì)接飛書(shū)API之前,需要結(jié)合實(shí)際業(yè)務(wù)需求進(jìn)行應(yīng)用的創(chuàng)建。
3.1 創(chuàng)建應(yīng)用過(guò)程
操作入口:應(yīng)用入口
如下,點(diǎn)擊創(chuàng)建應(yīng)用
跳轉(zhuǎn)鏈接來(lái)到下面的頁(yè)面
按要求填寫(xiě)應(yīng)用的信息,然后點(diǎn)擊創(chuàng)建,創(chuàng)建成功后就可以在列表上看到剛剛創(chuàng)建的這個(gè)應(yīng)用了
3.2 應(yīng)用發(fā)布過(guò)程
應(yīng)用必須要通過(guò)發(fā)布之后,應(yīng)用具備的操作各類(lèi)飛書(shū)文檔、多維表格的能力才能生效
點(diǎn)擊應(yīng)用圖標(biāo),跳轉(zhuǎn)到下面的應(yīng)用操作控制臺(tái),在這個(gè)頁(yè)面,圖中兩個(gè)參數(shù)請(qǐng)妥善保管,后面在程序代碼中會(huì)多處使用。
點(diǎn)擊 ”版本管理與發(fā)布”
點(diǎn)擊創(chuàng)建版本,參照下面的格式要求填寫(xiě),提交之后需要等待飛書(shū)管理員審核通過(guò)。
3.3 應(yīng)用添加操作權(quán)限
這里的操作權(quán)限,可以理解為,對(duì)上述添加的這個(gè)應(yīng)用能夠做哪些事情,是操作多維表數(shù)據(jù)?修改/刪除文檔?還是獲取組織機(jī)構(gòu)的人員?定一個(gè)具體的操作范圍。有點(diǎn)像你在阿里云控制臺(tái),或者一些SAAS的操作平臺(tái)上面,根據(jù)自身的需求選擇一些平臺(tái)提供的各類(lèi)操作能力。如下,在當(dāng)前的應(yīng)用頁(yè)面,點(diǎn)擊左側(cè) ” 權(quán)限管理”
在右側(cè)可以看到,平臺(tái)主要提供了API權(quán)限和數(shù)據(jù)權(quán)限兩種類(lèi)型,不同類(lèi)型的權(quán)限下面細(xì)分了很多種小場(chǎng)景下的權(quán)限能力,可以根據(jù)自身的需求,為你當(dāng)前創(chuàng)建的應(yīng)用勾選對(duì)應(yīng)的權(quán)限,比如后文需要操作多維表,所以我這里勾選了與多維表相關(guān)的權(quán)限。
四、多維表應(yīng)用授權(quán)操作
在正式通過(guò)應(yīng)用程序SDK操作飛書(shū)多維表之前,還需要在多維表為上述創(chuàng)建的這個(gè)應(yīng)用授權(quán),表示授權(quán)這個(gè)應(yīng)用對(duì)這個(gè)多維表的操作權(quán)限,如下,找到多維表對(duì)接的流程:多維表對(duì)接流程
找到上文中創(chuàng)建的那個(gè)測(cè)試用的多維表,然后通過(guò)多維表上面的 ... 找到添加文檔應(yīng)用
在彈出的搜索框中搜索前面創(chuàng)建并審核通過(guò)的那個(gè)應(yīng)用名稱并添加即可(應(yīng)用必須通過(guò)審核,否則這里無(wú)法搜索到),這一步操作成功后,就表示應(yīng)用具備了操作當(dāng)前這個(gè)多維表的能力了。
五、使用控制臺(tái)API調(diào)試操作多維表
飛書(shū)提供了控制臺(tái)在線調(diào)試各類(lèi)API的能力,通過(guò)在線調(diào)試,不僅可以快速的看到結(jié)果,也可以基于調(diào)試的參數(shù)生成應(yīng)用程序中可以真實(shí)使用的程序代碼,同時(shí)也可以在調(diào)試階段進(jìn)一步理解API需要的參數(shù),以及參數(shù)的獲取方式,從而對(duì)API的使用有更深一層的理解,下面以操作多維表格為例進(jìn)行說(shuō)明。
5.1 控制臺(tái)調(diào)試多維表操作過(guò)程
5.1.1 獲取token
token是調(diào)用所有飛書(shū)API接口必須要用到的參數(shù),可以通過(guò)鏈接點(diǎn)擊查看:獲取token
點(diǎn)擊之后跳轉(zhuǎn)到下面的頁(yè)面
點(diǎn)擊開(kāi)始調(diào)試按鈕,請(qǐng)求成功后,就能看到本次請(qǐng)求的tenant_access_token結(jié)果,如果需要user_access_token的話,點(diǎn)擊下面的獲取按鈕即可,需要注意的是,token的最大有效期是2小時(shí);
5.1.2 獲取多維表數(shù)據(jù)
API地址 多維表API
每一個(gè)具體的API在調(diào)用之前,建議仔細(xì)閱讀一下API文檔的描述,比如調(diào)用這個(gè)API需要的詳細(xì)參數(shù),各個(gè)參數(shù)代表的含義,以及各個(gè)參數(shù)怎么獲取等,都有詳細(xì)的說(shuō)明。
在這個(gè)查詢記錄的API中,需要傳遞3個(gè)參數(shù):
- Authorization ,
- 請(qǐng)求頭參數(shù),這里需要填token參數(shù),而token又分2種:
- tenant_access_token , 租戶級(jí)token也可以理解為應(yīng)用級(jí)token,權(quán)限和范圍最高;
- user_access_token , 用戶token,API權(quán)限限定為當(dāng)前操作的用戶;
- 請(qǐng)求頭參數(shù),這里需要填token參數(shù),而token又分2種:
- app_token
- 多維表格 App 的唯一標(biāo)識(shí),不同形態(tài)的多維表格,其 app_token 的獲取方式不同
按照上面參數(shù)的詳細(xì)解釋,以及獲取參數(shù)的方法,我們?cè)谟覀?cè)的API調(diào)試控制臺(tái)輸入對(duì)應(yīng)的參數(shù),點(diǎn)擊開(kāi)始調(diào)試,可以看到成功獲取到多維表的數(shù)據(jù)。
如果調(diào)用過(guò)程中出現(xiàn)任何錯(cuò)誤,在返回的響應(yīng)中會(huì)輸出相關(guān)的信息
5.1.3 新增記錄
基于多維表增加數(shù)據(jù),增加記錄所需參數(shù)相對(duì)比較復(fù)雜一些,可以參考請(qǐng)求示例,結(jié)合請(qǐng)求參數(shù)的描述進(jìn)行理解。
在右側(cè)調(diào)試控制臺(tái),在請(qǐng)求體中按要求填寫(xiě)如下參數(shù)
點(diǎn)擊調(diào)試,請(qǐng)求成功之后,可以看到下面的返回結(jié)果
調(diào)用成功之后,再在上面創(chuàng)建的測(cè)試多維表中可以看到增加了一條數(shù)據(jù)
5.1.4 刪除記錄
刪除多維數(shù)據(jù)表中的一行記錄
調(diào)用刪除接口,除了必須的那幾個(gè)公共參數(shù)之外,最核心的參數(shù)為 record_id ,可以理解為一張表的ID,以上一步新增接口返回的那條數(shù)據(jù) record_id為例進(jìn)行調(diào)用測(cè)試。
刪除接口請(qǐng)求成功后,再看原始的多維表,可以看到上面這條數(shù)據(jù)被刪掉了
上面演示了在線調(diào)試多維表常用的幾種API操作步驟,更多的功能也可以參照這種方式進(jìn)行操作即可
六、Java SDK操作多維表操作過(guò)程
接下來(lái)演示如何在代碼中集成飛書(shū)SDK操作多維表相關(guān)功能
6.1 導(dǎo)入相關(guān)依賴
在pom文件中導(dǎo)入http依賴,以及飛書(shū)SDK組件
<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>
6.2 操作多維表增刪改查相關(guān)功能
6.2.1 代碼集成小技巧
在上一小節(jié)通過(guò)控制臺(tái)調(diào)試API的時(shí)候,細(xì)心的伙伴可能會(huì)注意到在調(diào)試臺(tái)下面都有一個(gè)示例代碼的入口,類(lèi)似下面這樣,為了減少代碼編寫(xiě)成本,可以充分利用這里提供的示例代碼(前提:在代碼工程中導(dǎo)入SDK)
6.2.2 獲取token
token是后面調(diào)用其他接口都需要的參數(shù),因此首先需要通過(guò)程序獲得token,完整代碼如下:
import com.alibaba.fastjson.JSONObject; import org.springframework.http.HttpEntity; import org.springframework.http.HttpHeaders; import org.springframework.http.MediaType; import org.springframework.web.client.RestTemplate; import java.util.HashMap; import java.util.Map; /** * 獲取自建應(yīng)用的 tenant_access_token */ public class TenantAuthTokenTest { public static void main(String[] args) { String appId = "替換為你自己應(yīng)用的appId"; String appSecret = "替換為你自己應(yīng)用的appSecret"; RestTemplate restTemplate = new RestTemplate(); String url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"; HttpHeaders headers = new HttpHeaders(); MediaType type = MediaType.parseMediaType("application/json; charset=UTF-8"); headers.setContentType(type); headers.add("Accept", MediaType.APPLICATION_JSON.toString()); Map<String,Object> paramMap = new HashMap<>(); paramMap.put("app_id",appId); paramMap.put("app_secret",appSecret); String requestJson = JSONObject.toJSONString(paramMap); HttpEntity<String> entity = new HttpEntity<String>(requestJson,headers); String result = restTemplate.postForObject(url, entity, String.class); System.out.println(result); } }
運(yùn)行上面的代碼,從打印的結(jié)果中解析tenant_access_token即可(注意保存這個(gè)token,后面其他接口調(diào)用時(shí)會(huì)用到)
6.2.3 查詢多維表記錄
拷貝控制臺(tái)上面的示例代碼,然后調(diào)整示例代碼中的參數(shù)
package com.congge.feishu; import com.lark.oapi.Client; import com.lark.oapi.core.utils.Jsons; import com.lark.oapi.service.bitable.v1.model.*; import java.util.List; import java.util.Map; /** * TODO 第三步 : 獲取多維表的數(shù)據(jù),原始的URL: * https://kxv0z438jth.feishu.cn/wiki/Sv8SwfjImiWFusk2MBEczz0AnNg?table=tblDPPkqY93he1AO&view=vewq1cS7NC */ public class TableDataGetTest { public static void main(String[] args) throws Exception{ String appId = "你的appId "; String appSecret = "你的appSecret"; // 構(gòu)建client Client client = Client.newBuilder(appId, appSecret).build(); // 創(chuàng)建請(qǐng)求對(duì)象 SearchAppTableRecordReq req = SearchAppTableRecordReq.newBuilder() .appToken("JvJpbhm31a1s5xsqvOKcUTEMnrb") .tableId("tblDPPkqY93he1AO") .searchAppTableRecordReqBody(SearchAppTableRecordReqBody.newBuilder() .viewId("vewq1cS7NC") .fieldNames(new String[] { "名稱", "單號(hào)" }) .build()) .build(); // 發(fā)起請(qǐng)求 SearchAppTableRecordResp resp = client.bitable().appTableRecord().search(req); // 處理服務(wù)端錯(cuò)誤 if(!resp.success()) { System.out.println(String.format("code:%s,msg:%s,reqId:%s, resp:%s", resp.getCode(), resp.getMsg(), resp.getRequestId(), Jsons.DEFAULT.toJson(resp.getRawResponse()))); return; } // 業(yè)務(wù)數(shù)據(jù)處理 System.out.println(Jsons.DEFAULT.toJson(resp.getData())); SearchAppTableRecordRespBody data = resp.getData(); AppTableRecord[] items = data.getItems(); for (AppTableRecord item : items) { Map<String, Object> fields = item.getFields(); fields.forEach((key,val)->{ System.out.println("key:" + key); List<Map<String,Object>> fieldList = (List<Map<String,Object>>)val; System.out.println("fieldList:" + fieldList); }); } } }
這里需要重點(diǎn)說(shuō)明一下 appToken 和 tableId 這兩個(gè)參數(shù):
- appToken:
- 這里操作的多維表的URL鏈接中含有wiki,需要通過(guò)調(diào)用另一個(gè) “獲取知識(shí)空間節(jié)點(diǎn)信息“的接口返回的參數(shù)中獲取;
- 點(diǎn)擊“獲取知識(shí)空間節(jié)點(diǎn)信息“超鏈接,跳轉(zhuǎn)到另一個(gè)調(diào)試控制臺(tái)進(jìn)行獲??;
- 按照參數(shù)說(shuō)明,這里需要獲取接口返回值中的 obj_token 作為本次獲取記錄接口中的app_token參數(shù)使用;
將這個(gè)obj_token 值代入到代碼的參數(shù)中調(diào)用一下,記錄能夠全部查詢出來(lái)
6.2.4 獲取知識(shí)空間節(jié)點(diǎn)信息
在上一步的接口調(diào)用中,需要傳入一個(gè)app_token的參數(shù),這個(gè)參數(shù)需要調(diào)用另一個(gè)接口中獲取到,即:獲取知識(shí)空間節(jié)點(diǎn)信息,參數(shù)中的token值來(lái)源:
完整代碼如下(可拷貝官方提供的示例代碼做簡(jiǎn)單參數(shù)調(diào)整)
package com.congge.feishu; import com.fasterxml.jackson.databind.ObjectMapper; import com.lark.oapi.Client; import com.lark.oapi.service.wiki.v2.model.GetNodeSpaceReq; import com.lark.oapi.service.wiki.v2.model.GetNodeSpaceResp; import com.lark.oapi.service.wiki.v2.model.GetNodeSpaceRespBody; import com.lark.oapi.service.wiki.v2.model.Node; import java.util.Objects; /** * TODO : 第二步 ,獲取文檔節(jié)點(diǎn)的信息,真正在讀取文檔的數(shù)據(jù)記錄的時(shí)候需要拿到節(jié)點(diǎn)的信息 */ public class SpaceTokenGetTest { public static void main(String[] args) throws Exception{ String appId = "你的appId "; String appSecret = "你的appSecret"; // 構(gòu)建client Client client = Client.newBuilder(appId, appSecret).build(); // 創(chuàng)建請(qǐng)求對(duì)象 GetNodeSpaceReq req = GetNodeSpaceReq.newBuilder() .token("Sv8SwfjImiWFusk2MBEczz0AnNg") .objType("wiki") .build(); // 發(fā)起請(qǐng)求 GetNodeSpaceResp resp = client.wiki().space().getNode(req); GetNodeSpaceRespBody data = resp.getData(); if(!resp.success()){ System.out.println("請(qǐng)求獲取文檔節(jié)點(diǎn)接口失敗"); } Node node = data.getNode(); if(Objects.isNull(data) || Objects.isNull(node)){ System.out.println("請(qǐng)求的數(shù)據(jù)為空"); } String spaceId = node.getSpaceId(); String nodeToken = node.getNodeToken(); String objType = node.getObjType(); String objToken = node.getObjToken(); String title = node.getTitle(); if("bitable".equals(objType)){ System.out.println("當(dāng)前操作的是多維表格,表格名稱:" + title); System.out.println("當(dāng)前操作的是多維表格,對(duì)應(yīng)的節(jié)點(diǎn)token:" + nodeToken); System.out.println("當(dāng)前操作的是多維表格,作為獲取多維表格的查詢 app_token:" + objToken); } } }
運(yùn)行一下程序,可以看到成功獲取到響應(yīng)結(jié)果
6.2.5 新增記錄
完整代碼如下,注意:
appToken,即上一步獲取知識(shí)庫(kù)空間節(jié)點(diǎn)信息返回的 app_token;
package com.congge.feishu; 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; /** * TODO 第四步 : 新增數(shù)據(jù)到多維表,原始的URL: * https://kxv0z438jth.feishu.cn/wiki/Sv8SwfjImiWFusk2MBEczz0AnNg?table=tblDPPkqY93he1AO&view=vewq1cS7NC */ public class TableDataInsertTest { public static void main(String[] args) throws Exception { String appId = "你的appId"; String appSecret = "你的appSecret "; // 構(gòu)建client Client client = Client.newBuilder(appId, appSecret).build(); // 創(chuàng)建請(qǐng)求對(duì)象 CreateAppTableRecordReq req = CreateAppTableRecordReq.newBuilder() .appToken("JvJpbhm31a1s5xsqvOKcUTEMnrb") .tableId("tblDPPkqY93he1AO") .appTableRecord(AppTableRecord.newBuilder() .fields(new HashMap <String, Object > () { { put("名稱", "wiliam"); put("單號(hào)", "SX009"); } }) .build()) .build(); // 發(fā)起請(qǐng)求 CreateAppTableRecordResp resp = client.bitable().appTableRecord().create(req); // 處理服務(wù)端錯(cuò)誤 if(!resp.success()) { System.out.println(String.format("code:%s,msg:%s,reqId:%s, resp:%s", resp.getCode(), resp.getMsg(), resp.getRequestId(), Jsons.DEFAULT.toJson(resp.getRawResponse()))); return; } // 業(yè)務(wù)數(shù)據(jù)處理 System.out.println(Jsons.DEFAULT.toJson(resp.getData())); } }
運(yùn)行一下代碼,返回的結(jié)果和控制臺(tái)上面相同
然后再在多維表中可以看到多了一條數(shù)據(jù)
6.2.6 刪除記錄
完整代碼如下,注意:
- appToken,即上一步獲取知識(shí)庫(kù)空間節(jié)點(diǎn)信息返回的 app_token;
- recordId ,可以使用上一步新增的那條記錄返回的recordId ;
package com.congge.feishu; 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; /** * TODO 第四步 : 刪除多維表數(shù)據(jù),原始的URL: * https://kxv0z438jth.feishu.cn/wiki/Sv8SwfjImiWFusk2MBEczz0AnNg?table=tblDPPkqY93he1AO&view=vewq1cS7NC */ public class DeleteTableDataTest { public static void main(String[] args) throws Exception { String appId = "你的appId "; String appSecret = "你的appSecret"; // 構(gòu)建client Client client = Client.newBuilder(appId, appSecret).build(); // 創(chuàng)建請(qǐng)求對(duì)象 DeleteAppTableRecordReq req = DeleteAppTableRecordReq.newBuilder() .appToken("你的appToken") .tableId("你的tableId") .recordId("你的recordId") .build(); // 發(fā)起請(qǐng)求 DeleteAppTableRecordResp resp = client.bitable().appTableRecord().delete(req); // 處理服務(wù)端錯(cuò)誤 if(!resp.success()) { System.out.println(String.format("code:%s,msg:%s,reqId:%s, resp:%s", resp.getCode(), resp.getMsg(), resp.getRequestId(), Jsons.DEFAULT.toJson(resp.getRawResponse()))); return; } // 業(yè)務(wù)數(shù)據(jù)處理 System.out.println(Jsons.DEFAULT.toJson(resp.getData())); } }
運(yùn)行上面的代碼,可以看到記錄刪除成功
刪除成功后可以看到多維表中上面這條記錄被刪除了
七、寫(xiě)在文末
本文通過(guò)實(shí)際操作過(guò)程詳細(xì)介紹了如何對(duì)接飛書(shū)的多維表,希望對(duì)看到的同學(xué)有用哦,本篇到此結(jié)束,感謝觀看。
到此這篇關(guān)于Java 對(duì)接飛書(shū)多維表格使用詳解的文章就介紹到這了,更多相關(guān)Java 飛書(shū)多維表格內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
Activiti開(kāi)發(fā)環(huán)境的配置
本篇文章主要內(nèi)容介紹了Activiti開(kāi)發(fā)環(huán)境的配置,小編覺(jué)得挺不錯(cuò)的,現(xiàn)在分享給大家,也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2018-04-04一篇文章帶你搞懂Java restful 接口開(kāi)發(fā)
這篇文章主要介紹了Java restful 接口開(kāi)發(fā)的幾種方式(HTTPS),小編覺(jué)得挺不錯(cuò)的,現(xiàn)在分享給大家,也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2021-10-10開(kāi)發(fā)10年,全記在這本Java進(jìn)階寶典里了
這篇文章主要給大家分享介紹了這本Java進(jìn)階寶典里,是開(kāi)發(fā)10年總結(jié)出來(lái)的,文中通過(guò)圖文介紹的非常詳細(xì),需要的朋友可以參考借鑒,下面來(lái)一起看看吧2019-04-04java擴(kuò)展Hibernate注解支持java8新時(shí)間類(lèi)型
這篇文章主要介紹了java擴(kuò)展Hibernate注解支持java8新時(shí)間類(lèi)型,需要的朋友可以參考下2014-04-04Java中的FutureTask實(shí)現(xiàn)異步任務(wù)代碼實(shí)例
這篇文章主要介紹了Java中的FutureTask實(shí)現(xiàn)異步任務(wù)代碼實(shí)例,普通的線程執(zhí)行是無(wú)法獲取到執(zhí)行結(jié)果的,FutureTask?間接實(shí)現(xiàn)了?Runnable?和?Future?接口,可以得到子線程耗時(shí)操作的執(zhí)行結(jié)果,AsyncTask?異步任務(wù)就是使用了該機(jī)制,需要的朋友可以參考下2024-01-01