Automatisch 集成指南Google Tasks 触发器Triggers的轮询机制与工作流接入详解【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch导读本文以 Automatisch 开源自动化平台中的 Google Tasks 应用为切入点系统讲解其三大内置触发器——New completed tasks新完成任务、New task lists新任务列表与New tasks新任务的触发语义、参数配置与底层轮询实现。你将理解 Automatisch 基于轮询polling的触发器如何工作、pollInterval与internalId去重机制如何保证事件不重不漏并掌握如何在流程编辑器中把这些触发器接入实际工作流。文中所有实现细节均以当前仓库 packages/backend/src/apps/google-tasks 下的源码为事实依据可直接对照查阅。一、Google Tasks 触发器总览Automatisch 把 Google Tasks 定义为可通过 OAuth 建立连接supportsConnections: true的应用其入口文件 packages/backend/src/apps/google-tasks/index.js 将认证、操作、动态数据与触发器统一注册。触发器清单定义在 packages/backend/src/apps/google-tasks/triggers/index.js共注册三个触发器与文档 packages/docs/pages/apps/google-tasks/triggers.md 中的列表一一对应触发器名称触发时机需要配置的参数New completed tasks指定任务列表中有任务被标记为完成Task List任务列表下拉框New task lists创建了新的任务列表无New tasks指定任务列表中创建了新任务Task List任务列表下拉框三个触发器全部通过 Google Tasks API 的轮询接口获取数据不会因为 Google Tasks 本身不提供 Webhook 而受限——这正是 Automatisch 这类自动化平台处理无 Webhook 服务时的标准做法。二、触发器的核心概念轮询 去重在深入三个触发器之前先理解 Automatisch 轮询型触发器的两个底层机制这决定了后续所有代码行为的含义。2.1 pollInterval轮询间隔每个触发器定义中的pollInterval字段指定了轮询频率单位为分钟。Google Tasks 的三个触发器统一设置为pollInterval: 15即每 15 分钟向 Google Tasks API 拉取一次最新数据。Automatisch 通过 packages/backend/src/helpers/define-trigger.js 校验触发器定义的合法性只要触发器带有pollInterval或声明为type: webhook就会被判定为合法触发器否则抛出异常。Google Tasks 属于典型的带pollInterval的轮询型触发器其run函数会由执行引擎周期性调用。2.2 internalId事件去重的关键轮询型触发器的核心难点是“同一事件被重复拉取”。Automatisch 的解决办法是每个触发项trigger item携带一个internalId执行引擎依据internalId判断某条记录是否已处理过已处理的不再触发从而保证工作流不会对同一条任务重复执行。这也是为什么下面三个触发器的实现中都有meta: { internalId: task.id }这样的代码——Google Tasks 返回的记录本身带有稳定唯一的id字段天然适合作为去重依据。三、触发器一New tasks新任务3.1 触发语义与参数配置当你在指定任务列表中创建了一条新任务时触发。源码位于 packages/backend/src/apps/google-tasks/triggers/new-tasks/index.js。它要求一个必填参数Task List用于限定监听哪个任务列表arguments: [ { label: Task List, key: taskListId, type: dropdown, required: true, description: , variables: true, source: { type: query, name: getDynamicData, arguments: [ { name: key, value: listTaskLists, }, ], }, }, ],参数说明type: dropdown以下拉框形式选择required: true必填未选择任务列表无法保存该步骤variables: true允许在后续步骤中把该参数值作为变量引用source声明下拉选项来自动态数据查询listTaskLists即实时调用 Google Tasks API 拉取当前账号的任务列表。3.2 运行逻辑分页拉取 推送run函数的实现如下async run($) { const taskListId $.step.parameters.taskListId; const params { maxResults: 100, pageToken: undefined, }; do { const { data } await $.http.get(/tasks/v1/lists/${taskListId}/tasks); params.pageToken data.nextPageToken; if (data.items?.length) { for (const task of data.items) { $.pushTriggerItem({ raw: task, meta: { internalId: task.id, }, }); } } } while (params.pageToken); },这段代码有四个值得注意的实现要点每页 100 条maxResults: 100控制单次请求返回上限降低大列表下的请求次数自动分页请求完成后读取响应的nextPageToken并继续下一页直到没有下一页为止do...while循环确保一个轮询周期内拉全所有增量逐条推送对每一页中的每条任务调用$.pushTriggerItem推送给执行引擎去重元数据internalId使用 Google Tasks 记录自身的id引擎据此过滤已处理事件。调用的是GET https://tasks.googleapis.com/tasks/v1/lists/{taskListId}/tasks接口其中apiBaseUrl定义在应用入口packages/backend/src/apps/google-tasks/index.js#L12 中apiBaseUrl: https://tasks.googleapis.com$.http会自动拼接基础路径。四、触发器二New completed tasks新完成任务4.1 触发语义当指定任务列表中的某个任务状态变为已完成时触发源码位于 packages/backend/src/apps/google-tasks/triggers/new-completed-tasks/index.js。它同样接收必填的 Task List 下拉参数参数定义与 New tasks 触发器完全一致同样使用listTaskLists动态数据源。4.2 实现差异如何筛选“已完成”与 New tasks 最大的区别在run函数的查询参数与过滤逻辑const params { maxResults: 100, showCompleted: true, showHidden: true, pageToken: undefined, }; do { const { data } await $.http.get(/tasks/v1/lists/${taskListId}/tasks, { params, }); params.pageToken data.nextPageToken; if (data.items?.length) { for (const task of data.items) { if (task.status completed) { $.pushTriggerItem({ raw: task, meta: { internalId: task.id, }, }); } } } } while (params.pageToken);两个关键点showCompleted: true请求时明确要求 API 返回已完成的任务否则 Google Tasks API 默认只返回未完成任务showHidden: true连带返回被隐藏的任务避免漏掉被归档或隐藏的已完成项客户端二次过滤仅当task.status completed时才推送给引擎而不是把列表里所有任务都推送。这种“接口拉取 代码过滤”的双保险确保只有真正完成的任务才会触发工作流。去重逻辑与 New tasks 相同internalId取task.id因此一条任务即使多次出现在轮询结果中也只会触发一次。五、触发器三New task lists新任务列表5.1 触发语义当账号下创建了新的任务列表时触发源码位于 packages/backend/src/apps/google-tasks/triggers/new-task-lists/index.js。它是三个触发器中唯一不需要任何参数的——监听范围是账号下的全部任务列表因此没有 Task List 下拉框。5.2 实现细节接口与排序async run($) { const params { maxResults: 100, pageToken: undefined, }; do { const { data } await $.http.get(/tasks/v1/users/me/lists); params.pageToken data.nextPageToken; if (data.items?.length) { for (const taskList of data.items.reverse()) { $.pushTriggerItem({ raw: taskList, meta: { internalId: taskList.id, }, }); } } } while (params.pageToken); },需要注意的实现细节调用的是GET /tasks/v1/users/me/lists即当前用户me的全部任务列表与另外两个触发器不同这里对data.items执行了.reverse()再逐条推送。从实现意图看Google Tasks API 返回的列表按创建时间正序排列reverse()用于把最早的数据放在最后处理配合internalId去重有助于让新创建的任务列表在首轮轮询时被正确识别为“新事件”去重依旧使用taskList.id作为internalId。六、支撑机制动态数据与认证6.1 任务列表下拉框的数据来源New tasks 与 New completed tasks 的参数下拉选项来自动态数据端点listTaskLists实现在 packages/backend/src/apps/google-tasks/dynamic-data/list-task-lists/index.js。它同样按 100 条一页循环调用/tasks/v1/users/me/lists把每条任务列表映射为{ value: taskList.id, name: taskList.title }供下拉框展示taskLists.data.push({ value: taskList.id, name: taskList.title, });value是传给触发器taskListId参数的实际值name是用户在下拉框中看到的任务列表标题。6.2 触发 Google Tasks API 所需的 OAuth 授权要使用这三个触发器必须先通过 Google Tasks 连接配置 建立 OAuth 连接。认证作用域定义在 packages/backend/src/apps/google-tasks/common/auth-scope.jsconst authScope [ https://www.googleapis.com/auth/tasks, https://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile, ];其中tasks作用域用于读写任务数据两个userinfo作用域配合 People API 获取当前用户信息见 packages/backend/src/apps/google-tasks/common/get-current-user.js请求people.googleapis.com/v1/people/me。这也解释了为何连接配置文档要求同时启用Google Tasks API和People API——前者是触发器轮询的数据源后者用于身份信息校验。每次请求前应用通过beforeRequest: [addAuthHeader]见 packages/backend/src/apps/google-tasks/common/add-auth-header.js自动注入访问令牌触发器的run函数无需关心鉴权细节。访问令牌过期后由 packages/backend/src/apps/google-tasks/auth/refresh-token.js 自动刷新轮询过程对用户完全透明。七、在流程中接入 Google Tasks 触发器的实战步骤结合上述机制在 Automatisch 流程编辑器中使用这三个触发器的完整路径如下建立连接按 连接配置文档 在 Google Cloud Console 创建项目、启用Google Tasks API与People API、配置 OAuth 同意屏幕与 Web 应用客户端把 Automatisch 提供的OAuth Redirect URL填入授权回调地址再将 Client ID 与 Client Secret 填入 Automatisch 完成授权新建流程并选择触发器在流程编辑器中添加步骤选择 Google Tasks 应用从 New tasks / New completed tasks / New task lists 中选择一个作为触发步骤配置参数选择New tasks或New completed tasks时从动态下拉框中选择要监听的任务列表选择New task lists时无需任何参数设置后续动作把触发项中的数据如任务标题title、任务状态status、任务 IDid通过变量映射到后续步骤例如发送通知、写回其他应用、更新数据库记录保存并发布此后执行引擎会每 15 分钟轮询一次借助internalId去重只有真正新增或新完成的任务才会触发后续流程。一个典型的落地场景用New completed tasks监听“产品反馈”任务列表任务完成时自动把结果同步到团队通讯工具或通知渠道或用New tasks监听某个任务列表新任务产生时自动创建对应的工单或提醒。八、总结Automatisch 对 Google Tasks 的三个触发器给出了完整而简洁的轮询实现统一的 15 分钟轮询间隔、100 条/页的分页拉取、internalId去重、动态任务列表参数以及 OAuth 令牌自动注入与刷新。其设计思路可以复用到任何不支持 Webhook 的第三方服务上——这正是 define-trigger.js 允许“pollInterval 或 webhook 二选一”的通用约定。对照 触发器文档 与 触发器源码目录 阅读即可完整还原从“界面上的一个触发器选项”到“API 轮询与去重逻辑”的全链路实现。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考