API开发功能依赖数据源登记、API集合、API列表和应用管理这几个模块,以下内容讲解中,将按照对API开发的顺序对产品功能模块进行依次说明。

服务概览

服务概览页面,支持查看今日、近7日和近30日的API的调用情况(若开启了细粒度监控模式,还可以通过时间组件筛选90天内其中任意30天的监控数据),包括累计已发布的API数量、累计调用API的数量、累计调用API的次数、累计请求返回量数值指标以及累计调用API的成功次数,通过图表可了解在对应时间范围内的API调用的Top10、应用调用Top10、API调用次数趋势图、API返回量趋势图以及服务的调用比率等。

以下以细粒度监控下的指标进行说明:

新建和注册API - 图1

参数信息 说明
累计已发布API数量 累计处于已发布状态的API数量。
累计调用API数量 累计处于已发布状态的API中,被调用的API数量。
累计调用API次数 累计处于发布状态的API中,被调用的API次数。
累计调用API成功次数 累计处于发布状态的API中,被调用的API成功次数。
累计创建应用数量 累计已经创建的应用数量。
累计请求返回量 API发送请求累计返回的数据量。
API调用TOP10 发布的API中,被调用排名前10的API。
应用调用Top10 被线上API绑定的应用中,调用API排名前10的应用。
API调用失败率TOP10 发布的API中,被调用过程中失败率排名前10的API。
API调用平均耗时TOP10 发布的API中,被调用过程中平均耗时排名前10的API。
API调用次数趋势图 已发布的全部线上API,调用总次数和失败次数趋势图,可根据应用筛选查看。
API调用比率 调用API中成功和失败的比率。
API返回量趋势图 已发布的全部线上API,返回数据量的趋势图。
资源组请求趋势图 全部线上资源组,请求数量的趋势图,可根据资源组筛选查看。
数据服务错误类型分布 已发布的全部线上API,所返回的数据服务错误码分布情况,以便对API整体质量有宏观了解。

新建和注册API - 图2

数据概览页面还提供调用API列表未调用API列表功能。可在调用API列表中查看调用API中包含每个API的最近调用时间,如果最近调用时间比较久远,可以考虑将API进行下线操作。

还可以查看未调用API列表,若API创建成功,但未进行测试调用,可以考虑将API进行删除。

登记数据源

新建API,在将数据库表生成API创建之前,需要先登记数据源。单击数据源登记跳转至项目中心(新)页面完成数据源登记。

目前,在项目中心(新)的数据源登记过程中,支持MySQL、Oracle、GreenPlum、Vertica和ES等有源系统账号鉴权的功能,因此在数据服务使用这些数据源的时候需要注意是否已经开启了“源系统账号鉴权”。

针对该功能,数据服务支持通过在ops侧配置subSysActAuth.enable、useDsInfoIfUserNoActAuth.enable参数适配不同场景,具体如下:

1)subSysActAuth.enable设置为false:不接入源系统账号鉴权;
2)subSysActAuth.enable设置为true,useDsInfoIfUserNoActAuth.enable设置为false:接入源系统账号鉴权,提交任务的用户没有源系统账号则任务报错。(相当于彻底开启了源系统账号鉴权功能)
3)subSysActAuth.enable设置为true,useDsInfoIfUserNoActAuth.enable设置为true:接入源系统账号鉴权,提交任务的用户没有源系统账号则使用数据源登记的号。(相当于开启了源系统账号鉴权的同时使用数据源登记的账号密码作为兜底)

创建API集合

在创建API之前需要先创建API集合,一个API只能属于一个API集合,可以将具有相似功能的API放在同一个集合下,比如查询天气的API集合,那么可以将根据地理位置查询天气的API、根据名胜古迹查询天气的API、根据美食查询天气的API等均放在查询天气的API集合中,便于对同一类的API进行管理。

21 数据服务.png

