同个API在不同使用的场景中,默认的返回结构不一定能够满足调用者实际的需求,因此我们支持通过配置过滤器的方式,使用户可以对API返回的原始结构进行灵活的转换,减少用户API对接及二次开发的成本。本文为您介绍如何使用API结果过滤器。
使用方式
正确配置过滤器并生效后,会对返回结果自动进行格式转换
结果示例
某个API原始返回结构如下
参数 | 说明 |
code | 返回状态码 SUCCESS/ERROR。 |
data | 返回的数据,根据数据源类型不同结构也可能有所不同,一般为ArrayList或者jsonObject结构。 |
traceId | 本次调用追踪的唯一ID |
message | 当code为ERROR会在message里返回错误原因 |
若API使用者希望去掉code、traceId等字段的封装只返回其中data的部分。
当正确配置过滤器后,返回结构如下:
可以看到返回结果中只剩下了data字段里的内容,无需用户再手动转换。
两种配置方式介绍
第一种:API开发过程配置过滤器
在API开发过程中配置过滤器,配置完成后对所有调用都会生效。
使用方式
在API创建/编辑过程中,第三步API配置及测试页面,点击返回内容左上方过滤器按钮启用过滤器。
过滤器有两种设置方式:
格式处理:使用指定的方式对返回结果进行处理,分别是过滤code字段、过滤message字段、过滤traceId字段以及仅返回data内容,支持多选。
自定义逻辑:使用自定义脚本的方式,对整个返回数据的结构进行转换。目前支持js函数,后续会开放对更多种脚本语言的支持。 自定义逻辑的js函数脚本示例:
function filter(response) { // 获取返回结果data中第一组数据 var data = response.data[0]; // 拼接证件号码和客户名称后返回结果 return data.zzhm + " : " + data.khmc; }
使用上述脚本执行转换的结果:
设置完成后过滤器生效,关闭过滤器按钮则失效。
第二种:已获授权API配置过滤器
调用者对于获得授权的API,可以再单独设置一个过滤器,此过滤器只有在当前获得授权的应用调用API时才会失效,不会影响API本身的返回结构,也不会影响其他的应用对该API调用。
如果一个获得授权的API已经在开发过程中开启了过滤器,那么再开启应用授权过滤器后,两个过滤器会同步生效:应用授权过滤器会对API由过滤器转换后的结果,按照设置的方式进行再次过滤,最终返回给调用方。
使用方式
在已获授权API列表页,找到对应获得授权的API,点击右侧操作列中的测试,进入已获授权API测试页面。
在已获授权API测试页面,点击打开过滤器按钮,便可配置过滤器,配置的方法和API开发过程的过滤器相同。