Skip to main content

对接飞书 Lark 审批流程

本文档介绍如何在 NineData 中对接 国际版 Lark 外部审批流程，并把 SQL 任务、权限申请、数据导出等流程接入 Lark 审批。

您可以按照“创建并发布 Lark 应用、在 NineData 中绑定外部审批渠道、配置回调事件、准备审批定义、创建映射定义、绑定到具体审批流程”的顺序完成接入。

前提条件​

  • 已创建或加入组织，并且该组织已开通数据库 DevOps 企业版，同时请确保您的包年包月订阅未过期。
  • 当前账号已切换到目标组织。更多信息，请参见切换到组织。
  • 已通过目标组织的 Lark 管理员或应用管理员权限账号登录 Lark Developer。
  • 已通过 系统管理员 权限账号登录 NineData。
  • 已确认当前操作的 NineData 组织为 玖章测试。

注意事项​

  • 国际版 Lark 请使用 Lark Developer，不要使用飞书中国版开放平台替代。
  • NineData 中的 飞书 与 飞书 Lark 是两条不同的外部审批渠道，请不要混用。
  • 如果勾选 自动初始化审批定义 后没有生成可用模板，建议改为手动创建 Lark 审批定义，再回到 NineData 中创建映射定义。
  • 审批定义 ID 需要来自当前 Lark 应用，请不要直接复用其他应用下已有的审批定义 ID。

步骤一：在 Lark 创建并发布审批应用​

  1. 访问 Lark Developer，登录目标 Lark 账号。

  2. 创建一个新的企业自建应用，或打开已有应用。

  3. 在 凭证与基础信息 页面，记录 App ID 和 App Secret。

    lark_approval_app_credentials_20260318

  4. 在 权限管理 中开通审批相关权限。为了和 NineData 的现有对接逻辑保持一致，建议至少确认以下权限已经开通：

    • 应用身份权限：approval:approval
    • 应用身份权限：approval:approval:readonly
    • 应用身份权限：approval:definition
    • 应用身份权限：contact:user.id:readonly

    如果您的页面支持用户身份权限，建议同时开通对应的用户身份权限。

  5. 在 版本管理与发布 中创建版本并发布。

步骤二：在 NineData 绑定飞书 Lark 审批渠道​

  1. 登录 NineData 控制台。

  2. 在左侧导航栏，依次单击：

    • 数据库 DevOps
    • 规范与流程
    • 审批流程
    • 外部流程渠道

  3. 在右侧弹出的 外部渠道管理 面板中，确认当前存在 飞书、飞书 Lark、IT服务平台 三张卡片。

    lark_approval_channel_cards_20260318

  4. 在 飞书 Lark 卡片下单击 立即配置。

  5. 在弹窗中填写以下信息：

    参数说明
    AppID填写步骤一中记录的 Lark App ID。
    AppSecret填写步骤一中记录的 Lark App Secret。
    自动初始化审批定义建议按当前组织的接入方式选择。如未生成可用模板，可先不勾选，后续改为手动创建审批定义并完成映射。

  6. 单击 确定 保存配置。

  7. 保存成功后，再次打开该应用详情，记录页面中的 回调地址。

    回调地址格式如下：

    https://console.ninedata.cloud/api/inner/external/approval/callback/<orgId>?token=<token>

步骤三：在 Lark 配置事件与回调​

  1. 回到 Lark Developer，打开同一个 Lark 应用。

  2. 在左侧导航栏，单击 事件与回调。

  3. 在 事件配置 中，将订阅方式设置为将事件发送至开发者服务器，然后把步骤二中记录的 回调地址填入请求地址。

  4. 保存后，在 已添加事件 中单击 添加事件。

  5. 搜索并添加 审批实例状态变更 事件。

  6. 保存配置。

步骤四：在 Lark 准备可用于映射的审批定义​

如果未通过自动初始化拿到可用模板，可以手动准备一个 Lark 自己的审批定义。

  1. 访问 Lark 审批管理后台。

  2. 创建一个新的自定义审批。

  3. 为了让 NineData 更容易完成字段映射，建议优先使用以下控件：

    • 单行文本
    • 多行文本
    • 单选

  4. 发布审批定义后，记录该审批定义的 审批定义 ID。

    tip

    不要直接复用其他应用（例如飞书渠道）下已有的审批定义 ID。
    如果审批定义 ID 不属于当前应用，NineData 可能返回类似如下错误：

    nd.sql.external.approval.template.not.found

    出现该错误时，请为当前 Lark 应用重新准备审批定义，并重新填写审批定义 ID。

步骤五：在 NineData 创建审批流程映射定义​

  1. 回到 NineData 的 外部流程渠道 面板。

  2. 单击顶部页签 审批流程映射定义。

    lark_approval_mapping_tab_20260318

  3. 单击 添加审批流程定义。

  4. 在弹出的 创建审批流程定义 窗口中，完成以下配置：

    参数说明
    关联应用选择刚刚绑定成功的 飞书 Lark审批-cli_a93939bba438de17。
    名称自定义映射定义名称，例如：Lark审批映射测试-20260318。
    审批定义ID填写步骤四中准备好的 Lark 审批定义 ID。

  5. 正常情况下，系统会在填写 审批定义ID 后自动拉取 审批定义字段。

  6. 如果字段被成功拉出，再根据实际控件完成 平台字段 与 参数映射 的绑定。

步骤六：把映射定义绑定到具体审批流程​

  1. 登录 NineData 控制台。

  2. 在左侧导航栏，依次单击：

    • 数据库 DevOps
    • 规范与流程
    • 审批流程

  3. 在目标流程所在页面中，选择需要启用外部审批的环境或流程，单击其右侧 编辑。

  4. 勾选 启用外部审批流程。

  5. 在外部审批配置中：

    • 左侧选择刚刚绑定的 飞书 Lark 应用
    • 右侧选择步骤五中创建好的 审批流程映射定义

  6. 保存配置。

常见问题​

1. 勾选“自动初始化审批定义”后提示“未找到可用的审批模版”​

这是本次实测中稳定复现的问题。建议处理方式：

  • 先不要勾选“自动初始化审批定义”
  • 先完成渠道绑定、回调地址和事件配置
  • 再按步骤四和步骤五手动创建审批定义与映射定义

2. 在“审批流程映射定义”里填入审批定义 ID 后，字段没有被拉出​

本次实测中，当使用旧飞书审批定义 ID F34A2338-D184-45D8-83B7-DD2BC250B257 时，NineData 调用：

POST /api/external/approval/template/form

返回：

nd.sql.external.approval.template.not.found

这说明该审批定义并不属于当前 Lark 应用，不能直接复用。请重新在 Lark 审批管理后台 下，为当前 Lark 应用准备一个可用的审批定义，再重新填写。

3. 映射定义弹窗里明明填了值，还是显示“暂无数据”​

请依次检查：

  • 关联应用 是否已选到 飞书 Lark 应用，而不是飞书应用
  • 审批定义ID 是否来自当前 Lark 应用
  • Lark 侧是否已完成 事件与回调 配置
  • Lark 应用是否已经发布
Last updated on