Skip to content

构建编程式节点#

本教程将指导您构建一个编程式节点。开始之前，请确保这是您需要的节点类型。更多信息请参考选择节点构建方法。

先决条件#

您的开发机器上需要安装以下软件：

  • git
  • Node.js 和 npm。最低版本要求 Node 18.17.0。Linux、Mac 和 WSL 用户可以通过 nvm (Node Version Manager) 安装，具体步骤参见此处。Windows 用户请参考微软的在 Windows 上安装 NodeJS指南。

您需要了解以下知识：

  • JavaScript/TypeScript
  • REST API
  • git
  • n8n 中的表达式

构建您的节点#

在本节中，您将克隆 n8n 的节点入门仓库，并构建一个集成 SendGrid 的节点。您将创建一个实现 SendGrid 一项功能的节点：创建联系人。

现有节点

n8n 已内置 SendGrid 节点。为避免与现有节点冲突，您需要为您的版本使用不同的名称。

第一步：项目设置#

n8n 为节点开发提供了启动仓库。使用该模板可确保您拥有所有必要的依赖项，同时还提供了代码检查工具。

克隆仓库并进入目录：

  1. 从模板仓库生成新仓库
  2. 克隆您的新仓库： 
    1
2
    git clone https://github.com/<your-organization>/<your-repo-name>.git n8n-nodes-friendgrid
cd n8n-nodes-friendgrid

启动模板包含示例节点和凭据。请删除以下目录和文件：

  • nodes/ExampleNode
  • nodes/HTTPBin
  • credentials/ExampleCredentials.credentials.ts
  • credentials/HttpBinApi.credentials.ts

现在创建以下目录和文件：

nodes/FriendGrid
nodes/FriendGrid/FriendGrid.node.json
nodes/FriendGrid/FriendGrid.node.ts
credentials/FriendGridApi.credentials.ts

这些是任何节点所需的关键文件。有关必需文件和推荐组织结构的更多信息，请参阅节点文件结构。

接下来安装项目依赖：

1
npm i

第二步：添加图标#

从此处下载 SendGrid SVG 徽标，保存为 friendGrid.svg 并放入 nodes/FriendGrid/ 目录。

n8n 推荐使用 SVG 格式作为节点图标，但也可以使用 PNG 格式。如果使用 PNG，图标分辨率应为 60x60 像素。节点图标应保持正方形或接近正方形的宽高比。

不要引用 Font Awesome

如果要在节点中使用 Font Awesome 图标，请下载并嵌入该图像。

第三步：在基础文件中定义节点#

每个节点都必须有一个基础文件。关于基础文件参数的详细信息，请参考节点基础文件。

在本示例中，文件名为 FriendGrid.node.ts。为了使本教程简洁，我们将所有节点功能都放在这一个文件中。当构建更复杂的节点时，您应该考虑将功能拆分到不同模块中。更多信息请参考节点文件结构。

第三步.1：导入声明#

首先添加导入语句：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import {
	IExecuteFunctions,
} from 'n8n-core';

import {
	IDataObject,
	INodeExecutionData,
	INodeType,
	INodeTypeDescription,
} from 'n8n-workflow';

import {
	OptionsWithUri,
} from 'request';

第三步.2：创建主类#

节点必须导出一个实现 INodeType 的接口。该接口必须包含一个 description 接口，而该接口又包含 properties 数组。

类名与文件名

确保类名与文件名匹配。例如，给定类名 FriendGrid，文件名必须是 FriendGrid.node.ts。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
export class FriendGrid implements INodeType {
	description: INodeTypeDescription = {
		// 基础节点详情将放在这里
		properties: [
			// 资源和操作将放在这里
		],
	};
	// execute 方法将放在这里
	async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
	}
}

步骤 3.3：添加节点详情#

所有编程式节点都需要一些基本参数，例如显示名称和图标。在 description 中添加以下内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
displayName: 'FriendGrid',
name: 'friendGrid',
icon: 'file:friendGrid.svg',
group: ['transform'],
version: 1,
description: '使用 SendGrid API',
defaults: {
	name: 'FriendGrid',
},
inputs: ['main'],
outputs: ['main'],
credentials: [
	{
		name: 'friendGridApi',
		required: true,
	},
],

