DataLeap数据服务平台主要助您将不同数据库中存储的数据（例如某张数据表），通过可视化配置方式快速封装成一个可供服务端消费的API接口，并提供此API接口的管理、运维和共享能力。

1. 需求背景：
   在企业大数据业务场景里，不同角色常常面临着进行实时数据分析以及建设业务数据看板等工作需求，他们需要依据数据来做出关键的业务决策。数据服务 API 能够通过可视化配置或者低代码的方式，迅速构建与数据库表相对应的 API ，进而提供给下游数据应用的人员进行调用查询数据。
2. 如何搭建数据服务API？
   本实践中，上游数据开发人员采集到业务数据，先进行一系列的加工数据操作，并将其写入到 Oracle 数据库中存储。后续开发人员在DataLeap数据服务平台 > 数据源管理模块中，完成 Oracle 表(物理表)的接入和逻辑建模(创建基于 Oracle 表的逻辑表)，然后在 API 模块中进行逻辑表配置、调试、发布 API等操作，并将API授权给下游的数据应用(PSM)。后续此 API 的更新、权限变更、运维等操作，均可以在数据服务平台完成。

1 前置准备 #

在进行数据服务的 API 开发前，您需做以下准备工作。

1. Oracle 数据源信息
   Oracle 数据源配置信息及数据表准备工作。添加Oracle数据源。
2. 创建业务线
   系统管理员需要先到数据服务 > 系统管理 > 业务线管理模块中，创建业务线。创建操作详见“业务线管理”。
3. 创建项目
   系统管理员或业务线管理员需到数据服务 > 系统管理 > 项目管理模块中，创建数据服务项目。详见“项目管理”。
4. 添加账户权限
   添加数据服务角色，为后续 API 开发人员添加相应的权限。详见“账户权限管理”。
5. 创建API应用管理
   应用管理主要是管理企业内部的应用，以便于 API 对应用进行授权。应用管理包括应用的增、改、查基本操作，以及管理应用的密钥。详见“应用管理”

2 使用流程 #

前置准备工作完成后，您便可开始创建数据服务API，关键操作流程如下：

1. 创建数据源
   在创建数据服务API之前，您需要将 Oracle 数据库注册为数据源，通过数据源的元数据连接数据库，来访问库下数据表的 Schema 信息，帮助您构建物理表和逻辑表。
2. 构建物理表、逻辑表
   Oracle 数据源在数据服务平台中注册且连接成功后，需构建具体的物理表和逻辑表：
   • 物理表：Oracle 数据库中的一张表。 数据服务每次查询运行都需要使用物理表的元数据构造 DSL，因此目前将存储中表/字段信息注册到数据服务平台中以方便查看和管理。
   • 逻辑表：数据开发者在平台进行逻辑建模后产生的虚拟表，是物理表的一个映射。通过逻辑表屏蔽底层存储细节，完成物理表字段类型转换、规范命名、备份容灾配置等。您在实际配置API时必须使用逻辑表，不支持直接使用物理表。
3. 创建API
   逻辑表创建完成后，需选择配置 API 类型及基本信息，API 类型支持脚本式/向导式/原生式/指标式查询 四种方式。
4. 开发API
   API 类型选择完成后，可基于逻辑表创建相应的API。
5. 调试API
   API 开发完成后，您可在界面进行 API 调试操作，仅调试成功的 API，方可继续发布上线。
6. 发布API
   将调试成功的 API 进行发布操作。
7. 授权应用
   将 API 对项目中已创建的应用进行授权操作，方便企业内部或外部业务应用进行调用时的权限管理操作。
8. 调用API
   应用授权完成后，在 API 详情中，获取调用地址信息，请求代码示例、请求/返回参数等信息，后续可使用 Postman 工具进行调用测试。

3 数据源操作 #

3.1 配置数据源 #

注册 Oracle 数据源，打通 Oracle 和数据服务平台之间的网络链路，将数据源注册到数据服务平台 > 数据源模块。

1. 登录 DataLeap租户控制台。

2. 在右侧快速入口，单击数据服务按钮，并快速进入到数据服务 > 数据源界面。

3. 在数据源界面，左侧导航栏中切换至数据源，进入数据源管理界面。

4. 单击右上角添加数据源按钮，在弹窗中，进行 Oracle 数据源的配置，配置信息说明如下：
   
   其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。
   数据服务Oracle数据源配置说明：

   参数	说明
   基本信息
   *数据源类型	下拉选择 Oracle 数据源类型。
   *数据源名称	数据源的名称，可自行设置，仅支持中文，英文，数字，“_”，100个字符以内。
   描述	对当前新建数据源的注释说明。
   连接参数
   *IP	输入能连接 Oracle 数据库的 IP 信息。
   *Port	输入数据库的端口信息。
   *SID	输入 Oracle 实例的 SID 名称信息。
   *用户名	输入有权限访问数据库的账号。
   *密码	输入账号对应的密码信息。

