查询API

1 概述

1.1 版本

1.2 应用场景

用户需要将数据封装成API接口，供外部系统调用，并提供一系列与数据相关的服务。

2 功能入口

点击「数据服务>API管理」，可进行API的管理。如下图所示：

2 功能简介

API管理主要用于将数据通过 API 形式发布出去，供其他应用场景进行使用。

4 功能说明

新建一个 API 后，需要 4 步即可完成该 API 的设计，具体包括：基本信息、取数来源、API授权、API测试。

4.1 基础信息

基本信息包括请求方式、路径、超时时间等配置，如下图：

功能说明如下：
1、请求方式
支持GET和POST两种请求方式，其中，POST请求是通过Body传入参数，GET请求是通过URL传入参数（QueryParam）。
2、请求Body格式
请求方式为“POST”的特有配置，需要指定请求的Body格式，即请求Content-Type，支持两种格式：application/json、application/x-www-form-urlencoded。
3、路径
API对外发布的API路径，由头部固定格式+自定义路径组成：
固定格式：oapi/dataService/${API集key}/，其中API集key是该API绑定API集时产生的，显示的是对应API集的内部名称。
自定义路径：允许用户自定义的路径内容，支持输入小写字母、数字、下划线（_）、连字符（-）、正斜杠（/），不能以/开头或结尾。
4、超时时间
指的是调用接口时响应超时时间，如果在指定时间后仍没有返回查询结果，则接口返回超时错误。

4.2 取数来源

4.2.1 来源配置

支持两种来源：数据连接和数据集。

4.2.1.1 数据连接

1、数据源
可选择当前应用内配置的数据连接，目前支持的连接类型包括：MySQL、SQL Server、Oracle、达梦、PostgreSql、PolarDB O、ClickHouse、华为Gaussdb、其他JDBC。

2、配置方式
支持两种配置方式：表/视图、SQL。
1） 表/视图
该方式是直接选择对应数据库中的表或视图进行取数，支持对数据进行简单的过滤。

①选表/视图
显示所选数据连接中对应的表和视图，用户可搜索需要的表或视图，选择即可。

②数据过滤
可过滤来源表的数据，使用所选数据库的语法编写 WHERE 条件语句（无需填写 WHERE 关键字），参数的写法为：${参数名称}。如下图：

提供字段和自定义变量的选择，可快速引用表字段和自定义变量。

2） SQL

该方式是通过SQL语句从源数据库的表中查询取数，参数的写法为：${参数名称}。

左侧显示所选数据连接中对应的表和视图，用户可选择指定的表或字段添加到右侧的SQL输入框中，如下图所示：

SQL语句支持最大化窗口进行编辑，点击SQL输入框中右下角的最大化按钮，即可进入，如下图：

3、请求参数配置
实时解析数据过滤或SQL中的参数，显示在请求参数列表中，参数去重显示。如下图：

功能说明如下：

4.2.1.2 数据集

1、数据源
支持选择当前应用下JDBC、http查询和存储过程类型的数据视图。

2.数据集参数
显示所选数据视图中包含的所有参数，支持参数启用/禁用、参数值配置，主要用于请求参数的定义。
参数值支持常量和表达式，允许定义请求参数，也是${参数名称}，用来接收请求参数的值用于数据查询。
参数值非请求参数时，最终将根据此处设置的默认值进行数据查询。

注：http查询和存储过程类型的数据视图的参数均是启用，不可禁用。

3、请求参数配置
实时解析数据集参数中同时满足以下条件的参数：
1）参数是启用状态；
2）参数值类型为“表达式”；
3）值内容中含${参数名称}。
解析出来的请求参数功能同“数据连接”类型的请求参数。

4.2..2 返回字段配置

若配置了请求参数，点击[获取]按钮，将显示参数设置窗口，如下图：

有设置默认值则显示对应的默认值，请求参数中设置为必填的参数比如输入参数值，才能获取返回字段。

注：若参数选填，此处参数值内容为空，相当于剔除该参数进行查询。

无请求参数参数则直接执行对应SQL或数据视图即可获取到对应的字段。
获取到的字段默认全部输出，可更改输出字段名称和描述，不需要输出的字段取消“输出”的勾选状态即可。

返回字段支持数据预览和更新字段操作。
1）数据预览
无请求参数时，点击[数据预览]可直接查询输出字段对应的数据，如下图：

若有请求参数，则数据预览时需要先设置对应的参数值才能查询数据。
2）更新字段
数据源字段若有变更，可点击[更新字段]重新获取字段返回字段。

4.3 API授权

API 若想被调用必须绑定API集，API配置时可以暂时不绑定，后续在API集中绑定（若已有API集，也可在此步骤中绑定API集）。
支持添加、解绑和批量配置的操作。
1）添加
一个API可以绑定多个API集，点击[添加]可选择该应用下的API集进行绑定。

2）解绑
通过单个解绑或批量解绑操作，可解除该API与对应API集的授权关系。
3）批量设置
勾选已绑定的 API，点击「批量设置」，可以对 API 的授权有效期和 API 被访问的频率进行设置，如下图所示：

配置项说明如下：

4.4 API测试

用户可通过API测试对API接口进行调试，查看接口执行情况。

测试API集：若“API授权”步骤中绑定了API集，则此处需要选择绑定的其中一个API集进行测试。
API地址：根据配置的请求方式及路径自动生成对应的API地址。
参数信息
1）请求方式为“GET”时：
左侧「Params」列表展示了参数名和参数值，参数名中包含了固定参数和请求参数。

• 分页参数：pageNum、pageSize；
• 请求参数：由用户于「请求参数配置」中设置的参数；
• 应用参数：volumeName，显示当前应用的内部名称。

输入对应参数值后，点击「测试」，即可于右侧「返回内容」处查看执行结果。

2）请求方式为“POST”时：
左侧含有「Body」和「Headers」两个tab，「Body」中显示分页参数和请求参数，「Headers」中显示该API的请求body格式和当前应用的内部名称。

5 API上线

API测试无误后，用户点击完成即可查看该API的详情。

新建的API默认为“下线”状态，在右上角点击“上线”即可将该API上线，有访问权限的外部系统通过对应认证后即可访问该API。
若用户需变更其相关信息，则需先通过“下线”操作”将该API下线，再点击“编辑”进修改。