apiSQL快速入门
1.1 平台操作流程
温馨提示:在网站首页,注册登陆平台后,建议先看【演示项目】,先看简单的 [行政区域] 示例、再看常用的 [SQL类型] 和 [JS类似] 示例,最后看 [最佳实践] 示例,感受一下系统主要功能。
1.2 客服支持
在使用过程中如需帮助,请通过下列方式联系我们
微信扫一扫,添加工作人员的微信时,请备注:APISQL,拉你入用户群。
1.3 文档更新
对于内网环境下的用户,您可以离线使用本PDF版帮助文档。这些文档可能会过时,无法反映最新的功能和信息。如果用户想要查看最新的文档,请用浏览器访问平台的官方网站 http://www.apisql.cn
2.1 注册
APISQL云平台的注册地址:https://open.apisql.cn/ui/register
邮箱不用认证
登陆后如下界面
2.2 体验演示项目
可以先体验一下演示项目
【运行】一个已发布的API
切换到【接口设计】,可以看到SQL脚本很简单:SELECT * FROM area
再进一级,只是使用一个参数【:province_name】,参数类似是string,值为:广东省
3.1 创建项目
创建一个【测试项目】
3.2 安装网关
数据网关 中【新建网关】,勾选 示例数据 就是上一章看到,包含一个SQLite数据库的行政区域表
根据您的操作系统,下载相应的客户端程序。以下以Windows平台为例。
下载安装客户端时,会有如下提示,选择仍要运行
填写上文的值
APISQL_NODE_ID(网关ID)
APISQL_NODE_TOKEN(网关Token)
选择要安装的位置,下一步
下一步
完成
3.3 增加数据源
刷新平台,看到运行时,就可以增加数据源了
选择你的MySQL类、PostgreSQL类、SQL Server、Oracle、SQLite数据库,后续根据用户需求和反馈放,支持更多国产信创数据库、OLAP分析型数据库、NoSQL型数据库;以及开放数据源的功能,支持用户以插件方式连接更多的数据源。
可选配置,支持开发、生产多环境的场景。
4.1 创建API接口组
新建一个API接口组
4.2 调试SQL
接口设计,配置个接口路径、然后编辑调试SQL
这里是调试SQL界面
- 左侧: 查询网关、数据库、表名、字段;
- 上侧: 选择数据源;
- 中间: SQL编辑区,
- 右侧: SQL参数修改区;
- 下侧: 执行结果
4.3 SQL参数
您可以在SQL语句中使用【:】后跟参数名称来定义参数,然后在 右侧 的 【SQL参数】 区域选择相应的 【数据类型】
【默认值】:会影响正式开发的API和调试界面;当参数为空会提示"message": "参数异常,缺少参数 'xx'"。
【示例值】:只用于接口调试界面使用给开发人员使用,优先级更高。
SQL调试器编辑完成即可发布,但不能被调用,出于安全原则,必须指定访问策略,详见下一章节。
API 访问控制策略对于保护数据和确保系统安全至关重要。通过适当的身份验证、限制访问及密钥管理等方法,可以实现有效的 API 访问控制。防止未经授权的个人或系统对数据进行修改、删除或盗取。
访问控制策略是与API组分开设置的,您需要将访问控制策略与API组进行绑定,才能使该策略对该API组有效。
5.1 新建策略
认证类型
不鉴权(公开): 接口组中的所有接口将不再验证访问者身份(任何人可访问), 多用于初期测试,请务必注意数据安全。
API key: API Key 会创建一个秘钥,接口访问时携带此秘钥即可。将此秘钥分享给第三方,可实现快速对接。
IP鉴权: 允许某些IP地址访问,可用于有固定IP的用户/应用服务,如公网上部署的应用服务。
平台用户: 平台用户可通过平台账户直接调用接口,一个用户只能创建一个策略。适用于已在平台注册的用户。
5.2 绑定API组
一个访问控制策略可以绑定多个API组,若同一个API组被绑定到多个访问策略,则按照认证类型的优先级 不鉴权(公开) > IP鉴权 > 平台用户 > API key 依次验证访问权限,直至拥有访问权限。
这里绑定刚设计的API组
以下介绍两种常见的测试API接口方式,用户根据自己习惯任选一种。 我们为您提供了两种常用的测试API接口的方法,您可以根据自己的喜好选择其中一种。
6.1 平台自带的接口调试工具
使用APISQL云平台自带API接口调试工具,特点是简单,支持设计API时所用的参数。 在单个API接口的 概览 界面,点击 运行。
点击 搜索,查看该API支持的所有请求参数,示例值:填写一个测试的参数。
点击 【运行】 查看执行结果的JSON和HTTP信息
点击 认证信息, 切换认证方式,不鉴权(公开)、IP鉴权无须填写;API key、平台用户及密码认证需填写对应信息;
点击 【查看HTTP信息】 可以查看HTTP的参数信息
最常用的 API key认证 秘钥,是在【访问控制】->【创建访问控制策略】->【复制】获取,不要忘记 绑定API组,这个API组才能使用该秘钥访问。
IP鉴权如下,使用是当前上网的IP地址,当前上网的IP可通过如www.ipip.net查看。
6.2 第三方接口调试工具
这里使用一个替代Postman的开源接口调试工具: https://hoppscotch.io ,初次打开网站, 设置 -> 选择 语言 和 启用 代理中间件发送请求
出于安全优先的原则,APISQL默认所有请求都是POST以请求,以HTTPS加密,HTTP2传输,所以我们这里选择POST。
请求的**【参数】** 是以json格式放在 请求体 中,如下:
{
"params": {"id": 1}
}
API key认证 秘钥在【访问控制】->【创建访问控制策略】->【复制】获取。
然后将API Key放 【请求头】 中,注意有Bearer前辍后面还有个空格,(这是一种常见的认证方式,表示您使用的是API key,空格是为了区分前辍和秘钥)格式如下。
"Authorization": "Bearer sk-e225739e757138943774899fcdd1acda"
在没有配置API Key就发送,会收到类似“BAD_TOKEN”的提示,如下图所示, 所以在调试时可以跟据对应的错误提示,知道是哪方面的问题,再进行对应配置即可。
对于API接口管理,文档是少不了,方便以后一目了然的知道接口干什么的。
文档是以Markdown方式保存至平台(Markdown是一种轻量级的标记语言,可以方便地编写和格式化文本,支持标题、列表、表格、代码块等多种元素),方便同事一起查阅和修改。
到此,您应该已经掌握了如何使用APISQL主要功能,来快速设计和管理您的API接口,希望这些能够帮助您提高开发效率和设计出更安全的API。