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

1. 需求背景：
   在企业大数据业务场景里，不同角色常常面临着进行实时数据分析以及建设业务数据看板等工作需求，他们需要依据数据来做出关键的业务决策。数据服务 API 能够通过可视化配置或者低代码的方式，迅速构建与数据库表相对应的 API ，进而提供给下游数据应用的人员进行调用查询数据。
2. 如何搭建数据服务 API？
   本实践将向您介绍通过数据服务脚本式开发，搭建 MySQL 数据源 API，以实现基于特定业务逻辑和数据需求的多表 JOIN 场景。
   实践流程具体包括：完成 MySQL 数据源创建，接入 MySQL 表（物理表）并进行逻辑建模（创建基于 MySQL 表的逻辑表），接着在 API 模块中开展逻辑表配置、调试、发布 API 等操作，最后将 API 授权给下游的数据应用（PSM）。此后，该 API 的更新、权限变更、运维等操作均可在数据服务平台完成。

1 前置准备

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

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

2 使用流程

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

1. 创建数据源
   在创建数据服务 API 之前，您需要将 MySQL 数据库注册为数据源，通过数据源的元数据连接数据库，来访问库下数据表的 Schema 信息，帮助您构建物理表和逻辑表。
2. 构建物理表、逻辑表
   MySQL 数据源在数据服务平台中注册且连接成功后，需构建具体的物理表和逻辑表：
   • 物理表：MySQL 数据库中的一张表。数据服务每次查询运行都需要使用物理表的元数据构造 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 配置数据源

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

1. 登录 DataLeap 租户控制台。
2. 在概览界面顶部服务窗口，单击数据服务按钮，可快速进入到数据服务功能界面。
   
3. 在数据服务界面，上方导航栏中切换至数据源页签，进入数据源界面。
4. 在数据源界面，左侧导航栏中切换至数据源，进入数据源管理界面。
5. 单击右上角添加数据源按钮，在弹窗中，进行 MySQL 数据源的配置，配置信息说明如下：
   

其中参数名称前带 ＊ 的为必填参数，名称前未带 ＊ 的为可选填参数。

本实践中，以 Cloud MySQL 数据源类型的配置说明为例：

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

3.2 创建物理表

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

1. 在数据源创建完成后，左侧导航栏中切换至物理表管理界面。
2. 单击目录树上的新建物理表按钮，左侧即展现新建物理表界面。
3. 在新建物理表界面，完成以下配置：
   1. 数据源类型：下拉选择 Cloud-MySQL 数据源类型。
   2. 选择数据源：选择已创建成功的 MySQL 数据源。
4. 根据数据源配置时的用户名密码信息，在待选库表中展现有权限访问的库表，您可通过输入表名信息，进行选择。
5. 单击中间确定按钮，将表添加至已选库表窗口。
   
6. 表添加完成后，您可在下方表字段确认栏，选择字段对应的安全登记、是否为主键、是否为实时更新字段等属性。
7. 在基本信息确认阶段，您可对标设置以下基本信息：

其中参数名称前带 ＊ 的为必填参数，名称前未带 ＊ 的为可选填参数。

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 类型说明详见“4 开发 API”。

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

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

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

5 开发 API

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

1. 逻辑表选择
   下拉选择需参与多表 JOIN 计算的逻辑表名称，支持选择同源多张逻辑表，最多 20 张。
   

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

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

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

     return (<SELECT></SELECT>)
     

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

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

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

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

5. 高级配置

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

6 测试 API

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

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

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

7 发布 API

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

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

更多 API 发布操作详见7 发布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 'env: $ENV' \ 
     -H 'Content-Type: application/json' \
     http://xxxx.xx.x.xxx:xxx/data_service/api/v2/api_service/token \
     -d '{"AppKey": "you_app_key","AppSecret": "you_app_secret"}'
   

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

   参数	说明
   user	API 责任人用户名信息。
   ENV	API 发布的环境信息。 测试环境：$PPE 线上环境：$ONLINE
   Url	默认调用地址，以接口文档中的显示为准。
   AppKey	输入当前已授权应用的密钥 AppKey 信息。可从应用管理 ＞ 密钥管理界面获取：
   AppSecret	替换应用管理中已创建的密钥 AppSecret 信息。

4. API 调用示例：

   curl -X POST \
     -H 'user:username' \
     -H 'Content-Type: application/json' \
     -H 'env: $ENV' \
     http://xxxx.xx.x.xxx:xxx/invoker_engine/query_with_params  \
     -d '{"ApiID": "186xxxxxxxxx24","Option": [{"Id":100,"Val":0,"Val_":"$DPS_TOKEN"}],"Params": {}}'
   

   参数说明：

   参数	说明
   user	API 责任人用户名信息。非必填。
   ENV	API 发布的环境信息。 测试环境：$PPE 线上环境：$ONLINE
   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. 验证检查调用数据返回结果和原有 MySQL 表多表 JOIN 后的数据一致，即完成本次 API 调用实践。

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