如何理解事件推送？飞书集成案例

当涉及到应用程序之间的数据交互时，我们经常听到两个术语：API请求和事件推送。这两种方法都是信息传递的方式，但它们在如何触发和传递信息以及何时传递信息方面有着根本性的不同。本篇博客将深入探讨API请求和事件推送的定义以及它们的作用，帮助您更好地理解它们的区别以及何时使用哪种方式。

本文将通过飞书集成对接来帮助您更好的理解事件推送。无论您是一名开发人员、产品经理还是对技术领域感兴趣的人，理解这两种数据交互方式都将为您的工作和项目提供更多的灵活性和效率。让我们开始探索这两种重要的通信方式吧。

在线文档：【金山文档】 明道云-飞书集成
https://kdocs.cn/l/coARsa1lUTYJ

事件推送与API请求的定义以及作用

API请求（Application Programming Interface请求）：

定义： API请求是一种客户端应用程序与服务器之间进行通信的方式。通过API请求，客户端向服务器发送请求，请求特定的数据或执行特定的操作，然后服务器响应这些请求并提供相应的数据或执行相应的操作。

作用： API请求用于获取服务器上的数据或执行服务器上的操作。它允许不同的应用程序、系统或服务之间进行数据交换和互操作。API请求是一种主动请求方式，客户端应用程序必须明确指定需要的数据或操作，并主动发送请求，然后等待服务器的响应。这种方式通常适用于需要特定数据的情况，例如，从服务器获取天气信息、查询数据库中的用户信息或执行支付交易等。

事件推送：

定义： 事件推送是一种服务器主动通知客户端应用程序有关特定事件的发生或数据的变化。客户端应用程序在订阅事件后，服务器会在事件发生时主动向客户端推送相关信息，而无需客户端主动查询或请求。

作用： 事件推送用于实时通知客户端应用程序有关特定事件或数据的变化。它可以用于各种用途，包括通知新消息的到来、实时更新股票价格、告知特定事件状态的变化等。事件推送提供了实时性和主动性，使客户端应用程序能够立即响应事件，而无需等待或频繁地查询服务器。这在实时互动应用、实时监控和通知等场景中特别有用。

总之，API请求是一种客户端主动请求数据或执行操作的方式，而事件推送是一种服务器主动通知客户端有关事件或数据变化的方式。它们各自适用于不同的场景和需求，API请求用于主动获取数据，而事件推送用于实时通知事件发生。

举个栗子🌰

当涉及事件推送与API请求的区别时，我们可以使用以下通俗的例子来帮助业务人员更好地理解：

简单来讲就是一个主动查询（API查询），一个被动的接收推送（事件推送）。就像你在淘宝买了个东西，主动查询（API）就是你点开淘宝找到订单查看最新状态，这个时候淘宝会实时调用API查询当前这个订单的状态展示给你看。事件推送就是当你的订单状态发生变更时，比如发货了，这个时候淘宝会给你发送一条消息提示你的XXX订单已经发货啦~

• API请求：图书馆书籍借阅

想象一下您需要借一本书，但这本书不在您手边。您需要亲自前往图书馆，查阅书目，找到所需的书籍，然后向图书管理员提交借书请求。您需要主动采取行动，前往图书馆，请求图书，等待书本准备好，然后再将其借走。这是一个需要主动请求和等待响应的过程，就像使用API请求一样。

• ** 事件推送：实时新闻订阅**

想象一下您正在使用一个实时新闻订阅应用程序，您已经选择了您感兴趣的新闻类别，如体育、科技和政治。每当发生与您所关注的类别相关的新闻时，应用程序会立刻向您推送通知。这就像您订阅了一个实时新闻服务，不需要主动去查看新闻，新闻会自动推送到您的手机上，让您随时了解最新动态。

