准备工作

飞书开放平台-开发文档：https://open.feishu.cn/document/home/index

下载飞书手机版：手机号注册一个账号方便后面测试

可以关注快速上手的API：

相关参数信息：

1
2
3
4
5
6
凭证
appid: xx
app secret: xx
事件请阅
Verification Token: xx
Encrypt Key: xx

创建机器人

  • 开发者后台创建一个自己的企业，然后添加应用能力：机器人

  • “凭证与基础信息页面”创建应用版本

  • 权限管理页面开通”获取与发送单聊、群组信息”

  • “事件与回调页面”配置自己的项目地址(要有能访问的服务)，打通回调，并且添加“接收消息”事件

交互的大体流程（很基础很重要）

image-20240221142131409

配置请求地址中的工程示例代码：

Java版示例代码：https://open.feishu.cn/document/server-docs/event-subscription-guide/event-subscription-configure-/request-url-configuration-case

Java版服务端SDK：https://open.feishu.cn/document/server-docs/server-side-sdk

快速上手

API文档真的多，萌新一上来，根本不知道要干嘛，只希望可以直接调通

创建飞书应用

首先，需要在飞书开发者后台创建一个应用：https://open.feishu.cn/app?lang=zh-CN

image-20240221153558643

应用创建完毕，补全版本号方可生效：

image-20240221153616608

成功之后，会收到“开发者小助手”发来的消息：

image-20240221153927511

申请权限

如果要调用 API，需要先获取接口调用权限；如果涉及到访问敏感字段，还需获取访问敏感字段的权限。

在飞书开发者后台，点击相关的应用，然后定位到左侧栏的“权限管理”选项，即可开通相关的权限。

image-20240221154103290

注意： 权限的申请应该遵循最小可用的原则。权限范围过大可能会威胁企业数据安全，导致应用无法通过审核。在无充分理由的情况下，请注意杜绝直接申请大量的接口权限。*

飞书管理后台（管理员审核）：https://feishu.cn/admin

测试版

也可以创建测试版，免审核，适合开发阶段使用

在测试应用中，默认自己就是管理员身份，因此申请权限时是申请就开通。

image-20240221154222947

获取访问凭证

当以上两步都操作完毕，即“应用创建及审核通过”和“权限配置”完毕后，即可开始调试飞书 API。

飞书 API 的调试需要通过相关的访问凭证方可调用成功，所以需要先获取凭证。

因为是本教程的操作是自建应用，所以打开“开发者后台”后，选择相关的应用，然后点击左侧栏的“凭证与基础信息”即可看到当前的应用凭证。

image-20240221154749399

将应用凭证的 App ID 和 App Secret 复制下来，填入接口的 body 请求体中，即可获取到 access_token 凭证，如下图所示：

image-20240221163749936

image-20240221154818063

注意要在有效期内使用

也可以直接在飞书开发者后台通过API调试页面直接刷新获取

image-20240221173424468

添加IP白名单

不要配置，测试的时候API调不通，萌新都不知道发生了什么，坑

为了提高应用访问的安全性，开发者可以通过 IP 白名单功能设置能够合法访问飞书服务端 API 的 IP 列表，

不在白名单列表中的 IP 地址的请求会被拒绝，并返回错误提示信息。

在 Windows 系统上，使用快捷键 Win+R，然后输入 cmd 按回车，输入 ipconfig，即可看到当前系统的 ip 地址：

image-20240221154931537

然后在飞书开发者后台，选择一个应用后，点击左侧的“安全设置”，即可填写 IP 白名单。

image-20240221155013367

开始调试API

在apifox club可以克隆公共的API调用示例！非常方便！！

https://apifox.com/apihub

调试之前记得配置上之前获取到租户凭证

image-20240221170020918

开通“通过手机号或邮箱获取用户 ID”的权限：

image-20240221155418742

然后在调试工具中，填写你的手机号或者邮箱，即可获得 user_id

image-20240221155508494

有了 user_id 后，就可获取单个用户信息，如下图所示：

image-20240221155524918

其它操作也是类似，要使用某个功能，一般是先获取凭证和相关的参数，然后即可调用。

到这里，你就可以访问API了

优秀案例

这里有一些优秀的案例：https://bytedance.larkoffice.com/wiki/R6f9wEDftisiLkkTp0Qcpgjrnoc?table=tblLWDZe5wC1X4PW&view=vewKvhlUWq

至此，你就已经学会飞书API调用是怎么一回事了

开发感悟

  • 可能有开发者会问，调用飞书的API，为什么需要创建一个应用呢？

首先这是飞书的应用开发流程要求的。我个人理解，这主要还是和权限&安全相关，如果开放API给任何人用，任何人都可以操作其他人的数据，这不就乱套了嘛。创建一个应用，收敛权限为：只有管理员和协作者有操作权限，若不申请相关权限，是不能获取企业内他人信息的

  • 那么应用如何解决个人的权限隔离问题？

就调用API来自动创建文档需求而言，创建的文档在应用本身自己的空间中（后续若让其他人有操作权限，需通过api添加权限或转移所有权）。或者讲：自己的空间自己操作。

  • 如何理解开发者调用api的行为与应用之间的关系？

应用本身有自己的空间，一种好的类比理解是：新建应用（注册一个飞书账号）-通过API操作应用（在账号内部自己正常做自己的事情，区别只在于一个通过api一个自己去点界面而已）。则其产出的文档肯定在自己的空间中，就好比在飞书自己的空间中创建的文档，如果没有授权，其他人是没有访问权限的。

  • 企业自建应用和商店应用应该建哪一个？该需求创建商店应用可以不可以？

见关键概念，本需求只在小组内使用，则建立企业自建应用。可以但无必要，商店应用的创建、核、发布、权限审核等流程比较麻烦，增加开发审核负担，不是通用能力，分享无必要。

  • 关于token刷新问题

如果采用Postman进行调试，一个明显的感知是token会自动过期，需要一直刷新，在这一点上，后端api获取的操作对象会自动进行刷新，比较方便。

  • 如果处理量比较大，后端延退严重，可初步将数据填充完后及时将链接返回，其他的调整格式的耗时操作后续自动处理。

思路：创建在线文档–数据处理-填充数据–SendLark（发送链接到群）–格式调整–end实现：打开链接查看数据–格式自动在调整

关键点：在返回时做文档权限的转移（飞书平台>操作者

飞书api我会调用了，但是我想要在springboot项目中使用，应该怎么做呢？来代码实战吧

Spring Boot集成飞书OpenAPI

最直接的学习方式是下载官网的示例：

https://github.com/larksuite/oapi-sdk-java

sample包下的例子，直接启动，然后用ngrok做内网穿透，然后配置地址到飞书后台的回调地址就行了。

image-20240222151328684

将appid和appsecret配置好

image-20240222155352484

启动项目

在手机端飞书测试部门添加机器人，然后发送消息，可以在项目后台接收到消息。

image-20240222155512441

至此，你可以开发自己的业务逻辑了。