Automatisch 集成 Changedetection：创建与删除 Watch 的 Action 配置与源码解析
【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch
本篇技术指南聚焦 Automatisch 开源自动化平台中 Changedetection 集成模块的 Action 能力：围绕官方文档定义的Create a watch（创建监控）与Delete a watch（删除监控）两个操作，结合后端源码逐一还原其字段配置、API 调用链与返回数据格式，并顺带梳理连接认证与触发器机制。读完本文，你将掌握如何在 Automatisch 中为任意网站 URL 建立/移除变更检测 Watch，理解其底层如何与 Changedetection 的 REST API 交互，从而在业务流程中正确编排页面变更监控。
一、模块总览：Changedetection 在 Automatisch 中的定位
Changedetection.io 是一款自托管/云托管的"网页变更检测"服务，可周期性地抓取指定网页并在内容发生变化时给出通知。Automatisch 将其封装为独立 app 集成，模块入口定义在 packages/backend/src/apps/changedetection/index.js：
export default defineApp({ name: 'Changedetection', key: 'changedetection', iconUrl: '{BASE_URL}/apps/changedetection/assets/favicon.svg', authDocUrl: '{DOCS_URL}/apps/changedetection/connection', supportsConnections: true, baseUrl: 'https://changedetection.io', primaryColor: '#3056d3', beforeRequest: [setBaseUrl, addAuthHeader], auth, actions, dynamicData, triggers, });从该定义可以确认以下关键事实：
- 连接类型：
supportsConnections: true，所有 Action 必须先建立 Changedetection 连接（Connection）才能使用； - 官方默认服务：
baseUrl指向https://changedetection.io，但连接配置允许填写自定义Instance URL，因此也兼容自部署实例； - 请求预处理：
beforeRequest注册了setBaseUrl与addAuthHeader两个拦截器，负责拼接 API 地址与注入密钥，所有 Action/Trigger 的 HTTP 请求都会自动经过这两步； - 能力组成：
actions（2 个）、dynamicData（下拉数据源）、triggers（1 个）。
本模块共有 3 份文档页面：actions.md（本文主体）、connection.md（连接配置）、triggers.md（触发器），分别对应用户视角的三种交互形态。
二、Action 清单：官方文档定义的两大操作
官方文档 packages/docs/pages/apps/changedetection/actions.md 采用清单式结构（frontmatter + 动态组件渲染），明确定义了模块提供的全部 Action：
| Action 名称 | 说明 |
|---|---|
| Create a watch | Creates a new change detection watch for a specific website.（为指定网站创建新的变更检测 Watch） |
| Delete a watch | Deletes a change detection watch.（删除一个变更检测 Watch） |
两个 Action 分别对应源码 create-watch/index.js 与 delete-watch/index.js。下文逐一对它们的字段、执行逻辑与返回结果做深度展开。
三、Action 一：Create a watch（创建监控）
3.1 字段配置
由 create-watch/index.js 可知，该 Action 仅需一个必填参数：
| 配置项 | 键（key） | 类型 | 必填 | 变量支持 | 说明 |
|---|---|---|---|---|---|
| URL | url | string | 是 | 是 | 想要监控的网页地址（URL you want to monitor） |
type: 'string'表示编辑器渲染为单行文本框；variables: true表示该字段可以插入上游步骤的输出变量（例如用表单提交的链接、邮件正文中提取的 URL 作为监控目标），这使该 Action 很容易嵌入"收到新数据 → 自动开始监控"这类动态流程。
3.2 执行逻辑与 API 调用
async run($) { const url = $.step.parameters.url; const body = { url, }; const response = await $.http.post('/v1/watch', body); $.setActionItem({ raw: response.data }); }执行流程分为三步：
- 取值：从
$.step.parameters.url读取用户在流程编辑器中填写的 URL； - 请求：向
/v1/watch发送POST请求，请求体为{ url }。注意此处路径是相对路径，实际完整地址由beforeRequest中的setBaseUrl拦截器在请求发出前拼接而成； - 输出：通过
$.setActionItem({ raw: response.data })将 Changedetection 返回的完整响应体作为本步骤输出，供后续步骤引用。
3.3 底层请求构造：baseURL 与鉴权头
该 Action 之所以只写相对路径即可工作，是因为模块在beforeRequest中注册了两个拦截器：
- set-base-url.js：
import { URL } from 'node:url'; const setBaseUrl = ($, requestConfig) => { requestConfig.baseURL = new URL('/api', $.auth.data.instanceUrl).toString(); return requestConfig; };它将baseURL动态设置为Instance URL + /api。因此连接时填写的 Instance URL 形如https://changedetection.io时，Action 实际请求的完整地址为https://changedetection.io/api/v1/watch。这一设计同时兼容官方云服务和用户自部署的 Changedetection 实例——只需在连接时把 Instance URL 指到自己的服务即可。
- add-auth-header.js：
const addAuthHeader = ($, requestConfig) => { requestConfig.headers['x-api-key'] = $.auth.data.apiKey; return requestConfig; };它为每个请求附加x-api-key头，值来自连接中保存的 API Key。这是 Changedetection 官方 API 的标准鉴权方式，Automatisch 在每次调用前自动注入，使用者无需在 Action 中手动维护凭证。
3.4 输出与后续使用
response.data直接透传 Changedetection 的响应，通常包含新创建 Watch 的 ID、URL、创建时间等字段。典型用法是：将响应中的 Watch ID 存入数据存储（datastore）或作为变量传给后续步骤——例如下一步立即执行"Delete a watch"或让"Changed watch"触发器监听该 ID。
四、Action 二：Delete a watch（删除监控）
4.1 字段配置
由 delete-watch/index.js 可知，删除操作同样只有一个必填参数：
| 配置项 | 键（key） | 类型 | 必填 | 变量支持 | 说明 |
|---|---|---|---|---|---|
| Watch ID | watchId | string | 是 | 是 | 想要删除的 Watch ID（Watch ID you want to delete） |
watchId支持变量注入，因此常与 Create a watch 或"Changed watch"触发器配合，实现"监控任务完成/不再需要 → 自动删除监控"的闭环。
4.2 执行逻辑与 API 调用
async run($) { const watchId = $.step.parameters.watchId; await $.http.delete(`/v1/watch/${watchId}`); $.setActionItem({ raw: { result: 'successful', }, }); }执行流程：
- 取值：读取
$.step.parameters.watchId； - 请求：向
/v1/watch/{watchId}发送DELETE请求（同样经过 baseURL 拼接与x-api-key注入）； - 输出：与 Create 不同，Delete 不依赖服务端响应体，而是固定输出
{ result: 'successful' }作为 Action Item。后续步骤可以据此判断删除操作已成功执行。
五、配套机制：连接认证与"Changed watch"触发器
虽然本文主体是 Action，但两个 Action 的实际可用性高度依赖连接认证与触发器配合，这里一并给出源码层面的佐证。
5.1 连接（Connection）配置
官方文档 connection.md 给出了建立连接的标准步骤：
- 进入你的 Changedetection 管理后台；
- 点击Settings按钮；
- 切换到API标签页；
- 将页面上的API key复制到 Automatisch 的
API Key字段； - 在 Automatisch 的Instance URL字段填入你的实例地址；
- 填写一个展示用的屏幕名称（Screen Name）；
- 保存后即可开始使用 Changedetection 连接。
对应的字段定义位于 auth/index.js，共三个必填项：screenName（UI 展示名称）、instanceUrl（实例地址）、apiKey（API 密钥）。
连接建立时会触发凭证校验，见 verify-credentials.js：
const verifyCredentials = async ($) => { await $.http.get('/v1/systeminfo'); await $.auth.set({ screenName: $.auth.data.screenName, apiKey: $.auth.data.apiKey, }); };即保存连接前，Automatisch 会调用一次GET /api/v1/systeminfo验证 API Key 与 Instance URL 是否有效（请求同样自动携带x-api-key头），校验通过后才正式存储连接。这解释了为什么文档要求必须先在 Changedetection 后台开启 API Key——没有合法密钥，连接无法建立，后续 Action 自然无从执行。
5.2 "Changed watch"触发器（配套能力）
triggers.md 定义了唯一触发器Changed watch（当检测到任何变更时触发），源码位于 changed-watch/index.js：
- 轮询间隔：
pollInterval: 15，即每 15 秒轮询一次； - 参数：
watchId，以下拉框形式从动态数据源选择（source指向listWatches）； - 执行逻辑：
GET /v1/watch/{watchId}获取 Watch 状态，若响应非空则推送触发项，并以${watchId}-${data.last_changed}作为去重internalId——当last_changed时间戳变化时才会再次触发，实现"仅内容变更才触发"。
Watch 下拉框的数据来自 dynamic-data/list-watches/index.js：它调用GET /v1/watch拉取全部 Watch，遍历响应对象将watchId映射为下拉选项的 value、watchData.url作为展示名称。因此，在流程编辑器中，用户可以直接从下拉列表挑选要监听的 Watch，而无需手抄 ID。
这一触发器与两个 Action 形成了完整闭环：Create a watch创建监控 →Changed watch在页面变动时触发后续通知/处理 →Delete a watch在任务完成后清理监控资源。
六、实战编排建议
基于以上源码证据，可以给出两种贴合实际场景的编排方式（均为 Automatisch 流程设计器内的配置思路）：
- 动态监控链路：某表单/邮件触发流程 → 提取 URL 变量 → 使用Create a watch创建监控（URL 字段勾选变量）→ 用Changed watch触发器监听该 Watch，并在内容变化时执行通知（如发送邮件、推送 Slack/Telegram 消息）。此链路依赖
url与watchId的变量透传能力。 - 监控生命周期管理：将Delete a watch挂在业务流程的收尾步骤，
Watch ID引用上游步骤（如 Create a watch 的输出或数据存储中的值），实现自动化清理，避免 Watch 无限堆积、消耗 Changedetection 配额。
七、总结
Automatisch 的 Changedetection 集成以官方文档定义的Create a watch、Delete a watch两个 Action 为核心，分别对应POST /api/v1/watch与DELETE /api/v1/watch/{watchId}两个底层 API 调用；配合连接时的/v1/systeminfo凭证校验、"Changed watch"轮询触发器与 Watch 下拉动态数据源，构成了从创建、监听、通知到删除的完整网页变更检测自动化闭环。两个 Action 的入参均支持变量注入，非常适合嵌入"数据驱动 → 自动监控 → 变更通知"的真实业务场景。
【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