通过这个例子，您可以更好地理解事件推送与API请求之间的区别。事件推送是数据主动推送给您，就像实时新闻通知，而API请求需要您主动请求数据，就像前往图书馆借书一样。事件推送提供了实时性和便捷性，而API请求需要您采取主动行动来获取所需的信息。

飞书API与事件集成案例

集成准备

1、通过飞书自建应用来对接飞书API数据，若未创建则参考：飞书API对接指南


API对接
在准备好应用后，我们就可以获取到API调用时所需要的一些参数信息App ID，App Secret。
API对接主要是通过主动发起API请求的方式，去操作（增删改查）飞书平台的数据

若需要对接飞书的相关接口，需要在开发者后台开通对应接口的权限。所以在进行接口对接前，请先确保您想要对接的接口权限为已开通状态。

接口权限的开通也会影响API的返回数据

事件订阅

事件订阅通常需要我们配置一个用于接收事件推送的地址（飞书这里叫请求地址），再订阅你想要的事件。比如说我在订阅了「部门新增事件」后，当有新的部门创建时，飞书就会向我们配置的地址发送新创建的部门的数据。当我们想增量的同步某些数据时，通常会采取这种方式

配置请求地址

事件推送主要分为两种：参考：事件订阅指南
1、明文推送 ：数据以明文的形式推送至配置的地址
2、加密推送 ：需配置Encrypt Key，数据先进行加密后，再推送至配置的地址。接收到的数据需根据配置的Encrypt Key解密成原始数据

请求地址验证
在配置请求地址时，飞书会向该地址发送一条验证请求，已验证地址的可行性。参考：请求地址验证

（1）明文推送

若未配置Encrypt Key，则采取明文推送，需正确响应收到的challenge，才算配置成功

webhook实现请求地址配置（明文）

1. 第一步，创建一个webhook，选择从请求示例中生成参数，同时勾选生成body全文参数。复制链接（下一步需要用到）

2. 将复制好的webhook URL，填入请求地址内点击保存，初始会提示"challenge code没有返回"，因为在保存时飞书会验证该地址可行性，向该地址发送验证请求（如上述说明），需要我们正确的返回challenge，这里暂时先不用管，我们来看第三步。
   

3. 现在我们会发现webhook页面已经根据飞书的验证请求生成好了参数列表，包含生成好的body全文参数，点击保存

4. 在webhook自定义响应中，拼接好需要返回的数据，并将webhook进行发布

5. 再回到飞书开发者后台，点击保存，即可配置成功
   

（2）密文推送

若已配置Encrypt Key，则采取密文推送，需将收到的加密字符串进行解密，再正确响应收到的challenge，才算配置成功

webhook实现请求地址配置（密文）

1. 第一步，创建一个webhook，选择从请求示例中生成参数，同时勾选生成body全文参数。复制链接（下一步需要用到）

2. 生成Encrypt Key或自定义填入，将复制好的webhook URL，填入请求地址内点击保存，初始会提示"challenge code没有返回"，因为在保存时飞书会验证该地址可行性，向该地址发送验证请求（如上述说明），需要我们正确的返回challenge，这里暂时先不用管，我们来看第三步。

3. 现在我们会发现webhook页面已经根据飞书的验证请求生成好了参数列表，包含生成好的body全文参数，点击保存

4. 添加代码块节点，对获取到的密文数据进行解密处理。测试时Encrypt填入上一步获取到的数据即可，key填入我们在第二步中配置的Encrypt Key

5. 在webhook自定义响应中，拼接好需要返回的数据，并将webhook进行发布
   

6. 再回到飞书开发者后台，点击保存，即可配置成功
   

添加事件

在飞书开发者后台，添加需要订阅的事件，这样在这些事件触发时，webhook就会收到对应的数据

判断事件类型

飞书上订阅的所有事件，都会向我们配置的地址推送，那么问题来了，我如何区分这些事件类型再做对应的业务处理呢？

可用通过header中的event_type来判断事件类型，再做对应的业务处理