我们提供了一系列内置的请求参数,在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【查询银行客户信息列表】原始返回:
1)现在希望按照分页的方式获取数据,每页返回5条数据,并且每条数据中只包含zzhm(证件号码)、khmc(客户名称)、yddh1(电话)这三个字段,同时按照nl(年龄)来正序排序。因此调用时添加如图所示的请求参数:
调用返回结果为:
其中total是查询的数据总量,timeCost是本次请求的耗时,next_page_token是分页下一页页码。
2)现在希望按照jysp(教育水平)字段对客户的gz(工资)进行求平均值的聚合计算,再从小到大排序。因此在调用时添加如图所示的参数:
调用返回结果为:
特殊参数的key为系统保留字,因此在API参数命名时应尽量避免与上述参数名重合,后续也会在设置参数时增加校验避免此类问题。