diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md index ffcc7b929..488ba51a4 100644 --- a/content/cn/docs/clients/restful-api/auth.md +++ b/content/cn/docs/clients/restful-api/auth.md @@ -26,7 +26,7 @@ city: Beijing}) 描述：用户'boss'拥有对'graph1'图中北京人的读权限。 ##### 接口说明： -用户认证与权限控制接口包括 5 类：UserAPI、GroupAPI、TargetAPI、BelongAPI、AccessAPI。 +用户认证与权限控制的核心接口包括 5 类：UserAPI、GroupAPI、TargetAPI、BelongAPI、AccessAPI。除此之外，ManagerAPI 用于授予图空间级别的管理角色，LoginAPI 用于签发和校验 token，ProjectAPI 用于把多个图归为一组从而一次性授权。 **注意**: 1.5.0 及之前，group/target 等 id 的格式类似 -69:grant，1.7.0 及之后，id 和 name 一致，如 admin [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0) ### 10.2 用户（User）API @@ -38,10 +38,13 @@ city: Beijing}) - user_name: 用户名称 - user_password: 用户密码 +- user_nickname: 用户昵称 - user_phone: 用户手机号 -- user_email: 用户邮箱 +- user_email: 用户邮箱 +- user_avatar: 用户头像地址 +- user_description: 用户描述 -其中 user_name 和 user_password 为必填。 +其中 user_name 和 user_password 为必填，其余为选填。 ##### Request Body @@ -101,12 +104,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/users/test 204 ``` -##### Response Body - -```json -1 -``` - #### 10.2.3 修改用户 ##### Params @@ -120,7 +117,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/users/test ``` ##### Request Body -修改 user_name、user_password 和 user_phone +修改 user_password 和 user_phone。`user_name` 不可修改，传了也必须与已有名称一致。 ```json { "user_name": "test", @@ -136,7 +133,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/users/test ``` ##### Response Body -返回结果是包含修改过的内容在内的整个用户组对象 +返回结果是包含修改过的内容在内的整个用户对象 ```json { "user_password": "******", @@ -153,7 +150,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/users/test ##### Params -- limit: 返回结果条数的上限 +- name: 只返回该名称的用户，传该参数时返回的是单个用户对象而不是列表，用户不存在时返回 `404` +- limit: 返回结果条数的上限，默认为 100 ##### Method & Url @@ -207,16 +205,12 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/admin ```json { - "users": [ - { - "user_password": "******", - "user_update": "2020-11-11 11:41:12.254", - "user_name": "admin", - "user_creator": "system", - "id": "admin", - "user_create": "2020-11-11 11:41:12.254" - } - ] + "user_password": "******", + "user_update": "2020-11-11 11:41:12.254", + "user_name": "admin", + "user_creator": "system", + "id": "admin", + "user_create": "2020-11-11 11:41:12.254" } ``` @@ -317,12 +311,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant 204 ``` -##### Response Body - -```json -1 -``` - #### 10.3.3 修改用户组 ##### Params @@ -519,12 +507,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin 204 ``` -##### Response Body - -```json -1 -``` - #### 10.4.3 修改资源 ##### Params @@ -743,12 +725,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:gr 204 ``` -##### Response Body - -```json -1 -``` - #### 10.5.3 修改关联角色 关联角色只能修改描述，不能修改 user 和 group 属性，如果需要修改关联角色，需要删除原来关联关系，新增关联角色。 @@ -794,7 +770,11 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:grant ##### Params -- limit: 返回结果条数的上限 +- user: 只返回该用户的关联关系 +- group: 只返回该角色的关联关系 +- limit: 返回结果条数的上限，默认为 100 + +`user` 和 `group` 不能同时使用。 ##### Method & Url @@ -931,12 +911,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S 204 ``` -##### Response Body - -```json -1 -``` - #### 10.6.3 修改赋权 赋权只能修改描述，不能修改用户组、资源和权限许可，如果需要修改赋权的关系，可以删除原来的赋权关系，新增赋权。 @@ -983,7 +957,11 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S-77 ##### Params -- limit: 返回结果条数的上限 +- group: 只返回该角色的赋权记录 +- target: 只返回该资源上的赋权记录 +- limit: 返回结果条数的上限，默认为 100 + +`group` 和 `target` 不能同时使用。 ##### Method & Url @@ -1051,18 +1029,20 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>11>S-77 **重要提示**：在使用以下 API 之前，需要先创建图空间（graphspace）。请参考 [Graphspace API](./graphspace) 创建名为 `gs1` 的图空间。文档中的示例均假设已存在名为 `gs1` 的图空间 +**重要提示**：管理员相关接口只在 PD 模式下可用，单机模式下会返回 `400` 和 `GraphSpace management is not supported in standalone mode` 错误信息。 + 1. 图空间管理员 API 用于在 graphspace 维度给用户授予/回收管理员角色，并查询当前用户或其他用户在该 graphspace 下的角色信息。角色类型可取 `SPACE`、`SPACE_MEMBER`、`ADMIN` 。 #### 10.7.1 检查当前登录用户是否拥有某个角色 ##### Params -- type: 需要校验的角色类型，可选 +- type: 需要校验的角色类型，必填，取值为 `SPACE`、`SPACE_MEMBER`、`ADMIN` 之一 ##### Method & Url ``` -GET http://localhost:8080/graphspaces/gs1/auth/managers/check?type=WRITE +GET http://localhost:8080/graphspaces/gs1/auth/managers/check?type=SPACE_MEMBER ``` ##### Response Status @@ -1074,16 +1054,16 @@ GET http://localhost:8080/graphspaces/gs1/auth/managers/check?type=WRITE ##### Response Body ```json -"true" +{ + "check": true +} ``` -返回 `true/false` 字符串表示是否拥有对应角色。 - #### 10.7.2 查询图空间管理员列表 ##### Params -- type: 角色类型，可选，按角色过滤 +- type: 角色类型，必填，取值为 `SPACE`、`SPACE_MEMBER`、`ADMIN` 之一。`SPACE` 返回图空间管理员，`SPACE_MEMBER` 返回图空间成员，`ADMIN` 返回整个集群的管理员 ##### Method & Url @@ -1101,12 +1081,8 @@ GET http://localhost:8080/graphspaces/gs1/auth/managers?type=SPACE ```json { - "managers": [ - { - "user": "admin", - "type": "SPACE", - "create_time": "2024-01-10 09:30:00" - } + "admins": [ + "admin" ] } ``` @@ -1115,6 +1091,13 @@ GET http://localhost:8080/graphspaces/gs1/auth/managers?type=SPACE - 下面在 gs1 下，将用户 boss 授权为 SPACE_MEMBER 角色 +##### Params + +- user: 用户或角色名称，必填 +- type: 角色类型，必填，取值为 `SPACE`、`SPACE_MEMBER`、`ADMIN` 之一 + +> 把已经是图空间成员的用户授权为 `SPACE` 时会先回收其成员角色，反之同理。只有管理员可以授予 `ADMIN`。 + ##### Request Body ```json @@ -1142,8 +1125,7 @@ POST http://localhost:8080/graphspaces/gs1/auth/managers { "user": "boss", "type": "SPACE_MEMBER", - "manager_creator": "admin", - "manager_create": "2024-01-10 09:45:12" + "graphspace": "gs1" } ``` @@ -1153,8 +1135,8 @@ POST http://localhost:8080/graphspaces/gs1/auth/managers ##### Params -- user: 需要删除的用户 Id -- type: 需要删除的角色类型 +- user: 需要删除的用户名称，内置的 `admin` 用户不能从 `ADMIN` 中移除 +- type: 需要删除的角色类型，取值为 `SPACE`、`SPACE_MEMBER`、`ADMIN` 之一 ##### Method & Url @@ -1168,22 +1150,148 @@ DELETE http://localhost:8080/graphspaces/gs1/auth/managers?user=boss&type=SPACE_ 204 ``` +#### 10.7.5 查询指定用户在图空间中的角色 + +##### Params + +- user: 用户名称 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/gs1/auth/managers/role?user=boss +``` + +##### Response Status + +```json +200 +``` + ##### Response Body +返回的角色取自 `ADMIN`、`SPACE`、`SPACE_MEMBER`；用户在该图空间下不具备其中任何角色时返回 `NONE`。 + ```json -1 +{ + "user": "boss", + "graphspace": "gs1", + "roles": [ + "SPACE_MEMBER" + ] +} ``` -#### 10.7.5 查询指定用户在图空间中的角色 +#### 10.7.6 检查当前登录用户是否拥有某个默认角色 + +默认角色是图空间的内置角色，参见 [Graphspace API](./graphspace)。`role` 的合法取值为 `space`、`space_member`、`analyst` 和 `observer`；`graph` 只在 `role=observer` 时生效。 ##### Params -- user: 用户 Id +- role: 默认角色名称，必填 +- graph: 图名称，选填，只在 `role=observer` 时使用 ##### Method & Url ``` -GET http://localhost:8080/graphspaces/gs1/auth/managers/role?user=boss +GET http://localhost:8080/graphspaces/gs1/auth/managers/default?role=analyst +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "check": true +} +``` + +### 10.8 登录（Login）API + +除了 HTTP Basic 认证之外，服务还可以签发 JWT token，之后通过 `Authorization: Bearer ` 请求头携带。登录相关接口不带图空间前缀。 + +token 使用 `auth.token_secret` 配置项签名，有效期为 `auth.token_expire` 秒（默认 86400）。该密钥的默认值在启动时随机生成，因此当 token 需要在重启后继续有效、或者需要被多个服务节点接受时，必须显式配置该项。 + +#### 10.8.1 登录并获取 token + +##### Params + +- user_name: 用户名称，必填 +- user_password: 用户密码，必填 +- token_expire: token 有效期（秒），选填 + +##### Request Body + +```json +{ + "user_name": "test", + "user_password": "******" +} +``` + +##### Method & Url + +``` +POST http://localhost:8080/auth/login +``` + +##### Response Status + +```json +200 +``` + +用户名或密码错误时返回 `401`。 + +##### Response Body + +```json +{ + "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX25hbWUiOiJ0ZXN0IiwidXNlcl9pZCI6InRlc3QiLCJleHAiOjE3MTIxMjM0NTZ9.PBs0iBt0PtqvLDpJvKrPHkyIzT1TICz9zJmMy8FvXVo" +} +``` + +#### 10.8.2 登出并使 token 失效 + +需要失效的 token 从请求头中获取，无需请求体。 + +##### Params + +**请求头说明：** + +- Authorization: `Bearer `，必填。只接受 Bearer 方式，其他方式返回 `400`。 + +##### Method & Url + +``` +DELETE http://localhost:8080/auth/logout +``` + +##### Response Status + +```json +204 +``` + +token 非法或已过期时返回 `401`。 + +#### 10.8.3 校验 token + +##### Params + +**请求头说明：** + +- Authorization: `Bearer `，必填 + +##### Method & Url + +``` +GET http://localhost:8080/auth/verify ``` ##### Response Status @@ -1192,15 +1300,200 @@ GET http://localhost:8080/graphspaces/gs1/auth/managers/role?user=boss 200 ``` +token 非法或已过期时返回 `401`。 + ##### Response Body ```json { - "roles": { - "boss": [ - "READ", - "SPACE_MEMBER" + "user_name": "test", + "user_id": "test" +} +``` + +### 10.9 项目（Project）API + +项目把一组图和一个管理员角色、一个操作员角色绑定在一起，从而可以一次性对这组图授权。创建项目时会同时生成它的 `project_target`、`project_admin_group` 和 `project_op_group`，这些字段会在响应中返回，但不能由客户端设置。 + +#### 10.9.1 创建项目 + +##### Params + +- project_name: 项目名称，必填 +- project_description: 项目描述，选填 + +创建时不能传 `project_graphs`，请使用下面的 `add_graph` 操作。 + +##### Request Body + +```json +{ + "project_name": "test_project", + "project_description": "this is a good project" +} +``` + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/auth/projects +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +```json +{ + "project_name": "test_project", + "project_description": "this is a good project", + "project_target": "project_test_project", + "project_admin_group": "project_test_project_admin", + "project_op_group": "project_test_project_op", + "project_create": "2024-01-10 09:30:00.000", + "project_update": "2024-01-10 09:30:00.000", + "project_creator": "admin", + "id": "test_project" +} +``` + +#### 10.9.2 向项目中添加或移除图 + +##### Params + +- id: 项目 Id +- action: `add_graph` 表示添加，`remove_graph` 表示移除 + +##### Request Body + +```json +{ + "project_graphs": [ + "hugegraph" ] - } } ``` + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project?action=add_graph +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +返回整个项目对象，其中包含更新后的图列表。 + +#### 10.9.3 修改项目描述 + +##### Params + +- id: 项目 Id + +不传 `action` 时表示修改描述，此时请求体中不能带 `project_graphs`。 + +##### Request Body + +```json +{ + "project_description": "update desc" +} +``` + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project +``` + +##### Response Status + +```json +200 +``` + +#### 10.9.4 查询项目列表 + +##### Params + +- limit: 返回结果条数的上限，默认为 100 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/auth/projects +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "projects": [ + { + "project_name": "test_project", + "project_description": "this is a good project", + "project_target": "project_test_project", + "project_admin_group": "project_test_project_admin", + "project_op_group": "project_test_project_op", + "project_create": "2024-01-10 09:30:00.000", + "project_update": "2024-01-10 09:30:00.000", + "project_creator": "admin", + "id": "test_project" + } + ] +} +``` + +#### 10.9.5 查询某个项目 + +##### Params + +- id: 项目 Id + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project +``` + +##### Response Status + +```json +200 +``` + +#### 10.9.6 删除项目 + +##### Params + +- id: 项目 Id + +删除前需要先把项目中的图全部移除。 + +##### Method & Url + +``` +DELETE http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project +``` + +##### Response Status + +```json +204 +``` diff --git a/content/cn/docs/clients/restful-api/cypher.md b/content/cn/docs/clients/restful-api/cypher.md index 0d7154724..af3302fca 100644 --- a/content/cn/docs/clients/restful-api/cypher.md +++ b/content/cn/docs/clients/restful-api/cypher.md @@ -7,6 +7,8 @@ description: "Cypher（图查询语言）REST 接口:通过 HTTP 接口执行 Op ### 9.1 Cypher +> Cypher 接口必须携带 `Authorization` 请求头，`Basic` 或 `Bearer` 均可。即使服务未开启鉴权，不带该请求头的请求也会返回 `401`。凭证会通过 `conf/remote-objects.yaml` 转发给 Gremlin Server。 + #### 9.1.1 向 HugeGraphServer 发送 Cypher 语句（GET），同步执行 ##### Method & Url diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index fe1047010..437d0f5bc 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -138,7 +138,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_nam ##### Response Status ```javascript -200 +201 ``` ##### Response Body @@ -146,7 +146,9 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_nam ```javascript { "name": "cloneGraph", - "backend": "rocksdb" + "nickname": "cloneGraph", + "backend": "rocksdb", + "description": "" } ``` @@ -175,7 +177,16 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx **注意**！！ 1. 在 1.7.0 版本中，动态创建图会导致 NPE 错误。该问题已在 [PR#2912](https://github.com/apache/hugegraph/pull/2912) 中修复。当前 master 版本和 1.7.0 之前的版本不受此问题影响。 -2. 1.7.0 及之前版本，如果 backend 是 hstore，必须在请求体加上 "task.scheduler_type": "distributed"。同时请确保 HugeGraph-Server 已正确配置 PD，参见 [HStore 配置](/cn/docs/quickstart/hugegraph/hugegraph-server/#511-分布式存储-hstore)。 +2. 如果 backend 是 hstore，请确保 HugeGraph-Server 已正确配置 PD，参见 [HStore 配置](/cn/docs/quickstart/hugegraph/hugegraph-server/#511-分布式存储-hstore)。1.7.0 及之前版本还需要在请求体中设置 `"task.scheduler_type": "distributed"`，该配置项现已废弃并被忽略：调度器由后端类型决定，hstore 使用分布式调度器，其他后端使用本地调度器。 + +**选填字段及其默认值：** +- `gremlin.graph` 默认为 `org.apache.hugegraph.HugeFactory` +- `backend` 在 PD 模式下默认为 `hstore`，否则默认为 `rocksdb` +- `serializer` 默认为 `binary` +- `store` 默认为图名称 +- `nickname` 设置图的显示名，在图空间内必须唯一 +- `schema` 指定初始化该图所用的 [schema 模板](./graphspace)，会被保存为 `schema.init_template` +- `description` 会原样返回在响应中 **RocksDB 示例：** @@ -190,7 +201,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx } ``` -**HStore 示例（适用于 1.7.0 及之前版本）：** +**HStore 示例：** ```javascript { @@ -198,7 +209,6 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx "backend": "hstore", "serializer": "binary", "store": "hugegraph2", - "task.scheduler_type": "distributed", "pd.peers": "127.0.0.1:8686" } ``` @@ -208,15 +218,17 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx ##### Response Status ```javascript -200 +201 ``` ##### Response Body ```javascript { - "name":"hugegraph2", - "backend": "rocksdb" + "name": "hugegraph2", + "nickname": "hugegraph2", + "backend": "rocksdb", + "description": "" } ``` @@ -249,6 +261,214 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/graphA?confirm_message=I > 注意：对于 HugeGraph 1.5.0 及之前版本，如需创建或删除图，请继续使用旧的 `text/plain`（properties）格式请求体，而不是 JSON。 +#### 6.1.7 列出图空间中全部的图及其配置 + +对当前用户有读权限的每个图返回一条记录，其中包含该图的配置（形如密码、密钥、token、凭证、私钥的配置项会被过滤掉）以及下面这些字段。当前用户的默认图会排在前面。 + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 + +**请求参数说明：** + +- prefix: 只返回名称或显示名以该前缀开头的图 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/profile +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +`default_update_time` 只在该图是当前用户的默认图时返回，`create_time` 只在该图记录了创建时间时返回。 + +```javascript +[ + { + "backend": "rocksdb", + "serializer": "binary", + "store": "hugegraph", + "name": "hugegraph", + "nickname": "hugegraph", + "graphspace_nickname": "DEFAULT", + "default": true, + "default_update_time": "2024-05-01 12:30:00", + "create_time": "2024-05-01 12:00:00" + } +] +``` + +#### 6.1.8 修改某个图的显示名，**该操作需要管理员权限** + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 +- graph: 图名称 + +**请求参数说明：** + +- action: 固定为 `update` +- update: 需要修改的字段。`name` 必填且必须与路径中的图名一致，`nickname` 是新的显示名，在图空间内必须唯一。 + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph +``` + +##### Request Body + +```javascript +{ + "action": "update", + "update": { + "name": "hugegraph", + "nickname": "MyGraph" + } +} +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "hugegraph": "updated" +} +``` + +#### 6.1.9 管理当前用户的默认图 + +默认图是按用户记录的，因此下面的接口都以调用者的身份生效。它们依赖权限系统，未开启权限的单机模式下会返回 `400` 和 `GraphSpace management is not supported in standalone mode`。 + +##### 设置默认图 + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/default +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default_graph": [ + "hugegraph" + ] +} +``` + +##### 取消默认图 + +##### Method & Url + +``` +DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/default +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default_graph": [] +} +``` + +##### 查看默认图 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/default +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default_graph": [ + "hugegraph" + ] +} +``` + +#### 6.1.10 重新加载图空间中的图 + +重新加载服务中的图，适用于图配置在服务外部被改动之后。 + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 + +**请求参数说明：** + +- action: 固定为 `reload` + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage +``` + +##### Request Body + +```javascript +{ + "action": "reload" +} +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "graphs": "reloaded" +} +``` + ### 6.2 Conf #### 6.2.1 查看某个图的配置，**该操作需要管理员权限** @@ -332,7 +552,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode } ``` -> 合法的图模式包括：NONE，RESTORING，MERGING +> 合法的图模式包括：NONE，RESTORING，MERGING，LOADING #### 6.3.2 设置某个图的模式。**该操作需要管理员权限** @@ -348,7 +568,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode "RESTORING" ``` -> 合法的图模式包括：NONE，RESTORING，MERGING +> 合法的图模式包括：NONE，RESTORING，MERGING，LOADING ##### Response Status @@ -408,7 +628,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode "OLTP_ONLY" ``` -> 合法的图模式包括：ALL，OLTP_ONLY，OLAP_ONLY +> 合法的读模式包括：ALL，OLTP_ONLY。传入 OLAP_ONLY 时接口会报错 `Graph-read-mode could be ALL or OLTP_ONLY`。 ##### Response Status @@ -509,3 +729,161 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/compact } } ``` + +### 6.6 Raft + +以下接口只在图运行于 raft 模式时可用，参见 [配置项](/cn/docs/config/config-option/) 中的 `raft.mode`。未开启 raft 模式的图会返回 `400` 和 `Allowed operation only when working on raft mode`。 + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 +- graph: 图名称 + +**请求参数说明：** + +- group: raft 组名称，默认为 `default` +- endpoint: 节点地址，形如 `host:port`。`transfer_leader`、`set_leader`、`add_peer` 和 `remove_peer` 必填。 + +#### 6.6.1 查看 raft 组的成员列表 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/list_peers +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +返回对象的 key 是 raft 组名称。 + +```javascript +{ + "default": [ + "127.0.0.1:8281", + "127.0.0.1:8282", + "127.0.0.1:8283" + ] +} +``` + +#### 6.6.2 查看 raft 组的 leader + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/get_leader +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default": "127.0.0.1:8281" +} +``` + +#### 6.6.3 转移 raft 组的 leader + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/transfer_leader?endpoint=127.0.0.1:8282 +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default": "127.0.0.1:8282" +} +``` + +#### 6.6.4 指定 raft 组的 leader + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/set_leader?endpoint=127.0.0.1:8282 +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default": "127.0.0.1:8282" +} +``` + +#### 6.6.5 向 raft 组添加成员 + +该操作会创建一个异步任务，参见 [Task API](./task)。 + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/add_peer?endpoint=127.0.0.1:8284 +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "task_id": 1 +} +``` + +#### 6.6.6 从 raft 组移除成员 + +该操作会创建一个异步任务，参见 [Task API](./task)。 + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/remove_peer?endpoint=127.0.0.1:8284 +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "task_id": 2 +} +``` diff --git a/content/cn/docs/clients/restful-api/graphspace.md b/content/cn/docs/clients/restful-api/graphspace.md index 62231b3be..ac99f0218 100644 --- a/content/cn/docs/clients/restful-api/graphspace.md +++ b/content/cn/docs/clients/restful-api/graphspace.md @@ -14,7 +14,8 @@ description: "Graphspace（图空间）REST 接口：多租户与资源隔离的 1. 目前图空间功能只支持在 hstore 模式下使用。 2. 如果非 hstore 模式，则只能使用默认的图空间 `DEFAULT`，且不支持创建、删除和更新图空间的操作。 3. 注意在 rest-server.properties 中，设置 `usePD=true`，并且 hugegraph.properties 中，设置 `backend=hstore` -4. 图空间功能必须开启鉴权模式，默认账密为 admin:pa，请务必修改默认密码，防止未授权访问。 +4. 图空间功能必须开启鉴权模式，默认账密为 admin:pa（见 `auth.admin_pa` 配置项），请务必修改默认密码，防止未授权访问。 +5. 本页所有接口都只在 PD 模式下可用，单机模式下会返回 `400` 和 `GraphSpace management is not supported in standalone mode` 错误信息。 #### 2.0.1 创建一个图空间 @@ -28,24 +29,25 @@ POST http://localhost:8080/graphspaces 注意：目前 cpu，内存，以及 k8s 相关功能暂未开放 -| 名称 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 | -|------------------------------|------|---------|-------|-----------------------------------|-----------------------------------------------------------------------| -| name | 是 | String | | 小写字母、数字和下划线组成，首字符必须是小写字母，长度不超过 48 | 图空间的名字 | -| description | 是 | String | | | 图空间的描述信息 | -| cpu_limit | 是 | Int | | > 0 | CPU 核数 | -| memory_limit | 是 | Int | | > 0 | 内存大小，单位 GB | -| storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限 | -| compute_cpu_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外资源配置，单位 cores。当该字段不配置或者配置为 0 时，会由 cpu_limit 字段的值进行覆盖 | -| compute_memory_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外内存配置，单位 GB。当该字段不配置或者配置为 0 时，会由 memory_limit 字段的值进行覆盖 | -| oltp_namespace | 是 | String | | | OLTP 的 k8s 命名空间 | -| olap_namespace | 是 | String | | | OLAP 的 k8s 命名空间。当 olap_namespace 和 oltp_namespace 的值相同时，其配置的资源限额会进行合并 | -| storage_namespace | 是 | String | | | 存储的 k8s 命名空间 | -| operator_image_path | 否 | String | | | 图计算 operator 的镜像地址：在创建图空间时，允许指定对应的图计算镜像并交由 K8S 进行统一管理 | -| internal_algorithm_image_url | 否 | String | | | 图计算的算法镜像地址：在创建图空间时，允许指定图计算的算法镜像并交由 K8S 进行统一管理 | -| max_graph_number | 是 | Int | | > 0 | 图空间的图数目的上限 | -| max_role_number | 是 | Int | | > 0 | 图空间的角色数目的上限 | -| auth | 否 | Boolean | false | true, false | 图空间是否支持权限认证 | -| configs | 否 | Map | | | 其他配置信息 | +| 名称 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 | +|------------------------------|----------|---------|-----------|-----------------------------------------------------------------|------------------------------------------------------------------------------------------------------| +| name | 是 | String | | 小写字母、数字和下划线组成，首字符必须是小写字母，长度不超过 48 | 图空间的名字 | +| nickname | 否 | String | name 的值 | 在所有图空间中必须唯一 | 图空间的显示名 | +| description | 否 | String | | | 图空间的描述信息 | +| cpu_limit | 是 | Int | | > 0 | CPU 核数 | +| memory_limit | 是 | Int | | > 0 | 内存大小，单位 GB | +| storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限 | +| compute_cpu_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外资源配置，单位 cores。当该字段不配置或者配置为 0 时，会由 cpu_limit 字段的值进行覆盖 | +| compute_memory_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外内存配置，单位 GB。当该字段不配置或者配置为 0 时，会由 memory_limit 字段的值进行覆盖 | +| oltp_namespace | 否 | String | "" | | OLTP 的 k8s 命名空间 | +| olap_namespace | 否 | String | "" | | OLAP 的 k8s 命名空间。当 olap_namespace 和 oltp_namespace 的值相同时，其配置的资源限额会进行合并 | +| storage_namespace | 否 | String | "" | | 存储的 k8s 命名空间 | +| operator_image_path | 否 | String | "" | | 图计算 operator 的镜像地址：在创建图空间时，允许指定对应的图计算镜像并交由 K8S 进行统一管理 | +| internal_algorithm_image_url | 否 | String | "" | | 图计算的算法镜像地址：在创建图空间时，允许指定图计算的算法镜像并交由 K8S 进行统一管理 | +| max_graph_number | 是 | Int | | > 0 | 图空间的图数目的上限 | +| max_role_number | 否 | Int | 0 | | 图空间的角色数目的上限 | +| auth | 否 | Boolean | false | true, false | 图空间是否支持权限认证 | +| configs | 否 | Map | | | 其他配置信息 | ```json { @@ -72,6 +74,7 @@ POST http://localhost:8080/graphspaces ```json { "name": "gs1", + "nickname": "gs1", "description": "1st graph space", "cpu_limit": 1000, "memory_limit": 8192, @@ -88,9 +91,13 @@ POST http://localhost:8080/graphspaces "cpu_used": 0, "memory_used": 0, "storage_used": 0, + "storage_percent": 0.0, "graph_number_used": 0, "role_number_used": 0, - "auth": true + "auth": true, + "creator": "admin", + "create_time": "2024-05-01 12:00:00", + "update_time": "2024-05-01 12:00:00" } ``` @@ -144,6 +151,7 @@ GET http://localhost:8080/graphspaces/gs1 ```json { "name": "gs1", + "nickname": "gs1", "description": "1st graph space", "cpu_limit": 1000, "memory_limit": 8192, @@ -160,12 +168,20 @@ GET http://localhost:8080/graphspaces/gs1 "cpu_used": 0, "memory_used": 0, "storage_used": 0, + "storage_percent": 0.0, "graph_number_used": 0, "role_number_used": 0, - "auth": true + "auth": true, + "creator": "admin", + "create_time": "2024-05-01 12:00:00", + "update_time": "2024-05-01 12:00:00", + "dp_username": "gs1_dp", + "dp_password": "a1b2c3d4e5f60718" } ``` +> `dp_username` 和 `dp_password` 由图空间名称推导得到，只有该接口会返回这两个字段。 + #### 2.0.4 更新某个图空间 > 注意：auth 鉴权配置，在创建图空间的过程一旦确定下来，不允许更新 @@ -181,22 +197,23 @@ GET http://localhost:8080/graphspaces/gs1 - action: 标记本次操作为 Update 动作，取值固定为 "update" - update: 即将更新的值，下述参数都应置于 update 中 -| 名称 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 | -|------------------------------|------|--------|-----|------|-----------------------------------------------------------------------| -| name | 是 | String | | | 图空间名称 | -| description | 是 | String | | | 图空间的描述信息 | -| cpu_limit | 是 | Int | | > 0 | OLTP HugeGraphServer 的 CPU 核数 | -| memory_limit | 是 | Int | | > 0 | OLTP HugeGraphServer 的内存大小，单位 GB | -| storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限 | -| compute_cpu_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外资源配置，单位 cores。当该字段不配置或者配置为 0 时，会由 cpu_limit 字段的值进行覆盖 | -| compute_memory_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外内存配置，单位 GB。当该字段不配置或者配置为 0 时，会由 memory_limit 字段的值进行覆盖 | -| oltp_namespace | 是 | String | | | OLTP 的 k8s 命名空间 | -| olap_namespace | 是 | String | | | OLAP 的 k8s 命名空间。当 olap_namespace 和 oltp_namespace 的值相同时，其配置的资源限额会进行合并 | -| storage_namespace | 是 | String | | | 存储的 k8s 命名空间 | -| operator_image_path | 否 | String | | | 图计算 operator 的镜像地址：在更新图空间时，允许指定对应的图计算镜像并交由 K8S 进行统一管理 | -| internal_algorithm_image_url | 否 | String | | | 图计算的算法镜像地址：在更新图空间时，允许指定图计算的算法镜像并交由 K8S 进行统一管理 | -| max_graph_number | 是 | Int | | > 0 | 图空间的图数目的上限 | -| max_role_number | 是 | Int | | > 0 | 图空间的角色数目的上限 | +| 名称 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 | +|------------------------------|----------|--------|--------|----------------------------|------------------------------------------------------------------------------------------------------| +| name | 是 | String | | 必须与路径中的图空间名一致 | 图空间名称 | +| nickname | 否 | String | | 在所有图空间中必须唯一 | 图空间的显示名 | +| description | 否 | String | | | 图空间的描述信息 | +| cpu_limit | 是 | Int | | > 0 | OLTP HugeGraphServer 的 CPU 核数 | +| memory_limit | 是 | Int | | > 0 | OLTP HugeGraphServer 的内存大小，单位 GB | +| storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限 | +| compute_cpu_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外资源配置，单位 cores。当该字段不配置或者配置为 0 时，会由 cpu_limit 字段的值进行覆盖 | +| compute_memory_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外内存配置，单位 GB。当该字段不配置或者配置为 0 时，会由 memory_limit 字段的值进行覆盖 | +| oltp_namespace | 否 | String | | | OLTP 的 k8s 命名空间 | +| olap_namespace | 否 | String | | | OLAP 的 k8s 命名空间。当 olap_namespace 和 oltp_namespace 的值相同时，其配置的资源限额会进行合并 | +| storage_namespace | 否 | String | | | 存储的 k8s 命名空间 | +| operator_image_path | 否 | String | | | 图计算 operator 的镜像地址：在更新图空间时，允许指定对应的图计算镜像并交由 K8S 进行统一管理 | +| internal_algorithm_image_url | 否 | String | | | 图计算的算法镜像地址：在更新图空间时，允许指定图计算的算法镜像并交由 K8S 进行统一管理 | +| max_graph_number | 是 | Int | | > 0 | 图空间的图数目的上限 | +| max_role_number | 否 | Int | | | 图空间的角色数目的上限 | ##### Method & Url @@ -236,6 +253,7 @@ PUT http://localhost:8080/graphspaces/gs1 ```json { "name": "gs1", + "nickname": "gs1", "description": "1st graph space", "cpu_limit": 2000, "memory_limit": 40960, @@ -252,9 +270,13 @@ PUT http://localhost:8080/graphspaces/gs1 "cpu_used": 0, "memory_used": 0, "storage_used": 0, + "storage_percent": 0.0, "graph_number_used": 0, "role_number_used": 0, - "auth": true + "auth": true, + "creator": "admin", + "create_time": "2024-05-01 12:00:00", + "update_time": "2024-05-01 12:30:00" } ``` @@ -279,3 +301,305 @@ DELETE http://localhost:8080/graphspaces/gs1 ``` > 注意：删除图空间，会导致图空间的全部资源被释放。 + +#### 2.0.6 列出系统所有图空间及其详情 + +##### Params + +**请求参数说明：** + +- prefix: 只返回名称或显示名以该前缀开头的图空间 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/profile +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +每条记录包含与 `GET /graphspaces/{graphspace}` 相同的字段，并额外带上 `authed`、`default`、`create_time` 和 `update_time`。`authed` 表示当前用户是否可以进入该图空间：当图空间开启了鉴权，而当前用户既不是管理员、也不是该空间的管理员或成员时为 `false`。`default` 目前恒为 `false`，默认图空间功能尚未实现。 + +```json +[ + { + "name": "gs1", + "nickname": "gs1", + "description": "1st graph space", + "cpu_limit": 1000, + "memory_limit": 8192, + "storage_limit": 1000000, + "compute_cpu_limit": 0, + "compute_memory_limit": 0, + "oltp_namespace": "hugegraph-server", + "olap_namespace": "hugegraph-server", + "storage_namespace": "hugegraph-server", + "max_graph_number": 100, + "max_role_number": 10, + "cpu_used": 0, + "memory_used": 0, + "storage_used": 0, + "storage_percent": 0.0, + "graph_number_used": 0, + "role_number_used": 0, + "auth": true, + "creator": "admin", + "authed": true, + "default": false, + "create_time": "2024-05-01 12:00:00", + "update_time": "2024-05-01 12:30:00" + } +] +``` + +**默认角色** + +每个图空间内置四种默认角色，可以一次性把一整组权限赋给某个用户或角色： + +- `space`：图空间管理员，只有管理员可以授予 +- `space_member`：图空间成员 +- `analyst`：图空间分析师 +- `observer`：只读角色，传入 `graph` 时可以收窄到单个图 + +`user` 既可以是用户名，也可以是角色名。当前用户是否具备某个默认角色也可以通过 `GET /graphspaces/{graphspace}/auth/managers/default` 查询，参见 [Authentication API](./auth)。 + +#### 2.0.7 授予默认角色 + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 + +**请求体说明：** + +- user: 用户名或角色名，必填 +- role: 取值为 `space`、`space_member`、`analyst`、`observer` 之一，必填 +- graph: 图名称，选填，只在 `role=observer` 时生效 + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/gs1/role +``` + +##### Request Body + +```json +{ + "user": "boss", + "role": "analyst" +} +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +只有在单个图上授予角色时才会回显 `graph`。 + +```json +{ + "user": "boss", + "role": "analyst", + "graphSpace": "gs1" +} +``` + +#### 2.0.8 查询默认角色 + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 + +**请求参数说明：** + +- user: 用户名或角色名，必填 +- role: 默认角色名称，必填 +- graph: 图名称，选填，只在 `role=observer` 时生效 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/gs1/role?user=boss&role=analyst +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "check": true +} +``` + +#### 2.0.9 回收默认角色 + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 + +**请求参数说明：** + +- user: 用户名或角色名，必填 +- role: 默认角色名称，必填 +- graph: 图名称，选填，只在 `role=observer` 时生效 + +##### Method & Url + +``` +DELETE http://localhost:8080/graphspaces/gs1/role?user=boss&role=analyst +``` + +##### Response Status + +```json +204 +``` + +**Schema 模板** + +Schema 模板把一段 Gremlin schema 脚本以名称保存下来，创建图时通过 `schema` 字段引用它来初始化图，参见 [Graphs API](./graphs)。模板可以由它的创建者、图空间管理员或系统管理员修改和删除。 + +#### 2.0.10 创建 schema 模板 + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 + +**请求体说明：** + +- name: 模板名称，必填 +- schema: Gremlin schema 脚本，必填 + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/gs1/schematemplates +``` + +##### Request Body + +```json +{ + "name": "template1", + "schema": "schema.propertyKey('name').asText().ifNotExist().create();" +} +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +```json +{ + "name": "template1", + "schema": "schema.propertyKey('name').asText().ifNotExist().create();", + "creator": "admin", + "create": "2024-05-01 12:00:00.000", + "create_time": "2024-05-01 12:00:00.000", + "update": "2024-05-01 12:00:00.000", + "update_time": "2024-05-01 12:00:00.000" +} +``` + +#### 2.0.11 列出图空间的全部 schema 模板 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/gs1/schematemplates +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "schema_templates": [ + "template1" + ] +} +``` + +#### 2.0.12 查看某个 schema 模板 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/gs1/schematemplates/template1 +``` + +##### Response Status + +```json +200 +``` + +#### 2.0.13 修改某个 schema 模板 + +只能修改 `schema`，模板名称不可修改。 + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/gs1/schematemplates/template1 +``` + +##### Request Body + +```json +{ + "schema": "schema.propertyKey('age').asInt().ifNotExist().create();" +} +``` + +##### Response Status + +```json +200 +``` + +#### 2.0.14 删除某个 schema 模板 + +##### Method & Url + +``` +DELETE http://localhost:8080/graphspaces/gs1/schematemplates/template1 +``` + +##### Response Status + +```json +204 +``` diff --git a/content/cn/docs/clients/restful-api/indexlabel.md b/content/cn/docs/clients/restful-api/indexlabel.md index 0a51d23fd..1d1e096e1 100644 --- a/content/cn/docs/clients/restful-api/indexlabel.md +++ b/content/cn/docs/clients/restful-api/indexlabel.md @@ -175,3 +175,53 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/indexla 注： > 可以通过`GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/1`（其中"1"是 task_id）来查询异步任务的执行状态，更多[异步任务 RESTful API](./task) + +#### 1.5.5 为已存在的 IndexLabel 添加或移除 userdata + +该方式只能修改 `user_data`，请求体中不能带 `base_type`、`base_value` 和 `index_type`。 + +##### Params + +- action: 表示当前行为是添加还是移除，取值为 `append`（添加）和 `eliminate`（移除） + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/indexlabels/personByCity?action=append +``` + +##### Request Body + +```json +{ + "name": "personByCity", + "user_data": { + "comment": "index on city" + } +} +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "id": 1, + "base_type": "VERTEX_LABEL", + "base_value": "person", + "name": "personByCity", + "fields": [ + "city" + ], + "index_type": "SECONDARY", + "user_data": { + "comment": "index on city", + "~create_time": "2022-05-13 13:47:23.745" + } +} +``` diff --git a/content/cn/docs/clients/restful-api/other.md b/content/cn/docs/clients/restful-api/other.md index f1b78d64e..53258d1a3 100644 --- a/content/cn/docs/clients/restful-api/other.md +++ b/content/cn/docs/clients/restful-api/other.md @@ -2,7 +2,7 @@ title: "Other API" linkTitle: "Other" weight: 18 -description: "Other（其他接口）REST 接口:提供系统版本查询和 API 版本信息等辅助功能。" +description: "Other（其他接口）REST 接口:提供版本查询、API 列表、异常堆栈开关、IP 白名单和 Arthas 诊断代理等辅助功能。" --- ### 11.1 Other @@ -29,7 +29,273 @@ GET http://localhost:8080/versions "version": "v1", "core": "1.7.0", "gremlin": "3.5.1", - "api": "0.71.0.0" + "api": "0.72.0.0" } } ``` + +#### 11.1.2 查看服务的概要信息 + +返回服务名、内核版本、文档地址以及当前节点注册的 API 分组。 + +##### Method & Url + +``` +GET http://localhost:8080/ +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +`swagger_ui` 由 `restserver.url` 拼接得到，`apis` 是当前节点注册的 API 分组，按名称排序。 + +```json +{ + "service": "hugegraph", + "version": "1.7.0", + "doc": "https://hugegraph.apache.org/docs/", + "api_doc": "https://hugegraph.apache.org/docs/clients/", + "swagger_ui": "http://127.0.0.1:8080/swagger-ui/index.html", + "apis": [ + "arthas", + "auth", + "cypher", + "filter", + "graph", + "gremlin", + "job", + "metrics", + "profile", + "raft", + "schema", + "space", + "traversers", + "variables" + ] +} +``` + +#### 11.1.3 列出服务的全部 API + +按 API 分组和资源类列出所有已注册的接口方法，每条记录包含 url、HTTP 方法，以及查询参数的类型和默认值。 + +##### Method & Url + +``` +GET http://localhost:8080/apis +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +返回内容较长，下面的片段展示了它的结构： + +```json +{ + "apis": { + "schema": { + "PropertyKeyAPI": [ + { + "url": "graphspaces/{graphspace}/graphs/{graph}/schema/propertykeys", + "method": "GET", + "parameters": [ + { + "name": "names", + "type": "java.util.List", + "default_value": null + } + ] + } + ] + } + } +} +``` + +#### 11.1.4 查看和切换异常堆栈开关 + +服务返回的错误信息中是否带上 `exception` 和 `cause` 等异常堆栈字段，由 `exception.allow_trace` 配置项（默认 `true`）决定。下面的接口是一个节点级别的运行期覆盖开关：打开时无论配置项取值如何都会带上堆栈。`GET` 返回的是该覆盖开关的状态，初始为 `false`。 + +##### Method & Url + +``` +GET http://localhost:8080/exception/trace +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "trace": false +} +``` + +##### Method & Url + +``` +PUT http://localhost:8080/exception/trace +``` + +##### Request Body + +```json +true +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "trace": true +} +``` + +#### 11.1.5 管理 IP 白名单，**该操作需要管理员权限** + +白名单只在开关打开时生效，参见 `white_ip.status` 配置项（默认 `disable`）。 + +##### 查看白名单 + +##### Method & Url + +``` +GET http://localhost:8080/whiteiplist +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "whiteIpList": [ + "127.0.0.1" + ] +} +``` + +##### 向白名单添加或删除 IP + +##### Params + +- ips: IPv4 地址列表 +- action: `load` 表示添加，`remove` 表示删除 + +##### Method & Url + +``` +POST http://localhost:8080/whiteiplist +``` + +##### Request Body + +```json +{ + "ips": [ + "10.0.0.1", + "10.0.0.2" + ], + "action": "load" +} +``` + +##### Response Status + +```json +202 +``` + +##### Response Body + +`existed_ips` 是已经在白名单中的地址，`added_ips` 是新增的地址，`illegal_ips` 只在存在非法 IPv4 地址时返回。`action=remove` 时返回的是 `removed_ips` 和 `non_existed_ips`。 + +```json +{ + "existed_ips": [], + "added_ips": [ + "10.0.0.1", + "10.0.0.2" + ] +} +``` + +##### 启用或关闭白名单 + +##### Params + +- status: `true` 表示启用，`false` 表示关闭 + +##### Method & Url + +``` +PUT http://localhost:8080/whiteiplist?status=true +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "WhiteIpListOpen": true +} +``` + +#### 11.1.6 启动 Arthas 诊断代理 + +将 [Arthas](https://arthas.aliyun.com/) 代理挂载到正在运行的服务进程上用于诊断。端口、绑定 IP 和禁用命令取自 `arthas.telnetPort`、`arthas.httpPort`、`arthas.ip` 和 `arthas.disabledCommands` 配置项，参见 [配置项](/cn/docs/config/config-option/)。 + +##### Method & Url + +``` +PUT http://localhost:8080/arthas +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +返回生效的 Arthas 配置： + +```json +{ + "arthas.telnetPort": "8562", + "arthas.httpPort": "8561", + "arthas.ip": "0.0.0.0", + "arthas.disabledCommands": "jad" +} +``` diff --git a/content/cn/docs/clients/restful-api/rank.md b/content/cn/docs/clients/restful-api/rank.md index f18fc4730..dd3fb68f0 100644 --- a/content/cn/docs/clients/restful-api/rank.md +++ b/content/cn/docs/clients/restful-api/rank.md @@ -140,7 +140,7 @@ schema.edgeLabel("rating") **选填项**: - alpha：每轮迭代时从某个点往外走的概率，与 PageRank 算法中的 alpha 类似，取值区间为 (0, 1], 默认值 `0.85` - max_degree: 查询过程中，单个顶点遍历的最大邻接边数目，默认为 `10000` -- max_depth: 迭代次数，取值区间为 [2, 50], 默认值 `5` +- max_depth: 迭代次数，取值区间为 [2, 5000], 默认值 `5` - with_label：筛选结果中保留哪些结果，可选以下三类，默认为 `BOTH_LABEL` - SAME_LABEL：仅保留与源顶点相同类别的顶点 - OTHER_LABEL：仅保留与源顶点不同类别（二分图的另一端）的顶点 @@ -301,7 +301,8 @@ public class Loader { - direction：表示边的方向（OUT, IN, BOTH），默认是 BOTH - labels：边的类型列表，多个边类型取并集 - max_degree：查询过程中，单个顶点遍历的最大邻接边数目，默认为 10000 (注：0.12 版之前 step 内仅支持 degree 作为参数名，0.12 开始统一使用 max_degree, 并向下兼容 degree 写法) - - top：在结果中每一层只保留权重最高的前 N 个结果，默认为 100，最大值为 1000 + - skip_degree：当前层跳过超级点的阈值，默认为 0，表示不跳过 + - top：在结果中每一层只保留权重最高的前 N 个结果，默认为 10，最大值为 1000 - capacity: 遍历过程中最大的访问的顶点数目，选填项，默认为 10000000 ##### 4.2.2.2 使用方法 diff --git a/content/cn/docs/clients/restful-api/task.md b/content/cn/docs/clients/restful-api/task.md index 92c89aebb..94f6539ed 100644 --- a/content/cn/docs/clients/restful-api/task.md +++ b/content/cn/docs/clients/restful-api/task.md @@ -11,8 +11,10 @@ description: "Task（任务管理）REST 接口:查询和管理异步任务的 ##### Params -- status: 异步任务的状态 -- limit：返回异步任务数目上限 +- status: 异步任务的状态，取值为 NEW、SCHEDULING、SCHEDULED、QUEUED、RESTORING、RUNNING、SUCCESS、CANCELLING、CANCELLED、FAILED、HANGING、DELETING 之一，不区分大小写 +- ids: 需要查询的任务 id，可以重复传多个。不能与 `status` 或 `page` 同时使用，并且会忽略 `limit` +- limit：返回异步任务数目上限，默认为 100 +- page: 分页的页标记，传该参数时响应中会带上下一页的 `page` 字段 ##### Method & Url @@ -48,6 +50,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks?status=succ #### 7.1.2 查看某个异步任务的信息 +##### Params + +- with_result: 是否加载任务的结果，默认为 true + ##### Method & Url ``` @@ -80,6 +86,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2 #### 7.1.3 删除某个异步任务信息，**不删除异步任务本身** +##### Params + +- force: 任务仍在运行时是否强制删除，默认为 false + ##### Method & Url ``` @@ -122,12 +132,107 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2?action=ca 202 ``` +对已经完成或者正在取消中的任务发起取消会返回 `400`。 + ##### Response Body +返回整个任务对象，其中 `task_status` 为 `cancelling` 或 `cancelled`： + ```json { - "cancelled": true + "task_name": "for (int i = 0; i < 10; i++) {...}", + "task_progress": 0, + "task_create": 1532943976585, + "task_status": "cancelling", + "task_update": 1532943977001, + "task_retries": 0, + "id": 2, + "task_type": "gremlin", + "task_callable": "org.apache.hugegraph.api.job.GremlinAPI$GremlinJob" } ``` 此时查询 label 为 man 的顶点数目，一定是小于 10 的。 + +### 7.2 Algorithm Job + +在服务内部以异步任务的方式调度一个 OLAP 算法，返回的 task id 可以用上面的 Task API 跟踪。 + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 +- graph: 图名称 +- name: 算法名称，已注册的算法有 `count_vertex`、`count_edge`、`degree_centrality`、`stress_centrality`、`betweenness_centrality`、`closeness_centrality`、`eigenvector_centrality`、`triangle_count`、`cluster_coefficient`、`lpa`、`louvain`、`weak_connected_component`、`fusiform_similarity`、`rings`、`k_core`、`page_rank` 和 `subgraph_stat`。名称不存在时返回 `404`。 + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/algorithm/page_rank +``` + +##### Request Body + +请求体是算法的参数集合，每个算法各自校验自己的参数。传 `{}` 表示全部使用默认值。 + +```json +{ + "alpha": 0.15, + "times": 10 +} +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +```json +{ + "task_id": 1 +} +``` + +### 7.3 Computer Job + +以异步任务的方式调度一个 HugeGraph-Computer 作业。该作业在服务外部执行，参见 [HugeGraph-Computer](/cn/docs/quickstart/computing/hugegraph-computer)。 + +##### Params + +**路径参数说明：** + +- graphspace: 图空间名称 +- graph: 图名称 +- name: 算法名称，已注册的有 `page_rank`、`weak_connected_component`、`lpa`、`triangle_count` 和 `louvain`。名称不存在时返回 `404`。 + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/computer/page_rank +``` + +##### Request Body + +请求体是作业的参数集合，传 `{}` 表示全部使用默认值。 + +```json +{} +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +```json +{ + "task_id": 2 +} +``` diff --git a/content/cn/docs/clients/restful-api/traverser.md b/content/cn/docs/clients/restful-api/traverser.md index f20acba20..0226e95a0 100644 --- a/content/cn/docs/clients/restful-api/traverser.md +++ b/content/cn/docs/clients/restful-api/traverser.md @@ -42,6 +42,10 @@ HugeGraph 支持的 Traverser API 包括： - Rings API，从起始顶点出发，可到达的环路路径 - Rays API，从起始顶点出发，可到达边界的路径（即无环路径） - Fusiform Similarity API，查找一个顶点的梭形相似点 +- Adamic-Adar API，计算两个顶点的 Adamic-Adar 指标 +- Resource Allocation API，计算两个顶点的资源分配指标 +- Edge Existence API，查询两个顶点之间存在的边 +- Count API，统计经过若干步遍历后可达的顶点数量，不返回顶点本身 - Vertices API - 按 ID 批量查询顶点； - 获取顶点的分区； @@ -3040,3 +3044,213 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/traversers/edges/ - 按 id 列表查询边，可用于批量查询边 - 获取分片和按分片查询边，可以用来遍历全部边 + +#### 3.2.24 Adamic-Adar + +##### 3.2.24.1 功能介绍 + +计算两个顶点的 [Adamic-Adar](https://en.wikipedia.org/wiki/Adamic/Adar_index) 指标，即每个共同邻居的度取对数后倒数之和。 + +###### Params + +- vertex：一个顶点 id，必填项 +- other：另一个顶点 id，必填项，不能与 `vertex` 相同 +- direction：顶点向外发散的方向（OUT,IN,BOTH），选填项，默认是 BOTH +- label：边的类型，选填项，默认代表所有 edge label +- max_degree：查询过程中，单个顶点遍历的最大邻接边数目，选填项，默认为 10000 +- limit：参与计算的共同邻居的最大数目，选填项，默认为 10000000 + +##### 3.2.24.2 使用方法 + +###### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/adamicadar?vertex="1:marko"&other="1:josh" +``` + +###### Response Status + +```json +200 +``` + +###### Response Body + +度为 0 的共同邻居会被跳过，因此两个顶点没有共同邻居时结果为 0.0。 + +```json +{ + "adamic_adar": 0.9102392266268373 +} +``` + +##### 3.2.24.3 适用场景 + +预测两个顶点之间是否可能出现连边，其中冷门的共同邻居比热门的共同邻居权重更高。 + +#### 3.2.25 Resource Allocation + +##### 3.2.25.1 功能介绍 + +计算两个顶点的资源分配指标，即每个共同邻居的度的倒数之和。 + +###### Params + +- vertex：一个顶点 id，必填项 +- other：另一个顶点 id，必填项，不能与 `vertex` 相同 +- direction：顶点向外发散的方向（OUT,IN,BOTH），选填项，默认是 BOTH +- label：边的类型，选填项，默认代表所有 edge label +- max_degree：查询过程中，单个顶点遍历的最大邻接边数目，选填项，默认为 10000 +- limit：参与计算的共同邻居的最大数目，选填项，默认为 10000000 + +##### 3.2.25.2 使用方法 + +###### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/resourceallocation?vertex="1:marko"&other="1:josh" +``` + +###### Response Status + +```json +200 +``` + +###### Response Body + +```json +{ + "resource_allocation": 0.3333333333333333 +} +``` + +##### 3.2.25.3 适用场景 + +连边预测，相比 Adamic-Adar 对高度数的共同邻居惩罚更强。 + +#### 3.2.26 Edge Existence + +##### 3.2.26.1 功能介绍 + +查询起点和终点之间存在的边。 + +###### Params + +- source：起始顶点 id，必填项 +- target：目标顶点 id，必填项 +- label：边的类型，选填项，默认代表所有 edge label +- sort_values：排序键的取值，当 edge label 的 frequency 为 MULTIPLE 时用于从多条平行边中选定一条，选填项，默认为空字符串 +- limit：返回的边的最大数目，选填项，默认为 100 + +##### 3.2.26.2 使用方法 + +###### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/edgeexist?source="1:marko"&target="2:lop" +``` + +###### Response Status + +```json +200 +``` + +###### Response Body + +```json +{ + "edges":[ + { + "id":"S1:marko>2>>S2:lop", + "label":"created", + "type":"edge", + "inVLabel":"software", + "outVLabel":"person", + "inV":"2:lop", + "outV":"1:marko", + "properties":{ + "weight":0.4, + "date":"20171210" + } + } + ] +} +``` + +##### 3.2.26.3 适用场景 + +判断两个顶点之间是否直接相连，并在一次请求中拿到连接边的属性。 + +#### 3.2.27 Count + +##### 3.2.27.1 功能介绍 + +统计从起始顶点出发，经过若干步遍历后可达的顶点数量，不返回顶点本身。 + +###### Params + +- source：起始顶点 id，必填项 +- steps：遍历的步骤，必填项，每个 step 支持以下字段： + - direction：顶点向外发散的方向（OUT,IN,BOTH），选填项，默认是 BOTH + - labels：当前 step 的边类型列表，选填项，默认代表所有 edge label + - properties：当前 step 的边属性过滤条件，选填项 + - max_degree：当前 step 中单个顶点遍历的最大邻接边数目，选填项，默认为 10000 + - skip_degree：当前 step 中跳过超级点的阈值，选填项，默认为 100000 +- contains_traversed：是否把中间各步到达的顶点也计入结果，选填项，默认为 false +- dedup_size：用于去重的顶点数上限，`-1` 表示不限制，选填项，默认为 1000000 + +##### 3.2.27.2 使用方法 + +###### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/count +``` + +###### Request Body + +```json +{ + "source": "1:marko", + "steps": [ + { + "direction": "BOTH", + "labels": [], + "max_degree": 100, + "skip_degree": 100 + }, + { + "direction": "BOTH", + "labels": [], + "max_degree": 100, + "skip_degree": 100 + }, + { + "direction": "BOTH", + "labels": [], + "max_degree": 100, + "skip_degree": 100 + } + ] +} +``` + +###### Response Status + +```json +200 +``` + +###### Response Body + +```json +{ + "count": 3 +} +``` + +##### 3.2.27.3 适用场景 + +只关心多步邻居的规模时使用，避免序列化和传输大量顶点。 diff --git a/content/cn/docs/clients/restful-api/vertex.md b/content/cn/docs/clients/restful-api/vertex.md index 7f1c8a254..1318da72f 100644 --- a/content/cn/docs/clients/restful-api/vertex.md +++ b/content/cn/docs/clients/restful-api/vertex.md @@ -411,10 +411,12 @@ PUT http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices/"1 - label: 顶点的类型 - properties: 属性键值对（查询属性的前提是该属性已经建立了索引） -- limit: 查询结果的最大数目 +- keep_start_p: 默认为 false，设置为 true 时不会自动转义范围匹配表达式，例如 `properties={"age":"P.gt(18)"}` 会被当作精确匹配，即 age 属性等于字符串 "P.gt(18)" +- offset: 偏移量，默认为 0 +- limit: 查询结果的最大数目，默认为 100 - page: 分页的页号 -以上参数都是可选的，但如果提供了 page 参数，就必须同时提供 limit 参数，并且不能再提供其他参数。`label, properties`和`limit`之间可以任意组合。 +以上参数都是可选的，page 不能与非 0 的 offset 同时使用，其余参数之间可以任意组合。 属性键值对由属性名称和属性值组成 JSON 格式的对象，可以使用多个属性键值对作为查询条件，属性值支持精确匹配和范围匹配，精确匹配的形式如`properties={"age":29}`，范围匹配的形式如`properties={"age":"P.gt(29)"}`，范围匹配支持以下表达式： diff --git a/content/cn/docs/config/config-authentication.md b/content/cn/docs/config/config-authentication.md index 5660a908c..a6b67d1b5 100644 --- a/content/cn/docs/config/config-authentication.md +++ b/content/cn/docs/config/config-authentication.md @@ -53,6 +53,9 @@ RANDOM_STRING=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32) echo "auth.token_secret=${RANDOM_STRING}" >> rest-server.properties ``` +由于默认值在每次启动时随机生成，当 token 需要在重启后继续有效、或者需要被多个服务节点接受时，必须显式配置该项。token 的有效期由 +`auth.token_expire` 决定，默认为 86400 秒。 + #### StandardAuthenticator 模式 `StandardAuthenticator`模式是通过在数据库后端存储用户信息来支持用户认证和权限控制，该实现基于数据库存储的用户的名称与密码进行认证（密码已被加密），基于用户的角色来细粒度控制用户权限。下面是具体的配置流程（重启服务生效）： @@ -71,7 +74,7 @@ authentication: { ```properties auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator auth.graph_store=hugegraph -# PD 模式首次创建 admin 用户时可设置初始密码 +# 内置 admin 账号的密码，默认为 pa，在首次启动时生效 #auth.admin_pa= # auth client config diff --git a/content/cn/docs/config/config-https.md b/content/cn/docs/config/config-https.md index 5aa128bad..31f0da3c2 100644 --- a/content/cn/docs/config/config-https.md +++ b/content/cn/docs/config/config-https.md @@ -21,8 +21,9 @@ ssl.keystore_file=conf/hugegraph-server.keystore ssl.keystore_password=****** ``` -服务端的 conf 目录下已经给出了一个 keystore 文件`hugegraph-server.keystore`，该文件的密码为`hugegraph`， -这两项都是在开启了 https 协议时的默认值，用户可以生成自己的 keystore 文件及密码，然后修改`ssl.keystore_file`和`ssl.keystore_password`的值。 +由于 keystore 文件没有声明许可证，发行包中并不包含它。当 `restserver.url` 以 `https` 开头而 `conf/hugegraph-server.keystore` +不存在时，`bin/start-hugegraph.sh` 会在启动前从 hugegraph-doc 仓库的 `binary-1.5` 分支下载该文件，其密码为 `hugegraph`。 +这两项都是 `ssl.keystore_file` 和 `ssl.keystore_password` 的默认值，用户可以生成自己的 keystore 文件及密码，然后修改这两个配置项。 ### 客户端配置 diff --git a/content/cn/docs/guides/backup-restore.md b/content/cn/docs/guides/backup-restore.md index 705a1381b..f5fb6a074 100644 --- a/content/cn/docs/guides/backup-restore.md +++ b/content/cn/docs/guides/backup-restore.md @@ -122,7 +122,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode } ``` -> 合法的图模式包括：NONE，RESTORING，MERGING +> 合法的图模式包括：NONE，RESTORING，MERGING，LOADING ##### 设置某个图的模式. **该操作需要管理员权限** @@ -138,7 +138,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode "RESTORING" ``` -> 合法的图模式包括：NONE，RESTORING，MERGING +> 合法的图模式包括：NONE，RESTORING，MERGING，LOADING ###### Response Status diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md index a3af6339b..7c37de996 100644 --- a/content/en/docs/clients/restful-api/auth.md +++ b/content/en/docs/clients/restful-api/auth.md @@ -21,7 +21,7 @@ user(name=boss) -belong-> group(name=all) -access(read)-> target(graph=graph1, r Description: User 'boss' has read permission for people in the 'graph1' graph from Beijing. ##### Interface Description: -The user authentication and access control interface includes 5 categories: UserAPI, GroupAPI, TargetAPI, BelongAPI, AccessAPI. +The core of user authentication and access control is 5 categories: UserAPI, GroupAPI, TargetAPI, BelongAPI, AccessAPI. Alongside them, ManagerAPI grants graphspace-level manager roles, LoginAPI issues and verifies tokens, and ProjectAPI groups several graphs so that permissions can be granted for the whole set at once. **Note** Before 1.5.0, the format of ids such as group/target was similar to -69:grant. After 1.7.0, the id and name were consistent. Such as admin [HugeGraph 1.5 x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0) ### 10.2 User (User) API @@ -33,10 +33,13 @@ The user interface includes APIs for creating users, deleting users, modifying u - user_name: User name - user_password: User password +- user_nickname: User nickname - user_phone: User phone number - user_email: User email +- user_avatar: URL of the user avatar +- user_description: User description -Both user_name and user_password are required. +Both user_name and user_password are required, the rest are optional. ##### Request Body @@ -96,12 +99,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/users/test 204 ``` -##### Response Body - -```json -1 -``` - #### 10.2.3 Modify User ##### Params @@ -115,7 +112,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/users/test ``` ##### Request Body -Modify user_name, user_password, and user_phone. +Modify user_password and user_phone. `user_name` can not be changed, and when it is passed it must match the existing name. ```json { @@ -149,7 +146,8 @@ The returned result is the entire user object including the modified content. ##### Params -- limit: Upper limit of the number of results returned +- name: Return only the user with this name. When it is given, the response is a single user object instead of a list, and `404` is returned if no such user exists. +- limit: Upper limit of the number of results returned, default is 100 ##### Method & Url @@ -203,16 +201,12 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/admin ```json { - "users": [ - { - "user_password": "******", - "user_update": "2020-11-11 11:41:12.254", - "user_name": "admin", - "user_creator": "system", - "id": "admin", - "user_create": "2020-11-11 11:41:12.254" - } - ] + "user_password": "******", + "user_update": "2020-11-11 11:41:12.254", + "user_name": "admin", + "user_creator": "system", + "id": "admin", + "user_create": "2020-11-11 11:41:12.254" } ``` @@ -313,12 +307,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant 204 ``` -##### Response Body - -```json -1 -``` - #### 10.3.3 Modify Group ##### Params @@ -513,12 +501,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin 204 ``` -##### Response Body - -```json -1 -``` - #### 10.4.3 Modify Resource ##### Params @@ -738,12 +720,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:gr 204 ``` -##### Response Body - -```json -1 -``` - #### 10.5.3 Modify an Association of Roles An association of roles can only be modified for its description. The `user` and `group` properties cannot be modified. If you need to modify an association of roles, you need to delete the existing association and create a new one. @@ -790,7 +766,11 @@ The response includes the modified content as well as the entire association of ##### Params -- limit: Upper limit on the number of results to return +- user: Return only the associations of this user +- group: Return only the associations of this group +- limit: Upper limit on the number of results to return, default is 100 + +`user` and `group` can not be used together. ##### Method & Url @@ -926,12 +906,6 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S 204 ``` -##### Response Body - -```json -1 -``` - #### 10.6.3 Modify Authorization Authorization can only be modified for its description. User group, resource, and permission cannot be modified. If you need to modify the authorization relationship, delete the original authorization and create a new one. @@ -983,7 +957,11 @@ The response includes the modified content as well as the entire authorization o ##### Params -- limit: The maximum number of results to return +- group: Return only the authorizations of this group +- target: Return only the authorizations on this resource +- limit: The maximum number of results to return, default is 100 + +`group` and `target` can not be used together. ##### Method & Url @@ -1051,18 +1029,20 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>11>S-77 > **Note**: Before using the following APIs, you need to create a graphspace first. For example, create a graphspace named `gs1` via the [Graphspace API](./graphspace). The examples below assume that `gs1` already exists. +> **Note**: The manager APIs only work when the server runs in PD mode. In standalone mode they return `400` with the message `GraphSpace management is not supported in standalone mode`. + 1. The graphspace manager API is used to grant/revoke manager roles for users at the graphspace level, and to query the roles of the current user or other users in a graphspace. Supported role types include `SPACE`, `SPACE_MEMBER`, and `ADMIN`. #### 10.7.1 Check whether the current login user has a specific role ##### Params -- type: Role type to check, optional +- type: Role type to check, required, one of `SPACE`, `SPACE_MEMBER`, `ADMIN` ##### Method & Url ``` -GET http://localhost:8080/graphspaces/gs1/auth/managers/check?type=WRITE +GET http://localhost:8080/graphspaces/gs1/auth/managers/check?type=SPACE_MEMBER ``` ##### Response Status @@ -1074,16 +1054,16 @@ GET http://localhost:8080/graphspaces/gs1/auth/managers/check?type=WRITE ##### Response Body ```json -"true" +{ + "check": true +} ``` -The API returns the string `true` or `false` indicating whether the current user has the given role. - #### 10.7.2 List graphspace managers ##### Params -- type: Role type, optional, used to filter by role +- type: Role type, required, one of `SPACE`, `SPACE_MEMBER`, `ADMIN`. `SPACE` lists the managers of the graphspace, `SPACE_MEMBER` lists its members, and `ADMIN` lists the administrators of the whole cluster. ##### Method & Url @@ -1101,12 +1081,8 @@ GET http://localhost:8080/graphspaces/gs1/auth/managers?type=SPACE ```json { - "managers": [ - { - "user": "admin", - "type": "SPACE", - "create_time": "2024-01-10 09:30:00" - } + "admins": [ + "admin" ] } ``` @@ -1115,6 +1091,13 @@ GET http://localhost:8080/graphspaces/gs1/auth/managers?type=SPACE - The following example grants user `boss` the `SPACE_MEMBER` role in graphspace `gs1`. +##### Params + +- user: User or group name, required +- type: Role type, required, one of `SPACE`, `SPACE_MEMBER`, `ADMIN` + +> Granting `SPACE` to a user that is already a space member revokes the member role first, and the other way round. Only an administrator can grant `ADMIN`. + ##### Request Body ```json @@ -1142,8 +1125,7 @@ POST http://localhost:8080/graphspaces/gs1/auth/managers { "user": "boss", "type": "SPACE_MEMBER", - "manager_creator": "admin", - "manager_create": "2024-01-10 09:45:12" + "graphspace": "gs1" } ``` @@ -1153,8 +1135,8 @@ POST http://localhost:8080/graphspaces/gs1/auth/managers ##### Params -- user: User ID to revoke -- type: Role type to revoke +- user: User name to revoke. The built-in `admin` user can not be removed from `ADMIN`. +- type: Role type to revoke, one of `SPACE`, `SPACE_MEMBER`, `ADMIN` ##### Method & Url @@ -1168,22 +1150,288 @@ DELETE http://localhost:8080/graphspaces/gs1/auth/managers?user=boss&type=SPACE_ 204 ``` +#### 10.7.5 Query roles of a specific user in a graphspace + +##### Params + +- user: User name + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/gs1/auth/managers/role?user=boss +``` + +##### Response Status + +```json +200 +``` + ##### Response Body +The returned roles are a subset of `ADMIN`, `SPACE` and `SPACE_MEMBER`; `NONE` is returned when the user holds none of them in this graphspace. + ```json -1 +{ + "user": "boss", + "graphspace": "gs1", + "roles": [ + "SPACE_MEMBER" + ] +} ``` -#### 10.7.5 Query roles of a specific user in a graphspace +#### 10.7.6 Check whether the current login user holds a default role + +Default roles are the built-in roles of a graphspace, see [Graphspace API](./graphspace). Valid `role` values are `space`, `space_member`, `analyst` and `observer`; `graph` is only taken into account for the `observer` role. ##### Params -- user: User ID +- role: Default role name, required +- graph: Graph name, optional, only used with `role=observer` ##### Method & Url ``` -GET http://localhost:8080/graphspaces/gs1/auth/managers/role?user=boss +GET http://localhost:8080/graphspaces/gs1/auth/managers/default?role=analyst +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "check": true +} +``` + +### 10.8 Login (Login) API + +Besides HTTP Basic authentication, the server can hand out a JWT token that is then passed as `Authorization: Bearer `. The login endpoints are not scoped to a graphspace. + +The token is signed with the `auth.token_secret` option and expires after `auth.token_expire` seconds (default 86400). The default secret is generated randomly at startup, so set it explicitly when tokens must stay valid across a restart or must be accepted by more than one server. + +#### 10.8.1 Log in and get a token + +##### Params + +- user_name: User name, required +- user_password: User password, required +- token_expire: Token lifetime in seconds, optional + +##### Request Body + +```json +{ + "user_name": "test", + "user_password": "******" +} +``` + +##### Method & Url + +``` +POST http://localhost:8080/auth/login +``` + +##### Response Status + +```json +200 +``` + +Wrong credentials return `401`. + +##### Response Body + +```json +{ + "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX25hbWUiOiJ0ZXN0IiwidXNlcl9pZCI6InRlc3QiLCJleHAiOjE3MTIxMjM0NTZ9.PBs0iBt0PtqvLDpJvKrPHkyIzT1TICz9zJmMy8FvXVo" +} +``` + +#### 10.8.2 Log out and invalidate the token + +The token to invalidate is taken from the request header, no request body is needed. + +##### Params + +**Request header** + +- Authorization: `Bearer `, required. Only the Bearer scheme is accepted, other schemes return `400`. + +##### Method & Url + +``` +DELETE http://localhost:8080/auth/logout +``` + +##### Response Status + +```json +204 +``` + +An invalid or expired token returns `401`. + +#### 10.8.3 Verify a token + +##### Params + +**Request header** + +- Authorization: `Bearer `, required + +##### Method & Url + +``` +GET http://localhost:8080/auth/verify +``` + +##### Response Status + +```json +200 +``` + +An invalid or expired token returns `401`. + +##### Response Body + +```json +{ + "user_name": "test", + "user_id": "test" +} +``` + +### 10.9 Project (Project) API + +A project groups a set of graphs together with an admin group and an op group, so that permissions can be granted for the whole set at once. Creating a project also creates its `project_target`, `project_admin_group` and `project_op_group`, which are returned in the response but can not be set by the client. + +#### 10.9.1 Create Project + +##### Params + +- project_name: Project name, required +- project_description: Project description, optional + +`project_graphs` can not be passed on creation, use the `add_graph` action below. + +##### Request Body + +```json +{ + "project_name": "test_project", + "project_description": "this is a good project" +} +``` + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/auth/projects +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +```json +{ + "project_name": "test_project", + "project_description": "this is a good project", + "project_target": "project_test_project", + "project_admin_group": "project_test_project_admin", + "project_op_group": "project_test_project_op", + "project_create": "2024-01-10 09:30:00.000", + "project_update": "2024-01-10 09:30:00.000", + "project_creator": "admin", + "id": "test_project" +} +``` + +#### 10.9.2 Add graphs to or remove graphs from a project + +##### Params + +- id: Project ID +- action: `add_graph` to add graphs, `remove_graph` to remove them + +##### Request Body + +```json +{ + "project_graphs": [ + "hugegraph" + ] +} +``` + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project?action=add_graph +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +The whole project object is returned, including the updated graph list. + +#### 10.9.3 Modify the description of a project + +##### Params + +- id: Project ID + +Leave `action` out to update the description. `project_graphs` must not be present in this case. + +##### Request Body + +```json +{ + "project_description": "update desc" +} +``` + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project +``` + +##### Response Status + +```json +200 +``` + +#### 10.9.4 Query Project List + +##### Params + +- limit: The maximum number of results to return, default is 100 + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/auth/projects ``` ##### Response Status @@ -1196,11 +1444,56 @@ GET http://localhost:8080/graphspaces/gs1/auth/managers/role?user=boss ```json { - "roles": { - "boss": [ - "READ", - "SPACE_MEMBER" + "projects": [ + { + "project_name": "test_project", + "project_description": "this is a good project", + "project_target": "project_test_project", + "project_admin_group": "project_test_project_admin", + "project_op_group": "project_test_project_op", + "project_create": "2024-01-10 09:30:00.000", + "project_update": "2024-01-10 09:30:00.000", + "project_creator": "admin", + "id": "test_project" + } ] - } } ``` + +#### 10.9.5 Query a Specific Project + +##### Params + +- id: Project ID + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project +``` + +##### Response Status + +```json +200 +``` + +#### 10.9.6 Delete Project + +##### Params + +- id: Project ID + +Remove all graphs from the project before deleting it. + +##### Method & Url + +``` +DELETE http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project +``` + +##### Response Status + +```json +204 +``` diff --git a/content/en/docs/clients/restful-api/cypher.md b/content/en/docs/clients/restful-api/cypher.md index 4d4a5b940..6a98f4c23 100644 --- a/content/en/docs/clients/restful-api/cypher.md +++ b/content/en/docs/clients/restful-api/cypher.md @@ -7,6 +7,8 @@ description: "Cypher REST API: Execute OpenCypher declarative graph query langua ### 9.1 Cypher +> The Cypher API always needs an `Authorization` header, either `Basic` or `Bearer`. A request without one is rejected with `401`, even when the server runs without authentication. The credentials are forwarded to the Gremlin Server through `conf/remote-objects.yaml`. + #### 9.1.1 Sending a cypher statement (GET) to HugeGraphServer for synchronous execution ##### Method & Url diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index b13ca0617..cd87e1f17 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -138,7 +138,7 @@ Clone a `non-auth` mode graph (set `Content-Type: application/json`) ##### Response Status ```javascript -200 +201 ``` ##### Response Body @@ -146,7 +146,9 @@ Clone a `non-auth` mode graph (set `Content-Type: application/json`) ```javascript { "name": "cloneGraph", - "backend": "rocksdb" + "nickname": "cloneGraph", + "backend": "rocksdb", + "description": "" } ``` @@ -175,7 +177,16 @@ Create a graph (set `Content-Type: application/json`) **Note**!! 1. In version 1.7.0, dynamic graph creation would cause a NPE. This issue has been fixed in [PR#2912](https://github.com/apache/hugegraph/pull/2912). The current master version and versions after 1.7.0 do not have this problem. -2. For version 1.7.0 and earlier, if the backend is hstore, you must add "task.scheduler_type": "distributed" in the request body. Also ensure HugeGraph-Server is properly configured with PD, see [HStore Configuration](/docs/quickstart/hugegraph/hugegraph-server/#511-distributed-storage-hstore). +2. If the backend is hstore, ensure HugeGraph-Server is properly configured with PD, see [HStore Configuration](/docs/quickstart/hugegraph/hugegraph-server/#511-distributed-storage-hstore). On 1.7.0 and earlier the request body also had to set `"task.scheduler_type": "distributed"`. That key is now deprecated and ignored: the scheduler is selected from the backend type, hstore uses the distributed scheduler and other backends use the local one. + +**Optional fields and their defaults:** +- `gremlin.graph` defaults to `org.apache.hugegraph.HugeFactory` +- `backend` defaults to `hstore` when the server runs in PD mode, and to `rocksdb` otherwise +- `serializer` defaults to `binary` +- `store` defaults to the graph name +- `nickname` sets a display name for the graph, it must be unique inside the graphspace +- `schema` names a [schema template](./graphspace) to initialize the graph with, it is stored as `schema.init_template` +- `description` is returned as-is in the response **RocksDB Example:** @@ -190,7 +201,7 @@ Create a graph (set `Content-Type: application/json`) } ``` -**HStore Example (for version 1.7.0 and earlier):** +**HStore Example:** ```javascript { @@ -198,7 +209,6 @@ Create a graph (set `Content-Type: application/json`) "backend": "hstore", "serializer": "binary", "store": "hugegraph2", - "task.scheduler_type": "distributed", "pd.peers": "127.0.0.1:8686" } ``` @@ -208,7 +218,7 @@ Create a graph (set `Content-Type: application/json`) ##### Response Status ```javascript -200 +201 ``` ##### Response Body @@ -216,7 +226,9 @@ Create a graph (set `Content-Type: application/json`) ```javascript { "name": "hugegraph2", - "backend": "rocksdb" + "nickname": "hugegraph2", + "backend": "rocksdb", + "description": "" } ``` @@ -249,6 +261,214 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/graphA?confirm_message=I > Note: For HugeGraph 1.5.0 and earlier versions, if you need to create or drop a graph, please still use the legacy `text/plain` (properties) style request body instead of JSON. +#### 6.1.7 List the graphs of the graphspace with their configuration + +Returns one entry per graph the current user can read, each carrying the graph configuration (keys that look like passwords, secrets, tokens, credentials or private keys are left out) plus the fields below. Graphs marked as default for the current user come first. + +##### Params + +**Path parameters** + +- graphspace: Graphspace name + +**Query parameters** + +- prefix: Return only the graphs whose name or nickname starts with this prefix + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/profile +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +`default_update_time` is only present when the graph is a default graph of the current user, and `create_time` only when the graph records one. + +```javascript +[ + { + "backend": "rocksdb", + "serializer": "binary", + "store": "hugegraph", + "name": "hugegraph", + "nickname": "hugegraph", + "graphspace_nickname": "DEFAULT", + "default": true, + "default_update_time": "2024-05-01 12:30:00", + "create_time": "2024-05-01 12:00:00" + } +] +``` + +#### 6.1.8 Update the nickname of a graph, **this operation requires administrator privileges** + +##### Params + +**Path parameters** + +- graphspace: Graphspace name +- graph: Graph name + +**Request parameters** + +- action: Must be `update` +- update: Container for the fields to update. `name` is required and must match the graph name in the path, `nickname` is the new display name and must be unique inside the graphspace. + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph +``` + +##### Request Body + +```javascript +{ + "action": "update", + "update": { + "name": "hugegraph", + "nickname": "MyGraph" + } +} +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "hugegraph": "updated" +} +``` + +#### 6.1.9 Manage the default graphs of the current user + +A default graph is recorded per user, so the endpoints below act on behalf of the calling user. They need the authentication system, a server started in standalone mode without it answers `400` with `GraphSpace management is not supported in standalone mode`. + +##### Set a graph as default + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/default +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default_graph": [ + "hugegraph" + ] +} +``` + +##### Unset a default graph + +##### Method & Url + +``` +DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/default +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default_graph": [] +} +``` + +##### Get the default graphs + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/default +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default_graph": [ + "hugegraph" + ] +} +``` + +#### 6.1.10 Reload the graphs of the graphspace + +Reloads the graphs the server holds, which is useful after the graph configuration has changed outside the server. + +##### Params + +**Path parameters** + +- graphspace: Graphspace name + +**Request parameters** + +- action: Must be `reload` + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage +``` + +##### Request Body + +```javascript +{ + "action": "reload" +} +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "graphs": "reloaded" +} +``` + ### 6.2 Conf #### 6.2.1 Get configuration for a graph, **This operation requires administrator privileges** @@ -346,7 +566,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode } ``` -> Allowed graph mode values are: NONE, RESTORING, MERGING +> Allowed graph mode values are: NONE, RESTORING, MERGING, LOADING #### 6.3.2 Modify graph mode. **This operation requires administrator privileges** @@ -369,7 +589,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode "RESTORING" ``` -> Allowed graph mode values are: NONE, RESTORING, MERGING +> Allowed graph mode values are: NONE, RESTORING, MERGING, LOADING ##### Response Status @@ -435,7 +655,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode "OLTP_ONLY" ``` -> Allowed read mode values are: ALL, OLTP_ONLY, OLAP_ONLY +> Allowed read mode values are: ALL, OLTP_ONLY. The API rejects OLAP_ONLY with `Graph-read-mode could be ALL or OLTP_ONLY`. ##### Response Status @@ -545,3 +765,161 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/compact } } ``` + +### 6.6 Raft + +These endpoints only work when the graph runs in raft mode, see the `raft.mode` option in [Config Options](/docs/config/config-option/). On a graph that does not, they answer `400` with `Allowed operation only when working on raft mode`. + +##### Params + +**Path parameters** + +- graphspace: Graphspace name +- graph: Graph name + +**Query parameters** + +- group: Raft group name, default is `default` +- endpoint: Address of the peer, in the `host:port` form. Required by `transfer_leader`, `set_leader`, `add_peer` and `remove_peer`. + +#### 6.6.1 List the peers of a raft group + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/list_peers +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +The key of the returned object is the raft group name. + +```javascript +{ + "default": [ + "127.0.0.1:8281", + "127.0.0.1:8282", + "127.0.0.1:8283" + ] +} +``` + +#### 6.6.2 Get the leader of a raft group + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/get_leader +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default": "127.0.0.1:8281" +} +``` + +#### 6.6.3 Transfer the leadership of a raft group + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/transfer_leader?endpoint=127.0.0.1:8282 +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default": "127.0.0.1:8282" +} +``` + +#### 6.6.4 Set the leader of a raft group + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/set_leader?endpoint=127.0.0.1:8282 +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "default": "127.0.0.1:8282" +} +``` + +#### 6.6.5 Add a peer to a raft group + +This schedules an asynchronous task, see [Task API](./task). + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/add_peer?endpoint=127.0.0.1:8284 +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "task_id": 1 +} +``` + +#### 6.6.6 Remove a peer from a raft group + +This schedules an asynchronous task, see [Task API](./task). + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/remove_peer?endpoint=127.0.0.1:8284 +``` + +##### Response Status + +```javascript +200 +``` + +##### Response Body + +```javascript +{ + "task_id": 2 +} +``` diff --git a/content/en/docs/clients/restful-api/graphspace.md b/content/en/docs/clients/restful-api/graphspace.md index d38d056d4..2a5547448 100644 --- a/content/en/docs/clients/restful-api/graphspace.md +++ b/content/en/docs/clients/restful-api/graphspace.md @@ -14,7 +14,8 @@ HugeGraph implements multi-tenancy through graph spaces, which isolate compute/s 1. Graphspace currently only works in HStore mode. 2. In non-HStore mode you can only use the default graphspace `DEFAULT`; creating/deleting/updating other graphspaces is not supported. 3. Set `usePD=true` in `rest-server.properties` and `backend=hstore` in `hugegraph.properties`. -4. Graphspace enables strict authentication by default (default credential: `admin:pa`). Change the password immediately to avoid unauthorized access. +4. Graphspace enables strict authentication by default (default credential: `admin:pa`, see the `auth.admin_pa` option). Change the password immediately to avoid unauthorized access. +5. Every endpoint on this page requires PD mode. In standalone mode they answer `400` with the message `GraphSpace management is not supported in standalone mode`. #### 2.0.1 Create a graphspace @@ -31,19 +32,20 @@ Note: CPU/memory and Kubernetes-related capabilities are not publicly available | Name | Required | Type | Default | Range/Note | Description | |------------------------------|----------|---------|---------|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| | name | Yes | String | | Lowercase letters, digits, underscore; must start with a letter; max length 48 | Graphspace name | -| description | Yes | String | | | Description | +| nickname | No | String | name | Must be unique among graphspaces | Display name of the graphspace | +| description | No | String | | | Description | | cpu_limit | Yes | Int | | > 0 | CPU cores for the graphspace | | memory_limit | Yes | Int | | > 0 (GB) | Memory quota in GB | | storage_limit | Yes | Int | | > 0 | Maximum disk usage | | compute_cpu_limit | No | Int | 0 | >= 0 | Extra HugeGraph-Computer CPU cores; falls back to `cpu_limit` if unset or 0 | | compute_memory_limit | No | Int | 0 | >= 0 | Extra HugeGraph-Computer memory in GB; falls back to `memory_limit` if unset or 0 | -| oltp_namespace | Yes | String | | | Kubernetes namespace for OLTP HugeGraph-Server | -| olap_namespace | Yes | String | | Resources are merged when identical to `oltp_namespace` | Kubernetes namespace for OLAP / HugeGraph-Computer | -| storage_namespace | Yes | String | | | Kubernetes namespace for HugeGraph-Store | -| operator_image_path | No | String | | | HugeGraph-Computer operator image registry | -| internal_algorithm_image_url | No | String | | | HugeGraph-Computer algorithm image registry | +| oltp_namespace | No | String | "" | | Kubernetes namespace for OLTP HugeGraph-Server | +| olap_namespace | No | String | "" | Resources are merged when identical to `oltp_namespace` | Kubernetes namespace for OLAP / HugeGraph-Computer | +| storage_namespace | No | String | "" | | Kubernetes namespace for HugeGraph-Store | +| operator_image_path | No | String | "" | | HugeGraph-Computer operator image registry | +| internal_algorithm_image_url | No | String | "" | | HugeGraph-Computer algorithm image registry | | max_graph_number | Yes | Int | | > 0 | Maximum number of graphs that can be created inside the graphspace | -| max_role_number | Yes | Int | | > 0 | Maximum number of roles that can be created inside the graphspace | +| max_role_number | No | Int | 0 | | Maximum number of roles that can be created inside the graphspace | | auth | No | Boolean | false | true / false | Whether to enable authentication for the graphspace | | configs | No | Map | | | Additional configuration | @@ -72,6 +74,7 @@ Note: CPU/memory and Kubernetes-related capabilities are not publicly available ```json { "name": "gs1", + "nickname": "gs1", "description": "1st graph space", "cpu_limit": 1000, "memory_limit": 8192, @@ -88,9 +91,13 @@ Note: CPU/memory and Kubernetes-related capabilities are not publicly available "cpu_used": 0, "memory_used": 0, "storage_used": 0, + "storage_percent": 0.0, "graph_number_used": 0, "role_number_used": 0, - "auth": true + "auth": true, + "creator": "admin", + "create_time": "2024-05-01 12:00:00", + "update_time": "2024-05-01 12:00:00" } ``` @@ -144,6 +151,7 @@ GET http://localhost:8080/graphspaces/gs1 ```json { "name": "gs1", + "nickname": "gs1", "description": "1st graph space", "cpu_limit": 1000, "memory_limit": 8192, @@ -160,12 +168,20 @@ GET http://localhost:8080/graphspaces/gs1 "cpu_used": 0, "memory_used": 0, "storage_used": 0, + "storage_percent": 0.0, "graph_number_used": 0, "role_number_used": 0, - "auth": true + "auth": true, + "creator": "admin", + "create_time": "2024-05-01 12:00:00", + "update_time": "2024-05-01 12:00:00", + "dp_username": "gs1_dp", + "dp_password": "a1b2c3d4e5f60718" } ``` +> `dp_username` and `dp_password` are derived from the graphspace name and are only returned by this endpoint. + #### 2.0.4 Update a graphspace > `auth` cannot be changed once a graphspace is created. @@ -183,8 +199,9 @@ GET http://localhost:8080/graphspaces/gs1 | Name | Required | Type | Range/Note | Description | |------------------------------|----------|--------|---------------------------------------------------------|-----------------------------------------------------------------------------------| -| name | Yes | String | | Graphspace name | -| description | Yes | String | | Description | +| name | Yes | String | Must match the graphspace name in the path | Graphspace name | +| nickname | No | String | Must be unique among graphspaces | Display name of the graphspace | +| description | No | String | | Description | | cpu_limit | Yes | Int | > 0 | CPU cores for OLTP HugeGraph-Server | | memory_limit | Yes | Int | > 0 (GB) | Memory quota (GB) for OLTP HugeGraph-Server | | storage_limit | Yes | Int | > 0 | Maximum disk usage | @@ -236,6 +253,7 @@ PUT http://localhost:8080/graphspaces/gs1 ```json { "name": "gs1", + "nickname": "gs1", "description": "1st graph space", "cpu_limit": 2000, "memory_limit": 40960, @@ -252,9 +270,13 @@ PUT http://localhost:8080/graphspaces/gs1 "cpu_used": 0, "memory_used": 0, "storage_used": 0, + "storage_percent": 0.0, "graph_number_used": 0, "role_number_used": 0, - "auth": true + "auth": true, + "creator": "admin", + "create_time": "2024-05-01 12:00:00", + "update_time": "2024-05-01 12:30:00" } ``` @@ -280,3 +302,304 @@ DELETE http://localhost:8080/graphspaces/gs1 > Warning: deleting a graphspace releases all resources that belong to it. +#### 2.0.6 List all graphspaces with their details + +##### Params + +**Query parameters** + +- prefix: Return only the graphspaces whose name or nickname starts with this prefix + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/profile +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +Each entry carries the same fields as `GET /graphspaces/{graphspace}` plus `authed`, `default`, `create_time` and `update_time`. `authed` says whether the current user may enter the graphspace: it is `false` when the graphspace has authentication on and the user is neither an administrator, nor a manager, nor a member of it. `default` is always `false` for now, the default-graphspace feature is not implemented yet. + +```json +[ + { + "name": "gs1", + "nickname": "gs1", + "description": "1st graph space", + "cpu_limit": 1000, + "memory_limit": 8192, + "storage_limit": 1000000, + "compute_cpu_limit": 0, + "compute_memory_limit": 0, + "oltp_namespace": "hugegraph-server", + "olap_namespace": "hugegraph-server", + "storage_namespace": "hugegraph-server", + "max_graph_number": 100, + "max_role_number": 10, + "cpu_used": 0, + "memory_used": 0, + "storage_used": 0, + "storage_percent": 0.0, + "graph_number_used": 0, + "role_number_used": 0, + "auth": true, + "creator": "admin", + "authed": true, + "default": false, + "create_time": "2024-05-01 12:00:00", + "update_time": "2024-05-01 12:30:00" + } +] +``` + +**Default roles** + +Every graphspace carries four built-in roles, so that a user or a group can be given a whole set of permissions at once: + +- `space`: manager of the graphspace, only an administrator may grant it +- `space_member`: member of the graphspace +- `analyst`: analyst of the graphspace +- `observer`: read-only role, it can be narrowed to a single graph by passing `graph` + +`user` accepts either a user name or a group name. Whether the current user holds a default role can also be checked with `GET /graphspaces/{graphspace}/auth/managers/default`, see [Authentication API](./auth). + +#### 2.0.7 Grant a default role + +##### Params + +**Path parameter** + +- graphspace: Graphspace name + +**Request parameters** + +- user: User or group name, required +- role: One of `space`, `space_member`, `analyst`, `observer`, required +- graph: Graph name, optional, only taken into account with `role=observer` + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/gs1/role +``` + +##### Request Body + +```json +{ + "user": "boss", + "role": "analyst" +} +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +`graph` is echoed back only when the role was granted on a single graph. + +```json +{ + "user": "boss", + "role": "analyst", + "graphSpace": "gs1" +} +``` + +#### 2.0.8 Check a default role + +##### Params + +**Path parameter** + +- graphspace: Graphspace name + +**Query parameters** + +- user: User or group name, required +- role: Default role name, required +- graph: Graph name, optional, only taken into account with `role=observer` + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/gs1/role?user=boss&role=analyst +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "check": true +} +``` + +#### 2.0.9 Revoke a default role + +##### Params + +**Path parameter** + +- graphspace: Graphspace name + +**Query parameters** + +- user: User or group name, required +- role: Default role name, required +- graph: Graph name, optional, only taken into account with `role=observer` + +##### Method & Url + +``` +DELETE http://localhost:8080/graphspaces/gs1/role?user=boss&role=analyst +``` + +##### Response Status + +```json +204 +``` + +**Schema templates** + +A schema template stores a Gremlin schema script under a name, so that a new graph can be initialized with it by passing `schema` when the graph is created, see [Graphs API](./graphs). A template can be updated or deleted by its creator, by a manager of the graphspace, or by an administrator. + +#### 2.0.10 Create a schema template + +##### Params + +**Path parameter** + +- graphspace: Graphspace name + +**Request parameters** + +- name: Template name, required +- schema: Gremlin schema script, required + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/gs1/schematemplates +``` + +##### Request Body + +```json +{ + "name": "template1", + "schema": "schema.propertyKey('name').asText().ifNotExist().create();" +} +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +```json +{ + "name": "template1", + "schema": "schema.propertyKey('name').asText().ifNotExist().create();", + "creator": "admin", + "create": "2024-05-01 12:00:00.000", + "create_time": "2024-05-01 12:00:00.000", + "update": "2024-05-01 12:00:00.000", + "update_time": "2024-05-01 12:00:00.000" +} +``` + +#### 2.0.11 List the schema templates of a graphspace + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/gs1/schematemplates +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "schema_templates": [ + "template1" + ] +} +``` + +#### 2.0.12 Get a schema template + +##### Method & Url + +``` +GET http://localhost:8080/graphspaces/gs1/schematemplates/template1 +``` + +##### Response Status + +```json +200 +``` + +#### 2.0.13 Update a schema template + +Only `schema` can be updated, the name of a template is fixed. + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/gs1/schematemplates/template1 +``` + +##### Request Body + +```json +{ + "schema": "schema.propertyKey('age').asInt().ifNotExist().create();" +} +``` + +##### Response Status + +```json +200 +``` + +#### 2.0.14 Delete a schema template + +##### Method & Url + +``` +DELETE http://localhost:8080/graphspaces/gs1/schematemplates/template1 +``` + +##### Response Status + +```json +204 +``` diff --git a/content/en/docs/clients/restful-api/indexlabel.md b/content/en/docs/clients/restful-api/indexlabel.md index d56c156a6..a8123091e 100644 --- a/content/en/docs/clients/restful-api/indexlabel.md +++ b/content/en/docs/clients/restful-api/indexlabel.md @@ -175,3 +175,53 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/indexla Note: > You can query the execution status of an asynchronous task by using `GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/1` (where "1" is the task_id). For more information, refer to the [Asynchronous Task RESTful API](./task). + +#### 1.5.5 Add or remove userdata for an existing IndexLabel + +Only `user_data` can be changed this way, `base_type`, `base_value` and `index_type` must be left out of the request body. + +##### Params + +- action: Indicates whether the current action is to add or remove userdata. Possible values are `append` (add) and `eliminate` (remove). + +##### Method & Url + +``` +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/indexlabels/personByCity?action=append +``` + +##### Request Body + +```json +{ + "name": "personByCity", + "user_data": { + "comment": "index on city" + } +} +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "id": 1, + "base_type": "VERTEX_LABEL", + "base_value": "person", + "name": "personByCity", + "fields": [ + "city" + ], + "index_type": "SECONDARY", + "user_data": { + "comment": "index on city", + "~create_time": "2022-05-13 13:47:23.745" + } +} +``` diff --git a/content/en/docs/clients/restful-api/other.md b/content/en/docs/clients/restful-api/other.md index 34fb886d2..88cd37445 100644 --- a/content/en/docs/clients/restful-api/other.md +++ b/content/en/docs/clients/restful-api/other.md @@ -2,7 +2,7 @@ title: "Other API" linkTitle: "Other" weight: 18 -description: "Other REST API: Provide auxiliary functions such as system version query and API version information." +description: "Other REST API: Provide auxiliary functions such as version query, API listing, exception trace switch, IP allowlist and the Arthas agent." --- ### 11.1 Other @@ -29,7 +29,273 @@ GET http://localhost:8080/versions "version": "v1", "core": "1.7.0", "gremlin": "3.5.1", - "api": "0.71.0.0" + "api": "0.72.0.0" } } ``` + +#### 11.1.2 View the profile of the server + +Returns the service name, the core version, the documentation links and the API groups served by this node. + +##### Method & Url + +``` +GET http://localhost:8080/ +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +The `swagger_ui` value is derived from `restserver.url`, and `apis` lists the API groups registered on this node, sorted by name. + +```json +{ + "service": "hugegraph", + "version": "1.7.0", + "doc": "https://hugegraph.apache.org/docs/", + "api_doc": "https://hugegraph.apache.org/docs/clients/", + "swagger_ui": "http://127.0.0.1:8080/swagger-ui/index.html", + "apis": [ + "arthas", + "auth", + "cypher", + "filter", + "graph", + "gremlin", + "job", + "metrics", + "profile", + "raft", + "schema", + "space", + "traversers", + "variables" + ] +} +``` + +#### 11.1.3 List all APIs of the server + +Lists every registered resource method, grouped by API group and resource class. Each entry carries the url, the HTTP method and the query parameters with their types and default values. + +##### Method & Url + +``` +GET http://localhost:8080/apis +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +The response is long, the following fragment shows the shape: + +```json +{ + "apis": { + "schema": { + "PropertyKeyAPI": [ + { + "url": "graphspaces/{graphspace}/graphs/{graph}/schema/propertykeys", + "method": "GET", + "parameters": [ + { + "name": "names", + "type": "java.util.List", + "default_value": null + } + ] + } + ] + } + } +} +``` + +#### 11.1.4 View and switch the exception trace stack + +Whether the error responses of the server carry the exception stack in the `exception` and `cause` fields is decided by the `exception.allow_trace` option (default `true`). The switch below is a node-wide runtime override: while it is on, the stack is always included, no matter what the option says. `GET` reports the state of that override, which starts as `false`. + +##### Method & Url + +``` +GET http://localhost:8080/exception/trace +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "trace": false +} +``` + +##### Method & Url + +``` +PUT http://localhost:8080/exception/trace +``` + +##### Request Body + +```json +true +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "trace": true +} +``` + +#### 11.1.5 Manage the IP allowlist, **this operation requires administrator privileges** + +The allowlist is only enforced when it is switched on, see the `white_ip.status` option (default `disable`). + +##### List the allowlist + +##### Method & Url + +``` +GET http://localhost:8080/whiteiplist +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "whiteIpList": [ + "127.0.0.1" + ] +} +``` + +##### Add IPs to or remove IPs from the allowlist + +##### Params + +- ips: list of IPv4 addresses +- action: `load` to add, `remove` to delete + +##### Method & Url + +``` +POST http://localhost:8080/whiteiplist +``` + +##### Request Body + +```json +{ + "ips": [ + "10.0.0.1", + "10.0.0.2" + ], + "action": "load" +} +``` + +##### Response Status + +```json +202 +``` + +##### Response Body + +`existed_ips` are the addresses already in the list, `added_ips` are the newly added ones, and `illegal_ips` is only returned when some addresses are not valid IPv4 addresses. For `action=remove` the response carries `removed_ips` and `non_existed_ips` instead. + +```json +{ + "existed_ips": [], + "added_ips": [ + "10.0.0.1", + "10.0.0.2" + ] +} +``` + +##### Enable or disable the allowlist + +##### Params + +- status: `true` to enable, `false` to disable + +##### Method & Url + +``` +PUT http://localhost:8080/whiteiplist?status=true +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +```json +{ + "WhiteIpListOpen": true +} +``` + +#### 11.1.6 Start the Arthas agent + +Attaches the [Arthas](https://arthas.aliyun.com/en/) agent to the running server process for diagnosis. The ports, the bind IP and the disabled commands are taken from the `arthas.telnetPort`, `arthas.httpPort`, `arthas.ip` and `arthas.disabledCommands` options, see [Config Options](/docs/config/config-option/). + +##### Method & Url + +``` +PUT http://localhost:8080/arthas +``` + +##### Response Status + +```json +200 +``` + +##### Response Body + +The applied Arthas configuration is returned: + +```json +{ + "arthas.telnetPort": "8562", + "arthas.httpPort": "8561", + "arthas.ip": "0.0.0.0", + "arthas.disabledCommands": "jad" +} +``` diff --git a/content/en/docs/clients/restful-api/rank.md b/content/en/docs/clients/restful-api/rank.md index 9e335292c..7edd7d6ae 100644 --- a/content/en/docs/clients/restful-api/rank.md +++ b/content/en/docs/clients/restful-api/rank.md @@ -149,7 +149,7 @@ A random walk based PersonalRank algorithm should be likes this: **Optional**: - alpha: the probability of going out for one vertex in each iteration，similar to the alpha of PageRank,required, value range is (0, 1], default 0.85. - max_degree: in query process, the max iteration number of adjacency edge for a vertex, default `10000` -- max_depth: iteration number,range [2, 50], default `5` +- max_depth: iteration number,range [2, 5000], default `5` - with_label：result filter,default `BOTH_LABEL`,optional list as follows: - SAME_LABEL：Only keep vertex which has the same type as source vertex - OTHER_LABEL：Only keep vertex which has different type as source vertex (the another part in bipartite graph) @@ -311,7 +311,8 @@ In graph words: to go out from the starting point, get the probability of going - labels：a list of edge types, will union all edge types - max_degree：in query process, the max iteration number of adjacency edge for a vertex, default `10000` (Note: before v0.12 step only support degree as parameter name, from v0.12, use max_degree, compatible with degree) - - top： retains only the top N results with the highest weight in each layer of the results, default 100, max 1000 + - skip_degree: the threshold above which a super vertex is skipped in this layer, default `0` (no skipping) + - top： retains only the top N results with the highest weight in each layer of the results, default 10, max 1000 - capacity: the maximum number of vertexes visited during the traversal, optional, default 10000000 ##### 4.2.2.2 Usage diff --git a/content/en/docs/clients/restful-api/task.md b/content/en/docs/clients/restful-api/task.md index ef5097014..8221e035d 100644 --- a/content/en/docs/clients/restful-api/task.md +++ b/content/en/docs/clients/restful-api/task.md @@ -11,8 +11,10 @@ description: "Task REST API: Query and manage asynchronous task execution status ##### Params -- status: the status of asyncTasks -- limit: the max number of tasks to return +- status: the status of asyncTasks, one of NEW, SCHEDULING, SCHEDULED, QUEUED, RESTORING, RUNNING, SUCCESS, CANCELLING, CANCELLED, FAILED, HANGING, DELETING, case-insensitive +- ids: task ids to query, can be repeated. It can not be combined with `status` or `page`, and it ignores `limit`. +- limit: the max number of tasks to return, default is 100 +- page: page token for pagination. When it is passed, the response carries a `page` field with the token of the next page. ##### Method & Url @@ -48,6 +50,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks?status=succ #### 7.1.2 View the details of an async task +##### Params + +- with_result: whether to load the result of the task, default is true + ##### Method & Url ``` @@ -80,6 +86,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2 #### 7.1.3 Delete task information of an async task,**won't delete the task itself** +##### Params + +- force: whether to delete the task even when it is still running, default is false + ##### Method & Url ``` @@ -121,12 +131,107 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2?action=ca 202 ``` +Cancelling a task that is already completed or already cancelling returns `400`. + ##### Response Body +The whole task object is returned, with `task_status` set to `cancelling` or `cancelled`: + +```json +{ + "task_name": "for (int i = 0; i < 10; i++) {...}", + "task_progress": 0, + "task_create": 1532943976585, + "task_status": "cancelling", + "task_update": 1532943977001, + "task_retries": 0, + "id": 2, + "task_type": "gremlin", + "task_callable": "org.apache.hugegraph.api.job.GremlinAPI$GremlinJob" +} +``` + +At this point, the number of vertices whose label is man must be less than 10. + +### 7.2 Algorithm Job + +Schedules an OLAP algorithm as an asynchronous task inside the server. The task id in the response can be followed with the Task API above. + +##### Params + +**Path parameters** + +- graphspace: Graphspace name +- graph: Graph name +- name: Algorithm name. The registered algorithms are `count_vertex`, `count_edge`, `degree_centrality`, `stress_centrality`, `betweenness_centrality`, `closeness_centrality`, `eigenvector_centrality`, `triangle_count`, `cluster_coefficient`, `lpa`, `louvain`, `weak_connected_component`, `fusiform_similarity`, `rings`, `k_core`, `page_rank` and `subgraph_stat`. An unknown name returns `404`. + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/algorithm/page_rank +``` + +##### Request Body + +The body is the parameter map of the algorithm, and each algorithm validates its own parameters. Pass `{}` to run with the defaults. + ```json { - "cancelled": true + "alpha": 0.15, + "times": 10 } ``` -At this point, the number of vertices whose label is man must be less than 10. \ No newline at end of file +##### Response Status + +```json +201 +``` + +##### Response Body + +```json +{ + "task_id": 1 +} +``` + +### 7.3 Computer Job + +Schedules a HugeGraph-Computer job as an asynchronous task. The computer job runs outside the server, see [HugeGraph-Computer](/docs/quickstart/computing/hugegraph-computer). + +##### Params + +**Path parameters** + +- graphspace: Graphspace name +- graph: Graph name +- name: Computer name. The registered computers are `page_rank`, `weak_connected_component`, `lpa`, `triangle_count` and `louvain`. An unknown name returns `404`. + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/computer/page_rank +``` + +##### Request Body + +The body is the parameter map of the computer job. Pass `{}` to run with the defaults. + +```json +{} +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +```json +{ + "task_id": 2 +} +``` diff --git a/content/en/docs/clients/restful-api/traverser.md b/content/en/docs/clients/restful-api/traverser.md index 1aa85e160..6bd63cfa9 100644 --- a/content/en/docs/clients/restful-api/traverser.md +++ b/content/en/docs/clients/restful-api/traverser.md @@ -35,10 +35,6 @@ The Traverser API supported by HugeGraph includes: - Paths API: It finds all paths between two vertices. There are two versions: - The basic version uses the GET method to find all paths between a given starting vertex and an ending vertex. - The advanced version uses the POST method to find all paths that meet certain conditions between a set of starting vertices and a set of ending vertices. -### 3.2 Detailed Explanation of Traverser API - -In the following, we provide a detailed explanation of the Traverser API: - - Customized Paths API: It traverses all paths that pass through a batch of vertices according to a specific pattern. - Template Path API: It specifies a starting point, an ending point, and the path information between them to find matching paths. - Crosspoints API: It finds the intersection (common ancestors or common descendants) between two vertices. @@ -46,6 +42,10 @@ In the following, we provide a detailed explanation of the Traverser API: - Rings API: It finds the cyclic paths that can be reached from a starting vertex. - Rays API: It finds the paths from a starting vertex that reach the boundaries (i.e., paths without cycles). - Fusiform Similarity API: It finds the fusiform similar vertices to a given vertex. +- Adamic-Adar API: It computes the Adamic-Adar index of two vertices. +- Resource Allocation API: It computes the resource allocation index of two vertices. +- Edge Existence API: It returns the edges that exist between two given vertices. +- Count API: It counts the vertices reached after a series of traversal steps, without returning them. - Vertices API: - Batch querying vertices by ID. - Getting the partitions of vertices. @@ -3050,3 +3050,213 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/traversers/edges/ - Querying edges based on ID list, suitable for batch retrieval of edges. - Retrieving shard information and querying edges based on shards, useful for traversing all edges. + +#### 3.2.24 Adamic-Adar + +##### 3.2.24.1 Function Introduction + +Compute the [Adamic-Adar](https://en.wikipedia.org/wiki/Adamic/Adar_index) index of two vertices: the sum of the reciprocal of the logarithm of the degree of each common neighbor. + +###### Params + +- vertex: ID of one vertex, required. +- other: ID of another vertex, required. It must differ from `vertex`. +- direction: Direction in which the vertex expands outward (OUT, IN, BOTH). Optional, default is BOTH. +- label: Edge type. Optional, default represents all edge labels. +- max_degree: Maximum number of adjacent edges to traverse for each vertex during the query process. Optional, default is 10000. +- limit: Maximum number of common neighbors taken into account. Optional, default is 10000000. + +##### 3.2.24.2 Usage Method + +###### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/adamicadar?vertex="1:marko"&other="1:josh" +``` + +###### Response Status + +```json +200 +``` + +###### Response Body + +Common neighbors with a degree of 0 are skipped, so the result is 0.0 when the two vertices share no neighbor. + +```json +{ + "adamic_adar": 0.9102392266268373 +} +``` + +##### 3.2.24.3 Use Cases + +Predict whether a link is likely to appear between two vertices, where rare common neighbors weigh more than popular ones. + +#### 3.2.25 Resource Allocation + +##### 3.2.25.1 Function Introduction + +Compute the resource allocation index of two vertices: the sum of the reciprocal of the degree of each common neighbor. + +###### Params + +- vertex: ID of one vertex, required. +- other: ID of another vertex, required. It must differ from `vertex`. +- direction: Direction in which the vertex expands outward (OUT, IN, BOTH). Optional, default is BOTH. +- label: Edge type. Optional, default represents all edge labels. +- max_degree: Maximum number of adjacent edges to traverse for each vertex during the query process. Optional, default is 10000. +- limit: Maximum number of common neighbors taken into account. Optional, default is 10000000. + +##### 3.2.25.2 Usage Method + +###### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/resourceallocation?vertex="1:marko"&other="1:josh" +``` + +###### Response Status + +```json +200 +``` + +###### Response Body + +```json +{ + "resource_allocation": 0.3333333333333333 +} +``` + +##### 3.2.25.3 Use Cases + +Link prediction, as an alternative to Adamic-Adar with a stronger penalty on high-degree common neighbors. + +#### 3.2.26 Edge Existence + +##### 3.2.26.1 Function Introduction + +Return the edges that exist between a source vertex and a target vertex. + +###### Params + +- source: ID of the source vertex, required. +- target: ID of the target vertex, required. +- label: Edge type. Optional, default represents all edge labels. +- sort_values: Value of the sort keys, required for edge labels of the `MULTIPLE` frequency to pick one of several parallel edges. Optional, default is an empty string. +- limit: Maximum number of edges to be returned. Optional, default is 100. + +##### 3.2.26.2 Usage Method + +###### Method & Url + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/edgeexist?source="1:marko"&target="2:lop" +``` + +###### Response Status + +```json +200 +``` + +###### Response Body + +```json +{ + "edges":[ + { + "id":"S1:marko>2>>S2:lop", + "label":"created", + "type":"edge", + "inVLabel":"software", + "outVLabel":"person", + "inV":"2:lop", + "outV":"1:marko", + "properties":{ + "weight":0.4, + "date":"20171210" + } + } + ] +} +``` + +##### 3.2.26.3 Use Cases + +Check whether two vertices are directly connected, and get the properties of the connecting edges in one request. + +#### 3.2.27 Count + +##### 3.2.27.1 Function Introduction + +Count the vertices reached from a starting vertex after a series of traversal steps, without returning the vertices themselves. + +###### Params + +- source: ID of the starting vertex, required. +- steps: Steps of the traversal, required. Each step accepts the following fields: + - direction: Direction in which the vertex expands outward (OUT, IN, BOTH). Optional, default is BOTH. + - labels: List of edge labels of the step. Optional, default represents all edge labels. + - properties: Property filter of the edges of the step. Optional. + - max_degree: Maximum number of adjacent edges to traverse for each vertex in this step. Optional, default is 10000. + - skip_degree: Threshold above which a super vertex is skipped in this step. Optional, default is 100000. +- contains_traversed: Whether to also count the vertices reached by the intermediate steps. Optional, default is false. +- dedup_size: Maximum number of vertices kept for deduplication, `-1` means no limit. Optional, default is 1000000. + +##### 3.2.27.2 Usage Method + +###### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/count +``` + +###### Request Body + +```json +{ + "source": "1:marko", + "steps": [ + { + "direction": "BOTH", + "labels": [], + "max_degree": 100, + "skip_degree": 100 + }, + { + "direction": "BOTH", + "labels": [], + "max_degree": 100, + "skip_degree": 100 + }, + { + "direction": "BOTH", + "labels": [], + "max_degree": 100, + "skip_degree": 100 + } + ] +} +``` + +###### Response Status + +```json +200 +``` + +###### Response Body + +```json +{ + "count": 3 +} +``` + +##### 3.2.27.3 Use Cases + +Get the size of a multi-step neighborhood when only the number matters, so the vertices do not have to be serialized and transferred. diff --git a/content/en/docs/clients/restful-api/vertex.md b/content/en/docs/clients/restful-api/vertex.md index ab401f5da..52d604c4e 100644 --- a/content/en/docs/clients/restful-api/vertex.md +++ b/content/en/docs/clients/restful-api/vertex.md @@ -367,10 +367,12 @@ PUT http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices/"1 - label: Vertex type - properties: Property key-value pairs (precondition: indexes are created for property queries) -- limit: Maximum number of results +- keep_start_p: Default is false. When set to true, the range matching input expression will not be automatically escaped. For example, `properties={"age":"P.gt(18)"}` will be interpreted as an exact match, i.e., the age property is equal to the string "P.gt(18)" +- offset: Offset, default is 0 +- limit: Maximum number of results, default is 100 - page: Page number -All of the above parameters are optional. If the `page` parameter is provided, the `limit` parameter must also be provided, and no other parameters are allowed. `label, properties`, and `limit` can be combined in any way. +All of the above parameters are optional. `page` can not be combined with a non-zero `offset`, everything else can be combined in any way. Property key-value pairs consist of the property name and value in JSON format. Multiple property key-value pairs are allowed as query conditions. The property value supports exact matching, range matching, and fuzzy matching. For exact matching, use the format `properties={"age":29}`, for range matching, use the format `properties={"age":"P.gt(29)"}`, and for fuzzy matching, use the format `properties={"city": "P.textcontains("ChengDu China")}`. The following expressions are supported for range matching: diff --git a/content/en/docs/config/config-authentication.md b/content/en/docs/config/config-authentication.md index 1f646635f..f5de712c5 100644 --- a/content/en/docs/config/config-authentication.md +++ b/content/en/docs/config/config-authentication.md @@ -41,7 +41,7 @@ curl -u 'admin:' \ http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels ``` -**Warning**: Versions of HugeGraph-Server prior to 1.5.0 have a JWT-related security vulnerability in the Auth mode. +**Warning**: Versions of HugeGraph-Server prior to 1.5.0 have a JWT-related security vulnerability in the Auth mode. Users are advised to update to a newer version or manually set the JWT token's secretKey. It can be set in the `rest-server.properties` file by setting the `auth.token_secret` information: ```properties @@ -55,6 +55,10 @@ RANDOM_STRING=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32) echo "auth.token_secret=${RANDOM_STRING}" >> rest-server.properties ``` +Since 1.5.0 the option defaults to a key generated randomly at startup, so it does not have to be configured. Set it +explicitly when tokens have to survive a restart, or when more than one server must accept the same token. Tokens expire +after `auth.token_expire` seconds (default 86400). + #### StandardAuthenticator Mode The `StandardAuthenticator` mode supports user authentication and permission control by storing user information in the database backend. This implementation authenticates users based on their names and passwords (encrypted) stored in the database and controls user permissions based on their @@ -75,7 +79,7 @@ Configure the authenticator and the graph that stores authorization data in `res ```properties auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator auth.graph_store=hugegraph -# The initial admin password can be set when the admin user is first created in PD mode +# The password of the built-in admin account, default is pa, it takes effect on the first startup #auth.admin_pa= # Auth Client Config diff --git a/content/en/docs/config/config-https.md b/content/en/docs/config/config-https.md index 6387fc2c7..ac3491bd1 100644 --- a/content/en/docs/config/config-https.md +++ b/content/en/docs/config/config-https.md @@ -21,7 +21,11 @@ ssl.keystore_file=conf/hugegraph-server.keystore ssl.keystore_password=****** ``` -The server's `conf` directory already includes a keystore file named `hugegraph-server.keystore`, and the password for this file is `hugegraph`. These are the default values when enabling the HTTPS protocol. Users can generate their own keystore file and password, and then modify the values of `ssl.keystore_file` and `ssl.keystore_password`. +The keystore file is not shipped inside the distribution, because it carries no license declaration. When `restserver.url` +starts with `https` and `conf/hugegraph-server.keystore` is missing, `bin/start-hugegraph.sh` downloads it from the +`binary-1.5` branch of the hugegraph-doc repository before starting the server. The password of that file is `hugegraph`. +Both values are the defaults of `ssl.keystore_file` and `ssl.keystore_password`; users can generate their own keystore +file and password and then change the two options. ### Client Configuration diff --git a/content/en/docs/guides/backup-restore.md b/content/en/docs/guides/backup-restore.md index 423dc6a59..2ab1d7d9e 100644 --- a/content/en/docs/guides/backup-restore.md +++ b/content/en/docs/guides/backup-restore.md @@ -125,9 +125,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode } ``` -> Legal graph modes include: NONE, RESTORING, MERGING +> Legal graph modes include: NONE, RESTORING, MERGING, LOADING -##### Set the mode of a graph. ""This operation requires administrator privileges** +##### Set the mode of a graph. **This operation requires administrator privileges** ###### Method & Url @@ -141,7 +141,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode "RESTORING" ``` -> Legal graph modes include: NONE, RESTORING, MERGING +> Legal graph modes include: NONE, RESTORING, MERGING, LOADING ###### Response Status