企业官网建设流程全解析

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 型认证的完整实现范式，并了解它背后的源码运行机制。

系列阅读上下文

构建集成章节的内容是层层递进的，官方文档建议从头到尾按顺序阅读，以获得最完整的理解：

1. Folder structure
2. App
3. Global variable
4. Auth（本文）
5. Triggers
6. Actions
7. Examples

在动手之前，请先完成前几篇的准备工作：按照 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：服务商官网地址；apiBaseUrl：API 基地址。后续所有$.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, }, ], };

这里为认证定义了两个字段，每个字段的完整属性语义如下：

两个字段的职责：

• 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.js：

const 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;

代码中的两个关键上下文对象：

• $.http：Automatisch 提供的 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 示例）。

⚠️必须设置 screenName：verifyCredentials中必须始终向 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.js：

import 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 集成的提示：如果你的集成需要通过第三方服务的授权 URL（authorization URL）来完成连接，则需要同时使用generateAuthUrl、verifyCredentials与isStillVerified三个方法，具体实现请参考 3-legged OAuth 示例。

仓库中的真实实现印证

上述 API Key 型认证的写法在仓库中有大量现成案例，例如 ntfy 应用：

• packages/backend/src/apps/ntfy/auth/index.js：定义了serverUrl、username、password三个字段，并挂载verifyCredentials与isStillVerified；
• packages/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，字段中还包括oAuthRedirectUrl（readOnly: 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 的认证部分已经完成。接下来进行端到端验证：

1. 进入 Automatisch 的My Apps页面；
2. 点击添加新连接（Add Connection），选择The Cat API；
3. 填写你通过邮件收到的API Key（以及用于标识该连接的 Screen Name）；
4. 保存后，Automatisch 会调用verifyCredentials校验凭据；
5. 在连接详情中你还可以使用测试连接（Test Connection）功能，此时触发的是isStillVerified；
6. 若凭据失效，可在此处使用重新连接（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