프로그래밍 스타일 노드 구축하기#

이 튜토리얼은 프로그래밍 스타일 노드를 만드는 과정을 안내합니다. 시작하기 전에, 이 스타일의 노드가 필요한지 확인하세요. 자세한 내용은 노드 구축 접근 방식 선택하기를 참조하세요.

전제 조건#

다음이 개발 기계에 설치되어 있어야 합니다:

git
Node.js 및 npm. 최소 요구 버전: Node 18.17.0.
Linux, Mac, WSL에서 nvm(Node Version Manager)을 사용하여 설치하는 방법은 여기를 참고하세요.
Windows 사용자는 Microsoft의 Windows에서 NodeJS 설치 가이드를 참고하세요.

다음에 대한 이해가 필요합니다:

JavaScript/TypeScript
REST API
git
n8n의 Expressions

노드 구축하기#

이 섹션에서는 n8n의 노드 스타터 리포지토리를 복제하고, SendGrid와 통합되는 노드를 구축할 것입니다. SendGrid 기능 중 하나인 연락처 생성 기능을 구현하는 노드를 만들 것입니다.

기존 노드

n8n에는 내장된 SendGrid 노드가 있습니다. 기존 노드와 충돌을 피하기 위해, 버전의 이름을 다르게 지정할 것입니다.

1단계: 프로젝트 설정하기#

n8n은 노드 개발을 위한 스타터 리포지토리를 제공합니다. 스타터를 사용하면 모든 필수 종속성을 갖추게 됩니다. 또한 린터도 제공합니다.

리포지토리를 복제하고 디렉토리로 이동합니다:

템플릿 리포지토리에서 새 리포지토리 생성하기.

새 리포지토리를 복제합니다:

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

이들은 모든 노드에 필요한 주요 파일입니다. 필수 파일 및 권장 조직에 대한 자세한 정보는 노드 파일 구조를 참조하세요.

이제 프로젝트 종속성을 설치합니다:

npm i

2단계: 아이콘 추가하기#

이곳에서 SendGrid SVG 로고를 저장합니다 여기를 nodes/FriendGrid/에 friendGrid.svg로 저장하세요.

n8n에서는 SVG 형식의 아이콘 사용을 권장하지만, PNG 형식도 사용할 수 있습니다.
PNG를 사용할 경우 해상도는 60x60px 이어야 하며,
노드 아이콘은 정사각형 또는 정사각형에 가까운 비율을 유지해야 합니다.

Font Awesome 아이콘을 직접 참조하지 마세요

Font Awesome 아이콘을 사용하려면, 아이콘을 다운로드하여 직접 삽입해야 합니다.

3단계: 기본 파일에서 노드 정의하기#

모든 노드는 기본 파일을 가져야 합니다. 기본 파일 매개변수에 대한 자세한 정보는 노드 기본 파일을 참조하세요.

이 예시에서는 파일이 FriendGrid.node.ts입니다. 이 튜토리얼을 간결하게 유지하기 위해, 모든 노드 기능을 이 한 파일에 배치할 것입니다. 보다 복잡한 노드를 구축할 때는 기능을 모듈로 분할하는 것을 고려해야 합니다. 필요한 파일과 권장된 조직에 대한 자세한 정보는 노드 파일 구조를 참조하세요.

Step 3.1: Imports#

먼저 import 문을 추가하세요:

import {
	IExecuteFunctions,
} from 'n8n-core';

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

import {
	OptionsWithUri,
} from 'request';

Step 3.2: Create the main class#

노드는 INodeType를 구현하는 인터페이스를 내보내야 합니다. 이 인터페이스는 properties 배열을 포함하는 description 인터페이스를 포함해야 합니다.

Class names and file names

클래스 이름과 파일 이름이 일치하는지 확인하세요. 예를 들어, 클래스 FriendGrid가 주어지면 파일 이름은 FriendGrid.node.ts여야 합니다.

export class FriendGrid implements INodeType {
	description: INodeTypeDescription = {
		// 기본 노드 세부정보가 여기에 들어갑니다.
		properties: [
			// 리소스 및 작업이 여기에 들어갑니다.
		],
	};
	// 실행 메서드는 여기에 들어갑니다.
	async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
	}
}

Step 3.3: Add node details#

모든 프로그래밍 노드는 표시 이름과 아이콘과 같은 기본 매개변수가 필요합니다. description에 다음 내용을 추가하세요:

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입니다.

Step 3.4: Add the resource#

리소스 객체는 노드가 사용하는 API 리소스를 정의합니다. 이 튜토리얼에서는 SendGrid의 API 엔드포인트 중 하나인 /v3/marketing/contacts에 액세스할 노드를 생성하고 있습니다. 이는 이 엔드포인트에 대한 리소스를 정의해야 함을 의미합니다. properties 배열을 리소스 객체로 업데이트하세요:

{
	displayName: '리소스',
	name: 'resource',
	type: 'options',
	options: [
		{
			name: '연락처',
			value: 'contact',
		},
	],
	default: 'contact',
	noDataExpression: true,
	required: true,
	description: '새로운 연락처 생성',
},

type은 n8n이 리소스에 대해 어떤 UI 요소를 표시할지를 제어하며, 사용자로부터 어떤 유형의 데이터를 기대하는지를 n8n에 알려줍니다. options는 n8n이 사용자가 하나의 옵션을 선택할 수 있는 드롭다운을 추가하게 합니다. 자세한 내용은 Node UI elements를 참조하세요.

