理解 REST API 的 populate 参数
Page summary:在 REST API 查询中，
populate参数在响应中包含默认属性之外的额外字段、关系、组件和动态区域。使用populate=*获取所有一级深度关系，或者使用嵌套数组和片段语法显式指定字段以获取更深层或有选择的填充。🌐 The
populateparameter in REST API queries includes additional fields, relations, components, and dynamic zones in responses beyond default attributes. Usepopulate=*for all 1-level-deep relations, or explicitly specify fields with nested arrays and fragment syntax for deeper or selective population.
此页面的内容可能尚未与 Strapi 5 完全同步：
🌐 The content of this page might not be fully up-to-date with Strapi 5 yet:
- 所有概念信息和解释都是正确且最新的。
- 但是，在示例中，响应内容可能略有不同。
示例将在 Strapi 5.0.0（稳定版本）发布之后以及 FoodAdvisor 示例应用升级到 Strapi 5 后完全更新。
但是，响应示例略有不同不应妨碍你掌握本页所教授的基本概念。
🌐 However, having slightly different response examples should not prevent you from grasping the essential concepts taught in this page.
在使用 Strapi 的 REST API 查询内容类型时，默认情况下，响应只包含顶层字段，不包含任何关联、媒体字段、组件或动态区域。
🌐 When querying content-types with Strapi's REST API, by default, responses only include top-level fields and do not include any relations, media fields, components, or dynamic zones.
在 Strapi REST API 的上下文中，Populating 意味着通过返回比默认返回的字段更多的字段来在响应中包含额外的内容。你可以使用populate参数来实现这一点。
🌐 Populating in the context of the Strapi REST API means including additional content with your response by returning more fields than the ones returned by default. You use the populate parameter to achieve this.
在本指南中，示例是使用从 FoodAdvisor 示例应用附带的服务器查询的真实数据构建的。要自己测试示例，请设置 FoodAdvisor，在 /api/ 文件夹中启动服务器，并在发送查询之前确保为被查询的内容类型授予了适当的 find 权限。
本指南将详细解释以下用例：
🌐 The present guide will cover detailed explanations for the following use cases:
- 填充 所有字段和关系，深度1级，
- 填充 一些字段和关系，1 级深度，
- 填充一些字段和关系，几层深,
- 填充 组件,
- 填充动态区域。
填充多层通常被称为“深度填充”。
🌐 Populating several levels deep is often called "deep populate".
除了在查询中使用 populate 参数的各种方法外，你还可以构建自定义控制器作为一种解决方法来填充创建者字段（例如，createdBy 和 updatedBy）。这在专门的 如何填充创建者字段 指南中有说明。
🌐 In addition to the various ways of using the populate parameter in your queries, you can also build a custom controller as a workaround to populate creator fields (e.g., createdBy and updatedBy). This is explained in the dedicated How to populate creator fields guide.
填充所有关系和字段，深度为1级
🌐 Populate all relations and fields, 1 level deep
你可以通过单个查询返回所有关系、媒体字段、组件和动态区域。对于关系，这仅适用于一层深度，以防止性能问题和长时间的响应。
🌐 You can return all relations, media fields, components and dynamic zones with a single query. For relations, this will only work 1 level deep, to prevent performance issues and long response times.
要填充所有一级内容，请在查询中添加 populate=* 参数。
🌐 To populate everything 1 level deep, add the populate=* parameter to your query.
下图比较了 FoodAdvisor 示例应用在填充所有一级数据和未填充时返 回的数据：
让我们比较并解释使用和不使用此查询参数时会发生什么：
🌐 Let's compare and explain what happens with and without this query parameter:
示例：没有 populate
🌐 Example: Without populate
如果没有 populate 参数，对 /api/articles 的 GET 请求只会返回默认属性，不会返回任何媒体字段、关联、组件或动态区域。
🌐 Without the populate parameter, a GET request to /api/articles only returns the default attributes and does not return any media fields, relations, components or dynamic zones.
以下示例是来自 articles 内容类型的所有 4 个条目的完整响应。
🌐 The following example is the full response for all 4 entries from the articles content-types.
请注意，响应仅包含 title、slug、createdAt、updatedAt、publishedAt 和 locale 字段，以及由 CKEditor 插件处理的文章字段内容（ckeditor_content，为简洁起见已截断）：
🌐 Notice how the response only includes the title, slug, createdAt, updatedAt, publishedAt, and locale fields, and the field content of the article as handled by the CKEditor plugin (ckeditor_content, truncated for brevity):
未填充
仅返回默认属性，不包含任何媒体字段、关系、组件或动态区域。
- cURL
- JavaScript
curl 'http://localhost:1337/api/articles' \
-H 'Authorization: Bearer <token>'
const response = await fetch(
'http://localhost:1337/api/articles',
{
headers: {
Authorization: 'Bearer <token>',
},
}
);
const data = await response.json();
{
"data": [
{
"id": 1,
"documentId": "t3q2i3v1z2j7o8p6d0o4xxg",
"title": "Here's why you have to try basque cuisine, according to a basque chef",
"slug": "here-s-why-you-have-to-try-basque-cuisine-according-to-a-basque-chef",
"createdAt": "2021-11-09T13:33:19.948Z",
"updatedAt": "2023-06-02T10:57:19.584Z",
"publishedAt": "2022-09-22T09:30:00.208Z",
"locale": "en",
"ckeditor_content": "// truncated content"
},
{
"id": 2,
"documentId": "k2r5l0i9g3u2j3b4p7f0sed",
"title": "What are chinese hamburgers and why aren't you eating them?",
"slug": "what-are-chinese-hamburgers-and-why-aren-t-you-eating-them",
"createdAt": "2021-11-11T13:33:19.948Z",
"updatedAt": "2023-06-01T14:32:50.984Z",
"publishedAt": "2022-09-22T12:36:48.312Z",
"locale": "en",
"ckeditor_content": "// truncated content"
},
{
"id": 3,
"documentId": "k6m6l9q0n6v9z2m3i0z5jah",
"title": "7 Places worth visiting for the food alone",
"slug": "7-places-worth-visiting-for-the-food-alone",
"createdAt": "2021-11-12T13:33:19.948Z",
"updatedAt": "2023-06-02T11:30:00.075Z",
"publishedAt": "2023-06-02T11:30:00.075Z",
"locale": "en",
"ckeditor_content": "// truncated content"
},
{
"id": 4,
"documentId": "d5m4b6z6g5d9e3v1k9n5gbn",
"title": "If you don't finish your plate in these countries, you might offend someone",
"slug": "if-you-don-t-finish-your-plate-in-these-countries-you-might-offend-someone",
"createdAt": "2021-11-15T13:33:19.948Z",
"updatedAt": "2023-06-02T10:59:35.148Z",
"publishedAt": "2022-09-22T12:35:53.899Z",
"locale": "en",
"ckeditor_content": "// truncated content"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 4
}
}
}
示例：使用 populate=*
🌐 Example: With populate=*
使用 populate=* 参数，对 /api/articles 的 GET 请求也会返回所有媒体字段、一级关系、组件和动态区域。
🌐 With the populate=* parameter, a GET request to /api/articles also returns all media fields, first-level relations, components and dynamic zones.
以下示例是来自 articles 内容类型的所有 4 个条目中的第一个条目的完整响应（id 为 2、3 和 4 的文章数据为了简洁而被截断）。
🌐 The following example is the full response for the first of all 4 entries from the articles content-types (the data from articles with ids 2, 3, and 4 is truncated for brevity).
向下滚动查看响应大小比没有使用 populate 时大得多。响应现在包括额外的字段（见高亮行），例如：
🌐 Scroll down to see that the response size is much bigger than without populate. The response now includes additional fields (see highlighted lines) such as:
image媒体字段（存储关于文章封面 的所有信息，包括其所有不同格式）,blocks动态区域和seo组件的一级字段，category关系及其字段,- 甚至还有一些关于以其他语言翻译的文章的信息，如
localizations对象所示。
要填充深层嵌套的组件，请参阅填充组件部分。
🌐 To populate deeply nested components, see the populate components section.
使用 populate=*
返回所有媒体字段、一阶关系、组件和动态区域。
- cURL
- JavaScript
curl 'http://localhost:1337/api/articles?populate=*' \
-H 'Authorization: Bearer <token>'
const response = await fetch(
'http://localhost:1337/api/articles?populate=*',
{
headers: {
Authorization: 'Bearer <token>',
},
}
);
const data = await response.json();
填充特定的关系和字段
🌐 Populate specific relations and fields
你也可以通过明确定义要填充的内容来填充特定的关系和字段。这要求你知道要填充的字段和关系的名称。
🌐 You can also populate specific relations and fields, by explicitly defining what to populate. This requires that you know the name of fields and relations to populate.
通过这种方式填充的关系和字段可以有1级或多级深度。下图比较了当你填充1级深度与2级深度时， FoodAdvisor 示例应用返回的数据：
根据你的内容结构，你可能会发现使用不同的查询以不同的方式呈现类似的数据。例如，FoodAdvisor 示例应用包含文章、类别和餐厅内容类型，它们以不同的方式相互关联。这意味着，如果你想在单个 GET 请求中获取关于这三种内容类型的数据，你有两个选择：
下图说明了这两种不同的策略：
🌐 The 2 different strategies are illustrated in the following diagram:
作为对象填充与作为数组填充：使用交互式查询构建器
高级查询参数的语法手动构建可能相当复杂。我们建议你使用我们的交互式查询构建器工具来生成 URL。
🌐 The syntax for advanced query parameters can be quite complex to build manually. We recommend you use our interactive query builder tool to generate the URL.
使用这个工具，你将使用熟悉的（JavaScript）格式编写清晰且易读的请求，这应该有助于你理解不同查询和不同填充方式之间的差异。例如，深度填充 2 级意味着将 populate 用作对象，而深度填充 1 级的多个关系意味着将 populate 用作数组：
🌐 Using this tool, you will write clean and readable requests in a familiar (JavaScript) format, which should help you understand the differences between different queries and different ways of populating. For instance, populating 2 levels deep implies using populate as an object, while populating several relations 1 level deep implies using populate as an array:
填充为对象
（填充 1 个关系多个级别）：
{
populate: {
category: {
populate: ['restaurants'],
},
},
}
填充为数组
（填充许多 1 层深的关系）
{
populate: [
'articles',
'restaurants'
],
}
为特定关系填充 1 级深度
🌐 Populate 1 level deep for specific relations
你可以使用 populate 参数作为数组来填充 1 层深度的特定关系。
🌐 You can populate specific relations 1 level deep by using the populate parameter as an array.
由于 REST API 使用 LHS bracket notation （即带方括号的 []），要填充一级参数的语法如下所示：
| 填充多少关系 | 语法示例 |
|---|---|
| 仅 1 个关系 | populate[0]=a-relation-name |
| 多个关系 | populate[0]=relation-name&populate[1]=another-relation-name&populate[2]=yet-another-relation-name |
让我们比较并解释在向 FoodAdvisor 示例应用发送查询时，填充关系一级与不填充关系一级会发生什么：
示例：没有 populate
🌐 Example: Without populate
如果没有 populate 参数，向 /api/articles 的 GET 请求只会返回默认属性。
🌐 Without the populate parameter, a GET request to /api/articles only returns the default attributes.
以下示例是 articles 内容类型所有 4 个条目的完整响应。
🌐 The following example is the full response for all 4 entries from the articles content-type.
请注意，响应不包含任何媒体字段、关系、组件或动态区域：
🌐 Notice that the response does not include any media fields, relations, components or dynamic zones:
未填充
仅返回所有文章的默认属性。
- cURL
- JavaScript
curl 'http://localhost:1337/api/articles' \
-H 'Authorization: Bearer <token>'
const response = await fetch(
'http://localhost:1337/api/articles',
{
headers: {
Authorization: 'Bearer <token>',
},
}
);
const data = await response.json();
{
"data": [
{
"id": 1,
"documentId": "x2m0d7d9o4m2z3u2r2l9yes",
"title": "Here's why you have to try basque cuisine, according to a basque chef",
"slug": "here-s-why-you-have-to-try-basque-cuisine-according-to-a-basque-chef",
"createdAt": "2021-11-09T13:33:19.948Z",
"updatedAt": "2023-06-02T10:57:19.584Z",
"publishedAt": "2022-09-22T09:30:00.208Z",
"locale": "en",
"ckeditor_content": "…"
},
{
"id": 2,
"documentId": "k6m6l9q0n6v9z2m3i0z5jah",
"title": "What are chinese hamburgers and why aren't you eating them?",
"slug": "what-are-chinese-hamburgers-and-why-aren-t-you-eating-them",
"createdAt": "2021-11-11T13:33:19.948Z",
"updatedAt": "2023-06-01T14:32:50.984Z",
"publishedAt": "2022-09-22T12:36:48.312Z",
"locale": "en",
"ckeditor_content": "…"
},
{
"id": 3,
"documentId": "o5d4b0l4p8l4o4k5n1l3rxa",
"title": "7 Places worth visiting for the food alone",
"slug": "7-places-worth-visiting-for-the-food-alone",
"createdAt": "2021-11-12T13:33:19.948Z",
"updatedAt": "2023-06-02T11:30:00.075Z",
"publishedAt": "2023-06-02T11:30:00.075Z",
"locale": "en",
"ckeditor_content": "…"
},
{
"id": 4,
"documentId": "t3q2i3v1z2j7o8p6d0o4xxg",
"title": "If you don't finish your plate in these countries, you might offend someone",
"slug": "if-you-don-t-finish-your-plate-in-these-countries-you-might-offend-someone",
"createdAt": "2021-11-15T13:33:19.948Z",
"updatedAt": "2023-06-02T10:59:35.148Z",
"publishedAt": "2022-09-22T12:35:53.899Z",
"locale": "en",
"ckeditor_content": "…"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 4
}
}
}
示例：使用 populate[0]=category
🌐 Example: With populate[0]=category
在请求中添加 populate[0]=category 后，我们明确要求包含一些关于 category 的信息，category 是一个关系字段，用于链接 articles 和 categories 内容类型。
🌐 With populate[0]=category added to the request, we explicitly ask to include some information about category, which is a relation field that links the articles and the categories content-types.
以下示例是 articles 内容类型所有 4 个条目的完整响应。
🌐 The following example is the full response for all 4 entries from the articles content-type.
请注意，响应现在包含每篇文章的 category 字段的额外数据（见高亮行）：
🌐 Notice that the response now includes additional data with the category field for each article (see highlighted lines):
使用 populate[0]=category
返回填充了相关类别数据的文章。
- cURL
- JavaScript
curl 'http://localhost:1337/api/articles?populate[0]=category' \
-H 'Authorization: Bearer <token>'
const response = await fetch(
'http://localhost:1337/api/articles?populate[0]=category',
{
headers: {
Authorization: 'Bearer <token>',
},
}
);
const data = await response.json();
为特定关系填充多层数据
🌐 Populate several levels deep for specific relations
你还可以填充特定的多层关系。例如，当你填充一个关系，而该关系本身又填充另一个关系时，你就是在填充两层深的关系。在本指南中介绍的示例就是填充两层深的关系。
🌐 You can also populate specific relations several levels deep. For instance, when you populate a relation which itself populates another relation, you are populating 2 levels deep. Populating 2 levels deep is the example covered in this guide.
可以填充的层级数量没有限制。然而，填充的层级越深，请求执行所需的时间就越长。
🌐 There is no limit on the number of levels that can be populated. However, the deeper the populates, the more the request will take time to be performed.
由于 REST API 使用 LHS bracket notation（即使用方括号 []），例如，如果你想填充嵌套在另一个关系中的关系，参数语法如下所示：
populate[first-level-relation-to-populate][populate][0]=second-level-relation-to-populate
高级查询参数的语法手动构建起来可能相当复杂。我们建议你使用我们的交互式查询构建器工具来生成 URL。例如，以下示例中使用的 /api/articles?populate[category][populate][0]=restaurants URL 是通过使用我们的工具将以下对象转换生成的：
🌐 The syntax for advanced query parameters can be quite complex to build manually. We recommend you use our interactive query builder tool to generate the URL. For instance, the /api/articles?populate[category][populate][0]=restaurants URL used in the following examples has been generated by converting the following object using our tool:
{
populate: {
category: {
populate: ['restaurants'],
},
},
}
该 FoodAdvisor 示例应用包含内容类型之间的各种级别的关系。例如：
- 一个
article内容类型包括与category内容类型的关系， - 但是
category也可以分配给任何restaurant内容类型。
通过对 /api/articles 发出一次 GET 请求并使用适当的 populate 参数，你可以同时返回关于文章、餐厅和类别的信息。
🌐 With a single GET request to /api/articles and the appropriate populate parameters, you can return information about articles, restaurants, and categories simultaneously.
让我们比较并解释在向 FoodAdvisor 发送查询时，populate[0]=category（1 级深度）和 populate[category][populate][0]=restaurants（2 级深度）返回的响应：
🌐 Let's compare and explain the responses returned with populate[0]=category (1 level deep) and populate[category][populate][0]=restaurants (2 levels deep) when sending queries to FoodAdvisor:
示例：具有 1 级深度的人口
🌐 Example: With 1-level deep population
当我们只填充一层深度时，查询与文章相关的类别，我们可以得到以下示例响应（高亮行显示 category 关系字段）：
🌐 When we only populate 1 level deep, asking for the categories associated to articles, we can get the following example response (highlighted lines show the category relations field):
具有1级深度的人口
填充类别关系，深入1级。
- cURL
- JavaScript
curl 'http://localhost:1337/api/articles?populate[0]=category' \
-H 'Authorization: Bearer <token>'
const response = await fetch(
'http://localhost:1337/api/articles?populate[0]=category',
{
headers: {
Authorization: 'Bearer <token>',
},
}
);
const data = await response.json();
示例：具有两级深度的人口
🌐 Example: With 2-level deep population
当我们填充 2 层深度时，询问与文章相关的类别，以及与这些类别相关的餐馆，我们可以得到以下示例响应。
🌐 When we populate 2 levels deep, asking for the categories associated to articles, but also for restaurants associated to these categories, we can get the following example response.
请注意，我们现在在 category 关系内的响应中包含了 restaurants 关系字段（见高亮行）：
🌐 Notice that we now have the restaurants relation field included with the response inside the category relation (see highlighted lines):
具有两级深度的人口
填充类别关系和嵌套的餐厅关系，深度为2级。
- cURL
- JavaScript
curl 'http://localhost:1337/api/articles?populate[category][populate][0]=restaurants' \
-H 'Authorization: Bearer <token>'
const response = await fetch(
'http://localhost:1337/api/articles?populate[category][populate][0]=restaurants',
{
headers: {
Authorization: 'Bearer <token>',
},
}
);
const data = await response.json();
填充组件
🌐 Populate components
默认情况下，组件和动态区域不包含在响应中，你需要显式填充每个动态区域、组件及其嵌套组件。
🌐 Components and dynamic zones are not included in responses by default and you need to explicitly populate each dynamic zones, components, and their nested components.
由于 REST API 使用 LHS bracket notation（即带方括号的 []），你需要在 populate 数组中传递所有元素。嵌套字段也可以传递，参数语法可能如下所示：
populate[0]=a-first-field&populate[1]=a-second-field&populate[2]=a-third-field&populate[3]=a-third-field.a-nested-field&populate[4]=a-third-field.a-nested-component.a-nested-field-within-the-component
高级查询参数的语法手动构建起来可能相当复杂。我们建议你使用我们的交互式查询构建器工具来生成 URL。例如，以下示例中使用的 /api/articles?populate[0]=seo&populate[1]=seo.metaSocial&populate[2]=seo.metaSocial.image URL 是通过使用我们的工具将以下对象转换生成的：
🌐 The syntax for advanced query parameters can be quite complex to build manually. We recommend you use our interactive query builder tool to generate the URL. For instance, the /api/articles?populate[0]=seo&populate[1]=seo.metaSocial&populate[2]=seo.metaSocial.image URL used in the following examples has been generated by converting the following object using our tool:
{
populate: [
'seoData',
'seoData.sharedImage',
'seoData.sharedImage.media',
],
},
该 FoodAdvisor 示例应用包括各种组件，甚至包括嵌套在其他组件中的组件。例如：
- 一个
article内容类型包括一个seo组件 1， seo组件包含一个嵌套的、可重复的metaSocial组件 2,- 而
metaSocial组件本身有几个字段，包括一个image媒体字段 3。
默认情况下，这些字段或组件都不会包含在对 /api/articles 的 GET 请求响应中。但通过适当的 populate 参数，你可以在一次请求中返回它们所有。
🌐 By default, none of these fields or components are included in the response of a GET request to /api/articles. But with the appropriate populate parameters, you can return all of them in a single request.
让我们比较并解释通过 populate[0]=seo（一级组件）和 populate[0]=seo&populate[1]=seo.metaSocial（嵌套在一级组件中的二级组件）返回的响应：
🌐 Let's compare and explain the responses returned with populate[0]=seo (1st level component) and populate[0]=seo&populate[1]=seo.metaSocial (2nd level component nested within the 1st level component):
示例：仅第一级组件
🌐 Example: Only 1st level component
当我们只填充 seo 组件时，我们只深入 1 级，并且可以得到以下示例响应。高亮的行显示了 seo 组件。
🌐 When we only populate the seo component, we go only 1 level deep, and we can get the following example response. Highlighted lines show the seo component.
注意没有提到嵌套在 seo 组件中的 metaSocial 组件：
🌐 Notice there's no mention of the metaSocial component nested within the seo component:
仅一级组件
仅填充 SEO 组件，深度为1级。
- cURL
- JavaScript
curl 'http://localhost:1337/api/articles?populate[0]=seo' \
-H 'Authorization: Bearer <token>'
const response = await fetch(
'http://localhost:1337/api/articles?populate[0]=seo',
{
headers: {
Authorization: 'Bearer <token>',
},
}
);
const data = await response.json();
示例：一级组件和二级组件
🌐 Example: 1st level and 2nd level component
当我们填充两层深度时，同时请求 seo 组件和嵌套在 seo 内的 metaSocial 组件，我们可以得到以下示例响应。
🌐 When we populate 2 levels deep, asking both for the seo component and the metaSocial component nested inside seo, we can get the following example response.
请注意，我们现在在响应中包含了 metaSocial 组件相关的数据（见高亮行）：
🌐 Notice that we now have the metaSocial component-related data included with the response (see highlighted lines):
一级组件和二级组件
填充 seo 组件和嵌套的 metaSocial 组件。
- cURL
- JavaScript
curl 'http://localhost:1337/api/articles?populate[0]=seo&populate[1]=seo.metaSocial' \
-H 'Authorization: Bearer <token>'
const response = await fetch(
'http://localhost:1337/api/articles?populate[0]=seo&populate[1]=seo.metaSocial',
{
headers: {
Authorization: 'Bearer <token>',
},
}
);
const data = await response.json();
填充动态区域
🌐 Populate dynamic zones
动态区域本质上是高度动态的内容结构。在查询动态区域时，标准填充参数（例如 populate[0]=dynamic-zone-name 或 populate=*）只会获取动态区域内组件的默认标量字段（例如字符串、数字、布尔值）。默认情况下，它们不会填充这些组件内部的嵌套关系、媒体字段或嵌套组件。
🌐 Dynamic zones are highly dynamic content structures by essence. When querying dynamic zones, standard populate parameters (such as populate[0]=dynamic-zone-name or populate=*) will only fetch the default scalar fields (e.g., strings, numbers, booleans) of the components within the dynamic zone. By default, they will not populate nested relations, media fields, or nested components inside those components.
要检索特定组件的嵌套关系、媒体字段或动态区域内的组件，必须使用 on 属性（片段填充语法）为每个组件定义填充查询。这是因为动态区域中的不同组件可能具有完全不同的结构，并且需要它们自己的独特嵌套查询。
🌐 To retrieve component-specific nested relations, media fields, or components within a dynamic zone, you must define per-component populate queries using the on property (fragment population syntax). This is because different components in a dynamic zone can have completely different structures, and require their own unique nested queries.
例如，在 FoodAdvisor 示例应用中：
article内容类型上存在一个blocks动态区域 1。- 动态区域包括3个不同的组件：
relatedArticles2、faq3 和CtaCommandLine4。所有组件都有不同的内容结构，包含各种字段。 relatedArticles组件与文章内容类型具有articles关系 5 。
默认情况下，对 /api/articles 发起的 GET 请求的响应中不会包含任何深度嵌套的字段或关系。通过使用适当的 populate 参数并应用使用 on 属性的详细填充策略，你可以返回精确所需的数据。
🌐 By default, none of the deeply nested fields or relations are included in the response of a GET request to /api/articles. With the appropriate populate parameters and by applying a detailed population strategy using the fragment on property, you can return precisely the data you need.
高级查询参数的语法手动构建起来可能相当复杂。我们建议你使用我们的交互式查询构建器工具来生成 URL。例如，以下示例中使用的 /api/articles?populate[blocks][on][blocks.related-articles][populate][articles][populate][0]=image&populate[blocks][on][blocks.cta-command-line][populate]=* URL 是通过使用我们的工具将以下对象转换生成的：
🌐 The syntax for advanced query parameters can be quite complex to build manually. We recommend you use our interactive query builder tool to generate the URL. For instance, the /api/articles?populate[blocks][on][blocks.related-articles][populate][articles][populate][0]=image&populate[blocks][on][blocks.cta-command-line][populate]=* URL used in the following example has been generated by converting the following object using our tool:
{
populate: {
blocks: { // asking to populate the blocks dynamic zone
on: { // using a detailed population strategy to explicitly define what you want
'blocks.related-articles': {
populate: {
'articles': {
populate: ['image']
}
}
},
'blocks.cta-command-line': {
populate: '*'
}
},
},
},
}
让我们通过共享人口策略和详细人口策略的一些示例来比较和解释返回的响应：
🌐 Let's compare and explain the responses returned with some examples of a shared population strategy and a detailed population strategy:
例子
🌐 Example
当我们填充 blocks 动态区域时，我们会明确规定要填充哪些数据。
🌐 When we populate the blocks dynamic zone, we explicitly define which data to populate.
在以下示例响应中，高亮的行显示：
🌐 In the following example response, highlighted lines show that:
- 我们深入填充了
relatedArticles组件的articles关联，甚至使用片段（on）填充相关文章的image媒体字段。 - 但是因为我们只要求为
CtaCommandLine组件填充所有内容，并且没有为faq组件定义任何内容，所以没有返回来自faq组件的数据。
动态区域的详细人口策略
使用详细的逐组件填充策略来填充区块的动态区域。
- cURL
- JavaScript
curl 'http://localhost:1337/api/articles?populate[blocks][on][blocks.related-articles][populate][articles][populate][0]=image&populate[blocks][on][blocks.cta-command-line][populate]=*' \
-H 'Authorization: Bearer <token>'
const response = await fetch(
'http://localhost:1337/api/articles?populate[blocks][on][blocks.related-articles][populate][articles][populate][0]=image&populate[blocks][on][blocks.cta-command-line][populate]=*',
{
headers: {
Authorization: 'Bearer <token>',
},
}
);
const data = await response.json();
使用 populate=* 或深度填充插件可能会产生不可预测且代价高昂的数据库查询。在生产环境中，始终显式填充并将深度限制为 2-3 级。考虑使用路由级中间件来集中填充逻辑。详见 Strapi 博客上的 Building High-Performance Strapi Applications 。