REST API：联表加载（Population）与字段选择

页面摘要： 使用 populate 参数在 REST API 响应中纳入关联、媒体字段、组件与动态区域。使用 fields 参数仅返回特定字段。

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

字段选择（Field selection）

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

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

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

cURL

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

await request(`/api/restaurants?${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 数组。

你可以单独使用 populate 参数，也可以 与其它多个运算符组合，以更精细地控制联表加载。

下表列出了联表加载的用例及示例语法。每一行都链接到「理解联表加载」指南以查看详情：

将联表加载与其它运算符组合

你可以在联表加载查询中将 populate 运算符与字段选择、过滤器和排序等其它运算符组合使用。

配合字段选择进行联表加载

fields 与 populate 可以组合使用。

组合 fields 与 populate 参数，在主条目及其关联上选择特定字段。

cURL

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, // 美化 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 可以组合使用。

组合 populate 与排序、过滤参数，以精炼返回的相关条目。

cURL

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

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

响应

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