microCMS

チュートリアル
操作マニュアル
コンテンツAPI
マネジメントAPI（ベータ）
画像API

APIプレビューを活用したクエリパラメータの利用例

最終更新日:2023年12月21日

このページではコンテンツ（主にリスト形式）のAPIプレビュー機能を活用し、さまざまなシーンにおける各クエリパラメータの使い方の実例をご紹介します。

informationInformation

各クエリパラメータの詳細な使い方については、GET /api/v1/{endpoint} のページをご参照ください。

前提

前提として、APIと各コンテンツが以下のように存在していると仮定します。

  • ブログ
  • カテゴリ（ブログに「コンテンツ参照」で紐づけられている）
  • タグ（ブログに「複数コンテンツ参照」で紐づけられている）


▼ブログのAPIスキーマ



▼ ブログのコンテンツ一覧



▼ カテゴリのコンテンツ一覧



▼ タグのコンテンツ一覧

利用例

【例1】コンテンツ数を指定して取得する

コンテンツ数を指定して取得する場合、limit パラメータを利用します。
参考: GET /api/v1/{endpoint} - limit

以下は、ブログ一覧において、1件のコンテンツを取得する場合の指定です。


informationInformation

limitパラメータのデフォルト値は10件です。

【例2】取得開始位置をずらして取得する

ページングの実装などのために取得開始位置をずらして取得する場合、offset パラメータを利用します。
参考: GET /api/v1/{endpoint} - offset

以下は、ブログ一覧において、2件目のコンテンツから取得する場合の指定です。


【例3】公開日が新しい順に取得する

コンテンツの順序を指定して取得する場合、並び替えのためのorders パラメータを利用します。
参考: GET /api/v1/{endpoint} - orders

以下は、ブログ一覧において、公開日（publishedAt）が新しい順（降順）に取得する場合の指定です。

【例4】ブログの「タイトル」および「内容」を対象に全文検索したい

テキストフィールド／テキストエリア／リッチエディタを横断して全文検索をしたい場合、q パラメータを利用します。
参考: GET /api/v1/{endpoint} - q

以下は、ブログ一覧において、「タイトル（テキストフィールド）」および「内容（リッチエディタ）」フィールドに対して「フレームワーク」という文字列で横断的に全文検索する場合の指定です。

informationInformation

qパラメータによる検索は、コンテンツ内容を形態素解析した結果を対象に実施されます。検索語句と一致するキーワードの登録がないコンテンツでも、検索結果に含まれることがあります。正確な部分一致検索が必要な場合は、filtersパラメータの使用をご検討ください。

【例5】特定のカテゴリ（コンテンツ参照）を持つコンテンツのみを絞り込んで取得したい

コンテンツ参照フィールドを利用しているとき、参照先の特定のコンテンツのみを持つコンテンツを絞り込んで取得したい場合、filters パラメータを利用します。
参考: GET /api/v1/{endpoint} - filters

以下は、ブログ一覧において、「更新情報（コンテンツID: pk_fl45f4f）」を持つコンテンツのみを取得する場合の指定です。

【例6】特定のタグ（複数コンテンツ参照）を持つコンテンツのみを絞り込んで取得したい

複数コンテンツ参照フィールドを利用しているとき、参照先の特定のコンテンツのみを絞り込んで取得したい場合、filters パラメータを利用します。
参考: GET /api/v1/{endpoint} - filters

以下は、ブログ一覧において、「タグA（コンテンツID: zulopdaa50d）」を持つコンテンツのみを取得する場合の指定です。

【例7】必要な項目（id, titleなど）にのみ絞って取得したい

コンテンツのidやtitleなど、必要な項目にのみ絞り込んで取得したい場合、fields パラメータを利用します。
参考: GET /api/v1/{endpoint} - fields

以下は、ブログ一覧においてidとtitleのみを取得する場合の指定です。

informationInformation

fieldsパラメータは、取得するデータ量を絞り込むことで、データ転送量を節約するのに役立ちます。

【例8】指定したコンテンツIDを持つコンテンツを一気に取得したい

指定したコンテンツIDを持つ複数のコンテンツを一気に取得したい場合、ids パラメータを利用します。
参考: GET /api/v1/{endpoint} - ids

以下は、ブログ一覧において、次のコンテンツID（nvlzo5qffq と 8of0r4h9ppc）を持つコンテンツを取得する場合の指定です。

高度な利用例

複数のパラメータを組み合わせたケースなど、高度な利用例をご紹介します。

【例1】特定のカテゴリ（コンテンツ参照）を持つコンテンツのみを絞り込み、日時順で並び替えたうえで取得したい

コンテンツ参照フィールドで紐づけている特定のコンテンツのみを絞り込み、さらに日時順で並び替えたうえで取得したい場合、filtersパラメータとordersパラメータを利用します。

以下は、ブログ一覧において、「更新情報（コンテンツID: pk_fl45f4f）」を持つコンテンツのみを取得し、公開日時（publishedAt）の新しい順に並び替える場合の指定です。

【例2】ブログの「タイトル」および「内容」を対象に全文検索し、必要な項目（id, title）にのみ絞り取得したい

テキストフィールド／テキストエリア／リッチエディタを横断して全文検索をし、その結果について必要な項目にのみ絞って取得したい場合、qパラメータとfieldsパラメータを利用します。

以下は、ブログ一覧において、「タイトル」および「内容」フィールドに対して「フレームワーク」という文字列で横断的に全文検索し、それらのコンテンツのidとtitleのみを取得する場合の指定です。

目次