REST API：过滤器

🌐 REST API: Filters

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

你可以使用 $eq 筛选操作符来查找完全匹配项。

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

查找名字为 'John' 的用户

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

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

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

示例响应

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

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

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

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

const qs = require('qs');
const query = qs.stringify({
  filters: {
    id: {
      $in: [3, 6, 8],
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

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

示例响应

{
  "data": [
    {
      "id": 3,
      "documentId": "ethwxjxtvuxl89jq720e38uk",
      "name": "test3",
      // ...
    },
    {
      "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.

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

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

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

const qs = require('qs');
const query = qs.stringify({
  filters: {
    $and: [
      {
        $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}`);

示例响应

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

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

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

const qs = require('qs');
const query = qs.stringify({
  filters: {
    chef: {
      restaurants: {
        stars: {
          $eq: 5,
        },
      },
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

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

示例响应

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

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

示例：查找 ID 为 3、6、8 的多家餐厅​

复杂筛选​

深度过滤​

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

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

复杂筛选

深度过滤