本文介绍嬴图Restful API客户端工具的使用规范。
版本更新(v4.3至v4.4)
- 使用GO SDK v4.4
准备工作
- 一个命令行工具:
- Linux或MacOS:bash, zsh, tcsh
- Windows:Windows PowerShell
- 与操作系统相适配的嬴图Restful API
启动API服务
- 显示帮助信息
./ultipa_restful_api.exe --help
- 显示工具版本号
./ultipa_restful_api.exe --version
- 启动API服务
./ultipa_restful_api.exe -hosts 192.168.1.85:61095,192.168.1.87:61095,192.168.1.88:61095 -u employee -p joaGsdf -w 3
注:-hosts
、-u
、-p
等效于--hosts
、--username
、--password
。
![](https://img.ultipa.cn/img/2023-05-08-15-10-37-start-api.png)
其他参数:
参数 |
描述 | 默认值 |
---|---|---|
-l --listen | 监听的网络及起始端口 | 0.0.0.0:7001 |
-w --workers | 后台线程数量,例如:设置为5则默认监听端口7001-7005 | 0(即不启动API服务) |
-g --graph | 使用的图集名 | 'default' |
-b --boost | 使用SimpleCache | (不使用缓存) |
-batch --batch | 使用接口/insert/nodes 、/insert/edges 时的批大小(条数) |
5000 |
-d --duration | 批量插入时每批的等待时间(毫秒) | 1000 |
-c --consistency | 使用leader保证读一致性 | (不使用) |
-hb --heartbeat | 连接嬴图服务器时配置的的心跳时间(秒) | 5 |
-sd --schema_cache_duration | 插入操作时获取schema列表的心跳时间(毫秒) | 5000 |
API基本信息
- 请求类型:POST
- 请求网段:
- Linux:API服务所连接的嬴图服务器地址,如http://192.168.1.88
- Windows/MacOS:API服务本机地址,即http://127.0.0.1
- 请求端口:启动API服务时通过
-w
、-l
设置的有效端口 - Body参数类型:JSON、FORM
登录嬴图服务器
- 请求地址
.../login
- 请求示例
{
"username": "employee",
"password": "joaGsdf"
}
- 响应结果:登录后的token值
其余API接口均须使用Headers中的Cookie携带token值
ultipa=<token_value>
,Content_Type为application/json
。
发送嬴图GQL
- 请求地址
.../uql
- 请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
uql | string | 是 | 嬴图GQL语句 |
graph | string | 否 | 使用的图集名,默认使用启动API服务时通过-g 或--graph 指定的图集 |
- 请求示例
{
"uql": "find().nodes({name == \"abc\"}) return count(nodes)",
"graph": "test_text"
}
- 成功响应示例
{
"Data": [
{
"Name": "count(nodes)",
"PropertyType": 4,
"Rows": [
2
]
}
],
"Graph": "test_text",
"Statistic": {
"NodeAffected": 0,
"EdgeAffected": 0,
"TotalCost": 0,
"EngineCost": 0
},
"Status": {
"Message": "",
"Code": 0
}
}
发送嬴图GQL并限制流式返回结果
- 请求地址
.../uql/stream
- 请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
uql | string | 是 | 嬴图GQL语句 |
graph | string | 否 | 使用的图集名,默认使用启动API服务时通过-g 或--graph 指定的图集 |
package_num | int | 否 | 返回流式数据的包数量,默认为0,即只返回查询状态, 不返回数据 |
- 请求示例
{
"uql": "find().nodes({name == \"abc\"}) return nodes",
"graph": "test_text",
"package_num": 1
}
- 成功响应示例
插入点
- 请求地址
.../insert/nodes
- 请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
nodes | [{},{},...](JSON)或map(FORM) | 是 | 点属性,必须携带全部自定义属性,不支持_uuid ;使用Postman等工具时,FORM中可以设置多个nodes ,类型为{} |
schema | string | 是 | 点schema |
graph | string | 否 | 使用的图集名,默认使用启动API服务时通过-g 或--graph 指定的图集 |
sync | bool | 否 | 是否返回执行结果的状态,默认为false。为true且数据总量小于批大小(-batch 、--batch )时,会产生批等待时间(-d 、--duration ),从而影响插入效率 |
- 请求示例
{
"nodes": [{"name":"Jason","_id":"USER001"},{"name":"Alice"}],
"schema": "default",
"graph": "test_text",
"sync": true
}
- 成功响应示例
{
"Msg": "Insert Nodes Success: [{\"_id\":\"USER001\",\"name\":\"Jason\"},{\"name\":\"Alice\"}]"
}
插入边
- 请求地址
.../insert/edges
- 请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
edges | [{},{},...](JSON)或map(FORM) | 是 | 边属性,必须携带_from 和_to 以及全部自定义属性,不支持_uuid 、_from_uuid 、_to_uuid ;使用Postman等工具时,FORM中可以设置多个edges ,类型为{} |
schema | string | 是 | 边schema |
graph | string | 否 | 使用的图集名,默认使用启动API服务时通过-g 或--graph 指定的图集 |
sync | bool | 否 | 是否返回执行结果的状态,默认为false。为true且数据总量小于批大小(-batch 、--batch )时,会产生批等待时间(-d 、--duration ),从而影响插入效率 |
- 请求示例
{
"edges": [{"year":"1998", "_from":"USER001", "_to":"USER002"}],
"schema": "default",
"graph": "test_text",
"sync": true
}
- 成功响应示例
{
"Msg": "Insert Edges Success: [{\"_from\":\"USER001\",\"_to\":\"USER002\",\"year\":\"1998\"}]"
}
更新点
根据_id
或_uuid
对点进行更新。
- 请求地址
.../update/nodes
- 请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
nodes | [{},{},...](JSON)或map(FORM) | 是 | 点属性,必须携带_id 或_uuid ,二者均携带时忽略_uuid ;使用Postman等工具时,FORM中可以设置多个nodes ,类型为{} |
graph | string | 否 | 使用的图集名,默认使用启动API服务时通过-g 或--graph 指定的图集 |
- 请求示例
{
"nodes": [{"age":"35", "_id":"USER001"}, {"name":"John", "_id": "USER002"}],
"graph": "test_text"
}
- 成功响应示例
{
"Msg": "Update nodes on test_text",
"SuccessCount": 2
}
更新边
根据_from
和_to
、或_uuid
对边进行更新。
- 请求地址
.../update/edges
- 请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
edges | [{},{},...](JSON)或map(FORM) | 是 | 边属性,必须携带_from 和_to ,或_uuid ,二者均携带时忽略_uuid ;使用Postman等工具时,FORM中可以设置多个edges ,类型为{} |
graph | string | 否 | 使用的图集名,默认使用启动API服务时通过-g 或--graph 指定的图集 |
- 请求示例
{
"edges": [{"_uuid":"1","_from_uuid":"2", "age":"55"}],
"graph": "test_text"
}
- 成功响应示例
{
"Msg": "Update edges on test_text",
"SuccessCount": 1
}