エントリーの本文とカスタムフィールドを送る


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

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

エントリーの本文は、次のどちらかで送ります。同時には送れません(送ると 422、「units と body_html は同時に指定できません。」)。

方法

使いどころ

保存される形

body_html

ブロックエディターを使うサイト。外部の記事・HTML をそのまま入稿したいとき

1 つのブロックエディターユニット

units

ユニット(テキスト・メディア・マークダウンなど)を使うサイト。ユニットの並びを細かく決めたいとき

送ったとおりのユニットの並び

どちらも送らなかった場合、作成では本文が空になり、更新では今の本文がそのまま残ります。

ブロックエディターの HTML で送る(body_html)

body_html には、ブロックエディターで扱える HTML を送ります。ブロックエディターのスキーマに無い内容は、次の「入稿用タグ」で囲むと、保存時にブロックエディターの機能タグに変換されます。

入稿用タグ

変換されるもの

<acms-block-editor-html-block>任意の HTML</acms-block-editor-html-block>

HTML ブロック。中の HTML はそのまま保持されます

<acms-block-editor-embed-block url="https://..."></acms-block-editor-embed-block>

埋め込みブロック。保存時に URL を一度だけ取得して、埋め込み(oEmbed)かリンクカードにします。取得できなければ通常のリンクの段落に変換し、warnings で知らせます

{
  "title": "body_html で本文を送るエントリー",
  "status": "draft",
  "category_id": 22,
  "body_html": "<h2>見出し</h2><p>段落の本文です。<strong>強調</strong>もそのまま保存されます。</p><acms-block-editor-html-block><div class=\"cta\"><a href=\"/contact/\">お問い合わせ</a></div></acms-block-editor-html-block><acms-block-editor-embed-block url=\"https://www.youtube.com/watch?v=xxxxxxxxxxx\"></acms-block-editor-embed-block>"
}
curl -s -X POST "${ACMS_API}/entries/" \
  -H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
  --data-binary @body-html.json

応答の units には、ブロックエディターユニットが 1 つ入ります。HTML ブロックは機能タグ(acms-block-editor-function-tag)に変わっています。埋め込みの URL を取得できなかった場合の応答の例です。

{
  "id": 243,
  "units": [
    {
      "id": "52bd6cc1-ea7d-47f4-ad60-894e92b560f5",
      "type": "block-editor",
      "status": "open",
      "sort": 1,
      "align": null,
      "group": null,
      "anker": null,
      "attributes": {
        "html": "<h2>見出し</h2><p>段落の本文です。<strong>強調</strong>もそのまま保存されます。</p><acms-block-editor-function-tag data-block-type=\"html\" data-block-props=\"eyJodG1sIjoi...\"></acms-block-editor-function-tag><p><a href=\"https://example.invalid/video\">https://example.invalid/video</a></p>"
      },
      "children": []
    }
  ],
  "warnings": [
    { "message": "埋め込み(https://example.invalid/video)を取得できなかったため、通常のリンクに変換しました。", "retryable": true, "kind": "embed" }
  ]
}
  • warnings は保存を止めません。retryable が true の警告は、時間をおいて同じ内容で送り直すと解消することがあります。kind は警告の種類(埋め込みは embed)です。

  • ?dry_run=1 では、埋め込みの URL を外部に取りに行きません。

  • 入稿用タグは同じ名前を入れ子にできません。閉じタグの無い HTML ブロックは変換されず、警告になります。

  • 危険なタグの除去は、これまでどおり出力時のサニタイズの設定に従います。

  • プラグインが入稿用タグを追加している場合は、そのタグも使えます。

ユニットの配列で送る(units)

units は、本文のユニットを上から順に並べた配列です。配列ごと置き換えます(送らなかったユニットは消えます)。

キー

説明

type

必須。ユニットの型(下の表)

id

既存のユニットを残すときだけ、そのエントリーのユニットの ID を指定します。新しいユニットは省略します(自動で採番)。ほかのエントリーのユニットの ID や、存在しない ID は 422

status

open(表示。既定)か close(非表示)

align

center・left・right・auto

group

ユニットグループのクラス(ユニットグループを使う場合)

anker

アンカー

attributes

型ごとの値。値はすべて文字列で送ります

children

グループユニット(group)の子のユニットの配列。ほかの型には送れません

sort は読み取り専用です(並び順は配列の順で決まります)。attributes の名前は、管理画面のユニットのフォームの項目名から _{ユニット ID} を除いたものです。読み取りの attributes とは名前が違う型があります。

型(type)

書き込みの attributes

読み取りの attributes(実際の応答)

text

text_tag(必須。p・h2 などユニット設定のタグ)・text_text・text_extend_tag

