数据API注册/编辑
|
|
· 在API注册时，填写的请求路径不允许和系统中已存在的业务接口路径重复，否则访问的时候会发生错误，如/error、/success等。 · DLH数据源注册时，数据库需选择default，否则在获取数据模式时会失败。 · 用户在调用注册成功的数据API时，默认最多能获取10万条结果。若需要返回更多结果可修改后台配置文件，具体修改方式参见如何修改数据API最大返回结果数。 · 数据API注册时，如果发布的表字段中存储有大文件，当用户访问该数据API时，由于文件较大，可能存在请求响应过慢的问题。所以为了避免影响用户正常使用API，不建议开放此类表字段。 |
数据API通过向导式的设计将数据库表里字段开放出去，以标准restful接口的形式对外提供。
在服务集成模块下选择[API工厂/API管理]，进入API管理页面。
在页面顶部导航栏中选择工作空间，API管理页面显示对应工作空间下的API信息。
API管理页面，单击<API注册>按钮，弹出API设计-类型选择窗口，选择“数据API”，进入数据API设计页面，用户可根据实际需要进行设计。
如果需要修改已创建好的数据API，可单击API列表中“更多”下拉框中的<编辑>按钮进行修改。
配置基本属性：
API名称：配置API名称，系统会自动对API名称进行重复校验，不允许同一工作空间内存在两个相同的API名称，名称只允许输入中英文、数字或下划线，长度限制为3-50个字符。
标签：为API配置标签，用户可在输入框中选择系统内已存在的标签，或者直接单击<新增>按钮，新增一个标签，支持一次为API配置多个标签（最多5个）。
描述信息：API的描述信息，长度限制为不超过200。
所属目录：选择API所属的目录。API创建完成后将展示在对应目录下。
图标：配置API的图标。可选择系统默认图片或者本地上传图片。
版本号：系统做了API版本管理的功能，所以API的版本号不允许重复。
版本描述：当前版本的描述信息，长度限制为不超过255。
参数配置：
请求路径：以“/”开头的自定义访问路径，且只能包含字母、数字、“-”、“_”“.”、“/”，如“/api/v1.0/api-test”。
开启认证：默认是开启认证的，开启认证后，用户在授权时需选择静态认证或动态认证；如果不开启认证，则在授权时无需选择认证方式，用户在实际使用该API时也无需进行认证。
开启健康检查：配置是否开启健康检查，开启后，系统后台会定时检查API健康情况，同时会在API列表中展示API最新状态（正常、异常）；如果API状态异常，系统还会发送告警信息。如果未开启健康检查，API列表中的健康状态会展示为“未知”。
请求方式：可选GET或POST。
请求参数格式：默认都是json格式。
返回参数格式：默认都是json格式。
数据源：需要选择系统内添加的数据源，这里支持的数据源类型目前包含MySQL、PostgreSQL、Presto、Oracle、SQL Server、达梦、Vertica、Impala，DB2、SeaSQL MPP、UXDB、DLH、MySQL8、Greenplum、ClickHouse、HBase Phoenix等，数据源的管理请参见数据源管理模块对应介绍。
数据库：选择要发布的数据库。DLH数据源注册时，数据库需选择default，否则在获取数据模式时会失败。
数据模式：选择要发布的数据库里面的模式。
数据表：选择要发布的数据库里面的表。
开启分页查询：如果开启了分页查询，SQL在执行的时候，会自动拼接分页参数进行分页查询。开启分页查询后，接口请求时需要传递分页参数。当前仅Vertica、MySQL、MySQL 8、PostgreSQL、SeaSQL MPP、SQL Server 2005及以上版本、GreenPlum、Oracle数据源支持开启分页查询。
关联条件：关联条件的配置用于多表关联查询，可以将两张表的字段做关联，这里支持的关联方式包括LEFT JOIN、INNER JOIN以及RIGHT JOIN等。如果只需要查询一张表的字段信息，则不需要配置关联条件。
选择操作模式：数据API支持自定义SQL语句和字段筛选两种方式发布，自定义SQL语句可以实现复杂的SQL查询，字段筛选方式是以开放字段的方式发布，API授权和订阅时可以勾选需要订阅的字段。当选择自定义SQL语句时，支持在线SQL执行、SQL格式化以及SQL选中执行（执行光标选中的部分）。
SQL语句：选择自定义SQL方式发布后，可以选择字段，在选择字段的时候，可以看到字段名、所属表、类型以及字段描述，这里可以选择过滤列来作为筛选条件，支持AND和OR。选择完字段后会自动生成一条SQL语句。生成的SQL语句支持编辑，可以编写复杂的SQL语句进行查询，SQL语句中输入参数解析规则以英文冒号开头，例如“select id, name from table where id =:id”。
用户自定义SQL语句时，可根据实际情况配置参数是否必填，或者选择模糊查询。常见情况举例如下：
必填参数语法，如下SQL所示，必填参数直接用“=”连接。
|
select id, name from table where id =:id |
非必填参数语法，具体使用方法可参照如下示例。如下SQL分别列举了整型、字符串类型、布尔类型、时间类型等非必填参数设置方法。注意：Vertica数据源非必填参数都必须通过cast进行转换。
|
SELECT "ability_base"."id", "ability_base"."ability_name", "ability_base"."ability_desc", "ability_base"."ability_status", "ability_base"."create_by", "ability_base"."create_time" FROM "public"."ability_base" where 1 = 1 and (:id is null or "ability_base"."id" = :id) and (:name is null or "ability_base"."ability_name" = :name) and (cast(:time as timestamp) is null or "ability_base"."create_time" > :time) and (:bool01 is null or "ability_base"."bool01" = :bool01) and (cast(:date01 as date) is null or "ability_base"."date01" >= :date01) and (cast(:dtime01 as time) is null or "ability_base"."time01" >= :dtime01) |
Vertica数据源非必填参数都必须通过cast进行转换，具体使用方法可参照如下示例：
|
SELECT "ability_base"."id", "ability_base"."ability_name", "ability_base"."ability_desc", "ability_base"."ability_status", "ability_base"."create_by", "ability_base"."create_time" FROM "public"."ability_base" where 1 = 1 and (cast(:id as int) is null or "ability_base"."id" = :id) and (cast(:name as varchar) is null or "ability_base"."ability_name" = :name) and (cast(:time as timestamp) is null or "ability_base"."create_time" > :time) and (cast(:bool01 as boolean) is null or "ability_base"."bool01" = :bool01) and (cast(:date01 as date) is null or "ability_base"."date01" >= :date01) and (cast(:dtime01 as time) is null or "ability_base"."time01" >= :dtime01) |
非必填参数的in查询。在SQL中，in查询用于查找某个列中包含在指定值列表中的行，具体使用方法可参照如下示例：
|
select "time_table"."id" as "id", "time_table"."nowtime" as "nowtime", from "H3C"."time_table" where 1 = 1 and (COALESCE(:id) is null or "time_table"."id" in (:id)) |
模糊查询语法，具体使用方法可参照如下示例：
select id, ability_name from ability_base where ability_name like concat('%',:name,'%')
如果某种数据源concat方法不支持三个参数，如Vertica，可参考如下写法：
select id, ability_name from ability_base where REGEXP_LIKE ("ability_name",: name)
Impala复杂数据类型的查询。Impala数据源表结构使用复杂类型，用户自定义SQL语句时复杂类型需要修改生成的SQL语句。
表结构示例如下：
|
CREATE TABLE array_demo ( id BIGINT, name STRING, pets ARRAY <STRING>, employee_info STRUCT < employer: STRING, id: BIGINT, address: STRING >, ancestors MAP < STRING, STRING > ) STORED AS PARQUET; |
ARRAY类型查询语句示例：
|
SELECT id, name, pets.pos, pets.item FROM array_demo, array_demo.pets; |
STRUCT类型查询语句示例：
|
SELECT id, name, employee_info.employer,employee_info.address,employee_info.id as employee_info_id FROM array_demo ; |
MAP类型查询语句示例：
|
SELECT id, name, ancestors.key, ancestors.value FROM array_demo, array_demo.ancestors ; |
SQL分页语法，具体使用方法可参照如下示例。所有数据源均支持分页功能，通过配置请求头参数pageNum（每页条数）和pageSize（页数）即可实现分页效果。注意：请求头参数pageNum和pageSize需设置为Integer类型。
MySQL：
|
select id, name from table limit :pageSize offset :pageNum |
Oracle：
|
SELECT Id,name FROM (SELECT ROWNUM rm ,a.* FROM T_A a WHERE ROWNUM <=:pagenum * :pagesize) page WHERE page.rm >=(:pagenum-1)*:pagesize+1 |
PostgreSQL：
|
select id, name from table limit :pageSize offset :pageNum |
Vertica：
|
select id, name from table limit :pageSize offset :pageNum |
达梦：
|
select id, name from table limit :pageSize offset :pageNum |
Impala：
|
select id, name from table limit :pageSize offset :pageNum |
输入/输出参数：SQL语句编写完成后，单击<生成参数>，可以生成输入输出参数。
如果SQL语句中设置的是非必填参数，在输入参数列表中，需要将该参数设置为非必填。
根据输入参数的字段类型来选择数据类型，目前支持的字段类型包括string、integer、long、float、double、bit、numeric、boolean、date、time、timestamp等，输出参数的类型按string来处理。
可以填写每个字段的描述信息，方便用户使用接口的时候清楚每个字段的含义。
SQL语句编写的时候可以对数据表的字段设置别名，通过添加as的方式实现。这样单击<生成参数>后，输入参数和输出参数都以别名展示。
如果自动生成的输入参数和输出参数不准确，可以手动的去增加、删除以及修改参数。
可以选择函数（f(x)表达式）对输入/输出参数进行处理，将参数值替换为函数处理后的结果。单击<编辑>按钮，进入编辑表达式窗口，可查看函数列表及函数的具体使用方式。双击函数名称，窗口右侧会展示函数含义及具体使用方法，下方表达式中会自动填充函数语法，用户需根据实际需要进行修改。
字段列表：如果数据API发布方式选择字段筛选，则需要选择开放的字段，单击<选择字段>，可以看到字段名、所属表、类型以及字段描述，勾选需要开放出去的字段，单击<确定>按钮。在字段列表可以查看开放出去的字段，包括字段名称、所属表、字段别名、数据类型、字段描述，输入参数按钮和输出参数按钮可以控制该字段是否要作为输入或者输出参数，一个字段可以同时打开输入参数和输出参数按钮。字段别名和字段描述可以根据实际情况进行编辑。
筛选条件：数据API发布方式可以选择字段筛选，在选择完需要开放的字段后，可以设置筛选条件，该条件为非必填项，筛选条件格式要求以where开头，例如“where id > 3”，在接口查询时，会加上默认的筛选条件，只查询id > 3的数据。单击<下一步>可以进行基本属性和参数配置的预览。
在预览页面，用户可以查看已填写API的基本信息、参数配置信息以及数据来源，如果没有问题就可以单击<保存>，这样就可以完成数据API的注册，保存后的API在API列表中的状态为“待测试”。