メインコンテンツまでスキップ

REST API 出力フィールドの限定

このページでは、GET /api/apps/{appsId}/records の fields パラメータの仕様を確認できます。

fieldsとは​

fields は、レコード一覧取得時に出力するフィールドを限定するためのパラメータです。不要なフィールドを除外することで、レスポンスサイズと処理時間を削減できます。

GET /api/apps/10/records?fields=customer-name,amount

未指定の場合は、すべてのフィールドを出力します。

書き方​

基本構文​

フィールド識別名をカンマ区切りで指定します。

fields=フィールド識別名1,フィールド識別名2

例:

GET /api/apps/10/records?fields=customer-name,category,amount

レスポンスの record には、指定したフィールドのみが含まれます。

{
    "records": [
        {
            "recordId": 1,
            "uniqueId": "...",
            "createdAt": "2026-01-20 10:00:00",
            "record": {
                "customer-name": "株式会社サンプル",
                "category": "既存顧客",
                "amount": 100000
            }
        }
    ]
}

選択肢の関連コードを出力する​

次のフィールドタイプは、フィールド識別名の末尾に [1]〜[3] を付けることで、選択肢名の代わりに関連コード1〜3を出力できます。

  • 単一選択(コンボボックス)
  • 単一選択(ラジオボタン)
  • 複数選択(リストボックス)
  • 複数選択(チェックボックス)

例:

GET /api/apps/10/records?fields=customer-name,category[1]

省略した場合は選択肢名を出力します。

[ ] をURLに含める場合は %5B %5D を使用してください。

常に出力されるフィールド​

次のシステムフィールドは、fields の指定内容にかかわらず常に出力されます。除外はできません。

  • recordId
  • uniqueId
  • status（プロセス機能を使用している場合）
  • isDeleted
  • createdAt
  • creatorCode
  • creator
  • updatedAt
  • updaterCode
  • updater
  • accessUrl
  • accessEditUrl

fields で限定できるのは record 内のフィールドのみです。

明細フィールド​

  • 明細フィールドを指定した場合、その明細内のすべての列が出力されます。明細内の列単位で限定することはできません。
  • 明細フィールドを指定しなかった場合、その明細は出力されません。

ソート（order）との関係​

order に指定できるのは、fields で出力対象にしたフィールドとシステムフィールドのみです。出力対象外のフィールドを order に指定すると 400 Bad Request になります。

# エラーになる例（amountがfieldsに含まれていない）
GET /api/apps/10/records?fields=customer-name&order=amount:desc

# 正しい例
GET /api/apps/10/records?fields=customer-name,amount&order=amount:desc

システムフィールド（recordId uniqueId status createdAt updatedAt creator updater creatorCode updaterCode など）は常に出力対象のため、fields に含めなくてもソートできます。

なお、明細フィールドは order に指定できません。

利用者選択・組織選択フィールド​

利用者選択・組織選択フィールドを指定した場合、値は管理コード（code）と名称（name）を持つオブジェクトの配列で出力されます。どちらか一方のみを出力することはできません。

GET /api/apps/10/records?fields=staff,department

レスポンス（抜粋）:

{
    "records": [
        {
            "recordId": 1,
            "record": {
                "staff": [
                    {
                        "code": "1001",
                        "name": "山田 太郎"
                    },
                    {
                        "code": "1002",
                        "name": "鈴木 花子"
                    }
                ],
                "department": [
                    {
                        "code": "SALES",
                        "name": "営業部"
                    }
                ]
            }
        }
    ]
}

値が未設定の場合は空の配列（[]）を出力します。

エラー時の挙動​

  • 存在しないフィールド識別名を指定した場合、400 Bad Request（指定されたフィールド[xxx]が存在しません。）になります。
  • 出力に対応していないフィールドタイプを指定した場合、400 Bad Request（指定されたフィールド[xxx]は出力できません。）になります。

共通仕様の「存在しないフィールドをリクエストに含めた場合、その値は無視されます。」はレコードの登録・更新時のリクエストボディに対する挙動であり、fields には適用されません。

制限事項​

fields に対応しているのはレコード一覧API（GET /api/apps/{appsId}/records）のみです。レコード情報取得API（GET /api/apps/{appsId}/records/{recordId}）では指定できません（指定しても無視され、すべてのフィールドが出力されます）。

よく使う例​

# 特定フィールドのみ取得
GET /api/apps/10/records?fields=customer-name,amount

# 選択肢を関連コードで取得
GET /api/apps/10/records?fields=customer-name,category[1]

# 出力を限定しつつソート
GET /api/apps/10/records?fields=customer-name,amount&order=amount:desc

# クエリ検索と併用
GET /api/apps/10/records?fields=customer-name,amount&query=status%20%3D%20%22完了%22