apiSQL

Appearance

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）

网关ID、网关Token

选择要安装的位置，下一步

安装位置

下一步

安装中

完成

安装完成

3.3 增加数据源 ​

刷新平台，看到运行时，就可以增加数据源了 增加数据源

选择你的MySQL类、PostgreSQL类、SQL Server、Oracle、SQLite数据库，后续根据用户需求和反馈放，支持更多国产信创数据库、OLAP分析型数据库、NoSQL型数据库；以及开放数据源的功能，支持用户以插件方式连接更多的数据源。

可选配置，支持开发、生产多环境的场景。

数据源连接

4.1 创建API接口组 ​

新建一个API接口组 新建API接口组

4.2 调试SQL ​

接口设计，配置个接口路径、然后编辑调试SQL API设计

这里是调试SQL界面

  • 左侧： 查询网关、数据库、表名、字段；
  • 上侧： 选择数据源；
  • 中间： SQL编辑区，
  • 右侧： SQL参数修改区；
  • 下侧： 执行结果

SQL调试器界面

4.3 SQL参数 ​

您可以在SQL语句中使用【:】后跟参数名称来定义参数，然后在 右侧 的 【SQL参数】 区域选择相应的 【数据类型】

【默认值】：会影响正式开发的API和调试界面；当参数为空会提示"message": "参数异常,缺少参数 'xx'"。

【示例值】：只用于接口调试界面使用给开发人员使用，优先级更高。 SQL参数说明

SQL调试器编辑完成即可发布，但不能被调用，出于安全原则，必须指定访问策略，详见下一章节。

带参API设计完成

API 访问控制策略对于保护数据和确保系统安全至关重要。通过适当的身份验证、限制访问及密钥管理等方法，可以实现有效的 API 访问控制。防止未经授权的个人或系统对数据进行修改、删除或盗取。

访问控制策略是与API组分开设置的，您需要将访问控制策略与API组进行绑定，才能使该策略对该API组有效。

5.1 新建策略 ​

认证类型

  • 不鉴权(公开)： 接口组中的所有接口将不再验证访问者身份(任何人可访问)， 多用于初期测试，请务必注意数据安全。 不鉴权(公开)策略

  • API key： API Key 会创建一个秘钥，接口访问时携带此秘钥即可。将此秘钥分享给第三方，可实现快速对接。 API key策略

  • IP鉴权： 允许某些IP地址访问，可用于有固定IP的用户/应用服务，如公网上部署的应用服务。 IP鉴权策略

  • 平台用户： 平台用户可通过平台账户直接调用接口，一个用户只能创建一个策略。适用于已在平台注册的用户。

5.2 绑定API组 ​

一个访问控制策略可以绑定多个API组，若同一个API组被绑定到多个访问策略，则按照认证类型的优先级 不鉴权(公开) > IP鉴权 > 平台用户 > API key 依次验证访问权限，直至拥有访问权限。

这里绑定刚设计的API组 绑定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查看。 IP鉴权认证

6.2 第三方接口调试工具 ​

这里使用一个替代Postman的开源接口调试工具： https://hoppscotch.io ，初次打开网站， 设置 -> 选择 语言 和 启用 代理中间件发送请求hoppscotch设置

出于安全优先的原则，APISQL默认所有请求都是POST以请求，以HTTPS加密，HTTP2传输，所以我们这里选择POST。 POST

请求的**【参数】** 是以json格式放在 请求体 中，如下：

{
    "params": {"id": 1}
}

请求体

API key认证 秘钥在【访问控制】->【创建访问控制策略】->【复制】获取。

复制秘钥

然后将API Key放 【请求头】 中，注意有Bearer前辍后面还有个空格，（这是一种常见的认证方式，表示您使用的是API key，空格是为了区分前辍和秘钥）格式如下。

"Authorization": "Bearer sk-e225739e757138943774899fcdd1acda"

请求头

在没有配置API Key就发送，会收到类似“BAD_TOKEN”的提示，如下图所示， 所以在调试时可以跟据对应的错误提示，知道是哪方面的问题，再进行对应配置即可。 未填写请求头报错

对于API接口管理，文档是少不了，方便以后一目了然的知道接口干什么的。 API文档

文档是以Markdown方式保存至平台（Markdown是一种轻量级的标记语言，可以方便地编写和格式化文本，支持标题、列表、表格、代码块等多种元素），方便同事一起查阅和修改。 API文档以Markdown方式编辑

到此，您应该已经掌握了如何使用APISQL主要功能，来快速设计和管理您的API接口，希望这些能够帮助您提高开发效率和设计出更安全的API。

Copyright © 2022 - present apisql (V:1.0.16-B250527)