サインアップ
お問い合わせ ログイン サインアップ
システム状態

各フィールドタイプに特有のパラメータを使用してレコードのカスタムフィールドの値を更新します

カスタムフィールドの値を設定

カスタムフィールドは、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"
    }
  }]
}

重要な注意事項

  • アップサート動作: ミューテーションは、存在しない場合は新しいフィールド値を作成し、既存の値を更新します
  • 型安全性: フィールドタイプに一致するパラメータのみを提供してください（例：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アシスタント

回答はAIを使用して生成されており、間違いが含まれる可能性があります。

どのようにお手伝いできますか？

Blueやこのドキュメントについて何でも聞いてください。

送信するにはEnterを押してください • 新しい行を作成するにはShift+Enterを押してください • ⌘Iで開く