API集合需要填写集合名称、集合Path和描述,其中集合Path是拼接API URL地址的一部分,以标识API归属于哪个集合。在API集合列表,可以通过创建人以及API集合名称筛选定位API集合,支持查看当前API集合下包含了哪些API。

新建API

登记数据源和创建API集合成功后,就可以对数据表生成API进行创建了。库表新建API一般包括三步:填写API基本信息、配置表和参数、测试API。

配置API基本信息

配置API信息页面:
新建和注册API - 图4

配置项 描述
API名称 创建的API名称。
API集合 API所属的集合。
API Path API的请求路径,也是构成API url地址的一部分。
协议 API调用的请求协议。
请求方式 API调用的请求方式,支持get和post。
返回类型 API调用的返回类型,支持json。
超时时间 API超时时间。
环境类型 默认为线上环境
描述 对API的描述。
API标签 可以针对API添加业务标签,用于快速识别API。
API协助管理者 可指定当前API的协助管理者,等同创建人,拥有对API的所有操作权限
数据结果缓存 若对响应时效有要求,可开启API数据结果缓存。
传输加密 目前仅默认支持SM2+AES的加密算法。
apiToken鉴权 若打开,可通过apiToken调用API,只需要在header中添加字段apiTOken、appKey和version即可,适用于报表、数据大屏等安全性要求不高的使用场景。
入参定义 对API调用中的请求参数绑定的入参参数的定义,支持普通入参和函数入参,函数入参中支持concat、substring等函数,即通过函数对请求参数进行二次处理。
开启传输加密后,具体的调用方式如下,更详细的传输加密说明可参阅 传输加密
1)header中需要传入encryptedAesKey、sm2PublicKey两个参数,encryptedAesKey指的是SM2公钥加密后的AES密钥,sm2PublicKey指的是应用详情页的SM2公钥;
2)加密后的数据使用cipherData来表示;
3)若为GET请求方式,调用数据放在Query中,为:URL地址?cipherData=密文;
4)若为POST请求方式,调用数据放在Body中,为: {"cipherData":"密文"}。

入参参数的配置:

入参参数的设置,是为了在第二步中设置请求参数时进行绑定,请求参数一定要绑定入参参数中的其中一个,建议在请求参数中用到几个入参,就创建几个入参,若有冗余的参数,有可能会导致调用API失败。
新建和注册API - 图5

参数信息 说明
参数名 入参参数的名称。
参数位置 若请求方式选择了GET,参数位置为QUERY,若请求方式选择了POST,参数位置为BODY。
参数类型 支持参数类型为整型、浮点型、字符串和布尔型,布尔型在数据服务。
是否必填 若勾选了是,在测试和调用API时必须填写调用值,若勾选了否,则须给定一个默认值,用于测试和调用时使用;在向导模式下,若未填写默认值,且在调用API时未传参,则系统将忽略该参数。
默认值 若勾选了是否必填的"否",此处需要给定默认值。
示例值 用于API调用者查看的示例值。
描述 对于该入参参数的描述。
函数入参的表达式 若选择了函数入参,则需要书写函数入参表达式,可以通过系统提供的函数,对入参进行二次处理,比如concat(a,b)表示将入参a和b进行拼接,a和b需要是已经创建成功的入参。
注意: 若在向导模式下,默认值是非必填,并且没有填写默认值,则在API调用时将忽略该参数的调用,实现参数的动态传递。

配置表和参数

配置完API基本信息之后,需要进行表和参数的配置,此处需要配置三块内容分别为选择表、选择返回和排序参数以及配置查询条件。

选择表如下图所示:
新建和注册API - 图6

配置项 描述
生成方式 选择API的生成方式,支持向导和脚本模式生成API。
数据源类型 选择数据源类型,可供选择的数据源根据数据服务的版本不同而不同。
数据源名称 选择在数据源登记模块登记的数据源名称。
数据表 选择数据源下的数据表。
注意: Hive数据源仅建议在BI场景或者QPS不高的数据产品场景中使用,并且建议对Hive API配置流控策略,防止下游调用方并发过高时对Impala集群稳定性造成影响。如果通过Hive数据源创建API时,需要将hive的数据同步到Impala,当前有两种途径可以将数据同步到impala:一种是创建hive表时,打开"impala同步"的开关,另一种是执行SQL语句"INVALIDATE METADATA table_name;"。
新建和注册API - 图7

