构建声明式节点
本教程介绍如何构建声明式节点。在开始之前，请确保这是您需要的节点样式。参考选择您的节点构建方法 了解更多信息。
前置条件
您需要在开发机器上安装以下内容：
git Node.js 和 npm。最低版本 Node 18.17.0。您可以在这里 找到使用 nvm（Node 版本管理器）为 Linux、Mac 和 WSL 安装两者的说明。对于 Windows 用户，请参考 Microsoft 的在 Windows 上安装 NodeJS 指南。
您需要对以下内容有一定了解：
JavaScript/TypeScript
REST API
git
构建您的节点
在本节中，您将克隆 n8n 的节点启动器仓库，并构建一个集成 NASA API 的节点。您将创建一个使用 NASA 两个服务的节点：APOD（每日天文图片）和火星探测器照片。为了保持代码示例简短，该节点不会实现火星探测器照片端点的每个可用选项。
现有节点
n8n 有一个内置的 NASA 节点。为了避免与现有节点冲突，您将为您的版本提供不同的名称。
步骤 1：设置项目
n8n 为节点开发提供了一个启动器仓库。使用启动器确保您拥有所有必要的依赖项。它还提供了一个检查器。
克隆仓库并导航到目录：
从模板仓库生成新仓库 。
克隆您的新仓库：
git clone https://github.com/<your-organization>/<your-repo-name>.git n8n-nodes-nasa-pics
cd n8n-nodes-nasa-pics
启动器包含示例节点和凭据。删除以下目录和文件：
nodes/ExampleNodenodes/HTTPBincredentials/ExampleCredentials.credentials.tscredentials/HttpBinApi.credentials.ts
现在创建以下目录和文件：
nodes/NasaPicsnodes/NasaPics/NasaPics.node.jsonnodes/NasaPics/NasaPics.node.tscredentials/NasaPicsApi.credentials.ts
这些是任何节点所需的关键文件。参考节点文件结构 了解更多关于必需文件和推荐组织的信息。
现在安装项目依赖项：
步骤 2：添加图标
从这里 保存 NASA SVG 徽标，作为 nasapics.svg 保存在 nodes/NasaPics/ 中。
n8n 建议为您的节点图标使用 SVG 格式，但您也可以使用 PNG。如果使用 PNG，图标分辨率应为 60x60px。节点图标应具有正方形或接近正方形的宽高比。
不要引用 Font Awesome
如果您想在节点中使用 Font Awesome 图标，请下载并嵌入图像。
步骤 3：创建节点
每个节点都必须有一个基础文件。参考节点基础文件 了解基础文件参数的详细信息。
在这个示例中，文件是 NasaPics.node.ts。为了保持本教程简短，您将把所有节点功能放在这一个文件中。在构建更复杂的节点时，您应该考虑将功能拆分到模块中。参考节点文件结构 了解更多信息。
步骤 3.1：导入
首先添加导入语句：
import { INodeType , INodeTypeDescription } from 'n8n-workflow' ;
步骤 3.2：创建主类
节点必须导出一个实现 INodeType 的接口。此接口必须包含一个 description 接口，该接口又包含 properties 数组。
类名和文件名
确保类名和文件名匹配。例如，给定类 NasaPics，文件名必须是 NasaPics.node.ts。
export class NasaPics implements INodeType {
description : INodeTypeDescription = {
// 基本节点详细信息将放在这里
properties : [
// 资源和操作将放在这里
]
};
}
步骤 3.3：添加节点详细信息
所有节点都需要一些基本参数，如显示名称、图标以及使用节点进行请求的基本信息。将以下内容添加到 description 中：
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 displayName : 'NASA Pics' ,
name : 'nasaPics' ,
icon : 'file:nasapics.svg' ,
group : [ 'transform' ],
version : 1 ,
subtitle : '={{$parameter["operation"] + ": " + $parameter["resource"]}}' ,
description : 'Get data from NASAs API' ,
defaults : {
name : 'NASA Pics' ,
},
inputs : [ 'main' ],
outputs : [ 'main' ],
credentials : [
{
name : 'NasaPicsApi' ,
required : true ,
},
],
requestDefaults : {
baseURL : 'https://api.nasa.gov' ,
headers : {
Accept : 'application/json' ,
'Content-Type' : 'application/json' ,
},
},
n8n 使用 description 中设置的一些属性在编辑器 UI 中渲染节点。这些属性是 displayName、icon、description 和 subtitle。
步骤 3.4：添加资源
资源对象定义节点使用的 API 资源。在本教程中，您正在创建一个节点来访问 NASA 的两个 API 端点：planetary/apod 和 mars-photos。这意味着您需要在 NasaPics.node.ts 中定义两个资源选项。使用资源对象更新 properties 数组：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 properties : [
{
displayName : 'Resource' ,
name : 'resource' ,
type : 'options' ,
noDataExpression : true ,
options : [
{
name : 'Astronomy Picture of the Day' ,
value : 'astronomyPictureOfTheDay' ,
},
{
name : 'Mars Rover Photos' ,
value : 'marsRoverPhotos' ,
},
],
default : 'astronomyPictureOfTheDay' ,
},
// 操作将放在这里
]
type 控制 n8n 为资源显示哪个 UI 元素，并告诉 n8n 期望用户提供什么类型的数据。options 导致 n8n 添加一个允许用户选择一个选项的下拉菜单。参考节点 UI 元素 了解更多信息。
步骤 3.5：添加操作
操作对象定义资源上的可用操作。
在声明式节点中，操作对象包含 routing（在 options 数组内）。这设置了 API 调用的详细信息。
将以下内容添加到 properties 数组中，在 resource 对象之后：
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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105 {
displayName : 'Operation' ,
name : 'operation' ,
type : 'options' ,
noDataExpression : true ,
displayOptions : {
show : {
resource : [
'astronomyPictureOfTheDay' ,
],
},
},
options : [
{
name : 'Get' ,
value : 'get' ,
action : 'Get the APOD' ,
description : 'Get the Astronomy Picture of the day' ,
routing : {
request : {
method : 'GET' ,
url : '/planetary/apod' ,
},
},
},
],
default : 'get' ,
},
{
displayName : 'Operation' ,
name : 'operation' ,
type : 'options' ,
noDataExpression : true ,
displayOptions : {
show : {
resource : [
'marsRoverPhotos' ,
],
},
},
options : [
{
name : 'Get' ,
value : 'get' ,
action : 'Get Mars Rover photos' ,
description : 'Get photos from the Mars Rover' ,
routing : {
request : {
method : 'GET' ,
},
},
},
],
default : 'get' ,
},
{
displayName : 'Rover name' ,
description : 'Choose which Mars Rover to get a photo from' ,
required : true ,
name : 'roverName' ,
type : 'options' ,
options : [
{ name : 'Curiosity' , value : 'curiosity' },
{ name : 'Opportunity' , value : 'opportunity' },
{ name : 'Perseverance' , value : 'perseverance' },
{ name : 'Spirit' , value : 'spirit' },
],
routing : {
request : {
url : '=/mars-photos/api/v1/rovers/{{$value}}/photos' ,
},
},
default : 'curiosity' ,
displayOptions : {
show : {
resource : [
'marsRoverPhotos' ,
],
},
},
},
{
displayName : 'Date' ,
description : 'Earth date' ,
required : true ,
name : 'marsRoverDate' ,
type : 'dateTime' ,
default : '' ,
displayOptions : {
show : {
resource : [
'marsRoverPhotos' ,
],
},
},
routing : {
request : {
// 您已经设置了 URL。qs 将字段值作为查询字符串附加
qs : {
earth_date : '={{ new Date($value).toISOString().substr(0,10) }}' ,
},
},
},
},
// 可选/附加字段将放在这里
此代码创建两个操作：一个获取今天的 APOD 图像，另一个发送获取火星探测器照片的请求。名为 roverName 的对象要求用户选择他们想要照片的探测器。火星探测器操作中的 routing 对象引用此内容来创建 API 调用的 URL。
步骤 3.6：可选字段
大多数 API，包括您在此示例中使用的 NASA API，都有可选字段，您可以使用这些字段来优化查询。
为了避免让用户感到不知所措，n8n 在 UI 中的附加字段 下显示这些字段。
对于本教程，您将添加一个附加字段，以允许用户选择用于 APOD 端点的日期。将以下内容添加到 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 {
displayName : 'Additional Fields' ,
name : 'additionalFields' ,
type : 'collection' ,
default : {},
placeholder : 'Add Field' ,
displayOptions : {
show : {
resource : [
'astronomyPictureOfTheDay' ,
],
operation : [
'get' ,
],
},
},
options : [
{
displayName : 'Date' ,
name : 'apodDate' ,
type : 'dateTime' ,
default : '' ,
routing : {
request : {
// 您已经设置了 URL。qs 将字段值作为查询字符串附加
qs : {
date : '={{ new Date($value).toISOString().substr(0,10) }}' ,
},
},
},
},
],
}
步骤 4：设置身份验证
NASA API 要求用户使用 API 密钥进行身份验证。
将以下内容添加到 nasaPicsApi.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 import {
IAuthenticateGeneric ,
ICredentialType ,
INodeProperties ,
} from 'n8n-workflow' ;
export class NasaPicsApi implements ICredentialType {
name = 'NasaPicsApi' ;
displayName = 'NASA Pics API' ;
// 使用此教程的链接作为示例
// 在构建自己的节点时，请替换为您自己的文档链接
documentationUrl = 'https://docs.n8ncn.io/integrations/creating-nodes/build/declarative-style-node/' ;
properties : INodeProperties [] = [
{
displayName : 'API Key' ,
name : 'apiKey' ,
type : 'string' ,
default : '' ,
},
];
authenticate = {
type : 'generic' ,
properties : {
qs : {
'api_key' : '={{$credentials.apiKey}}'
}
},
} as IAuthenticateGeneric ;
}
有关凭据文件和选项的更多信息，请参考凭据文件 。
步骤 5：添加节点元数据
关于您节点的元数据放在节点根目录的 JSON 文件中。n8n 将此称为代码库文件。在此示例中，文件是 NasaPics.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.NasaPics" ,
"nodeVersion" : "1.0" ,
"codexVersion" : "1.0" ,
"categories" : [
"Miscellaneous"
],
"resources" : {
"credentialDocumentation" : [
{
"url" : ""
}
],
"primaryDocumentation" : [
{
"url" : ""
}
]
}
}
有关这些参数的更多信息，请参考节点代码库文件 。
步骤 6：更新 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-nasapics" ,
"version" : "0.1.0" ,
"description" : "n8n node to call NASA's APOD and Mars Rover Photo services." ,
"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/NasaPicsApi.credentials.js"
],
"nodes" : [
"dist/nodes/NasaPics/NasaPics.node.js"
]
},
"devDependencies" : {
// 不要更改
},
"peerDependencies" : {
// 不要更改
}
}
您需要更新 package.json 以包含您自己的信息，如您的姓名和仓库 URL。有关 npm package.json 文件的更多信息，请参考 npm 的 package.json 文档 。
测试您的节点
您可以通过在本地 n8n 实例中运行来测试正在构建的节点。
使用 npm 安装 n8n：
当您准备测试节点时，在本地发布它：
# 在您的节点目录中
npm run build
npm link
将节点安装到您的本地 n8n 实例中：
# 在您的 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 设置了不同的名称。
启动 n8n：
在浏览器中打开 n8n。当您在节点面板中搜索时，应该能看到您的节点。
节点名称
确保您使用节点名称搜索，而不是包名称。例如，如果您的 npm 包名称是 n8n-nodes-weather-nodes，并且包含名为 rain、sun、snow 的节点，您应该搜索 rain，而不是 weather-nodes。
故障排除
如果在 ~/.n8n 本地安装中没有 custom 目录，您需要手动创建 custom 目录并运行 npm init：
# 在 ~/.n8n 目录中运行
mkdir custom
cd custom
npm init
下一步