カスタムフィールドの定義を扱う
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
GUI で作るカスタムフィールドの定義(カスタムフィールド定義の概要)を、REST API で読み書きします。読み取り(field-definitions:read)は read に含まれますが、書き込み(field-definitions:write)は「強い権限」で、そのスコープを選んだトークンだけが使えます。どちらも、管理画面の定義の画面と同じ権限(定義の編集権限)が要ります。
操作 | メソッドとパス | 成功 |
|---|---|---|
定義の一覧(フィールドセットごと) |
| 200 |
フィールドセットの取得 |
| 200( |
フィールドセットの作成 |
| 201 |
フィールドセットの並べ替え |
| 201 |
フィールドセットの更新 |
| 200 |
フィールドセットの削除 |
| 200(影響) |
フィールド定義の取得 |
| 200( |
フィールド定義の作成 |
| 201 |
フィールド定義の並べ替え |
| 201 |
フィールド定義の更新 |
| 200 |
フィールド定義の複製 |
| 201 |
キーの変更 |
| 201 |
フィールド定義の削除 |
| 200(影響) |
テーマ・継承由来の定義を使わない / 使う |
| 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":[]}}'フィールドセットの項目
キー | 説明 |
|---|---|
| 作成で必須。英数字とアンダースコア 64 文字まで。同じ |
| 作成で必須。表示名 |
| 説明 |
|
|
| 定義の対象。作成のときだけ指定でき、あとから変えられません |
|
|
| 編集画面で表示する場所(省略は |
| フィールドセットを出す条件。 |
| 作成だけ。同じブログ・同じ |
フィールド定義の項目
キー | 説明 |
|---|---|
| 作成で必須。フィールドのキー(エントリーの |
| 作成で必須。ラベル |
| ロケールごとのラベル(ロケールをキーにしたオブジェクト。定義があるときだけ返ります) |
| 作成で必須。フィールドの型( |
| 説明 |
|
|
| 親(フィールドグループ・レイアウトの箱)のキー。同じフィールドセットの定義のキーだけ。 |
| キーワード検索の対象にするか |
| 型ごとの設定(選択肢・最小値・書式など。キーは型ごとに決まっていて、camelCase のキーを含みます)。各型の設定は 入力の型の設定 などを参照してください |
|
|
| フィールドを出す条件(ほかのフィールドの値で出し分け)。 |
書き込みの応答の 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(影響)が入ります。
キー | 説明 |
|---|---|
| このキーで保存済みの値の行数(現在の値 / 過去のバージョンの値) |
| このキーを表示条件・入力の検証で参照する、このブログの定義(キーの変更では参照も書き換わる) |
| このキーを参照する、テーマが宣言した定義のキー(書き換えられない) |
| フィールドセットの削除だけ。配下のフィールドごとの |
キーの変更は、保存済みの値(現在・過去のバージョン)のキーと、ほかの定義の参照も書き換えます。公開側のテンプレートの
{キー}と、テーマが宣言した定義は書き換わりません。新しいキーが使えない・新しいキーに値がある場合は 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 の一覧から読みます。