配置返回和排序参数

如下图所示:
新建和注册API - 图8

配置项 描述
添加返回和排序参数 在选择返回和排序参数下,点击"添加",弹窗中展示表的所有字段,选择返回参数和排序参数。
1)返回参数:平台支持传入系统参数灵活指定返回列,若定义的返回参数有a,b,c,传入"system_return_column=a,b"可只返回a,b列。
2)排序参数:向导模式下支持传入"system_字段名_order"参数改变升降序,"=desc"表示降序,"=asc"表示升序,"=false"表示排序不生效;支持传入"system_order_param"参数改变排序顺序,比如"=a,b,c"表示重新按照a,b,c顺序进行排序。
返回参数后置处理 支持通过UDF对返回结果进行二次处理,可单独上传jar包或从udf studio产品中选择已创建好的函数。
UDF配置 返回参数后置处理开启后,可在此处选择UDF的配置方式,包括“选择UDF Studio中的函数”和“上传Jar包”。
如果选择UDF Studio中的函数,下拉列表中展示UDF 列表,对于有权限的函数可直接选择使用,对于无权限的函数可进入UDF市场进行申请。
后置返回参数 后置返回参数支持重新定义函数列表,便于API调用者了解真实的返回内容。

配置查询条件

如下图所示:
配置查询条件支持请求参数的多级嵌套,实现诸如(a or b) and c等逻辑,需要先选择最外层连接符。
新建和注册API - 图9

特殊说明:

对于请求参数中操作符的使用说明如下:

1. 除了in和between操作符外,都只关联一个参数的操作符,比如=,绑定方式如下:

2021-08-27-11-17-23.png

测试方式如下:

2021-08-27-11-17-39.png

2. 对于in和between操作符,参数之间用逗号进行分隔,绑定方式如下:

2021-08-27-11-17-51.png

测试方式如下:

2021-08-27-11-18-04.png

上图中,可以实现a between 1 and 2。同理,若在操作符中选择了in,则测试页面多个参数也使用逗号进行分隔,例如id in (1,2)。

此外,还可通过上传Jar包对返回参数的二次处理功能。

21 数据服务01.png

若对返回参数有二次处理的需求,平台支持上传Jar包或者从UDF Studio产品中选择函数对返回参数进行二次处理,可以将对返回参数的处理逻辑在Jar中完成,然后上传Jar包,填写类名,若Jar中对返回参数进行了修改,可添加真实的返回参数。

保存和测试

数据服务提供在线功能测试,便于测试API取数逻辑配置的正确性。在测试页面,左侧是请求参数和分页信息(默认分页页号为1,分页大小为200,最多返回3000条数据,HBase类型的数据源最多返回1W条数据),点击开始测试,右侧会有API的测试详情和返回内容等信息。
新建和注册API - 图15

点击查看错误状态码可以查看返回的错误码对应的错误原因,便于用户更好的定位失败的API的错误原因。
21 数据服务02.png

在返回内容中打印执行的SQL语句,便于问题定位。
新建和注册API - 图17

如果字段通过安全中心配置了脱敏,在创建Hive API时,可以选择个人账号执行,达到字段脱敏的目的。
新建和注册API - 图18

说明: 在调用API时,若在向导模式下,支持使用参数"use_total_num=1"返回API的总条数。

当前如果API是hive数据源类型支持使用个人账号执行此功能。如果数据字段配置了脱敏,创建hive API时,通过选择个人账号执行,以达到字段脱敏的目的。

发布API

测试成功的API便可以进行发布上线,只有发布的API才可以绑定应用,API才可以被调用。在API列表中,找到需要发布的API单击更多选择发布,只有测试成功的API才可以进行发布。

