企业官网建设流程全解析

Automatisch HubSpot 应用操作（Actions）实战指南：创建与更新联系人详解

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch

本指南以 Automatisch 开源仓库中的 HubSpot 应用文档（actions.md）为主体，系统讲解 HubSpot 集成模块提供的两大联系人操作——Create a contact（创建联系人）与Update contact（更新联系人）。文章从自动化工作流接入的实际场景出发，完整还原文档定义的操作清单，并结合后端源码逐字段剖析参数映射、HubSpot CRM API 调用细节与 OAuth 连接前置条件，帮助读者快速掌握在 Automatisch 中配置、测试与运维 HubSpot 联系人操作的完整方法。

一、操作清单总览：文档定义的两个联系人动作

在 Automatisch 中，HubSpot 应用的操作（Actions）注册于应用目录packages/backend/src/apps/hubspot/actions/。官方文档 actions.md 明确列出了当前应用支持的两个操作：

这一清单与源码完全一致：应用目录下的动作聚合文件 packages/backend/src/apps/hubspot/actions/index.js 导入并导出两个动作——createContact与updateContact：

import createContact from './create-contact/index.js'; import updateContact from './update-contact/index.js'; export default [createContact, updateContact];

而从应用级入口 packages/backend/src/apps/hubspot/index.js 可以看到，HubSpot 应用通过defineApp注册，actions字段将上述动作列表接入整个 Automatisch 引擎，supportsConnections: true表明该应用使用 OAuth 连接（Connection）体系，动作只有在建立有效连接后才能执行。

二、前置条件：为操作建立 HubSpot 连接

两个联系人操作都依赖 Automatisch 的“连接”机制（Connection）——即通过 OAuth 2.0 授权码流程获取 HubSpot 的访问令牌。官方连接指南 connection.md 给出了完整步骤，操作前请确保完成以下要点：

1. 前往 HubSpot Developer 页面 注册开发者账号；
2. 创建 Public app，并在Auth标签页中把 Automatisch 连接创建页面显示的OAuth Redirect URL填入 HubSpot 的Redirect URL(s)字段；
3. 在Scopes标签页中勾选所需的权限范围，然后创建 App；
4. 复制Client ID与Client Secret，在 Automatisch 中分别粘贴到对应输入框并提交；
5. 完成授权后即可在流程中使用 HubSpot 连接。

OAuth 回调地址由应用认证配置动态生成，源码 packages/backend/src/apps/hubspot/auth/index.js 中定义其值为{WEB_APP_URL}/app/hubspot/connections/add，并带有clickToCopy标记方便复制。该认证配置要求三个字段：oAuthRedirectUrl（只读，自动生成）、clientId、clientSecret（后两者为必填）。

Scopes 说明（与操作的直接关联）：HubSpot 的授权范围定义在 packages/backend/src/apps/hubspot/common/scopes.js：

const scopes = ['crm.objects.contacts.read', 'crm.objects.contacts.write'];

可以看到，应用申请的是 CRM 联系人对象的读与写权限，这与本篇文章的两个动作（创建、更新联系人）所需能力完全匹配：crm.objects.contacts.write用于创建与更新请求，crm.objects.contacts.read则用于授权验证阶段读取访问令牌信息等校验逻辑。

令牌的获取与自动刷新：连接建立时，packages/backend/src/apps/hubspot/auth/verify-credentials.js 会以authorization_code授权方式向POST /oauth/v1/token换取access_token、refresh_token与expires_in，随后调用getAccessTokenInfo拉取用户、Hub 域、scopes 等信息并写入$.auth。此后每次请求都会由前置拦截器 packages/backend/src/apps/hubspot/common/add-auth-header.js 自动附加Authorization: Bearer <accessToken>请求头；令牌过期时则由refreshToken流程自动续期。因此，在流程编排中无需手动管理令牌，只需保证连接处于“已验证”状态即可。

三、Create a contact：创建联系人操作详解

3.1 参数定义

创建联系人动作的源码位于 packages/backend/src/apps/hubspot/actions/create-contact/index.js，通过defineAction定义。其对外暴露 7 个参数，全部为string类型且均可选（required: false），同时均开启了variables: true，意味着可以在流程编辑器中使用上游步骤的输出变量、全局变量等进行动态填充：

3.2 请求构造与字段映射

动作的run函数从$.step.parameters读取各参数值，然后向 HubSpot CRM API 发起POST /crm/v3/objects/contacts请求。核心实现如下：

const response = await $.http.post('/crm/v3/objects/contacts', { properties: { company, email, firstname: firstName, lastname: lastName, phone, website, hubspot_owner_id: hubspotOwnerId, }, }); $.setActionItem({ raw: response.data });

