WordPress ACFの​カスタムフィールドが​REST APIに​出ない​理由

ACFと​カスタムフィールドとは

ACF（Advanced Custom Fields）は、​WordPressに​「カスタムフィールド」​（＝標準には​ない​独自の​入力欄）を​追加する​ための​定番プラグイン​（＝機能を​追加する​拡張ソフト）である。

標準の​WordPress投稿には​「タイトル」​「本文」​「カテゴリー」などが​あるが、​ACFを​使うと​「価格」​「評価​（星の​数）」​「関連リンク」​「担当者」のような​業務固有の​フィールドを​自由に​追加できる。

フィールドとは、​投稿や​ページに​紐づく​独自データの​入れ物である。​ACFの​管理画面で​フィールドを​定義し、​投稿編集画面で​値を​入力する。

WordPressの​REST APIとは

REST APIは、​投稿データを​HTTP経由で​JSONと​して​やり取りする​ための、​WordPress標準搭載の​インターフェースである。

REST（Representational State Transfer）は​Web上で​データを​やり取りする​際に​標準的に​使われる​規約である。JSON（JavaScript Object Notation）は{ "key": "value" }の​形で​データを​表現する​テキスト形式である。

エンドポイント​（＝アクセスする​URLの​窓口）は/wp-json/wp/v2/postsのような​形を​取り、​アクセスすると​投稿一覧が​JSONで​返る。

問題：​ACFフィールドが​REST APIに​出ない

ACFで​作成した​カスタムフィールドは、​デフォルトでは​REST APIの​レスポンスに​含まれない。

/wp-json/wp/v2/postsに​アクセスすると、​標準のtitle・content・excerptなどは​返るが、​ACFで​追加した​カスタムフィールドの​データは​JSONに​現れない。​これは​ACFと​REST APIの​組み合わせで​よく​あるつまずきどころである。

理由は、​ACFの​フィールドが​WordPressのpost_meta（＝投稿メタデータ）と​して​保存される​一方、​REST APIは​明示的に​登録された​項目だけを​出力する​設計に​なっている​ためである。

3つの​解決策

1. ACFの​設定で​「REST APIに​表示」を​オンに​する​（推奨）

ACF 5.11以降、​フィールドグループ​（＝複数の​フィールドを​束ねる​単位）の​設定に​「Show in REST API​（REST APIに​表示）」と​いう​オプションが​追加された。​ACFの​管理画面で​フィールドグループを​編集し、​この​トグルを​オンに​するだけで​よい。

レスポンスにacfと​いう​キーが​追加され、​その下に​フィールドの​値が​ネストされる。​これが​最も​シンプルで​ACF標準の​方法である。

2. PHPで​register_rest_field()を​使って​明示的に​登録する

テーマのfunctions.phpや​プラグインに​次のような​コードを​追加すると、​任意の​フィールドを​REST APIに​出力できる。

add_action('rest_api_init', function () {
  register_rest_field('post', 'my_price', [
      'get_callback' => function ($post) {
          return get_field('my_price', $post['id']);
      },
      'schema' => ['type' => 'number'],
  ]);
});

register_rest_field()は、​任意の​フィールドを​REST APIの​レスポンスに​追加する​ために​WordPressが​提供する​関数である。​細かい​制御が​必要な​場合に​使う。

3.​「ACF to REST API」​プラグインを​使う

サードパーティ製プラグイン​「ACF to REST API」を​導入すると、​ACFフィールドが​自動的に​REST APIへ​出力される。​旧バージョンの​ACF​（5.11より​前）を​使っている​場合や、​手早く​試したい​場合の​選択肢に​なる。​ただし、​依存する​プラグインが​1つ増える​点には​注意が​必要である。

ヘッドレスWordPressとの​関係

ヘッドレス構成​（Headless WordPress）とは、​WordPressを​データ管理​（＝CMS）​専用にし、​表示は​Next.jsなど別の​フロントエンドに​任せる​構成である。​「頭​（表示部​分）を​切り離す」​ことから​ヘッドレスと​呼ばれる。

この​構成では、​WordPressの​データを​フロントエンドに​渡す手段と​して​REST API、​またはWPGraphQL（＝クエリ言語GraphQLで​WordPressの​データを​取得できる​プラグイン）を​使う。​だから​こそ、​ACFの​カスタムフィールドを​多用する​ほど​「REST APIに​出ない」​問題に​必ず​直面し、​上記3つの​解決策の​いずれかが​必要に​なる。

まとめ

ACFの​カスタムフィールドは​仕様上、​デフォルトでは​REST APIに​出ない。​ACF 5.11以降なら、​フィールドグループ設定の​「REST APIに​表示」​（デフォルトは​オフ）を​オンに​するだけでacfキーと​して​出力される。​ヘッドレス構成で​ACFを​使う​場合は、​フィールドグループ作成時に​必ず​この​設定を​確認する。