註冊
聯絡 登入 註冊
系統狀態

使用特定於類型的參數更新記錄上的自訂欄位值

設定自訂欄位值

自訂欄位擴展了 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! 如果操作成功則為真

所需權限

用戶必須有權編輯記錄和特定的自訂欄位：

角色 可以設定欄位值
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"
    }
  }]
}

重要注意事項

  • Upsert 行為：如果不存在，則該變更會創建一個新的欄位值，或更新現有值
  • 類型安全：僅提供與欄位類型匹配的參數（例如，不要為 NUMBER 欄位發送 text）
  • 副作用：設定值會觸發：
    • 公式欄位重新計算
    • 自動化規則
    • Webhook 通知
    • 活動日誌條目
    • 圖表更新
  • 特殊行為：
    • 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 助手

回應是使用人工智慧生成的，可能包含錯誤。

我能幫助您什麼？

隨時詢問我有關 Blue 或此文件的任何問題。

輸入發送 • Shift+Enter 進行換行 • ⌘I 打開