カスタムフィールドの定義を扱う


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

GUI で作るカスタムフィールドの定義(カスタムフィールド定義の概要)を、REST API で読み書きします。読み取り(field-definitions:read)は read に含まれますが、書き込み(field-definitions:write)は「強い権限」で、そのスコープを選んだトークンだけが使えます。どちらも、管理画面の定義の画面と同じ権限(定義の編集権限)が要ります。

操作

メソッドとパス

成功

定義の一覧(フィールドセットごと)

GET /field-definitions

200

フィールドセットの取得

GET /field-sets/{id}

200(ETag 付き)

フィールドセットの作成

POST /field-sets

201

フィールドセットの並べ替え

POST /field-sets/reorder

201

フィールドセットの更新

PATCH /field-sets/{id}(If-Match 必須)

200

フィールドセットの削除

DELETE /field-sets/{id}(If-Match 必須)

200(影響)

フィールド定義の取得

GET /field-definitions/{id}

200(ETag 付き)

フィールド定義の作成

POST /field-sets/{id}/fields

201

フィールド定義の並べ替え

POST /field-sets/{id}/fields/reorder

201

フィールド定義の更新

PATCH /field-definitions/{id}(If-Match 必須)

200

フィールド定義の複製

POST /field-definitions/{id}/duplicate

201

キーの変更

POST /field-definitions/{id}/rename-key(If-Match 必須)

201

フィールド定義の削除

DELETE /field-definitions/{id}(If-Match 必須)

200(影響)

テーマ・継承由来の定義を使わない / 使う

POST /field-definitions/suppress

201

定義を読む

GET /field-definitions は、URL のブログの ?entity_type=(既定 entry)のフィールドセットを、配下のフィールド定義を含めて返します。DB の定義に、テーマの宣言と祖先のブログから継承した定義を重ねた結果です。?status=open で使う定義だけにできます。

curl -s "${ACMS_API}/field-definitions/?entity_type=entry&status=open&limit=100" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
{
  "items": [
    {
      "id": 47,
      "code": "product",
      "label": "商品情報",
      "description": "",
      "status": "open",
      "source": "blog",
      "entity_type": "entry",
      "sort": 23,
      "scope": "local",
      "layout": { "placement": "main" },
      "conditions": null,
      "fields": [
        {
          "id": 127,
          "set_id": 47,
          "key": "color",
          "label": "色",
          "type": "select",
          "description": "",
          "status": "open",
          "source": "blog",
          "parent_key": null,
          "sort": 2,
          "search": true,
          "config": { "options": [{ "value": "red", "label": "赤" }, { "value": "blue", "label": "青" }] },
          "validation": { "required": "none", "rules": [] },
          "conditions": null,
          "updated_datetime": "2026-11-02T19:01:55+09:00",
          "blog_id": 1,
          "links": {
            "self": "https://example.com/rest-api/acms/v1/field-definitions/127/",
            "field_set": "https://example.com/rest-api/acms/v1/field-sets/47/",
            "blog": "https://example.com/rest-api/acms/v1/blogs/1/"
          }
        }
      ],
      "updated_datetime": "2026-11-02T19:01:55+09:00",
      "blog_id": 1,
      "links": { "self": "https://example.com/rest-api/acms/v1/field-sets/47/", "blog": "https://example.com/rest-api/acms/v1/blogs/1/" }
    }
  ],
  "meta": { "total": 24, "page": 1, "limit": 100, "last_page": 1 },
  "links": { "...": "..." }
}

source は由来です。blog(このブログの DB)・theme(テーマの宣言)・inherited(祖先のブログから継承)で、「使わない」にしたテーマ・継承由来は theme-suppressed・inherited-suppressed(status は close)です。テーマ・継承由来の定義は id が null で、単体の取得・更新はできません(一覧から読みます)。entity_type は entry・category・blog・user・module・component(コンポーネント)と、プラグインが登録したものです。

フィールドセットとフィールド定義を作る

フィールドセットを作ってから、その中にフィールド定義を足します。

# 1. フィールドセットを作る(code と label が必須。entity_type は省略すると entry)
curl -s -X POST "${ACMS_API}/field-sets/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{
    "code": "event_info",
    "label": "イベント情報",
    "entity_type": "entry",
    "status": "open",
    "scope": "local",
    "layout": { "placement": "main" },
    "conditions": { "or": [ { "and": [ { "subject": "category", "operator": "in", "value": ["3"] } ] } ] }
  }'

# 2. フィールド定義を足す(key・label・type が必須。例ではフィールドセットの ID を 48 とする)
curl -s -X POST "${ACMS_API}/field-sets/48/fields/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{"key":"event_date","label":"開催日","type":"date","search":false,"validation":{"required":"publish","rules":[]}}'

フィールドセットの項目

キー

説明

code

作成で必須。英数字とアンダースコア 64 文字まで。同じ entity_type・ブログで一意。既定のフィールドセット(default)のコードは変えられません

label

作成で必須。表示名

description

説明

status

open(使う)・close(編集画面に出さない)

entity_type

定義の対象。作成のときだけ指定でき、あとから変えられません

scope

local(定義したブログだけ)・global(子孫のブログにも継承)

layout.placement

編集画面で表示する場所(省略は main。エントリーは main・foot・side など)

conditions

フィールドセットを出す条件。null は常に出す。or の中の and のグループで書きます(例: {"subject":"category","operator":"in","value":["3"]})