text_text・text_tag

block-editor

block-editor_html

html

markdown

markdown_value

value

html

html_html

html

code

code_value

value

table

table_source

table_source

wysiwyg

wysiwyg_html

—

rich-editor

rich-editor_json

—

media

media_id(必須。メディア ID を文字列で)・media_caption・media_alt・media_link・media_enlarged・media_use_icon・media_size

media_id(整数)・media_enlarged・media_size

map

map_msg・map_lat・map_lng・map_zoom・map_view_activate・map_view_pitch・map_view_zoom・map_view_heading・map_size

—

osmap

map_msg・map_lat・map_lng・map_zoom・map_size

msg・lat・lng・zoom(数値)・size

video

video_id・video_size

—

youtube

youtube_id・youtube_size

youtube_id・youtube_size

module

module_mid・module_tpl

—

break

break_label

break_label

quote

quote_url

—

group

group_tag・group_class(子は children)

tag・class

custom

カスタムユニットのカスタムフィールドの名前(値は文字列か文字列の配列)

—

「—」の型は、読み取りの名前をこのページの作成時に確かめていません。実際の名前は GET /entries/{id} で確かめてください。

書き込めないユニット

画像(image)・ファイル(file)・画像URL(eximage)のユニットと、プラグインの独自ユニットは書き込めません(422 unsupported_unit_type)。画像やファイルは、先に メディア として登録し、media ユニットの media_id で参照します。

例: 見出し・段落・画像・グループ

{
  "title": "ユニットで本文を送るエントリー",
  "status": "draft",
  "category_id": 22,
  "primary_image_unit_id": null,
  "units": [
    { "type": "text", "attributes": { "text_tag": "h2", "text_text": "見出しです" } },
    { "type": "text", "attributes": { "text_tag": "p", "text_text": "本文の段落です。" } },
    { "type": "media", "align": "center", "attributes": { "media_id": "36", "media_caption": "キャプション", "media_alt": "代替テキスト" } },
    { "type": "markdown", "attributes": { "markdown_value": "## 小見出し\n\n- リスト 1\n- リスト 2" } },
    { "type": "osmap", "attributes": { "map_lat": "35.681236", "map_lng": "139.767125", "map_zoom": "15", "map_msg": "東京駅" } },
    {
      "type": "group",
      "attributes": { "group_tag": "section", "group_class": "box" },
      "children": [
        { "type": "text", "attributes": { "text_tag": "p", "text_text": "グループの中の段落" } }
      ]
    }
  ]
}

primary_image_unit_id を省略すると、管理画面と同じく最初の画像のユニットがメイン画像になります(作成した例では media のユニットの ID が入りました)。ほかのユニットをメイン画像にしたいときは、units の中のユニットの ID を指定します。新しいユニットの ID は保存するまで分からないため、作成の後に PATCH で指定します。

既存の本文の一部だけを変える

本文は配列ごと置き換えるため、一部だけ変えるときは「取得 → 変更 → 全体を送る」の手順にします。残すユニットには取得した id を付けます(ID を付けると、ユニットの ID が変わらず、メイン画像の指定なども保たれます)。

# 1. 今の本文と ETag を取得する
curl -s -D headers.txt "${ACMS_API}/entries/240/?fields=units" -H "Authorization: Bearer ${ACMS_API_TOKEN}" -o units.json
{
  "units": [
    { "id": "71966e5d-524b-41dc-abdf-45d62c090221", "type": "text", "attributes": { "text_tag": "h2", "text_text": "見出しを直しました" } },
    { "id": "a3949156-6aef-4260-a86a-f7cdb1f6d125", "type": "text", "attributes": { "text_tag": "p", "text_text": "本文の段落です。" } },
    { "id": "08360537-7dca-468d-87cb-96d8998257ff", "type": "media", "align": "center", "attributes": { "media_id": "36" } },
    { "type": "text", "attributes": { "text_tag": "p", "text_text": "末尾に足した段落です。" } }
  ]
}

取得した units を送り返すときは、読み取り専用の sort を除き、attributes を書き込みの名前・文字列の値に直します(上の例)。fields で項目を絞って取得しても ETag は全体と同じ値なので、そのまま If-Match に使えます(include を付けた取得の ETag は違う値になるので使えません)。

カスタムフィールドを送る(fields)

fields は、カスタムフィールドのキーと値のオブジェクトです。GUI で定義したフィールド(カスタムフィールド定義)は、型に合わせた JSON の値で読み書きします。定義の無いキー(テンプレートだけで作った従来のカスタムフィールド)は、文字列か文字列の配列です。

フィールドの型

値の形

例

