노드의 UI는 검증된 커뮤니티 노드 후보가 되기 위해 이 가이드라인을 준수해야 합니다.

자격 증명#

API 키와 민감한 자격 증명은 항상 비밀번호 필드로 만들어야 합니다.

OAuth#

가능한 경우 항상 OAuth 자격 증명을 포함하세요.

노드 구조#

포함해야 할 작업#

각 리소스 유형에 대해 CRUD 작업을 포함하도록 노력하세요.

각 리소스에 대한 노드에서 공통 작업을 포함하도록 노력하세요. n8n은 일관된 경험을 유지하고 사용자가 리소스에 대한 기본 작업을 수행할 수 있도록 일부 CRUD 작업을 사용합니다. 권장 작업은 다음과 같습니다.

• 생성(Create)
• 생성 또는 업데이트(Upsert)
• 삭제(Delete)
• 가져오기(Get)
• 여러 개 가져오기(Get Many): 필터링이나 검색이 가능한 경우에도 사용됩니다
• 업데이트(Update)

참고:

1. 이 작업들은 리소스 자체 또는 리소스 내부의 엔터티(예: Google Sheet 내부의 행)에 적용될 수 있습니다. 리소스 내부의 엔터티를 대상으로 작업할 때는 작업 이름에 엔터티의 이름을 명시해야 합니다.
2. 노드와 리소스에 따라 명명이 달라질 수 있습니다. 자세한 내용은 다음 가이드라인을 확인하세요.

리소스 로케이터#

• 가능하면 항상 리소스 로케이터 컴포넌트를 사용하세요. 이는 사용자에게 훨씬 나은 UX를 제공합니다. 리소스 로케이터 컴포넌트는 단일 항목을 선택해야 할 때 가장 유용합니다.
• 리소스 로케이터 컴포넌트의 기본 옵션은 (가능한 경우) From list여야 합니다.

다른 노드와의 일관성#

• UX 일관성 유지: n8n은 UX의 일관성을 유지하려고 노력합니다. 즉, 기존 UX 패턴, 특히 최신 신규 또는 개편된 노드에서 사용된 패턴을 따르는 것을 의미합니다.
• 유사한 노드 확인: 예를 들어, 데이터베이스 노드 작업 중이라면 Postgres 노드를 확인해 볼 가치가 있습니다.

정렬 옵션#

• 사용자에게 정렬 옵션을 제공하여 특정 "Get Many" 작업을 개선할 수 있습니다.
• "Options" 컬렉션 아래에 전용 컬렉션으로 정렬을 추가하세요. Airtable Record:Search의 예시를 참고하세요.

노드 기능#

삭제 작업 출력#

항목(레코드나 행 등)을 삭제할 때는 단일 객체를 담은 배열 {"deleted": true}를 반환하세요. 이는 삭제가 성공했음을 사용자에게 확인시켜 주며, 이 항목이 다음 노드를 트리거하게 됩니다.

출력 필드 단순화#

일반 노드: 'Simplify' 매개변수#

엔드포인트가 10개 이상의 필드를 가진 데이터를 반환하는 경우, 최대 10개의 필드로 출력을 단순화한 버전을 반환하는 "Simplify" 불리언 매개변수를 추가하세요.

• n8n의 주요 문제점 중 하나는 데이터의 크기이며, Simplify 매개변수는 데이터 크기를 줄여 이 문제를 완화합니다.
• 단순화된 노드에서 출력할 가장 유용한 필드를 선택하고, 가장 많이 사용되는 필드가 위에 오도록 정렬하세요.
• Simplify 모드에서는 중첩된 필드를 평탄화하는 것이 좋은 경우가 많습니다.
• 표시 이름: Simplify
• 설명: Whether to return a simplified version of the response instead of the raw data

AI 도구 노드: 'Output' 매개변수#

엔드포인트가 10개 이상의 필드를 가진 데이터를 반환하는 경우, 3가지 모드가 있는 'Output' 옵션 매개변수를 추가하세요.

