회원가입
문의 로그인 회원가입
시스템 상태

각 필드 유형에 대한 유형별 매개변수를 사용하여 레코드의 사용자 정의 필드 값을 업데이트합니다.

사용자 정의 필드 값 설정

사용자 정의 필드는 Blue의 표준 레코드 구조를 비즈니스 특정 데이터로 확장합니다. 이 엔드포인트를 사용하면 레코드의 모든 사용자 정의 필드에 대한 값을 설정하거나 업데이트할 수 있습니다. 각 필드 유형은 데이터 무결성과 적절한 유효성을 보장하기 위해 특정 매개변수를 요구합니다.

기본 예제

mutation SetTextFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_xyz789"
    text: "Project specification document"
  })
}

고급 예제

mutation SetMultipleFieldTypes {
  # Set a date range field
  dateField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_date_001"
    startDate: "2024-01-15T09:00:00Z"
    endDate: "2024-01-31T17:00:00Z"
    timezone: "America/New_York"
  })
  
  # Set a multi-select field
  selectField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_select_002"
    customFieldOptionIds: ["option_high", "option_urgent", "option_client"]
  })
  
  # Set a location field
  locationField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_location_003"
    latitude: 40.7128
    longitude: -74.0060
  })
}

입력 매개변수

SetTodoCustomFieldInput

매개변수 유형 필수 설명
todoId String! ✅ 예 업데이트할 레코드의 ID
customFieldId String! ✅ 예 사용자 정의 필드의 ID
text String 아니오 TEXT_SINGLE, TEXT_MULTI, PHONE, EMAIL, URL의 경우
number Float 아니오 NUMBER, PERCENT, RATING의 경우
currency String 아니오 CURRENCY 유형의 통화 코드 (예: "USD")
checked Boolean 아니오 CHECKBOX 필드의 경우
startDate DateTime 아니오 DATE 필드의 시작 날짜
endDate DateTime 아니오 DATE 범위 필드의 종료 날짜
timezone String 아니오 DATE 필드의 시간대 (예: "America/New_York")
latitude Float 아니오 LOCATION 필드의 위도
longitude Float 아니오 LOCATION 필드의 경도
regionCode String 아니오 PHONE 필드의 지역 코드
countryCodes [String!] 아니오 COUNTRY 필드의 ISO 국가 코드
customFieldOptionId String 아니오 SELECT_SINGLE 필드의 옵션 ID
customFieldOptionIds [String!] 아니오 SELECT_MULTI 필드의 옵션 ID
customFieldReferenceTodoIds [String!] 아니오 REFERENCE 필드의 레코드 ID

필드 유형 예제

텍스트 필드

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_description"
    text: "Detailed project requirements and specifications"
  })
}

숫자 필드

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_budget"
    number: 15000.50
  })
}

선택 필드

# Single Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_priority"
    customFieldOptionId: "option_high"
  })
}

# Multi Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_tags"
    customFieldOptionIds: ["option_frontend", "option_urgent", "option_v2"]
  })
}

날짜 필드

# Single Date
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_deadline"
    startDate: "2024-12-31T23:59:59Z"
  })
}

# Date Range
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_project_timeline"
    startDate: "2024-01-01T00:00:00Z"
    endDate: "2024-03-31T23:59:59Z"
    timezone: "UTC"
  })
}

위치 필드

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_office_location"
    latitude: 37.7749
    longitude: -122.4194
  })
}

통화 필드

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_invoice_amount"
    number: 5000
    currency: "USD"
  })
}

파일 필드

파일 필드는 별도의 변형을 사용합니다:

# Add a file
mutation {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

# Remove a file
mutation {
  deleteTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

레코드 생성 중 값 설정

새 레코드를 생성할 때 사용자 정의 필드 값을 설정할 수 있습니다:

mutation {
  createTodo(input: {
    todoListId: "list_project_123"
    title: "New Feature Development"
    customFields: [
      {
        customFieldId: "field_priority"
        value: "high"
      },
      {
        customFieldId: "field_estimate"
        value: "8"
      }
    ]
  }) {
    id
    customFields {
      customField {
        name
      }
      value
    }
  }
}

응답 필드

변형은 성공 여부를 나타내는 부울 값을 반환합니다:

필드 유형 설명
setTodoCustomField Boolean! 작업이 성공하면 True

필수 권한

사용자는 레코드와 특정 사용자 정의 필드를 편집할 수 있는 권한이 있어야 합니다:

역할 필드 값 설정 가능
OWNER ✅ 예
ADMIN ✅ 예
MEMBER ✅ 예 (사용자 정의 역할에 의해 제한되지 않는 경우)
CLIENT ✅ 예 (사용자 정의 역할에 의해 제한되지 않는 경우)

사용자 정의 프로젝트 역할이 있는 사용자의 경우 시스템은 두 단계 검사를 수행합니다:

  1. 먼저 사용자가 프로젝트 수준 접근 권한이 있는지 확인합니다.
  2. 그런 다음 특정 필드가 사용자 정의 역할 구성에서 editable로 표시되어 있는지 확인합니다.

이는 사용자가 일반 프로젝트 접근 권한을 가질 수 있지만, 사용자 정의 역할에 따라 특정 필드를 편집하는 것이 제한될 수 있음을 의미합니다.

오류 응답

사용자 정의 필드를 찾을 수 없음

{
  "errors": [{
    "message": "Custom field was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

권한 없는 접근

{
  "errors": [{
    "message": "You are not authorized.",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

잘못된 필드 값

{
  "errors": [{
    "message": "Invalid value for field type NUMBER",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

중요 사항

  • 업서트 동작: 변형은 필드 값이 없으면 새 값을 생성하고, 기존 값을 업데이트합니다.
  • 유형 안전성: 필드 유형과 일치하는 매개변수만 제공하십시오 (예: NUMBER 필드에 text를 보내지 마십시오).
  • 부작용: 값을 설정하면 다음이 발생합니다:
    • 수식 필드 재계산
    • 자동화 규칙
    • 웹훅 알림
    • 활동 로그 항목
    • 차트 업데이트
  • 특별 동작:
    • CURRENCY 필드는 자동으로 변환 계산을 처리합니다.
    • REFERENCE 필드는 양방향 관계를 업데이트합니다.
    • FORMULA 필드는 읽기 전용이며 직접 설정할 수 없습니다 (자동으로 계산됩니다).
    • LOOKUP 필드는 읽기 전용이며 직접 설정할 수 없습니다 (참조된 레코드에서 데이터를 가져옵니다).
    • BUTTON 필드는 "클릭"될 때 자동화 이벤트를 트리거합니다.
  • 유효성 검사: API는 다음을 확인합니다:
    • 레코드가 프로젝트에 존재하는지
    • 사용자 정의 필드가 동일한 프로젝트에 존재하는지
    • 사용자가 편집 권한이 있는지
    • 값이 필드 유형 요구 사항과 일치하는지

값 형식 참조

필드 유형 매개변수 형식 예시
TEXT_SINGLE text String "Project Alpha"
TEXT_MULTI text String with newlines "Line 1\nLine 2"
NUMBER number Float 42.5
CURRENCY number + currency Float + ISO code 1000.00 + "USD"
PERCENT number Float (0-100) 75
RATING number Float (within min/max) 4.5
CHECKBOX checked Boolean true
DATE startDate ISO 8601 DateTime "2024-01-15T00:00:00Z"
DATE (range) startDate + endDate ISO 8601 DateTimes See example above
SELECT_SINGLE customFieldOptionId Option ID "option_123"
SELECT_MULTI customFieldOptionIds Array of Option IDs ["opt_1", "opt_2"]
PHONE text String "+1-555-123-4567"
EMAIL text String "user@example.com"
URL text String "https://example.com"
LOCATION latitude + longitude Floats 40.7128, -74.0060
COUNTRY countryCodes ISO 3166 codes ["US", "CA"]
REFERENCE customFieldReferenceTodoIds Array of record IDs ["todo_1", "todo_2"]
FORMULA N/A Read-only - calculated automatically N/A
LOOKUP N/A Read-only - pulls from references N/A

관련 엔드포인트

© Blue | 사랑으로 디자인 ❤ 전체에 걸쳐

AI 어시스턴트

응답은 AI를 사용하여 생성되며 오류가 포함될 수 있습니다.

어떻게 도와드릴까요?

Blue 또는 이 문서에 대해 궁금한 점이 있으면 무엇이든 물어보세요.

전송하려면 Enter • 새 줄을 추가하려면 Shift+Enter • ⌘I를 눌러 열기