飞书开发学习笔记(二)-云文档简单开发练习

飞书开发学习笔记(二)-云文档简单开发练习

一.云文档飞书开发环境API

首先还是进入开放平台
飞书开放平台：https://open.feishu.cn/app?lang=zh-CN
云文档相关API都在“云文档”目录中，之下又有"云空间",“文档”，“电子表格”，“多维表格”等子模块，
各自有对应的功能API。

二.利用飞书API操作文件夹和云文档

2.1 获取我的空间目录下的文件清单

对于一个企业用户而言，他拥有一个"个人空间"的目录，对应的就是"我的空间" root folder。

获取我的空间这个根目录下的文件清单的API如下：

真实请求地址: 
GET
https://open.feishu.cn/open-apis/drive/v1/files?direction=DESC&order_by=EditedTime

返回结果为Json字符串，由响应头和响应体构成，其中响应体为关键返回信息，如下：

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

可以看到files：[]数组为空，也就是说，主目录下没有文件。
为了测试，我们在"我的空间"目录下新建一个"测试文档"的云文档以及一个“测试表格”的电子表格,以及一个"测试子目录"的子目录，然后再查询一次

返回的响应体结果如下：
code 0代表查询成功
files[]数组中不再是空，而是有三个元素，对应的分别是“测试子目录”，“测试表格”，“测试文档”

{"code": 0,"data": {"files": [{"created_time": "1691555","modified_time": "1691555","name": "测试子目录","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": "测试表格","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": "测试文档","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中每个元素有8个字段构成：
created_time：创建时间戳
modified_time：修改时间戳
name:文档名称
owner_id：文档拥有者Id
parent_token:父对象的令牌，这里也就是"我的空间"这个目录的令牌，可以通过这个令牌获取到父对象文件夹
token：本文档的令牌，也就是当前文档的"身份证"，也可以通过这个令牌获取到这个文档
type：这里可以看到文件夹的类型是folder，电子表格的类型是sheet，而文档的类型是docx
url：当前文件的https链接地址，通过这个地址跳转访问。

2.2 获取文件数据

这里的文件是不确定类型的，可能是doc，也可能是docx或者sheet
有了文件的token，就可以利用它来访问文档的元数据

返回数据

{"code": 0,"msg": "success","data": {"metas": [{"doc_token": "doccnfbcef","doc_type": "doc","title": "测试文档","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-内部"}],"failed_list": [{"token": "boxcachabcef","code": 970005}]}
}

其中code 0为成功返回
metas列表中则返回了文档的基本信息。
sec_label_name是保密等级名称
下面还有复制/移动/删除等操作的API函数，核心参数就是要拿到操作目录的token，以及当前文档的token。

2.3 获取云文档的详细内容

1. 获取云文档基本信息

根据文档的document_id，在开通相关文档操作的API权限的情况下，就可以利用云空间->文档->新版文档下的API来获取文档的整个内容。
文档内容是由若干块组成的，所以获取文档以后，还需要获取块和子块的信息。
document_id就是文档的唯一id，在文档的地址中最后一部分即是，目前发现与当前文档的token是一致的。

获取文档基本信息，需要填入document_id

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

{"code": 0,"data": {"document": {"document_id": "PAiZdxxxx","revision_id": 7,"title": "测试文档"}},"msg": "success"
}

2. 获取云文档的纯文本内容
   
   返回数据

{"code": 0,"data": {"content": "测试文档\n测试文档\n"},"msg": "success"
}

content中返回了纯文本内容，包括换行符等字符

3. 获取云文档的所有块
   
   返回数据

{"code": 0,"data": {"has_more": false,"items": [{"block_id": "PAiZdu4wuoNPxxxxx","block_type": 1,"children": ["Vvabd8vG3ozusxxx"],"page": {"elements": [{"text_run": {"content": "测试文档","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": "测试文档","text_element_style": {"bold": false,"inline_code": false,"italic": false,"strikethrough": false,"underline": false}}}],"style": {"align": 1,"folded": false}},"parent_id": "PAiZdu4wuoNPxxxxxxxx"}]},"msg": "success"
}

从返回数据可以看到，在data下的items中有block的信息。
block的主要字段为
block_id为块的id
block_type为块的类型
children为子块的id列表
接下来为该block的类型名称，如page为正文， heading3则为标题3，名称后的列表则是子元素的格式和内容
text_run：为子元素类型
content：文本内容
text_element_style：文本元素的style，包粗体 下划线 删除线等等
子块的最后信息是父元素的id即parent_id
如以上，则获取了云文档的全部内容。

2.4 获取电子表格的详细内容

1. 获取电子表格和工作表信息
   和云文档类似，通过另一个电子表格口令spreadsheet_token可以获取表格的信息
   

返回信息

{"code": 0,"data": {"spreadsheet": {"owner_id": "ou_3bda2cc","title": "测试表格","token": "SVTxxxx","url": "https://test-cptojg6atdfe.feishu.cn/sheets/SVhh"}},"msg": ""
}

返回了owner_id，title，token，url
获取工作表的详细信息

返回信息

{"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个元素，因此查询到两张工作表
Sheet1 id:885d89
Sheet2 id:xBuAyL
grid_properties则包含了行数和列数信息，以及冻结的行列数信息

2. 先利用spreadsheet_token和sheet_id查询工作表信息
   
   返回数据

{"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": ""
}

与获取电子表格信息类似，是指定工作表信息，内容比较简单。

3. 根据工作表id获取表中的具体单元格和值信息
   调试工具台不支持API调试，但是回到开发文档，服务端API是有介绍的，因此只能通过开发程序来应用API能力读取单元格和值信息了。
   
   
   这个就下次在开发环境中测试了。