AI 도구 노드에서는 사용자가 더 세밀하게 조정하여 출력할 필드를 선택할 수 있도록 허용하세요. 그 이유는 도구가 컨텍스트 윈도우를 초과할 수 있고, 필드가 너무 많으면 혼란스러워할 수 있으므로 필요한 필드만 전달하는 것이 더 낫기 때문입니다.

옵션:

• Simplified: 위에서 설명한 "Simplify" 매개변수와 동일하게 작동합니다.
• Raw: 사용 가능한 모든 필드를 반환합니다.
• Selected fields: 출력에 추가하여 AI 에이전트로 전송할 필드를 선택할 수 있는 다중 선택 매개변수를 표시합니다. 기본적으로 이 옵션은 항상 레코드/엔터티의 ID를 반환합니다.

문구(Copy)#

대소문자 표기(Text Case)#

노드 name, parameters display names(레이블), dropdown titles에는 Title Case를 사용하세요. Title Case란 관사나 짧은 전치사 등 특정 짧은 단어를 제외하고 각 단어의 첫 글자를 대문자로 표기하는 방식입니다.

노드 action 이름, 노드 descriptions, parameters descriptions(툴팁), hints, dropdown descriptions에는 Sentence case를 사용하세요.

용어#

• 서드파티 서비스의 용어를 사용하세요: 연동 중인 서비스와 동일한 용어를 사용하려고 노력하세요(예: Notion '단락(paragraphs)'이 아니라 Notion '블록(blocks)').
• UI에서 사용하는 용어를 사용하세요: API나 기술 문서에서 사용하는 용어보다는 서비스의 사용자 인터페이스에서 사용하는 용어를 따르세요(예: Trello에서는 카드를 "보관(archive)"하지만, API에서는 "닫힘(closed)"으로 표시됩니다. 이 경우 "보관(archive)"을 사용하는 것이 좋습니다).
• 기술 전문 용어 지양: 단순한 단어로 충분한 경우 기술 전문 용어를 사용하지 마세요. 예를 들어 "key" 대신 "field"를 사용하세요.
• 일관된 명명: 하나의 용어를 선택하고 이를 고수하세요. 예를 들어 "directory"와 "folder"를 혼용하지 마세요.

플레이스홀더#

매개변수 플레이스홀더에 콘텐츠 예시를 삽입하는 것이 도움이 되는 경우가 많습니다. 이는 "e.g."로 시작해야 하며, 필드의 데모 콘텐츠에는 카멜 케이스를 사용해야 합니다.

복사해서 사용할 플레이스홀더 예시:

• 이미지: e.g. https://example.com/image.png
• 동영상: e.g. https://example.com/video.mp4
• 검색어: e.g. automation
• 이메일: e.g. nathan@example.com
• Twitter 사용자(또는 유사한 항목): e.g. n8n
• 이름과 성: e.g. Nathan Smith
• 이름: e.g. Nathan
• 성: e.g. Smith

작업의 이름, 액션, 설명#

• Name(이름): 캔버스에서 노드가 열려 있을 때 선택 항목에 표시되는 이름입니다. Title Case를 사용해야 하며, 리소스를 반드시 포함할 필요는 없습니다(예: "Delete").
• Action(액션): 사용자가 노드를 선택하는 패널에 표시되는 작업의 이름입니다. Sentence case로 작성해야 하며, 반드시 리소스를 포함해야 합니다(예: "Delete record").
• Description(설명): 캔버스에서 노드가 열려 있을 때 선택 항목의 이름 아래에 표시되는 하위 텍스트입니다. Sentence case를 사용해야 하며, 반드시 리소스를 포함해야 합니다. 약간의 추가 정보를 덧붙이거나 기본 리소스/작업과 다른 표현을 사용할 수 있습니다(예: "Retrieve a list of users").
• 작업이 Resource가 아닌 엔터티(예: Google Sheet의 행)를 대상으로 하는 경우, 작업 이름에 이를 명시하세요(예: "Delete Row").

일반적인 규칙으로, 작업의 **대상(object)**이 무엇인지 이해하는 것이 중요합니다. 때로는 작업의 대상이 리소스 자체인 경우가 있습니다(예: Sheet를 삭제하는 Sheet:Delete).