duplicate_from

作成だけ。同じブログ・同じ entity_type のフィールドセットの ID を渡すと、配下の定義も同じ順で複製します

フィールド定義の項目

キー

説明

key

作成で必須。フィールドのキー(エントリーの fields の名前)。作成のときだけ指定でき、変えるには rename-key

label

作成で必須。ラベル

labels

ロケールごとのラベル(ロケールをキーにしたオブジェクト。定義があるときだけ返ります)

type

作成で必須。フィールドの型(text・number・select・group など、プラグインが登録した型を含む)

description

説明

status

open・close。削除するには先に close にします

parent_key

親(フィールドグループ・レイアウトの箱)のキー。同じフィールドセットの定義のキーだけ。null は親なし

search

キーワード検索の対象にするか

config

型ごとの設定(選択肢・最小値・書式など。キーは型ごとに決まっていて、camelCase のキーを含みます)。各型の設定は 入力の型の設定 などを参照してください

validation

required(none・save・publish)と、rules(method・arg・message の配列。管理画面のバリデーターのメソッド名と引数)

conditions

フィールドを出す条件(ほかのフィールドの値で出し分け)。null は常に出す

書き込みの応答の warnings には、保存は済んでいるがあとの対応が要る知らせ(検索対象の変更をキーワード検索へまだ反映していない、など)が入ります。キーワード検索の反映は ジョブ の POST /fulltext/rebuild で行えます。

更新・キーの変更・削除(If-Match 必須)

フィールドセット・フィールド定義の更新・キーの変更・削除は、If-Match が必須です。取得した ETag を付けます。無いか違うと 412 です。

ETAG=$(curl -s -D - -o /dev/null -H "Authorization: Bearer ${ACMS_API_TOKEN}" "${ACMS_API}/field-definitions/135/" \
  | awk 'tolower($1)=="etag:"{print $2}' | tr -d '\r')

# キーを変える前に、影響を確かめる(保存済みの値の行数と参照元)
curl -s -X POST "${ACMS_API}/field-definitions/135/rename-key/?dry_run=1" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" -H "If-Match: ${ETAG}" \
  -d '{"new_key":"price"}'

削除・キーの変更・型の変更の応答には、impact(影響)が入ります。

キー

説明

impact.values.rows / impact.values.revision_rows

このキーで保存済みの値の行数(現在の値 / 過去のバージョンの値)

impact.references.definitions

このキーを表示条件・入力の検証で参照する、このブログの定義(キーの変更では参照も書き換わる)

impact.references.theme_definitions

このキーを参照する、テーマが宣言した定義のキー(書き換えられない)

impact.fields

フィールドセットの削除だけ。配下のフィールドごとの key・rows・revision_rows

  • キーの変更は、保存済みの値(現在・過去のバージョン)のキーと、ほかの定義の参照も書き換えます。公開側のテンプレートの {キー} と、テーマが宣言した定義は書き換わりません。新しいキーが使えない・新しいキーに値がある場合は 422 です。

  • 型を変えると、値の形が変わる組み合わせ(text と textarea の間以外)は、保存済みの値があれば 409 です。

  • 削除できるのは、先に status を close にしたものだけです(open のままなら 409)。保存済みの値は消えず、公開側のテンプレートの {キー} も残ります。フィールドグループ・ブロックは中の定義も、タブの入れ物は中のタブも消えます。既定のフィールドセットは削除できません。

  • テーマ・継承由来の定義の更新は 409 です。

並べ替え・複製・使わない設定

# フィールドセットを並べたい順に(URL のブログのすべての ID を重複なく)
curl -s -X POST "${ACMS_API}/field-sets/reorder/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" -d '{"ids":[1,47,48]}'

# フィールドセットの中のフィールド定義を並べたい順に
curl -s -X POST "${ACMS_API}/field-sets/48/fields/reorder/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" -d '{"ids":[201,200]}'

# フィールド定義を同じフィールドセットの末尾へ複製(キーは <key>_copy・<key>_copy2 …)
curl -s -X POST "${ACMS_API}/field-definitions/200/duplicate/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"

# テーマが宣言した定義(キー subtitle)を、このブログでは使わない
curl -s -X POST "${ACMS_API}/field-definitions/suppress/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{"entity_type":"entry","key":"subtitle","source":"theme-suppressed","suppressed":true}'
  • 並べ替えの ids に、ほかのブログ・ほかのフィールドセット・テーマ由来・存在しない ID を含めると 422 です。

  • suppress の source は theme-suppressed(テーマの宣言。既定)か inherited-suppressed(祖先のブログから継承した定義)です。suppressed を false にすると、使う設定に戻します。元の宣言は書き換えません。

よくある質問・つまずき

write のトークンで定義を作れません(403 insufficient_scope)

定義の書き込みは「強い権限」の field-definitions:write が要ります。定義の削除・キーの変更・型の変更は、エントリーの入力と公開側のテンプレートを壊しうるためです。

PATCH が 412 になります

定義の更新は If-Match が必須です。GET /field-sets/{id} または GET /field-definitions/{id} の ETag を付けてください。

テーマの定義を GET /field-definitions/{id} で取得できません

単体の取得は、URL のブログの DB に保存した定義だけです。テーマ・継承由来の定義は、GET /field-definitions の一覧から読みます。