5. 信息配置完成后，单击下方连通性测试按钮，等待网络测试完成后，单击确定按钮，即可完成数据源的注册。

3.2 创建物理表 #

物理表是在线存储引擎中（如 MySQL/Doris/Oracle 等数据库）中的一张表。服务每次查询运行都需要使用物理表的元数据构造 DSL，因此目前将存储中表/字段信息注册到数据服务平台中以方便查看和管理。

1. 在数据源创建完成后，左侧导航栏中切换至物理表管理界面。

2. 单击目录树上的新建物理表按钮，左侧即展现新建物理表界面。

3. 在新建物理表界面，完成以下配置：

   1. 数据源类型：下拉选择 Oracle 数据源类型。
   2. 选择数据源：选择已创建成功的 Oracle 数据源。

4. 根据数据源配置时的用户名密码信息，在待选库表中展现有权限访问的库表，您可通过输入表名信息，进行选择。

5. 单击中间确定按钮，将表添加至已选库表窗口。
   

6. 表添加完成后，您可在下方表字段确认栏，选择字段对应的安全登记、是否为主键、是否为实时更新字段等属性。

7. 在基本信息确认阶段，您可对标设置以下基本信息：
   其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。

   配置项	说明
   安全等级	设置表安全等级，分为 L1-公开、L2-内部、L3-秘密、L4-机密 4 种安全等级。
   *创建同名逻辑表	选择是否创建同名逻辑表。为提高创建效率，此处选择开启创建。
   *逻辑表存储目录	指定同名逻辑表存放目录。
   *逻辑表名称	设定对应逻辑表的名称信息。

8. 基本信息配置完成后，单击保存按钮，完成物理表创建。

物理表更多管理操作，详见“物理表管理”。

3.3 创建逻辑表 #

逻辑表是数据开发者在平台进行逻辑建模后产生的虚拟表，是物理表的一个映射。
通过逻辑表屏蔽底层存储细节，完成物理表字段类型转换、规范命名、备份容灾配置等。用户实际配置 API 时必须使用逻辑表，不支持直接使用物理表。
因上方创建物理表时，已开启创建同名逻辑表选项，此时您可直接前往逻辑表界面，进行查看对应的逻辑表信息。

更多详细逻辑表相关操作，详见“逻辑表管理”。

4 创建 API #

通过页面相关配置，基于逻辑表快速表生成 API。API 目前支持脚本式/向导式/原生式/指标式查询四种类型，可根据实际需要进行 API 的创建选择。
本实践中，以脚本式API创建为例说明。

4.1 新建 API 文件夹 #

在新建 API 之前，您需先建一个根文件夹，来存放 API 文件。
在上方导航栏中，单击 API 按钮，进入 API 开发界面，在左侧目录树上单击新建文件夹按钮，弹窗中输入文件夹名称信息，单击确定按钮，完成文件夹创建。

4.2 新建 API #

文件夹新建完成后，您便可开始新建 API。

1. 单击左侧目录树上方新建 API 按钮，或鼠标Hover文件夹更多操作中新建API选项，进入新建API配置界面。
   

2. 以脚本式 API 类型创建为例：

   说明

   脚本式 API 支持自行编写 API 的查询 SQL，该方式可满足高阶需求，支持选择同源多张逻辑表进行处理。其余更多 API 类型说明详见“新建API”。

   新建脚本式 API 相关参数说明如下表所示，其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。

   参数	说明
   基本信息
   *API名称	输入 API 名称信息，API 名称需以字母、数字或下划线字符组成，30个字符以内。如：doc_api_test
   *存储目录	下拉选择已创建的文件夹目录，用来存放创建的API。
   *最大QPS	配置该API允许的最大QPS，默认为 100。
   *命中缓存	按需选择并发调用API时，是否将同请求参数的调用计入限流中。
   安全等级	设置API安全等级，分为L1-公开、L2-内部、L3-秘密、L4-机密 4 种安全等级。
   负责部门	可输入负责当前API管理的部门信息。
   描述	输入API描述信息，方便后续维护和管理。
   更多配置
   最大 limit	正整数形式，输入API查询的最大limit。
   *报警模版	选择是否开启报警模板，开启后，平台将自动为API配置默认的报警规则，报警接收人为API负责人，您可根据实际情况，进行选择需开启的报警规则。 如需编辑或删除报警规则，请到【API详情】报警配置中进行修改。详见“报警配置”。
   初始版本	初始创建时，默认为V0
   版本描述	请填写版本描述

3. 新建API配置完基础信息后，单击保存即可进入相应类型API的开发页面。

5 开发 API #

脚本式 API，可以通过自定义 SQL，自行编写 API 数据的查询 SQL，实现更复杂的查询需求，支持选择同源多张逻辑表进行处理。

