モジュール ID・ルール・コンフィグを扱う
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
サイトの設定に関わるリソースを扱います。どれも管理画面の同じ画面と同じ権限が要ります(多くは管理者)。設定キーの書き込み(configs:write)は「強い権限」のスコープです。
モジュール ID
操作 | メソッドとパス | スコープ |
|---|---|---|
一覧・取得 |
|
|
作成 |
|
|
更新 |
|
|
複製 |
|
|
削除 |
|
|
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/" }
}キー | 説明 |
|---|---|
| モジュール ID の識別子(テンプレートの |
| 作成で必須。モジュールの名前( |
| 作成で必須。管理画面に出す名前 |
| 説明 |
|
|
|
|
| キャッシュの秒数(0 は無効) |
| モジュールの API 機能で使うか / レイアウトモードで使うか / モジュールのカスタムフィールドを使うか |
| 引数。 |
| モジュールの設定。値が 1 つなら文字列、複数なら文字列の配列。書き込みはキー単位で置き換え、 |
| モジュールのカスタムフィールド |
| 読み取り専用 |
configのキーはモジュールごとの設定キー(管理画面のモジュール ID の編集画面のフォームの名前)です。既存のモジュール ID をGETすると、使っているキーを確かめられます。?rule_id={ルール ID}を付けると、GETと更新のconfigがそのルール別の設定になります。複製は管理者だけが使え、識別子とラベルに複製の接尾辞(
module_identifier_duplicate_suffix・module_label_duplicate_suffix)と新しい ID が付きます。設定・カスタムフィールドも複製されます。削除は、設定・カスタムフィールドと一緒に削除します。
ルール
操作 | メソッドとパス | スコープ |
|---|---|---|
一覧・取得 |
|
|
作成・更新・削除 |
|
|
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 です。
キー | 条件 |
|---|---|
| ブログ ID |
| エイリアス ID |
| ユーザー ID |
| カテゴリー ID |
| エントリー ID |
| ユーザーコード / カテゴリーコード / エントリーコード |
| ユーザーエージェント |
| Cookie |
| 期間(日時はタイムゾーン付きの ISO 8601) |
| ログイン中のユーザー |
| 権限 |
| カスタム |
*_case は比較の方法で、管理画面のルールの編集画面の選択肢と同じ値です。管理画面で作ったルールを GET /rules/{id} で取得すると、値の形を確かめられます。ルールの一覧は、URL のブログのルールと祖先のブログのグローバルなルールを返します(?blog_axis は受け付けません)。
コンフィグセット
操作 | メソッドとパス | スコープ |
|---|---|---|
一覧・取得 |
|
|
作成・更新・削除 |
|
|
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 で扱えるように宣言された設定キー(コンフィグスキーマ)だけが対象です。
層 | 読み取り( | 書き込み( |
|---|---|---|
ブログ(このブログのコンフィグ) |
|
|
ルール |
|
|
コンフィグセット |
|
|
ブログがコンフィグセットを使っている場合、効いている設定はコンフィグセットの層です。設定を変えるときは、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": { "...": "..." }
}キー | 説明 |
|---|---|
| 設定キー |
| この層に保存された値(無ければ |
| この層に値が保存されているか |
| この層で効いている値(既定値とほかの層を重ねた結果) |
|
|
|
|
扱える設定キーの一覧は、サイトとプラグインによって変わるため、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にします。一部だけは 422group_incomplete、長さの違いは 422group_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 です。