向导模式开发API
服务开发支持以向导模式开发API,无需编写代码即可完成服务开发和发布。
操作步骤
- 登录平台,进入数据服务,选择“服务开发”。
- 在目录区域选中需要生成API的分组,点击右侧的添加图标,选择“生成API”。在“生成API”弹窗选择API模式为“向导模式”。
配置基本信息
填写API名称、API路径、请求方式、返回类型、标签、描述等信息,上述信息的约束如下:
字段 | 说明 |
---|---|
API名称 | 支持中文、英文、数字、下划线(_),且只能以英文或汉字开头。API名称不可重复。 |
API路径 | API的请求路径。例如/user/userinfo。 支持英文、数字、下划线(_)和连字符(-),必须以“/”开头,不能以“/”结尾,不能有连续“/”。 |
请求方式 | 可选择GET或POST。 |
返回类型 | 可选择JSON类型。 |
标签 | 最多输入5个标签,标签长度不超过32字符。 |
描述 | 最多输入255字符。 |
配置数据资源
配置前需在数据源管理模块添加数据源的配置信息,相关操作可参见数据源概述模块。此处需选择数据源类型、数据源名称、数据库、数据表等信息。数据源类型当前支持MySQL、Oracle、Doris。
参数配置
选择数据资源后,所选表的字段信息将显示在参数配置区域,用户可勾选字段设置为请求参数、返回参数、排序字段和过滤字段,勾选后的字段将显示在对应的参数区域。
配置请求参数
设为请求参数的字段将显示在请求参数区域,可配置参数名称、参数类型、比较方式、是否必填、示例值、默认值、描述等信息。
配置返回参数
设为返回参数的字段将显示在返回参数区域,可配置参数名称、示例值、描述、脱敏配置等信息。
配置排序字段
设为排序字段的字段将显示在排序字段区域,可配置字段的排序方式,并支持对排序字段进行上移、下移、删除等操作。
过滤配置
设为过滤字段的字段将显示在过滤配置区域,支持按列设置过滤规则,可添加一或多组条件,条件默认为AND关系。
高级配置
可配置API的超时时间、分页逻辑和缓存逻辑。
超时时间默认为1000ms,用户可手动修改。
若用户设置“返回结果分页”为“是”,可设置每页条数,每页条数最大为2000。当返回结果记录数大于2000时请选择分页,不分页则最多返回500条记录。
支持配置缓存时间和缓存条数,配置缓存逻辑后在缓存时间内如果被相同的请求参数调用,接口将会返回已缓存的结果,缓存条数为最大缓存条数,超过将自动清理旧的缓存数据。缓存数据会占用服务资源组的内存大小,请合理配置缓存参数。
脚本模式开发API
服务开发支持以脚本模式开发API,支持手动编辑API的查询SQL语句,满足个性化发布API的需求。
操作步骤
- 登录平台,进入数据服务,选择“服务开发”。
- 在目录区域选中需要生成API的分组,点击右侧的添加图标,选择“生成API”。在“生成API”弹窗选择API模式为“脚本模式”。
配置基本信息
填写API名称、API路径、请求方式、返回类型、标签、描述等信息,上述信息的约束如下:
字段 | 说明 |
---|---|
API名称 | 支持中文、英文、数字、下划线(_),且只能以英文或汉字开头。API名称不可重复。 |
API路径 | API的请求路径。例如/user/userinfo。 支持英文、数字、下划线(_)和连字符(-),必须以“/”开头,不能以“/”结尾,不能有连续“/”。 |
请求方式 | 可选择GET或POST。 |
返回类型 | 可选择JSON类型。 |
标签 | 最多输入5个标签,标签长度不超过32字符。 |
描述 | 最多输入255字符。 |
配置数据资源
配置前需在数据源管理模块添加数据源的配置信息,相关操作可参见数据源概述模块。此处需选择数据源类型、数据源名称、数据库、数据表等信息。数据源类型支持MySQL、Oracle、Doris。
编写查询SQL
可在此区域填写SQL查询语句。SELECT算子中的字段即API的返回参数,WHERE条件处的参数即API的请求参数,可使用#{}标识请求参数。
输入SQL语句时,需要遵循以下规则:
1)支持同一数据源下的单表查询、多表关联查询和嵌套查询。
2)不支持以下语句:
- 不支持多条SQL语句。
- 不支持写入注释。
- 不支持INSERT、UPDATE和DELETE等非SELECT语法。
- 不支持SELECT *,必须明确指定查询的列。
- 不支持将#{param}放在引号中。例如' {id}'、'abc {xyz}123'。如果有相关需求可通过concat('abc', #{xyz}, '123’)实现。
- 不支持设置参数为可选。
3)如果SELECT查询列的列名带有表名前缀(例如t.name),则必须取别名作为返回参数名(例如t.name as name)。
4)如果使用聚合函数(min、max、sum和count等),必须取别名作为返回参数名。例如sum(num) as total_num。
5)SQL中的#{param}统一作为请求参数进行替换,包含字符串中的#{param}。当#{param}前包含转义符(\)时,作为普通字符串处理。
脚本模式部分SQL可自动解析请求参数和返回参数,不支持解析请求参数和返回参数的需用户根据编写的脚本手动配置请求参数和返回参数信息。
配置请求参数
可手动添加一行或多行请求参数,配置参数名称、参数类型、比较方式、是否必填、示例值、默认值、描述等信息。点击操作栏的【删除】可删除已添加的请求参数。
配置返回参数
可手动添加一行或多行返回参数,配置参数名称、参数类型、示例值、描述、脱敏配置等信息。点击操作栏的【删除】可删除已添加的返回参数。
高级配置
可配置API的超时时间和分页逻辑,超时时间默认为1000ms,用户可手动修改。若用户设置“返回结果分页”为“是”,可设置每页条数,每页条数最大为2000。当返回结果记录数大于2000时请选择分页,不分页则最多返回2000条记录。
注册API
若用户已有API,也可以通过注册功能,将API通过数据服务平台进行统一管理。在API列表页面点击注册API可进行注册,注册API包含三个步骤:填写基础信息、参数配置以及功能测试。
操作步骤
- 登录平台,进入数据服务,选择“服务开发”。
- 在目录区域选中需要生成API的分组,点击右侧的添加图标,选择“注册API”。
配置基本信息
填写API名称、API路径、请求方式、返回类型、标签、描述等信息,上述信息的约束如下:
字段 | 说明 |
---|---|
API名称 | 支持中文、英文、数字、下划线(_),且只能以英文或汉字开头。API名称不可重复。 |
API路径 | API的请求路径。例如/user/userinfo。 支持英文、数字、下划线(_)和连字符(-),必须以“/”开头,不能以“/”结尾,不能有连续“/”。 |
请求方式 | 可选择GET或POST。 |
返回类型 | 可选择JSON类型。 |
标签 | 最多输入5个标签,标签长度不超过32字符。 |
描述 | 最多输入255字符。 |
配置后端服务
需填写所注册API的后台服务Host、后台服务Path、后台超时时间等信息。
配置请求参数
可手动添加一行或多行请求参数,配置参数名称、参数类型、是否必填、示例值、默认值、描述等信息。点击操作栏的【删除】可删除已添加的请求参数。
配置内容返回实例
可在正常返回结果示例区域和异常返回结果示例区域填写API的返回结果示例。
配置错误码
可手动添加一行或多行错误码信息,添加后需配置错误码、错误信息、解决方案等信息。点击操作栏的【删除】可删除已添加的请求参数。
测试API
API逻辑配置完成后,点击【保存】,并点击【测试】进行API测试,测试通过的API才可以进行发布。
发布API
点击【发布】,并填写版本说明,即可将API发布上线。
查看API详情
- 登录平台,进入数据服务,选择“服务开发”。
- 在目录区域选中需要查看详情的API,点击【详情】操作,可在右侧界面中查看API的配置详情。
查看API版本
- 登录平台,进入数据服务,选择“服务开发”。
- 在目录区域选中需要查看版本的API,点击【版本】操作,可进入API的版本历史页面。支持查看历史版本详情、版本对比和历史版本回滚。
复制API
- 登录平台,进入数据服务,选择“服务开发”。
- 在目录区域选中需要复制的API,点击【复制】操作,可在“复制API”弹窗中填写新API的属性信息,填写完毕后点击【确定】按钮,即可创建和原API配置相同的API。