n8n 使用 description 中设置的部分属性在编辑器 UI 中渲染节点。这些属性包括 displayName、icon 和 description。

步骤 3.4：添加资源#

资源对象定义了节点使用的 API 资源。在本教程中，您将创建一个节点来访问 SendGrid 的一个 API 端点：/v3/marketing/contacts。这意味着您需要为这个端点定义一个资源。使用资源对象更新 properties 数组：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
	displayName: '资源',
	name: 'resource',
	type: 'options',
	options: [
		{
			name: '联系人',
			value: 'contact',
		},
	],
	default: 'contact',
	noDataExpression: true,
	required: true,
	description: '创建新联系人',
},

type 控制 n8n 为资源显示的 UI 元素，并告知 n8n 预期从用户那里获取什么类型的数据。options 会导致 n8n 添加一个下拉菜单，允许用户选择一个选项。更多信息请参考节点 UI 元素。

步骤 3.5：添加操作#

operations 对象定义了可以对资源执行的操作。它通常对应 REST API 的动词（GET、POST 等）。在本教程中，我们有一个操作：创建联系人。该操作有一个必填字段，即用户创建的联系人电子邮件地址。

在 resource 对象之后，将以下内容添加到 properties 数组中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
	displayName: '操作',
	name: 'operation',
	type: 'options',
	displayOptions: {
		show: {
			resource: [
				'contact',
			],
		},
	},
	options: [
		{
			name: 'Create',
			value: 'create',
			description: '创建联系人',
			action: '创建联系人',
		},
	],
	default: 'create',
	noDataExpression: true,
},
{
	displayName: '邮箱',
	name: 'email',
	type: 'string',
	required: true,
	displayOptions: {
		show: {
			operation: [
				'create',
			],
			resource: [
				'contact',
			],
		},
	},
	default:'',
	placeholder: 'name@email.com',
	description:'联系人的主要邮箱地址',
},

步骤 3.6：添加可选字段#

大多数 API（包括本示例中使用的 SendGrid API）都提供可选字段来优化查询。

为了避免用户界面过于复杂，n8n 会在 UI 中将这些字段显示在 附加字段 部分。

在本教程中，我们将添加两个附加字段，允许用户输入联系人的名和姓。将以下内容添加到 properties 数组中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
	displayName: '附加字段',
	name: 'additionalFields',
	type: 'collection',
	placeholder: '添加字段',
	default: {},
	displayOptions: {
		show: {
			resource: [
				'contact',
			],
			operation: [
				'create',
			],
		},
	},
	options: [
		{
			displayName: '名',
			name: 'firstName',
			type: 'string',
			default: '',
		},
		{
			displayName: '姓',
			name: 'lastName',
			type: 'string',
			default: '',
		},
	],
},

步骤4：添加 execute 方法#

您已经设置了节点 UI 和基本信息。现在是时候将节点 UI 映射到 API 请求，让节点真正发挥作用了。

execute 方法在每次节点运行时执行。在这个方法中，您可以访问输入项和用户在 UI 中设置的参数，包括凭据。

在 FriendGrid.node.ts 中添加以下 execute 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// 处理来自前一个节点的数据
const items = this.getInputData();
let responseData;
const returnData = [];
const resource = this.getNodeParameter('resource', 0) as string;
const operation = this.getNodeParameter('operation', 0) as string;

