过滤规范

POB API 对过滤和排序都做了规范约束，让我们来了解下规范是如何定义的吧。

POB SDK 使用一种称为 NQL 的查询语言来允许过滤 API 结果。您可以使用匹配、大于/小于或否定，以及与和/或结合来过滤任何字段或包含的字段。NQL 还不支持“like”或部分匹配。

在最简单的情况下，过滤的工作原理与 GMail、GitHub 或 Slack 相同——你提供一个字段和一个值，用冒号分隔。

如何指定过滤字段#

当前仅支持 GET 请求，我们在查询参数中指定过滤字段，比如：

GET /api/v1/workflow?filter=namespace:'MetaJam',namespace:'xxx'

没错，细心的您会发现，我们通过 filter 来指定过滤条件。过滤字段可以是多个，我们用 , 表示或。更多的可以了解过滤字段的语法。

语法参考#

过滤表达式#

过滤器表达式是一个字符串，它提供了属性、操作符和值，形式如下: 属性:操作符值:

• 属性 - 表示要筛选的字段的路径
• : - 分隔符在属性和操作符-值表达式之间
• 操作符 (可选) - 如何比较值 (: 可以简单的理解为 =)
• 值 - 要匹配的值

属性#

匹配项: [a-zA-Z_][a-zA-Z0-9_.]

• 只能包含字母数字字符和 _
• 不能包含空格
• 必须以字母开头
• 支持 . 分隔路径，例如authors.slug 或 posts.count
• 总是小写，但接受并转换为大写

值#

可以是以下其中之一

• null
• true
• false
• 数字 (整数)
• 文字
  • 任何符合以下规则的字符串:
  • 不能以 - 开头，但可以包含它
  • 不能包含这些符号: '"+,()><=[] 除非它们被转义
  • 不能包含空格
• 字符串
  • '这里是字符串'，这里是字符串表示除单引号或者双引号以外的任意字符
  • 如果是单引号或者双引号，则必须要转义
  • 不能包含空格
  • 一个字符串可以包含一个可以被 new Date() 解析的任何格式的日期
• 相对日期
  • 使用模式： now-30d
  • 必须以 now 开头
  • 可以使用 - 或者 +
  • 可以使用任何整数作为周期的大小
  • 支持下面这些周期: d, w, M, y, h, m, s

操作符#

• - - 否
• > - 大于
• >= - 大于等于
• < - 小于
• <= - 小于等于
• ~= - 包含
• ~^ - 以某某开头
• ~$ - 以某某结束
• [ value, value, … ] - in 操作，用于或查询，表示任意一个在其中即可, 可以以 - 取反操作，表示不在其中

组合#

• + - 表示与
• , - 表示或
• ( 过滤表达式 ) - 用于提升优先级

Strings vs Literals#

大多数时候，在 POB API 中构建过滤器时，不需要在字符串周围加上引号。如果您基于 slug 进行过滤，则 slug 始终与文字兼容。但是，在某些情况下，您可能需要使用包含过滤器语法中使用的其他字符之一的字符串，例如日期和时间包含 :，对这些使用单引号。