Skip to content

Latest commit

 

History

History
340 lines (276 loc) · 11.6 KB

7.restful-api.md

File metadata and controls

340 lines (276 loc) · 11.6 KB
Raw

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"}