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

JavaScript 查询（使用 qs 库构建）

上面的查询 URL 是使用 `qs` 库构建的。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
    }
  }
}

人口

🌐 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

总体和分页运算符不能组合使用。

🌐 The population and pagination operators cannot be combined.

用字段选择填充

🌐 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

JavaScript 查询（使用 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}`);

示例响应

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

JavaScript 查询（使用 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}`);

示例响应

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

字段选择​

人口​

将人口与其他操作符结合​

用字段选择填充​

填充并筛选​

字段选择

人口

将人口与其他操作符结合

用字段选择填充

填充并筛选