다른 경우, 작업의 대상이 리소스가 아니라 리소스 내부에 포함된 무언가일 수 있습니다(예: Table:Delete rows. 여기서 리소스는 테이블이지만, 실제로 조작하는 대상은 그 안에 있는 행입니다).

name 명명#

캔버스에서 노드가 열려 있을 때 선택 항목에 표시되는 이름입니다.

• 매개변수: name
• 대소문자 표기: Title Case

명명 가이드라인:

• (위에 리소스 선택이 있는 경우) 리소스를 반복하지 마세요: 리소스는 작업 위에 표시되는 경우가 많으므로, 작업의 대상이 리소스 자체인 경우 굳이 작업에서 리소스를 반복할 필요가 없습니다.
  • 예: Sheet:Delete → n8n이 위쪽 필드에 Sheet를 표시하고 삭제 대상이 Sheet이므로, Delete에서 Sheet를 반복할 필요가 없습니다.
• 위에 리소스 선택이 없는 경우 작업에 리소스를 명시하세요: 일부 노드에는 (리소스가 하나뿐이라) 리소스 선택이 없습니다. 이 경우 작업에 리소스를 명시하세요.
  • 예: Delete Records → Airtable에는 리소스 선택이 없으므로, Delete 작업이 레코드를 삭제한다는 것을 명시하는 것이 좋습니다.
• 작업의 대상이 리소스가 아닌 경우 이를 명시하세요: 때로는 작업의 대상이 리소스가 아닐 수 있습니다. 이 경우 대상을 작업에도 명시하세요.
  • 예: Table:Get Columns → 리소스가 Table이고 작업의 대상이 Columns이므로 Columns를 명시하세요.

action 명명#

사용자가 노드를 선택하는 패널에 표시되는 작업의 이름입니다.

• 매개변수: action
• 대소문자 표기: Sentence case

명명 가이드라인:

• 관사를 생략하세요: 텍스트를 더 짧게 유지하기 위해 관사(a, an, the 등)를 제거하세요.
  • 올바른 예: Update row in sheet
  • 잘못된 예: Update a row in a sheet
• 리소스를 반복하세요: 이 경우에는 리소스를 반복해도 괜찮습니다. 리소스가 목록에 표시되더라도 사용자가 이를 알아차리지 못할 수 있으므로, 작업 레이블에서 리소스를 반복하는 것이 유용합니다.
• 작업의 대상이 리소스가 아닌 경우 이를 명시하세요: 작업 이름의 경우와 동일합니다. 이 경우 리소스를 반복할 필요는 없습니다.
  • 예: Append Rows → 실제로 추가하는 대상이 행이므로 Rows를 명시해야 합니다. 리소스(Sheet)에 추가하는 것이 아니므로 리소스는 추가하지 마세요.

description 명명#

캔버스에서 노드가 열려 있을 때 선택 항목의 이름 아래에 표시되는 하위 텍스트입니다.

• 매개변수: description
• 대소문자 표기: Sentence case

명명 가이드라인:

• 가능하다면 작업 name에 명시된 것보다 더 많은 정보를 추가하세요.
• 사용자가 작업이 무엇을 하는지 더 잘 이해할 수 있도록 다른 표현을 사용하세요. 일부 사용자는 작업에 사용된 텍스트를 이해하지 못할 수 있으며(영어가 모국어가 아닐 수도 있음), 대체 표현을 사용하면 이들에게 도움이 될 수 있습니다.

어휘#

n8n은 일반적인 어휘와 함께, 유사한 애플리케이션 그룹(예: 데이터베이스나 스프레드시트)에 특화된 어휘를 사용합니다.

일반 어휘는 CRUD 작업에서 영감을 받았습니다.

• Clear
  • 리소스의 모든 콘텐츠를 삭제합니다(리소스를 비웁니다).
  • 설명: Delete all the s inside the
• Create
  • 리소스의 새 인스턴스를 생성합니다.
  • 설명: Create a new
• Create or Update
  • 리소스의 기존 인스턴스를 생성하거나 업데이트합니다.
  • 설명: Create a new or update an existing one (upsert)
