本文介绍 Ultipa Restful API 客户端工具的使用规范
版本更新(V4.2至V4.3)
- 使用 GO SDK 4.3
准备工作
- 与您的操作系统相适配的命令行工具:
- Linux 或 MacOS:bash, zsh, tcsh
- Windows:Windows PowerShell
- 与您的操作系统相适配的 Ultipa 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
其他参数:
参数 |
描述 | 默认值 |
---|---|---|
-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 | 连接 Ultipa server 时配置的的心跳时间(秒) | 5 |
-sd --schema_cache_duration | 插入操作时获取 schema 列表的心跳时间(毫秒) | 5000 |
API 基本信息
- 请求类型:POST
- 请求网段:
- Linux:API 服务所连接的 Ultipa 服务器地址,如 'http://192.168.1.88'
- Windows/MacOS:API 服务本机地址,即 'http://127.0.0.1'
- 请求端口:启动 API 服务时通过
-w
、-l
设置的有效端口 - Body 参数类型:JSON、FORM
登录 Ultipa 服务器
- 请求地址
.../login
- 请求示例
{
"username": "employee",
"password": "joaGsdf"
}
- 响应结果:登录后的 token 值
其余 API 接口均须使用 Headers 中的 Cookie 携带 token 值
ultipa=<token_value>
,Content_Type 为application/json
。
发送 UQL
- 请求地址
.../uql
- 请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
uql | string | 是 | UQL 语句 |
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
}
}
发送 UQL 并限制流式返回结果
- 请求地址
.../uql/stream
- 请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
uql | string | 是 | UQL 语句 |
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
}