メインコンテンツまでスキップ

REST API: ポピュレートとフィールド選択

Page summary:

populate パラメータで、リレーション、メディア、コンポーネント、ダイナミックゾーンを REST API のレスポンスに含めます。fields パラメータで、返すフィールドだけに絞ります。

REST API は既定ではリレーション、メディア、コンポーネント、ダイナミックゾーンをポピュレートしません。含めたいフィールドには populate パラメータ を使います。クエリ結果に特定のフィールドだけを返すには fields パラメータ を使います。

Tip

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.

フィールド選択​

クエリでは fields で返すフィールドを限定できます。既定では REST API は次の フィールド型 のみ返します。

  • 文字列系: string、text、richtext、enumeration、email、password、uid
  • 日付・時刻系: date、time、datetime、timestamp
  • 数値系: integer、biginteger、float、decimal
  • 汎用: boolean、array、JSON
用途パラメータの例
1 フィールドだけfields=name
複数フィールドfields[0]=name&fields[1]=description
Note

フィールド選択は、リレーション、メディア、コンポーネント、ダイナミックゾーンには使えません。これらを含めるには populate パラメータ を使います。

リクエスト例: name と description だけ返す

GET /api/restaurants?fields[0]=name&fields[1]=description

JavaScript のクエリ（qs ライブラリで組み立て）

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, // prettify URL
  }
);

await request(`/api/users?${query}`);

レスポンス例
{
  "data": [
    {
      "id": 4,
      "Name": "Pizzeria Arrivederci",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "Specialized in pizza, we invite you to rediscover our classics, such as 4 Formaggi or Calzone, and our original creations such as Do Luigi or Nduja."
            }
          ]
        }
      ],
      "documentId": "lr5wju2og49bf820kj9kz8c3"
    },
    // …
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 4
    }
  }
}

ポピュレート​

REST API は既定ではこれらの型をポピュレートしないため、populate を渡さない限りリレーション、メディア、コンポーネント、ダイナミックゾーンは含まれません。ポピュレートしたリレーションは常にオブジェクト全体が返り、REST API では ID の配列だけを返すことはできません。

Prerequisites

ポピュレートするコンテンツタイプには find 権限が必要です。ロールにアクセスがないコンテンツタイプはポピュレートされません（find の付与方法は Users & Permissions を参照）。

populate は単独で使うほか、複数のオペレータと組み合わせて細かく制御できます。

Caution

populate=deep 系のプラグインは Strapi では推奨されません。

Note

クエリ文字列に並ぶ長い populate リスト（populate[0]、populate[1]、…）は、クエリパーサの arrayLimit（既定: 100）で上限があります。より長くするには strapi::query ミドルウェア の arrayLimit を上げます。値を大きくするとリクエストあたりのパース負荷が増えます。

次の表は代表的な populate の書式です。各行の詳細は Understanding 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コンポーネントのポピュレート
ダイナミックゾーン（第 1 階層の要素のみ）populate[0]=dynamic-zone-nameダイナミックゾーンのポピュレート
ダイナミックゾーンとネスト・リレーションを、on で明示した戦略でポピュレートpopulate[dynamic-zone-name][on][component-category.component-name][populate][relation-name][populate][0]=field-nameダイナミックゾーンのポピュレート
Tip

階層の深い populate は インタラクティブなクエリビルダー で組み立てるとよいです。例と説明は REST API ガイド も参照してください。

ポピュレートと他オペレータの併用​

populate は、フィールド選択、フィルター、ソート などと組み合わせられます。

Note

ポピュレートとページネーションのオペレータは同時に使えません。

フィールド選択と併用​

fields と populate は一緒に使えます。

リクエスト例

GET /api/articles?fields[0]=title&fields[1]=slug&populate[headerImage][fields][0]=name&populate[headerImage][fields][1]=url

JavaScript のクエリ（qs ライブラリで組み立て）

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, // prettify URL
  }
);

await request(`/api/articles?${query}`);

レスポンス例
{
  "data": [
    {
      "id": 1,
      "documentId": "h90lgohlzfpjf3bvan72mzll",
      "title": "Test Article",
      "slug": "test-article",
      "headerImage": {
        "id": 1,
        "documentId": "cf07g1dbusqr8mzmlbqvlegx",
        "name": "17520.jpg",
        "url": "/uploads/17520_73c601c014.jpg"
      }
    }
  ],
  "meta": {
    // ...
  }
}

フィルターと併用​

filters と populate は一緒に使えます。

リクエスト例

GET /api/articles?populate[categories][sort][0]=name%3Aasc&populate[categories][filters][name][$eq]=Cars

JavaScript のクエリ（qs ライブラリで組み立て）

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: 'Cars',
          },
        },
      },
    },
  },
  {
    encodeValuesOnly: true, // prettify URL
  }
);

await request(`/api/articles?${query}`);

レスポンス例
{
  "data": [
    {
      "id": 1,
      "documentId": "a1b2c3d4e5d6f7g8h9i0jkl",
      "title": "Test Article",
      // ...
      "categories": {
        "data": [
          {
            "id": 2,
            "documentId": "jKd8djla9ndalk98hflj3",
            "name": "Cars"
            // ...
          }
        ]
        }
      }
    }
  ],
  "meta": {
    // ...
  }
}
このページを編集