みなさんこんにちは、ウォンタ株式会社代表の松田です。
いつもmicroCMSをご利用いただきありがとうございます。

本日よりAPIで取得するコンテンツを絞り込めるようになりました！
この記事では絞り込みのために使うfiltersパラメータの具体的な使い方について説明していきます。

filtersパラメータ

絞り込みをするためにはfiltersパラメータをリクエスト時のURLに付与します。
簡単なJavaScriptで使い方を確認してみましょう。

<script>
  fetch(
    'https://microcms.microcms.io/api/v1/news?filters=title[contains]不具合',
    { headers: { 'X-MICROCMS-API-KEY': '1c801446-5d12-4076-aba6-da78999af9a8' } }
  )
    .then(result => result.json())
    .then(json => console.log(json));
</script>

※言語や環境によっては明示的なURLエンコードが必要ですのでご注意ください。

filtersという名前で渡されている値が重要です。

?filters=title[contains]不具合

ここで一つみなさんに秘密をお教えします。実は管理画面左下で確認できる更新情報はmicroCMS自身で作られています。そのためAPIでデータが取得できるのです😜
今回の指定ではそんなmicroCMSの更新情報から、タイトルに「不具合」を含むコンテンツのみを取得してコンソールに表示しています。（このデータが増えていかないようにしっかり運用進めます🙇🏻‍♂️）

また、filtersは[and]や[or]（12/24更新：別記事にて解説しています）で複数の条件を指定できます。例えば以下の指定では2019年11月に発生した不具合情報を取得できます。この記事を書いた時点では1件のデータが取得できるはずです！

?filters=title[contains]不具合[and]publishedAt[begins_with]2019-11

[contains] や [begins_with] のようにfiltersにはいくつかの使えるパラメータがあります。それぞれについて使用例を見ていきましょう。

[equals]

値が完全一致しているコンテンツを取得します。例えば女性のみを取得する場合は以下のように指定します。

/api/v1/members?filters=gender[equals]women

[not_equals]

値が一致していないコンテンツを取得します。女性以外のメンバーを取得するには以下のような形ですね。

/api/v1/members?filters=gender[not_equals]women

[less_than]

指定より値が小さいコンテンツを取得します。数字だけでなく文字列でも比較が可能です。例えば作成日が2019年6月までのブログを取得する場合は以下のような形となります。

/api/v1/blogs?filters=createdAt[less_than]2019-07

[greater_than]

less_thanの反対で、指定より値が大きいコンテンツを取得します。2019年7月以降のブログを取得するには以下の記述です。

/api/v1/blogs?filters=createdAt[greater_than]2019-06

[contains]

指定した値を含むコンテンツを取得します。おすすめ情報が乗ったコラムを探してみましょう。

/api/v1/columns?filters=title[contains]おすすめ

[exists]

指定した値が存在する（管理画面で入力済み）であるコンテンツを取得します。次の記事が存在しているブログを絞り込む記述です。

/api/v1/blogs?filters=nextLink[exists]

[not_exists]

指定した値が存在しない（管理画面で未入力）であるコンテンツを取得します。メインビジュアル画像のないブログは以下のように見つけられます。

/api/v1/blogs?filters=mainVisual[not_exists]

[begins_with]

指定した値で始まるコンテンツを取得します。2019年10月のブログを取得する記述がこちら。

/api/v1/blogs?filters=createdAt[begins_with]2019-10

そのほかの注意事項

filtersパラメータで指定できるのは公開状態にあるコンテンツのみです。下書き状態のコンテンツは抽出できません。また、リッチテキスト内部のテキストの検索もできません。こちらについては検索APIでの対応予定ですので今しばらくお待ちください。

また、コンテンツ参照にもいくつかの制約事項があります。

• 単数のコンテンツ参照では使用できるのは [equals] のみです。また、以下の例のように値部分にはコンテンツのidが入ります。

category[equals]uN28Folyn

• 複数のコンテンツ参照では使用できるのは [contains] のみです。また、以下の例のように値部分にはコンテンツのidが入ります

tags[contains]oJIZmiban

終わりに

最後に、今回説明した内容はAPIリファレンスにも表示されていますのでそちらもご確認ください。


さて、ここまででfiltersパラメータについてご説明してきました。これまでは絞り機能がなかったため、全てのデータを取得してメモリ上で絞り込むなどご不便をおかけして申し訳ありませんでした🙇🏻‍♂️
今後はよりスムーズにタグやカテゴリなどを実装できるようになるかと思います！
ぜひお試しください。

-----

microCMSは日々改善を進めています。
ご意見・ご要望は管理画面右下のチャット、公式Twitter、メールからお気軽にご連絡ください！
引き続きmicroCMSをよろしくお願いいたします！