node의 UI가 검증된 커뮤니티 node 후보가 되려면 이 가이드라인을 준수해야 합니다.

자격 증명#

API 키 및 민감한 자격 증명은 항상 비밀번호 필드여야 합니다.

OAuth#

사용 가능한 경우 항상 OAuth 자격 증명을 포함합니다.

Node 구조#

포함할 오퍼레이션#

각 리소스 타입에 대해 CRUD 오퍼레이션을 포함하도록 노력합니다.

각 리소스의 node에 일반적인 오퍼레이션을 포함하도록 노력합니다. n8n은 일관된 경험을 유지하고 사용자가 리소스에 대한 기본 오퍼레이션을 수행할 수 있도록 일부 CRUD 오퍼레이션을 사용합니다. 권장 오퍼레이션은 다음과 같습니다:

• Create
• Create or Update (Upsert)
• Delete
• Get
• Get Many: 일부 필터링 또는 검색이 가능할 때도 사용
• Update

참고:

1. 이 오퍼레이션은 리소스 자체 또는 리소스 내의 엔티티(예: Google Sheet의 행)에 적용될 수 있습니다. 리소스 내의 엔티티에 대해 오퍼레이션하는 경우 오퍼레이션 이름에 엔티티 이름을 명시해야 합니다.
2. node와 리소스에 따라 이름이 달라질 수 있습니다. 자세한 내용은 다음 가이드라인을 확인하세요.

Resource Locator#

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

다른 node와의 일관성#

• UX 일관성 유지: n8n은 UX를 일관되게 유지하려고 합니다. 이는 기존 UX 패턴, 특히 최신 신규 또는 개선된 node에서 사용하는 패턴을 따르는 것을 의미합니다.
• 유사한 node 확인: 예를 들어, 데이터베이스 node를 작업 중인 경우 Postgres node를 확인하는 것이 좋습니다.

정렬 옵션#

• 사용자에게 정렬 옵션을 제공하여 특정 "Get Many" 오퍼레이션을 향상시킬 수 있습니다.
• "Options" collection 아래에 전용 collection에 정렬을 추가합니다. Airtable Record:Search 예시를 따르세요.

Node 기능#

오퍼레이션 출력 삭제#

항목(레코드나 행 등)을 삭제할 때 단일 오브젝트가 있는 배열 {"deleted": true}를 반환합니다. 이는 삭제가 성공했다는 사용자 확인이며 해당 항목이 다음 node를 트리거합니다.

출력 필드 단순화#

일반 node: 'Simplify' 파라미터#

엔드포인트가 10개 이상의 필드로 데이터를 반환하는 경우, 최대 10개 필드로 단순화된 출력 버전을 반환하는 "Simplify" 불리언 파라미터를 추가합니다.

• n8n의 주요 문제 중 하나는 데이터 크기이며 Simplify 파라미터는 데이터 크기를 줄여 해당 문제를 제한합니다.
• 단순화된 node에서 출력할 가장 유용한 필드를 선택하고 가장 많이 사용되는 것을 맨 위에 정렬합니다.
• Simplify 모드에서는 중첩된 필드를 평탄화하는 것이 종종 최선입니다.
• Display Name: Simplify
• Description: Whether to return a simplified version of the response instead of the raw data

AI 도구 node: 'Output' 파라미터#

엔드포인트가 10개 이상의 필드로 데이터를 반환하는 경우, 3가지 모드가 있는 'Output' 옵션 파라미터를 추가합니다.

AI 도구 node에서는 사용자가 더 세밀하게 출력할 필드를 선택할 수 있도록 합니다. 도구가 컨텍스트 윈도우를 소진할 수 있고 너무 많은 필드로 혼란스러워질 수 있으므로, 필요한 것만 전달하는 것이 좋습니다.

옵션:

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

카피#

텍스트 대소문자#

node name, parameters display names(레이블), dropdown titles에는 Title Case를 사용합니다. Title Case는 관사와 짧은 전치사와 같은 특정 작은 단어를 제외하고 각 단어의 첫 글자를 대문자로 쓰는 것입니다.

node action 이름, node descriptions, parameters descriptions(툴팁), hints, dropdown descriptions에는 Sentence case를 사용합니다.

용어#

• 서드파티 서비스 용어 사용: 인터페이스하는 서비스와 동일한 용어를 사용하세요(예: Notion '단락'이 아닌 Notion '블록').
• UI에서 사용하는 용어 사용: API나 기술 문서에서 사용하는 것보다 서비스의 사용자 인터페이스에서 사용하는 용어를 고수하세요(예: Trello에서는 카드를 "아카이브"하지만 API에서는 "closed"로 표시됩니다. 이 경우 "archive"를 사용하는 것이 좋을 수 있습니다).
• 기술 용어 금지: 간단한 단어로 충분한 곳에 기술 용어를 사용하지 마세요. 예를 들어 "key" 대신 "field"를 사용합니다.
• 일관된 명명: 어떤 것에 대해 하나의 용어를 선택하고 그것을 고수하세요. 예를 들어 "directory"와 "folder"를 혼용하지 마세요.

플레이스홀더#

파라미터 플레이스홀더에 콘텐츠 예시를 삽입하는 것이 도움이 될 수 있습니다. "e.g."로 시작하고 필드의 데모 콘텐츠에 camel case를 사용해야 합니다.

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

• image: e.g. https://example.com/image.png
• video: e.g. https://example.com/video.mp4
• search term: e.g. automation
• email: e.g. nathan@example.com
• Twitter user (or similar): e.g. n8n
• Name and last name: e.g. Nathan Smith
• First name: e.g. Nathan
• Last name: e.g. Smith

오퍼레이션 이름, 액션, 설명#

