RESTful API

此文档主要介绍 TuGrpah 的 Rest API 的调用详情。

1.简介

TuGraph 提供遵从 REST 规范的 HTTP API，以供开发者通过 HTTP 请求远程调用 TuGraph 提供的服务。

本文档描述 TuGraph 的 HTTP API 使用方式。

2.请求与响应格式

TuGraph HTTP Server 接收json格式的请求，经过鉴权后开始提取请求中的字段，根据定义好的接口逻辑处理请求，并返回json格式的响应。

2.1.标准响应格式

每一个响应都以标准响应格式返回，格式如下：

body参数	参数说明	参数类型	是否必填
errorCode	业务级错误码	int类型	是
success	请求是否成功	int类型	是
errorMessage	业务级错误信息	字符串类型	是
data	请求成功时返回的响应信息	json字符串	是

2.2请求类型

2.2.1. 用户登陆

用户在登陆请求中携带用户名和密码发送到服务端。登录成功会收到带有签名的令牌(Json Web Token)和判断是否为默认密码的布尔型变量，客户端储存该令牌，在后续的请求中将令牌加入请求头的Authorization域中。如果登录失败会收到“Authentication failed”错误。

• URI: /login

• METHOD: POST

• REQUEST:

body参数	参数说明	参数类型	是否必填
userName	用户名	字符串类型	是
password	用户密码	字符串类型	是

• RESPONSE: 如果成功，返回的响应信息中success为00，data中包含令牌

body参数	参数说明	参数类型	是否必填
authorization	令牌	字符串类型	是
default_password	默认密码	布尔类型	是

Example request.

    {"userName" : "test", "password" : "123456"}

2.2.2. 用户登出

用户登出，同时删除已经认证的token，用户后续发送请求时，需要重新登陆，并获取新的token。

• URI: /logout

• METHOD: POST

• REQUEST: http request header中携带调用login接口时返回的token，body中没有参数

• RESPONSE: 如果成功，返回的响应信息中success为00，data为空

2.2.3. 身份刷新

已下发的token失效后，需要调用本接口重新认证。后端验证token合法性。token在初次登录后，1小时内有效，过期需要刷新

• URI: /refresh

• METHOD: POST

• REQUEST: http request header中携带调用login接口时返回的token，body中没有参数

• RESPONSE: 如果成功，返回的响应信息中success为00，data中包含令牌

body参数	参数说明	参数类型	是否必填
authorization	令牌	字符串类型	是

2.2.4. 调用cypher

用户对TuGraph的增删改查请求需要调用cypher接口，并通过标准的cypher查询语言发起

• URI: /cypher

• METHOD: POST

• REQUEST:

body参数	参数说明	参数类型	是否必填
graph	查询的子图名称	字符串类型	是
script	cypher语句	字符串类型	是

• RESPONSE: 如果成功，返回的响应信息中success为00，data中包含查询结果

body参数	参数说明	参数类型	是否必填
result	查询结果	json字符串	是

Example request.

    {"script" : "Match (n) return n", "graph" : "default"}

2.2.5. 上传文件

接口用于将本地文件上传至TuGraph所在机器。可以上传文本文件，二进制文件，可以上传大文件，也可以上传小文件，对于大文件，客户端在上传时应该对文件做切分，每个文件分片不大于1MB，参数Begin-Pos和Size对应本次分片在完整文件中的偏移量与分片大小。参数需要放在http请求的报文头，请求内容对应文件分片内容。本接口请求头不止有token参数

• URI: /upload_file

• METHOD: POST

• REQUEST:

header参数	参数说明	参数类型	是否必填
File-Name	文件名称	字符串类型	是
Begin-Pos	开始位置在文件内的偏移	可以转成size_t类型的字符串	是
Size	本次请求文件分片大小	可以转成size_t类型的字符串	是

• RESPONSE: 如果成功，返回的响应信息中success为00

2.2.6. 检查文件

本接口用于检查已上传文件正确性，如果成功通过检查，再次上传同一文件时，直接返回成功

• URI: /check_file

• METHOD: POST

• REQUEST:

body参数	参数说明	参数类型	是否必填
fileName	文件名称	字符串类型	是
checkSum	文件对应md5值	可以转成int类型的字符串	flag为”1”时必填
fileSize	文件长度(以字节计算)	可以转成int类型的字符串	flag为”2”时必填
flag	标记位，flag为1时校验md5。flag为2时校验文件长度	可以转成int类型的字符串	是

• RESPONSE: 如果成功，返回的响应信息中success为00

body参数	参数说明	参数类型	是否必填
pass	检查成功为true，否则为false	bool类型	是

Example request.

{"fileName" : "test.csv", "checkSum" : "$MD5", "flag" : “1”}

2.2.7. 清理缓存文件

admin用户可以删除所有用户上传的文件，其他用户可以删除自己的上传的文件，可以删除指定名称的文件，指定用户上传的文件，也可以删除所有文件

• URI: /clear_cache

• METHOD: POST

