飞书应用开发初解

前言

　　飞书是一款企业常用的协作管理平台，集通讯、文档、会议、审批等等一体化，由字节跳动于2017年开发完成。使用飞书产品的企业，都有他们自己的企业号。

　　而对于这些企业而言，飞书不仅仅提供了上述的功能，还能做二次开发，也就是说能够进一步增强飞书的功能，包括了通讯录、云文档、审批、机器人、小程序等等。同时也能够调用飞书相应的API，给公司做控制访问管理。具体引用文档上的一张图：

　　现在我来根据飞书开发文档做一些简单介绍，链接也放在这里：https://open.feishu.cn/document/home/index。

开放平台介绍

　　该平台主要2种应用类型：企业自建应用、应用商店应用。前者是企业内部使用的，后者是所有飞书使用者都可以去使用的。这边飞书开发都是讲的前者，做企业内部的飞书开发。

　　这些应用中，主要有4种应用形态：小程序（不推荐）、网页、机器人、工作台小组件。

　　相应应用都是可以调用飞书的API的，使用示例可以在API调试台中看到，调用方式主要分为webhook和sdk。webhook就是用curl的方式去调用，除了命令行使用，还可以用各自语言中直接发送Http数据包的方式去调用。sdk的话是飞书自己开发的封装好的包，可以直接传入相关参数进行调用。两者的区别和调用方式可以参考API调用(webhook/sdk)。

应用鉴权

访问凭证（access_token）：用于识别应用在访问飞书时使用的虚拟身份，代表应用从平台侧获取的授权。用于验证调用方身份、确保调用方具有执行操作所需要的权限。详情参考应用访问凭证。
API 权限（Scope）：定义应用能够调用哪些飞书开放能力接口（OpenAPI）。API 接口权限是以应用为维度授予的，每个应用的接口权限都是独立存在的，若多个应用需要调用同一个接口，那么每个应用都要添加对应的接口权限。详情参考应用 API 权限。
可用范围：定义哪些用户可以在飞书中看到和使用该应用，详情参考应用可用范围。

不同类型的用户ID

　　飞书中提供了5个不同的用户ID，开发者应该根据情况选用合适的ID。

ID	定义	生成方式	注意事项
lark_id	全局 ID，物理用户身份。刚完成注册的飞书用户属于个人身份，你可以在飞书 App 上看到`飞书个人版`的标识。	当一个用户用手机号在飞书注册登录之后，就会在飞书中生成一个全局 lark_id。	lark_id 对开发者或普通飞书用户来说不可见，开发者也无需关注。
user_id	用户在企业或组织内的身份。同一个飞书用户在企业 A 和企业 B 内的 user_id 是不同的。 user_id 也称为 employee_id，这两个概念在大多数情况下完全对等（除飞书招聘业务）。	通过调用创建用户接口在员工入职时直接指定其 user_id。也可以由企业管理员在添加用户时指定。推荐企业使用邮箱前缀、工号或者手机号等有意义的字段作为员工的 user_id，这便于和企业既有的业务系统在用户身份上保持一致。如果在调用创建用户接口时没有指定 user_id 字段，则系统会随机生成一个字符串作为该用户的 user_id。	一个飞书用户可以同时加入多个企业或组织，其在每个企业或组织内的身份是逻辑独立的，并且在数据层面相互隔离。用户存在“离职再入职”的场景，合理设计 user_id 的规则有利于维护账号体系。
open_id	用户在应用内的身份。同一个 user_id 在不同应用中的 open_id 不同，其值统一以 ou_ 为前缀，如`ou_c99c5f35d542efc7ee492afe11af19ef`。	open_id 是用户在特定应用下才存在的身份标识，所以其生成是由用户在第一次启用该应用时由系统赋值生成的，对开发者来说这都是「只读」字段。	不要在跨应用的数据通信过程中使用 open_id。一个常见的的错误用法是，用应用 A 的鉴权凭证获取到了用户 open_id 之后，在应用 B 中直接使用，这种情况会直接提示出现跨应用操作的错误信息。
union_id	用户在同一应用服务商提供的多个应用间的统一身份。让应用开发商可以把同个用户(以 user_id 为标识）在多个应用中的身份关联起来。在需要跨应用做用户 ID 关联的场景中，开发者可以使用飞书开放平台提供的 union_id。union_id 以 on_ 为前缀，如 `on_cad4860e7af114fb4ff6c5d496d1dd76` 。	union_id 都是用户在特定应用下才存在的身份标识，所以其生成是由用户在第一次启用该应用时由系统赋值生成的，对开发者来说这都是「只读」字段。	应用开发商是组织概念，而非开发者维度的概念。

不同类型的token

　　token是访问凭证，用于身份鉴权，在飞书中有三种token类型。

访问凭证类型	是否需要用户授权	说明
tenant_access_token	否	以应用身份调用 API 时需要使用的凭证，可读写的数据范围由应用的数据权限范围决定。该类凭证的值以`t-`为前缀，示例值：`t-24b5bf4e00b2af1234`。
user_access_token	是	以用户身份调用 API 时需要使用的凭证，可读写的数据范围由用户可读写的数据范围决定。该类凭证的值以`u-`为前缀，示例值：`u-Lr1RT7S8fS03mT1234`。
app_access_token	否	应用身份的短期令牌。开放平台根据 app_access_token 识别调用方的应用身份。该类凭证的值以`a-`或者`t-`为前缀，示例值：`a-24b5cef00b1234`。