CloudQuery OpenAPI，v1.4.1首次开放「部门导入」和「用户导入」

Posted 2021-08-29 CloudQuery

「 API 具有功能丰富、发展迅速且公共可用的特点，极大地推动了以 API 为中心的业务增长。原因有很多，比如 API 随处可用的特性、高效的开发和部署平台，以及摆脱资金密集型需求的金融模型。」

——《Evolution of the API economy》

随着企业对客户体验关注度的增加，越来越多企业期望以低成本、无摩擦的方式融入成熟的生态系统，由此引出「OpenAPI」的概念。API 以其高度的灵活性、友好性来面对众多前来调用的开发者，成功在各分布式应用之间进行接口调用与数据互通，构造一座无形的数据桥梁。

OpenAPI 描述语言也被称为接口描述语言（IDL）。描述语言通常以结构化的方式形成文档，因为同一工具生成的所有文档都遵循相同的格式约定，所以比自由形式的文档更具有可读性。此外，描述语言通常足够精确，可以自动生成各种软件类库，方便以各种语言来接入、调用 API。

CloudQuery 开放 API 的意义：从社区中来，到社区中去

CloudQuery 是一款出生于社区，生长于社区的产品，各位社区用户见证着我们的成长，但在我们自身功能还未完善的时候， 之前很多用户提到的内部 OA、组织架构对接功能就显得格外力不从心。自 CloudQuery 诞生的那一天起，我们就赋予了它基本的价值观：「开放、包容、互助、共赢」。所以我们产品逐渐趋于稳定的今天，也终于可以实现当初「开放」的承诺。

在 1.4.1 版本中我们将开放首个用户模块的 API，后续也会逐步开放审计、权限模块 API。我们来自于社区，最终也会回归社区，希望最后是我们和社区内的用户一起来把 CloudQuery 做成一款广受欢迎、贴合数据操作人员使用场景的数据库工具。

技术实现

前文已经提到各种新兴行业趋势和技术已经导致 API 激增，当前应用程序组件不再是单个进程中在一台机器上彼此通信的内部对象，而是通过网络相互通信的 API。网络的信息交互页增加了被攻击的风险，甚至 OWASP 已经推出了针对 API 攻击的十大漏洞列表，API 在今年成为了网络安全的重中之重。

CloudQuery 作为数据管控平台，数据安全管控对其的重要性不言而喻，所以在设计整个 OpenAPI 模块时我们在确保请求安全性、可靠性方面着重进行了多重加固。

发起请求时，服务端会以请求头中的 API 密钥来进行用户鉴权，鉴权成功后会给客户端颁发 token，token 具有时效性，在进行时效性校验的同时避免了重复信息反复查询数据库和对比等操作，也提高了服务器响应速度。如果仍然担心在输入密码时被网络抓包的方式窃取，则可以通过配置 HTTPS 的方式来进行传输加密，具体配置方式可以参考《CloudQuery 安全系列（一）：Http 与 Https》。

在请求过程中，身份认证无疑是最重要的环节。OpenAPI 规范中我们可以使用自定义对象和属性，针对每个 api 接口进行扩展，在定义 api 模块时我们都会定义 api自身的安全方案、应用级别，例如在定义用户模块的应用级别时就可以定义它的支持范围，防止其他恶意用户进行越权调用。

Paths:
    /users:
        Post:
            Security:
                - OAuth2:[admin]

使用方法

CloudQuery 对外开放的接口接受「GET」和「POST」两种调用方式，字符编码统一使用「UTF-8」编码。对于所有的「POST」调用方式接口，提交的数据格式统一为「JSON(application/json)」格式。

接口调用前需管理员在 CloudQuery 进行「开发者授权」申请接口调用的身份信息。平台会自动生成 appId，secret 信息，在代码调用接口中使用。

本次 v1.4.1 版本，CloudQuery开放了「组织架构」模块『部门导入』和『用户导入』的API。具体的《OpenAPI开发者文档》可在官网文档站查看，地址为：https://cloudquery.club/docs/。

我们以「用户导入」为例来说明使用方法。

输入参数：

参数名称	类型	是否必填	描述	是否用户标识加密
appId	String	是	用户标识id	是
source	String	是	数据来源	是
currentTime	Long	是	当前时间	是
status	String	是	加密字段生成的标识key
userInfos	UserInfo	是	用户详情

请求示例：

{
​    "currentTime":"1624520308159",
​    "source":"AD域",
​    "appid":"ryca9fwJ",
​    "status":"bb8058d05cec73ba5dac33a9f6e19977",
​    "userInfos":[{
​       "Dept":"cqUser",
​       "userName":"测试用户",
​       "userId":"test123",
​       "userGender”:”MALE",
​       "password":"abc",
​        "telephone":"15786547114",
​        "email":"[e-mail]",
​        "jobNumber”:"A001"
  }]
}

成功实例：

{
    "code": 200,
    "message": "success"
}

返回结果一览：

错误码	错误信息	排查思路
4600	无效的appId	使用appId的值与管理员发放的不匹配
4610	无效的身份认证	Secret的值不对。加密认证的key与服务器不一致
4620	数据同步存在异常数据	可以查询cq的系统库
4630	服务调度异常	存在服务没有启动。查看执行日志

在当前企业内部应用复杂的场景下，OpenAPI 正在逐步取代之前数据直接交换的方式进行应用间数据互通，开放 api 并不意味着将内部数据完全暴露，反而是以更加安全的方式来实现信息交互。随着 CloudQuery 的不断迭代，我们也会在未来更加注重企业内部生态连接，铸造更友好的一体化平台。

官网地址：https://cloudquery.club/