新建和注册API

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

服务概览

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

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

数据概览页面还提供调用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进行管理。

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

新建API

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

配置API基本信息

配置API信息页面：

入参参数的配置：

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

配置表和参数

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

选择表如下图所示：

注意： Hive数据源仅建议在BI场景或者QPS不高的数据产品场景中使用，并且建议对Hive API配置流控策略，防止下游调用方并发过高时对Impala集群稳定性造成影响。如果通过Hive数据源创建API时，需要将hive的数据同步到Impala，当前有两种途径可以将数据同步到impala：一种是创建hive表时，打开"impala同步"的开关，另一种是执行SQL语句"INVALIDATE METADATA table_name;"。

配置返回和排序参数

如下图所示：

配置查询条件

如下图所示：
配置查询条件支持请求参数的多级嵌套，实现诸如(a or b) and c等逻辑，需要先选择最外层连接符。

特殊说明：

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

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

测试方式如下：

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

测试方式如下：

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

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

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

保存和测试

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

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

在返回内容中打印执行的SQL语句，便于问题定位。

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

当前如果API是hive数据源类型支持使用个人账号执行此功能。如果数据字段配置了脱敏，创建hive 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创建时开启了传输加密，加密调用过程中的SM2公钥也需要在应用详情页查看并复制使用。

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

调用API

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

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

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

API集市

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

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

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

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

关于列级权限，可选择API请求的返回参数，调用者只能查看选中的参数。

导出、复制和锁定API

• API导入、导出
  针对互相独立的两套网络不通的环境，比如A作为测试环境，B作为线上环境，想要将A环境的API同步到B环境，可以通过导出、导入的方式实现。
  
  

  注意： 1）导出的包格式为zip，其大小不可超过200MB； 2）导入API时会进行逻辑校验，具体如下： 校验项 说明 资源包校验 资源包格式必须为zip，大小不超过200MB。 集合和path校验 需要提前创建同名集合和path，若不存在，将无法导入，若存在，将放在同名集合和同名path的集合下。 API发布状态校验 若API在当前项目下存在且为已发布状态，以当前项目下已有的为主，无法导入API；若在当前项目下存在且为未发布状态，将替换当前项目下的API。 3）数据源和资源组默认填充同名内容，若不存在，则置空； 4）导入后的API均为已创建、待测试状态，需重新执行测试和发布流程。

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

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

  

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

    注意： 当API进行复制和编辑，如果参数未发生变更，则会保留上次测试数据，如果参数发生了改变，则清空测试数据。

  • API锁定
    对于自己是创建人的API，支持对API增加锁定，API锁定后，只有API的创建人和协助管理者可以对API执行锁定(数据服务平台管理员，即超管不受锁定的限制)和解锁，锁定后，只有API的创建人和协助管理者才可以对API进行编辑、解除应用等操作。点击更多里面的锁定，API前增加图标，即锁定成功，锁定后的API也可解锁。
    

  API在线升级

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

  

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

  API版本历史

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

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

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

  2. 针对已发布状态的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、返回类型、超时时间（最长为180s）、描述、API标签、数据结果缓存和apiToken鉴权等参数。

  参数配置

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

  

  若注册API在第一步选择的POST请求，支持在第二步选择content-type，可选内容包括application/json、application/x-www-form-urlencoded 、multipart/form-data。

  需要注意的是：数据服务API默认仅支持application/json，此处的content-type表示转发至第三方时可支持的格式，其中multipart/form-data不支持文件上传下载。

  

  测试

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