API 开发

数据服务 API 开发，您可通过页面相关配置，基于逻辑表快速表生成 API，供服务应用系统调用 API 获取数据，且可对 API 进行统一管理、发布、运维等操作，主要面向于 API 开发人员。
本文将为您介绍如何进行 API 的开发。

1 前提条件

在进行 API 开发前，请保证满足以下两点使用前提：

1. 已加入数据服务项目，且需要是该项目的数据开发或项目管理员角色。
2. 已在数据源模块创建了物理表和逻辑表，并拥有表的读权限。详见数据源。

2 文件夹管理

2.1 新建文件夹

在新建 API 之前，您需要先创建 API 文件夹目录，API 文件夹目录用于存放 API、管理 API，方便对API进行分类。

1. 登录 DataLeap租户控制台 。
2. 在概览界面顶部服务窗口，单击数据服务按钮，可快速进入到数据服务功能界面。
3. 进入到 API 开发界面，在左侧目录树上单击新建文件夹按钮，弹窗中输入文件夹名称信息，单击确定按钮，完成文件夹创建。
   

2.2 文件夹操作

文件夹创建完成后，您可在文件夹中，进行以下操作：

1. 可在一级文件夹路径下创建第二、第三级文件夹，同样单击文件夹右侧的新建子文件夹按钮，在弹窗中输入文件夹名称完成创建。

   说明

   • 目前仅支持在根目录下，创建三级文件夹。
   • 同级的文件夹名称不允许重名。

   

2. 文件夹涉及到的更多操作如下，移动至文件夹最右侧更多按钮，进行以下操作：

   操作	描述
   重命名	单击重命名按钮，在弹窗中，输入新的文件夹名称。
   移动	单击移动按钮，在弹出窗口中可选择新的文件夹路径，确认后文件夹及文件下的 API 会移动到新路径目录下。 说明 为了不影响线上 API 调用情况，待移动的 API，所对应的逻辑表，会自动授权至目标项目下，需秉持权限最小化原则，谨慎操作移动 API文件夹。
   删除	单击删除按钮，当删除时当文件夹下为空，可直接进行删除；当文件夹下有子文件夹或 API 时，文件夹和 API 的位置会上升一级。

3 新建 API

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

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

2. 新建 API 支持三种类型：

   1. 脚本式：支持自行编写 API 的查询 SQL，该方式可满足高阶需求，支持选择同源多张逻辑表进行处理。
   2. 向导式：无需代码编写，在界面勾选配置即可快速生成 API 。请求参数为 Where 条件、返回参数为 Select 字段，系统自动生成查询语句。

      说明

      向导式创建 API ，仅支持单张逻辑表。

   3. 原生式：支持灵活查询数据集的一种 API 类型，目标是对在圈选范围内逻辑表进行灵活的重组查询，适合数据分析面板类场景。

3. API 类型选择完成后，需配置 API 的基本信息和更多配置：
   新建API相关参数如下所示，其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数。

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

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

4 开发 API

4.1 脚本式

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

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

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

   • SQL 编辑：
     直接编写普通 SQL 语句。您可以在一些简单的场景下使用该类型，如仅需对固定的数据表结构、过滤条件范围进行查询时，可直接用 SQL 编辑。
   • 动态 SQL：
     动态 SQL 必须以<SELECT></SELECT>包裹。您可以在复杂的场景下，如您需根据外部输入或其他变量参数动态改变 SQL 语句时；亦或是需要根据不同业务情况执行不同的 SQL 语句，来实现灵活的业务逻辑查询时，您便可用动态 SQL 语句来生成复杂的查询逻辑。
     动态 SQL 语句说明详见Dynamic SQL 语法。
     编辑区上相关快捷按钮的作用如下表所示：

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

