跳到主要内容

Zapier

Zapier 上官方的 B1.church 应用程序,让 Zap 能够响应教会中的事件(新增人员、新奉献、新小组成员等),并将记录写回 B1。无需编写代码,也无需任何基础设施——只需在 Zapier 的拖放式编辑器中完成设置,粘贴 API 密钥,然后开启 Zap 即可。

等待 Zapier 审核

B1.church 应用程序已建置完成并可正常运作,但仍在等待 Zapier 的审核,才会公开出现在 Zap 编辑器的应用程序目录中。在获得批准之前,只有受邀的账户可以使用。以下内容说明的是获批后的运作方式。

开始之前

  • 一个 Zapier 账户(免费方案即可应付少量的 Zap)
  • 一位在 B1Admin 中具有 Edit Settings 权限的教会管理员(你需要建立 API 密钥)
  • 对你想做的事情有一个构想,例如"当 B1 中新增人员时,将其加入我的 Mailchimp 名单"

触发器与操作​

类型内容B1 事件/端点
TriggerNew Personperson.created
TriggerUpdated Personperson.updated
TriggerNew Donationdonation.created
TriggerNew Group Membergroup.member.added
TriggerNew Form Submissionform.submission.created
ActionCreate Person新增一位人员
ActionAdd Donation记录一笔奉献
ActionAdd Group Member将人员加入小组
ActionFind Person依 ID、电子邮件或姓名查找人员;若无人符合则任务失败

这些触发器与操作可以自由搭配 Zapier 支持的 7,000 多个应用程序使用。

设置​

1. 建立 B1 API 密钥​

  1. 在 B1Admin 中前往 Settings → Developer → API Keys。
  2. 点击 New API Key,为其命名(例如"Zapier"),并选择 Zap 所需的权限范围。
  3. 重要:务必包含 settings:write 权限范围。连接时,Zapier 会将密钥与 B1 的 webhook 清单进行核对;开启 Zap 时,B1 触发器也会代你注册 webhook——两者都需要 settings:write。没有此权限的密钥即使你的 Zap 只使用 B1 操作,连接测试也会失败。
  4. 同时授予操作所需的权限范围——例如"Add Donation"操作需要 donations:write,"Create Person"需要 people:write。
  5. 保存。完整的 cak_… 密钥只会显示一次——请务必复制。

2. 将 Zapier 连接到 B1​

  1. 在 Zapier 中建立新的 Zap。
  2. 第一次选择 B1 的触发器或操作时,Zapier 会要求你登录 B1.church。
  3. 将第 1 步的 API 密钥粘贴到 API Key 中(API URL 留空),然后点击 Yes, Continue。Zapier 会向你的教会验证该密钥。

该连接会保存在 Zapier 中,并可供你账户下的每个 Zap 重复使用。

3. 建立 Zap​

选择一个触发器,然后加入一个或多个操作步骤。以下为范例。

常见范例​

将 B1 的新人员加入 Mailchimp​

  • 触发器——B1:New Person
  • 操作——Mailchimp:Add/Update Subscriber。将 B1 的 name__first、name__last、contactInfo__email 分别对应到 Mailchimp 的 First Name/Last Name/Email 栏位。

以比内置连接器更丰富的卡片格式,将奉献发布到 Slack 频道​

  • 触发器——B1:New Donation
  • 操作——Slack:Send Channel Message。可编排任何版面——按钮、附件等——这些是内置的 Slack 连接器无法做到的。

将新的小组成员加入 Google 群组​

  • 触发器——B1:New Group Member
  • 操作——Filter by Zapier:仅当触发器中的 groupId 是你关注的 B1 小组时才继续
  • 操作——B1:Find Person(使用触发器中的 personId 取得电子邮件)
  • 操作——Google Groups:Add Member

将表单提交转寄到专案追踪工具​

  • 触发器——B1:New Form Submission
  • 操作——Notion/Linear/Asana/Trello:Create page/issue/task

触发器的底层运作方式​

触发器采用 REST hook,而非轮询——Zapier 不会每 15 分钟就去询问 B1 一次。开启 Zap 时,Zapier 会要求 B1 注册一个指向 Zapier 私有网址的 webhook;事件发生时,B1 会将数据包 POST 到 Zapier,你的 Zap 会在数秒内启动。关闭 Zap 时,Zapier 会要求 B1 删除该 webhook——不会留下任何孤立的订阅。

这表示触发器只会针对 Zap 开启之后发生的事件触发。没有回溯补发的机制——开启 Zap 并不会重新执行昨天的奉献。

限制与注意事项​

  • 同一个触发器的多个 Zap各自会注册自己的 B1 webhook——不会产生冲突,但若你在检视 Settings → Developer → Webhooks 时看到三个相同的 Zapier — donation.created 项目,请不必惊讶。
  • Zap 设置中的测试资料——建立 Zap 时,Zapier 会要求示例资料以对应栏位。如果 B1 中有最近符合条件的事件,它会拉取最新的一笔;否则会使用应用程序定义中的模拟示例。
  • 操作失败会以 Zap 错误的形式显示在 Zapier 的任务记录中。常见原因是 API 密钥缺少正确的权限范围(例如 "Add Donation" 操作需要 donations:write)。请以正确的权限范围重新建立密钥,并在 Zapier 中重新连接。
  • 外发 API 调用配额——操作所进行的每一次 B1 API 调用,都会计入你的 Zapier 任务配额,而不会计入 B1 这一端的任何用量。

故障排除​

  • 连接时出现"Authentication failed"——API 密钥有误、已被删除,或缺少 settings:write。请在 B1Admin 中建立包含 settings:write 以及 Zap 所涉及资源权限范围的新密钥(权限范围无法在现有密钥上更改),然后更新连接。
  • 触发器从未启动——请确认 webhook 确实已注册:在 B1Admin 的 Settings → Developer → Webhooks 中,现在应该会出现一行名为"Zapier — <event>"的项目。如果没有,很可能是你开启 Zap 时该 API 密钥缺少 settings:write。请修正密钥,然后将 Zap 关闭再重新开启。
  • 触发器重复启动两次——如果 Zapier 未收到确认回应,偶尔会重新传送。如果你需要严格的去重,请在唯一 ID(例如人员的 id)上加入 "Filter by Zapier" 步骤。

另见​