飛書(shū)開(kāi)發(fā)學(xué)習(xí)筆記(二)-云文檔簡(jiǎn)單開(kāi)發(fā)練習(xí)

一.云文檔飛書(shū)開(kāi)發(fā)環(huán)境API

首先還是進(jìn)入開(kāi)放平臺(tái)
飛書(shū)開(kāi)放平臺(tái)：https://open.feishu.cn/app?lang=zh-CN
云文檔相關(guān)API都在“云文檔”目錄中，之下又有"云空間",“文檔”，“電子表格”，“多維表格”等子模塊，
各自有對(duì)應(yīng)的功能API。

二.利用飛書(shū)API操作文件夾和云文檔

2.1 獲取我的空間目錄下的文件清單

對(duì)于一個(gè)企業(yè)用戶(hù)而言，他擁有一個(gè)"個(gè)人空間"的目錄，對(duì)應(yīng)的就是"我的空間" root folder。

獲取我的空間這個(gè)根目錄下的文件清單的API如下：

真實(shí)請(qǐng)求地址: 
GET
https://open.feishu.cn/open-apis/drive/v1/files?direction=DESC&order_by=EditedTime

返回結(jié)果為Json字符串，由響應(yīng)頭和響應(yīng)體構(gòu)成，其中響應(yīng)體為關(guān)鍵返回信息，如下：

{"code": 0,"data": {"files": [],"has_more": false},"msg": "success"
}

可以看到files：[]數(shù)組為空，也就是說(shuō)，主目錄下沒(méi)有文件。
為了測(cè)試，我們?cè)?#34;我的空間"目錄下新建一個(gè)"測(cè)試文檔"的云文檔以及一個(gè)“測(cè)試表格”的電子表格,以及一個(gè)"測(cè)試子目錄"的子目錄，然后再查詢(xún)一次

返回的響應(yīng)體結(jié)果如下：
code 0代表查詢(xún)成功
files[]數(shù)組中不再是空，而是有三個(gè)元素，對(duì)應(yīng)的分別是“測(cè)試子目錄”，“測(cè)試表格”，“測(cè)試文檔”

{"code": 0,"data": {"files": [{"created_time": "1691555","modified_time": "1691555","name": "測(cè)試子目錄","owner_id": "ou_3bd0cc","parent_token": "nodcnfcMb","token": "VGOkfIDnuf","type": "folder","url": "https://test-cptojg6atdfe.feishu.cn/drive/folder/VGOkrUnuf"},{"created_time": "16996","modified_time": "169682","name": "測(cè)試表格","owner_id": "ou_3bd053a2cc","parent_token": "nodcnEBAfcMb","token": "SVT0Zh","type": "sheet","url": "https://test-cptojg6atdfe.feishu.cn/sheets/SVT0Rnhh"},{"created_time": "1699408","modified_time": "1692455","name": "測(cè)試文檔","owner_id": "ou_3bd053cc","parent_token": "nodcnEcMb","token": "PAiZdu4wuAe","type": "docx","url": "https://test-cptojg6atdfe.feishu.cn/docx/PAiZdunAe"}],"has_more": false},"msg": "success"
}

files中每個(gè)元素有8個(gè)字段構(gòu)成：
created_time：創(chuàng)建時(shí)間戳
modified_time：修改時(shí)間戳
name:文檔名稱(chēng)
owner_id：文檔擁有者Id
parent_token:父對(duì)象的令牌，這里也就是"我的空間"這個(gè)目錄的令牌，可以通過(guò)這個(gè)令牌獲取到父對(duì)象文件夾
token：本文檔的令牌，也就是當(dāng)前文檔的"身份證"，也可以通過(guò)這個(gè)令牌獲取到這個(gè)文檔
type：這里可以看到文件夾的類(lèi)型是folder，電子表格的類(lèi)型是sheet，而文檔的類(lèi)型是docx
url：當(dāng)前文件的https鏈接地址，通過(guò)這個(gè)地址跳轉(zhuǎn)訪(fǎng)問(wèn)。

2.2 獲取文件數(shù)據(jù)

這里的文件是不確定類(lèi)型的，可能是doc，也可能是docx或者sheet
有了文件的token，就可以利用它來(lái)訪(fǎng)問(wèn)文檔的元數(shù)據(jù)

返回?cái)?shù)據(jù)

{"code": 0,"msg": "success","data": {"metas": [{"doc_token": "doccnfbcef","doc_type": "doc","title": "測(cè)試文檔","owner_id": "ou_b13d41c02edc5f1abcef","create_time": "1652045","latest_modify_user": "ou_b13d1abcef","latest_modify_time": "16520","url": "https://sample.feishu.cn/docs/doccabcef","sec_label_name": "L2-內(nèi)部"}],"failed_list": [{"token": "boxcachabcef","code": 970005}]}
}

其中code 0為成功返回
metas列表中則返回了文檔的基本信息。
sec_label_name是保密等級(jí)名稱(chēng)
下面還有復(fù)制/移動(dòng)/刪除等操作的API函數(shù)，核心參數(shù)就是要拿到操作目錄的token，以及當(dāng)前文檔的token。

2.3 獲取云文檔的詳細(xì)內(nèi)容

