Ai.KG 接口设计V1.0 郝伟 2021/05/27 [TOC]

1. 1 简介

1.1. 1.1 基本理念

基于HugeGraph数据库（下称HG），有以下设计理念：

  1. 基于RESTful协议，即使用url访问数据，返回json格式数据。
  2. 接口分为两类：公有数据协议和稀有数据协议。
  3. 使用SSL/TSL对链接进行加密。
  4. 支持中文。
  5. 数据与访问分离，分别使用数据服务器和接口服务器两台主机实现。
  6. 使用基于IP绑定的认证机制：
    • 数据服务器只接受接口服务器访问；
    • 接口服务器根据访问者IP提供两类接口：公共接口和私有接口；
    • 配置模块暂由开发人员在内部配置，不对外开放
  7. 将HG的强schema隐藏为弱schema，即将schema的创建过程隐藏起来。
  8. 可以添加节点、边和属性，但原则上不要修改节点、边或属性的名称。
  9. 提供文件上传以实现数据批量导入。

1.2. 1.2 接口目标

接口格式为 网址+参数的方式，以下为一些接口示例，具体含意见后文定义部分： 添加节点：https://api.abc.com/vetext/ip/create?name=192.168.3.117&owner=张三 添加关系：https://api.abc.com/edge/hasPort/create?head=192.168.3.117&tail=80&date=2021050312_152241&owner=张三 查询IP：https://api.abc.com/vetex/ip/query?skip=1230&limit=100&orderby=name,desc

2. 2 接口定义

2.1. 2.1 接口格式定义

网址格式为：

[prefix]/[type]/[label]/[operation]?[paramaters]

下面分别就这几部分内容进行介绍。

2.2. 2.2 prefix 网址前缀

目标主机提供的HG服务网址，如 https://api.abc.com。如果长期考虑的话，可以加上版本，如：https://api.abc.com/v1。

2.3. 2.3 type 操作类型

操作类型，目前定义以下三种：

  • vetex, 表示图数据中的节点
  • edge, 表图数据中的边；
  • fun, 表示一些操作函数。 根据具体需求可以进行细分和扩展，比如将 fun 分为更多的类型，如统计、辅助、归类等。

2.4. 2.4 label 对象名称

待操作的对象的标签，包括节点名称或连的名称，类型为字符串，相当于关系数据库中的表名。

2.5. 2.5 operation 操作命令

以下为具体操作，包括：

  • query, 根据一定的条件查询数据，为本设计的核心内容。
  • create, 创建对象，（保留，不推荐外部调用使用）；
  • delete, 删除对象，（保留，不推荐外部调用使用）；
  • modify, 修改对象，（保留，不推荐外部调用使用）；
  • update, 更新数据，（保留，不推荐外部调用使用）；

注：在本版本中，从数据安全角度，主要以对外查询为主，添加删除等数据修改功能暂不推荐使用。

2.6. 2.6 paramaters

不同的操作会有不同的数据作为参数传递，paramaters 就是用于表示参数列表，其格式为： key_1=value_1&key_2=value_2&...&key_n=value_n 在调用时，会转换为字典传递给后台接口。

2.7. 2.7 注意事项

这里有下几点需要注意：

  • 所有的key都是字符串
  • key和value中不得包括以下特殊符号： &, ", ?, !, /, \；
  • 在需要分隔时，推荐使用的符号：=, ,, -；
  • value不需要加引号，如果字符串中包括引号，使用两个单引号 ' 表示。
  • value包括数据类型时，需要进行指定，指定方式使用 类型, 值 的方式，如：
    • int,5 表示整型
    • str,5 表示字符串，也可以省略 str 写为 5
    • double,5 表示又精度浮点型。
    • 注：底层函数在处理时依据是否有 , 判断数据类型。

关于数据类型，目前HG支持以下数据类型：

1 str 字符串类型，是默认值，可以省略
2 int 整型
3 date 日期类型
4 Uuid UUID类型
5 boolean 布尔型
6 byte 字节型
7 blob 字节数组型
8 double 双精度浮点型
9 float 单精度浮点型
10 Long 长整型

3. 3 指令详解

3.1. 3.1 query

query的参数列表：

  • offset=10, 偏移量
  • limit=50, 返回数量
  • orderby=property_name,desc, 根据属性名排序，desc表倒序。

  • status=closed,updated, 记录的状态（待定）

  • 示例1：按时间顺序每页50条分页显示漏洞数据 第1页：https://api.abc.com/vetex/vulnerability/query?skip=0&limit=50&orderby=date,desc 第2页：https://api.abc.com/vetex/vulnerability/query?skip=50&limit=50&orderby=date,desc ... 第n页：https://api.abc.com/vetex/vulnerability/query?skip=[(n-1)*50]&limit=50&orderby=date,desc

如果是经常使用的函数，可以进一步封装成函数，如： 第n页：https://api.abc.com/fun/vulnerability/query?pageno=[n]&pagecount=50

返回结果: Json格式，是对象的列表。

{
    "ip":[
      {
        "name":"192.168.3.117",
        "date":"2020/05/12 20:34:14"
      },
      {
        "name":"192.168.3.117",
        "date":"2020/05/12 20:34:14"
      },
    ]
}

3.2. 3.2 create

（待定）

3.3. 3.3 update 更新

（待定）

3.4. 3.4 delete 删除

（待定）

4. 4 函数详解

（待定）

5. 5 参考资料

results matching ""

    No results matching ""