You need to enable JavaScript to run this app.
导航

API 开发

最近更新时间2023.12.26 20:26:15

首次发布时间2022.07.26 11:41:18

数据服务 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 时,文件夹和 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 必须以<SELECT></SELECT>包裹。
      编辑区上相关快捷按钮的作用如下表所示:

    按钮

    描述

    运行

    在非全屏页面,单击运行按钮后会切换到编辑器全屏页面,在全屏页面,单击运行按钮可解析请求/返回参数,并展现运行后的查询结果和查询日志。

    解析请求参数

    单击解析请求参数按钮后可将 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 的高级参数信息:

    参数

    说明

    数据缓存时间

    缓存策略为返回结果的缓存时间,一共有三种策略:

    • 系统策略:默认策略,默认为 600s
    • 用户自定义:用户可自定义缓存时间,根据实际场景进行设置
    • 关闭:关闭缓存,每次都走实时查询。
  6. 脚本式 API 实现分页操作
    目前 One Service 脚本式实现了查询表的总数返回,您可以根据返回的数据总数来进行分页操作。
    当前只适用于 MySQL 语法类的数据源,且返回的总数是根据用户的 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 的高级参数信息:

    参数

    说明

    数据缓存时间

    缓存策略为返回结果的缓存时间,一共有三种策略:

    • 系统策略:默认策略,默认为 600s
    • 用户自定义:用户可自定义缓存时间,根据实际场景进行设置
    • 关闭:关闭缓存,每次都走实时查询。

    开启分页

    支持存储为 CH、Doris、MySQL、ByteSQL,默认为关闭状态;如开启返回结果分页后,会增加以下公共参数的设置:

    • 公共请求参数
      • pageNum:当前页号。
      • pageSize:页面大小,即每页记录数。
    • 公共返回参数
      • pageNum:当前页号。
      • pageSize:页面大小,即每页记录数。
      • total:总记录数。

4.3 原生式

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

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

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

    参数

    说明

    数据缓存时间

    缓存策略为返回结果的缓存时间,一共有三种策略:

    • 系统策略:默认策略,默认为 600s
    • 用户自定义:用户可自定义缓存时间,根据实际场景进行设置
    • 关闭:关闭缓存,每次都走实时查询。

    开启分页

    支持存储为 CH、Doris、MySQL、ByteSQL,默认为关闭状态;如开启返回结果分页后,会增加以下公共参数的设置:

    • 公共请求参数
      • pageNum:当前页号。
      • pageSize:页面大小,即每页记录数。
    • 公共返回参数
      • pageNum:当前页号。
      • pageSize:页面大小,即每页记录数。
      • total:总记录数。

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 发布至线上环境 。

发布配置参数说明:

说明

预计审批流程发布线上环境通知人配置项,仅发布至线上环境时才需配置。

配置

说明

发布版本

显示当前发布的 API 是第几个版本,显示版本序号。

选择发布环境

您可选择发布环境为线上环境测试环境, 发布至哪个环境,在指定环境中才可以调研该 API,否则调用会显示异常。必选项。

预计审批流程

发布审核流程预览,仅对需要审核的 API 展示。
若项目中开启了 API 发布审批设置,则 API 发布时需要审核,当审核提交后 Lark 通知审核人。

发布线上环境通知人

支持手动配置通知接收用户,系统自动通知下游应用负责人。
API 上线时,您可通知下游服务调用者与 API 协作者,保障服务调用方对变更信息及时获取,可在出现问题快速响应。

发布线上环境原因

填写本次 API 发布的原因。

8 基本配置

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

配置项

说明

API 名称

显示当前 API 的名称信息,您可对其进行相应的修改。

负责人

调整 API 负责人为项目下其他成员。

最大 QPS

设置 API 的最大 QPS,您可根据实际情况,自定义设置调用 API 时最大的 QPS。

安全等级

设置 API 的安全等级,支持设置 L1-公开、L2-内部、L3-秘密、L4-机密 4 种安全等级。

最大 limit

设置 API 查询的最大 limit 数量。

描述

输入 API 的描述信息,方便后续维护管理。

标签

您可以对 API 进行添加自定义标签,用于标识某一类 API,以便快速搜索过滤,操作即时生效,无需重新上线任务。

  • 单击添加按钮,添加标签组信息,下拉选择标签组,及对应的标签信息,支持添加多个标签组。
  • 若没有可选的标签组,您可单击上方创建标签组按钮,进入数据服务 > 系统管理 > 标签管理界面,进行新建标签组操作。详见标签管理。
  • 您也可单击操作栏中的删除按钮,将已添加的标签进行删除操作。

标签添加操作详见标签管理。

9 版本信息

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

9.1 版本列表

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

操作项

说明

下线

当 API 已发布时,单击操作列中的下线按钮,进入下线 API 界面:

  • 当选择下线环境为线上环境时,可配置下线通知人及下线时间,当项目配置中配置了 API 下线审批时,在审批通过后下线策略会生效,并发送下线通知到指定接收人。若项目中没有配置下线审批时,单击确定按钮后,下线策略生效。
  • 当选择下线环境为测试环境时,您可直接单击确定按钮,完成下线。

删除

当 API 处于未发布状态时,单击操作列中的删除按钮,便可将当前未发布的 API 进行删除操作。

发布

API 信息配置完成,保存操作后,您也可在版本信息界面,单击操作列中的发布按钮,将 API 草稿版本进行发布。

版本对比

当 API 有比较多的历史版本记录时,您可同时勾选两个版本的 API,单击版本对比按钮,进行不同版本 API 的对比操作,您可在版本对比中,查看不同版本中不同的配置参数情况。

9.2 灰度策略

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

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

  2. 在版本信息界面右侧,单击新建策略按钮,进入策略配置界面:
    图片

    注意

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

    配置项

    说明

    基础信息

    名称

    输入灰度策略的名称信息。

    描述

    填写灰度策略描述信息,方便后续维护和查看。

    策略配置

    灰度版本

    下拉选择需要切流的版本。

    灰度状态

    选择当前策略的开启状态,您可根据实际情况,在合适的时机进行开启或关闭操作。

    灰度策略

    目前默认只支持流量灰度的策略。

    灰度比例

    设置灰度的 API 版本,需要切流的比例大小。

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

10 API 详情

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