• REQUEST:

body参数	参数说明	参数类型	是否必填
fileName	文件名称	字符串类型	flag为”0”时必填
userName	用户名称	字符串类型	flag为”1”时必填
flag	标记位，flag为0时删除fileName指定文件, flag为1时删除userName指定用户已经上传的所有文件，flag为2时删除所有用户上传的文件	可以转成int类型的字符串	是

• RESPONSE: 如果成功，返回中success为00

Example request.

{"fileName" : "test.csv", "userName" : "test", "flag" : “1”}

2.2.8. 导入schema

本接口可以根据用户指定的schema信息创建schema模型，schema的详细格式信息请参考data-import.md

• URI: /import_schema

• METHOD: POST

• REQUEST:

body参数	参数说明	参数类型	是否必填
graph	子图名称	字符串	是
description	schema描述信息	json字符串	是

• RESPONSE: 如果成功，返回中success为00

Example request.

{
	"graph": "test_graph",
	"description": {
		"schema": [{
			"label": "Person",
			"type": "VERTEX",
			"primary": "name",
			"properties": [{
				"name": "name",
				"type": "STRING"
			}, {
				"name": "birthyear",
				"type": "INT16",
				"optional": true
			}, {
				"name": "phone",
				"type": "INT16",
				"unique": true,
				"index": true
			}]
		}, {
			"label": "City",
			"type": "VERTEX",
			"primary": "name",
			"properties": [{
				"name": "name",
				"type": "STRING"
			}]
		}, {
			"label": "Film",
			"type": "VERTEX",
			"primary": "title",
			"properties": [{
				"name": "title",
				"type": "STRING"
			}]
		}, {
			"label": "HAS_CHILD",
			"type": "EDGE"
		}, {
			"label": "MARRIED",
			"type": "EDGE"
		}, {
			"label": "BORN_IN",
			"type": "EDGE",
			"properties": [{
				"name": "weight",
				"type": "FLOAT",
				"optional": true
			}]
		}, {
			"label": "DIRECTED",
			"type": "EDGE"
		}, {
			"label": "WROTE_MUSIC_FOR",
			"type": "EDGE"
		}, {
			"label": "ACTED_IN",
			"type": "EDGE",
			"properties": [{
				"name": "charactername",
				"type": "STRING"
			}]
		}, {
			"label": "PLAY_IN",
			"type": "EDGE",
			"properties": [{
				"name": "role",
				"type": "STRING",
				"optional": true
			}],
			"constraints": [
				["Person", "Film"]
			]
		}]
	}
}

2.2.9. 导入数据

本接口允许用户指定已经通过上传，校验的文件作为数据文件，按照schema参数描述的配置信息，导入到graph参数指定的子图中。导入过程是异步的，server在接收到导入请求后，返回一个任务id

• URI: /import_data

• METHOD: POST

• REQUEST:

body参数	参数说明	参数类型	是否必填
graph	子图名称	字符串类型	是
schema	导入schema描述	json字符串	是
delimiter	分隔符	字符串类型	是
continueOnError	单行数据出错是否跳过错误并继续	boolean类型	否
skipPackages	跳过的包个数	可以转成int类型的字符串	否
taskId	任务id，用于重启出错的任务	字符串类型	否
flag	标记位，flag为1时导入成功将删除数据文件	可以转成int类型的字符串	否
other	其他参数	可以转成int类型的字符串	否

• RESPONSE: 如果成功，返回的响应信息中success为00

body参数	参数说明	参数类型	是否必填
taskId	任务编号	字符串类型	是

Example request.

{
   "graph": "default",         //导入的子图名称
   "delimiter": ",",						//数据分隔符
   "continueOnError": true,		//遇到错误时是否跳过错误数据并继续导入
   "skipPackages": “0”,					//跳过的包个数
   "flag" : "1",
	 "schema": {
		"files": [{
			"DST_ID": "Film",				//终点label类型
			"SRC_ID": "Person",			//起点label类型
			"columns": [						//数据格式说明
				"SRC_ID",							//起点id
				"DST_ID",							//终点id
                "SKIP",								//表示跳过此列数据
				"charactername"				//属性名称
			],
			"format": "CSV",				//数据文件格式类型,支持csv和json
			"path": "acted_in.csv",	//数据文件名称
			"header": 0, 						//数据从第几行开始
			"label": "ACTED_IN"			//边的类型
		}]
	}
}

2.2.10. 导入进度查询

本接口用于查询导入任务的执行进度

• URI: /import_progress

• METHOD: POST

• REQUEST:

body参数	参数说明	参数类型	是否必填
taskId	import_data接口返回的任务id	字符串类型	是

• RESPONSE: 如果成功，返回的响应信息中success为00

body参数	参数说明	参数类型	是否必填
success	是否成功导入	boolean类型	是
reason	导入失败原因	字符串类型	success为false时必填
progress	当前导入进度	可以转成double类型的字符串	是

Example request.

{"taskId" : "$taskId"}