值得注意的字段映射细节：

• 表单参数使用 camelCase（如firstName、lastName、hubspotOwnerId），而发送到 HubSpot 的请求体properties使用 HubSpot 标准属性名（snake_case：firstname、lastname、hubspot_owner_id），中间存在一次命名转换；
• 请求体未做空值过滤，未填写的参数会以undefined形式被序列化，HubSpot 会忽略空属性；
• 请求发往api.hubapi.com（见应用注册时的apiBaseUrl: 'https://api.hubapi.com'，packages/backend/src/apps/hubspot/index.js）；
• 创建成功后，$.setActionItem({ raw: response.data })将 API 返回的完整响应（含新联系人的id、properties、createdAt等字段）写入执行结果，作为后续步骤可引用的数据源。

3.3 典型使用场景

创建联系人操作适合作为工作流的“写入末端”或“同步环节”，例如：

• 当 Webhook 或表单触发器收到新客户线索（Lead）时，自动在 HubSpot 创建联系人；
• 将其他应用（如 Google Sheets、Gmail）中的客户数据批量同步为 HubSpot 联系人；
• 与条件判断（filter）配合，仅在满足特定条件时创建联系人。

四、Update contact：更新联系人操作详解

4.1 参数定义

更新联系人动作位于 packages/backend/src/apps/hubspot/actions/update-contact/index.js。与创建操作相比，它额外要求一个必填参数，其余 7 个可填字段与创建操作完全一致：

4.2 请求构造与字段映射

更新操作的核心差异有两点：一是使用PATCH /crm/v3/objects/contacts/{contactId}请求；二是只提交有值的字段。源码在构造properties对象时逐一判空：

const properties = {}; if (company !== undefined) properties.company = company; if (email !== undefined) properties.email = email; if (firstName !== undefined) properties.firstname = firstName; if (lastName !== undefined) properties.lastname = lastName; if (phone !== undefined) properties.phone = phone; if (website !== undefined) properties.website = website; if (hubspotOwnerId !== undefined) properties.hubspot_owner_id = hubspotOwnerId; const response = await $.http.patch( `/crm/v3/objects/contacts/${contactId}`, { properties } ); $.setActionItem({ raw: response.data });

这一设计避免了部分更新场景下未填字段被意外清空的问题——与创建操作“整体提交”不同，更新操作是真正的增量更新（partial update），只有显式传入的字段才会进入请求体。字段命名同样遵循 camelCase → snake_case 的映射（firstname、lastname、hubspot_owner_id）。

4.3 典型使用场景

更新操作适合需要“按 ID 修改既有记录”的工作流，例如：

• 联系人信息变更事件（如来源系统更新了邮箱/电话）触发后，依据 Contact ID 同步修改 HubSpot 中的对应联系人；
• 多个上游分支各自修改同一联系人的不同字段，利用增量更新避免相互覆盖；
• 与“创建联系人”配合，实现“存在则更新、不存在则创建”的 upsert 式同步逻辑。

五、执行结果与后续步骤引用

两个操作在执行成功后都调用$.setActionItem({ raw: response.data })，将 HubSpot API 的原始响应作为该步骤的“动作项（action item）”输出。在流程编辑器中，后续步骤可以引用这些输出字段，例如：

• 创建操作返回的id可作为后续“更新联系人”步骤的contactId；
• 返回的properties中的email、createdAt、updatedAt等字段可用于通知、日志或下游应用。

从源码结构看，动作响应由 Automatisch 引擎统一收集并写入执行记录（Execution），可在执行详情页查看每个步骤的输入输出原始数据，便于排障与调试。

六、配置与使用要点小结

1. 先建连接，再配动作：创建/更新联系人操作强依赖有效的 HubSpot OAuth 连接，请先按 connection.md 完成 App 注册与授权；
2. 权限范围：应用固定申请crm.objects.contacts.read与crm.objects.contacts.write两个 scope（scopes.js），这与联系人操作的读写需求一一对应，若后续扩展其他 CRM 对象（如公司、交易）需要同步扩展 scope 与动作定义；
3. 参数映射规则：界面参数为 camelCase，发送给 HubSpot 的属性名为 snake_case，注意firstName → firstname、lastName → lastname、hubspotOwnerId → hubspot_owner_id；
4. 创建 vs 更新：创建使用POST全量提交；更新使用PATCH且仅提交已填字段，避免误清空已有数据；
5. 动态变量：所有参数均支持variables: true，可在编排时引用上游输出或全局变量，适合构建数据驱动的自动化流程。

通过本文，读者应能完整理解 Automatisch 中 HubSpot 应用两个联系人操作的参数体系、底层 API 调用与最佳实践，并可直接在自己的流程中配置使用。

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch