文档

API结果过滤器

更新时间:

同个API在不同使用的场景中,默认的返回结构不一定能够满足调用者实际的需求,因此我们支持通过配置过滤器的方式,使用户可以对API返回的原始结构进行灵活的转换,减少用户API对接及二次开发的成本。本文为您介绍如何使用API结果过滤器。

使用方式

正确配置过滤器并生效后,会对返回结果自动进行格式转换

结果示例

某个API原始返回结构如下

image

参数

说明

code

返回状态码 SUCCESS/ERROR。

data

返回的数据,根据数据源类型不同结构也可能有所不同,一般为ArrayList或者jsonObject结构。

traceId

本次调用追踪的唯一ID

message

当code为ERROR会在message里返回错误原因

若API使用者希望去掉code、traceId等字段的封装只返回其中data的部分。

当正确配置过滤器后,返回结构如下:

image

可以看到返回结果中只剩下了data字段里的内容,无需用户再手动转换。

两种配置方式介绍

第一种:API开发过程配置过滤器

在API开发过程中配置过滤器,配置完成后对所有调用都会生效。

使用方式

API创建/编辑过程中,第三步API配置及测试页面,点击返回内容左上方过滤器按钮启用过滤器。

Image 6

过滤器有两种设置方式:

  • 格式处理:使用指定的方式对返回结果进行处理,分别是过滤code字段、过滤message字段、过滤traceId字段以及仅返回data内容,支持多选。

  • 自定义逻辑:使用自定义脚本的方式,对整个返回数据的结构进行转换。目前支持js函数,后续会开放对更多种脚本语言的支持。 自定义逻辑的js函数脚本示例:

    function filter(response) {
      // 获取返回结果data中第一组数据
      var data = response.data[0];
      // 拼接证件号码和客户名称后返回结果
      return data.zzhm + " : " + data.khmc;
    }

    使用上述脚本执行转换的结果:

    image

设置完成后过滤器生效,关闭过滤器按钮则失效。

第二种:已获授权API配置过滤器

调用者对于获得授权的API,可以再单独设置一个过滤器,此过滤器只有在当前获得授权的应用调用API时才会失效,不会影响API本身的返回结构,也不会影响其他的应用对该API调用。

说明

如果一个获得授权的API已经在开发过程中开启了过滤器,那么再开启应用授权过滤器后,两个过滤器会同步生效:应用授权过滤器会对API由过滤器转换后的结果,按照设置的方式进行再次过滤,最终返回给调用方。

使用方式

  1. 已获授权API列表页,找到对应获得授权的API,点击右侧操作列中的测试,进入已获授权API测试页面。

    image

  2. 在已获授权API测试页面,点击打开过滤器按钮,便可配置过滤器,配置的方法和API开发过程的过滤器相同。

    image