// 为每个项目创建 API 调用以创建联系人
for (let i = 0; i < items.length; i++) {
	if (resource === 'contact') {
		if (operation === 'create') {
			// 获取 email 输入
			const email = this.getNodeParameter('email', i) as string;
			// 获取附加字段输入
			const additionalFields = this.getNodeParameter('additionalFields', i) as IDataObject;
			const data: IDataObject = {
				email,
			};

			Object.assign(data, additionalFields);

			// 根据 https://sendgrid.com/docs/api-reference/ 发起 HTTP 请求
			const options: OptionsWithUri = {
				headers: {
					'Accept': 'application/json',
				},
				method: 'PUT',
				body: {
					contacts: [
						data,
					],
				},
				uri: `https://api.sendgrid.com/v3/marketing/contacts`,
				json: true,
			};
			responseData = await this.helpers.requestWithAuthentication.call(this, 'friendGridApi', options);
			returnData.push(responseData);
		}
	}
}
// 将数据映射到 n8n 数据结构
return [this.helpers.returnJsonArray(returnData)];

注意以下代码行：

1
2
3
4
5
6
7
const items = this.getInputData();
... 
for (let i = 0; i < items.length; i++) {
	...
	const email = this.getNodeParameter('email', i) as string;
	...
}

用户可以通过两种方式提供数据：

  • 直接在节点字段中输入
  • 通过映射工作流中先前节点的数据

getInputData() 和后续循环允许节点处理数据来自前一个节点的情况。这包括支持多个输入。这意味着，例如，如果前一个节点输出了五个人的联系信息，您的 FriendGrid 节点可以创建五个联系人。

步骤5：设置认证#

SendGrid API 要求用户使用 API 密钥进行身份验证。

将以下内容添加到 FriendGridApi.credentials.ts 文件中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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 将其称为 codex 文件。在本示例中，文件名为 FriendGrid.node.json。

将以下代码添加到 JSON 文件中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
	"node": "n8n-nodes-base.FriendGrid",
	"nodeVersion": "1.0",
	"codexVersion": "1.0",
	"categories": [
		"Miscellaneous"
	],
	"resources": {
		"credentialDocumentation": [
			{
				"url": ""
			}
		],
		"primaryDocumentation": [
			{
				"url": ""
			}
		]
	}
}

有关这些参数的更多信息，请参阅节点 codex 文件。

步骤 7：更新 npm 包信息#

您的 npm 包信息位于项目根目录的 package.json 文件中。必须包含带有凭证和基础节点文件链接的 n8n 对象。更新该文件以包含以下信息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
	// 所有节点名称必须以 "n8n-nodes-" 开头
	"name": "n8n-nodes-friendgrid",
	"version": "0.1.0",
	"description": "用于在 SendGrid 中创建联系人的 n8n 节点",
	"keywords": [
		// 此关键词是社区节点的必需项
		"n8n-community-node-package"
	],
	"license": "MIT",
	"homepage": "https://n8n.io",
	"author": {
		"name": "测试",
		"email": "test@example.com"
	},
	"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 文档。

测试您的节点#

在构建节点时，您可以通过在本地 n8n 实例中运行来测试它。

  1. 使用 npm 安装 n8n： 
    1
    npm install n8n -g
  2. 准备测试节点时，将其发布到本地： 
    1
2
3
    # 在您的节点目录中
npm run build
npm link

  3. 将节点安装到本地 n8n 实例： 

    1
2
3
    # 在 n8n 安装目录内的 nodes 文件夹中
# node-package-name 是 package.json 中的名称
npm link <node-package-name>

    检查目录

    确保您在 n8n 安装目录内的 nodes 文件夹中运行 npm link <node-name>。可能的路径包括：

    • ~/.n8n/custom/
    • ~/.n8n/<your-custom-name>：如果您的 n8n 安装使用 N8N_CUSTOM_EXTENSIONS 设置了不同的名称。

  4. 启动 n8n： 

    1
    n8n start

  5. 在浏览器中打开 n8n。在节点面板中搜索时应该能看到您的节点。

    节点名称

    请确保使用节点名称而非包名称进行搜索。例如，如果您的 npm 包名是 n8n-nodes-weather-nodes，而包中包含名为 rain、sun、snow 的节点，您应该搜索 rain 而不是 weather-nodes。

故障排除#

  • 本地安装的 ~/.n8n 中没有 custom 目录

您需要手动创建 custom 目录并运行 npm init 

1
2
3
4
# 在 ~/.n8n 目录中运行
mkdir custom 
cd custom 
npm init

后续步骤#