• Delete
  • "Delete"는 두 가지 방식으로 사용할 수 있습니다.
    1. 리소스 삭제:
       • 설명: Delete a permanently("permanently"는 실제로 그런 경우에만 사용)
    2. 리소스 내부의 무언가(예: 행) 삭제:
       • 이 경우 항상 작업의 대상을 명시하세요: 예를 들어 Delete Rows나 Delete Records.
       • 설명: Delete a permanently
• Get
  • "Get"은 두 가지 방식으로 사용할 수 있습니다.
    1. 리소스 가져오기:
       • 설명: Retrieve a
    2. 리소스 내부의 항목(예: 레코드) 가져오기:
       • 이 경우 항상 작업의 대상을 명시하세요: 예를 들어 Get Row나 Get Record.
       • 설명: Retrieve a from the/a
• Get Many
  • "Get Many"는 두 가지 방식으로 사용할 수 있습니다.
    1. (필터링 없이) 리소스 목록 가져오기:
       • 설명: Retrieve a list of s
    2. 리소스 내부의 항목(예: 레코드) 목록 가져오기:
       • 이 경우 항상 작업의 대상을 명시하세요: 예를 들어 Get Many Rows나 Get Many Records.
       • Many는 생략할 수 있습니다: Get Many Rows는 Get Rows로 표기할 수 있습니다.
       • 설명: List all s in the/a
• Insert 또는 Append
  • 리소스 내부에 무언가를 추가합니다.
  • 데이터베이스 노드에는 insert를 사용하세요.
  • 설명: Insert (s) in a
• Insert or Update 또는 Append or Update
  • 리소스 내부에 무언가를 추가하거나 업데이트합니다.
  • 데이터베이스 노드에는 insert를 사용하세요.
  • 설명: Insert (s) or update an existing one(s) (upsert)
• Update
  • "Update"는 두 가지 방식으로 사용할 수 있습니다.
    1. 리소스 업데이트:
       • 설명: Update one or more s
    2. 리소스 내부의 무언가(예: 행) 업데이트:
       • 이 경우 항상 작업의 대상을 명시하세요: 예를 들어 Update Rows나 Update Records.
       • 설명: Update (s) inside a

매개변수 및 필드 이름 참조#

문구에서 매개변수 이름이나 필드 이름을 참조해야 할 때는 작은따옴표로 묶으세요(예: "Please fill the 'name' parameter").

불리언 설명#

불리언 컴포넌트의 설명은 'Whether...'로 시작하세요.

오류#

일반 철학#

오류는 사용자에게 고통의 원인이 됩니다. 이 때문에 n8n은 항상 사용자에게 다음을 알리고자 합니다.

• 무슨 일이 일어났는지: 오류에 대한 설명과 무엇이 잘못되었는지.
• 문제를 해결하는 방법: 또는 최소한 막힌 상황에서 벗어나 n8n을 계속 문제없이 사용하는 방법. n8n은 사용자가 막힌 상태로 남아 있는 것을 원하지 않으므로, 이를 사용자를 성공으로 안내할 기회로 활용하세요.

Output 패널의 오류 구조#

오류 메시지 - 무슨 일이 일어났는지#

이 메시지는 사용자에게 무슨 일이 일어났는지, 그리고 실행 완료를 막는 현재 문제가 무엇인지 설명합니다.

• 오류를 유발한 매개변수의 displayName이 있다면, 이를 오류 메시지나 설명(또는 둘 다)에 포함하세요.
• 항목 인덱스: 오류를 유발한 항목의 ID가 있다면, 오류 메시지에 [Item X]를 덧붙이세요. 예를 들어, The ID of the release in the parameter "Release ID" for could not be found [item 2].
• "error", "problem", "failure", "mistake"와 같은 단어의 사용을 피하세요.

오류 설명 - 해결 방법 또는 막힌 상황에서 벗어나는 방법#

이 설명은 사용자에게 문제를 해결하는 방법, 노드 구성에서 무엇을 변경해야 하는지(그런 경우라면), 또는 막힌 상황에서 벗어나는 방법을 설명합니다. 여기서는 사용자를 다음 단계로 안내하고 막힌 상태를 풀어주어야 합니다.

"error", "problem", "failure", "mistake"와 같은 단어의 사용을 피하세요.