エントリーの本文とカスタムフィールドを送る
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
エントリーの本文は、次のどちらかで送ります。同時には送れません(送ると 422、「units と body_html は同時に指定できません。」)。
方法 | 使いどころ | 保存される形 |
|---|---|---|
| ブロックエディターを使うサイト。外部の記事・HTML をそのまま入稿したいとき | 1 つのブロックエディターユニット |
| ユニット(テキスト・メディア・マークダウンなど)を使うサイト。ユニットの並びを細かく決めたいとき | 送ったとおりのユニットの並び |
どちらも送らなかった場合、作成では本文が空になり、更新では今の本文がそのまま残ります。
ブロックエディターの HTML で送る(body_html)
body_html には、ブロックエディターで扱える HTML を送ります。ブロックエディターのスキーマに無い内容は、次の「入稿用タグ」で囲むと、保存時にブロックエディターの機能タグに変換されます。
入稿用タグ | 変換されるもの |
|---|---|
| HTML ブロック。中の HTML はそのまま保持されます |
| 埋め込みブロック。保存時に URL を一度だけ取得して、埋め込み(oEmbed)かリンクカードにします。取得できなければ通常のリンクの段落に変換し、 |
{
"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 は、本文のユニットを上から順に並べた配列です。配列ごと置き換えます(送らなかったユニットは消えます)。
キー | 説明 |
|---|---|
| 必須。ユニットの型(下の表) |
| 既存のユニットを残すときだけ、そのエントリーのユニットの ID を指定します。新しいユニットは省略します(自動で採番)。ほかのエントリーのユニットの ID や、存在しない ID は 422 |
|
|
|
|
| ユニットグループのクラス(ユニットグループを使う場合) |
| アンカー |
| 型ごとの値。値はすべて文字列で送ります |
| グループユニット( |
sort は読み取り専用です(並び順は配列の順で決まります)。attributes の名前は、管理画面のユニットのフォームの項目名から _{ユニット ID} を除いたものです。読み取りの attributes とは名前が違う型があります。
型( | 書き込みの | 読み取りの |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| — |
|
| — |
|
|
|
|
| — |
|
|
|
|
| — |
|
|
|
|
| — |
|
|
|
|
| — |
|
|
|
| カスタムユニットのカスタムフィールドの名前(値は文字列か文字列の配列) | — |
「—」の型は、読み取りの名前をこのページの作成時に確かめていません。実際の名前は 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・隠し値・ラジオボタン・日付・時刻・日時・ブロックエディター | 文字列 |
|
数値 | 数値 |
|
セレクトボックス・チェックボックス | 単一選択は文字列、複数選択は文字列の配列(選択肢の値) |
|
メディア画像・メディアファイル | メディア ID(整数) |
|
メディアギャラリー | メディア ID の配列 |
|
エントリー参照・カテゴリー参照・ユーザー参照 | 単一は ID(整数)、複数は ID の配列 |
|
地図 |
|
|
フィールドグループ(繰り返し) | 行のオブジェクトの配列(行の中は、メンバーのキーと値) |
|
画像・ファイル(アップロードの型) | 書き込めません(422、「ファイルのアップロードは API では扱えません。メディアの型を使ってください。」)。読み取りではパスの文字列 | — |
見出し・メッセージ・行・タブ・アコーディオン(レイアウトの型) | 値を持ちません | — |
定義の無いキー | 文字列か文字列の配列 |
|
実際に作成した例です(定義のあるキーは、作成の応答でも同じ形で返ります)。
{
"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 なら時間をおいて送り直します。埋め込みの許可ホストなどは、管理画面のブロックエディターの埋め込みと同じ規則です。