Automatisch 集成开发指南从零构建 App Actions 动作的完整实战【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本指南是 Automatisch 构建集成Build Integrations系列教程的第六篇围绕packages/docs/pages/build-integrations/actions.md展开。你将学习如何在一个自定义 App 集成中定义、注册、实现并测试 Actions动作掌握defineAction、$.http、$.setActionItem等核心 API 的实战用法最终能够在 Automatisch 工作流中搭建可运行的触发-动作链条。本系列建议按顺序阅读先是 Folder structure、App、Global variable、Auth、Triggers本篇聚焦 Actions最后可参考 Examples 巩固完整案例。Actions 在 Automatisch 集成架构中的定位Actions 是 Automatisch 集成中执行操作的单元当触发事件发生后工作流中的 Action 步骤负责调用目标应用的 API 完成具体任务发消息、建 issue、写数据库等。在目录结构中每个 App 的 Actions 集中放在app-key/actions/目录下与auth/、triggers/、dynamic-data/并列。从源码看Automatisch 将 Action 视为带有固定契约的 JavaScript 对象。入口定义函数 define-action.js 目前只是一个恒等函数不做额外校验export default function defineAction(actionDefinition) { return actionDefinition; }同理App 的定义函数 define-app.js 也只是透传。这意味着 Action 的本质就是一个包含元数据与run函数的标准对象defineAction的作用在于统一结构、便于后续演进。一个只提供 Actions、不需要连接认证的 App如 HTTP Request甚至可以不配置 auth 和 triggers见 http-request/index.js。第一步在 App 入口注册 Actions打开thecatapi/index.js本系列教程虚构的示例 App在原有导入基础上增加 actions 的导入与注册对应高亮行import defineApp from ../../helpers/define-app.js; import auth from ./auth/index.js; import triggers from ./triggers/index.js; import actions from ./actions/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, triggers actions });这里第 4 行导入、第 17 行注册。actions与auth、triggers一样都是对象数组后续 UI 会通过step.getActionCommand()按key从中查找对应 Action 定义见 models/step.jsasync getActionCommand() { const { appKey, key, isAction } this; if (!isAction || !appKey || !key) return null; const app await App.findOneByKey(appKey); const command app.actions?.find((action) action.key key); return command; }第二步创建 actions/index.js 汇总导出在thecatapi目录下新建actions/index.js把所有 Action 作为数组导出。这一文件是 Actions 的清单每新增一个 Action 都要在此登记import markCatImageAsFavorite from ./mark-cat-image-as-favorite/index.js; export default [markCatImageAsFavorite];提示如果你新增了 Actions必须把它们加入actions/index.js并以数组形式导出否则引擎无法发现它们。仓库中的真实示例 github/actions/index.js 与 slack/actions/index.js 均遵循同一模式——每个 Action 独立成目录目录下index.js存放定义文件。第三步添加 Action 元数据在thecatapi目录下创建actions/mark-cat-image-as-favorite/index.js用defineAction描述该 Actionimport defineAction from ../../../../helpers/define-action.js; export default defineAction({ name: Mark the cat image as favorite, key: markCatImageAsFavorite, description: Marks the cat image as favorite., arguments: [ { label: Image ID, key: imageId, type: string, required: true, description: The ID of the cat image you want to mark as favorite., variables: true, }, ], async run($) { // TODO: Implement action! }, });各字段含义如下nameAction 的名称用于在 Automatisch UI 中展示。keyAction 的唯一标识Automatisch 通过它来识别该 Action与数据库中的 step 记录对应。descriptionAction 的功能描述。argumentsAction 的参数列表即用户使用该 Action 时填写的输入值。每个参数支持label标签、key参数键名、type类型、required是否必填、description说明、variables是否允许引用上游变量等字段。runAction 被执行时调用的函数入参为全局上下文对象$。arguments的类型并不限于字符串。仓库中 github/actions/create-issue/index.js 展示了dropdown类型参数与动态数据源source的用法——source.type: query、name: getDynamicData会把listRepos动态数据拉取结果渲染成下拉选项让用户在界面上直接选择仓库{ label: Repo, key: repo, type: dropdown, required: true, variables: true, source: { type: query, name: getDynamicData, arguments: [ { name: key, value: listRepos, }, ], }, },此外还有dynamic类型如 http-request 的 Headers 参数允许用户动态增删键值对以及additionalFields等进阶用法可在编写复杂参数时参考。第四步实现 run 函数打开actions/mark-cat-image-as-favorite.js补全run逻辑import defineAction from ../../../../helpers/define-action.js; export default defineAction({ // ... async run($) { const requestPath /v1/favourites; const imageId $.step.parameters.imageId; const headers { x-api-key: $.auth.data.apiKey, }; const response await $.http.post( requestPath, { image_id: imageId }, { headers } ); $.setActionItem({ raw: response.data }); }, });这个 Action 向 Cat API 发送请求把指定猫咪图片标记为收藏。它用$.http.post发起请求请求体包含 API 要求的image_id。run 内部可用的$全局对象$由引擎在执行前统一构建定义于 engine/global-variable.js。上文用到三个核心成员$.step.parameters当前步骤的参数对象用户在 UI 填写的值含上游变量解析结果都会进入这里。$.auth.data当前连接的认证数据如apiKey、accessToken来自connection.formattedData。因此示例中能直接以$.auth.data.apiKey作为请求头。$.setActionItem({ raw: ... })设置 Action 的输出结果。它会写入$.actionOutput.data这个数据一方面用于在 Automatisch UI 中展示本次 Action 的返回结果另一方面可在工作流后续步骤中作为变量被引用。此外$还提供$.http基于 app 的apiBaseUrl和beforeRequest构建的 HTTP 客户端、$.execution.exit()提前结束执行、$.getLastExecutionStep()获取上一步执行结果、$.datastore.get/set流程级数据存取、$.flow、$.app等详见 global-variable.js。$.http的底层行为$.http由 helpers/http-client/index.js 创建它基于app.apiBaseUrl设置 baseURL并将 app 定义的beforeRequest如附加鉴权头、刷新 token 的钩子注册为请求拦截器。值得注意的一点是当响应为 401/403 且 app 配置了auth.refreshToken时客户端会自动刷新 token 并重试原请求其他错误则包装为HttpError抛出执行器会将其error.details记录到执行步骤的errorDetails中。这解释了为什么编写 Action 时通常只需关心业务请求本身鉴权与错误处理由框架兜底。Action 执行的真实链路在引擎侧Action 的每次执行都经过 engine/action/process.js 编排engine/action/context.js 根据stepId加载 step、app、connection并调用step.getActionCommand()取到我们定义的 Action 对象构建$全局对象computeParameters结合上游执行步骤解析参数中的变量引用覆盖回$.step.parameters调用command.run($)将dataIn计算后的参数、dataOut$.actionOutput.data.raw、status、errorDetails写入execution_steps表供 UI 展示与后续步骤使用。因此$.setActionItem({ raw: response.data })中response.data的形态直接决定了该步骤在 UI 中展示的 JSON以及下游步骤能引用到的数据结构。第五步在 Automatisch UI 中测试 Action完成代码后按以下步骤验证进入 Automatisch 的 flows 页面创建一个新的 flow添加Search cat images作为 flow 的触发器Trigger添加Mark the cat image as favorite作为 flow 的第二步Action在 Action 的Image ID参数中填入一个从 Cat API 获取到的图片 ID点击Test Continue按钮。如果在界面中看到 JSON 响应说明我们构建的触发器和 Action 都能正常工作。测试运行test run模式下引擎会把本次执行标记为testRun方便你随时重试而不影响正式执行记录。参考仓库中的真实 Action 实战除了教程示例仓库中有大量生产可用的 Action 实现可对照学习Create issue展示了必填参数校验throw new Error(A repo must be set!)、参数解析与动态下拉的完整组合。Custom request展示了大文件响应限制25MB、二进制响应 Base64 编码、动态 Headers 参数等进阶处理是编写通用型 Action 的范本。Slack 四个 Action多 Action App 的典型目录与导出结构。结合 folder-structure.md、triggers.md 与 examples.md你可以把定义元数据 实现 run 注册导出 UI 验证这条链路完整落地从而为任意第三方服务构建出高质量的 Automatisch 集成。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Automatisch 集成开发指南：从零构建 App Actions 动作的完整实战
Automatisch 集成开发指南从零构建 App Actions 动作的完整实战【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本指南是 Automatisch 构建集成Build Integrations系列教程的第六篇围绕packages/docs/pages/build-integrations/actions.md展开。你将学习如何在一个自定义 App 集成中定义、注册、实现并测试 Actions动作掌握defineAction、$.http、$.setActionItem等核心 API 的实战用法最终能够在 Automatisch 工作流中搭建可运行的触发-动作链条。本系列建议按顺序阅读先是 Folder structure、App、Global variable、Auth、Triggers本篇聚焦 Actions最后可参考 Examples 巩固完整案例。Actions 在 Automatisch 集成架构中的定位Actions 是 Automatisch 集成中执行操作的单元当触发事件发生后工作流中的 Action 步骤负责调用目标应用的 API 完成具体任务发消息、建 issue、写数据库等。在目录结构中每个 App 的 Actions 集中放在app-key/actions/目录下与auth/、triggers/、dynamic-data/并列。从源码看Automatisch 将 Action 视为带有固定契约的 JavaScript 对象。入口定义函数 define-action.js 目前只是一个恒等函数不做额外校验export default function defineAction(actionDefinition) { return actionDefinition; }同理App 的定义函数 define-app.js 也只是透传。这意味着 Action 的本质就是一个包含元数据与run函数的标准对象defineAction的作用在于统一结构、便于后续演进。一个只提供 Actions、不需要连接认证的 App如 HTTP Request甚至可以不配置 auth 和 triggers见 http-request/index.js。第一步在 App 入口注册 Actions打开thecatapi/index.js本系列教程虚构的示例 App在原有导入基础上增加 actions 的导入与注册对应高亮行import defineApp from ../../helpers/define-app.js; import auth from ./auth/index.js; import triggers from ./triggers/index.js; import actions from ./actions/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, triggers actions });这里第 4 行导入、第 17 行注册。actions与auth、triggers一样都是对象数组后续 UI 会通过step.getActionCommand()按key从中查找对应 Action 定义见 models/step.jsasync getActionCommand() { const { appKey, key, isAction } this; if (!isAction || !appKey || !key) return null; const app await App.findOneByKey(appKey); const command app.actions?.find((action) action.key key); return command; }第二步创建 actions/index.js 汇总导出在thecatapi目录下新建actions/index.js把所有 Action 作为数组导出。这一文件是 Actions 的清单每新增一个 Action 都要在此登记import markCatImageAsFavorite from ./mark-cat-image-as-favorite/index.js; export default [markCatImageAsFavorite];提示如果你新增了 Actions必须把它们加入actions/index.js并以数组形式导出否则引擎无法发现它们。仓库中的真实示例 github/actions/index.js 与 slack/actions/index.js 均遵循同一模式——每个 Action 独立成目录目录下index.js存放定义文件。第三步添加 Action 元数据在thecatapi目录下创建actions/mark-cat-image-as-favorite/index.js用defineAction描述该 Actionimport defineAction from ../../../../helpers/define-action.js; export default defineAction({ name: Mark the cat image as favorite, key: markCatImageAsFavorite, description: Marks the cat image as favorite., arguments: [ { label: Image ID, key: imageId, type: string, required: true, description: The ID of the cat image you want to mark as favorite., variables: true, }, ], async run($) { // TODO: Implement action! }, });各字段含义如下nameAction 的名称用于在 Automatisch UI 中展示。keyAction 的唯一标识Automatisch 通过它来识别该 Action与数据库中的 step 记录对应。descriptionAction 的功能描述。argumentsAction 的参数列表即用户使用该 Action 时填写的输入值。每个参数支持label标签、key参数键名、type类型、required是否必填、description说明、variables是否允许引用上游变量等字段。runAction 被执行时调用的函数入参为全局上下文对象$。arguments的类型并不限于字符串。仓库中 github/actions/create-issue/index.js 展示了dropdown类型参数与动态数据源source的用法——source.type: query、name: getDynamicData会把listRepos动态数据拉取结果渲染成下拉选项让用户在界面上直接选择仓库{ label: Repo, key: repo, type: dropdown, required: true, variables: true, source: { type: query, name: getDynamicData, arguments: [ { name: key, value: listRepos, }, ], }, },此外还有dynamic类型如 http-request 的 Headers 参数允许用户动态增删键值对以及additionalFields等进阶用法可在编写复杂参数时参考。第四步实现 run 函数打开actions/mark-cat-image-as-favorite.js补全run逻辑import defineAction from ../../../../helpers/define-action.js; export default defineAction({ // ... async run($) { const requestPath /v1/favourites; const imageId $.step.parameters.imageId; const headers { x-api-key: $.auth.data.apiKey, }; const response await $.http.post( requestPath, { image_id: imageId }, { headers } ); $.setActionItem({ raw: response.data }); }, });这个 Action 向 Cat API 发送请求把指定猫咪图片标记为收藏。它用$.http.post发起请求请求体包含 API 要求的image_id。run 内部可用的$全局对象$由引擎在执行前统一构建定义于 engine/global-variable.js。上文用到三个核心成员$.step.parameters当前步骤的参数对象用户在 UI 填写的值含上游变量解析结果都会进入这里。$.auth.data当前连接的认证数据如apiKey、accessToken来自connection.formattedData。因此示例中能直接以$.auth.data.apiKey作为请求头。$.setActionItem({ raw: ... })设置 Action 的输出结果。它会写入$.actionOutput.data这个数据一方面用于在 Automatisch UI 中展示本次 Action 的返回结果另一方面可在工作流后续步骤中作为变量被引用。此外$还提供$.http基于 app 的apiBaseUrl和beforeRequest构建的 HTTP 客户端、$.execution.exit()提前结束执行、$.getLastExecutionStep()获取上一步执行结果、$.datastore.get/set流程级数据存取、$.flow、$.app等详见 global-variable.js。$.http的底层行为$.http由 helpers/http-client/index.js 创建它基于app.apiBaseUrl设置 baseURL并将 app 定义的beforeRequest如附加鉴权头、刷新 token 的钩子注册为请求拦截器。值得注意的一点是当响应为 401/403 且 app 配置了auth.refreshToken时客户端会自动刷新 token 并重试原请求其他错误则包装为HttpError抛出执行器会将其error.details记录到执行步骤的errorDetails中。这解释了为什么编写 Action 时通常只需关心业务请求本身鉴权与错误处理由框架兜底。Action 执行的真实链路在引擎侧Action 的每次执行都经过 engine/action/process.js 编排engine/action/context.js 根据stepId加载 step、app、connection并调用step.getActionCommand()取到我们定义的 Action 对象构建$全局对象computeParameters结合上游执行步骤解析参数中的变量引用覆盖回$.step.parameters调用command.run($)将dataIn计算后的参数、dataOut$.actionOutput.data.raw、status、errorDetails写入execution_steps表供 UI 展示与后续步骤使用。因此$.setActionItem({ raw: response.data })中response.data的形态直接决定了该步骤在 UI 中展示的 JSON以及下游步骤能引用到的数据结构。第五步在 Automatisch UI 中测试 Action完成代码后按以下步骤验证进入 Automatisch 的 flows 页面创建一个新的 flow添加Search cat images作为 flow 的触发器Trigger添加Mark the cat image as favorite作为 flow 的第二步Action在 Action 的Image ID参数中填入一个从 Cat API 获取到的图片 ID点击Test Continue按钮。如果在界面中看到 JSON 响应说明我们构建的触发器和 Action 都能正常工作。测试运行test run模式下引擎会把本次执行标记为testRun方便你随时重试而不影响正式执行记录。参考仓库中的真实 Action 实战除了教程示例仓库中有大量生产可用的 Action 实现可对照学习Create issue展示了必填参数校验throw new Error(A repo must be set!)、参数解析与动态下拉的完整组合。Custom request展示了大文件响应限制25MB、二进制响应 Base64 编码、动态 Headers 参数等进阶处理是编写通用型 Action 的范本。Slack 四个 Action多 Action App 的典型目录与导出结构。结合 folder-structure.md、triggers.md 与 examples.md你可以把定义元数据 实现 run 注册导出 UI 验证这条链路完整落地从而为任意第三方服务构建出高质量的 Automatisch 集成。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考