• Name: 캔버스에서 node를 열 때 선택 항목에 표시되는 이름입니다. title case를 사용해야 하며 리소스를 포함하지 않아도 됩니다(예: "Delete").
• Action: 사용자가 node를 선택하는 패널에 표시되는 오퍼레이션 이름입니다. sentence case여야 하며 리소스를 포함해야 합니다(예: "Delete record").
• Description: 캔버스에서 node를 열 때 선택 항목에서 이름 아래에 표시되는 하위 텍스트입니다. sentence case를 사용해야 하며 리소스를 포함해야 합니다. 약간의 정보를 추가하고 기본 리소스/오퍼레이션 외에 다른 단어를 사용할 수 있습니다(예: "Retrieve a list of users").
• 오퍼레이션이 Resource가 아닌 엔티티(예: Google Sheet의 행)에 적용되는 경우 오퍼레이션 이름에 명시합니다(예: "Delete Row").

일반적인 규칙으로, 오퍼레이션의 오브젝트가 무엇인지 이해하는 것이 중요합니다. 경우에 따라 오퍼레이션의 오브젝트는 리소스 자체입니다(예: Sheet:Delete - 시트 삭제).

다른 경우에는 오퍼레이션의 오브젝트가 리소스가 아니라 리소스 안에 포함된 것입니다(예: Table:Delete rows - 여기서 리소스는 테이블이지만 오퍼레이션하는 것은 그 안의 행입니다).

name 명명#

캔버스에서 node를 열 때 선택 항목에 표시되는 이름입니다.

• 파라미터: name
• 대소문자: Title Case

명명 가이드라인:

• 리소스를 반복하지 않음 (위에 리소스 선택이 있는 경우): 리소스는 오퍼레이션 위에 표시되는 경우가 많으므로 오퍼레이션에서 반복할 필요가 없습니다(오퍼레이션의 오브젝트가 리소스 자체인 경우).
  • 예: Sheet:Delete → 위 필드에 Sheet가 표시되고 삭제하는 것이 Sheet이므로 Delete에서 Sheet를 반복할 필요 없음.
• 위에 리소스 선택이 없는 경우 리소스 명시: 일부 node에는 리소스 선택이 없습니다(리소스가 하나이므로). 이런 경우 오퍼레이션에서 리소스를 명시합니다.
  • 예: Delete Records → Airtable에는 리소스 선택이 없으므로 Delete 오퍼레이션이 레코드를 삭제한다는 것을 명시하는 것이 좋습니다.
• 오퍼레이션의 오브젝트가 리소스가 아닌 경우 명시: 오퍼레이션의 오브젝트가 리소스가 아닌 경우가 있습니다. 이런 경우 오퍼레이션에서도 오브젝트를 명시합니다.
  • 예: Table:Get Columns → 리소스는 Table이고 오퍼레이션의 오브젝트는 Columns이므로 Columns를 명시합니다.

action 명명#

사용자가 node를 선택하는 패널에 표시되는 오퍼레이션 이름입니다.

• 파라미터: action
• 대소문자: Sentence case

명명 가이드라인:

• 관사 생략: 텍스트를 더 짧게 유지하기 위해 관사(a, an, the…)를 제거합니다.
  • correct: Update row in sheet
  • incorrect: Update a row in a sheet
• 리소스 반복: 이 경우에는 리소스를 반복해도 괜찮습니다. 목록에서 리소스가 보이더라도 사용자가 알아채지 못할 수 있고 오퍼레이션 레이블에서 반복하면 유용합니다.
• 오퍼레이션의 오브젝트가 리소스가 아닌 경우 명시: 오퍼레이션 이름과 동일합니다. 이 경우 리소스를 반복할 필요가 없습니다.
  • 예: Append Rows → 실제로 추가하는 것이 행이므로 Rows를 명시해야 합니다. 추가하는 것이 리소스(Sheet)가 아니므로 리소스는 추가하지 않습니다.

description 명명#

캔버스에서 node를 열 때 선택 항목에서 이름 아래에 표시되는 하위 텍스트입니다.

• 파라미터: description
• 대소문자: Sentence case

명명 가이드라인:

• 가능하면 오퍼레이션 name에 명시된 것보다 더 많은 정보를 추가합니다.
• 사용자가 오퍼레이션이 무엇을 하는지 더 잘 이해할 수 있도록 다른 표현을 사용합니다. 일부 사람들은 오퍼레이션에 사용된 텍스트를 이해하지 못할 수 있으며(영어가 모국어가 아닌 경우), 다른 표현을 사용하면 도움이 될 수 있습니다.

어휘#

n8n은 일반 어휘와 유사한 애플리케이션 그룹(예: 데이터베이스 또는 스프레드시트)에 대한 컨텍스트별 어휘를 사용합니다.

일반 어휘는 CRUD 오퍼레이션에서 영감을 받습니다:

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

파라미터 및 필드 이름 참조#

카피에서 파라미터 이름이나 필드 이름을 참조해야 할 때 작은따옴표로 감쌉니다(예: "Please fill the 'name' parameter).

불리언 설명#

불리언 컴포넌트의 설명은 'Whether...'로 시작합니다.

오류#

일반 철학#

오류는 사용자에게 고통의 원인입니다. 이런 이유로 n8n은 항상 사용자에게 다음을 알려주려 합니다:

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

출력 패널의 오류 구조#

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

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

• 오류를 트리거한 파라미터의 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"와 같은 단어 사용을 피합니다.

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

설명은 사용자에게 문제 해결 방법, node 구성에서 변경할 사항(해당하는 경우) 또는 막힌 상태에서 벗어나는 방법을 설명합니다. 여기서 다음 단계로 안내하고 막힌 상태를 해소해야 합니다.

"error", "problem", "failure", "mistake"와 같은 단어 사용을 피합니다.