构建声明式节点
本教程将逐步介绍如何构建声明式节点。开始之前,请确保这是您需要的节点样式。请参阅选择您的节点构建方法 了解更多信息。
先决条件
您需要在开发机器上安装以下内容:
- 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 的节点启动器仓库,并构建一个集成 NASA API{:target=_blank .external-link} 的节点。您将创建一个使用 NASA 两个服务的节点:APOD(每日天文图片)和火星探测器照片。为了保持代码示例简短,该节点不会实现火星探测器照片端点的每个可用选项。
提示
Existing node 现有节点
n8n 有一个内置的 NASA 节点。为了避免与现有节点发生冲突,您将为您的版本指定一个不同的名称。
第 1 步:设置项目
n8n 为节点开发提供了一个启动器仓库。使用启动器确保您拥有所有必要的依赖项。它还提供了一个检查器。
克隆仓库并导航到目录:
- 从模板仓库生成新仓库。
- 克隆您的新仓库:
shell git clone https://github.com/<your-organization>/<your-repo-name>.git n8n-nodes-nasa-pics cd n8n-nodes-nasa-pics
启动器包含示例节点和凭据。删除以下目录和文件:
nodes/Examplenodes/GithubIssuescredentials/GithubIssuesApi.credentials.tscredentials/GithubIssuesOAuth2Api.credentials.ts
现在创建以下目录和文件:
nodes/NasaPics
nodes/NasaPics/NasaPics.node.json
nodes/NasaPics/NasaPics.node.ts
credentials/NasaPicsApi.credentials.ts
这些是所有节点都需要的关键文件。有关必需文件和推荐组织方式的更多信息,请参阅节点文件结构。
现在安装项目依赖项:
npm i
步骤 2:添加图标
从NASA SVG 标志{:target=_blank .external-link}保存 NASA SVG 徽标,作为 nasapics.svg 保存在 nodes/NasaPics/ 中。
n8n 建议使用 SVG 作为节点图标,但您也可以使用 PNG。如果使用 PNG,图标分辨率应为 60x60px。节点图标应具有正方形或接近正方形的长宽比。
提示
Don't reference Font Awesome 不要引用 Font Awesome
如果要在节点中使用 Font Awesome 图标,请下载并嵌入该图像。不要设置 defaults.color:它只能为 Font Awesome 图标着色,且 n8n 3.0 已将其移除。
步骤3:创建节点
每个节点都必须有一个基本文件。基础文件参数的详细信息请参考节点基础文件。
在此示例中,文件为 NasaPics.node.ts。为了使本教程简短,您将把所有节点功能放在这个文件中。当构建更复杂的节点时,您应该考虑将功能拆分为模块。有关更多信息,请参阅节点文件结构。
步骤 3.1:导入
首先添加导入语句:
import { NodeConnectionTypes } from 'n8n-workflow';
import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
步骤 3.2:创建主类
节点必须导出一个实现 INodeType 的接口。此接口必须包含一个 description 接口,该接口又包含 properties 数组。
提示
Class names and file names 类名和文件名
确保类名和文件名匹配。例如,给定类 NasaPics,文件名必须是 NasaPics.node.ts。
export class NasaPics implements INodeType {
description: INodeTypeDescription = {
// 基本节点详细信息将放在这里
properties: [
// 资源和操作将放在这里
]
};
}
步骤 3.3:添加节点详细信息
所有节点都需要一些基本参数,如显示名称、图标以及使用节点进行请求的基本信息。将以下内容添加到 description 中:
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',
},
usableAsTool: true,
inputs: [ NodeConnectionTypes.Main ],
outputs: [ NodeConnectionTypes.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 数组:
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 添加一个下拉菜单,允许用户选择一个选项。更多信息请参考 Node UI 元素。
步骤3.5:添加操作
操作对象定义资源上的可用操作。
在声明式节点中,操作对象包含 routing(在 options 数组内)。这设置了 API 调用的详细信息。
将以下内容添加到 properties 数组中,在 resource 对象之后:
{
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 数组:
{
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 密钥进行身份验证。您还可以发送请求以检查 API 密钥是否有效。
将以下内容添加到 nasaPicsApi.credentials.ts:
import {
IAuthenticateGeneric,
ICredentialTestRequest,
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: IAuthenticateGeneric = {
type: 'generic',
properties: {
qs: {
'api_key': '={{$credentials.apiKey}}'
}
},
};
test: ICredentialTestRequest = {
request: {
baseURL: 'https://api.nasa.gov',
url: '/apod',
},
};
}
有关凭证文件和选项的更多信息,请参阅凭证文件。
步骤5:添加节点元数据
关于您节点的元数据放在节点根目录的 JSON 文件中。n8n 将此称为代码库文件。在此示例中,文件是 NasaPics.node.json。
将以下代码添加到 JSON 文件:
{
"node": "n8n-nodes-nasapics",
"nodeVersion": "1.0",
"codexVersion": "1.0",
"categories": [
"Miscellaneous"
],
"resources": {
"credentialDocumentation": [
{
"url": ""
}
],
"primaryDocumentation": [
{
"url": ""
}
]
}
}
有关这些参数的更多信息,请参阅 Node codex 文件。
步骤 6:更新 npm 包详细信息
您的 npm 包详细信息在项目根目录的 package.json 中。包含带有凭据和基础节点文件链接的 n8n 对象是至关重要的。更新此文件以包含以下信息:
{
// 所有节点名称必须以 "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 文档{: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。