API绑定应用

将API发布之后,点击API的名称进入详情页,单击添加授权按钮,选择需要绑定的应用进行添。
新建和注册API - 图19

授权API应用

API调用者可以创建API应用,便于API的开发者将发布好的API绑定应用。

数据服务页面,打开应用管理功能详情页面,单击新建应用,在弹出的对话框中完成应用的创建。
新建和注册API - 图20

在API应用模块,点击查看授权或者应用名称,可以进入应用的详情页,在关联API处,可以看到当前应用被哪些API所绑定,可以对绑定的API进行测试,也可以解除绑定。同时,在详情页还能看到生成的应用的APPKey和APPSecert,在API的调用中,所需要的APPKey和APPSecert信息可以直接在此进行复制,若在API创建时开启了传输加密,加密调用过程中的SM2公钥也需要在应用详情页查看并复制使用。
新建和注册API - 图21

当前支持应用批量绑定已发布的API,单击绑定API,在弹出的对话框中进行API批量选择。
21 数据服务04.png

调用API

数据服务支持Restful和Java SDK两种方式调用API,在SDK下载或者API集市页面的右上方,可以下载详细的使用说明文档,以供用户调用参考,调用说明文档中对这两种方式均进行了详细的说明。

更详细的API调用说明,可参阅API调用说明

如果在创建API时,开启了apiToken鉴权,将API发布成功后,在API详情页的基础信息中会有apiToken内容,在header中添加apiToken、version和appKey的内容,也可以调用该API,适用于报表、数据大屏等安全性要求不高的场景。

21 数据服务03.png

API集市

对于API的调用者而言,不需要关心API的取数逻辑,可以直接在API集市查看已经发布的API,通过详情页,查看当前API的请求和返回参数,如果属于需要的API,可点击申请API进入申请审批流程。
新建和注册API - 图24

在申请API的弹框中,支持调用截止时间调用频次的自定义设置,默认为永久。支持行级权限列级权限设置,默认关闭。如果有新建应用的权限,可直接新建应用,或绑定已有的应用,填写申请理由,默认由API的创建者进行审核,提交申请后,会弹窗提示工单进入流程协作与通知中心,可快速点击链接,进入流程协作中心查看申请工单的状态。

当工单审批成功之后,则具备调用该API的权限,通过参考调用手册,正确调用已授权的API。

关于行级权限,必须满足入参为必填项入参参数类型和权限中设置一致才可绑定。且若入参绑定了in、between操作符且参数类型为字符串时,还可以选择行权限值的传参配置,单个权限值即只能传递单个值且需精准匹配,任意权限值的组合,则支持传递多个行权限值。

新建和注册API - 图25

关于列级权限,可选择API请求的返回参数,调用者只能查看选中的参数。
新建和注册API - 图26

