过滤器、区域设置和发布状态 Filters, Locale, and Publication State

使用 Strapi 的 REST API 来过滤请求的结果。

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

如果在内容类型上启用了国际化 (i18n) 插件，则可以按语言环境进行过滤。
如果启用了草稿和发布，则可以根据“实时”或“预览”状态进行过滤。

Strapi 利用 qs 库解析嵌套对象的能力来创建更复杂的查询。

直接使用 qs 生成复杂查询，而不是手动创建。本文档中的示例展示了如何使用 qs。

如果您更喜欢使用我们的在线工具，而不是在您的机器上使用 qs 生成查询，您也可以使用交互式查询生成器。

Filtering

查询可以接受 filters 参数，语法如下：

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

可以使用以下运算符：

运算符	说明
`$eq`	等于
`$eqi`	等于（不区分大小写）
`$ne`	不等于
`$nei`	不等于（不区分大小写）
`$lt`	小于
`$lte`	小于或等于
`$gt`	大于
`$gte`	大于或等于
`$in`	包含在数组中
`$notIn`	不包含在数组中
`$contains`	包含
`$notContains`	不包含
`$containsi`	包含（不区分大小写）
`$notContainsi`	不包含（不区分大小写）
`$null`	为 null
`$notNull`	不为 null
`$between`	介于
`$startsWith`	以...开头
`$startsWithi`	以...开头（不区分大小写）
`$endsWith`	以...结尾
`$endsWithi`	以...结尾（不区分大小写）
`$or`	以“或”表达式连接过滤器
`$and`	以“与”表达式连接过滤器
`$not`	以“非”表达式连接过滤器

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

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

您可以使用 $eq 过滤运算符来查找精确匹配项。

查找名字为“John”的用户

bash

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

Example response

json

[
  {
    "id": 1,
    "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"
  }
]

const qs = require('qs')
const query = qs.stringify({
  filters: {
    username: {
      $eq: 'John',
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
})

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

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

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

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

bash

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

示例响应

json

{
  "data": [
    {
      "id": 3,
      "attributes": {
        "name": "test3"
        // ...
      }
    },
    {
      "id": 6,
      "attributes": {
        "name": "test6"
        // ...
      }
    },
    {
      "id": 8,
      "attributes": {
        "name": "test8"
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}

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

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

复杂过滤

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

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

bash

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

Example response

json

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

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}`)

深度过滤

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

使用深度过滤器查询 API 可能会导致性能问题。如果您的某个深度过滤查询太慢，我们建议您使用优化版本的查询构建自定义路由。
深度过滤不适用于多态关系（例如：动态区域和媒体字段）。

默认情况下不填充关系、媒体字段、组件和动态区域。使用 populate 参数填充这些数据结构（请参阅 populate 文档)
无法对动态区域或媒体字段进行过滤。

查找属于五星级餐厅的厨师所拥有的餐厅

bash

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

示例响应

json

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

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

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

区域设置

应安装国际化 (i18n) 插件。
应为内容类型启用本地化。

locale API 参数可用于从特定区域设置获取条目（请参阅 i18n 插件文档）。

发布状态

应启用草稿和发布功能。

查询可以接受 publicationState 参数，以根据发布状态获取条目：

live：仅返回已发布的条目（默认）
preview：返回草稿条目和已发布的条目

et both published and draft articles

bash

GET /api/articles?publicationState=preview

Example response

json

{
  "data": [
    {
      "id": 1,
      "attributes": {
        "title": "This a Draft",
        "publishedAt": null
        // ...
      }
    },
    {
      "id": 2,
      "attributes": {
        "title": "This is Live",
        "publishedAt": "2021-12-03T20:08:17.740Z"
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}

const qs = require('qs')
const query = qs.stringify({
  publicationState: 'preview',
}, {
  encodeValuesOnly: true, // prettify URL
})

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

若要仅检索草稿条目，请结合“预览”发布状态和“publishedAt”字段： GET /api/articles?publicationState=preview&filters[publishedAt][$null]=true

const qs = require('qs')
const query = qs.stringify({
  publicationState: 'preview',
  filters: {
    publishedAt: {
      $null: true,
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
})

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