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 明确列出了当前应用支持的两个操作操作名称说明Create a contact在 HubSpot 中创建一个新的联系人Creates a contact.Update contact更新一个已存在的联系人Updates an existing contact.这一清单与源码完全一致应用目录下的动作聚合文件 packages/backend/src/apps/hubspot/actions/index.js 导入并导出两个动作——createContact与updateContactimport 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 给出了完整步骤操作前请确保完成以下要点前往 HubSpot Developer 页面 注册开发者账号创建 Public app并在Auth标签页中把 Automatisch 连接创建页面显示的OAuth Redirect URL填入 HubSpot 的Redirect URL(s)字段在Scopes标签页中勾选所需的权限范围然后创建 App复制Client ID与Client Secret在 Automatisch 中分别粘贴到对应输入框并提交完成授权后即可在流程中使用 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.jsconst 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意味着可以在流程编辑器中使用上游步骤的输出变量、全局变量等进行动态填充参数 Label参数 Key是否必填说明Company namecompany否公司名称Emailemail否邮箱地址First namefirstName否名Last namelastName否姓Phonephone否电话号码Website URLwebsite否网站地址Owner IDhubspotOwnerId否HubSpot 联系人所有者OwnerID3.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_casefirstname、lastname、hubspot_owner_id中间存在一次命名转换请求体未做空值过滤未填写的参数会以undefined形式被序列化HubSpot 会忽略空属性请求发往api.hubapi.com见应用注册时的apiBaseUrl: https://api.hubapi.compackages/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 个可填字段与创建操作完全一致参数 Label参数 Key是否必填说明Contact IDcontactId是待更新联系人的 IDHubSpot 对象 IDCompany namecompany否公司名称Emailemail否邮箱地址First namefirstName否名Last namelastName否姓Phonephone否电话号码Website URLwebsite否网站地址Owner IDhubspotOwnerId否HubSpot 联系人所有者OwnerID4.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可在执行详情页查看每个步骤的输入输出原始数据便于排障与调试。六、配置与使用要点小结先建连接再配动作创建/更新联系人操作强依赖有效的 HubSpot OAuth 连接请先按 connection.md 完成 App 注册与授权权限范围应用固定申请crm.objects.contacts.read与crm.objects.contacts.write两个 scopescopes.js这与联系人操作的读写需求一一对应若后续扩展其他 CRM 对象如公司、交易需要同步扩展 scope 与动作定义参数映射规则界面参数为 camelCase发送给 HubSpot 的属性名为 snake_case注意firstName → firstname、lastName → lastname、hubspotOwnerId → hubspot_owner_id创建 vs 更新创建使用POST全量提交更新使用PATCH且仅提交已填字段避免误清空已有数据动态变量所有参数均支持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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
