一、准备工作：

对于几乎所有的一体化协同办公平台而言，因为涉及到的工作流程非常多样化，所以会有各种不同的功能。包括不限于人员信息管理（通讯录）、消息管理、云文档管理、会议管理、日程管理、审批管理等等……

对于办公平台而言，基于企业做内部系统或搭建企业业务自动化的需求，需要将一些功能，提供给企业用于外部连接（API接口），这样企业才能够将实现对应的办公平台功能的自动化完成。

但是，如果直接提供功能，将会导致功能过多，不论是从使用效率还是安全性而言都不合适。因此普遍都会采用，集成开放平台的方式。

总而言之，办公平台的所有自动化需求，被集中到对应平台自身的开放平台上，由开放平台的应用统一做权限管理和调用。

而外部系统只能够通过访问这个开放平台的应用，进一步的，实现应用进行办公平台的工作流完成。

所以在使用绝大多数办公平台的功能时，都需要做下列逻辑的准备工作：

• 创建开放平台应用
• 对应用进行需要权限的申请（部分涉及到对外传输数据的权限，需要企业的管理人员审批）和应用能力的申请（根据需求是否需要）
• 设置应用调用的事件请求or回调（根据需求是否需要）
• 发版应用（需要企业的管理人员审批）

以飞书多维表格功能举例，流程如下：

创建开放平台应用

飞书开放平台地址： https://open.feishu.cn/

• 登录并进入开放平台

• 点击创建企业自建应用

• 进行应用基本信息填写

• 获取应用凭证信息（外部调用应用的必要数据，重要！）

对应用进行需要权限的申请（部分涉及到对外传输数据的权限，需要企业的管理人员审批）和应用能力的申请（根据需求是否需要）

• 多维表格的外部调用，不需要添加应用能力！不需要！

但是，需要添加对应的多维表格权限！需要！

• 首先进入权限开通的界面

• 选中多维表格权限并确认开通

设置应用调用的事件请求or回调（根据需求是否需要）

• 多维表格外部调用功能不需要设置事件回调，不需要！

发版应用（需要企业的管理人员审批）

• 进入版本发布标签页面

• 填写应用发布的必要信息

• 申请后，需要管理员在飞书管理后台进行审批同意；

开发者界面会看到审批中提示，可以选择撤销申请

• 重要！应用完成创建且审批结束，还需要添加进入对应的多维表格，才能执行对应功能。

进入需要操作的多维表格，操作添加应用（该功能需要操作人具有文档管理权限与应用使用权限）

到这里，准备工作完美结束！

二、飞书多维表格说明

对于多维表格的使用，首先需要打破常规对于表格的认识；

传统表格的常见储存结构：工作簿（workbook）->工作表（sheet）->行、列、单元格（row、column）->数据（data）

如果按照传统格式，我们常见的用法是，确定工作簿对象、工作表对象，针对需求选择行、列、单元格，作为数据写入或读取的范围，最终进行数据处理。

特别需要解释的是：我们在传统表格，数据的结构（关系）是与数据的位置（行列）相关联的，这一点和多维表格完全不同。

无论是在线表格还是本地表格，基本操作是一致的，唯一的区别，本地表格可能使用本地资源路径读取文件，得到对象。但是在线表格通过在线的表格唯一标识获取文件对象，同时除了表格标识，工作表（sheet）也会具备独特的标识。

但是多维表格和传统无法用同一概念去理解，多维表格的数据储存结构完全不同，并非按照行、列、单元格，的位置关系进行储存和数据储存结构的设计。多维表格类似于添加了非常多应用的数据库，所有的信息，按照一条条互相独立的数据储存在一个“表格”整体中。

只不过这个数据默认用最基本的表格形式做了展示（类似于数据库，如果直观的去看数据库的内容，也非常类似一张表格）。

因此，在处理和使用多维表格时，一定要始终去理解一条数据的概念，将每一条数据所包含的内容作为一个整体去看。

多维表格类型

由于飞书中多维表格有不同的类型，虽然大体操作思路相同，但是在一些唯一标识的获取上有很大区别。

所以确定表格类型并获取唯一标识（app_token）非常关键。

1、文件夹中的多维表格——Base app

区分方法：多维表格打开后，url字段包含 /base/ 内容。

在企业未在飞书上进行线上数据的同一整理（建立有逻辑，结构清晰的数据档案分类）时，可能所有的线上文档数据，会出现直接在云空间中进行创建。

长期来讲，这对于企业是不利的。因为这种情况创建的所有在线文档，文档和文档之间没有关联，未进行统一的归纳梳理。随着使用量的增加，业务数据的冗杂程度将会不断提高，以至于经历一段时间之后，企业的运转流程越来越复杂，数据使用难度提高，最终想要解决问题，又不得不面临丢弃所有数据，或者花费极大人力物力进行归档。

正常来讲这种情况会比较多的出现在临时文档的创建（非系统的，长时间的使用，仅仅用于暂时数据储存、处理和展示）。

这种情况的唯一标识（app_token）获取非常容易，直接才打开文档后的url中就能获取到，如上图高亮部分。

2、知识库下的多维表格——wiki node

区分方法：多维表格打开后，url字段包含 /wiki/ 内容。

注意：/wiki/ 字段后续紧跟的内容为知识库节点token，不是多维表格app_token，无法直接用于后续RPA指令使用。

这一类的线上文档，存在于系统性的知识库中。就整体而言，能够有更好的企业线上数据整体结构。

但是因为数据存在于一个企业的数据整体（知识空间）中，因此无法直接得到单个文档的唯一标识（app_token）。

需要使用知识库相关获取知识空间节点信息接口获取该类多维表格的 app_token。

接口获取一般企业一次性使用并记录即可，因此可以直接在开放平台使用内置的API调试台，得到即可，不需要使用代码请求。

接口获取链接（需要登录）： https://open.feishu.cn/document/server-docs/docs/wiki-v2/space-node/get_node

获取流程如下：

• 启动API调试台选择开放平台应用进行数据获取

• 点击获取用户token（相当于判断正在操作的用户是否有权限，去使用当前获取空间节点信息的功能，会有一个飞书授权动作）

• 从 /wiki/ 多维表格url，后获取节点toekn

（注意！这不是多维表格的唯一标识app_toke，而是知识库节点token，我们要通过节点获取多维表格的app_token）

• 填写知识库节点token并运行API

• 获取结果中对应的多维表格（wiki）app_token

3、文档嵌入多维表格——Base docx block

区分方法：文档打开后，url字段包含 /docx/ 内容。

注意：/docx/ 字段后续紧跟的内容为在线文档document_id，不是多维表格app_token，无法直接用于后续RPA指令使用。

这类多维表格并非独立一份在线文档，而是存在于在线文档（docx）内作为一个内嵌块存在，作为文档数据和功能补充。

同样因为数据存在于在线文档（docx）中，因此无法直接得到单个文档的唯一标识（app_token）。

需要使用知识库相关获取文档所有块信息接口获取该类多维表格的 app_token。

接口获取一般企业一次性使用并记录即可，因此可以直接在开放平台使用内置的API调试台，得到即可，不需要使用代码请求。

接口获取链接（需要登录）：  https://open.feishu.cn/api-explorer/cli_a704fcd4aaee500b

获取流程如下：

• 点击获取用户token（相当于判断正在操作的用户是否有权限，去使用当前获取空间节点信息的功能，会有一个飞书授权动作）

• 从 /docx/ 在线文档url，后获取文档的document_id

• 填写在线文档document_id并运行API，获取多维表格块app_token

4、电子表格嵌入多维表格——Base sheet block

区分方法：文档打开后，url字段包含 /sheets/ 内容。

注意：/sheets/ 字段后续紧跟的内容为在线电子表格的spreadsheetToken，不是多维表格app_token，无法直接用于后续RPA指令使用。

这类多维表格并非独立一份在线文档，而是存在于在线电子表格（sheets）内作为一个内嵌块存在，作为电子表格数据和功能补充。

同样因为数据存在于在线电子表格（sheets）中，因此无法直接得到单个文档的唯一标识（app_token）。

需要使用知识库相关获取文档所有块信息接口获取该类多维表格的 app_token。

