データの受け渡し ​

JSON を手で書かなくてよく、jq も要りません。 JSON の組み立ても値の取り出しも、 mtb のフラグで行えます。

組み立てる — --set ​

mtb sites templates create --site-id 1 \
  --set template.name=メインページ \
  --set template.type=index \
  --set template.outputFile=index.html \
  --set template.text=@index.html

• 書き方は --set <フラグ>.<項目>=<値>。値は文字列です
• @ファイル名 でファイルから読み込みます（- で標準入力）
• 数値・真偽値・入れ子は --set-json（--set-json template.contentType='{"id":5}'）
• --template @base.json と併用すると、ファイルの内容をもとに一部の項目だけを差し替えられます

指定できる項目名は --help に表示されます。

--template string  (object: buildType, contentType, customFields, linkToFile,
                    name, outputFile, templateType, text, type)

JSON をそのまま渡すこともできます。mtb は送信の前に JSON の構文を検査します。

mtb sites entries create --site-id 1 --entry '{"title":"タイトル","status":"Publish"}'
mtb sites entries create --site-id 1 --entry @entry.json
cat entry.json | mtb sites entries create --site-id 1 --entry -

取り出す — --extract ​

応答から1つの項目を生の値で取り出します（jq -r と同じ）。

mtb sites templates get 1 42 --extract text --out index.html
mtb sites entries list 4 --extract items.0.title

• 文字列はそのまま、それ以外は JSON で出力されます
• items.0.name のように配列の添字も指定できます
• --out と組み合わせると、値をバイト列のままファイルに書き出します （端末に出すときだけ末尾に改行が付きます）
• 項目名を間違えると、その応答に含まれる項目名の一覧を表示します

絞る — --fields ​

MT はリソースの全属性を返します。 一覧では必ず使ってください。

mtb sites list --fields id,name,url
mtb sites entries list 4 --fields id,title,status --limit 50

--fields はどのコマンドでも使えます。 MT は GET にしか fields を用意して いませんが（226 中 67）、対応していないエンドポイントでは mtb が手元で絞ります。 そのため、作成の応答からも ID だけを取り出せます。

mtb sites entries create --site-id 1 --entry @entry.json --fields id --compact
# => {"id":42}

指定した項目名が1つも一致しなければ、綴り違いとして知らせます。

全部取る — --all ​

MT の一覧は既定10件です。 --limit を指定しないと「見つからない」ことが あります。全件を取得するときは --all を付けます。

mtb sites entries list 4 --all --fields id,title   # 261件を3リクエストで
mtb sites entries list 4 --all --limit 50          # --limit は1ページの件数になる

totalResults には実際に取得した件数が入ります。--all を使えるのは、 limit と offset を両方持つコマンドだけです。

出力の形 ​

既定は整形した JSON です。日本語はそのまま読める形で出力されます。 MT は \uXXXX にエスケープして返しますが、mtb が元の文字に戻します。

mtb sites entries list 4 --compact       # 1行 JSON
mtb sites entries list 4 --format raw    # 無加工（バイト列が要るとき）
mtb sites backup 1 --out backup.tar.gz   # ファイルに書き出す

--out を付けたときだけ、本文を標準出力に出しません（案内のメッセージは標準エラー出力に出ます）。

本文の書式 — ここが一番危ない ​

mtb sites entries get 4 42 --extract body                     # 変換後（表示用）
mtb sites entries get 4 42 --no-text-filter 1 --extract body  # 原稿（編集用）

本文を含めない部分更新（タイトルだけ、ステータスだけ）は安全です。 原稿はそのまま残ります。

format に入れる値は mtb text-filters list で確かめられます。

ブロックエディタ ​

API から書き込めます。 原稿は <!-- mt-beb ... --> でブロックを区切った HTML です。

<!-- mt-beb t="core-text" --><p>段落</p><!-- /mt-beb -->
<!-- mt-beb t="core-html" --><figure><img src="..."></figure><!-- /mt-beb -->

区切りが無い素の HTML を block_editor で送っても受け付けられますが、 core-html の単一ブロックとして扱われます。公開される HTML は同じですが、 管理画面で開くと1つの生HTMLブロックとして表示されます。ブロックの構造を持たせるなら、 区切りを自分で書いてください。

カスタムブロックも同じ形で書けます（t="mtbnotice" のように識別子を入れるだけ）。 ただし、カスタムブロックの定義そのものは Data API で扱えません。 定義を別の環境へ移す手段はテーマだけです。

カスタムフィールド ​

# ① カテゴリに画像フィールドを作る
mtb sites fields create 4 --set field.name=見出し画像 --set field.basename=hero \
  --set field.systemObject=category --set field.type=image --extract id

# ② 画像を上げて URL を得る
URL=$(mtb assets upload --site-id 4 --file ./hero.png --path /catimg --extract url)

# ③ カテゴリに設定する
mtb sites categories update 4 18 \
  --set-json category.customFields="[{\"basename\":\"hero\",\"value\":\"$URL\"}]"

• アセット系の値は URL です。ID ではありません。 検証されないので、 間違えても 200 が返ります
• customFields は、指定したものだけでなく全フィールドが配列で返ります （未設定は value: null）。--extract customFields.0.value では 別のフィールドの値を取り出すことになるので、basename で探してください
• 部分更新でも customFields は配列ごと送ります（送った要素だけが更新されます）

次は ​

• 公開と再構築 — 保存した内容をサイトに反映する
• リファレンス：共通フラグ