テキスト・テキストエリア・電話番号・メールアドレス・URL・隠し値・ラジオボタン・日付・時刻・日時・ブロックエディター

文字列

"rp_text": "山田 太郎"、"rp_date": "2026-12-01"

数値

数値

"rp_number": 1200

セレクトボックス・チェックボックス

単一選択は文字列、複数選択は文字列の配列(選択肢の値)

"rp_select": "b"、"rp_checkbox": ["a", "c"]

メディア画像・メディアファイル

メディア ID(整数)

"rp_media_image": 36

メディアギャラリー

メディア ID の配列

"rp_media_gallery": [36, 37]

エントリー参照・カテゴリー参照・ユーザー参照

単一は ID(整数)、複数は ID の配列

"rp_rel_category": 22、"rp_rel_entries": [232]

地図

lat・lng(と任意の zoom)のオブジェクト

"rp_map": { "lat": 35.681236, "lng": 139.767125, "zoom": 15 }

フィールドグループ(繰り返し)

行のオブジェクトの配列(行の中は、メンバーのキーと値)

"rp_group": [{ "rp_group_title": "1 行目", "rp_group_body": "内容" }]

画像・ファイル(アップロードの型)

書き込めません(422、「ファイルのアップロードは API では扱えません。メディアの型を使ってください。」)。読み取りではパスの文字列

—

見出し・メッセージ・行・タブ・アコーディオン(レイアウトの型)

値を持ちません

—

定義の無いキー

文字列か文字列の配列

"memo": "自由な値"

実際に作成した例です(定義のあるキーは、作成の応答でも同じ形で返ります)。

{
  "title": "カスタムフィールドを送るエントリー",
  "status": "draft",
  "category_id": 22,
  "fields": {
    "rp_text": "山田 太郎",
    "rp_select": "b",
    "rp_checkbox": ["a", "c"],
    "rp_number": 1200,
    "rp_date": "2026-12-01",
    "rp_media_image": 36,
    "rp_media_gallery": [36],
    "rp_map": { "lat": 35.681236, "lng": 139.767125, "zoom": 15 },
    "rp_rel_entries": [232],
    "rp_rel_category": 22,
    "rp_group": [
      { "rp_group_title": "1 行目の項目名", "rp_group_body": "1 行目の内容" },
      { "rp_group_title": "2 行目の項目名", "rp_group_body": "2 行目の内容" }
    ],
    "memo": "定義の無いキー"
  }
}
  • PATCH では、送ったキーだけを置き換えます。null を送ると、そのキーを削除します(例: {"fields":{"memo":null}})。フィールドグループは行の配列ごと置き換えます。

  • 作成で送らなかったキーには、定義の既定値が入ります。

  • 値の検証(必須・選択肢・書式・範囲・行数)は、サーバーが定義から行います。違反は 422 で、pointer は #/fields/{キー}(グループの行は #/fields/{キー}/{行の番号}/{メンバー})です。

  • 日付・日時の書式は定義の設定に従います。各キーの型・書式・選択肢は、GET /openapi.json のエントリーの fields のスキーマか、GET /field-definitions で確かめられます。

  • コンポーネントのフィールドは、<フィールドのキー>_<中のキー> の平らなキーで送ります(コンポーネント)。

  • ロールの設定などで変えられない(読み取り専用・非表示の)フィールドを送ると 422 read_only_field です。読み取りは制限されません。

カテゴリー・ブログ・ユーザー・モジュール ID の fields も、同じ形で読み書きします。

よくある質問・つまずき

media ユニットの media_caption・media_alt が応答に出ません

書き込みでは保存されますが、読み取りの attributes には media_id・media_enlarged・media_size だけが出ます。保存されたかは管理画面の編集画面で確かめてください。メディア自体のキャプション・代替テキストは GET /media/{id} の fields で読めます。

attributes に数値を送ると 422 になります

ユニットの attributes の値は文字列で送ります("media_id": "36"、"map_lat": "35.68")。カスタムフィールドの fields とは違うので注意してください。

units を送ったら、本文のほかのユニットが消えました

units は本文の全体を置き換えます。残したいユニットも、id を付けて一緒に送ってください。

テキストユニットの text_tag に何を指定すればよいですか

ユニット設定のテキストのタグの選択肢(設定キー column_text_tag。例: p・h2・h3・ul)の値を指定します。GET /configs で column_text_tag を確かめられます。

body_html の埋め込みがリンクになります

保存時に URL を取得できなかったか、埋め込みに対応していない URL です。warnings を確かめ、retryable が true なら時間をおいて送り直します。埋め込みの許可ホストなどは、管理画面のブロックエディターの埋め込みと同じ規則です。