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时包含	字符串	否