---

カスタムフィールドの一覧

カスタムフィールドを使用すると、ビジネスニーズに特有の追加データフィールドで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フィールドは、現在のユーザーがこのカスタムフィールドの値を変更できるかどうかを示します

関連エンドポイント

• カスタムフィールドの作成 - プロジェクトに新しいカスタムフィールドを追加
• カスタムフィールドの更新 - 既存のカスタムフィールドのプロパティを変更
• カスタムフィールドの削除 - プロジェクトからカスタムフィールドを削除
• カスタムフィールド値の設定 - レコードに値を設定