Skip to main content

REST API：过滤器

🌐 REST API: Filters

Page summary:

REST API 筛选功能允许使用 $eq、$contains 和 $between 等操作符对查询结果进行筛选，并支持使用 $and、$or 和 $not 进行复杂筛选，以及跨相关内容进行深度筛选。

🌐 The REST API filters feature allows filtering query results using operators like $eq, $contains, and $between, with support for complex filtering using $and, $or, and $not, as well as deep filtering across related content.

REST API 提供了使用其 "获取条目" 方法筛选结果的能力。
使用可选的 Strapi 功能可以提供更多筛选条件：

  • 如果在某个内容类型上启用了国际化 (i18n) 插件，就可以按语言环境进行过滤。
  • 如果启用了 Draft & Publish，可以根据 published（默认）或 draft 状态进行筛选。
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.

查询可以接受带有以下语法的 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将筛选器连接为“或”表达式
$and将筛选器连接为“与”表达式
$not将筛选器连接为“非”表达式

当 filters 对象中传入多个字段时，它们会与 $and 隐式组合（例如，GET /api/restaurants?filters[stars][$gte]=3&filters[open][$eq]=true 只返回开放且评分至少为 3 星的餐厅）。

🌐 When several fields are passed in the filters object, they are implicitly combined with $and (e.g. GET /api/restaurants?filters[stars][$gte]=3&filters[open][$eq]=true only returns restaurants that are open and have at least 3 stars).

Tip

$and、$or 和 $not 运算符可以互相嵌套。

Caution

默认情况下，滤镜只能用于由内容类型构建器和 CLI 生成的 find 端点。

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

示例：查找名字为 'John' 的用户​

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

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

查找名字为 'John' 的用户

使用 $eq 过滤操作符查找完全匹配。

terminal
curl 'http://localhost:1337/api/users?filters[username][$eq]=John' \
  -H 'Authorization: Bearer <token>'
200 OK
{
  "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

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

查找ID为3、6、8的多家餐厅

使用 $in 过滤运算符和一个值数组来查找多个精确值。

terminal
curl 'http://localhost:1337/api/restaurants?filters[id][$in][0]=3&filters[id][$in][1]=6&filters[id][$in][2]=8' \
  -H 'Authorization: Bearer <token>'
200 OK
{
  "data": [
    {
      "id": 3,
      "documentId": "ethwxjxtvuxl89jq720e38uk",
      "name": "test3"
    },
    {
      "id": 6,
      "documentId": "ethwxjxtvuxl89jq720e38uk",
      "name": "test6"
    },
    {
      "id": 8,
      "documentId": "cf07g1dbusqr8mzmlbqvlegx",
      "name": "test8"
    }
  ],
  "meta": {}
}

复杂筛选​

🌐 Complex filtering

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

查找有两个可能日期和特定作者的书籍

结合 $and 和 $or 操作符进行复杂过滤。

terminal
curl 'http://localhost:1337/api/books?filters[$and][0][$or][0][date][$eq]=2020-01-01&filters[$and][0][$or][1][date][$eq]=2020-01-02&filters[$and][1][author][name][$eq]=Kai%20doe' \
  -H 'Authorization: Bearer <token>'
200 OK
{
  "data": [
    {
      "id": 1,
      "documentId": "rxngxzclq0zdaqtvz67hj38d",
      "name": "test1",
      "date": "2020-01-01"
    },
    {
      "id": 2,
      "documentId": "kjkhff4e269a50b4vi16stst",
      "name": "test2",
      "date": "2020-01-02"
    }
  ],
  "meta": {}
}
Note

上述响应仅包含书籍自身的属性。通过 $and 过滤器遍历的 author 关系不会被返回，除非通过 populate 参数 请求，例如通过在请求中添加 &populate=author。

🌐 The response above only contains a book's own attributes. The author relation traversed by the $and filter is not returned unless requested through the populate parameter, for example by adding &populate=author to the request.

深度过滤​

🌐 Deep filtering

Note
  • 关系、媒体字段、组件和动态区域默认情况下未填充。使用 populate 参数来填充这些内容结构（参见 populate 文档`)
  • 你可以过滤填充的内容，也可以过滤嵌套关系，但不能对多态内容结构（例如媒体字段和动态区域）使用过滤器。
Caution

使用深层过滤器查询你的 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 with the various APIs

有关如何使用各种 API 进行深度过滤的示例，请参阅 this blog article。

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

寻找由属于五星级餐厅的厨师拥有的餐厅

使用深度过滤来过滤关系的字段。

terminal
curl 'http://localhost:1337/api/restaurants?filters[chef][restaurants][stars][$eq]=5' \
  -H 'Authorization: Bearer <token>'
200 OK
{
  "data": [
    {
      "id": 1,
      "documentId": "cvsz61qg33rtyv1qljb1nrtg",
      "name": "GORDON RAMSAY STEAK",
      "stars": 5
    },
    {
      "id": 2,
      "documentId": "uh17h7ibw0g8thit6ivi71d8",
      "name": "GORDON RAMSAY BURGER",
      "stars": 5
    }
  ],
  "meta": {}
}
Note

上面的响应反映了默认的 REST 输出，它不包括过滤器所遍历的关系。添加一个 populate 参数，例如 &populate[chef][populate][restaurants]=true，以同时返回过滤器中引用的 chef.restaurants 关系。

🌐 The response above mirrors the default REST output, which excludes the relations traversed by the filter. Add a populate parameter such as &populate[chef][populate][restaurants]=true to also return the chef.restaurants relation referenced in the filter.

On this page