REST API:过滤、区域设置和发布状态

¥REST API: Filtering, Locale, and Publication State

REST API 能够过滤通过 "获取条目" 方法找到的结果。
使用可选的 Strapi 功能可以提供更多过滤器：

¥The REST API offers the ability to filter results found with its "Get entries" method.
Using optional Strapi features can provide some more filters:

• 如果在内容类型上启用了 国际化 (i18n) 插件，则可以按区域设置进行过滤。

  ¥If the Internationalization (i18n) plugin is enabled on a content-type, it's possible to filter by locale.

• 如果启用了 起草并发布，则可以根据 published（默认）或 draft 状态进行过滤。

  ¥If the Draft & Publish is enabled, it's possible to filter based on a published (default) or draft status.

💡 提示

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.

过滤

¥Filtering

查询可以接受具有以下语法的 filters 参数：

¥Queries can accept a filters parameter with the following syntax:

GET /api/:pluralApiId?filters[field][operator]=value

可以使用以下运算符：

¥The following operators are available:

运算符	描述
$eq	平等的
$eqi	等于（不区分大小写）
$ne	不等于
$nei	不等于（不区分大小写）
$lt	少于
$lte	小于或等于
$gt	比...更棒
$gte	大于或等于
$in	包含在数组中
$notIn	不包含在数组中
$contains	包含
$notContains	不含
$containsi	包含（不区分大小写）
$notContainsi	不包含（不区分大小写）
$null	一片空白
$notNull	不为空
$between	在。。。之间
$startsWith	以。。开始
$startsWithi	开头为（不区分大小写）
$endsWith	以。。结束
$endsWithi	结尾为（不区分大小写）
$or	连接 "or" 表达式中的过滤器
$and	连接 "and" 表达式中的过滤器
$not	连接 "not" 表达式中的过滤器

✋ 提醒

默认情况下，只能从内容类型生成器和 CLI 生成的 find 端点使用过滤器。

¥By default, the filters can only be used from find endpoints generated by the Content-type Builder and the CLI.

示例：查找名字为 '约翰' 的用户

¥Example: Find users having 'John' as a first name

你可以使用 $eq 过滤运算符来查找完全匹配。

¥You can use the $eq filter operator to find an exact match.

Find users having 'John' as first name

GET /api/users?filters[username][$eq]=John

JavaScript 查询（使用 qs 库构建）：

¥JavaScript query (built with the qs library):