3. 请求参数
   脚本式请求参数可通过解析请求参数来自动解析，单击解析按钮，可进入全面屏模式，进行自动解析。当然也支持您手动添加和校正参数：

   参数配置	是否必填	输入类型	说明
   参数名称	是	单选	API 请求参数名称，单 API 请求参数范围内唯一。
   绑定逻辑表字段	是	单选	请求参数映射的逻辑表字段。
   参数类型	是	默认值	字段类型，和表元信息保持一致。
   操作符	是	单选	支持操作符： 等于：请求参数等于实际赋值。 LIKE：为请求参数搜索某种指定模式。 IN：为请求参数规定赋值集合。 NOT IN： 请求参数不在赋值集合中。 NOT LIKE： 请求参数不在该指定模式中。 !=：请求参数不等于实际赋值。 ＞：请求参数大于实际赋值。 ＜：请求参数小于实际赋值。 ＞=：请求参数大于或等于实际赋值。 ＜=：请求参数小于或等于实际赋值。
   是否必选	是	勾选	默认勾选支持取消，即设定为必传参数。
   示例值	否	文本输入	文本输入，任意字符，长度0~200，不填为 null； 用于提供消费者测试使用。
   缺省值	否	文本输入	文本输入，任意字符，长度0~200，不填为 null； 用于提供消费者测试使用。
   安全等级	否	单选	设置安全等级：L1-公开、L2-内部、L3-秘密、L4-机密
   参数描述	否	文本输入	文本输入，任意字符，长度0~200，不填为null； 用于参数说明。
   操作	—	—	复制：单击复制该行参数，用于设定区间起始值等。 删除：单击删除该行参数。

4. 返回参数
   脚本式返回参数可通过单击运行按钮自动解析，也支持手动添加和校正参数：

   参数配置	是否必填	输入类型	说明
   参数名称	是	文本输入	API 请求参数名称，单 API 请求参数范围内唯一。
   绑定逻辑表字段	是	单选	返回参数映射的逻辑表字段。
   参数类型	是	默认值	字段类型，和表元信息保持一致。
   是否排序参数	否	勾选	用于设定返回结果排序； 指定字段对 API 的返回结果进行排序，当排序参数勾选了多个字段时，按照字段顺序排序优先级降低，可以选择升序或降序的方式进行排序。
   是否必选	否	勾选	返回参数中确认是否必须要返回。
   示例值	否	文本输入	文本输入，任意字符，长度0~200，不填为null； 用于提供消费者理解返回数据。
   缺省值	否	文本输入	文本输入，任意字符，长度0~200，不填为null； 用于提供消费者理解返回数据。
   安全等级	否	单选	设置安全等级：L1-公开、L2-内部、L3-秘密、L4-机密
   参数描述	否	文本输入	文本输入，任意字符，长度0~200，不填为null； 用于参数说明。
   操作	—	—	复制：单击复制该行参数，用于设定区间起始值等。 删除：单击删除该行参数。

5. 高级配置
   设置 API 的高级参数信息：

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

6. 脚本式 API 实现分页操作
   目前 One Service 脚本式实现了查询表的总数返回，您可以根据返回的数据总数来进行分页操作。
   当前只适用于 MySQL、ClickHouse 语法类的数据源，且返回的总数是根据用户的 SQL 来返回。

   1. 创建一个 API 用以分页查询：
      

   2. 如何进行调用：
      在进行调用时，需要在请求提 Option 中新增配置项，参考以下方式：

      {
          "Id": 6,
          "Val": 0,
          "Val_": "{\"with_total\": true}"
      }
      

      
      之后在返回结果中，会新增字段 TotalCnt 标明查询表的总数，如下图所示：
      
      请求 Demo 如下：

      curl --location 'http://xxx.xxx.xx.xxx/invoker_engine/query_with_params' \
      --header 'user: test' \
      --header 'env: ONLINE' \
      --header 'Content-Type: application/json' \
      --data '{
          "ApiID": "170xxxxx0485xxxxx",
          "Option": [
              {
                  "Id": 100,
                  "Val": 0,
                  "Val_": "$DPS_TOKEN"
              },
              {
                  "Id": 6,
                  "Val": 0,
                  "Val_": "{\"with_total\": true}"
              }
          ],
          "Params": {        
              "pageNum": 1,
              "pageSize": 10
              }
      }'
      

      • 参数说明：

      参数	说明
      location	获取调用说明栏中的调用 URL。
      user	API 责任人用户名信息。
      env	API 发布的环境信息。 测试环境：PPE 线上环境：ONLINE
      ApiID	在 API 详情页上方，获取 APP ID 信息。
      DPS_TOKEN	输入实际的 token 值信息，用于 API 访问鉴权，您可前往系统管理 > 应用管理 > 秘钥管理 > 应用秘钥界面，进行token 信息获取。操作详见2 管理应用密钥
      Params	向导式/脚本式 API 的请求参数示例。

      更多请求参数说明，详见2.1 请求参数说明

