如何设置查询参数
  • 04 Nov 2023
  • 1 分钟阅读
  • 贡献者

如何设置查询参数


Article Summary

根据 API 文档,学习在 HTTP 连接器函数中使用查询参数的基本方法。

通过查询参数,您可以完善和定制连接器函数的结果。使用参数可以进行排序、过滤、设置限制、偏移索引等操作。本文使用的是 Tulip Table API 参数,但其他 API 可能有不同的参数要求。请务必查看文档,确保使用正确的语法和规格。

如何在文档中查找查询参数

要查找请求的可用查询参数,请浏览 API 文档。如果使用的是郁金香表 API,可以在以下网址找到文档:your-instance.tulip.co/apiDocs。 选择要使用的请求,然后向下滚动到 "参数"选项卡。

Parameters in API Docs.png

每个方法都有自己的参数集,但并非每个请求都有相关参数。请务必事先注意文档中的可用参数。

查询参数语法

查询参数语法依赖于查询字符串格式。这种格式为指定参数赋值,查询字符串本身就是 URL 的一部分。

在连接器功能编辑器中,单击 "添加参数 "创建新的查询参数。

Query Parameters - Add Parameter.png

查询参数由两部分组成:。键是参数的名称,值是为结果设置参数的信息。

查询参数语法使用 Dot Notation,该语法指定了参数的确切类型。确保书写大小写符合其他系统的 API 标准。

将常用参数应用于连接器函数

要为连接器函数设置参数,首先要在 API 文档中确定要使用的参数。每个参数都有不同的要求,让我们来看看它们是什么样的。

:::(Info) (注)为了保持连续性,我们将在下面的每个示例中使用相同的请求 API Call。这是通过郁金香表 API 获取郁金香表记录列表的 GET 请求。您使用的其他 API 会有不同的参数规范,请务必查看 API 文档要求:

限制

限制为返回结果设置了指定的上限。请注意,有些限制有默认设置,因此请务必查看 API 文档以了解初始值。

示例我们希望连接器函数运行时获得的记录不超过 70 条。幸运的是,此请求中限制的默认值是 10,最高值是 100。查询参数的语法如下:

Query Parameters - Limits.png

过滤器

过滤器根据参数的给定信息对结果进行分离和细化。

过滤器由三部分组成,必须写入单独的参数中:

  • 字段 - 表中列的名称
  • 函数类型 - 比较函数类型
  • 参数 - 比较结果的值

每个过滤器都有 3 个部分,每个完整的过滤器都是一个对象。使用点符号书写每个键,指定参数类型("筛选器")、筛选器编号(0 到 n)以及筛选器的部分("字段"、"函数类型 "或 "参数")。过滤器的三个部分都必须有一个参数。

示例我们要确保连接器函数的结果只显示特定字段(eubmc_value)中等于函数指定输入值(消耗值)的值。由于这是函数参数中的第一个过滤器,过滤器编号为 0,这意味着该过滤器的每个键都将以 "filter.0 "开头。该过滤器的语法如下:

Query Parameters - Filters.png

排序

排序结果根据参数信息对视图进行优先排序。排序结果决定了哪些结果会被纳入聚合。您可以使用多个排序功能,但选项的顺序决定了排序的优先级。

排序功能包括两个部分:

  • sortBy - 对结果进行排序的字段
  • sortDir - 排序方向,升序 (asc) 或降序 (desc)

每个排序功能都有 3 个部分。使用点符号写入每个键,指定参数类型("sortOptions")、排序编号(0 到 n)和排序参数("sortBy "或 "sortDir")。排序功能的所有三个部分都必须有一个参数才能起作用。

示例我们希望连接器函数的结果按最近更新的字段升序排序。因为这是第一个排序功能,所以排序编号是 0,这意味着该排序的两个键都将以 "sortOptions.0 "开头。对于 sortBy 关键字,其值是从 API 文档中导出的特殊值('_updatedAt'),用于对更新字段进行排序。这些参数的语法如下:

Query Parameters - Sorting.png

偏移量

Offsets 决定返回结果的起始索引。该参数用于分页,而不是由排序参数决定的记录顺序。参数值必须是大于或等于 0 的整数。

示例我们只想查看第 5 位以后的记录,这样就看不到前 5 位的结果了。查询参数的语法如下:

Query Parameters - Offset.png

过滤器聚合器

过滤器聚合器决定了如何组合参数中的过滤器。可供选择的两个值是 "任意 "和 "全部"。全部 "值表示所有筛选器都必须有记录才能将记录包含在结果中。任意 "值表示至少有一个筛选器必须匹配一条记录,结果中才会包含该记录。默认值为 "全部",与是否设置参数无关。

示例我们在查询参数中设置了一系列筛选器,但我们只需要其中一个筛选器为真,记录就会与我们的请求相匹配。查询参数的语法如下:

Query Parameter - Filter Aggregators.png

进一步阅读


本文对您有帮助吗?