上面的查询 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({
  filters: {
    username: {
      $eq: 'John',
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

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

Example response

{
  "data": [
    {
      "id": 1,
      "documentId": "znrlzntu9ei5onjvwfaalu2v",
      "username": "John",
      "email": "john@test.com",
      "provider": "local",
      "confirmed": true,
      "blocked": false,
      "createdAt": "2021-12-03T20:08:17.740Z",
      "updatedAt": "2021-12-03T20:08:17.740Z"
    }
  ],
  "meta": {
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "pageCount": 1,
    "total": 1
  }
}

示例：查找多个 id 为 3, 6,8 的餐厅

¥Example: Find multiple restaurants with ids 3, 6,8

你可以将 $in 过滤运算符与值数组结合使用来查找多个精确值。

¥You can use the $in filter operator with an array of values to find multiple exact values.

Find multiple restaurants with ids 3, 6, 8

GET /api/restaurants?filters[id][$in][0]=6&filters[id][$in][1]=8

JavaScript 查询（使用 qs 库构建）：

¥JavaScript query (built with the qs library):

上面的查询 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({
  filters: {
    id: {
      $in: [3, 6, 8],
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

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

Example response

{
  "data": [
    {
      "id": 6,
      "documentId": "ethwxjxtvuxl89jq720e38uk",
      "name": "test6",
      // ...
    },
    {
      "id": 8,
      "documentId": "cf07g1dbusqr8mzmlbqvlegx",
      "name": "test8",
      // ...
    },
  ],
  "meta": {
    // ...
  }
}

复杂过滤

¥Complex filtering

复杂过滤是使用高级方法组合多个过滤器，例如组合 $and 和 $or。这允许更灵活地请求准确所需的数据。

¥Complex filtering is combining multiple filters using advanced methods such as combining $and & $or. This allows for more flexibility to request exactly the data needed.

Find books with 2 possible dates and a specific author

GET /api/books?filters[$or][0][date][$eq]=2020-01-01&filters[$or][1][date][$eq]=2020-01-02&filters[author][name][$eq]=Kai%20doe

JavaScript 查询（使用 qs 库构建）：

¥JavaScript query (built with the qs library):

上面的查询 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({
  filters: {
    $or: [
      {
        date: {
          $eq: '2020-01-01',
        },
      },
      {
        date: {
          $eq: '2020-01-02',
        },
      },
    ],
    author: {
      name: {
        $eq: 'Kai doe',
      },
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

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

Example response

{
  "data": [
    {
      "id": 1,
      "documentId": "rxngxzclq0zdaqtvz67hj38d",
      "name": "test1",
      "date": "2020-01-01",
      // ...
    },
    {
      "id": 2,
      "documentId": "kjkhff4e269a50b4vi16stst",
      "name": "test2",
      "date": "2020-01-02",
      // ...
    }
  ],
  "meta": {
    // ...
  }
}

深度过滤

¥Deep filtering

深度过滤是对关系的字段进行过滤。

¥Deep filtering is filtering on a relation's fields.

✋ 提醒

• 使用深层过滤器查询 API 可能会导致性能问题。如果你的深度过滤查询之一太慢，我们建议使用查询的优化版本构建自定义路由。

  ¥Querying your API with deep filters may cause performance issues. If one of your deep filtering queries is too slow, we recommend building a custom route with an optimized version of the query.

• 深度过滤不适用于某些多态关系（例如媒体字段），但它适用于动态区域。

  ¥Deep filtering isn't available for some polymorphic relations such as media fields, but it works on dynamic zones.

✏️ 注意

• 默认情况下不填充关系、媒体字段、组件和动态区域。使用 populate 参数填充这些数据结构（参见 populate 文档）

  ¥Relations, media fields, components, and dynamic zones are not populated by default. Use the populate parameter to populate these data structures (see populate documentation)

• 无法过滤动态区域或媒体字段。

  ¥It is not possible to filter on dynamic zones or media fields.

Find restaurants owned by a chef who belongs to a 5-star restaurant

GET /api/restaurants?filters[chef][restaurants][stars][$eq]=5

JavaScript 查询（使用 qs 库构建）：

¥JavaScript query (built with the qs library):

上面的查询 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({
  filters: {
    chef: {
      restaurants: {
        stars: {
          $eq: 5,
        },
      },
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

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

Example response

{
  "data": [
    {
      "id": 1,
      "documentId": "cvsz61qg33rtyv1qljb1nrtg",
      "name": "GORDON RAMSAY STEAK",
      "stars": 5
      // ...
    },
    {
      "id": 2,
      "documentId": "uh17h7ibw0g8thit6ivi71d8",
      "name": "GORDON RAMSAY BURGER",
      "stars": 5
      // ...
    }
  ],
  "meta": {
    // ...
  }
}

语言环境

¥Locale

☑️ Prerequisites

• 应安装 国际化 (i18n) 功能。

  ¥The Internationalization (i18n) feature should be installed.

• 应为内容类型启用本地化。

  ¥Localization should be enabled for the content-type.

locale API 参数可用于处理特定语言环境的条目（参见 国际化文档）。

¥The locale API parameter can be used to work with entries from a specific locale (see Internationalization documentation).

状态

¥Status

☑️ Prerequisites

应启用 起草并发布 功能。

¥The Draft & Publish feature should be enabled.

查询可以接受 status 参数来明确定义要填充哪些字段，语法选项示例如下。

¥Queries can accept a status parameter to fetch documents based on their status:

• published：仅返回文档的已发布版本（默认）

  ¥published: returns only the published version of documents (default)

• draft：仅返回文档的草稿版本

  ¥draft: returns only the draft version of documents

💡 提示

在响应数据中，publishedAt 字段对于草稿为 null。

¥In the response data, the publishedAt field is null for drafts.

✏️ 注意

由于默认返回已发布的版本，因此不传递状态参数相当于传递 status=published。

¥Since published versions are returned by default, passing no status parameter is equivalent to passing status=published.

Get draft versions of restaurants

GET /api/articles?status=draft

JavaScript 查询（使用 qs 库构建）：

¥JavaScript query (built with the qs library):

上面的查询 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({
  status: 'draft',
}, {
  encodeValuesOnly: true, // prettify URL
});

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

Example response

{
  "data": [
    // …
    {
      "id": 5,
      "documentId": "znrlzntu9ei5onjvwfaalu2v",
      "Name": "Biscotte Restaurant",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "This is the draft version."
            }
          ]
        }
      ],
      "createdAt": "2024-03-06T13:43:30.172Z",
      "updatedAt": "2024-03-06T21:38:46.353Z",
      "publishedAt": null,
      "locale": "en"
    },
    // …
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 4
    }
  }
}