モジュール ID・ルール・コンフィグを扱う


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

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

サイトの設定に関わるリソースを扱います。どれも管理画面の同じ画面と同じ権限が要ります(多くは管理者)。設定キーの書き込み(configs:write)は「強い権限」のスコープです。

モジュール ID

操作

メソッドとパス

スコープ

一覧・取得

GET /modules・GET /modules/{id}

modules:read

作成

POST /modules

modules:write

更新

PATCH /modules/{id}・PUT /modules/{id}

modules:write

複製

POST /modules/{id}/duplicate

modules:write

削除

DELETE /modules/{id}

modules:write

curl -s -X POST "${ACMS_API}/modules/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{
    "identifier": "news_summary",
    "name": "Entry_Summary",
    "label": "お知らせの一覧",
    "status": "open",
    "scope": "local",
    "cache": 0,
    "arguments": { "cid": { "value": "3", "axis": "self" } },
    "config": { "entry_summary_limit": "5", "entry_summary_order": "datetime-desc" }
  }'
{
  "id": 1,
  "identifier": "archive_list",
  "name": "Entry_ArchiveList",
  "label": "エントリーアーカイブリスト",
  "description": null,
  "status": "open",
  "scope": "local",
  "cache": 0,
  "api_use": false,
  "layout_use": false,
  "custom_field": false,
  "arguments": {
    "bid": { "value": null, "scope": null, "axis": "self" },
    "uid": { "value": null, "scope": "local", "axis": null },
    "cid": { "value": null, "scope": "global", "axis": "self" },
    "eid": { "value": null, "scope": "local", "axis": null },
    "keyword": { "value": null, "scope": "local", "axis": null },
    "tag": { "value": null, "scope": "local", "axis": null },
    "field": { "value": null, "scope": "local", "axis": null },
    "start": { "value": null, "scope": "local", "axis": null },
    "end": { "value": null, "scope": "local", "axis": null },
    "page": { "value": null, "scope": "local", "axis": null },
    "order": { "value": null, "scope": "local", "axis": null }
  },
  "config": { "entry_archive_list_order": "desc", "entry_archive_list_chunk": "month", "entry_archive_list_limit": "10" },
  "fields": {},
  "blog_id": 1,
  "links": { "self": "https://example.com/rest-api/acms/v1/modules/1/", "blog": "https://example.com/rest-api/acms/v1/blogs/1/" }
}

キー

説明

identifier

モジュール ID の識別子(テンプレートの id="...")

name

作成で必須。モジュールの名前(Entry_Summary など)

label

作成で必須。管理画面に出す名前

description

説明

status

open・close

scope

local(そのブログだけ)か global(子孫のブログでも使える)

cache

キャッシュの秒数(0 は無効)

api_use / layout_use / custom_field

モジュールの API 機能で使うか / レイアウトモードで使うか / モジュールのカスタムフィールドを使うか

arguments

引数。bid・uid・cid・eid・keyword・tag・field・start・end・page・order ごとに value(値。%{BID} などの変数も可。start・end は Y-m-d H:i:s)・scope(local・global)・axis(bid・cid だけ。self・descendant-or-self・descendant)

config

モジュールの設定。値が 1 つなら文字列、複数なら文字列の配列。書き込みはキー単位で置き換え、null は空にします

fields

モジュールのカスタムフィールド

id・blog_id・links

読み取り専用

  • config のキーはモジュールごとの設定キー(管理画面のモジュール ID の編集画面のフォームの名前)です。既存のモジュール ID を GET すると、使っているキーを確かめられます。

  • ?rule_id={ルール ID} を付けると、GET と更新の config がそのルール別の設定になります。

  • 複製は管理者だけが使え、識別子とラベルに複製の接尾辞(module_identifier_duplicate_suffix・module_label_duplicate_suffix)と新しい ID が付きます。設定・カスタムフィールドも複製されます。

  • 削除は、設定・カスタムフィールドと一緒に削除します。

ルール

操作

メソッドとパス

スコープ

一覧・取得

GET /rules・GET /rules/{id}

rules:read

作成・更新・削除

POST /rules・PATCH / PUT /rules/{id}・DELETE /rules/{id}

rules:write

curl -s -X POST "${ACMS_API}/rules/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{"name":"スマートフォン","description":null,"status":"open","scope":"local","conditions":{"ua":"iPhone|Android","ua_case":"regex"}}'

conditions は、ルールの条件です。キーは、管理画面のルールの条件の列の名前から rule_ を外したもので、設定しない条件は null です。

キー

条件

bid・bid_case

ブログ ID

aid・aid_case

エイリアス ID

uid・uid_case

ユーザー ID

cid・cid_case

カテゴリー ID

eid・eid_case

エントリー ID

ucd・ucd_case / ccd・ccd_case / ecd・ecd_case

ユーザーコード / カテゴリーコード / エントリーコード

ua・ua_case

ユーザーエージェント

cookie_key・cookie_val・cookie_case

Cookie

term_type・term_start・term_end・term_case

期間(日時はタイムゾーン付きの ISO 8601)

session_uid・session_uid_case

ログイン中のユーザー

authority・authority_case

権限

custom・custom_case

カスタム

*_case は比較の方法で、管理画面のルールの編集画面の選択肢と同じ値です。管理画面で作ったルールを GET /rules/{id} で取得すると、値の形を確かめられます。ルールの一覧は、URL のブログのルールと祖先のブログのグローバルなルールを返します(?blog_axis は受け付けません)。