该部分由于飞书开放平台的更新，暂时无法在线获取，需要手动运行请求代码，获取数据，难度较高，不作步骤演示。

参考文档：  https://open.feishu.cn/document/server-docs/historic-version/docs/sheets/obtain-spreadsheet-metadata

三、多维表格的数据结构和指令

多维表格对于一整份在线文档而言，数据按照以下层级进行储存：

多维表格文档->数据表（table）->视图（view）（不同的展示形式）

                                                   └>字段（field）（数据的多个维度）

                                                   └>记录（record）（实际的每一条记录在内的数据整体）

按照上述第二点，对于多维表格的介绍，多维表格数据，以一条记录（record）中多部分数据为整体，进行储存，因此需要明确2点：

• 最终以数据读取、写入为目的的处理一定是针对记录（record）相关的指令。
• 除添加新增记录（record）之外，其他对已有数据的操作，均需要依据数据对应的id为依据进行编辑。

下面将会根据多维表格文档的不同层级做指令使用介绍。

1、RPA指令使用准备工作，录入凭证以及填写多维表格的app_token

使用RPA指令进行在线文档操作，可以认为必须经过开放平台应用，作为任务的中间流转；相当于在每一次执行功能时，都需要确认我们所执行的单项工作，是调用哪个开放平台应用（凭证）。

由于开放平台应用的凭证，是固定不变的（ID无法改变，secret可以手动重置，不会自动变化），所以我们可以进行一次凭证录入，从而在后续的所有开放平台有应用相关指令中，选择即可，不需要重复填写。

录入流程如下：

• 在RPA指令中选择新增凭证

• 将准备工作，获取的开放平台应用appID与appSecret复制

• 在弹出的界面填写对应信息，修改权限范围

（用户权限为该凭证仅当前RPA账号使用，组织权限为企业内部RPA均可使用）

• RPA指令凭证选择界面出现新增凭证，可以点击右侧编辑按钮修改名称，方便识别

• 填写app_token

（app_token的获取在上述的二、飞书多维表格说明中，详细介绍了各种类型多维表格的token获取方法，不再赘述）

2、数据表相关指令

数据表，本身相当于在一份多维表格文档中，多个独立的数据空间；

不同数据表内的数据，无直接关联。

可以理解为，数据表1，与，数据表2，中，哪怕有内容相同的记录（数据），也是互相独立的两条，仅仅内容相同而已；

同时，数据表的id在一个多维表格文档中唯一且不变，因此可以程序中直接写为常量数据。

后面将会以上图为准进行数据表指令展示

相关指令如下：

• 列出数据表

列出其实相当于读取当前多维表格文档的所有数据表数据，该指令可以得到每一张数据表的id数据，用于后续对数据表进行的修改。

无需填写额外内容，即可获取多维表格文档对象的所有数据表信息。

返回结果说明：

返回结果为一个整体数据，需要提取出items部分才能够获取详细数据

返回值为列表、字典嵌套结构；

外层列表包含每一个数据表数据，每一个数据表数据储存为一个字典数据。

字典包含，表明（name）、数据表id（table_id）、数据表版本号（revision）

• 添加数据表

允许RPA流程，自动往多维表格文档中新建新的数据表。

由于数据表本身至少需要有1个视图，因此需要创建新数据表时，同时制定数据表名称和视图名称。

• 更新数据表

更新并非是更新数据表内部的数据，对于整个数据表而言，只是修改该表格的名称而已。

选择被修改的数据表，填写修改后的名称即可。

• 删除数据表

删除数据表可以自动从一份多维表格文档中，将置顶数据表删除。

RPA指令中进行简化，只需好填写数据表表明即可，并且支持填写app_token后，用户下拉框选择。

3、视图相关指令

视图是一张数据表中，数据的不同形式的展现，展现的数据范围均为当前数据表的数据。

重要！在一张数据表中，数据是在所有视图范围内通用的。

• 列出视图

类似于列出数据表，可以得到一张数据表内全部的视图数据并返回。

需要注意，因为视图存在于单个数据表中是唯一的，因此选择凭证、填写app_token之后，还需要选择需要获取的数据表。

