操作手册

用户准备

用户添加进机构安全组

新建用户使用云原生数据服务平台（Data Service，以下简称DS），需确保该用户在KDP中存在于一个机构安全组。下面演示新建机构且将其加入机构安全组步骤：

添加机构类型安全组

jpg

激活安全组

jpg

添加用户进入机构安全组

jpg
具体操作，详见KDP操作手册。

用户同步

新增用户登录云原生数据服务平台后，需先通过「用户管理」页面进行用户数据同步，避免在API管理中设置白名单时出现用户信息未补全问题。
png

首页

DS系统首页是数据服务大厅，页面实现API的浏览、筛选（已上线、未上线API）、搜索及排序（当前页面内容），用户可在界面点击具体API跳转API详情页，查看任意API的详细信息。

API 状态颜色标注说明：

类目	描述
红色	待提交、已驳回
橘色	正在审核
绿色	审核通过、已发布

监控面板

系统支持用户自定义监控面板。系统提供筛选图表包括：返回状态分布、请求 URL 分布、API 请求数、请求平均时延（毫秒）、请求时延分布（毫秒）、数据服务请求类型分布、用户请求返回数据总大小分布和用户请求数分布的组合图表展示，用户可根据需要选取监控面板的展示内容。同时用户可在当前展示界面，通过时间范围、刷新间隔、API 名称、用户名称及 IP 等组合条件进行 API 监控筛选。

API管理

系统支持用户进行 API 创建，查看，编辑，测试，发布等操作。用户可对相关API的列表进行多选/全选，从而进行批量添加标签操作。添加成功后会显示在列表。列表按API创建时间先后进行排序。用户可对标签进行单个/批量删除。

注：

管理员权限用户可对标签进行单个/批量更改、删除等操作，删除标签后会自动解除标签和 API 的关联关系。
标签名称建议增加创建时间，标签名称不可重复，与删除后的标签名称也不可重复。

API 创建-发布流程：

序号	类目	描述
1	创建、编辑	创建或编辑 API
2	测试	对创建或编辑过的 API 进行测试（更改 API 标签则无需重新测试）
3	提交审核	测试结果达到预期可提交审核（系统管理员权限用户可在【审批者管理】界面对 API 审批人员进行管理）
4	发布	审批人批准审核后，即可发布 API

创建API

点击右上方「创建 API」，用户可通过简单的配置信息创建 API，并提供数据服务。本系统使用 KONG 的 JWT 和 Rate Limit 插件来实现访问控制，用户可通过 API 访问控制或JWT 验证对创建的 API 进行访问流量限制。系统支持基于已添加的数据源，进行数据集配置。

API基础信息

条目	内容	描述
API 名称*		用户自定义
API 分组*		用来区分 API 类别（创建 API 时需先选择/创建 API 分组）
请求方式	默认 GET	支持 GET ，POST请求
API 路径*		支持最多五级 path 如格式：/aaa/bbb/ccc/ddd/eee
描述		用户自定义

注：在配置 API 路径时，DS系统保留了如下的系统路径，用户不可使用以此开头的路径：

/test
/mysql
/redis
/config
/api
/es
/pgsql
/oracle
/clickhouse
/dameng

API标签
系统支持选择已有标签，或者点击「+」，新增相应的标签。

条目	内容	补充
新建标签	下拉框选择已有的标签或新建标签	方便用户通过标签进行搜索目标API

数据集配置
【数据集配置 - 以MySQL为例】

系统支持用户通过界面简单配置，创建基于 MySQL 为数据源的 API，并提供对 MySQL 数据集的异步查询功能。

支持使用自定义sql，在语句中可使用${x}用作url中传参’x’。语句中不可出现分号”;”，会导致执行报错。

请求参数和返回参数
当数据集配置完毕，选定数据表之后，即可对请求参数和返回参数进行配置。通过添加按钮，对数据集需要的字段进行配置。

请求参数：通过选择字段名、编辑API使用的参数名和操作符，设定是否为可选参数，即可为API设定请求参数。如果设定请求参数并关闭可选，该API需要携带请求参数来获取信息。

返回参数同理，如果该API需要特定的参数返回，可在返回参数处设定需要返回的数据表字段名，不配置即默认返回所有。

API访问控制

通过设置，对API的访问进行控制。

条目	内容	描述
每秒	“0”为不限制，用户根据实际需要填入	-
每小时	“0”为不限制，用户根据实际需要填入	-
每天	“0”为不限制，用户根据实际需要填入	-
分配流控	小时区间段额度操作	点击添加按钮，可选取分时流控时间段，规定特定时间段的分配额度
总访问额度	-	设定接口能被调用总次数

JWT验证：JWT验证是JSON Web Token，是一种跨域身份验证解决方案。打开JWT验证，即可对用户组白名单进行配置，允许白名单的用户组/用户访问该API，不受流量控制。

IP和IP段白名单：通过设定单独的IP或者IP段白名单，使得该IP或IP段的用户访问API时，不受流量控制。IP段使用CIDR表示法来表示，示例：192.168.1.0/24，其表示192.168.1.1-192.168.1.254

查看 API

点击API管理，即可查看API列表，通过点击API的具体名称，用户可查看 API 基本信息，如 ID、分组、负责人、创建时间及描述信息；HTTP 接口信息，如调用地址、请求方式、返回类型等信息；数据源信息，如名称、类型、连接地址、连接用户名、自定义 SQL 及数据描述等信息；请求参数，如通过访问控制，如 JWT 验证、API 流量控制等信息。

API 基本信息：
png

HTTP 接口信息：
png

数据源信息：
png

访问控制：
png

注：若未使用自定义sql，则还存在请求参数、返回参数信息。

编辑 API

用户通过点击API列表右侧的操作「编辑」，可对处于“待提交”、“已驳回”、“审核通过”状态下的API配置信息进行更新。可编辑内容与创建API内容一致，不再赘述。
png

对于处于“已发布”状态下的API，编辑操作可复制当前API配置信息，创建API的开发版本，针对开发版本可继续进行测试、提交审核、发布操作。再次发布会覆盖上一次发布内容。

测试 API

用户通过点击API列表右侧的操作「测试」，可跳转至「API测试」页面，对所有API进行测试并查看测试结果。

注：只有对创建的API进行测试，并测试成功后，才能提交审核。

提交审核

API测试成功且结果显示预期内容后，可提交此API的发布审核。

注：如审批被驳回，API 创建者可以对 API 进行修改、测试成功后可再次提交审批。

发布API

用户通过点击API右侧的操作「更多」-「发布」，即将“审核通过”状态下的API对外发布。所有的服务都需要发布后，才能供集群中的应用调用。支持对“已发布”的API创建开发版本编辑配置后，重新测试、提交审核、发布。再次发布后，会对上一次发布的 API 配置进行覆盖。

禁用API

支持对任意API进行禁用操作，禁用后的API会保留API的名称、路径和分组信息。“正在审核”的API被禁用后会从待审核列表移除。“已禁用”的API不可以被调用或者测试，也不能使用标签功能，不会在「数据服务大厅」中进行展示，或者被搜索。“已禁用”的API，可在「已禁用API」页中查看，可以重新启用回到原始状态，也可以直接被逻辑删除。

png