1. 逻辑表选择
   下拉选择逻辑表名称 doc_api2las，支持选择同源多张逻辑表，最多10张。

2. 编辑查询
   在代码框中进行API对应的查询SQL开发，API开发阶段，建议可全屏开发来编写SQL语句，目前支持的SQL类型为：

   • SQL编辑：
     直接编写普通SQL语句。您可以在一些简单的场景下使用该类型，如仅需对固定的数据表结构、过滤条件范围进行查询时，可直接用 SQL 编辑。

   • 动态SQL编辑：
     动态SQL必须以

     return (<SELECT></SELECT>)
     

     包裹。您可以在复杂的场景下，如您需根据外部输入或其他变量参数动态改变 SQL 语句时；亦或是需要根据不同业务情况执行不同的 SQL 语句，来实现灵活的业务逻辑查询时，您便可用动态 SQL 语句来生成复杂的查询逻辑。
     动态 SQL 语句说明详见“数据服务语法”。
     编辑区上相关快捷按钮的作用如下表所示：
     

     操作	说明
     运行	在非全屏页面，单击运行按钮后会切换到编辑器全屏页面，在全屏页面，单击运行按钮可解析请求/返回参数，并展现运行后的查询结果和查询日志。
     解析请求参数	单击解析请求参数按钮后可将SQL中的where条件作为解析参数传入请求参数栏。
     表字段	单击表字段按钮后打开表字段弹窗，表字段弹出显示选中的逻辑表的字段信息。
     格式化	单击格式化按钮可将SQL格式化标准格式。
     全屏显示	在非全屏状态下，单击全屏显示按钮会切换到编辑器全屏页面。
     取消全屏	在全屏状态下，单击取消全屏按钮会切换到编辑器非全屏页面。

3. 请求参数
   脚本式请求参数可通过解析请求参数按钮，来自动解析SQL中where条件后的请求参数，单击解析按钮，可进入全面屏模式，进行自动解析。当然也支持您手动添加和校正参数，本实践中，查询不设置where过滤条件，即请求参数置为空。
   更多请求参数配置详见脚本式。

4. 返回参数
   脚本式返回参数可通过单击运行按钮自动解析，也支持手动添加和校正参数，本实践中，查询将返回表所有字段数据。
   更多返回参数配置详见脚本式。
   

5. 高级配置

   操作	说明
   返回结果格式	数据返回的结果格式，支持选择 JSON 和 JSONCompact 两种类型： 选择 JSON 格式时，调用接口返回的结果中的 DATA 部分将按照 JSON 格式返回。 选择 JSONCompact 格式时，调用接口返回的结果中的 DATA 部分将按照二维数组格式返回。 注意 该配置项在保存并发布当前版本后生效。对于已有下游调用的API，请谨慎更改，因为可能会导致下游在使用数据时出现异常。
   数据缓存时间	缓存策略为返回结果的缓存时间，一共有三种策略： 系统策略：默认策略，默认为 600s 用户自定义：用户可自定义缓存时间，根据实际场景进行设置 关闭：关闭缓存，每次都走实时查询。

6 测试 API #

API 开发配置完成后，您可通过测试能力，来查看 API 的逻辑是否正确。

1. 单击界面右上角测试按钮，进入API测试窗口。
2. 在API测试窗口，单击右下角测试按钮，等待测试结果成功返回。

更多测试操作详见测试API。

7 发布 API #

API 测试无误后，您可将 API 发布至线上环境，以便您在不同环境中进行调用。

1. 单击保存按钮，保存当前API配置信息；
2. 单击发布按钮，将当前版本API发布至线上环境。

更多API发布操作详见发布API。

8 授权应用 #

API发布至线上环境后，可进入API详情界面，对API进行应用授权管理、报警配置等API运维操作。

1. 单击右侧导航栏中的API详情按钮，进入API详情界面。
   

2. 选择授权管理页签，并单击新增授权按钮，进入API应用授权配置窗口。

   说明

   进行API应用授权前，您需先在系统管理 > 应用管理中完成注册，并创建**OAuth2.0(动态token)**秘钥类型。创建应用操作，详见“应用管理”。

