REST API：人口和字段选择

🌐 REST API: Population & Field Selection

Page summary:

使用 populate 参数在 REST API 响应中包含关系、媒体字段、组件和动态区域。使用 fields 参数仅返回特定字段。

🌐 Use the populate parameter to include relations, media fields, components, and dynamic zones in REST API responses. Use the fields parameter to return only specific fields.

REST API 默认不会填充任何关联、媒体字段、组件或动态区域。使用 populate 参数 来填充特定字段。使用 fields 参数 仅返回查询结果中的特定字段。

🌐 The REST API by default does not populate any relations, media fields, components, or dynamic zones. Use the populate parameter to populate specific fields. Use the fields parameter to return only specific fields with the query results.

Tip

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

🌐 Strapi takes advantage of the ability of the `qs` library to parse nested objects to create more complex queries.

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

🌐 Use qs directly to generate complex queries instead of creating them manually. Examples in this documentation showcase how you can use qs.

如果你更喜欢使用我们的在线工具，而不是在你的机器上使用 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.

字段选择

🌐 Field selection

查询可以接受一个 fields 参数来只选择某些字段。默认情况下，REST API 仅返回以下 类型的字段:

🌐 Queries can accept a fields parameter to select only some fields. By default, the REST API only returns the following types of 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

Note

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

🌐 Field selection does not work on relational, media, component, or dynamic zone fields. To populate these fields, use the populate parameter.

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

只返回名称和描述字段

使用 fields 参数仅选择响应中的特定字段。

cURL

terminal

curl 'http://localhost:1337/api/restaurants?fields[0]=name&fields[1]=description' \
  -H 'Authorization: Bearer <token>'

JavaScript

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

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

200 OK

{
  "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
    }
  }
}

人口

🌐 Population

默认情况下，REST API 不会填充任何类型的字段，因此它不会填充关联、媒体字段、组件或动态区域，除非你传递一个 populate 参数来填充各种字段类型。已填充的关联总是返回完整对象；REST API 目前无法仅返回 ID 数组。

🌐 The REST API by default does not populate any type of fields, so it will not populate relations, media fields, components, or dynamic zones unless you pass a populate parameter to populate various field types. Populated relations always return full objects; the REST API currently cannot return just an array of IDs.

Prerequisites

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

🌐 The find permission must be enabled for the content-types that are being populated. If a role does not have access to a content-type, the content-type will not be populated (see Users & Permissions for additional information on how to enable find permissions for content-types).

你可以单独使用 populate 参数，或与多个操作符结合使用以更好地控制人口。

🌐 You can use the populate parameter alone or in combination with multiple operators for more control over the population.

Caution

populate=deep 插件在 Strapi 中 不推荐使用。

Note

查询字符串中的大型 populate 列表（许多 populate[0]、populate[1] 等条目）受到查询解析器 arrayLimit 的限制（默认值：100）。要允许更长的列表，请在 strapi::query 中间件 上提高 arrayLimit。更高的值会增加每个请求的解析开销。

🌐 Large populate lists in the query string (many populate[0], populate[1], … entries) are bounded by the query parser arrayLimit (default: 100). To allow a longer list, raise arrayLimit on the strapi::query middleware. Higher values increase parsing cost per request.

下表列出了 populate 的用例及示例语法。每一行都链接到“理解 populate”指南以获取详细信息：

🌐 The following table lists populate use cases with example syntax. Each row links to the Understanding populate guide for details:

用例	参数示例语法	详细说明阅读
填充所有内容，深度 1 级，包括媒体字段、关联、组件和动态区域	populate=*	填充所有关联和字段，深度 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	填充动态区域

Tip

要构建具有多级填充的复杂查询，请使用 交互式查询构建器 工具。有关更详细的说明和示例，请参阅 REST API 指南。

🌐 To build complex queries with multiple-level population, use the interactive query builder tool. For more detailed explanations and examples, see the REST API guides.

将人口与其他操作符结合

🌐 Combining population with other operators

你可以在填充查询中将 populate 操作符与其他操作符结合使用，例如 字段选择、过滤器 和 排序。

🌐 You can combine the populate operator with other operators such as field selection, filters, and sort in the population queries.

Note

顶层分页参数（例如，pagination[page] 和 pagination[pageSize]）与 populate 一起用于分页主查询结果。然而，你不能将分页参数直接应用于已填充的关联，以限制每个结果中返回的相关条目数量（REST API 不支持关联上的嵌套分页）。

🌐 Top-level pagination parameters (e.g., pagination[page] and pagination[pageSize]) work alongside populate to paginate the main query results. However, you cannot apply pagination parameters directly to populated relations to limit the number of related entries returned within each result (nested pagination on relations is not supported in the REST API).

用字段选择填充

🌐 Populate with field selection

fields 和 populate 可以结合。

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

用字段选择填充

组合字段并填写参数，以选择主条目及其关联条目上的特定字段。

cURL

terminal

curl 'http://localhost:1337/api/articles?fields[0]=title&fields[1]=slug&populate[headerImage][fields][0]=name&populate[headerImage][fields][1]=url' \
  -H 'Authorization: Bearer <token>'

JavaScript

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

200 OK

{
  "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": {}
}

填充并筛选

🌐 Populate with filtering

filters 和 populate 可以结合。

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

填充并筛选

将 populate 与 sort 和 filter 参数结合使用，以优化返回的相关条目。

cURL

terminal

curl 'http://localhost:1337/api/articles?populate[categories][sort][0]=name%3Aasc&populate[categories][filters][name][$eq]=Cars' \
  -H 'Authorization: Bearer <token>'

JavaScript

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

200 OK

{
  "data": [
    {
      "id": 1,
      "documentId": "a1b2c3d4e5d6f7g8h9i0jkl",
      "title": "Test Article",
      "categories": {
        "data": [
          {
            "id": 2,
            "documentId": "jKd8djla9ndalk98hflj3",
            "name": "Cars"
          }
        ]
      }
    }
  ],
  "meta": {}
}

Note

对于多对多和其他关联表关系，在 populate 对象中显式的 sort 会覆盖默认的连接顺序。省略 sort 可以保留连接顺序（条目关联的顺序）。

🌐 For many-to-many and other join-table relations, an explicit sort within a populate object overrides the default connect order. Omit sort to preserve the connect order (the order in which entries were associated).

Performance tip

在生产环境中，请始终使用显式填充，而不是像 populate=* 这样的通配符。将填充深度限制在 2-3 级，并考虑将填充逻辑集中在路由中间件中。参见 Strapi 博客上的 Building High-Performance Strapi Applications 。