导出、复制和锁定API

  • API导入、导出
    针对互相独立的两套网络不通的环境,比如A作为测试环境,B作为线上环境,想要将A环境的API同步到B环境,可以通过导出、导入的方式实现。
    新建和注册API - 图27
    注意:
    1)导出的包格式为zip,其大小不可超过200MB;
    2)导入API时会进行逻辑校验,具体如下:
    校验项 说明
    资源包校验 资源包格式必须为zip,大小不超过200MB。
    集合和path校验 需要提前创建同名集合和path,若不存在,将无法导入,若存在,将放在同名集合和同名path的集合下。
    API发布状态校验 若API在当前项目下存在且为已发布状态,以当前项目下已有的为主,无法导入API;若在当前项目下存在且为未发布状态,将替换当前项目下的API。

    3)数据源和资源组默认填充同名内容,若不存在,则置空;

    4)导入后的API均为已创建、待测试状态,需重新执行测试和发布流程。

    • API信息下载
      点击“下载”按钮支持下载API信息,当前支持PDF和Excel两种格式。API信息包括基本信息、参数信息、响应示例、授权信息和调用示例说明等,Excel格式的文档支持在总览页中通过软连接进行跳转。
      新建和注册API - 图28

    Excel格式的API文档示例如下:

    新建和注册API - 图29

    • API复制
      点击更多下的复制,可快速复制与当前一模一样的API,默认API名称和path后面填充时间戳,允许修改。
      新建和注册API - 图30

      注意: 当API进行复制和编辑,如果参数未发生变更,则会保留上次测试数据,如果参数发生了改变,则清空测试数据。
    • API锁定
      对于自己是创建人的API,支持对API增加锁定,API锁定后,只有API的创建人和协助管理者可以对API执行锁定(数据服务平台管理员,即超管不受锁定的限制)和解锁,锁定后,只有API的创建人和协助管理者才可以对API进行编辑、解除应用等操作。点击更多里面的锁定,API前增加图标新建和注册API - 图31,即锁定成功,锁定后的API也可解锁。
      2021-08-27-11-24-14.png

    API在线升级

    对于已发布的API,支持在线升级,单击更多选择API升级。API升级只能修改影响取数逻辑的字段,比如入参、请求和数据源等内容。在API升级的第四个步骤,可对该API绑定的资源节点执行升级操作,全部节点处于升级成功,才可完成并退出,若有节点升级失败,可选择放弃并退出。

    21 数据服务06.png

    注意: 1、若原API开启了缓存,API升级版本将会延迟生效,延迟时间将取决于缓存的更新时间,且在第三步测试阶段,测试结果也会受到缓存数据的影响。 2、API在升级过程中,不支持修改传输加密,防止升级后的API无法调用。

    API版本历史

    在API列表中,点击更多选择版本历史可以查看API的各版本信息。

    有以下两种情况才会产生版本历史:

    1. 发布后的API重新下线编辑再发布,且编辑的字段为影响取数逻辑的内容,比如入参、请求参数、数据源等,此时会产生版本历史;

    2. 针对已发布状态的API,执行API升级操作,会产生新的版本历史。

    其他情况,比如编辑的是非取数逻辑字段、名称等,不会产生版本历史;再未发布状态下对API的修改,也不会记录版本历史。

    21 数据服务07.png

    API回滚和版本历史对比

    在API版本历史管理弹窗中,可以选中其中两个版本,进行版本对比,对于基本信息和参数信息,若两个版本有不一致的地方,页面会标红显示,

    21 数据服务08.png

    针对某个API的回滚操作,只有该API处于发布状态,才可执行回滚。API回滚成功之后,再查看版本历史时,回滚版本将作为最新版本。

    21 数据服务09.png

    注意: API升级和回滚版本互斥,若在API升级过程中,未完成或退出,而是直接关闭页面等方式,再进行回滚时将无法操作;同样,若在API回滚过程中,未完成或退出,执行API升级也将无法执行操作。

    注册API

    若用户已有API,也可以通过注册功能,将API通过数据服务平台进行统一管理。

    首先在数据源管理界面将已有的API通过"API"数据源类型登记到平台中,然后在API列表页面,新建下拉框选择注册API可进行注册,注册API包含三个步骤:填写基础信息、参数配置以及功能测试。

    配置基础信息

    此处和新建API页面相似,需要配置API名称、API集合、API Path、返回类型、超时时间、描述、API标签、数据结果缓存和apiToken鉴权等参数。

    参数配置

    在参数配置中,首先选择API类型的数据源,即待注册API服务的后台地址,可以在数据源登记页面选择API类型的数据源。然后对注册的API添加请求参数,便于API调用者在详情页查看API的详情内容。对于响应示例,也可以自定义成功和失败示例,也是便于API调用者查看当前API的返回内容,便于更好的使用API。

    新建和注册API - 图37

    测试

    注册的API配置完成后,可以在线对注册的API进行测试。测试成功的API即可进行发布,其他操作同新建API类型,包括复制、升级、下载等。
    21 数据服务05.png