REST API: ポピュレーションとフィールド選択
REST APIはデフォルトでは、関係、メディアフィールド、コンポーネント、またはダイナミックゾーンをポピュレートしません。特定のフィールドをポピュレートするためにpopulateパラメータを、クエリ結果と共に特定のフィールドのみを返すためにselectパラメータを使用します。
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.
AI Marketer v4のドキュメントには最近、populateパラメータの使用方法についてより詳細な説明が含まれており、[詳細なAPIリファレンス](https://docs.AI Marketer.io/dev-docs/api/rest/populate-select#population)や[追加のガイド](https://docs.AI Marketer.io/dev-docs/api/rest/guides/intro)も含まれています。これらのv4のページは現在、AI Marketer 5のドキュメントに移植および適応されており、例が新しいデータレスポンスフォーマットを反映するようになっています。
その間、このページの内容は正確であると信じていただけます。というのも、これはすでに新しいAI Marketer 5、フラット化されたレスポンスフォーマットを反映しているからです（breaking change entryおよびREST API introductionを参照してください）。このページはまだv4と同等の完成度には達していません。
フィールド選択
クエリはfieldsパラメータを受け入れて、一部のフィールドのみを選択することができます。デフォルトでは、以下のフィールドのタイプのみが返されます：
- 文字列タイプ: string、text、richtext、enumeration、email、password、uid
- 日付タイプ: date、time、datetime、timestamp
- 数値タイプ: integer、biginteger、float、decimal
- 汎用タイプ: boolean、array、JSON。
| ユースケース | 例のパラメータ構文 |
|---|---|
| 単一フィールドの選択 | fields=name |
| 複数フィールドの選択 | fields[0]=name&fields[1]=description |
フィールド選択は、関係、メディア、コンポーネント、ダイナミックゾーンのフィールドでは動作しません。これらのフィールドをポピュレートするには、populateパラメータを使用します。
GET /api/restaurants?fields[0]=name&fields[1]=description
{
"data": [
{
"id": 4,
"Name": "ピッツェリアアリヴェデルチ",
"Description": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"text": "ピザ専門店として、私たちはあなたに4フォルマッジやカルツォーネなどのクラシックを再発見することをお勧めします。また、ド・ルイージやンドゥージャなどのオリジナルクリエーションもご用意しています。"
}
]
}
],
"documentId": "lr5wju2og49bf820kj9kz8c3"
},
// …
],
"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(
{
fields: ['name', 'description'],
},
{
encodeValuesOnly: true, // URLをきれいにする
}
);
await request(`/api/users?${query}`);
ポピュレーション
REST APIはデフォルトではフィールドのタイプをポピュレートしません。つまり、関連フィールド、メディアフィールド、コンポーネント、ダイナミックゾーンは、populateパラメータを渡して各種フィールドタイプをポピュレートしない限り、ポピュレートされません。
populateパラメータは単独で使用することも、複数の演算子と組み合わせて使用することも可能で、ポピュレーションの制御をより詳細に行うことができます。
ポピュレートされるコンテンツタイプに対してfind権限が有効になっている必要があります。ロールがコンテンツタイプにアクセスできない場合、そのコンテンツタイプはポピュレートされません（find権限をコンテンツタイプに有効にする方法については、ユーザーガイドを参照してください）。
現在、リクエストでIDの配列のみを返すことはできません。
:::AI Marketer ポピュレートガイド
REST APIガイドセクションには、populateパラメータの様々な使用例について、より詳細な情報が含まれています：
- populateの理解ガイドでは、populateの仕組みを図解や比較、実際の例を交えて詳しく説明しています。
- 作成者フィールドのポピュレート方法ガイドでは、クエリ応答に
createdByとupdatedByフィールドを追加する方法をステップバイステップで説明しています。
:::
以下の表は、可能なポピュレートの使用例とそれに関連するパラメータ構文、およびpopulateガイドの詳細な説明へのリンクをまとめたものです：
| ユースケース | 例のパラメーター構文 | 読むための詳細な説明 |
|---|---|---|
| メディアフィールド、リレーション、コンポーネント、ダイナミックゾーンを含む、1レベル深くすべてを埋める | populate=* | すべてのリレーションとフィールドを1レベル深く埋める |
| 1つのリレーションを埋める、 1レベル深く | populate=a-relation-name | 特定のリレーションに対して1レベル深く埋める |
| 複数のリレーションを埋める、 1レベル深く | populate[0]=relation-name&populate[1]=another-relation-name&populate[2]=yet-another-relation-name | 特定のリレーションに対して1レベル深く埋める |
| いくつかのリレーションを埋める、複数レベル深く | populate[root-relation-name][populate][0]=nested-relation-name | 特定のリレーションに対して複数レベル深く埋める |
| コンポーネントを埋める | populate[0]=component-name | コンポーネントを埋める |
| コンポーネントとそのネストされたコンポーネントの一つを埋める | populate[0]=component-name&populate[1]=component-name.nested-component-name | コンポーネントを埋める |
| ダイナミックゾーンを埋める（その最初のレベルの要素のみ） | populate[0]=dynamic-zone-name | ダイナミックゾーンを埋める |
| 正確に定義された、詳細な埋め込み戦略を使用して、ダイナミックゾーンとそのネストされた要素とリレーションを埋める | populate[dynamic-zone-name][on][component-category.component-name][populate][relation-name][populate][0]=field-name | ダイナミックゾーンを埋める |
複数レベルの埋め込みを含む複雑なクエリを作成する最も簡単な方法は、私たちのインタラクティブなクエリビルダーツールを使用することです。
埋め込みと他のオペレーターの組み合わせ
populateオペレーターを利用することで、フィールド選択、フィルター、およびソートなどの他のオペレーターを埋め込みクエリに組み合わせることができます。
埋め込みとページネーションのオペレーターは組み合わせることができません。
フィールド選択との埋め込み
fieldsとpopulateは組み合わせることができます。
GET /api/articles?fields[0]=title&fields[1]=slug&populate[headerImage][fields][0]=name&populate[headerImage][fields][1]=url
{
"data": [
{
"id": 1,
"documentId": "h90lgohlzfpjf3bvan72mzll",
"title": "テスト記事",
"slug": "test-article",
"headerImage": {
"id": 1,
"documentId": "cf07g1dbusqr8mzmlbqvlegx",
"name": "17520.jpg",
"url": "/uploads/17520_73c601c014.jpg"
}
}
],
"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(
{
fields: ['title', 'slug'],
populate: {
headerImage: {
fields: ['name', 'url'],
},
},
},
{
encodeValuesOnly: true, // URLを整形する
}
);
await request(`/api/articles?${query}`);
フィルタリングと組み合わせたPopulate
filtersとpopulateは組み合わせて使用することができます。
GET /api/articles?populate[categories][sort][0]=name%3Aasc&populate[categories][filters][name][$eq]=Cars
{
"data": [
{
"id": 1,
"documentId": "a1b2c3d4e5d6f7g8h9i0jkl",
"title": "テスト記事",
// ...
"categories": {
"data": [
{
"id": 2,
"documentId": "jKd8djla9ndalk98hflj3",
"name": "車"
// ...
}
]
}
}
}
],
"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(
{
populate: {
categories: {
sort: ['name:asc'],
filters: {
name: {
$eq: '車',
},
},
},
},
},
{
encodeValuesOnly: true, // URLを整形する
}
);
await request(`/api/articles?${query}`);