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