エントリーの公開・バージョン・承認フロー


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

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

このページの操作は、管理画面の同じ操作と同じ判定(権限・承認フロー・編集ロック)で動きます。公開に関わる操作には entries:publish のスコープが要ります(REST API の認証と API トークン)。

公開する・非公開にする

操作

メソッドとパス

スコープ

成功

公開

POST /entries/{id}/publish

entries:publish

200(エントリー)。承認済みで作業領域へ保存したときは 202(バージョン)

非公開

POST /entries/{id}/unpublish

entries:publish

200(エントリー)

curl -s -X POST "${ACMS_API}/entries/240/publish/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
curl -s -X POST "${ACMS_API}/entries/240/unpublish/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
  • 本文は送りません。

  • 公開は、管理画面の「公開」と同じ判定(編集者以上、または自分のエントリーの投稿者)です。すでに公開中なら何も変えずに 200 を返します。

  • 公開時に必須の項目(エントリー項目設定・カスタムフィールドの定義で「公開時」)が埋まっていなければ、何も変えずに 422 validation_failed を返します。

  • 非公開は、公開中のエントリーだけを非公開(close)にします。非公開・下書きのエントリーは何も変えずに 200 を返します。

  • 承認フローが必要なときは、PATCH で status を open にするのと同じ保存になります。承認済みのエントリーはメインを変えずに作業領域へ保存して 202、承認前(approval が pre_approval)のエントリーはメインの status を open にして 200 を返します(承認されるまで公開側には出ません)。

  • 公開日時(start_datetime)が未来なら、公開しても期間が来るまで公開側に出ません(is_public は false)。

公開時に必須の項目が足りない場合の応答の例です。

{
  "type": "https://developer.a-blogcms.jp/rest-api/problems/validation-failed",
  "title": "入力内容にエラーがあります。",
  "status": 422,
  "detail": "1 件の項目を修正してください。",
  "instance": "/rest-api/acms/v1/entries/245/publish/",
  "code": "validation_failed",
  "errors": [
    { "pointer": "#/fields/summary", "code": "required", "detail": "入力してください。" }
  ]
}

バージョン(リビジョン)を扱う

リビジョン管理が有効なサイトでは、エントリーのバージョンを扱えます。リビジョン ID 1 は作業領域、2 以降が保存したバージョンです。

操作

メソッドとパス

スコープ

成功

一覧

GET /entries/{id}/revisions

entries:read

200

取得

GET /entries/{id}/revisions/{revisionId}

entries:read

200(ETag 付き)

新しいバージョンを作る

POST /entries/{id}/revisions

entries:write

201

上書き

PATCH /entries/{id}/revisions/{revisionId}

entries:write(作業領域でメインも更新し、メインが公開中か公開にするなら entries:publish も)

200

公開バージョンにする

POST /entries/{id}/revisions/{revisionId}/publish

entries:publish

204

作業領域から新しいバージョンを作る(承認依頼の準備)

POST /entries/{id}/revisions/1/duplicate

entries:write

201

削除

DELETE /entries/{id}/revisions/{revisionId}

entries:write

204

公開中のエントリーを新しいバージョンとして直す

entries:write だけのトークンで公開中のエントリーを直すときの手順です。メインのエントリーは変えず、送った内容で新しいバージョンを保存します(送らなかった項目はメインの値)。本文で送れる項目はエントリーと同じで、memo でバージョンのメモを付けられます。

curl -s -i -X POST "${ACMS_API}/entries/240/revisions/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{"title":"新しいバージョンのタイトル","memo":"REST API で作ったバージョン"}'
{
  "id": 2,
  "entry_id": 240,
  "is_workspace": false,
  "is_current": false,
  "is_reserved": false,
  "status": "approved",
  "memo": "REST API で作ったバージョン",
  "user_id": 1,
  "datetime": "2026-11-12T13:57:27+09:00",
  "title": "新しいバージョンのタイトル",
  "entry_status": "draft",
  "start_datetime": "1000-01-01T00:00:00+09:00",
  "end_datetime": "9999-12-31T23:59:59+09:00",
  "approval_points": { "public": 0, "reject": 0 },
  "entry": { "id": 240, "title": "新しいバージョンのタイトル", "...": "(バージョンの内容のエントリーの表現)" },
  "warnings": [],
  "links": {
    "self": "https://example.com/rest-api/acms/v1/entries/240/revisions/2/",
    "entry": "https://example.com/rest-api/acms/v1/entries/240/",
    "user": "https://example.com/rest-api/acms/v1/users/1/"
  }
}

応答は 201 で、Location にバージョンの URL が入ります。人が管理画面のバージョン一覧で内容を確かめて公開するか、entries:publish を持つトークンで公開バージョンにします。

curl -s -i -X POST "${ACMS_API}/entries/240/revisions/2/publish/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
# HTTP/2 204

公開バージョンにすると、そのバージョンの内容がエントリーになります。公開日時が未来なら公開予約になります。作業領域(1)・公開中・公開予約中のバージョンは 403 です。承認機能が有効なら、承認済みで承認管理者のときだけ切り替えられます。

バージョンの表現の項目

キー

説明

id

リビジョン ID(1 は作業領域)

entry_id

エントリー ID

is_workspace / is_current / is_reserved

作業領域か / 公開中のバージョンか / 公開予約中か

status

承認の状態(none・in_review・approved・reject・trash)

memo

バージョンのメモ

user_id

このバージョンを保存したユーザー(エントリーの投稿者は entry.user_id)

datetime / title / entry_status / start_datetime / end_datetime

