构建一个编程式节点
本教程将逐步介绍如何构建编程式节点。开始之前,请确保这是您需要的节点样式。请参阅选择您的节点构建方法 了解更多信息。
先决条件
您需要在开发机器上安装以下内容:
- git
- Node.js 和 npm。Node.js 最低版本为 24。您可以在nvm 安装说明{:target=_blank class=.external-link}找到使用 nvm(Node 版本管理器)为 Linux、Mac 和 WSL 安装两者的说明。对于 Windows 用户,请参考 Microsoft 的在 Windows 上安装 NodeJS{:target=_blank class=.external-link} 指南。
您需要对以下内容有一定了解:
- JavaScript/TypeScript
- REST API
- Git
- n8n 中的表达式[^1]
构建您的节点
在本节中,您将克隆 n8n 的节点启动器仓库,并构建一个集成 SendGrid{:target=_blank .external-link} 的节点。您将创建一个实现 SendGrid 功能的节点:创建联系人。
提示
Existing node 现有节点
n8n 有一个内置的 SendGrid 节点。为了避免与现有节点发生冲突,您将为您的版本指定一个不同的名称。
第 1 步:设置项目
n8n 为节点开发提供了一个启动器仓库。使用启动器确保您拥有所有必要的依赖项。它还提供了一个检查器。
克隆仓库并导航到目录:
- 从模板仓库生成新仓库{:target=_blank .external-link}。
- 克隆您的新仓库:
shell git clone https://github.com/<your-organization>/<your-repo-name>.git n8n-nodes-friendgrid cd n8n-nodes-friendgrid
启动器包含示例节点和凭据。删除以下目录和文件:
nodes/Examplenodes/GithubIssuescredentials/GithubIssuesApi.credentials.tscredentials/GithubIssuesOAuth2Api.credentials.ts
现在创建以下目录和文件:
nodes/FriendGrid
nodes/FriendGrid/FriendGrid.node.json
nodes/FriendGrid/FriendGrid.node.ts
credentials/FriendGridApi.credentials.ts
这些是所有节点都需要的关键文件。有关必需文件和推荐组织方式的更多信息,请参阅节点文件结构。
现在安装项目依赖项:
npm i
步骤 2:添加图标
从SendGrid SVG 标志{:target=_blank .external-link}保存 SendGrid SVG 徽标,作为 friendGrid.svg 保存在 nodes/FriendGrid/ 中。
n8n 建议使用 SVG 作为节点图标,但您也可以使用 PNG。如果使用 PNG,图标分辨率应为 60x60px。节点图标应具有正方形或接近正方形的长宽比。
提示
Don't reference Font Awesome 不要引用 Font Awesome
如果要在节点中使用 Font Awesome 图标,请下载并嵌入该图像。不要设置 defaults.color:它只能为 Font Awesome 图标着色,且 n8n 3.0 已将其移除。
步骤3:在基础文件中定义节点
每个节点都必须有一个基本文件。基础文件参数的详细信息请参考节点基础文件。
在此示例中,文件为 FriendGrid.node.ts。为了使本教程简短,您将把所有节点功能放在这个文件中。当构建更复杂的节点时,您应该考虑将功能拆分为模块。有关更多信息,请参阅节点文件结构。
步骤 3.1:导入
首先添加导入语句:
import type {
IDataObject,
IExecuteFunctions,
IHttpRequestOptions,
INodeExecutionData,
INodeType,
INodeTypeDescription,
} from 'n8n-workflow';
import { NodeConnectionTypes } from 'n8n-workflow';
步骤 3.2:创建主类
节点必须导出一个实现 INodeType 的接口。此接口必须包含一个 description 接口,该接口又包含 properties 数组。
提示
Class names and file names 类名和文件名
确保类名和文件名匹配。例如,给定类 FriendGrid,文件名必须是 FriendGrid.node.ts。
export class FriendGrid implements INodeType {
description: INodeTypeDescription = {
// 基本节点详细信息将放在这里
properties: [
// 资源和操作将放在这里
],
};
// 执行方法将放在这里
async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
}
}
步骤 3.3:添加节点详细信息
所有编程式节点都需要一些基本参数,如显示名称和图标。将以下内容添加到 description 中:
displayName: 'FriendGrid',
name: 'friendGrid',
icon: 'file:friendGrid.svg',
group: ['transform'],
version: 1,
description: 'Consume SendGrid API',
defaults: {
name: 'FriendGrid',
},
inputs: [NodeConnectionTypes.Main],
outputs: [NodeConnectionTypes.Main],
usableAsTool: true,
credentials: [
{
name: 'friendGridApi',
required: true,
},
],
n8n 使用 description 中设置的一些属性在编辑器 UI 中渲染节点。这些属性是 displayName、icon 和 description。
步骤3.4:添加资源
资源对象定义节点使用的 API 资源。在本教程中,您正在创建一个节点来访问 SendGrid 的 API 端点之一:/v3/marketing/contacts。这意味着您需要为此端点定义一个资源。使用资源对象更新 properties 数组:
{
displayName: 'Resource',
name: 'resource',
type: 'options',
options: [
{
name: 'Contact',
value: 'contact',
},
],
default: 'contact',
noDataExpression: true,
required: true,
description: 'Create a new contact',
},
type 控制 n8n 为资源显示哪个 UI 元素,并告诉 n8n 期望从用户那里获得什么类型的数据。 options 导致 n8n 添加一个下拉菜单,允许用户选择一个选项。更多信息请参考 Node UI 元素。
步骤3.5:添加操作
操作对象定义您可以对资源执行的操作。它通常与 REST API 动词(GET、POST 等)相关。在本教程中,有一个操作:创建联系人。它有一个必需字段,即用户创建的联系人的电子邮件地址。
将以下内容添加到 properties 数组中,在 resource 对象之后:
{
displayName: 'Operation',
name: 'operation',
type: 'options',
displayOptions: {
show: {
resource: [
'contact',
],
},
},
options: [
{
name: 'Create',
value: 'create',
description: 'Create a contact',
action: 'Create a contact',
},
],
default: 'create',
noDataExpression: true,
},
{
displayName: 'Email',
name: 'email',
type: 'string',
required: true,
displayOptions: {
show: {
operation: [
'create',
],
resource: [
'contact',
],
},
},
default:'',
placeholder: '[email protected]',
description:'Primary email for the contact',
},
步骤 3.6:添加可选字段
大多数 API,包括您在此示例中使用的 SendGrid API,都有可选字段,您可以使用这些字段来优化查询。
为了避免让用户感到不知所措,n8n 在 UI 中的附加字段下显示这些字段。
对于本教程,您将添加两个附加字段,以允许用户输入联系人的名字和姓氏。将以下内容添加到 properties 数组:
{
displayName: 'Additional Fields',
name: 'additionalFields',
type: 'collection',
placeholder: 'Add Field',
default: {},
displayOptions: {
show: {
resource: [
'contact',
],
operation: [
'create',
],
},
},
options: [
{
displayName: 'First Name',
name: 'firstName',
type: 'string',
default: '',
},
{
displayName: 'Last Name',
name: 'lastName',
type: 'string',
default: '',
},
],
},
步骤4:添加执行方法
您已经设置了节点 UI 和基本信息。现在是时候将节点 UI 映射到 API 请求,并让节点实际执行某些操作了。
execute 方法在每次节点运行时运行。在此方法中,您可以访问输入项目和用户在 UI 中设置的参数,包括凭据。
将以下内容添加到 FriendGrid.node.ts 中的 execute 方法:
// 处理来自前一个节点的数据
const items = this.getInputData();
let responseData;
const returnData: INodeExecutionData[] = [];
const resource = this.getNodeParameter('resource', 0);
const operation = this.getNodeParameter('operation', 0);
// 对于每个项目,进行 API 调用以创建联系人
for (let i = 0; i < items.length; i++) {
try {
if (resource === 'contact') {
if (operation === 'create') {
// 获取电子邮件输入
const email = this.getNodeParameter('email', i);
// 获取附加字段输入
const additionalFields = this.getNodeParameter('additionalFields', i);
const data: IDataObject = {
email,
};
Object.assign(data, additionalFields);
// 根据 https://sendgrid.com/docs/api-reference/ 进行 HTTP 请求
const options: IHttpRequestOptions = {
headers: {
'Accept': 'application/json',
},
method: 'PUT',
body: {
contacts: [
data,
],
},
url: 'https://api.sendgrid.com/v3/marketing/contacts',
json: true,
};
responseData = await this.helpers.httpRequestWithAuthentication.call(this, 'friendGridApi', options);
const executionData = this.helpers.constructExecutionMetaData(
this.helpers.returnJsonArray(responseData as IDataObject),
{ itemData: { item: i } },
);
returnData.push.apply(returnData, executionData);
}
}
} catch (error) {
if (this.continueOnFail()) {
const executionData = this.helpers.constructExecutionMetaData(
this.helpers.returnJsonArray({ error: error.message }),
{ itemData: { item: i } },
);
returnData.push.apply(returnData, executionData);
continue;
}
throw error;
}
}
return [returnData];
注意此代码的以下行:
const items = this.getInputData();
...
for (let i = 0; i < items.length; i++) {
...
const email = this.getNodeParameter('email', i);
...
}
用户可以通过两种方式提供数据:
- 直接在节点字段中输入
- 通过映射工作流中早期节点的数据
getInputData() 和随后的循环允许节点处理数据来自前一个节点的情况。这包括支持多个输入。这意味着,例如,如果前一个节点输出五个人的联系信息,您的 FriendGrid 节点可以创建五个联系人。
步骤 5:设置身份验证
SendGrid API 要求用户使用 API 密钥进行身份验证。
将以下内容添加到 FriendGridApi.credentials.ts
import {
IAuthenticateGeneric,
ICredentialTestRequest,
ICredentialType,
INodeProperties,
} from 'n8n-workflow';
export class FriendGridApi implements ICredentialType {
name = 'friendGridApi';
displayName = 'FriendGrid API';
properties: INodeProperties[] = [
{
displayName: 'API Key',
name: 'apiKey',
type: 'string',
default: '',
},
];
authenticate: IAuthenticateGeneric = {
type: 'generic',
properties: {
headers: {
Authorization: '=Bearer {{$credentials.apiKey}}',
},
},
};
test: ICredentialTestRequest = {
request: {
baseURL: 'https://api.sendgrid.com/v3',
url: '/marketing/contacts',
},
};
}
有关凭证文件和选项的更多信息,请参阅凭证文件。
步骤6:添加节点元数据
关于您节点的元数据放在节点根目录的 JSON 文件中。n8n 将此称为代码库文件。在此示例中,文件是 FriendGrid.node.json。
将以下代码添加到 JSON 文件:
{
"node": "n8n-nodes-friendgrid",
"nodeVersion": "1.0",
"codexVersion": "1.0",
"categories": [
"Miscellaneous"
],
"resources": {
"credentialDocumentation": [
{
"url": ""
}
],
"primaryDocumentation": [
{
"url": ""
}
]
}
}
有关这些参数的更多信息,请参阅 Node codex 文件。
步骤 7:更新 npm 包详细信息
您的 npm 包详细信息在项目根目录的 package.json 中。包含带有凭据和基础节点文件链接的 n8n 对象是至关重要的。更新此文件以包含以下信息:
{
// 所有节点名称必须以 "n8n-nodes-" 开头
"name": "n8n-nodes-friendgrid",
"version": "0.1.0",
"description": "n8n node to create contacts in SendGrid",
"keywords": [
// 社区节点需要此关键字
"n8n-community-node-package"
],
"license": "MIT",
"homepage": "https://n8n.io",
"author": {
"name": "Test",
"email": "[email protected]"
},
"repository": {
"type": "git",
// 将 git 远程更改为您自己的仓库
// 在此添加新 URL
"url": "git+<your-repo-url>"
},
"main": "index.js",
"scripts": {
// 不要更改
},
"files": [
"dist"
],
// 链接凭据和节点
"n8n": {
"n8nNodesApiVersion": 1,
"credentials": [
"dist/credentials/FriendGridApi.credentials.js"
],
"nodes": [
"dist/nodes/FriendGrid/FriendGrid.node.js"
]
},
"devDependencies": {
// 不要更改
},
"peerDependencies": {
// 不要更改
}
}
您需要更新 package.json 以包含您自己的信息,如您的姓名和仓库 URL。有关 npm package.json 文件的更多信息,请参考 npm 的 package.json 文档{:target=_blank .external-link}。
测试您的节点
构建节点时,可以使用 n8n-node 工具在本地 n8n 实例中运行并测试节点。n8n-node 已包含 n8n,因此无需全局安装 n8n。
- 在项目根目录中运行
dev命令:shell npm run dev这会运行n8n-node dev,构建节点并将其链接到 n8n 自定义节点目录,启动已加载该节点的本地 n8n 实例,并在文件更改时重新构建节点。
提示
**自定义节点目录**
`n8n-node dev` 使用自己的 n8n 用户文件夹 `.n8n-node-cli`,因此不会影响现有的 n8n 安装。默认位置取决于操作系统:
- Windows:`C:\Users\<username>\.n8n-node-cli\.n8n\custom`
- Linux:`/home/<username>/.n8n-node-cli/.n8n/custom`
- macOS:`/Users/<username>/.n8n-node-cli/.n8n/custom`
若要使用自行运行的 n8n 实例进行测试,请传入 `--external-n8n`,并将 `--custom-user-folder <path>` 设为该实例的用户文件夹(即其 `.n8n` 目录的父目录)。在该实例上设置 `N8N_DEV_RELOAD=true`,使其能够加载你的更改。
注意:`.n8n-node-cli` 和 `.n8n` 是隐藏文件夹,因此文件浏览器可能不会显示它们。
- 在浏览器中打开
http://localhost:5678,并登录 n8n 实例。 - 打开一个工作流,然后在节点面板中搜索你的节点。
提示
**节点名称**
请确保使用节点名称而不是 package 名称进行搜索。例如,如果你的 npm package 名称是 `n8n-nodes-weather-nodes`,并且 package 包含名为 `rain`、`sun`、`snow` 的节点,应搜索 `rain`,而不是 `weather-nodes`。
将节点添加到工作流,并在开发过程中进行测试。要停止 n8n,请按 ctrl + c。
后续步骤
- 部署您的节点。
- 查看编程节点示例:n8n 的 Mattermost 节点。这是更复杂的编程节点结构的示例。
- 了解节点版本控制。
- 确保您理解关键概念:项目链接 和数据结构。
[^1]:在 n8n 中,表达式允许您通过执行 JavaScript 代码动态填充节点参数。您可以使用 n8n 表达式语法,使用来自先前节点、其他工作流程或 n8n 环境的数据来定义值,而不是提供静态值。