1. 獲取云文檔基本信息

根據(jù)文檔的document_id，在開(kāi)通相關(guān)文檔操作的API權(quán)限的情況下，就可以利用云空間->文檔->新版文檔下的API來(lái)獲取文檔的整個(gè)內(nèi)容。
文檔內(nèi)容是由若干塊組成的，所以獲取文檔以后，還需要獲取塊和子塊的信息。
document_id就是文檔的唯一id，在文檔的地址中最后一部分即是，目前發(fā)現(xiàn)與當(dāng)前文檔的token是一致的。

獲取文檔基本信息，需要填入document_id

返回信息：
只有revision_id版本id和title

{"code": 0,"data": {"document": {"document_id": "PAiZdxxxx","revision_id": 7,"title": "測(cè)試文檔"}},"msg": "success"
}

2. 獲取云文檔的純文本內(nèi)容
   
   返回?cái)?shù)據(jù)

{"code": 0,"data": {"content": "測(cè)試文檔\n測(cè)試文檔\n"},"msg": "success"
}

content中返回了純文本內(nèi)容，包括換行符等字符

3. 獲取云文檔的所有塊
   
   返回?cái)?shù)據(jù)

{"code": 0,"data": {"has_more": false,"items": [{"block_id": "PAiZdu4wuoNPxxxxx","block_type": 1,"children": ["Vvabd8vG3ozusxxx"],"page": {"elements": [{"text_run": {"content": "測(cè)試文檔","text_element_style": {"bold": false,"inline_code": false,"italic": false,"strikethrough": false,"underline": false}}}],"style": {"align": 1}},"parent_id": ""},{"block_id": "Vvabd8vGxxxx","block_type": 5,"heading3": {"elements": [{"text_run": {"content": "測(cè)試文檔","text_element_style": {"bold": false,"inline_code": false,"italic": false,"strikethrough": false,"underline": false}}}],"style": {"align": 1,"folded": false}},"parent_id": "PAiZdu4wuoNPxxxxxxxx"}]},"msg": "success"
}

從返回?cái)?shù)據(jù)可以看到，在data下的items中有block的信息。
block的主要字段為
block_id為塊的id
block_type為塊的類(lèi)型
children為子塊的id列表
接下來(lái)為該block的類(lèi)型名稱(chēng)，如page為正文， heading3則為標(biāo)題3，名稱(chēng)后的列表則是子元素的格式和內(nèi)容
text_run：為子元素類(lèi)型
content：文本內(nèi)容
text_element_style：文本元素的style，包粗體 下劃線(xiàn) 刪除線(xiàn)等等
子塊的最后信息是父元素的id即parent_id
如以上，則獲取了云文檔的全部?jī)?nèi)容。

2.4 獲取電子表格的詳細(xì)內(nèi)容

1. 獲取電子表格和工作表信息
   和云文檔類(lèi)似，通過(guò)另一個(gè)電子表格口令spreadsheet_token可以獲取表格的信息
   

返回信息

{"code": 0,"data": {"spreadsheet": {"owner_id": "ou_3bda2cc","title": "測(cè)試表格","token": "SVTxxxx","url": "https://test-cptojg6atdfe.feishu.cn/sheets/SVhh"}},"msg": ""
}

返回了owner_id，title，token，url
獲取工作表的詳細(xì)信息

返回信息

{"code": 0,"data": {"sheets": [{"grid_properties": {"column_count": 20,"frozen_column_count": 0,"frozen_row_count": 0,"row_count": 200},"hidden": false,"index": 0,"resource_type": "sheet","sheet_id": "885d89","title": "Sheet1"},{"grid_properties": {"column_count": 20,"frozen_column_count": 0,"frozen_row_count": 0,"row_count": 200},"hidden": false,"index": 1,"resource_type": "sheet","sheet_id": "xBuAyL","title": "Sheet2"}]},"msg": ""
}

返回的信息主體sheets列表中，共有2個(gè)元素，因此查詢(xún)到兩張工作表
Sheet1 id:885d89
Sheet2 id:xBuAyL
grid_properties則包含了行數(shù)和列數(shù)信息，以及凍結(jié)的行列數(shù)信息

2. 先利用spreadsheet_token和sheet_id查詢(xún)工作表信息
   
   返回?cái)?shù)據(jù)

{"code": 0,"data": {"sheet": {"grid_properties": {"column_count": 20,"frozen_column_count": 0,"frozen_row_count": 0,"row_count": 200},"hidden": false,"index": 0,"resource_type": "sheet","sheet_id": "885d89","title": "Sheet1"}},"msg": ""
}

與獲取電子表格信息類(lèi)似，是指定工作表信息，內(nèi)容比較簡(jiǎn)單。

3. 根據(jù)工作表id獲取表中的具體單元格和值信息
   調(diào)試工具臺(tái)不支持API調(diào)試，但是回到開(kāi)發(fā)文檔，服務(wù)端API是有介紹的，因此只能通過(guò)開(kāi)發(fā)程序來(lái)應(yīng)用API能力讀取單元格和值信息了。
   
   
   這個(gè)就下次在開(kāi)發(fā)環(huán)境中測(cè)試了。