数据填充与字段选择 Population & Field Selection

Use Strapi's REST API to populate or select certain fields.

REST API 默认不填充任何关系、媒体字段、组件或动态区域。使用 populate 参数可以填充特定字段，使用 select 参数可以只返回查询结果中的特定字段。确保为填充的关系字段授予查找权限。

Strapi 利用 qs 库解析嵌套对象的能力来创建更复杂的查询。

直接使用 qs 来生成复杂的查询，而不是手动创建它们。文档中的示例展示了如何使用 qs。

如果你更喜欢使用我们的在线工具来生成查询，而不是在你的机器上使用 qs，你也可以使用交互式查询生成器。

字段选择

查询可以接受一个 fields 参数来选择部分字段。默认情况下，只返回以下字段类型：

字符串类型：string, text, richtext, enumeration, email, password, 和 uid,
日期类型：date, time, datetime, 和 timestamp,
数字类型：integer, biginteger, float, 和 decimal,
通用类型：boolean, array, 和 JSON.

字段选择不适用于关系、媒体、组件或动态区域字段。要填充这些字段，请使用 populate 参数。

默认情况下，字段会被选择，除了关系、媒体、动态区域和组件字段，但你可以用通配符 * 来代替数组来指定所有字段。

示例请求：仅返回标题和正文字段

bash

GET /api/users?fields[0]=title&fields[1]=body

Example response

json

{
  "data": [
    {
      "id": 1,
      "attributes": {
        "title": "test1",
        "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
      }
    }
  ],
  "meta": {
    // ...
  }
}

qs查询

上面的查询 URL 是使用 qs 库构建的。 qs 可以在您的机器上本地运行，如以下代码示例所示，或者您可以使用我们的 交互式查询生成器 在线工具。

const qs = require('qs')
const query = qs.stringify(
  {
    fields: ['title', 'body'],
  },
  {
    encodeValuesOnly: true, // prettify URL
  }
)

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

填充

默认情况下，REST API 不会填充任何类型的字段，因此除非您传递 populate 参数来填充各种字段类型，否则它不会填充关系、媒体字段、组件或动态区域。

populate 参数可以单独使用，也可以与多个运算符结合使用，以便更好地控制填充。

必须为正在填充的内容类型启用 find 权限。如果角色无权访问内容类型，则不会填充该内容类型（有关如何为内容类型启用 find 权限的更多信息，请参阅用户指南）。

目前无法通过请求仅返回一个 ID 数组。

填充指南

REST API 指南部分包含有关填充参数的各种可能用例的更多详细信息：

了解填充指南详细说明了填充的工作原理，并提供了图表、比较和实际示例。
如何填充创建者字段指南提供了有关如何将 createdBy 和 updatedBy 字段添加到查询响应的分步说明。

Strapi 博客还包括有关如何使用查询填充和过滤数据的教程。

下表总结了可能的填充用例及其相关参数语法，并链接到“了解填充”指南的各部分，其中包含更详细的解释：

用例	参数语法示例	详细解释
填充所有内容，深度为 1 级，包括媒体字段、关系、组件和动态区域	`populate=*`	填充所有关系和字段，深度为 1 级
填充一个关系，深度为 1 级	`populate[0]=a-relation-name`	为特定关系填充 1 级
填充多个关系，深度为 1 级	`populate[0]=relation-name&populate[1]=another-relation-name&populate[2]=yet-another-relation-name`	为特定关系填充 1 级深度
填充一些关系，深度为几级	`populate[first-level-relation-to-populate][populate][0]=second-level-relation-to-populate`	为特定关系填充几级深度
填充组件	`populate[0]=component-name`	填充组件
填充组件及其嵌套组件之一	`populate[0]=component-name&populate[1]=component-name.nested-component-name`	填充组件
填充动态区域（仅限其第一级元素）	`populate[0]=dynamic-zone-name`	填充动态区域
使用唯一、共享的填充策略填充动态区域及其嵌套元素和关系	`populate[dynamic-zone-name][populate]=*`	填充动态区域
使用精确定义的详细填充策略填充动态区域及其嵌套元素和关系	`populate[dynamic-zone-name][on][dynamic-zone-name.component-name][populate][relation-name][populate][0]=field-name`	填充动态区域

构建具有多级填充的复杂查询的最简单方法是使用我们的交互式查询生成器工具。

将 Population 与其他运算符相结合

通过使用 populate 运算符，可以在 Population 查询中结合其他运算符，例如 field choice、filters 和 sort。

population 和 pagination 运算符不能结合使用。

使用字段选择进行 Populate

fields 和 populate 可以结合使用。

Example request

bash

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

Example response

json

{
  "data": [
    {
      "id": 1,
      "attributes": {
        "title": "Test Article",
        "slug": "test-article",
        "headerImage": {
          "data": {
            "id": 1,
            "attributes": {
              "name": "17520.jpg",
              "url": "/uploads/17520_73c601c014.jpg"
            }
          }
        }
      }
    }
  ],
  "meta": {
    // ...
  }
}

qs查询

上述查询 URL 是使用 qs 库构建的。 qs 可以在您的机器上本地运行，如以下代码示例所示，或者您可以使用我们的 交互式查询生成器 在线工具。

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}`)

使用过滤填充

filters 和 populate 可以组合使用。

Example request

bash

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

Example response

json

{
  "data": [
    {
      "id": 1,
      "attributes": {
        "title": "Test Article",
        // ...
        "categories": {
          "data": [
            {
              "id": 2,
              "attributes": {
                "name": "Cars"
                // ...
              }
            }
          ]
        }
      }
    }
  ],
  "meta": {
    // ...
  }
}

qs查询

上述查询 URL 是使用 qs 库构建的。 qs 可以在您的机器上本地运行，如以下代码示例所示，或者您可以使用我们的 交互式查询生成器 在线工具。

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}`)