REST API: フィルタリング、ロケール、公開状態
REST API は、"エントリの取得"メソッドで見つけた結果をフィルタリングする機能を提供します。
オプショナルなAI Marketerの機能を使用すると、さらに多くのフィルターが提供されます：
- コンテンツタイプで国際化（i18n）プラグインが有効になっている場合、ロケールでフィルタリングすることが可能です。
- 下書き＆公開が有効になっている場合、
published（デフォルト）またはdraftのステータスに基づいてフィルタリングすることが可能です。
Strapi takes advantage of the ability of the qs library to parse nested objects to create more complex queries.
Use qs directly to generate complex queries instead of creating them manually. Examples in this documentation showcase how you can use qs.
You can also use the interactive query builder if you prefer playing with our online tool instead of generating queries with qs on your machine.
フィルタリング
クエリは以下の構文でfiltersパラメータを受け入れることができます：
GET /api/:pluralApiId?filters[field][operator]=value
以下のオペレーターが利用可能です：
| オペレーター | 説明 |
|---|---|
$eq | 等しい |
$eqi | 等しい（大文字小文字を区別しない） |
$ne | 等しくない |
$nei | 等しくない（大文字小文字を区別しない） |
$lt | より小さい |
$lte | 以下 |
$gt | より大きい |
$gte | 以上 |
$in | 配列に含まれる |
$notIn | 配列に含まれない |
$contains | 含む |
$notContains | 含まない |
$containsi | 含む（大文字小文字を区別しない） |
$notContainsi | 含まない（大文字小文字を区別しない） |
$null | nullである |
$notNull | nullでない |
$between | ～の間 |
$startsWith | ～で始まる |
$startsWithi | ～で始まる（大文字小文字を区別しない） |
$endsWith | ～で終わる |
$endsWithi | ～で終わる（大文字小文字を区別しない） |
$or | フィルターを"or"式で結合する |
$and | フィルターを"and"式で結合する |
$not | フィルターを"not"式で結合する |
デフォルトでは、フィルタはContent-type BuilderやCLIによって生成されたfindエンドポイントからのみ使用できます。
例：名前が'John'のユーザーを探す
$eqフィルタ演算子を使用して、正確な一致を見つけることができます。
GET /api/users?filters[username][$eq]=John
{
"data": [
{
"id": 1,
"documentId": "znrlzntu9ei5onjvwfaalu2v",
"username": "John",
"email": "john@test.com",
"provider": "local",
"confirmed": true,
"blocked": false,
"createdAt": "2021-12-03T20:08:17.740Z",
"updatedAt": "2021-12-03T20:08:17.740Z"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
JavaScript query (built with the qs library):
The query URL above was built using the qs library.
qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.
const qs = require('qs');
const query = qs.stringify({
filters: {
username: {
$eq: 'John',
},
},
}, {
encodeValuesOnly: true, // URLを整形
});
await request(`/api/users?${query}`);
例：IDが3、6、8の複数のレストランを探す
$inフィルタ演算子を値の配列と共に使用して、複数の正確な値を見つけることができます。
GET /api/restaurants?filters[id][$in][0]=6&filters[id][$in][1]=8
{
"data": [
{
"id": 6,
"documentId": "ethwxjxtvuxl89jq720e38uk",
"name": "test6",
// ...
},
{
"id": 8,
"documentId": "cf07g1dbusqr8mzmlbqvlegx",
"name": "test8",
// ...
},
],
"meta": {
// ...
}
}
JavaScript query (built with the qs library):
The query URL above was built using the qs library.
qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.
const qs = require('qs');
const query = qs.stringify({
filters: {
id: {
$in: [3, 6, 8],
},
},
}, {
encodeValuesOnly: true, // URLを整形
});
await request(`/api/restaurants?${query}`);
複雑なフィルタリング
複雑なフィルタリングとは、$andや$orなどの高度な方法を使用して複数のフィルタを組み合わせることです。これにより、必要なデータを正確にリクエストするための柔軟性が増します。
GET /api/books?filters[$or][0][date][$eq]=2020-01-01&filters[$or][1][date][$eq]=2020-01-02&filters[author][name][$eq]=Kai%20doe
{
"data": [
{
"id": 1,
"documentId": "rxngxzclq0zdaqtvz67hj38d",
"name": "test1",
"date": "2020-01-01",
// ...
},
{
"id": 2,
"documentId": "kjkhff4e269a50b4vi16stst",
"name": "test2",
"date": "2020-01-02",
// ...
}
],
"meta": {
// ...
}
}
JavaScript query (built with the qs library):
The query URL above was built using the qs library.
qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.
const qs = require('qs');
const query = qs.stringify({
filters: {
$or: [
{
date: {
$eq: '2020-01-01',
},
},
{
date: {
$eq: '2020-01-02',
},
},
],
author: {
name: {
$eq: 'Kai doe',
},
},
},
}, {
encodeValuesOnly: true, // prettify URL
});
await request(`/api/books?${query}`);
ディープフィルタリング
ディープフィルタリングとは、関連フィールドのフィルタリングを指します。
- ディープフィルタを使用してAPIをクエリすると、パフォーマンスに問題が発生する可能性があります。 ディープフィルタリングのクエリが遅すぎる場合は、クエリの最適化版を持つカスタムルートを作成することをお勧めします。
- ディープフィルタリングは、メディアフィールドなどの一部の多態的な関係では利用できませんが、ダイナミックゾーンでは機能します。
- 関係、メディアフィールド、コンポーネント、ダイナミックゾーンはデフォルトではポピュレートされません。これらのデータ構造をポピュレートするには、
populateパラメータを使用してください（populateドキュメンテーションを参照） - ダイナミックゾーンやメディアフィールドにフィルタをかけることはできません。
GET /api/restaurants?filters[chef][restaurants][stars][$eq]=5
{
"data": [
{
"id": 1,
"documentId": "cvsz61qg33rtyv1qljb1nrtg",
"name": "GORDON RAMSAY STEAK",
"stars": 5
// ...
},
{
"id": 2,
"documentId": "uh17h7ibw0g8thit6ivi71d8",
"name": "GORDON RAMSAY BURGER",
"stars": 5
// ...
}
],
"meta": {
// ...
}
}
JavaScript query (built with the qs library):
The query URL above was built using the qs library.
qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.
const qs = require('qs');
const query = qs.stringify({
filters: {
chef: {
restaurants: {
stars: {
$eq: 5,
},
},
},
},
}, {
encodeValuesOnly: true, // prettify URL
});
await request(`/api/restaurants?${query}`);
ロケール
- 国際化（i18n）機能がインストールされていること。
- コンテンツタイプに対してローカライゼーションが有効になっていること。
locale APIパラメータは、特定のロケールからのエントリーを操作するために使用できます（国際化ドキュメンテーションを参照）。
GET /api/articles?status=draft
{
"data": [
// …
{
"id": 5,
"documentId": "znrlzntu9ei5onjvwfaalu2v",
"Name": "Biscotte Restaurant",
"Description": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"text": "This is the draft version."
}
]
}
],
"createdAt": "2024-03-06T13:43:30.172Z",
"updatedAt": "2024-03-06T21:38:46.353Z",
"publishedAt": null,
"locale": "en"
},
// …
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 4
}
}
}
JavaScript query (built with the qs library):
The query URL above was built using the qs library.
qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.
const qs = require('qs');
const query = qs.stringify({
status: 'draft',
}, {
encodeValuesOnly: true, // URLをきれいにする
});
await request(`/api/articles?${query}`);