4.2 向导式

通过界面向导的方式新建 API，您无需编写任何代码，在界面上勾选相关配置即可快速生成 API。请求参数为 Where 条件、返回参数为 Select 字段，系统自动生成查询语句。

1. 逻辑表选择
   选择逻辑表，仅对所选的逻辑表进行 SQL 自动生成。请求参数为 Where 中包含的字段，返回参数为 Select 中包含的字段。

2. 参数设置
   请求/返回参数，您可单击参数列表下方添加/批量添加按钮，来快速选择需要的请求/返回参数，并配置每个参数的信息。
   

3. 高级配置
   设置 API 的高级参数信息：

   参数	说明
   返回结果格式	数据返回的结果格式，支持选择 JSON 和 JSONCompact 两种类型： 选择 JSON 格式时，调用接口返回的结果中的 DATA 部分将按照 JSON 格式返回。 选择 JSONCompact 格式时，调用接口返回的结果中的 DATA 部分将按照二维数组格式返回。 注意 该配置项在保存并发布当前版本后生效。对于已有下游调用的 API，请谨慎更改，因为可能会导致下游在使用数据时出现异常。
   数据缓存时间	缓存策略为返回结果的缓存时间，一共有三种策略： 系统策略：默认策略，默认为 600s 用户自定义：用户可自定义缓存时间，根据实际场景进行设置 关闭：关闭缓存，每次都走实时查询。
   开启分页	默认为关闭状态；如开启返回结果分页后，会增加以下公共参数的设置： 公共请求参数 pageNum：当前页号。 pageSize：页面大小，即每页记录数。 公共返回参数 pageNum：当前页号。 pageSize：页面大小，即每页记录数。 TotalCnt：总记录数。仅当 option 中有{"Id": 6,"Val": 0,"Val_": "{"with_total": true}"}时，返回 SQL 查询的总记录数(TotalCnt)。 调用说明 同脚本式 API，需在请求参数中传入 pageNum 和 pageSize，另外在 option 中增加 {"Id": 6,"Val": 0,"Val_": "{"with_total": true}"} 时，可返回 SQL 查询的总记录数(TotalCnt)。

4.3 原生式

原生式查询是支持用户灵活查询数据集的一种 API 类型，目标是对在圈选范围内逻辑表进行灵活的重组查询，适合数据分析面板类场景。

1. 逻辑表选择
   选择逻辑表，支持选择同源的多张逻辑表，最多为 5 张，用户动态传入 SQL，主要用于动态分析场景

2. 高级配置
   设置 API 的高级参数信息：

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

5 保存 API

API 开发之后需要进行保存，保存场景有如下几种：

• 单击保存按钮，会直接更新当前版本，如当前版本为线上版本，则不允许直接保存；
• 单击另存为新的版本，会直接生成一个新的版本；
• 单击另存为新的 API，会直接生成一个新的 API。

6 测试 API

API 开发完成后，您可在本地直接进行 API 测试，用于辅助 API 开发人员在线验证数据查询逻辑是否符合要求。
打开配置完成的 API 界面，单击右上角测试按钮，进入测试界面。

6.1 脚本/向导式测试 API

脚本/向导式模式测试 API 时，您可进行以下操作：

• dryRun：勾选 dryRun 时，返回结果中只返回执行的 SQL 逻辑，但不做执行。

• 请求参数格式：支持选择表单或 JSON 格式。