保存日時 / タイトル / エントリーのステータス / 公開日時 / 掲載期限

approval_points

並列承認のポイント(public・reject)

entry

バージョンの内容(ユニット・フィールド・タグなど)。一覧の要素には含みません

warnings / links / embedded

エントリーと同じ

  • 一覧はリビジョン ID の昇順(?order=id-desc で降順)で、要素は概要だけです。内容は単体で取得します。

  • 投稿者はエントリー全体の値です。メインを更新しない保存で、メインの今の投稿者と違う user_id を送ると 409 です(投稿者は PATCH /entries/{id} に user_id だけを送って変えます)。

  • バージョンの削除はゴミ箱を経ない物理削除です。If-Match(そのバージョンの ETag)が必須で、無いか違えば 412 です。作業領域・公開中・公開予約中のバージョンは削除できません(403)。

承認フローを操作する

承認機能を使うサイトでは、POST /entries/{id}/approvals で承認フローを進めます。スコープは approvals:write(強い権限)で、最終承認(publish)には entries:publish も要ります。

項目

型

説明

action

必須。request・publish・reject・request_reject・comment

承認を依頼する / 最終承認して公開する / 却下して差し戻す / 却下を依頼する(並列承認) / コメントを残す

revision_id

必須。2 以上の整数

対象のバージョン(作業領域の 1 は対象外)

comment

文字列

コメント(既定は空)

usergroup_id

整数 / null

操作するときのユーザーグループ(エンタープライズライセンスの直列承認)

receiver

{ "usergroup_id": 整数, "user_id": 整数 } / null

request の宛先。省略すると、エンタープライズライセンスはワークフローの最終承認グループ、プロフェッショナルライセンスはブログの編集者以上

# 1. 作業領域から新しいバージョンを作る(承認依頼する内容を固める)
curl -s -X POST "${ACMS_API}/entries/240/revisions/1/duplicate/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{"memo":"11 月のキャンペーン告知"}'

# 2. そのバージョン(例: 3)の承認を依頼する
curl -s -X POST "${ACMS_API}/entries/240/approvals/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  -d '{"action":"request","revision_id":3,"comment":"確認をお願いします"}'

# 3. 履歴を確かめる
curl -s "${ACMS_API}/entries/240/approvals/?revision_id=3&include=request_user" -H "Authorization: Bearer ${ACMS_API_TOKEN}"

操作の結果と履歴は、承認フローの履歴の表現(id・type・method(series・parallel・null)・comment・datetime・entry_id・revision_id・request_user_id・request_usergroup_id・receive_user_id・receive_usergroup_id・links)で返ります。

  • 権限・対象のバージョンの状態は管理画面と同じ判定で、満たさなければ 403 です。

  • 依頼・却下で宛先(依頼者)かメールのテンプレートが無いときは、何も保存せず 409 です。

  • 最終承認は、公開するバージョンが公開時に必須の項目を満たさなければ、何も保存せず 422 です。

  • 履歴は、承認管理者はエントリーの全履歴、そのほかの人は自分が関わった(依頼者・宛先)か承認プレビューを開けるバージョンの履歴だけを読めます。

  • 作業領域から新しいバージョンを作る操作は、承認機能が有効で承認フローを経由するユーザーだけが使えます。作業領域以外のバージョンは 409 です。

編集ロック

管理画面と同じ編集ロックを、API から取得・解除できます。長い時間をかけて書き換える処理の前にロックすると、管理画面で同時に編集されるのを防げます。

# ロックする(すでに自分がロックしていれば期限を延ばす)
curl -s -X POST "${ACMS_API}/entries/240/lock/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
{ "locked": true, "user_id": 1, "mine": true, "locked_at": "2026-11-12T13:57:43+09:00", "expires_at": "2026-11-14T13:57:43+09:00" }
# 状態を見る
curl -s "${ACMS_API}/entries/240/lock/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
# 解除する(ロックした本人とブログの管理者だけ。ロックされていなければ何もせず 204)
curl -s -i -X DELETE "${ACMS_API}/entries/240/lock/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"

ほかのユーザーがロック中なら 409 entry_locked、ロック機能が無効なら 409 conflict です。ロックの期限は管理画面の設定に従います。

共有プレビューの URL を発行する

ログインしていない人にも、期限まで下書きを含むエントリーを見せられる URL を発行します。管理画面の「プレビューの共有」と同じ権限(投稿者以上)・期限です。本文は送りません。

curl -s -X POST "${ACMS_API}/entries/240/preview-links/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
{ "url": "https://example.com/rest-api-doc/rest-api-sample.html?...", "expires_at": "2026-11-14T04:57:44+00:00" }

URL は秘密の値で、監査ログには残りません。?dry_run=1 では発行せず、期限だけを返します(url は null)。

よくある質問・つまずき

公開中のエントリーを更新すると 403 insufficient_scope になります

公開中のエントリーの更新には entries:publish が要ります。スコープを足すか、POST /entries/{id}/revisions で新しいバージョンとして保存し、公開は人に任せます。

承認フローのブログで更新すると 202 が返ります

承認フローが必要で承認済みのエントリーは、メインを変えずに作業領域へ保存しています。応答はバージョンの表現です。公開は承認フローで進めます。

POST /entries/{id}/revisions が 403 になります

リビジョン管理が無効なサイトか、そのエントリーを編集できない権限です。コンフィグの manage_revisions と、ユーザーの権限を確かめてください。

バージョンの削除で 412 になります

バージョンの削除は If-Match が必須です。GET /entries/{id}/revisions/{revisionId} の ETag を付けて送ります。