数据服务 - API开发和管理 - 《有数数据开发及管理平台用户手册 V6.4》

服务概览
登记数据源
创建API集合
创建API

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

服务概览

服务概览页面，支持查看今日、近7日和近30日的API的调用情况，包括累计已发布的API数量、累计调用API的数量、累计调用API的次数、累计请求返回量数值指标以及累计调用API的成功次数，通过图表可了解在对应时间范围内的API调用的Top10、应用调用Top10、API调用次数趋势图、API返回量趋势图以及服务的调用比率等。

参数信息	说明
累计已发布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列表和未调用API列表功能。可在调用API列表中查看调用API中包含每个API的最近调用时间，如果最近调用时间比较久远，可以考虑将API进行下线操作。还可以查看未调用API列表，若API创建成功，但未进行测试调用，可以考虑将API进行删除。

登记数据源

在使用数据服务之前，需要先登记数据源。单击数据源登记跳转至项目中心（新）页面完成数据源登记。配置方式可在数据源登记中进行查看。

创建API集合

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

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

创建API

登记数据源和创建API集合成功后，就可以进行API的构建了。构建API一共包括三步：填写API基本信息、配置表和参数、测试API。

配置API基本信息

配置API信息页面：

参数信息	说明
API名称	创建的API名称。
API集合	API所属的集合。
API Path	API的请求路径，也是构成API url地址的一部分。
协议	API调用的请求协议。
请求方式	API调用的请求方式，支持get和post。
返回类型	API调用的返回类型，支持json。
超时时间	API超时时间。
描述	对API的描述。
API标签	可以针对API添加业务标签，用于快速识别API。
数据结果缓存	若对响应时效有要求，可开启API数据结果缓存。
apiToken鉴权	若打开，可通过apiToken调用API，只需要在header中添加字段apiTOken、appKey和version即可，适用于报表、数据大屏等安全性要求不高的使用场景。
入参定义	对API调用中的请求参数绑定的入参参数的定义，支持普通入参和函数入参，函数入参中支持concat、substring等函数，即通过函数对请求参数进行二次处理。

入参参数的配置：

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

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

注意： 若在向导模式下，默认值是非必填，并且没有填写默认值，则在API调用时将忽略该参数的调用，实现参数的动态传递。

配置表和参数

配置完API基本信息之后，需要进行表和参数的配置，如下图所示：

参数信息	说明
生成方式	选择API的生成方式，支持向导和SQL模式生成API。
数据源类型	选择数据源类型，可供选择的数据源根据数据服务的版本不同而不同。
数据源名称	选择在数据源登记模块登记的数据源名称。
数据表	选择数据源下的数据表。
添加返回和排序参数	在选择返回和排序参数下，点击”添加”，弹窗中展示表的所有字段，选择返回参数和排序参数。
添加请求参数	在添加请求参数下，点击”添加请求参数”，弹窗中选择字段，请求参数支持多层嵌套，使用and或者or连接，实现诸如”(a or b) and c”的逻辑。

特殊说明：

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

除了in和between操作符外，都只关联一个参数的操作符，比如=，绑定方式如下：
测试方式如下：
对于in和between操作符，参数之间用逗号进行分隔，绑定方式如下：

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

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

若对返回参数有二次处理的需求，平台支持上传Jar包达到对返回参数的二次处理，可以将对返回参数的处理逻辑在Jar中完成，然后上传Jar包，填写类名，若Jar中对返回参数进行了修改，可添加真实的返回参数。

保存和测试

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

点击查看错误状态码可以查看返回的错误码对应的错误原因，便于用户更好的定位失败的API的错误原因。

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

发布API

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

API绑定应用

将API发布之后，点击API的名称进入详情页，单击添加授权按钮，选择需要绑定的应用进行添。

授权API应用

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

在数据服务页面，打开应用管理功能详情页面，单击新建应用，在弹出的对话框中完成应用的创建。

在API应用模块，点击查看授权或者应用名称，可以进入应用的详情页，在关联API处，可以看到当前应用被哪些API所绑定，可以对绑定的API进行测试，也可以解除绑定。同时，在详情页还能看到生成的应用的APPKey和APPSecert，在API的调用中，所需要的APPKey和APPSecert信息可以直接在此进行复制。

当前支持应用批量绑定已发布的API，单击绑定API，在弹出的对话框中进行API批量选择。

调用API

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

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

API集市

对于API的调用者而言，不需要关心API的取数逻辑，可以直接在API集市查看已经发布的API，通过详情页，查看当前API的请求和返回参数，如果属于需要的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配置完成后，可以在线对注册的API进行测试。测试成功的API即可进行发布，其他操作同新建API类型。

导出、复制和锁定API

API导出
对于已经创建的API，支持选择后进行导出下载，可下载word或者pdf版本，下载的文档中包含API的基础信息、请求参数、排序参数和返回参数等内容。
API复制
点击更多下的复制，可快速复制与当前一模一样的API，默认API名称和path后面填充时间戳，允许修改。
API锁定
对于自己是创建人的API，支持对API增加锁定，API锁定后，只有API的创建人可以对API执行锁定(数据服务平台管理员，即超管不受锁定的限制)和解锁，锁定后，只有API的创建人才可以对API进行编辑、解除应用等操作。点击更多里面的锁定，API前增加图标，即锁定成功，锁定后的API也可解锁。