Automatisch 集成开发指南为你的第一个 App 接入认证Auth能力【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本指南是 Automatisch「构建集成Build Integrations」系列教程的第四篇以 The Cat API 为例完整演示如何为自定义集成应用添加连接Connection认证能力从注册第三方服务、定义认证字段到实现verifyCredentials与isStillVerified两个核心方法并最终在 Automatisch 界面中完成连接创建、测试连接与重新连接。读完本文你将掌握 Automatisch 集成体系中 API Key 型认证的完整实现范式并了解它背后的源码运行机制。系列阅读上下文构建集成章节的内容是层层递进的官方文档建议从头到尾按顺序阅读以获得最完整的理解Folder structureAppGlobal variableAuth本文TriggersActionsExamples在动手之前请先完成前几篇的准备工作按照 Folder structure 创建好名为thecatapi的应用目录并按照 App 完成应用的基础定义。本文默认你已经拥有了这个可运行的 App 骨架。注册 The Cat API 并获取 API Key前往 The Cat API 的注册页面注册账号。免费账号每月允许10k 次请求注册完成后 API Key 会通过邮件发送给你。这个 API Key 就是我们稍后在 Automatisch 中完成认证所要用到的凭据请妥善保存。查阅 The Cat API 官方文档在构建集成的整个过程中需要反复查阅 The Cat API 的官方文档确认接口的请求方式、路径与参数确认 API Key 在请求中如何传递Header 还是 Query确认是否存在可用于验证身份的用户信息端点例如/me或/users/me。这一点非常关键因为在后面的verifyCredentials实现中我们要根据“第三方 API 是否提供用户信息端点”来设计不同的验证策略。在 App 定义中接入 auth 模块打开thecatapi/index.js添加下面代码中高亮的两行import auth与auth属性把认证模块接入应用定义import defineApp from ../../helpers/define-app.js; import auth from ./auth/index.js; export default defineApp({ name: The Cat API, key: thecatapi, iconUrl: {BASE_URL}/apps/thecatapi/assets/favicon.svg, authDocUrl: {DOCS_URL}/apps/thecatapi/connection, supportsConnections: true, baseUrl: https://thecatapi.com, apiBaseUrl: https://api.thecatapi.com, primaryColor: #000000, auth, });逐项理解这个 App 定义的关键属性name/key应用的显示名称与唯一标识符key同时也是代码目录名iconUrl/authDocUrl使用{BASE_URL}与{DOCS_URL}占位符由 Automatisch 在运行时替换为实际部署地址supportsConnections: true声明该应用支持“连接”能力这是接入认证的前提baseUrl服务商官网地址apiBaseUrlAPI 基地址。后续所有$.http请求都会相对apiBaseUrl发起auth认证配置对象即我们接下来要实现的auth/index.js。从源码角度看defineApp是定义在 packages/backend/src/helpers/define-app.js 中的一个透传函数——它原样返回传入的应用定义对象本身不做校验真正的校验与加工发生在后续的加载与序列化环节。你可以在仓库中大量真实应用的入口文件里看到完全一致的结构例如 packages/backend/src/apps/ntfy/index.js 中同样使用defineApp传入auth、actions等模块并额外通过beforeRequest注入认证请求头。定义认证字段Auth Fields接下来在thecatapi目录下创建auth文件夹与auth/index.js文件mkdir auth touch auth/index.js然后在auth/index.js中定义认证所需的字段export default { fields: [ { key: screenName, label: Screen Name, type: string, required: true, readOnly: false, value: null, placeholder: null, description: Screen name of your connection to be used on Automatisch UI., clickToCopy: false, }, { key: apiKey, label: API Key, type: string, required: true, readOnly: false, value: null, placeholder: null, description: API key of the cat API service., clickToCopy: false, }, ], };这里为认证定义了两个字段每个字段的完整属性语义如下属性含义key字段标识符在代码中通过$.auth.data.key访问用户输入值label在 Automatisch 界面上展示的字段名称type字段类型API Key 型认证通常为string密码类敏感字段在真实集成中也会用string展示required是否必填true时用户不填写将无法提交连接readOnly是否只读例如 OAuth 中由系统生成的回调地址字段通常为truevalue默认值可为null或像 ntfy 的serverUrl那样给出https://ntfy.sh这样的预设值placeholder输入框占位提示description字段说明展示在输入框下方引导用户clickToCopy是否提供一键复制按钮常用于 OAuth Redirect URL 等需要用户复制到第三方平台填写的字段两个字段的职责apiKey用于对 The Cat API 的请求进行认证screenName用于在 Automatisch 界面上标识这条连接。⚠️必须添加 screenName 字段如果第三方 API 没有可用来获取用户名或任何用户信息的端点你就必须添加一个 screen name 字段。有些 API 提供了类似/me或/users/me的端点用于此目的但 The Cat API 并没有这样的端点因此这里必须显式提供screenName字段。⛔API Key 与 OAuth 的取舍如果第三方服务同时支持 API Key 和 OAuth 两种认证方式Automatisch 期望你使用OAuth而不是 API Key。在为新集成提交 Pull Request 时请务必考虑这一点否则可能会被要求改为 OAuth 实现。想看 OAuth 实现的示例应用可查看 3-legged OAuth 示例。verifyCredentials验证用户提交的凭据字段定义完成后Automatisch 需要在用户创建连接时验证凭据是否正确这通过verifyCredentials方法实现。先在auth/index.js中引入并挂载它import verifyCredentials from ./verify-credentials.js; export default { fields: [ // ... ], verifyCredentials, };然后在auth文件夹内创建verify-credentials.jsconst verifyCredentials async ($) { // TODO: Implement verification of the credentials }; export default verifyCredentials;验证策略选择可用的探测端点一般我们会使用users/me端点或任何其他能够验证 API Key / 凭据有效性的端点。对本例而言The Cat API 没有专门的凭据校验端点因此随机选用其中一个 API 端点GET /v1/images/search。原理很简单携带 API Key 向该端点发送请求若 API Key 正确服务端返回正常响应若 API Key 错误服务端返回错误响应$.http会抛出异常Automatisch 自动拦截并提示用户凭据无效。完整实现const verifyCredentials async ($) { await $.http.get(/v1/images/search); await $.auth.set({ screenName: $.auth.data.screenName, }); }; export default verifyCredentials;代码中的两个关键上下文对象$.httpAutomatisch 提供的 HTTP 客户端自动以apiBaseUrl为基地址拼接请求路径。请求发出前会执行应用定义中的beforeRequest钩子例如 ntfy 应用在 packages/backend/src/apps/ntfy/common/add-auth-header.js 中把用户名密码拼成 Basic Auth 头从而把凭据自动带入每次请求$.auth.data用户在字段表单中提交的原始数据例如$.auth.data.apiKey、$.auth.data.screenName$.auth.set()将指定数据持久化写入连接的认证数据后续所有流程执行时均可通过$.auth.data读取。真实集成中还会在这里保存accessToken、scope、userId等令牌相关数据详见下文 GitHub OAuth 示例。⚠️必须设置 screenNameverifyCredentials中必须始终向 auth data 提供screenName字段否则连接将没有名称在用户界面中无法正常工作。即使是从/me端点拿到真实用户名最终也要把它写入screenName。isStillVerified判断连接是否仍然有效verifyCredentials解决“初次创建连接时的凭据校验”而isStillVerified负责 Automatisch测试连接Test Connection功能所需的“连接是否仍然有效”的检查。先在auth/index.js中引入并挂载import verifyCredentials from ./verify-credentials.js; import isStillVerified from ./is-still-verified.js; export default { fields: [ // ... ], verifyCredentials, isStillVerified, };创建is-still-verified.jsimport verifyCredentials from ./verify-credentials.js; const isStillVerified async ($) { await verifyCredentials($); return true; }; export default isStillVerified;需要注意ℹ️isStillVerified方法必须返回真值truthy凭据才被视为仍然有效。这里我们直接复用了verifyCredentials来探测凭据有效性有效则返回true无效则抛错并由 Automatisch 自动处理。⚠️为什么要保留两个独立方法你可能会疑惑既然本场景底层只用到其中一个函数为什么还要写两个这是因为 The Cat API 这类 API 恰好可以复用同一套探测逻辑但有些第三方 API无法直接复用同一函数来判断凭据是否仍然有效例如令牌已过期需要刷新、需要携带已保存的 accessToken 而不仅是用户重新输入的密钥等。因此 Autmotisch 的认证体系强制将“验证凭据”与“检查是否仍有效”拆分为两个独立方法让每个集成可以按需实现各自的逻辑。关于 OAuth 集成的提示如果你的集成需要通过第三方服务的授权 URLauthorization URL来完成连接则需要同时使用generateAuthUrl、verifyCredentials与isStillVerified三个方法具体实现请参考 3-legged OAuth 示例。仓库中的真实实现印证上述 API Key 型认证的写法在仓库中有大量现成案例例如 ntfy 应用packages/backend/src/apps/ntfy/auth/index.js定义了serverUrl、username、password三个字段并挂载verifyCredentials与isStillVerifiedpackages/backend/src/apps/ntfy/auth/verify-credentials.js先发送请求探测服务可达性与凭据有效性再根据是否提供用户名拼接出screenName形如username serverUrl最后$.auth.set({ screenName })packages/backend/src/apps/ntfy/auth/is-still-verified.js与本文示例完全一致——调用verifyCredentials后返回true。OAuth 型认证的差异则体现在 GitHub 应用中packages/backend/src/apps/github/auth/index.js 额外挂载了generateAuthUrl字段中还包括oAuthRedirectUrlreadOnly: true且clickToCopy: true便于用户复制到 GitHub 开发者后台其 verify-credentials.js 先用code换取access_token再调用getCurrentUser获取当前用户信息最后把accessToken、scope、tokenType、userId、screenName真实登录名一次性$.auth.set保存。这套认证流程的前端编排逻辑定义在 packages/backend/src/helpers/add-authentication-steps.js应用没有generateAuthUrl时如 The Cat API、ntfy认证步骤为两步createConnection用{fields.all}提交表单字段→verifyConnection触发后端的verifyCredentials应用有generateAuthUrl时如 GitHub认证步骤扩展为五步创建连接 →generateAuthUrl生成授权链接 → 弹出授权窗口openWithPopup→ 把授权回调数据更新进连接 →verifyConnection校验并保存令牌。这就是为什么文档要求在 OAuth 场景下必须同时实现generateAuthUrl——它不仅是方法更决定了连接创建向导的完整交互流程。在 Automatisch 界面中测试认证至此The Cat API 的认证部分已经完成。接下来进行端到端验证进入 Automatisch 的My Apps页面点击添加新连接Add Connection选择The Cat API填写你通过邮件收到的API Key以及用于标识该连接的 Screen Name保存后Automatisch 会调用verifyCredentials校验凭据在连接详情中你还可以使用测试连接Test Connection功能此时触发的是isStillVerified若凭据失效可在此处使用重新连接Reconnect功能重新走一遍认证流程。确认连接创建、测试连接与重新连接功能都正常后就可以进入系列教程的下一页为这个集成添加触发器Trigger了。构建触发器的完整教程见 Triggers。小结通过 The Cat API 这个最小可运行的案例我们已经走通了 Automatisch 集成中认证模块的完整链路App 定义挂载auth→ 声明字段含必备的screenName→verifyCredentials校验凭据并保存认证数据 →isStillVerified支撑测试连接功能。对照仓库中的 ntfy 应用 与 GitHub 应用可以清楚看到 API Key 型与 OAuth 型两种认证在字段设计、方法组合以及由 add-authentication-steps.js 驱动的连接创建流程上的异同。掌握这套模式后你可以将其复用到任意 API Key 型第三方服务的集成中如需接入 OAuth 服务直接参考 3-legged OAuth 示例 即可。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Automatisch 集成开发指南：为你的第一个 App 接入认证（Auth）能力
Automatisch 集成开发指南为你的第一个 App 接入认证Auth能力【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本指南是 Automatisch「构建集成Build Integrations」系列教程的第四篇以 The Cat API 为例完整演示如何为自定义集成应用添加连接Connection认证能力从注册第三方服务、定义认证字段到实现verifyCredentials与isStillVerified两个核心方法并最终在 Automatisch 界面中完成连接创建、测试连接与重新连接。读完本文你将掌握 Automatisch 集成体系中 API Key 型认证的完整实现范式并了解它背后的源码运行机制。系列阅读上下文构建集成章节的内容是层层递进的官方文档建议从头到尾按顺序阅读以获得最完整的理解Folder structureAppGlobal variableAuth本文TriggersActionsExamples在动手之前请先完成前几篇的准备工作按照 Folder structure 创建好名为thecatapi的应用目录并按照 App 完成应用的基础定义。本文默认你已经拥有了这个可运行的 App 骨架。注册 The Cat API 并获取 API Key前往 The Cat API 的注册页面注册账号。免费账号每月允许10k 次请求注册完成后 API Key 会通过邮件发送给你。这个 API Key 就是我们稍后在 Automatisch 中完成认证所要用到的凭据请妥善保存。查阅 The Cat API 官方文档在构建集成的整个过程中需要反复查阅 The Cat API 的官方文档确认接口的请求方式、路径与参数确认 API Key 在请求中如何传递Header 还是 Query确认是否存在可用于验证身份的用户信息端点例如/me或/users/me。这一点非常关键因为在后面的verifyCredentials实现中我们要根据“第三方 API 是否提供用户信息端点”来设计不同的验证策略。在 App 定义中接入 auth 模块打开thecatapi/index.js添加下面代码中高亮的两行import auth与auth属性把认证模块接入应用定义import defineApp from ../../helpers/define-app.js; import auth from ./auth/index.js; export default defineApp({ name: The Cat API, key: thecatapi, iconUrl: {BASE_URL}/apps/thecatapi/assets/favicon.svg, authDocUrl: {DOCS_URL}/apps/thecatapi/connection, supportsConnections: true, baseUrl: https://thecatapi.com, apiBaseUrl: https://api.thecatapi.com, primaryColor: #000000, auth, });逐项理解这个 App 定义的关键属性name/key应用的显示名称与唯一标识符key同时也是代码目录名iconUrl/authDocUrl使用{BASE_URL}与{DOCS_URL}占位符由 Automatisch 在运行时替换为实际部署地址supportsConnections: true声明该应用支持“连接”能力这是接入认证的前提baseUrl服务商官网地址apiBaseUrlAPI 基地址。后续所有$.http请求都会相对apiBaseUrl发起auth认证配置对象即我们接下来要实现的auth/index.js。从源码角度看defineApp是定义在 packages/backend/src/helpers/define-app.js 中的一个透传函数——它原样返回传入的应用定义对象本身不做校验真正的校验与加工发生在后续的加载与序列化环节。你可以在仓库中大量真实应用的入口文件里看到完全一致的结构例如 packages/backend/src/apps/ntfy/index.js 中同样使用defineApp传入auth、actions等模块并额外通过beforeRequest注入认证请求头。定义认证字段Auth Fields接下来在thecatapi目录下创建auth文件夹与auth/index.js文件mkdir auth touch auth/index.js然后在auth/index.js中定义认证所需的字段export default { fields: [ { key: screenName, label: Screen Name, type: string, required: true, readOnly: false, value: null, placeholder: null, description: Screen name of your connection to be used on Automatisch UI., clickToCopy: false, }, { key: apiKey, label: API Key, type: string, required: true, readOnly: false, value: null, placeholder: null, description: API key of the cat API service., clickToCopy: false, }, ], };这里为认证定义了两个字段每个字段的完整属性语义如下属性含义key字段标识符在代码中通过$.auth.data.key访问用户输入值label在 Automatisch 界面上展示的字段名称type字段类型API Key 型认证通常为string密码类敏感字段在真实集成中也会用string展示required是否必填true时用户不填写将无法提交连接readOnly是否只读例如 OAuth 中由系统生成的回调地址字段通常为truevalue默认值可为null或像 ntfy 的serverUrl那样给出https://ntfy.sh这样的预设值placeholder输入框占位提示description字段说明展示在输入框下方引导用户clickToCopy是否提供一键复制按钮常用于 OAuth Redirect URL 等需要用户复制到第三方平台填写的字段两个字段的职责apiKey用于对 The Cat API 的请求进行认证screenName用于在 Automatisch 界面上标识这条连接。⚠️必须添加 screenName 字段如果第三方 API 没有可用来获取用户名或任何用户信息的端点你就必须添加一个 screen name 字段。有些 API 提供了类似/me或/users/me的端点用于此目的但 The Cat API 并没有这样的端点因此这里必须显式提供screenName字段。⛔API Key 与 OAuth 的取舍如果第三方服务同时支持 API Key 和 OAuth 两种认证方式Automatisch 期望你使用OAuth而不是 API Key。在为新集成提交 Pull Request 时请务必考虑这一点否则可能会被要求改为 OAuth 实现。想看 OAuth 实现的示例应用可查看 3-legged OAuth 示例。verifyCredentials验证用户提交的凭据字段定义完成后Automatisch 需要在用户创建连接时验证凭据是否正确这通过verifyCredentials方法实现。先在auth/index.js中引入并挂载它import verifyCredentials from ./verify-credentials.js; export default { fields: [ // ... ], verifyCredentials, };然后在auth文件夹内创建verify-credentials.jsconst verifyCredentials async ($) { // TODO: Implement verification of the credentials }; export default verifyCredentials;验证策略选择可用的探测端点一般我们会使用users/me端点或任何其他能够验证 API Key / 凭据有效性的端点。对本例而言The Cat API 没有专门的凭据校验端点因此随机选用其中一个 API 端点GET /v1/images/search。原理很简单携带 API Key 向该端点发送请求若 API Key 正确服务端返回正常响应若 API Key 错误服务端返回错误响应$.http会抛出异常Automatisch 自动拦截并提示用户凭据无效。完整实现const verifyCredentials async ($) { await $.http.get(/v1/images/search); await $.auth.set({ screenName: $.auth.data.screenName, }); }; export default verifyCredentials;代码中的两个关键上下文对象$.httpAutomatisch 提供的 HTTP 客户端自动以apiBaseUrl为基地址拼接请求路径。请求发出前会执行应用定义中的beforeRequest钩子例如 ntfy 应用在 packages/backend/src/apps/ntfy/common/add-auth-header.js 中把用户名密码拼成 Basic Auth 头从而把凭据自动带入每次请求$.auth.data用户在字段表单中提交的原始数据例如$.auth.data.apiKey、$.auth.data.screenName$.auth.set()将指定数据持久化写入连接的认证数据后续所有流程执行时均可通过$.auth.data读取。真实集成中还会在这里保存accessToken、scope、userId等令牌相关数据详见下文 GitHub OAuth 示例。⚠️必须设置 screenNameverifyCredentials中必须始终向 auth data 提供screenName字段否则连接将没有名称在用户界面中无法正常工作。即使是从/me端点拿到真实用户名最终也要把它写入screenName。isStillVerified判断连接是否仍然有效verifyCredentials解决“初次创建连接时的凭据校验”而isStillVerified负责 Automatisch测试连接Test Connection功能所需的“连接是否仍然有效”的检查。先在auth/index.js中引入并挂载import verifyCredentials from ./verify-credentials.js; import isStillVerified from ./is-still-verified.js; export default { fields: [ // ... ], verifyCredentials, isStillVerified, };创建is-still-verified.jsimport verifyCredentials from ./verify-credentials.js; const isStillVerified async ($) { await verifyCredentials($); return true; }; export default isStillVerified;需要注意ℹ️isStillVerified方法必须返回真值truthy凭据才被视为仍然有效。这里我们直接复用了verifyCredentials来探测凭据有效性有效则返回true无效则抛错并由 Automatisch 自动处理。⚠️为什么要保留两个独立方法你可能会疑惑既然本场景底层只用到其中一个函数为什么还要写两个这是因为 The Cat API 这类 API 恰好可以复用同一套探测逻辑但有些第三方 API无法直接复用同一函数来判断凭据是否仍然有效例如令牌已过期需要刷新、需要携带已保存的 accessToken 而不仅是用户重新输入的密钥等。因此 Autmotisch 的认证体系强制将“验证凭据”与“检查是否仍有效”拆分为两个独立方法让每个集成可以按需实现各自的逻辑。关于 OAuth 集成的提示如果你的集成需要通过第三方服务的授权 URLauthorization URL来完成连接则需要同时使用generateAuthUrl、verifyCredentials与isStillVerified三个方法具体实现请参考 3-legged OAuth 示例。仓库中的真实实现印证上述 API Key 型认证的写法在仓库中有大量现成案例例如 ntfy 应用packages/backend/src/apps/ntfy/auth/index.js定义了serverUrl、username、password三个字段并挂载verifyCredentials与isStillVerifiedpackages/backend/src/apps/ntfy/auth/verify-credentials.js先发送请求探测服务可达性与凭据有效性再根据是否提供用户名拼接出screenName形如username serverUrl最后$.auth.set({ screenName })packages/backend/src/apps/ntfy/auth/is-still-verified.js与本文示例完全一致——调用verifyCredentials后返回true。OAuth 型认证的差异则体现在 GitHub 应用中packages/backend/src/apps/github/auth/index.js 额外挂载了generateAuthUrl字段中还包括oAuthRedirectUrlreadOnly: true且clickToCopy: true便于用户复制到 GitHub 开发者后台其 verify-credentials.js 先用code换取access_token再调用getCurrentUser获取当前用户信息最后把accessToken、scope、tokenType、userId、screenName真实登录名一次性$.auth.set保存。这套认证流程的前端编排逻辑定义在 packages/backend/src/helpers/add-authentication-steps.js应用没有generateAuthUrl时如 The Cat API、ntfy认证步骤为两步createConnection用{fields.all}提交表单字段→verifyConnection触发后端的verifyCredentials应用有generateAuthUrl时如 GitHub认证步骤扩展为五步创建连接 →generateAuthUrl生成授权链接 → 弹出授权窗口openWithPopup→ 把授权回调数据更新进连接 →verifyConnection校验并保存令牌。这就是为什么文档要求在 OAuth 场景下必须同时实现generateAuthUrl——它不仅是方法更决定了连接创建向导的完整交互流程。在 Automatisch 界面中测试认证至此The Cat API 的认证部分已经完成。接下来进行端到端验证进入 Automatisch 的My Apps页面点击添加新连接Add Connection选择The Cat API填写你通过邮件收到的API Key以及用于标识该连接的 Screen Name保存后Automatisch 会调用verifyCredentials校验凭据在连接详情中你还可以使用测试连接Test Connection功能此时触发的是isStillVerified若凭据失效可在此处使用重新连接Reconnect功能重新走一遍认证流程。确认连接创建、测试连接与重新连接功能都正常后就可以进入系列教程的下一页为这个集成添加触发器Trigger了。构建触发器的完整教程见 Triggers。小结通过 The Cat API 这个最小可运行的案例我们已经走通了 Automatisch 集成中认证模块的完整链路App 定义挂载auth→ 声明字段含必备的screenName→verifyCredentials校验凭据并保存认证数据 →isStillVerified支撑测试连接功能。对照仓库中的 ntfy 应用 与 GitHub 应用可以清楚看到 API Key 型与 OAuth 型两种认证在字段设计、方法组合以及由 add-authentication-steps.js 驱动的连接创建流程上的异同。掌握这套模式后你可以将其复用到任意 API Key 型第三方服务的集成中如需接入 OAuth 服务直接参考 3-legged OAuth 示例 即可。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考