Weegloo Docs - 通用查询参数

WEEGLOO 的列表查询端点(如 GET /spaces/{spaceId}/contents 这类返回集合的 GET)接受通用查询参数。通过这些参数,可以限制单页获取的数量、指定排序依据、一并获取关联资源、只选取所需字段、用条件收窄列表,以及跳转到下一页或上一页。

无论资源类型如何,这些参数的行为方式都相同。各资源的单独参考页只单独说明该资源特有的条件,而本页所讲的通用参数则引用本页。

参数

参数	类型	说明
`limit`	integer	单页返回的项目数。1~100。默认值 15。
`skip`	integer	跳过的项目数。默认值 0。翻页时请使用游标(`next`、`prev`)而非 `skip`。请参阅下方的分页(游标)。
`next`	string	下一页游标。从上一次响应的 `links.next` 中获取。
`prev`	string	上一页游标。从上一次响应的 `links.prev` 中获取。
`order`	string	排序依据。用逗号连接多个依据可实现多级排序(例如 `sys.createdAt,sys.id`)。默认值 `sys.createdAt,sys.id`。以 `fields.` 开头的字段需包含 Locale(例如 `fields.title.en-US`)。
`include`	integer	一并展开获取关联资源的层级。0=默认,1=关联资源,2=嵌套关系,3=全部。默认值 0。
`select`	string	用逗号列出要在结果中包含的字段(例如 `sys.id,sys.createdAt`)或要排除的字段(例如 `-sys.id`)。同一请求中不要混用包含与排除。
`filter`	(条件)	用条件收窄列表。格式请参阅下方的过滤。

order、select 中使用的 sys 字段的种类,可在系统属性 (sys)中查看。

过滤

过滤条件不用 filter[] 包裹,而是作为查询参数直接发送。格式为 {字段}[{运算符}]={值},省略运算符时按 eq 解析。可用的全部运算符请参阅下方的运算符。

{字段}[{运算符}]={值}

例如,要只获取 name 以 保温杯 开头的项目,可发送 name[prefix]=保温杯。规则与注意事项如下。

不用 filter[] 包裹。 像 filter[name[prefix]]=保温杯 这样包裹则不起作用。
多个条件以 AND 组合。 只会保留全部满足的项目,只需满足多个条件之一的 OR 搜索不受支持。若要让某个字段匹配多个值中的任意一个,请使用 in。
fields. 条件需包含 Locale。 例如,fields.file.ko-KR.mimeGroups=Image 在 Media 列表中只保留图片文件,而 sys.createdAt[gte]=2026-06-01T00:00:00Z 只保留在该时刻之后创建的项目。
用 fields. 条件对 Content 列表进行过滤或排序时,还需指定 Content Type。 必须同时发送 sys.contentType.sys.id(仅限 /contents 列表),仅凭 contentType= 无法替代。详情请参阅 Content 参考。

运算符

运算符	含义	值
`eq`	等于。省略运算符时按此解析。	单个值
`ne`	不等于	单个值
`in`	等于所列值中的任意一个	值列表
`nin`	与所列任意值都不相等	值列表
`all`	数组字段包含所列的全部值	值列表
`exists`	值是否存在	`true` 或 `false`
`prefix`	前缀匹配	单个值
`gt` / `gte`	大于 / 大于等于	单个值
`lt` / `lte`	小于 / 小于等于	单个值
`regex`	正则表达式匹配。仅限高级搜索(见下方高级搜索)。	正则表达式
`near`	Location 字段在距某一点一定距离之内。仅限高级搜索。	`纬度,经度,距离`(距离单位为千米)
`within`	Location 字段在多边形之内。仅限高级搜索。	将三对及以上 `纬度,经度` 坐标依次连接而成的值

RichText、Json 字段不属于搜索对象,无法用于过滤条件。

高级搜索(Advanced Search)

regex、near、within 运算符以及文本全文搜索仅在高级搜索下生效。高级搜索通过在列表查询请求中附加请求头 X-Weegloo-Advanced-Search: true 来开启,响应中也会带回同一请求头。

全文搜索
(LongText)使用 eq 时,不再要求完全相等,而是通过部分、近似匹配找出包含该值的项目。若未开启高级搜索,或所用套餐不提供高级搜索,则同样的 eq 按精确匹配执行。
Location 搜索:near(半径)、within(多边形)只用于 Location 字段,且仅在高级搜索下生效。
在无法使用高级搜索的请求中发送 regex、near、within 时,将不被接受。

分页(游标)

列表响应的正文中包含一个 links 对象,其中含有 next、prev。links.next 是跳转到下一页的完整路径。

/v1/spaces/HnQ32YiH/contents?limit=15&next=<游标>

获取下一页有两种方法。可以直接调用 links.next 路径,或从 links.next 中取出 next 游标值,作为下一次请求的 next 参数传入。若没有 links.next,则表示已是最后一页。上一页用 links.prev 以相同方式跳转。

翻页时请勿通过增大 skip 来使用。若在列表之间新增或删除了项目,skip 的位置会发生错位,可能导致项目遗漏或重复。游标(next、prev)则不存在此类问题。

以下是列表响应的结构示例。包装器的 sys.type 为 TotalPageResponse,items 中是项目数组,links 中是跳转路径。

{
  "sys": { "type": "TotalPageResponse" },
  "limit": 15,
  "totalCount": 42,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
        "type": "Content",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "createdAt": "2026-06-18T09:51:14.597Z",
        "updatedAt": "2026-06-18T09:51:44.128Z",
        "version": 2,
        "status": "Published"
      }
    }
  ],
  "links": {
    "self": "/v1/spaces/HnQ32YiH/contents?limit=15",
    "next": "/v1/spaces/HnQ32YiH/contents?limit=15&next=Q3Vyc29yVmFsdWU"
  }
}

totalCount 是符合条件的全部项目数,limit 是本次响应所采用的单页大小。items 中只装载与该页对应的项目。

系统属性 (sys):order、select 中使用的 sys 字段。
约定
、JSON Patch、并发。

参数

过滤

运算符

高级搜索(Advanced Search)

分页(游标)

相关文档