n8n을 사용하여 업무 자동화를 구축하다 보면 노드 결과 미리보기에서 데이터 구조가 계속 바뀌거나 분명히 존재하는 데이터인데도 언디파인드 오류가 발생해 답답했던 경험이 한 번쯤 있으실 겁니다. 워크플로우를 아무리 정교하게 설계해도 데이터가 흐르는 기본 원리를 모르면 결국 어딘가에서 막히게 됩니다. 이런 문제의 90퍼센트는 n8n이 데이터를 처리하는 핵심 방식인 제이슨(JSON) 구조에 대한 이해 부족에서 시작됩니다. 오늘은 n8n을 다루는 데 있어 필수적인 데이터 구조의 기초부터 실전 응용 방법까지 상세히 알아보겠습니다. 이 글을 통해 더 이상 데이터 구조 때문에 워크플로우가 멈추는 일이 없도록 만들어 드리겠습니다.
n8n 워크플로우 자동화에서 제이슨이 중요한 이유
n8n은 수많은 애플리케이션과 서비스를 연결해주는 강력한 자동화 도구입니다. 이 모든 연결의 중심에는 데이터가 있으며 n8n은 이 데이터를 제이슨이라는 표준 형식으로 주고받습니다. 마치 전 세계 사람들이 영어를 공용어로 사용해 소통하듯 n8n의 모든 노드들은 제이슨이라는 언어로 대화하는 셈입니다. 이 표준화된 데이터 구조 덕분에 어떤 노드에서든 일관된 방식으로 데이터를 추출하고 변환하며 적재하는 작업이 가능해집니다.
만약 제이슨 데이터 구조를 제대로 이해하지 못하면 데이터 증발 현상을 겪게 됩니다. 워크플로우 중간에 데이터가 갑자기 사라진 것처럼 보이지만 실제로는 데이터 경로를 잘못 참조한 경우가 대부분입니다. 또한 외부 API에서 받은 데이터 구조가 매번 조금씩 달라져 후속 노드들이 데이터를 제대로 찾지 못하고 오류를 일으키기도 합니다. 특히 머지나 이프 노드에서 단 하나의 데이터와 여러 데이터 묶음인 배열의 차이를 구분하지 못해 워크플로우가 오작동하는 경우도 빈번합니다.
n8n의 제이슨 데이터 구조 기본 개념
n8n에서 데이터 다루기의 첫걸음은 기본 데이터 단위를 이해하는 것입니다. 가장 중요한 핵심은 n8n의 모든 데이터는 아이템스(items)라는 배열 안에 제이슨 객체가 담긴 형태라는 점입니다. 각 노드는 이 배열을 입력으로 받아 배열 안의 아이템 개수만큼 실행됩니다. 예를 들어 배열 안에 아이템이 5개 있다면 해당 노드는 5번 실행됩니다.
n8n의 한 아이템은 크게 세 가지 주요 속성으로 구성됩니다. 첫째 제이슨(json)입니다. 우리가 워크플로우에서 실제로 다루는 대부분의 텍스트와 숫자 그리고 중첩된 데이터가 이곳에 객체 형태로 저장됩니다. 둘째 바이너리(binary)입니다. 이미지나 PDF 같은 파일 데이터와 관련된 정보가 담깁니다. 셋째 페어드아이템스(pairedItems)입니다. 현재 아이템이 이전 노드의 어떤 아이템과 연결되는지 추적하기 위한 메타 정보입니다. 이 구조를 엑셀 시트에 비유하면 쉽게 이해할 수 있습니다. 아이템스 배열은 전체 시트이고 하나의 아이템은 행에 해당하며 제이슨 객체 안의 각 키는 열에 해당한다고 생각하면 편리합니다.
실제 데이터 예시를 보면 단일 아이템일 때는 배열 안에 객체가 하나만 존재합니다. 반면 다중 아이템일 때는 배열 안에 여러 개의 객체가 포함됩니다. API 응답 데이터에서 흔히 볼 수 있는 중첩 제이슨 구조는 객체 안에 또 다른 객체가 포함된 형태를 띠고 있습니다. 이러한 구조적 특징을 눈에 익혀두는 것이 중요합니다.
실전 접근법 표현식을 이용한 데이터 참조
기본 구조를 이해했다면 이제 데이터를 실제로 참조하고 가공하는 방법을 알아볼 차례입니다. n8n에서는 표현식(Expressions)을 사용해 데이터에 쉽게 접근할 수 있습니다. 표현식은 중괄호 두 개 안에 작성하며 워크플로우의 거의 모든 입력 필드에서 사용할 수 있습니다.
가장 기본적으로 사용되는 것은 달러 제이슨($json)입니다. 현재 노드에서 처리 중인 아이템의 제이슨 객체에 직접 접근할 때 사용합니다. 예를 들어 이름 데이터에 접근하고 싶다면 달러 제이슨 점 네임($json.name)과 같이 작성합니다. 다음으로 달러 노드($node)가 있습니다. 이는 특정 이전 노드의 결과 데이터에 접근할 때 사용합니다. 바로 앞 단계가 아닌 훨씬 이전 단계의 노드에서 데이터를 가져와야 할 때 유용합니다. 마지막으로 달러 인풋($input)은 현재 노드로 들어오는 전체 입력 데이터를 가리킵니다. 주로 코드 노드에서 여러 아이템을 한 번에 처리할 때 사용됩니다.
주요 노드별 데이터 처리 방법과 노하우
각 노드는 저마다의 방식으로 데이터를 처리합니다. 자주 사용하는 노드들의 데이터 처리법을 알아두면 워크플로우 설계가 훨씬 쉬워집니다.
셋(Set) 노드는 데이터를 추가하거나 수정하고 삭제하는 가장 기본적인 노드입니다. 익스프레션 토글을 활성화하면 표현식을 사용해 동적인 데이터를 만들 수 있습니다. 예를 들어 성과 이름을 합쳐서 전체 이름이라는 새로운 필드를 만들 수 있습니다. 간단한 데이터 조작은 셋 노드가 가장 편리하고 가독성도 좋습니다.
코드(Code) 노드는 자바스크립트로 복잡한 데이터 변환을 처리할 때 사용합니다. 여러 아이템을 종합하거나 복잡한 로직이 필요할 때는 코드 노드가 필수적입니다. 입력된 모든 아이템을 받아와 맵(map)이나 필터(filter) 같은 배열 함수로 처리하고 새로운 배열을 반환하는 패턴이 주로 사용됩니다. 다만 코드가 길어지면 다른 사람이 이해하기 어려울 수 있으므로 꼭 필요한 경우에만 사용하는 것이 좋습니다.
머지(Merge) 노드는 여러 경로로 나뉜 데이터 흐름을 하나로 합칠 때 사용됩니다. 두 가지 핵심 모드의 차이를 이해하는 것이 중요합니다. 인덱스 기준 결합은 두 입력의 아이템 순서를 기준으로 데이터를 합칩니다. 순서가 중요한 데이터를 처리할 때 유용합니다. 반면 키 기준 결합은 지정한 키의 값이 같은 아이템끼리 데이터를 합칩니다. 데이터의 순서와 상관없이 사용자 아이디나 제품 코드 같은 고유 값을 기준으로 정확하게 데이터를 병합할 때 사용합니다.
제이슨 파싱과 문자열화의 차이
워크플로우를 만들다 보면 순수한 제이슨 객체가 아닌 문자열 형태의 제이슨을 다뤄야 할 때가 있습니다. 제이슨 문자열과 제이슨 객체는 엄연히 다릅니다. 문자열은 텍스트 덩어리라서 속성에 접근할 수 없습니다. 이를 접근 가능한 객체로 바꾸는 과정을 파싱(Parsing)이라고 합니다. 코드 노드에서 제이슨 닷 파스(JSON.parse) 함수를 사용하면 됩니다. 잘못된 형식의 문자열 때문에 워크플로우가 멈추는 것을 방지하기 위해 예외 처리 구문으로 감싸주는 것이 안전합니다.
반대로 제이슨 객체를 다른 API로 보낼 때 순수한 문자열 형태로 바꿔야 하는 경우가 있습니다. 이 과정을 문자열화 또는 직렬화라고 부릅니다. 코드 노드에서 제이슨 닷 스트링기파이(JSON.stringify) 함수를 사용해 간단히 변환할 수 있습니다. 이렇게 생성된 문자열을 HTTP 요청 노드의 바디에 넣고 헤더의 콘텐츠 타입을 애플리케이션 제이슨으로 설정해 API 요청을 보내는 것이 일반적인 패턴입니다.
안정적인 워크플로우를 위한 고급 전략
기본기를 다졌다면 워크플로우를 더 안정적이고 관리하기 쉽게 만드는 전략이 필요합니다. 먼저 표준 데이터 스키마를 만드는 것이 좋습니다. 여러 다른 API에서 데이터를 가져올 때 각기 다른 필드 이름을 가질 수 있습니다. 워크플로우 초반에 셋 노드 등을 배치하여 모든 데이터를 일관된 공통 구조로 맞춰주면 후속 노드들을 훨씬 간단하게 관리할 수 있습니다.
에러 핸들링을 위한 구조 설계도 중요합니다. 데이터 처리 중 문제가 발생했을 때를 대비해 에러나 원본 데이터 같은 필드를 객체에 추가하는 패턴을 사용하면 좋습니다. 이렇게 하면 에러 발생 시 원본 데이터와 에러 메시지를 함께 로깅하기 편리해져 유지보수가 수월해집니다.
마지막으로 중첩 구조를 평탄화하는 것입니다. 데이터 구조가 너무 깊어지면 표현식이 길고 복잡해집니다. 중간에 셋 노드를 사용해 자주 쓰는 값을 상위 레벨로 한번 꺼내주면 이후의 작업이 훨씬 깔끔해집니다.