Skip to content

步骤二:添加事件

添加所需订阅的事件后,当事件发生时,开放平台会向应用推送事件信息,以便应用快速响应事件。

前提条件

在添加事件之前,需要先配置订阅方式

事件版本

飞书开放平台提供的事件包括 v2.0 和 v1.0 两个版本,v2.0 版本的事件设置更全面、更合理。如果同时订阅不同版本的同一事件,会导致应用收到重复的事件,因此建议应用仅订阅 v2.0 版本的事件,取消订阅 v1.0 版本的事件。不同版本的事件结构说明参考事件结构

image.png

订阅身份

为了提升开放能力的安全性,飞书开放平台设计了访问凭证(access_token)机制,调用 API 获取应用资源时,需要通过 access_token 对调用者身份进行鉴权,即告知飞书当前是谁、以什么身份获取什么租户的数据。关于如何选择和获取不同类型 access token,参考 获取访问凭证。相应在添加事件时,也需要依赖访问凭证机制,使用不同的身份订阅事件。

订阅身份介绍:

订阅身份类型描述场景示例
应用身份订阅tenant_access_token 订阅事件,不需要用户登录,直接以应用身份获取事件数据,可获取的数据范围由应用自身的数据权限范围决定。假设有一个应用名为 “My bot”,该应用 订阅云文档事件 时,如果以 tenant_access_token 订阅,则仅能订阅 “My bot” 作为拥有者或者管理员的文档变更,无法感知其他文档变更。
用户身份订阅user_access_token 订阅事件,需要用户登录并授权应用,可获取的事件数据由用户本人可见的数据权限范围决定。假设有一个应用名为 “My bot”,该应用 订阅云文档事件 时,如果以 user_access_token 订阅,该 token 代表的用户是 “李健”,则仅能订阅 “李健” 作为拥有者或者管理员的文档变更,无法感知其他文档变更。

大多数事件均需要使用应用身份订阅,需要使用用户身份订阅的场景说明如下:

  • 云文档:该业务的事件支持通过应用身份或用户身份订阅,你需要根据实际场景选择适配的身份订阅。
  • 日历:该业务的事件只支持通过用户身份订阅。
  • 邮箱:该业务的事件只支持通过用户身份订阅(邮箱的事件订阅功能正在内测中,若无法使用请耐心等待)。

操作步骤

  1. 进入开发者后台

  2. 在应用列表中,点击指定应用,进入应用详情页。

  3. 进入 事件与回调 > 事件配置 页面,在 已添加事件 区域,点击 添加事件

    image.png

  4. 添加事件 对话框,选择 应用身份订阅 或者 用户身份订阅

  5. 勾选需要订阅的事件后,点击 确认添加

    • 点击 确认开通权限,可一键开通事件所需的权限。

    • 若选择 暂不开通,可以返回 事件配置 页签后,在 已添加事件 区域,点击事件所需的权限,并点击 开通权限image.png

  6. 发布应用。

    WARNING

    即使已经开通相关权限(已审批通过或申请了免审权限),在填写事件订阅方式并添加事件后,也需要发布应用才能使配置生效。

    1. 在左侧导航栏选择 应用发布 > 版本管理与发布,并在页面右上角点击 创建版本

    2. 版本详情 页面,根据实际需要完成应用版本号、默认能力、更新说明以及可用范围等配置项。

    3. 在页面底部点击 保存,并在弹出的对话框中点击申请线上发布

      成功发起申请后,你需要等待企业管理员完成应用审核。待审核通过后应用会自动发布,此时事件订阅相关配置才会生效。

内容来源:飞书开放平台 · 自动爬取整理