API调用特殊参数

我们提供了一系列内置的请求参数,在API的调用过程中,用户可以通过这些特殊的请求参数,在数据API原有的查询逻辑上添加聚合、排序、过滤返回字段等等额外的逻辑,或者在返回结果里透出额外的信息字段等等。

使用场景

交管云控平台使用数据资源平台统一服务作为数据服务发布、管理的平台,交通行业线的API开发者在为API服务编写查询SQL时,会选择使用比较基础的语法,例如只包含select和where条件做一些简单的查询逻辑。等到API开发完成上线后,调用方再根据真实的需求,选择性地使用特殊参数在简单查询的基础上进一步实现排序、聚合的逻辑,使同一个服务可以适配至不同业务场景中,减少了开发者的工作量,增加API使用的灵活性。

使用方式

API调用时在query参数里添加指定的key和value,无需提前在API中声明。

参数列表

参数名

说明

示例值

return_fields

指定返回字段,多个时逗号分隔。

​aa,bb,ccc

aggregation

聚合计算字段,格式为:“聚合字段,运算方式,聚合后字段名”,多组聚合函数时分号分隔。

gz,avg,工资;csrq,min,最早出生

group_by

分组字段,多个时逗号分隔。

xb,jj

order_by

排序字段,默认为顺序,逆序加desc,多个时逗号分隔。

aa desc,bb

page_size

分页大小。

10

page_token

分页页码,同时返回下一页页码。

1

fetch_all

指定返回查询数据总量。

true

return_lower_case

返回数据转小写。

true

说明
  • 最终的分页结果以page_size、page_token为准。

  • 如果当前接口已经实现分页(比如SQL中增加了limit、offset等),请求时附带这组page参数会在原先分页结果的基础上实现二次分页。

  • 如果无需二次分页,仅想查看当前查询返回的数据量,可以使用fetch_all参数。

示例

API【查询银行客户信息列表】原始返回:

image.png

1)现在希望按照分页的方式获取数据,每页返回5条数据,并且每条数据中只包含zzhm(证件号码)、khmc(客户名称)、yddh1(电话)这三个字段,同时按照nl(年龄)来正序排序。因此调用时添加如图所示的请求参数:

image.png

调用返回结果为:

image.png

其中total是查询的数据总量,timeCost是本次请求的耗时,next_page_token是分页下一页页码。

2)现在希望按照jysp(教育水平)字段对客户的gz(工资)进行求平均值的聚合计算,再从小到大排序。因此在调用时添加如图所示的参数:

image.png

调用返回结果为:

image.png

说明

特殊参数的key为系统保留字,因此在API参数命名时应尽量避免与上述参数名重合,后续也会在设置参数时增加校验避免此类问题。