Cześć! Zapewne znasz to uczucie: pracujesz nad nową automatyzacją w n8n, wszystko idzie gładko, przeciągasz kolejne klocki, aż tu nagle… stop. Brakuje jednego, kluczowego elementu – integracji z tym jednym, specyficznym API, którego używa Twój klient lub Twój niszowy projekt. Oficjalnych node’ów brak, a community nodes też nie pomagają. Czy to koniec marzeń o w pełni zautomatyzowanym workflow? Nic z tych rzeczy! To idealny moment, by zakasać rękawy i napisać własny, skrojony na miarę node.
W tym wpisie pokażę Ci, jak od podstaw stworzyć custom node w n8n przy użyciu TypeScript. Przejdziemy przez całą strukturę, od definicji pól w interfejsie, przez logikę działania, aż po testowanie i publikację. To wcale nie jest czarna magia, a umiejętność, która wynosi Twoje możliwości automatyzacji na zupełnie nowy poziom. Zaczynajmy!
Spis treści
- Anatomia node’a – z czego się składa?
- Definiowanie properties, czyli serce interfejsu
- Wejścia i wyjścia – klucz do przepływu danych
- Metoda execute() – tu dzieje się cała akcja!
- Testowanie i publikacja, czyli jak pokazać swoje dzieło światu
- Praktyczny przykład: integracja z niszowym API
Anatomia node’a – rozkładamy go na części pierwsze
Zanim zaczniemy pisać kod, musimy zrozumieć, z czego tak naprawdę składa się node. W uproszczeniu, każdy node w n8n to klasa w TypeScript, która implementuje określony interfejs. Struktura plików jest dość prosta i zazwyczaj sprowadza się do kilku kluczowych elementów w Twoim projekcie:
- Główny plik node’a (np. `MyNode.node.ts`): To tutaj znajduje się cała logika, definicja interfejsu i metadane Twojego node’a.
- Plik z danymi uwierzytelniającymi (np. `MyApi.credentials.ts`): Jeśli Twój node wymaga autoryzacji (np. kluczem API), definiujesz ją w osobnym pliku.
- `package.json`:** Standardowy plik dla każdego projektu Node.js, zawierający informacje o zależnościach i skryptach.
Najważniejszy jest oczywiście główny plik. Wewnątrz niego tworzymy klasę, która dziedziczy po `INodeType` i zawiera kluczowy obiekt `description`. To właśnie w nim definiujemy wszystko, co n8n musi wiedzieć o naszym klocku: jego nazwę, ikonę, grupę w panelu bocznym, a przede wszystkim – jego pola i logikę.
Każdy node to w zasadzie klasa w TypeScript, która mówi n8n, jak ma wyglądać i co ma robić. Obiekt `description` to jego dowód osobisty, a metoda `execute()` to jego mózg.
Tworzenie interfejsu i logiki – properties i metoda execute
Skoro znamy już ogólną strukturę, pora na konkrety. Jak sprawić, żeby w panelu n8n pojawiły się pola do wpisania danych? Jak pobrać te dane i coś z nimi zrobić? Za wszystko odpowiadają `properties` i metoda `execute`.
Definiowanie `properties` – Twoje pola w UI
W obiekcie `description` znajduje się tablica o nazwie `properties`. Każdy obiekt w tej tablicy to jedno pole, które użytkownik zobaczy w interfejsie node’a. To właśnie tutaj dzieje się cała magia interfejsu użytkownika. Możemy definiować różne typy pól, na przykład:
- String: Zwykłe pole tekstowe (np. na ID klienta).
- Number: Pole na wartości liczbowe.
- Boolean: Przełącznik typu „tak/nie”.
- Options: Lista rozwijana z predefiniowanymi opcjami.
- Fixed Collection: Zbiór pól, który pozwala na tworzenie bardziej złożonych struktur, np. listy klucz-wartość dla nagłówków HTTP.
Każde pole musi mieć co najmniej `displayName` (etykieta widoczna dla usera) oraz `name` (wewnętrzna nazwa, której użyjemy w kodzie do odczytania wartości). To proste, a daje ogromne możliwości konfiguracji.
Wejścia i wyjścia – jak płyną dane?
Kolejnym ważnym elementem w `description` są właściwości `inputs` i `outputs`. Zazwyczaj dla prostego node’a, który pobiera dane, przetwarza je i przekazuje dalej, wystarczy ustawić obie na `[’main’]`. To stworzy standardowe jedno wejście i jedno wyjście, które możesz połączyć z innymi node’ami w swoim workflow. Jeśli planujesz bardziej skomplikowane scenariusze, np. z kilkoma ścieżkami wyjścia (dla sukcesu i błędu), możesz zdefiniować je właśnie tutaj.
Metoda `execute()` – tu dzieje się akcja!
To jest serce operacyjne Twojego node’a. Metoda `execute` jest wywoływana, gdy workflow dochodzi do momentu wykonania Twojego klocka. To w niej umieszczasz całą logikę:
- Pobieranie danych wejściowych: Używasz `this.getInputData()`, aby uzyskać dostęp do danych, które „wpłynęły” do node’a z poprzednich kroków.
- Pobieranie parametrów z UI: Za pomocą `this.getNodeParameter(’nazwa_pola’, i)` odczytujesz wartości, które użytkownik wpisał w zdefiniowane przez Ciebie `properties`.
- Wykonanie logiki: Tutaj dzieje się właściwa praca – wysyłasz request do API, przetwarzasz pliki, wykonujesz skomplikowane obliczenia.
- Zwracanie wyników: Na koniec musisz przygotować i zwrócić dane w formacie zrozumiałym dla n8n, aby mogły popłynąć do kolejnych node’ów.
Pamiętaj, n8n operuje na tablicach obiektów. Nawet jeśli Twój node przetwarza jeden element, wynik metody `execute` powinien być opakowany w strukturę `INodeExecutionData[]`, aby zachować spójność przepływu danych.
Od pomysłu do gotowego node’a – testy i publikacja
Stworzenie kodu to jedno, ale trzeba go jeszcze przetestować. Najprostszym sposobem jest lokalne uruchomienie n8n i podlinkowanie do niego Twojego tworzonego node’a za pomocą `npm link`. Dzięki temu możesz na żywo edytować kod i od razu widzieć zmiany w działającym workflow, co niesamowicie przyspiesza development i debugowanie.
Gdy Twój node jest już gotowy i przetestowany, czas podzielić się nim ze światem! Proces jest prosty:
- Przygotuj `package.json`: Upewnij się, że wszystkie pola są poprawnie uzupełnione, a w sekcji `n8n` znajdują się ścieżki do Twoich plików `.node.ts` i `.credentials.ts`.
- Opublikuj na npm: Wystarczy komenda `npm publish`, aby Twój node trafił do publicznego rejestru pakietów.
- Instalacja w n8n: Od teraz każdy może zainstalować Twój node w swojej instancji n8n (zarówno self-hosted, jak i w chmurze) poprzez panel Community Nodes.
Tworzenie własnych node’ów otwiera przed Tobą drzwi do automatyzacji praktycznie każdego procesu, niezależnie od dostępności gotowych integracji. To potężne narzędzie w arsenale każdego specjalisty od automatyzacji. Mam nadzieję, że ten przewodnik zachęcił Cię do eksperymentów. Jeśli potrzebujesz wsparcia przy zaawansowanych automatyzacjach lub tworzeniu niestandardowych rozwiązań dla Twojej firmy, sprawdź moją ofertę na https://michalzareba.pl/. Powodzenia w kodowaniu!
Dodaj komentarz