コンフィグセット

操作

メソッドとパス

スコープ

一覧・取得

GET /config-sets(?type=config・theme・editor)・GET /config-sets/{id}

config-sets:read

作成・更新・削除

POST /config-sets・PATCH / PUT /config-sets/{id}・DELETE /config-sets/{id}

config-sets:write

curl -s -X POST "${ACMS_API}/config-sets/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{"type":"config","name":"キャンペーン用","description":null,"scope":"local"}'
{
  "id": 1,
  "type": "config",
  "name": "基本設定",
  "description": null,
  "scope": "global",
  "sort": 2,
  "blog_id": 1,
  "links": { "self": "https://example.com/rest-api/acms/v1/config-sets/1/", "blog": "https://example.com/rest-api/acms/v1/blogs/1/" }
}

type は config(コンフィグセット)・theme(テーマセット)・editor(編集画面セット)です。削除できるのは、どのブログ・カテゴリーにも使われていないものだけです。

設定キー(コンフィグ)を読み書きする

設定キーは、ブログ・ルール・コンフィグセットの 3 つの層で読み書きします。REST API で扱えるように宣言された設定キー(コンフィグスキーマ)だけが対象です。

層

読み取り(configs:read)

書き込み(configs:write)

ブログ(このブログのコンフィグ)

GET /configs

PATCH /configs

ルール

GET /rules/{rid}/configs

PATCH /rules/{rid}/configs

コンフィグセット

GET /config-sets/{setid}/configs

PATCH /config-sets/{setid}/configs

ブログがコンフィグセットを使っている場合、効いている設定はコンフィグセットの層です。設定を変えるときは、GET /blogs/{id} の config_set_id で使っているコンフィグセットを確かめ、その層を更新します。

# コンフィグセット 1 の設定キーを読む(100 件ずつ。links.next でたどる)
curl -s "${ACMS_API}/config-sets/1/configs/?limit=100" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
{
  "items": [
    { "key": "google_api_key", "value": "***", "is_set": true, "effective": "***", "source": "set", "type": "string" },
    { "key": "entry_code_prefix", "value": null, "is_set": false, "effective": "entry-", "source": "default", "type": "string" },
    { "key": "initial_entry_status", "value": null, "is_set": false, "effective": "draft", "source": "default", "type": "enum" },
    { "key": "manage_revisions", "value": true, "is_set": true, "effective": true, "source": "set", "type": "bool" },
    { "key": "column_text_tag", "value": null, "is_set": false, "effective": ["p", "h2", "h3", "h4", "h5", "ul", "ol", "dl", "blockquote"], "source": "default", "type": "list" }
  ],
  "meta": { "total": 276, "page": 1, "limit": 100, "last_page": 3 },
  "links": { "...": "..." }
}

キー

説明

key

設定キー

value

この層に保存された値(無ければ null)

is_set

この層に値が保存されているか

effective

この層で効いている値(既定値とほかの層を重ねた結果)

source

effective の値を与えた層(default・blog・set・rule)

type

string(文字列)・bool(真偽値)・int(整数)・enum(選択肢の文字列)・list(文字列の配列)

扱える設定キーの一覧は、サイトとプラグインによって変わるため、GET /configs の応答を正としてください(Ver. 3.3.0-alpha.1 のコアでは 276 個)。秘密の値は "***" で返します。

書き込みは、本文に「設定キー: 値」を並べて PATCH で送ります。送ったキーだけを変え、更新したキーの設定を返します。null を送るとこの層の値を消し、ほかの層・既定値が効くようになります。

curl -s -X PATCH "${ACMS_API}/config-sets/1/configs/?dry_run=1" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{"entry_code_prefix":"news-","manage_revisions":true}'
{
  "items": [
    { "key": "entry_code_prefix", "value": "news-", "is_set": true, "effective": "news-", "source": "set", "type": "string" },
    { "key": "manage_revisions", "value": true, "is_set": true, "effective": true, "source": "set", "type": "bool" }
  ],
  "meta": { "total": 2, "page": 1, "limit": 2, "last_page": 1 },
  "links": { "...": "..." }
}
  • 宣言されていないキーは 422 unknown_config_key です(例: rest_api_enable など API に関わる設定は REST API から変えられません)。

  • 位置で組になるリスト(ユニットのメニューの column_text_tag と column_text_tag_label など)は、組のすべてのキーを同じ長さの配列で送るか、すべてを null にします。一部だけは 422 group_incomplete、長さの違いは 422 group_length です。

  • 設定の保存は、管理画面で設定を保存できる権限が要ります。

よくある質問・つまずき

PATCH /configs で変えたのに、サイトの動きが変わりません

ブログがコンフィグセットを使っていると、ブログの層(/configs)の値は効きません。GET /configs の source と effective を見て、効いている層を確かめ、/config-sets/{setid}/configs を更新してください。

モジュール ID の作成で 422 required になります

name(モジュールの名前)と label は必須です。name は Entry_Summary のようなモジュールの名前です。存在しない名前でも保存できてしまう(Ver. 3.3.0-alpha.1 で確かめた動き)ため、綴りに注意してください。

編集者のトークンでモジュール ID を作れません

モジュール ID・ルール・コンフィグの操作は、管理画面と同じく管理者の権限(ロールでは該当する権限)が要ります。足りないと 403 forbidden です。