注册
联系 登录 注册
系统状态

使用特定于类型的参数更新记录上的自定义字段值

设置自定义字段值

自定义字段通过业务特定的数据扩展了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 打开