Google Tasks API与Zapier集成：高级用户的公开API指南

每当表单提交时自动创建Google Tasks任务，当团队成员完成共享发布清单上的任务时发送Slack消息，或是每晚将逾期任务归档到电子表格，这些自动化需求现在都能实现。

Google Tasks确实提供了原生API，但存在明显局限：没有webhook机制意味着只能通过轮询检查任务状态，缺乏标签和分配人功能，且每次调用都需要繁琐的OAuth授权流程。

TasksBoard现推出基于Google Tasks数据的增强型REST API，包含个人API密钥、HMAC签名的webhook以及Zapier集成。本指南将详解功能特性、密钥获取方式、核心接口用法、webhook机制及适用场景。该API为团队版专属功能。

TasksBoard API的增强特性

该API完全兼容原生Google Tasks数据，所有列表和任务ID均与Google官方API保持一致，确保与其他工具的兼容性。在此基础之上新增：

• 标签与分配人：原生Google Tasks仅支持标题、备注和截止日期，TasksBoard将标签（首行）和分配人（格式👤 Assigned to <邮箱>）存储在备注字段中，API则以独立字段labels和assignee进行读写
• 看板管理：可视化配置各看板显示的列表
• 共享列表：标记列表共享状态，并捕获协作者的任务变更事件
• Webhook支持：支持task.created、task.updated、task.completed和task.deleted事件通知

基础地址：https://api.tasksboard.com/v1。响应数据包裹在data字段中，错误格式为{ "error": { "code", "message", "details" } }，其中code为固定错误码，422状态时details会标识无效字段。

创建API密钥

密钥与个人账户绑定，拥有该账户在Google Tasks中的所有权限：

1. 在TasksBoard中点击头像进入团队→API标签页（或直接访问/team?tab=api）
2. 创建密钥时选择是否开启写入权限（只读密钥会在所有写操作返回403）
3. 复制以tb_live_开头的密钥（仅显示一次）
4. 每次请求需携带Bearer Token：

curl https://api.tasksboard.com/v1/lists \
  -H "Authorization: Bearer tb_live_…"

密钥管理页面可随时查看权限范围、撤销密钥或管理webhook。如发生密钥泄露，应立即撤销并生成新密钥（即时生效）。

核心接口速览

主要接口概览（完整文档见API参考）：

账户

• GET /me：获取当前账户信息及密钥权限

任务列表

• GET /lists：获取所有列表（含shared共享状态和boardId看板ID）
• POST /lists：创建新列表（参数title）
• GET /lists/{listId}：获取单个列表详情

任务管理

• GET /lists/{listId}/tasks：默认获取未完成任务，可选参数：
  • status=completed/all
  • 时间筛选：updatedAfter、dueBefore、dueAfter
  • includeDeleted包含已删除任务
• POST /lists/{listId}/tasks：创建任务（支持parent子任务和previous排序）
• GET /tasks/{taskId}?listId=：获取单个任务（需指定listId）
• PATCH /tasks/{taskId}：部分更新（null可清空字段）
• POST /tasks/{taskId}/complete：标记任务完成
• DELETE /tasks/{taskId}?listId=：删除任务

看板配置

• GET /boards：获取所有看板及其包含的列表ID（主看板始终排在首位）

Webhook管理

• 支持GET/POST /webhooks及单条记录的增删改查

创建带标签和分配人的任务示例：

curl -X POST https://api.tasksboard.com/v1/lists/LIST_ID/tasks \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "发送Q3报告", "due": "2026-10-24",
       "labels": ["❗️重要"], "assignee": "bob@example.com"}'

分页请求可通过meta.nextCursor和cursor参数实现。

Webhook：实时获取任务变更

告别轮询！TasksBoard会在任务创建、更新、完成或删除时主动推送事件：

1. 注册webhook并订阅事件类型：

curl -X POST https://api.tasksboard.com/v1/webhooks \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/tasksboard",
       "events": ["task.created", "task.completed"]}'

2. 保存响应中的secret（仅返回一次，也可自定义）
3. 在10秒内返回2xx状态码确认接收

每次推送包含三个关键头信息：

• X-TasksBoard-Event：事件类型
• X-TasksBoard-Delivery：事件ID
• X-TasksBoard-Signature：签名验证

消息体包含完整任务数据(data.task)、时间戳(createdAt)和事件来源(source)：

• api：通过API直接触发
• sync：来自共享列表的同步变更
• poll：通过后台轮询发现（见下文）

签名验证机制

签名头格式为t=<时间戳>,v1=<签名>，其中签名是对"<时间戳>.<原始消息体>"的HMAC-SHA256计算结果。验证时需注意：

• 使用原始请求体（未经JSON解析）
• 拒绝时间戳偏差过大的请求（默认5分钟）

const crypto = require("crypto")

function verify(secret, rawBody, header, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(parts.v1, "hex"), Buffer.from(expected, "hex"))
}

重试与熔断机制

失败推送会自动重试3次（间隔逐步延长）。连续20次失败后webhook将自动禁用（active: false），需通过PATCH /webhooks/{id}手动激活。团队页面的API标签页会清晰标注每个webhook的状态（活跃/已禁用）。

非共享列表的轮询机制

Webhook事件有三种来源：

1. 直接API调用
2. 共享列表的同步变更
3. 后台轮询（需手动开启）

特别注意：在Gmail或Google Tasks应用中对非共享列表的修改，必须开启”每15分钟轮询我的列表”选项（位于API标签页）才能被捕获。这类事件会标记为source: "poll"。如果仅需监控共享列表变更，可关闭此选项以节省资源。

Zapier集成

无需编写代码也能实现自动化！TasksBoard的Zapier应用提供：

• 触发器：新任务、任务完成（基于updatedAfter参数的轮询机制）
• 动作：创建任务、标记完成、创建列表

当前Zapier应用正在发布流程中，正式上线后可直接在Zapier平台搜索TasksBoard并输入API密钥进行配置。在此之前，您仍可通过REST API和webhook实现相同功能。更多自动化方案可参考Google Tasks集成指南。

体验TasksBoard团队版

在原生Google Tasks基础上提供共享列表、角色权限、操作日志及带webhook的REST API，团队统一结算。

查看方案 →

适用场景

作为团队版专属功能，该API特别适合：

• 以共享列表为协同核心的团队：通过source: "sync"的webhook实时捕获任何协作者的任务状态变更，触发Slack通知或数据归档
• 需要跨系统对接的运营人员：表单系统/CRM/客服平台可直接创建带标签和分配人的任务，实时同步至相关人员看板
• 受限于原生API的开发者：免去OAuth配置烦恼，直接通过个人密钥实现完整功能

如需开发个人自动化脚本且已配置OAuth客户端，原生Google Tasks API仍是免费选择。单次数据导出可参考Google Tasks导出指南。

常见问题

总结

Google Tasks原生API缺乏webhook、标签和分配人功能，且配置复杂。TasksBoard API在保持Google原生ID体系的同时，提供：

• 分钟级配置的个人API密钥
• 完整的列表/任务/看板接口
• 可验证签名的webhook
• 非共享列表的可选轮询机制
• 即将上线的Zapier集成

立即在团队页面的API标签页创建密钥，通过API文档探索更多可能。