TuGraph-Restful-Server

TuGraph Restful Server 强依赖 TuGraph，Restful Server 与 Tugraph 共存

1.TuGraph-Restful-Server 简介

TuGraph Restful Server 使用brpc框架支持的http协议，提供restful接口查询功能，在实现中，restful server 与rpc server 使用同一个端口。目前restful接口提供文件上传，数据导入，导入进度查询，cypher查询，文件删除等功能

2.启动 TuGraph-Restful-Server

需要在启动Tugraph时设置enable_rpc参数为true的方式，正常启动TuGraph

3.连接 TuGraph-Restful-Server

TuGraph正常启动后，Restful Server 将监听在rpc_port上， 通过访问 http://\({ip}:\){rpc_port}/LGraphHttpService/Query/ url可以链接到TuGraph

4.数据格式

客户端与服务端数据交互的格式是 JSON。在发送请求时，请将发送数据的请求的报头设置为 Accept:application/json, Content-Type:application/json。 例如在创建一个点时，请求报头包含以下内容：

    Accept: application/json; charset=UTF-8
    Content-Type: application/json
    server_version: 12

5.返回值

通用返回格式

body参数

参数说明

参数类型

是否必填

errorCode

状态码

字符串

是

errorMessage

错误信息

字符串

是

data

返回的数据

字符串

是

TuGraph 返回的 HTTP 状态码包含以下四种：

  • 200 OK: 操作成功

  • 400 Bad Request: 输入有误，例如 URI 错误，或者请求中的 JSON 参数错误

  • 401 Unauthorized: 未通过鉴权认证，例如用户名密码错误，token超过有效期等

  • 500 Internal Server Error: 服务器端错误 当操作成功时，返回的 data 中包含操作的返回值。 当发生输入错误或者服务器错误时，返回的 errorMessage 中包含错误提示。

6.URI格式

URI

说明

/cypher

执行cypher查询请求

/refresh

刷新token请求

/login

用户登陆请求

/logout

用户登出请求

/upload_files

上传文件请求

/clear_cache

清理用户上传文件请求

/check_file

文件认证请求

/import_data

数据导入请求

/import_progress

导入进度查询请求

/import_schema

批量创建schema请求

7.接口

7.1 用户登陆

用于用户第一次与服务端通信时的鉴权操作，请求报文在 http body 中携带用户名和密码，响应报文在 http body 中会返回一个带有有效期的token，后续请求中需要在http header中携带该token作为凭证

7.1.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/login

7.1.2 REQUEST

body参数

参数说明

参数类型

是否必填

userName

用户名

字符串

是

password

密码

字符串

是

7.1.3 RESPONSE

body参数

参数说明

参数类型

是否必填

authorization

token

字符串

是

7.2 刷新token

token到期后将无法使用此token与服务端正常通信，需要获取新的token作为后续请求的凭证，请求报文在http header中携带旧的token，响应报文在http body中返回新的token

7.2.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/refresh

7.2.2 REQUEST

header参数

参数说明

参数类型

是否必填

Authorization

旧的token

字符串

是

7.2.3 RESPONSE

body参数

参数说明

参数类型

是否必填

authorization

新的token

字符串

是

7.3 用户登出

用户不再需要与服务端进行通信时，需要请求登出接口，释放自己的token。请求报文在http header中携带旧的token，如果拿到返回errorCode为200的响应报文即为正常登出

7.3.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/logout

7.3.2 REQUEST

header参数

参数说明

参数类型

是否必填

Authorization

旧的token

字符串

是

7.4 执行cypher查询请求

用户通过此类请求发cypher给server端执行并获取执行结果，请求报文在http body 中将执行的cypher语句和目标子图发送给server，server执行完成后在响应报文的http body中返回执行结果

7.4.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/cypher

7.4.2 REQUEST

body参数

参数说明

参数类型

是否必填

graph

查询目标子图

字符串

是

script

cypher查询语句

字符串

是

7.4.3 RESPONSE

body参数

参数说明

参数类型

是否必填

result

返回结果

字符串

是

7.5 上传文件请求

用户通过此类请求向server发送文件，可以对文件进行分片，分片大小不大于1MB，支持多线程乱序发送，请求报文在http header 中包含文件名，第一字节内容在文件中的偏移和分片大小，在body中包含文件内容，server收到请求后将验证分片大小是否与分片内容一致，一致时将文件分段写入文件。不一致时将返回errorCode为400的响应

7.5.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/upload_files

7.5.2 REQUEST

header参数

参数说明

参数类型

是否必填

File-Name

文件名

字符串

是

Begin-Pos

开始位置在文件内的偏移

字符串

是

Size

文件分片大小

字符串

是

body参数

参数说明

参数类型

是否必填

-

文件内容

字符串

是

7.6 文件认证请求

用户通过此类请求验证发送到server端的文件是否与期望一致，server端使用两种验证方式，md5值和文件长度，目前已支持文件长度验证。

7.6.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/check_file

7.6.2 REQUEST

body参数

参数说明

参数类型

是否必填

fileName

文件名

字符串

是

checkSum

文件对应md5值

字符串

否

fileSize

文件长度(以字节计算)

字符串

否

flag

标记位，为1时校验md5值，为2时校验文件长度

字符串

是

7.6.3 RESPONSE

body参数

参数说明

参数类型

是否必填

pass

检查成功为true，否则为false

bool

是

7.7 批量创建schema请求

用户通过此类请求批量创建schema，请求报文在http body 中将创建schema的目标子图和schema信息发送给server，如果拿到返回errorCode为200的响应报文即为正常创建

7.7.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/import_schema

7.7.2 REQUEST

body参数

参数说明

参数类型

是否必填

graph

创建目标子图

字符串

是

schema

schema描述信息

字符串

是

7.8 数据导入请求

用户通过此类请求导入已经上传的数据文件。导入不论成功或失败，都将删除已上传文件。数据导入请求在server中实现为一个异步任务，响应返回并不意味着导入已完成，返回的是任务id，后续可以通过此任务id查询导入进度

7.8.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/import_data

7.8.2 REQUEST

body参数

参数说明

参数类型

是否必填

graph

导入目标子图

字符串

是

schema

导入schema描述

json字符串

是

delimiter

分隔符

字符串

是

continueOnError

单行数据出错是否跳过错误并继续

boolean

否

skipPackages

跳过的包个数

字符串

否

taskId

任务id

字符串

否

other

其他参数

json字符串

否

7.8.3 RESPONSE

body参数

参数说明

参数类型

是否必填

taskId

任务编号

字符串

是

7.9 清理用户上传文件请求

用户通过此类请求清理已经上传的文件，如果拿到返回errorCode为200的响应报文即为正常清理

7.9.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/clear_cache

7.9.2 REQUEST

body参数

参数说明

参数类型

是否必填

fileName

文件名称

字符串

否

userName

用户名称

字符串

否

flag

标记位， flag = 0时删除fileName指定文件, flag = 1时删除userName指定用户已经上传的所有文件， flag = 2时删除所有用户上传的文件

字符串

是

7.10. 导入进度查询请求

用户通过此类请求获得导入任务的状态

7.10.1 URL

http://\({ip}:\){rpc_port}/LGraphHttpService/Query/import_progress

7.10.2 REQUEST

body参数

参数说明

参数类型

是否必填

taskId

任务编号

字符串

是

7.10.3 RESPONSE

body参数

参数说明

参数类型

是否必填

state

状态标记，为0表示准备导入，为1表示导入中，为2表示导入成功，为3表示导入失败

字符串

是

progress

导入进度，state为1时包含

字符串

否

reason

失败原因，state为3时包含

字符串

否