• 配置请求参数：

  配置项	说明
  参数名称	自动填写 API 配置的请求参数名称 。
  参数值	输入测试值，不同参数类型填写方式如下： 参数为数字(例如 MySQL 的 int、float、double)，直接将值填写到测试值输入框中。 当参数值为布尔类型时，直接填 true/false。 参数为其他类型(比如 MySQL 的 text，date)时，需要转为 json string 的格式(带引号)，不传值时，勾选 null。 实际请求参数要以“请求参数体”中的 json 为准。
  参数类型	自动为 API 配置参数类型。
  是否必选	自动获取当前版本 API 配置时的请求参数字段信息。
  安全等级	获取当前版本 API 配置时设置的字段安全等级，您也可以在测试时勾选相应的安全等级。
  参数描述	自动展现当前版本 API 配置时输入的描述信息。

• 返回结果：
  请求参数配置完成后，单击右下角测试按钮，开始 API 测试。
  测试的返回结果栏中，包含结果信息、请求日志、请求参数体等返回信息：

  返回信息	说明
  结果信息	API 查询结果返回： 查询成功时，支持以 Excel 表单或 JSON 形式查看结果，同时可对结果进行隐藏列、复制改行、复制该列、复制选中和搜索等操作。 查询失败时，返回结果包含状态码、报错信息。
  请求日志	查看详细的请求日志，展现具体的 SQL 查询逻辑，支持全屏查看。
  请求参数体	以 JSON 格式展现请求的参数体。
  查询状态	返回查询的状态码：成功/失败；以及查询耗时、大小等信息。

API 测试完成后，您可单击下方“同步参数至调用信息”按钮，将以上配置参数保存为 API 详情页中的接口请求/返回代码，和请求/返回参数示例。

6.2 原生式测试 API

原生模式测试 API 时，您可进行以下操作：

• 请求参数：
  • dryRun：勾选 dryRun 时，返回结果中只返回执行的 SQL 逻辑，但不做执行。
  • 请求参数编辑区：支持您自行编写查询的 SQL 语句，可通过全屏模式进行编辑。
• 返回结果：
  返回结果和上方脚本/向导式测试 API 的返回结果一致，详见脚本/向导式测试 API > 返回结果。
  支持操作：保存返回参数（仅脚本式API出现）；保存为返回示例（保存为该版本API返回示例，自动为成功/失败）

7 发布API

数据服务 API 测试无误后，您可将 API 发布至线上环境和测试环境：

• 测试环境：无需审核，您可直接发布成功。
• 线上环境（PORD 环境）：根据项目配置的信息，如有审核流程，则会触发审核流程，审核通过之后 API 发布至线上环境 。

发布配置参数说明：

8 基本配置

API 的基本配置，打开 API 配置界面，单击右侧导航栏中的基本信息按钮，可对 API 基本信息进行修改：

9 版本信息

在 API 配置界面，单击右侧导航栏中的版本信息按钮，进入 API 历史版本信息界面，展现了当前 API 的版本更新记录情况。

9.1 版本列表

展示当前 API 的版本信息列表，您可单击每个版本号，查看每个版本 API 的配置详情。
在版本列表中，您也可查看 API 每个版本的发布情况与发布环境，同时可下线或删除某个版本，更多操作如下：

9.2 灰度策略

数据服务 API，需要小范围灰度某个版本，其余版本线上不受影响时，此时您可开启 API 灰度策略，灰度某个 API 版本。

1. 单击 API 名称，进入 API 开发配置页面 > 版本信息界面。

2. 在版本信息界面右侧，单击新建策略按钮，进入策略配置界面：
   

   注意

   若为线上环境配置灰度流量，并开启灰度策略，会影响线上调用 API，您需谨慎操作开启。

   配置项	说明
   基础信息
   名称	输入灰度策略的名称信息。
   描述	填写灰度策略描述信息，方便后续维护和查看。
   策略配置
   灰度版本	下拉选择需要切流的版本。
   灰度状态	选择当前策略的开启状态，您可根据实际情况，在合适的时机进行开启或关闭操作。
   灰度策略	目前默认只支持流量灰度的策略。
   灰度比例	设置灰度的 API 版本，需要切流的比例大小。

3. 灰度策略参数配置完成后，单击确定按钮，完成灰度策略新建。

10 API 详情

在 API 配置界面，单击右侧导航栏中的 API 详情按钮，进入 API 详情信息界面，展现了当前 API 的详细配置信息，包含调用信息说明、授权管理、报警配置、调用监控等。API 详情界面说明及操作详见 API 运维。