---

모든 사용자 정의 필드 목록

사용자 정의 필드는 귀하의 비즈니스 요구에 맞는 추가 데이터 필드로 Blue의 표준 레코드 구조를 확장할 수 있게 해줍니다. 이 엔드포인트는 필드 유형별로 필터링하고 페이지 매김 지원을 통해 귀하의 프로젝트에서 사용할 수 있는 사용자 정의 필드를 검색합니다.

기본 예제

query ListCustomFields {
  customFields(
    filter: { projectId: "project_123" }
    sort: position_ASC
    take: 20
  ) {
    items {
      id
      uid
      name
      type
      position
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

고급 예제

query ListCustomFieldsAdvanced {
  customFields(
    filter: {
      projectId: "project_123"
      types: [TEXT_SINGLE, NUMBER, SELECT_SINGLE]
    }
    sort: name_ASC
    skip: 20
    take: 50
  ) {
    items {
      id
      uid
      name
      type
      position
      description
      
      # Type-specific fields
      min              # For NUMBER, RATING, PERCENT
      max              # For NUMBER, RATING, PERCENT
      currency         # For CURRENCY type
      prefix           # For UNIQUE_ID type
      isDueDate        # For DATE type
      formula          # For FORMULA type
      
      # Validation settings
      editable
      metadata
      
      # For SELECT types
      customFieldOptions {
        id
        title
        color
        position
      }
    }
    pageInfo {
      totalItems
      hasNextPage
      hasPreviousPage
    }
  }
}

입력 매개변수

CustomFieldFilterInput

매개변수	유형	필수	설명
projectId	String	아니오	특정 프로젝트 ID로 필터링
types	[CustomFieldType!]	아니오	사용자 정의 필드 유형으로 필터링

CustomFieldSort 값

값	설명
name_ASC	이름 오름차순으로 정렬 (A-Z)
name_DESC	이름 내림차순으로 정렬 (Z-A)
createdAt_ASC	생성일로 정렬 (가장 오래된 것 먼저)
createdAt_DESC	생성일로 정렬 (가장 최근 것 먼저)
position_ASC	위치로 정렬 (기본값)
position_DESC	위치 내림차순으로 정렬

CustomFieldType 값

값	설명
TEXT_SINGLE	단일 행 텍스트 입력
TEXT_MULTI	다중 행 텍스트 영역
SELECT_SINGLE	단일 선택 드롭다운
SELECT_MULTI	다중 선택 드롭다운
CHECKBOX	불리언 체크박스 필드
RATING	별점 (1-5 또는 사용자 정의 범위)
PHONE	유효성 검사가 있는 전화번호
NUMBER	숫자 입력
CURRENCY	통화 금액
PERCENT	백분율 값
EMAIL	유효성 검사가 있는 이메일 주소
URL	유효성 검사가 있는 웹 URL
UNIQUE_ID	자동 생성된 고유 식별자
LOCATION	지리적 위치 (위도/경도)
FILE	파일 첨부
DATE	날짜 선택기
COUNTRY	국가 선택기
FORMULA	다른 필드를 기반으로 계산된 필드
REFERENCE	다른 프로젝트의 레코드에 대한 링크
LOOKUP	참조된 레코드에서 데이터 가져오기
TIME_DURATION	시간 추적 필드
BUTTON	작업 가능한 버튼 필드
CURRENCY_CONVERSION	통화 변환 필드

페이지 매김 매개변수

매개변수	유형	필수	설명
skip	Int	아니오	건너뛸 항목 수 (기본값: 0)
take	Int	아니오	반환할 항목 수 (기본값: 20, 최대: 500)

응답 필드

CustomField

필드	유형	설명
id	String!	고유 식별자
uid	String!	고유 사용자 친화적 ID
name	String!	필드의 표시 이름
type	CustomFieldType!	사용자 정의 필드의 유형
position	Float!	정렬 순서 위치
description	String	선택적 필드 설명
min	Float	최소 값 (NUMBER, RATING, PERCENT)
max	Float	최대 값 (NUMBER, RATING, PERCENT)
currency	String	통화 코드 (CURRENCY 유형)
prefix	String	UNIQUE_ID 생성을 위한 접두사
isDueDate	Boolean	DATE 필드가 마감일을 나타내는지 여부
formula	JSON	수식 구성 (FORMULA 유형)
editable	Boolean	현재 사용자가 이 필드를 편집할 수 있는지 여부
metadata	JSON	추가 필드 구성
customFieldOptions	[CustomFieldOption!]	SELECT 유형에 대한 사용 가능한 옵션

CustomFieldOption

필드	유형	설명
id	String!	고유 식별자
title	String!	옵션의 표시 텍스트
color	String!	16진수 색상 코드
position	Float!	정렬 순서 위치

PageInfo

필드	유형	설명
totalItems	Int	총 사용자 정의 필드 수
hasNextPage	Boolean!	더 많은 페이지가 존재하는지 여부
hasPreviousPage	Boolean!	이전 페이지가 존재하는지 여부
endCursor	String	페이지 매김을 위한 커서 (사용 중단 - 오프셋 기반 페이지 매김 사용)

필수 권한

사용자 정의 필드는 귀하의 프로젝트 역할에 따라 접근할 수 있습니다. 필드 접근이 제한된 사용자 정의 역할이 있는 경우, 귀하의 역할에 대해 편집 가능한 것으로 표시된 필드만 반환됩니다.

역할	사용자 정의 필드 목록 가능 여부
OWNER	✅ 예 (모든 필드)
ADMIN	✅ 예 (모든 필드)
MEMBER	✅ 예 (역할 권한에 따라)
CLIENT	✅ 예 (역할 권한에 따라)

오류 응답

프로젝트를 찾을 수 없음

{
  "errors": [{
    "message": "Project not found.",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

잘못된 필드 유형

{
  "errors": [{
    "message": "Variable \"$filter\" got invalid value \"INVALID_TYPE\" at \"filter.types[0]\"; Value \"INVALID_TYPE\" does not exist in \"CustomFieldType\" enum.",
    "extensions": {
      "code": "GRAPHQL_VALIDATION_FAILED"
    }
  }]
}

중요 사항

• 사용자 정의 필드는 프로젝트에 국한됩니다 - 필터에서 projectId를 지정해야 합니다.
• take 매개변수는 성능을 위해 요청당 500 항목으로 제한됩니다.
• 필드는 사용자 권한에 따라 반환됩니다 - 사용자 정의 역할은 접근이 제한될 수 있습니다.
• 기본 정렬 순서는 position 오름차순이며, 이는 UI에 표시된 순서를 반영합니다.
• 이 쿼리는 단일 프로젝트 필터링을 지원합니다 - 다중 프로젝트 쿼리의 경우 중첩된 CustomFieldQueries 인터페이스를 사용하십시오.
• 일부 필드 유형(예: FORMULA 및 REFERENCE)은 추가 중첩 데이터 구조를 포함할 수 있습니다.
• editable 필드는 현재 사용자가 이 사용자 정의 필드의 값을 수정할 수 있는지 여부를 나타냅니다.

관련 엔드포인트

• 사용자 정의 필드 생성 - 프로젝트에 새로운 사용자 정의 필드 추가
• 사용자 정의 필드 업데이트 - 기존 사용자 정의 필드 속성 수정
• 사용자 정의 필드 삭제 - 프로젝트에서 사용자 정의 필드 제거
• 사용자 정의 필드 값 설정 - 레코드에 값 설정