在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

n8n-io/n8n

菜单

服务集成节点

相关源文件

此页面记录了n8n中服务集成节点的架构和实现。服务集成节点允许用户通过各自的API连接到Pipedrive、Asana、GitHub等外部服务。这些节点既支持基于操作（创建、读取、更新、删除数据）的操作，也支持基于触发器（当外部服务中发生事件时启动工作流）的操作。

有关HTTP请求节点的信息，请参阅HTTP请求节点。有关AI工具集成的信息，请参阅AI工具集成。

服务集成节点概览

服务集成节点是连接到特定第三方服务的专用节点类型。它们通过提供预先构建的操作和用户友好的API请求配置界面，来抽象化API交互的复杂性。

来源

服务集成节点的通用结构

服务集成节点在其实现中遵循一致的模式

  1. 节点类：每个服务都有一个实现INodeType接口的主类
  2. 节点描述：定义节点的属性、操作和用户界面
  3. 通用函数：API通信的辅助函数
  4. 凭证：服务的身份验证机制
  5. 触发器节点：处理服务 webhook 的可选伴随节点

节点类结构

来源

认证机制

服务集成节点支持多种身份验证方法

  1. API密钥/令牌：使用标题或查询参数中的令牌进行简单身份验证
  2. OAuth2：更安全的身份验证流程，具有令牌刷新功能
  3. 基本身份验证：用户名/密码身份验证，用于 webhook 安全

来源

通用函数模式

大多数服务集成节点都实现了一组用于API通信的辅助函数

  1. API请求函数：向服务 API 发出单个请求
  2. 请求所有项目函数：处理分页以检索多个项目
  3. 自定义辅助函数：特定于服务的实用程序，用于数据转换

来源

节点属性和操作

服务集成节点通过INodeTypeDescription接口定义其用户界面和功能

  1. 资源选择：选择要操作的实体（例如，交易、联系人）
  2. 操作选择：选择要执行的操作（例如，创建、更新、获取）
  3. 参数配置：操作的输入字段
  4. 附加字段：用于高级配置的可选参数

节点结构示例

属性描述
资源要操作的实体类型（例如，交易、联系人、任务）
操作要执行的操作（例如，create、update、get、getAll）
必需字段操作必须提供的参数
附加字段操作的可选参数

来源

触发器节点

触发器节点是伴随节点，它允许工作流由外部服务的事件启动。它们实现了 webhook 功能

  1. Webhook 注册：在外部服务中创建 webhook
  2. Webhook 验证：验证 webhook 的存在和真实性
  3. Webhook 处理：处理传入的 webhook 数据

来源

实现示例

Pipedrive 集成

Pipedrive 集成展示了一个全面的服务集成，包含操作节点和触发器节点

  1. Pipedrive 节点：处理交易、联系人、活动等的操作。
  2. Pipedrive 触发器节点：在 Pipedrive 事件上启动工作流
  3. 通用函数：处理 API 通信和数据转换
  4. 凭证：支持 API 令牌和 OAuth2 身份验证

来源

GitHub 触发器节点

GitHub 触发器节点是基于 webhook 的触发器实现的良好示例

  1. 事件选择：选择要监听的 GitHub 事件
  2. 存储库选择：选择要监视的存储库
  3. Webhook 管理：注册、验证和删除 webhook
  4. 事件处理：处理传入的 webhook 数据

来源

常见模式和最佳实践

错误处理

服务集成节点实现了一致的错误处理

  1. API 错误处理：将 API 错误转换为 n8n NodeApiError
  2. 验证：在发出请求之前验证必需的参数
  3. Webhook 验证：确保 webhook 已正确注册和身份验证

动态选项加载

许多服务集成节点为下拉菜单实现了动态选项加载

  1. 加载选项方法：从 API 获取可用选项
  2. 依赖选项：根据先前的选择加载选项
  3. 搜索功能：允许在大型数据集中搜索选项

来源

自定义属性处理

某些服务（如Pipedrive）支持自定义字段，这需要特殊的处理

  1. 自定义属性解析：获取自定义字段定义
  2. 值映射：在 API 值和用户友好值之间进行映射
  3. 自定义属性编码：将自定义属性转换为 API 格式

来源

结论

服务集成节点为将n8n连接到外部服务提供了统一的模式。它们抽象化了API交互的复杂性，同时提供了丰富的操作和配置选项。操作节点用于操作，触发器节点用于事件，这种组合使得与外部服务的全面集成成为可能。

主要组成部分包括：

  • 实现INodeType接口的节点类
  • 用于API通信的通用函数
  • 用于身份验证的凭证处理
  • 用于触发器节点的Webhook方法
  • 用于改善用户体验的动态选项加载

这种架构允许轻松添加新的服务集成，同时保持不同服务之间一致的用户体验。