Step 3.5: Add operations#

작업 객체는 리소스에 대해 수행할 수 있는 작업을 정의합니다. 일반적으로 REST API 동사(GET, POST 등)와 관련이 있습니다. 이 튜토리얼에서는 하나의 작업인 연락처 생성이 있습니다. 이 작업은 사용자가 생성하는 연락처의 이메일 주소라는 하나의 필수 필드를 가지고 있습니다.

다음 내용을 properties 배열에, resource 객체 뒤에 추가하세요:

{
	displayName: '작업',
	name: 'operation',
	type: 'options',
	displayOptions: {
		show: {
			resource: [
				'contact',
			],
		},
	},
	options: [
		{
			name: '생성',
			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단계: 선택적 필드 추가#

예제에서 사용 중인 SendGrid API를 포함한 대부분의 API는 쿼리를 세분화하는 데 사용할 수 있는 선택적 필드가 있습니다.

사용자를 압도하지 않도록 n8n은 UI의 추가 필드 아래에 이러한 필드를 표시합니다.

이 튜토리얼에서는 사용자가 연락처의 이름과 성을 입력할 수 있도록 두 개의 추가 필드를 추가합니다. 다음을 속성 배열에 추가하십시오:

{
	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 메서드에 다음을 추가하십시오:

// 이전 노드에서 오는 데이터 처리
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') {
			// 이메일 입력 가져오기
			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)];

이 코드의 다음 줄에 유의하십시오:

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에 추가하세요.

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',
		},
	};
}

자세한 자격 증명 파일 및 옵션에 대한 정보는 Credentials file를 참조하세요.

6단계: 노드 메타데이터 추가하기#

노드에 대한 메타데이터는 노드의 루트에 있는 JSON 파일에 들어갑니다. n8n에서는 이를 codex 파일이라고 부릅니다. 이 예제에서 파일은 FriendGrid.node.json입니다.

다음 코드를 JSON 파일에 추가하세요:

{
	"node": "n8n-nodes-base.FriendGrid",
	"nodeVersion": "1.0",
	"codexVersion": "1.0",
	"categories": [
		"Miscellaneous"
	],
	"resources": {
		"credentialDocumentation": [
			{
				"url": ""
			}
		],
		"primaryDocumentation": [
			{
				"url": ""
			}
		]
	}
}

이 매개변수에 대한 자세한 정보는 Node codex files를 참조하세요.

7단계: npm 패키지 세부 정보 업데이트하기#

여러분의 npm 패키지 세부 정보는 프로젝트의 루트에 있는 package.json에 있습니다. n8n 객체를 포함하여 자격 증명 및 기본 노드 파일에 대한 링크를 포함하는 것이 중요합니다. 이 파일을 업데이트하여 다음 정보를 포함하세요:

{
	// 모든 노드 이름은 "n8n-nodes-"로 시작해야 합니다.
	"name": "n8n-nodes-friendgrid",
	"version": "0.1.0",
	"description": "n8n 노드를 사용하여 SendGrid에서 연락처를 생성합니다.",
	"keywords": [
		// 이 키워드는 커뮤니티 노드에 필수입니다.
		"n8n-community-node-package"
	],
	"license": "MIT",
	"homepage": "https://n8n.io",
	"author": {
		"name": "Test",
		"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 인스턴스에서 노드를 실행하며 테스트할 수 있습니다.

n8n 설치
1
npm install n8n -g
노드를 테스트할 준비가 되면 로컬에서 빌드 및 배포하세요:
1 2 3
# 노드 디렉터리에서 실행 npm run build npm link

n8n 설치 디렉터리의 nodes 디렉터리에서 다음을 실행합니다:

# 노드 패키지 이름은 package.json에 정의된 이름입니다.
npm link <node-package-name>

디렉터리 확인

`npm link <node-name>` 명령을 실행할 때, n8n 설치 디렉터리 내 nodes 디렉터리에서 실행해야 합니다.

* `~/.n8n/custom/`
* `~/.n8n/<your-custom-name>`: if your n8n installation set a different name using `N8N_CUSTOM_EXTENSIONS`.

n8n 시작
1
n8n start
브라우저에서 n8n을 열고, 노드 패널에서 추가한 노드를 검색하세요.

노드 이름 검색

노드를 검색할 때 패키지 이름이 아니라 노드 이름을 입력해야 합니다.

예를 들어, npm 패키지 이름이 n8n-nodes-weather-nodes이고,
이 패키지에 rain, sun, snow 노드가 포함되어 있다면,
검색 시 weather-nodes 가 아니라 rain 을 입력해야 합니다.

Troubleshooting#

~/.n8n 디렉터리에 custom 폴더가 없는 경우

직접 custom 디렉터리를 생성하고 npm init을 실행하세요:

# In ~/.n8n directory run
mkdir custom 
cd custom 
npm init

다음 단계#

노드 배포를 확인하세요.
프로그래밍 방식의 노드 예제 보기: n8n의 Mattermost 노드. 이것은 더 복잡한 프로그래밍 방식의 노드 구조 예입니다.
노드 버전 관리에 대해 알아보세요.
주요 개념을 이해했는지 확인하세요: 항목 링크 및 데이터 구조.