- チュートリアル
- API
NewtのAPIで利用できるクエリパラメータを理解して、様々なクエリを実行する
この記事ではNewtのAPI(Newt CDN API・Newt API)で利用できるクエリパラメータを理解して、様々なクエリを実行する方法を紹介します。
URLにクエリパラメータを付与する場合の書き方と、SDK を利用する場合の書き方を説明します。
記事内で使用している主なソフトウェアのバージョン
- newt-client-js(
newt-client-js
): 3.2.4
概要
はじめに、NewtのAPI(Newt CDN API・Newt API)で利用可能なクエリと演算子の一覧について説明します。
その後、よくある質問に回答する形で、各クエリの使い方を紹介していきます。
最後に、現状のクエリパラメータではできないことも記載します。
1. 利用可能なクエリ・演算子一覧
1-1. NewtのAPIで利用できるクエリは9種類
まず、NewtのAPI(Newt CDN API・Newt API)で利用できるクエリ一覧について説明します。
NewtのAPIで利用できるクエリには大きく以下の9種類があります。Newt CDN APIもNewt APIも利用できるクエリは共通です。
名前 | 説明 |
---|---|
Filters | 条件に合致するコンテンツのみ取得する |
Format | HTML形式のデータを取得するか、テキスト形式のデータを取得するか指定する |
Select | 指定したフィールドの情報のみ取得する |
Order | 指定した順番で取得する |
Limit | 返却されるコンテンツの最大件数を指定する |
Skip | 何件のコンテンツをスキップするか指定する |
Depth | 画像フィールド・ファイルフィールド・参照フィールドで、取得するデータの階層を指定する |
And | すべての条件に合致するコンテンツを取得する(複数条件の関係を指定) |
Or | いずれかの条件に合致するコンテンツを取得する(複数条件の関係を指定) |
以下、それぞれについて説明します。
詳細については、Queries のリファレンスに記載があるので、ご確認ください。
1-1-1. Filters
条件に合致するコンテンツのみ取得します。
1-2で利用可能なすべての演算子について説明します。
URLの場合
// 書き方
{field}={value}
// 例
slug=hoge
SDKの場合
// 書き方
query: {
field: value
}
// 例
query: {
slug: 'hoge'
}
1-1-2. Format
フィールドタイプがリッチテキストまたはマークダウンの場合、デフォルトではHTML形式のデータが返されます。Formatクエリを利用して、HTML形式のデータを取得するか、テキスト形式のデータを取得するか、指定します。
fmt
演算子を使用して、text
の値を指定した場合に、テキスト形式のデータが返却されます。それ以外の場合はHTML形式のデータが返却されます。
URLの場合
// 書き方
{field}[fmt]=text
// 例
body[fmt]=text
SDKの場合
// 書き方
query: {
field: {
fmt: 'text'
}
}
// 例
query: {
body: {
fmt: 'text'
}
}
1-1-3. Select
指定したフィールドの情報のみ取得します。
URLの場合
// 書き方
select={field},{field}
// 例
select=title,slug
SDKの場合
// 書き方
query: {
select: [field, field]
}
// 例
query: {
select: ['title', 'slug']
}
1-1-4. Order
指定した順番でコンテンツを取得します。
複数の値を指定した場合、左のものから順にソートされます。降順にしたい場合は -
をつけます。
URLの場合
// 書き方
order=-{field},{field}
// 例
order=-priority,_sys.createdAt
SDKの場合
// 書き方
query: {
order: [-field, field]
}
// 例
query: {
order: ['-priority', '_sys.createdAt']
}
1-1-5. Limit
返却されるコンテンツの最大件数を指定します。
URLの場合
// 書き方
limit={value}
// 例
limit=10
SDKの場合
// 書き方
query: {
limit: value
}
// 例
query: {
limit: 10
}
1-1-6. Skip
何件のコンテンツをスキップするか指定します。
URLの場合
// 書き方
skip={value}
// 例
skip=10
SDKの場合
// 書き方
query: {
skip: value
}
// 例
query: {
skip: 10
}
1-1-7. Depth
画像・ファイル・参照フィールドで、取得するデータの階層を指定します。
URLの場合
// 書き方
depth={value}
// 例
depth=2
SDKの場合
// 書き方
query: {
depth: value
}
// 例
query: {
depth: 2
}
1-1-8. And
指定したすべての条件を満たすコンテンツを取得します。
URLで記載する時は &
で接続します。
SDKで記載する時は query
オブジェクトの中にすべての条件を記載します。
URLの場合
// 例: tagの名称がdevelopersであるコンテンツを作成順で取得する
tag=developers&order=_sys.createdAt
SDKの場合
// 例: tagの名称がdevelopersであるコンテンツを作成順で取得する
query: {
tag: 'developers',
order: ['_sys.createdAt']
}
1-1-9. Or
いずれかの条件に合致するコンテンツを取得します。
URLで記載する時は、条件を ()
で囲み、各条件を ;
で区切ります。
SDKで記載する時は query
オブジェクトの中に or
オブジェクトを作成し、配列で条件を記載します。
URLの場合
// 例: slugがdevelopers、またはtagがdevelopersであるコンテンツを取得する
[or]=(slug=developers;tag=developers)
SDKの場合
// 例: slugがdevelopers、またはtagがdevelopersであるコンテンツを取得する
query: {
or: [
{
slug: 'developers',
},
{
tag: 'developers',
},
],
}
また、OR条件と他の条件をANDで接続することも可能です。
URLの場合
// 例: slugがdevelopers、またはtagがdevelopersであるコンテンツを取得する。かつ作成順で取得する
[or]=(slug=developers;tag=developers)&order=_sys.createdAt
SDKの場合
// 例: slugがdevelopers、またはtagがdevelopersであるコンテンツを取得する。かつ作成順で取得する
query: {
or: [
{
slug: 'developers',
},
{
tag: 'developers',
},
],
order: ['_sys.createdAt']
}
1-2. Filtersで利用できる演算子は11種類
上記で説明した Filters
では、さらに11種類の演算子を利用できます。
Newt CDN APIもNewt APIも利用できる演算子は共通です。
演算子 | 説明 |
---|---|
なし | 指定した値に一致するコンテンツを取得する |
ne | 指定した値に一致するコンテンツを除外する |
match | 指定した値を含むコンテンツを取得する |
in | 指定した要素のどれかに一致するコンテンツを取得する |
nin | 指定した要素のどれかに一致するコンテンツを除外する |
all | 指定した要素のすべてを含むコンテンツを取得する |
exists | 指定したフィールドを持つ(持たない)コンテンツを取得する |
gt | 指定した値より大きいコンテンツを取得する |
gte | 指定した値以上のコンテンツを取得する |
lt | 指定した値未満のコンテンツを取得する |
lte | 指定した値以下のコンテンツを取得する |
以下、それぞれについて説明します。
詳細については、Queries のリファレンスに記載があるので、ご確認ください。
1-2-1. 演算子なし
指定した値に一致するコンテンツを取得します。
URLの場合
// 書き方
{field}={value}
// 例
slug=hoge
SDKの場合
// 書き方
query: {
field: value
}
// 例
query: {
slug: 'hoge'
}
1-2-2. ne
指定した値に一致するコンテンツを除外します。
URLの場合
// 書き方
{field}[ne]={value}
// 例
slug[ne]=fuga
SDKの場合
// 書き方
query: {
field: {
ne: value
}
}
// 例
query: {
slug: {
ne: 'fuga'
}
}
1-2-3. match
指定した値を含むコンテンツを取得します。
URLの場合
// 書き方
{field}[match]={value}
// 例
body[match]=abc
SDKの場合
// 書き方
query: {
field: {
match: value
}
}
// 例
query: {
body: {
match: 'abc'
}
}
1-2-4. in
指定した要素のどれかに一致するコンテンツを取得します。
URLの場合
// 書き方
{field}[in]={value},{value}
// 例
tag[in]=developers,community
SDKの場合
// 書き方
query: {
field: {
in: [value, value]
}
}
// 例
query: {
tag: {
in: ['developers', 'community']
}
}
1-2-5. nin
指定した要素のどれかに一致するコンテンツを除外します。
URLの場合
// 書き方
{field}[nin]={value},{value}
// 例
tag[nin]=engineer,designer
SDKの場合
// 書き方
query: {
field: {
nin: [value, value]
}
}
// 例
query: {
tag: {
nin: ['engineer', 'designer']
}
}
1-2-6. all
指定した要素のすべてを含むコンテンツを取得します。
URLの場合
// 書き方
{field}[all]={value},{value}
// 例
tag[all]=update,feature
SDKの場合
// 書き方
query: {
field: {
all: [value, value]
}
}
// 例
query: {
tag: {
all: ['update', 'feature']
}
}
1-2-7. exists
指定したフィールドを持つ(持たない)コンテンツを取得します。
trueを指定した場合は該当のフィールドを持つコンテンツを、falseを指定した場合は該当のフィールドを持たないコンテンツを取得します。
URLの場合
// 書き方
{field}[exists]={value}
// 例
custom.description[exists]=true
SDKの場合
// 書き方
query: {
field: {
exists: true
}
}
// 例
query: {
'custom.description': {
exists: true
}
}
1-2-8. gt
指定した値より大きいコンテンツを取得します。
URLの場合
// 書き方
{field}[gt]={value}
// 例
_sys.createdAt[gt]=2022
SDKの場合
// 書き方
query: {
field: {
gt: value
}
}
// 例
query: {
'_sys.createdAt': {
gt: '2022'
}
}
1-2-9. gte
指定した値以上のコンテンツを取得します。
URLの場合
// 書き方
{field}[gte]={value}
// 例
_sys.createdAt[gte]=2023
SDKの場合
// 書き方
query: {
field: {
gte: value
}
}
// 例
query: {
'_sys.createdAt': {
gte: '2023'
}
}
1-2-10. lt
指定した値未満のコンテンツを取得します。
URLの場合
// 書き方
{field}[lt]={value}
// 例
_sys.createdAt[lt]=2023
SDKの場合
// 書き方
query: {
field: {
lt: value
}
}
// 例
query: {
'_sys.createdAt': {
lt: '2023'
}
}
1-2-11. lte
指定した値以下のコンテンツを取得します。
URLの場合
// 書き方
{field}[lte]={value}
// 例
_sys.createdAt[lte]=2022
SDKの場合
// 書き方
query: {
field: {
lte: value
}
}
// 例
query: {
'_sys.createdAt': {
lte: '2022'
}
}
2. クエリに関するよくある質問(フィールド別)
2-1. 参照フィールド
特定の参照先を持つコンテンツを取得したい(単数の参照フィールド)
単数の(複数値ではない)参照フィールドを利用している場合の質問です。
質問:
「投稿」モデルと「カテゴリ」モデルを定義しています。
投稿モデルはカテゴリという参照フィールドを定義していて、参照先モデルに「カテゴリ」を指定しています。
特定のカテゴリを持つ投稿を取得したいのですが、どのようなクエリを利用すればいいですか?
参照フィールドは _id
の情報を持っているので、あらかじめ_id情報を調べてから演算子なしのFilterを利用します。
例えば_idが 123abc
の場合、以下のようになります。
// URLの場合
category=123abc
// SDKの場合
query: {
category: '123abc'
}
特定の参照先を含むコンテンツを取得したい(複数値の参照フィールド)
複数値の参照フィールドを利用している場合の質問です。
質問:
「投稿」モデルと「タグ」モデルを定義しています。
投稿モデルはタグという複数値の参照フィールドを定義していて、参照先モデルに「タグ」を指定しています。
いずれかのタグを含む投稿を取得したいのですが、どのようなクエリを利用すればいいですか?
参照フィールドは _id
の情報を持っているので、あらかじめ_id情報を調べてからin演算子のFilterを利用します。
例えば_idが 123abc
と 456abc
の場合、以下のようになります。
// URLの場合
tags[in]=123abc,456abc
// SDKの場合
query: {
tags: {
in: ['123abc', '456abc']
}
}
また、「いずれかのタグ」ではなく「特定のタグ」を含む投稿を取得したい場合は、演算子なしでの記載も可能です。
(単数の参照フィールドを利用している場合と同じ書き方となります)
// URLの場合
tags=123abc
// SDKの場合
query: {
tags: '123abc'
}
_id以外の参照先の情報を取得したい
質問:
「投稿」モデル・「著者」モデル・「部門」モデルを定義しています。
投稿モデルは著者という参照フィールドを定義していて、参照先モデルに「著者」を指定しています。
著者モデルは部門という参照フィールドを定義していて、参照先モデルに「部門」を指定しています。
投稿を取得した時に、著者の情報は表示されますが、部門の情報は_idのみしか返却されません。
部門の名前やその他の情報を取得できないですか?
Depthクエリを利用することで、深い階層の情報も取得できます。
以下のように depth
を指定することで、2階層目の情報も取得できます。
// URLの場合
depth=2
// SDKの場合
query: {
depth: 2
}
2-2. リッチテキストフィールド
HTML形式ではなく、プレーンなテキスト形式で取得したい
質問:
「投稿」モデルを定義していて、「body」というリッチテキストフィールドを定義しています。
一覧表示を行う時に、本文の抜粋を表示しようと考えているのですが、
HTML形式ではなく、プレーンなテキスト形式でbodyデータを取得する方法はありますか?
Formatクエリを利用することで、テキスト形式でデータを取得できます。
// URLの場合
body[fmt]=text
// SDKの場合
query: {
body: {
fmt: 'text'
}
}
2-3. マークダウンフィールド
HTML形式ではなく、マークダウン形式のテキストで取得したい
質問:
「投稿」モデルを定義していて、「description」というマークダウンフィールドを定義しています。
HTML形式ではなく、マークダウン形式のままdescriptionデータを取得する方法はありますか?
Formatクエリを利用することで、マークダウン形式のテキストデータを取得できます。
// URLの場合
description[fmt]=text
// SDKの場合
query: {
description: {
fmt: 'text'
}
}
2-4. _sysフィールド
指定した年に公開されたコンテンツのみを取得したい
質問:
「投稿」モデルを定義しています。
2023年に公開された投稿を取得したいのですが、どのようなクエリを利用すればいいですか?
CDN APIを利用している場合、_sys.createdAt
に初めて公開された日時の情報がISO形式で入ります。
gte演算子・lt演算子のFilterを利用します。
// URLの場合
_sys.createdAt[gte]=2023&_sys.createdAt[lt]=2024
// SDKの場合
query: {
'_sys.createdAt': {
gte: '2023',
lt: '2024'
}
}
指定した月に公開されたコンテンツのみを取得したい
質問:
「投稿」モデルを定義しています。
2023年3月に公開された投稿を取得したいのですが、どのようなクエリを利用すればいいですか?
CDN APIを利用している場合、_sys.createdAt
に初めて公開された日時の情報がISO形式で入ります。
gte演算子・lt演算子のFilterを利用します。
// URLの場合
_sys.createdAt[gte]=2023-03&_sys.createdAt[lt]=2023-04
// SDKの場合
query: {
'_sys.createdAt': {
gte: '2023-03',
lt: '2023-04'
}
}
2-5. 日付フィールド
指定した年に公開されたコンテンツのみを取得したい
質問:
「イベント」モデルを定義していて、「date」という日付フィールドを定義しています。
2023年の日付が入力されているイベントを取得したいのですが、どのようなクエリを利用すればいいですか?
gte演算子・lt演算子のFilterを利用します。
// URLの場合
date[gte]=2023&date[lt]=2024
// SDKの場合
query: {
date: {
gte: '2023',
lt: '2024'
}
}
指定した月に公開されたコンテンツのみを取得したい
質問:
「イベント」モデルを定義していて、「date」という日付フィールドを定義しています。
2023年3月の日付が入力されているイベントを取得したいのですが、どのようなクエリを利用すればいいですか?
gte演算子・lt演算子のFilterを利用します。
// URLの場合
date[gte]=2023-03&date[lt]=2023-04
// SDKの場合
query: {
date: {
gte: '2023-03',
lt: '2023-04'
}
}
3. クエリに関するよくある質問(ユースケース別)
3-1. コンテンツの並び替え
データの降順で取得したい
質問:
コンテンツの更新日に応じて、日付が新しいものから順番に表示したいです。
コンテンツを降順で取得する方法はありますか?
CDN APIを利用している場合、_sys.updatedAt
に公開中のコンテンツを更新した日時が入ります。
Orderクエリを利用して、降順にしたい場合は -
をつけます。
// URLの場合
order=-_sys.updatedAt
// SDKの場合
query: {
order: ['-_sys.updatedAt']
}
カスタムオーダーの順番で取得したい
質問:
管理画面でコンテンツを手動で並び替えました。
コンテンツを並び替えた順番の通りに取得する方法はありますか?
_sys.customOrder
に手動並び替えを行った際の順序値が入ります。
降順で取得すると、管理画面の通りに取得できます。
// URLの場合
order=-_sys.customOrder
// SDKの場合
query: {
order: ['-_sys.customOrder']
}
3-2. 検索
複数フィールドのどこかにキーワードが含まれるコンテンツを取得したい
質問:
「投稿」モデルを定義していて、「title」・「body」というフィールドを定義しています。
どちらかのフィールドに特定のキーワードを含むコンテンツを取得したいのですが、
どのようなクエリを利用すればいいですか?
Orクエリを利用することで、いずれかの条件に合致するコンテンツを取得できます。
// URLの場合
[or]=(title[match]=hoge;body[match]=hoge)
// SDKの場合
query: {
or: [
{
title: {
match: 'hoge'
}
},
{
body: {
match: 'hoge'
}
},
],
}
より複雑な検索を実行したい場合は、AlgoliaとNext.jsを利用して、高度な全文検索を実現する のチュートリアルもご確認ください。
リッチテキストフィールド・マークダウンフィールドに対して、「含む」の検索条件を指定したい
3-3. ページネーション
指定した箇所から指定した件数だけ取得したい
質問:
ページネーションの実装を考えています。
例えば41番目のコンテンツから50番目のコンテンツまで取得する場合、
どのようなクエリを利用すればいいですか?
Skipクエリで、何件のコンテンツをスキップするか指定できます。
Limitクエリで、返却されるコンテンツの最大件数を指定できます。
「41番目のコンテンツから50番目のコンテンツまで取得する」という指定は「40個のコンテンツをスキップし、10個のコンテンツを取得する」と言い換えて指定します。
// URLの場合
skip=40&limit=10
// SDKの場合
query: {
skip: 40,
limit: 10
}
3-4. 前後の記事
あるコンテンツの次のコンテンツを取得したい
質問:
「投稿」モデルを定義しています。
記事詳細ページから次の記事に遷移することを考えているのですが、
あるコンテンツの次のコンテンツを取得する場合、
どのようなクエリを利用すればいいですか?
Orderクエリと、gt演算子(lt演算子)のFilterを使います。
SDKの場合は getFirstContent メソッドを使うことで便利に取得できます。
どちらの場合も、以下のステップで考えます。
- 現在のコンテンツと比べて、どの値がより大きい(小さい)のか明確にする
- gt演算子(lt演算子)を利用して、上記の条件を表現する
- 該当のコンテンツが先頭に来るよう並び順を考えて、Orderクエリで表現する
ここでは、公開日の降順で記事を並べていると想定します。1つ次の記事として、公開日が1つ古いものを取得する場合の方法を示します。以下のように考えます。
- 現在のコンテンツと比べて
_sys.createdAt
が1つ古い(小さい)コンテンツを取得したい - 上記はlt演算子で表現できそう
- 1つ古いコンテンツが先頭に来るには、「公開日の降順」=「-_sys.createdAt」で並べると良さそう
// URLの場合
_sys.createdAt[lt]=2023-04-06T00:18:26.810Z&order=-_sys.createdAt&limit=1
// SDKの場合
client.getFirstContent({
(省略)
query: {
'_sys.createdAt': {
lt: article._sys.createdAt, // articleは現在の記事の情報が入っているとする
},
order: ['-_sys.createdAt'],
},
})
あるコンテンツの前のコンテンツを取得したい
質問:
「投稿」モデルを定義しています。
記事詳細ページから前の記事に遷移することを考えているのですが、
あるコンテンツの前のコンテンツを取得する場合、
どのようなクエリを利用すればいいですか?
Orderクエリと、lt演算子(gt演算子)のFilterを使います。
SDKの場合は getFirstContent メソッドを使うことで便利に取得できます。
どちらの場合も、以下のステップで考えます。
- 現在のコンテンツと比べて、どの値がより小さい(大きい)のか明確にする
- lt演算子(gt演算子)を利用して、上記の条件を表現する
- 該当のコンテンツが先頭に来るよう並び順を考えて、Orderクエリで表現する
ここでは、公開日の降順で記事を並べていると想定します。1つ前の記事として、公開日が1つ新しいものを取得する場合の方法を示します。以下のように考えます。
- 現在のコンテンツと比べて
_sys.createdAt
が1つ新しい(大きい)コンテンツを取得したい - 上記はgt演算子で表現できそう
- 1つ新しいコンテンツが先頭に来るには、「公開日の昇順」=「_sys.createdAt」で並べると良さそう
// URLの場合
_sys.createdAt[gt]=2023-04-06T00:18:26.810Z&order=_sys.createdAt&limit=1
// SDKの場合
client.getFirstContent({
(省略)
query: {
'_sys.createdAt': {
gt: article._sys.createdAt, // articleは現在の記事の情報が入っているとする
},
order: ['_sys.createdAt'],
},
})
4. クエリパラメータの仕様上の制限
クエリをかけられないもの
以下に対しては、Filtersによる絞り込み・Formatによる取得形式の変更・Orderによる並び順の指定は行えません。ご注意ください。
- 参照フィールド・画像フィールド・ファイルフィールドの_id以外の項目
- マルチタイプフィールド
以上で、NewtのAPIで利用できるクエリパラメータの紹介を終わります。
クエリパラメータを利用することで、取得形式を柔軟に変更できるので、ぜひお試しください。