3. 在应用授权配置窗口，完成以下信息配置：

   参数	说明
   基本权限
   *应用名称	下拉选择允许调用 API 的应用名称，对应一个已创建成功的应用信息。 若您还未创建应用，您可单击新建应用按钮，前往应用管理进行创建。新建操作详见“应用管理”。
   标志符	应用的唯一标识，在应用管理创建时指定。
   有效期	设定应用授权有效期限，新的到期时间=当前到期时间+续期天数，续期时会给 API 管理者和应用的申请者发送相应通知。您可下拉选择有效期天数。
   应用方	输入应用方名称信息，可用于申请 API、授权或审批时方便明确应用方信息。
   *最大QPS	设置应用调用 API 的最大 QPS，您可根据实际情况，自定义设置调用 API 时最大的 QPS，当调用的 QPS 达到最大值时，会触发限流。 若不填或选择不限制，则默认不限流。
   *调用负责人	下拉选择真正调用当前 API 的应用负责人。
   调用优先级	下拉选择调用的优先级情况，数字越小，代表等级越高。
   标签	您可以自定义标签，用于标识某一类授权，以便快速搜索区分。 单击添加按钮，添加标签组信息，下拉选择标签组，及对应的标签信息，支持添加多个标签组。 若没有可选的标签组，您可单击上方创建标签组按钮，进入数据服务 > 系统管理 > 标签管理界面，进行新建标签组操作。详见“标签管理”。 您也可单击操作栏中的删除按钮，将已添加的标签进行删除操作。
   授权描述	添加授权描述信息，可针对授权场景进行信息补充。
   行列权限
   行级权限	设置调用的行级权限，您可针对请求参数做限制，比如限制只能访问某个请求参数的某几个值。支持添加多个行权限，各请求参数可以是“且”、“或”的关系。 注意 行级权限设置前，您需先添加对应的请求参数，如指标查询式API设置权限前，需先添加所需的维度字段。
   列权限	列权限针对返回参数做限制，比如限制只能返回某列的参数信息。下拉选择返回参数字段列，支持选择多个。

4. 应用授权信息配置完成后，单击右下角确认按钮，完成授权应用添加。

9 调用 API #

应用授权完成后，您便可在API调用工具（如：Postman）中，进行调用。

1. 在API详情界面，切换至调用信息页签。

2. 在调用信息中，获取调用地址。
   

3. 【可选】如果授权的应用，其创建的密钥为动态密钥时，需先调用接口来动态获取API调用时所需的动态token信息。动态获取Token信息调用示例如下：

   curl -X POST \
     -H 'user: username' \
     -H 'Content-Type: application/json' \
     http://exxxxxxleap.datarangers-onpremise.volces.com/data_service/api/v2/api_service/token \ 
     -d '{"AppKey": "you_app_key","AppSecret": "you_app_secret"}'
   

   调用示例可在界面接口文档中获取：
   
   参数说明：

   参数	说明
   user	API 责任人用户名信息。非必填。
   Url	默认调用地址，以接口文档中的显示为准。
   AppKey	输入当前已授权应用的密钥AppKey信息。 应用管理 > 密钥管理：
   AppSecret	替换应用管理中已创建的密钥AppSecret信息。

4. API调用示例：

   curl -X POST \
      -H 'user: username' \
      -H 'Content-Type: application/json' \
      http://exxxxx.datarangers-onpremise.volces.com/invoker_engine/query_with_params \
      -d '{"ApiID": "180xxxxxx64","Option": [{"Id":100,"Val":0,"Val_":"$DPS_TOKEN"}],"Params": {}}'
   

   参数说明：

   参数	说明
   user	API 责任人用户名信息。非必填。
   Url	获取调用说明栏中的调用 URL。
   ApiID	输入当前已发布的API ID信息，在API详情中可获取。
   $DPS_TOKEN	替换应用管理中已创建的秘钥信息，或通过接口获取的动态token信息。
   Params/Sql	Params：向导式/脚本式 API 的请求参数示例。 Sql：原生 API 中逻辑表的查询 SQL 语句。

5. 打开API调用工具（Postman），进行调用测试：

   1. 【可选】动态获取Token信息：
      1. 在Postman工具已创建的Workspace界面，单击上方Import按钮；
      2. 并在弹窗的输入框中，复制动态获取token信息调用示例（上方第 3 步操作）；
         
      3. 示例输入完成后，单击“Import Without Saving”或“Import Into Collection”按钮，完成添加调用示例。
      4. 单击界面中的“Send”按钮，并在下方“Body”页签中，复制获取到的Token信息，供后续API调用时使用。
         
   2. API调用查看数据返回结果
      1. 在Postman工具已创建的Workspace界面，继续单击上方Import按钮；
      2. 并在弹窗的输入框中，复制API调用示例（上方第 4 步操作）；
         
      3. 示例输入完成后，单击“Import Without Saving”或“Import Into Collection”按钮，完成添加调用示例。
      4. 切换至“Body”页签，并将“raw”窗口中展示的“$DPS_TOKEN”信息，替换为刚刚获取到的动态Token信息。
         
      5. 替换完成后，单击界面中的“Send”按钮，并在下方“Body”页签中，查看最终调用查询的API数据结果。
         

6. 验证检查调用数据返回结果和原有Oracle表中的数据一致，即完成本次API调用实践。

后续，您便可在其他工具中，通过该API给下游数据应用的人员进行调用查询数据，提高数据可用性。