🔄 n8n에서 입력과 출력 포맷 맞추기 완벽 가이드
n8n 워크플로우에서 노드 간 데이터를 원활하게 전달하기 위해서는 입력과 출력 포맷을 올바르게 맞춰야 합니다. 이 가이드는 Context7 MCP를 통해 수집된 최신 정보를 바탕으로 작성되었습니다.
📋 1. n8n 데이터 구조 이해하기
n8n에서 모든 데이터는 아이템(Item) 형태로 전달됩니다. 각 아이템은 JSON 데이터와 바이너리 데이터를 포함할 수 있습니다.
1.1 기본 데이터 구조
[
{
“json”: {
“apple”: “beets”,
“carrot”: {
“dill”: 1
}
},
“binary”: {
“apple-picture”: {
“data”: “….”, // Base64 인코딩된 바이너리 데이터
“mimeType”: “image/png”,
“fileExtension”: “png”,
“fileName”: “example.png”
}
}
}
]
{
“json”: {
“apple”: “beets”,
“carrot”: {
“dill”: 1
}
},
“binary”: {
“apple-picture”: {
“data”: “….”, // Base64 인코딩된 바이너리 데이터
“mimeType”: “image/png”,
“fileExtension”: “png”,
“fileName”: “example.png”
}
}
}
]
💡 핵심 포인트
- json 키: 구조화된 데이터를 저장
- binary 키: 파일이나 이미지 등 바이너리 데이터 저장
- 배열 구조: 모든 데이터는 배열로 래핑됨
⚡ 2. 입력 데이터 접근 방법
n8n 노드에서 입력 데이터에 접근하는 다양한 방법들을 알아보겠습니다.
2.1 JavaScript 스타일 접근법
| 변수/함수 | 설명 | 사용 가능한 노드 |
|---|---|---|
$json |
현재 아이템의 JSON 데이터 | Code 노드 (각 아이템마다 실행) |
$input.item |
현재 처리 중인 아이템 | Code 노드 |
$input.all() |
모든 입력 아이템 | Code 노드 |
$input.first() |
첫 번째 입력 아이템 | Code 노드 |
$input.last() |
마지막 입력 아이템 | Code 노드 |
$binary |
바이너리 데이터 | Code 노드 외 |
2.2 Python 스타일 접근법
# Python 스타일 접근법
_json # 현재 아이템의 JSON 데이터
_input.item # 현재 처리 중인 아이템
_input.all() # 모든 입력 아이템
_input.first() # 첫 번째 입력 아이템
_input.last() # 마지막 입력 아이템
_json # 현재 아이템의 JSON 데이터
_input.item # 현재 처리 중인 아이템
_input.all() # 모든 입력 아이템
_input.first() # 첫 번째 입력 아이템
_input.last() # 마지막 입력 아이템
🔧 3. 데이터 변환 함수 활용하기
n8n 1.34.0부터 제공되는 내장 데이터 변환 함수들을 활용하여 포맷을 맞춰보겠습니다.
3.1 배열 데이터 변환
// 배열 변환 예제
{{ $json.myArray.average() }} // 배열의 평균값
{{ $json.myArray.sum() }} // 배열의 합계
{{ $json.myArray.chunk(3) }} // 3개씩 묶어서 배열 분할
{{ $json.myArray.compact() }} // 빈 값 제거
{{ $json.myArray.removeDuplicates() }} // 중복 제거
{{ $json.myArray.pluck(‘name’) }} // 특정 필드만 추출
{{ $json.myArray.toJsonString() }} // JSON 문자열로 변환
{{ $json.myArray.average() }} // 배열의 평균값
{{ $json.myArray.sum() }} // 배열의 합계
{{ $json.myArray.chunk(3) }} // 3개씩 묶어서 배열 분할
{{ $json.myArray.compact() }} // 빈 값 제거
{{ $json.myArray.removeDuplicates() }} // 중복 제거
{{ $json.myArray.pluck(‘name’) }} // 특정 필드만 추출
{{ $json.myArray.toJsonString() }} // JSON 문자열로 변환
3.2 문자열 데이터 변환
// 문자열 변환 예제
{{ $json.myString.toDateTime() }} // 날짜/시간으로 변환
{{ $json.myString.parseJson() }} // JSON 파싱
{{ $json.myString.extractUrlPath() }} // URL 경로 추출
{{ $json.myString.toBoolean() }} // 불린 값으로 변환
{{ $json.myString.base64Encode() }} // Base64 인코딩
{{ $json.myString.base64Decode() }} // Base64 디코딩
{{ $json.myString.toDateTime() }} // 날짜/시간으로 변환
{{ $json.myString.parseJson() }} // JSON 파싱
{{ $json.myString.extractUrlPath() }} // URL 경로 추출
{{ $json.myString.toBoolean() }} // 불린 값으로 변환
{{ $json.myString.base64Encode() }} // Base64 인코딩
{{ $json.myString.base64Decode() }} // Base64 디코딩
3.3 숫자 데이터 변환
// 숫자 변환 예제
{{ $json.myNumber.ceil() }} // 올림
{{ $json.myNumber.floor() }} // 내림
{{ $json.myNumber.round(2) }} // 소수점 둘째 자리 반올림
{{ $json.myNumber.format(‘ko-KR’) }} // 한국어 형식으로 포맷
{{ $json.myNumber.isEven() }} // 짝수 여부 확인
{{ $json.myNumber.toBoolean() }} // 불린 값으로 변환
{{ $json.myNumber.ceil() }} // 올림
{{ $json.myNumber.floor() }} // 내림
{{ $json.myNumber.round(2) }} // 소수점 둘째 자리 반올림
{{ $json.myNumber.format(‘ko-KR’) }} // 한국어 형식으로 포맷
{{ $json.myNumber.isEven() }} // 짝수 여부 확인
{{ $json.myNumber.toBoolean() }} // 불린 값으로 변환
🔄 4. 실제 워크플로우 예제
4.1 JSON을 XML로 변환하는 워크플로우
Manual Trigger
→
HTTP Request
→
XML Node
→
HTTP Request
→
XML Node
HTTP Request 노드 설정:
- Authentication: None
- Request Method: GET
- URL: https://pokeapi.co/api/v2/pokemon
XML 노드 설정:
- Mode: JSON to XML
- Property name: data
4.2 배열 데이터를 여러 아이템으로 분할
// Code 노드에서 실행할 JavaScript
let items = $input.all();
return items[0].json.workEmail.map(item => {
return {
json: item
}
});
let items = $input.all();
return items[0].json.workEmail.map(item => {
return {
json: item
}
});
4.3 데이터 병합 워크플로우
{
“parameters”: {
“mode”: “combine”,
“mergeByFields”: {
“values”: [
{
“field1”: “name”,
“field2”: “name”
}
]
}
}
}
“parameters”: {
“mode”: “combine”,
“mergeByFields”: {
“values”: [
{
“field1”: “name”,
“field2”: “name”
}
]
}
}
}
📁 5. 파일 변환 및 처리
5.1 JSON을 파일로 변환
Convert to File 노드 설정:
- Operation: toJson
- Mode: each
- File name: report_orderID_{{ $(‘If’).item.json.orderID }}.json
5.2 PDF를 JSON으로 변환
Manual Trigger
→
HTTP Request
→
Extract From File
→
HTTP Request
→
Extract From File
Extract From File 노드 설정:
- Operation: pdf
- Options: 기본 설정
🎯 6. 출력 데이터 포맷 맞추기
6.1 Code 노드에서 올바른 출력 형식
// 올바른 출력 형식
return [
{
json: {
name: “John Doe”,
age: 30,
email: “john@example.com”
},
pairedItem: 0 // 원본 아이템과의 연결 정보
}
];
return [
{
json: {
name: “John Doe”,
age: 30,
email: “john@example.com”
},
pairedItem: 0 // 원본 아이템과의 연결 정보
}
];
6.2 아이템 연결 (Item Linking)
// 아이템 연결을 포함한 변환
newItems = [];
for(let i = 0; i < items.length; i++){ newItems.push({ "json": { "name": items[i].json.name, "aBrandNewField": "New data for item " + i }, "pairedItem": i // 원본 아이템 인덱스 }); } return newItems;
newItems = [];
for(let i = 0; i < items.length; i++){ newItems.push({ "json": { "name": items[i].json.name, "aBrandNewField": "New data for item " + i }, "pairedItem": i // 원본 아이템 인덱스 }); } return newItems;
⚠️ 7. 주의사항 및 베스트 프랙티스
⚠️ 주요 주의사항
- 데이터 타입 일치: 입력과 출력의 데이터 타입이 일치해야 함
- 배열 구조 유지: 모든 출력은 배열 형태로 래핑되어야 함
- JSON 키 필수: 구조화된 데이터는 반드시 ‘json’ 키 안에 포함
- 바이너리 데이터 처리: 파일 데이터는 ‘binary’ 키에 올바른 메타데이터와 함께 저장
💡 베스트 프랙티스
- 데이터 검증: 입력 데이터의 구조를 항상 확인
- 에러 처리: 예상치 못한 데이터 형식에 대한 대비책 마련
- 성능 고려: 대용량 데이터 처리 시 청크 단위로 분할
- 문서화: 복잡한 변환 로직에 대한 주석 작성
🔍 8. 디버깅 및 문제 해결
8.1 일반적인 문제들
| 문제 | 원인 | 해결책 |
|---|---|---|
| 데이터가 전달되지 않음 | 출력 형식이 잘못됨 | 배열로 래핑하고 json 키 사용 확인 |
| 바이너리 데이터 손실 | binary 키 누락 | binary 키에 올바른 메타데이터 포함 |
| 타입 에러 | 데이터 타입 불일치 | 변환 함수 사용하여 타입 맞추기 |
| 배열 처리 실패 | 배열 구조 오해 | 배열 메서드 활용하여 올바른 처리 |
8.2 디버깅 도구
데이터 검사 방법:
- 노드 실행 후 데이터 미리보기 활용
- Code 노드에서 console.log() 사용
- Set 노드로 데이터 구조 확인
- Expression 에디터에서 데이터 접근 테스트
🚀 9. 고급 활용 예제
9.1 AI Code 노드를 활용한 데이터 변환
// AI Code 노드 프롬프트 예제
“Extract usernames from input items, quote them, and join with commas”
“Extract usernames from input items, quote them, and join with commas”
// 생성된 코드
const items = $input.all();
const usernames = items.map((item) => `”${item.json.username}”`);
const result = usernames.join(“, “);
return [{ json: { usernames: result } }];
9.2 날짜/시간 데이터 처리
// Date & Time 노드 설정 예제
{
“operation”: “formatDate”,
“date”: “={{ $json.customerSince }}”,
“options”: {
“includeInputFields”: true
}
}
{
“operation”: “formatDate”,
“date”: “={{ $json.customerSince }}”,
“options”: {
“includeInputFields”: true
}
}
9.3 조건부 데이터 처리
// If 노드를 활용한 조건부 처리
{
“conditions”: {
“conditions”: [
{
“leftValue”: “={{ $json[‘new-date’] }}”,
“rightValue”: “1960-01-01T00:00:00”,
“operator”: {
“type”: “dateTime”,
“operation”: “after”
}
}
]
}
}
{
“conditions”: {
“conditions”: [
{
“leftValue”: “={{ $json[‘new-date’] }}”,
“rightValue”: “1960-01-01T00:00:00”,
“operator”: {
“type”: “dateTime”,
“operation”: “after”
}
}
]
}
}
📝 마무리
n8n에서 입력과 출력 포맷을 올바르게 맞추는 것은 워크플로우의 성공적인 실행을 위해 필수적입니다. 이 가이드에서 제시한 방법들을 활용하여 데이터 변환과 처리를 효율적으로 수행하세요. 복잡한 변환이 필요한 경우 여러 노드를 조합하여 단계별로 처리하는 것을 권장합니다.
추가 리소스:
- n8n 공식 문서: https://docs.n8n.io
- n8n 커뮤니티 포럼: https://community.n8n.io
- n8n GitHub 저장소: https://github.com/n8n-io/n8n