過去記事「WP REST APIでWordPressの投稿データをJSON形式で取得してみる」では、API経由でWordPressの投稿記事のデータを取得する方法をまとめてみましたが、今回はその続きで、クエリパラメータを追加して条件を指定した形で取得してみたいと思います。WordPressのテーマ内での投稿記事を取得する場合に使うクエリと同じように使えますので、イメージしやすいのではないでしょうか。   おさらいではありますが、例としてWP REST APIでは下記のURLへGETリクエストを送信すると、対応する投稿記事がJSONデータとしてレスポンスで帰ってくる形となります。POST_TYPEは通常投稿の記事を取得したい場合には「posts」を、固定ページなら「pages」、カスタム投稿であればそれに対応するスラッグを指定とそれぞれアクセスできるものは決まっています。

https://exapmle.com/wp-json/wp/v2/POST_TYPE

  ちなみに、「https://exapmle.com/wp-json/wp/v2/」にアクセスすると、下記のようにデータを取得（GETメソッド）やデータの投稿（POSTメソッド）に対応したルーティングの一覧が確認できます。   このルーティングで設定されているルーティングに示されているURLにリクエストを送信することで、データがレスポンスとして返ってくるのですが、その際にクエリパラメーターを追加することで、データを取得する条件を指定できるようになります。過去記事でも紹介しましたが、下記は投稿記事のアイキャッチ画像の情報も含める指定のパラメーター設定になります。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?_embed

  このように、エンドポイントの末尾に「?」を記述し、その直後に続けてパラメーターとその値を「=」で結んで記述することでデータ取得の条件を設定できます。また、複数のパラメーターをつなげる場合には「&」を使って続けて記述します。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?PARAMETER_1=VALUE_1&PARAMETER_2=VALUE_2

   

取得件数指定

一回で取得する記事の件数を指定してデータを取得します、デフォルト値は10になります。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?per_page=[NUMBER]

  ただし、下記のようにWP_queryのパラメーターと同じように全件取得をしてみると下記のようなエラーが発生します。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?per_page=-1

code: "rest_invalid_param"
data: {status: 400, params: {per_page: "per_page は1以上、100以下でなければなりません。"}}
message: "無効なパラメーター: per_page"

  どうやらデフォルトでは最大100件までしか取得できないようなので、一度に全件取得させる場合にはカスタマイズが必要のようです。  

ページ指定

n番目のページを指定してデータを取得します。デフォルト値は1になり、新しい記事から取得できるようになります。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?page=[NUMBER]

   

検索キーワード指定

検索キーワードを指定してデータを取得します。キーワードを含む投稿記事を取得することができます。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?search=[KEYWORD]

   

降順・昇順の指定

降順か昇順で指定してデータを取得します。指定できる値は「asc」もしくは「desc」です。デフォルトでは降順（desc）になり、新しい記事から取得できるようになります。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?order=[VALUE]

   

並び順の指定

記事の並び順を指定してデータを取得します。指定できる値は「date」「author」「modified」「title」などいろんな条件で並び替えできます。デフォルトでは投稿日順（date）となり、新しい記事から取得できるようになります。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?orderby=[VALUE]

   

投稿日の期間指定

記事の投稿日時を期間指定してデータを取得します。降順の場合、beforeのパラメーターには指定期間の終わりを、afterには指定期間の始まりを指定します。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?before=[DATE]&after=[DATE]

  値はISO8601に準拠させる必要があるので「yyyy-mm-ddThour:minutes:second」というように下記のような表記で指定します。もちろんbeforeとafterのパラメーターは単独でも使用できます。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?before=2020-09-11T23:45:33&after=2020-07-28T17:17:40

   

取得開始位置の指定

n番目の記事から指定してデータを取得します。指定した数以降の記事から取得する形になります。取得件数指定のパラメーターである「per_page」と組み合わせることでページネーションを作成できます。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?offset=[NUMBER]

   

投稿IDで絞り込みと除外指定

取得条件の中にIDを使う場合に、含めるものや除外するものを個別に指定できます。「include」のパラメーターでは含める対象に、「exclude」のパラメーターでは除外する対象をIDで指定します。複数ある場合にはカンマで区切ります。

// IDを指定して絞り込み
https://exapmle.com/wp-json/wp/v2/POST_TYPE?include=[NUMBER],[NUMBER],[NUMBER]......

// IDを指定して除外
https://exapmle.com/wp-json/wp/v2/POST_TYPE?exclude=[NUMBER],[NUMBER],[NUMBER]......

   

特定のタクソノミーのタームで指定

タクソノミーのターム別にデータを取得できます。ターム名ごとのアーカイブを出力するときに使えます。パラメーターにはタクソノミー名を指定し、その値に対象となるタームのIDを入れる形になります。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?TAXONOMY_NAME=[TERM_ID]

   

投稿者の指定

投稿者別でデータを取得できます。パラメーターの値には投稿者の識別用スラッグが入る形になります。

https://exapmle.com/wp-json/wp/v2/POST_TYPE?author=[AUTHOR_NAME]

   

---

  このようにクエリパラメーターを指定することで、より細かな条件で投稿記事を取得することがAPI経由でも可能となります。使い方に関してはWordPressのテーマ内で扱うサブクエリの引数に近いと思いますのでわかりやすいですね。また、WordPress側で独自のエンドポイントを作成することも可能のようですので、デフォルトで用意されているもの以外でも対応できるとのことなので、また別記事でまとめていきたいと思います。   （参考にさせて頂いたサイト） REST API Handbook - Reference -