获取数据仍然需要选择数据信息部分，做进一步提取

返回说明：

数据为3层结构，最外层字典，包含数据表整体视图数目（total）等基本信息。

其中通过items，可以取到内层列表结构。

该列表对应为每一个视图数据，单个视图数据为列表中的一个字典。

包含视图id（view_id）、视图类型（view_type）、视图权限等信息。

• 新增视图

类似其他新增指令，因视图存在于数据表内，因此需要在确定凭证、app_token后，选择数据表。

另外，创建视图需要指定视图名称和视图类型。

• 更新视图

同其他更新指令，仅仅更新名称，不对内容和类型进行修改。

需要确定数据表，以及该表内确定的视图名称，并指定修改后的名称。

• 删除视图

同其他删除类指令，逐级选择指定到具体的视图对象，即可完成视图删除。

4、字段相关指令

字段，在表单视图中，会体现为多维表格的“列”，但是不同视图情况下，所展示的数据是不一样的。

字段的本质，可以理解为，一个数据单元，包含的数据组成有哪些。

任何一条数据（记录），可以包含任意个字段数据，允许某些字段数据为空，甚至所有字段数据为空。

• 列出字段

逐级填写信息，指定数据表，即可获取该数据表所有数据单元的字段信息。

注意！因数据表内数据共同，尽管有些视图中并没有展示全部字段数据，但是每一条记录的所有字段数据，仍然存在（可以为空）。

因此，字段的设置同样在同一张数据表内是完全一致的，不收到视图影响。

返回说明：

同样返回数据需要读取内部信息，才能进一步做数据提取。

返回为多层嵌套结构，外层字典包含数据表整体字段信息。

items键，获取第2层列表，列表内容为所有字段数据，每一个字段数据为一个字典。

子店内包含字段id（field_id）、字段类型（ui_type）等数据。

• 添加字段

同其他添加类指令相同，逐级置顶到数据表后，可以选择新增的字段名称和字段类型。

• 更新字段

逐级指定到具体的字段数据后，可以用于修改字段的名称，以及重新设置字段的类型。

• 删除字段

逐级选择，指定到具体字段后，即可进行字段的删除。

5、记录相关指令

数据表中的每一行数据都是一条记录（record）。每条记录都有唯一标识。

数据由多条字段内容组成，无论以任何视图展示，记录在一张数据表中是统一存在的。

• 列出记录

可以获取一张数据表的所有记录数据。

注意！虽然数据在同一张表格中，是共用的。但是不同视图下，记录的展示形式（顺序）有所不同。

所以在列出记录时，需要指定需要获取的视图。

返回说明：

返回值为嵌套数据，提取内部信息之后，得到数据为列表类型。

列表中每一项为代表一条记录的字典，字典包含记录id（record_id）、所有字段内容（fields，字典结果）展示。

可以通过获取fields对应的字典，从而进一步获取字段的数据。

• 新增记录

新增记录相当于给目前已经存在的数据表中，增加新的数据。

由于记录是由多个字段内容组成，所以添加时可以对每一个字段内容进行填写（可以为空）

由于记录在不同的视图中是共用的，所以新增记录不需要指定视图，所有视图中数据会自动新增。

• 更新记录

更新记录用于对已经存在的记录进行修改，由于记录已经存在，所以需要指定目前需要修改的记录对象。

记录对象需要用到记录的唯一id（record_id），可以在更新前，对记录进行列出从而获取。

注意！在这里，指令中虽然会需要填写所有字段信息，但是不填写的部分默认为不修改，只会将填写部分进行修改。

• 检索记录

注意！该功能并非用于记录查询！

检索功能类似于列出，区别在于，列出记录用于得到一个数据表中所有记录数据（不同视图顺序不同）

而检索，用于确定记录id的情况下，获取指定一条记录的数据。

• 删除记录

同其他删除功能，逐级指定到对应的记录即可将记录内容删除。

注意！记录需要使用记录id（record_id）进行指定，因此删除前，需要对记录进行列出，从而获取记录id。

更多技术问题，欢迎咨询线上、线下技术支持！