Other API

Other（其他接口）REST 接口:提供版本查询、API 列表、异常堆栈开关、IP 白名单和 Arthas 诊断代理等辅助功能。

11.1 Other

11.1.1 查看HugeGraph的版本信息

Method & Url

GET http://localhost:8080/versions

Response Status

Response Body

{
    "versions": {
        "version": "v1",
        "core": "1.7.0",
        "gremlin": "3.5.1",
        "api": "0.72.0.0"
    }
}

11.1.2 查看服务的概要信息

返回服务名、内核版本、文档地址以及当前节点注册的 API 分组。

Method & Url

GET http://localhost:8080/

Response Status

Response Body

swagger_ui 由 restserver.url 拼接得到，apis 是当前节点注册的 API 分组，按名称排序。

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

Response Body

返回内容较长，下面的片段展示了它的结构：

{
    "apis": {
        "schema": {
            "PropertyKeyAPI": [
                {
                    "url": "graphspaces/{graphspace}/graphs/{graph}/schema/propertykeys",
                    "method": "GET",
                    "parameters": [
                        {
                            "name": "names",
                            "type": "java.util.List<java.lang.String>",
                            "default_value": null
                        }
                    ]
                }
            ]
        }
    }
}

11.1.4 查看和切换异常堆栈开关

服务返回的错误信息中是否带上 exception 和 cause 等异常堆栈字段，由 exception.allow_trace 配置项（默认 true）决定。下面的接口是一个节点级别的运行期覆盖开关：打开时无论配置项取值如何都会带上堆栈。GET 返回的是该覆盖开关的状态，初始为 false。

Method & Url

GET http://localhost:8080/exception/trace

Response Status

Response Body

{
    "trace": false
}

Method & Url

PUT http://localhost:8080/exception/trace

Request Body

true

Response Status

Response Body

{
    "trace": true
}

11.1.5 管理 IP 白名单，该操作需要管理员权限

白名单只在开关打开时生效，参见 white_ip.status 配置项（默认 disable）。

查看白名单

Method & Url

GET http://localhost:8080/whiteiplist

Response Status

Response Body

{
    "whiteIpList": [
        "127.0.0.1"
    ]
}

向白名单添加或删除 IP

Params

ips: IPv4 地址列表
action: load 表示添加，remove 表示删除

Method & Url

POST http://localhost:8080/whiteiplist

Request Body

{
    "ips": [
        "10.0.0.1",
        "10.0.0.2"
    ],
    "action": "load"
}

Response Status

Response Body

existed_ips 是已经在白名单中的地址，added_ips 是新增的地址，illegal_ips 只在存在非法 IPv4 地址时返回。action=remove 时返回的是 removed_ips 和 non_existed_ips。

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

Response Body

{
    "WhiteIpListOpen": true
}

11.1.6 启动 Arthas 诊断代理

将 Arthas 代理挂载到正在运行的服务进程上用于诊断。端口、绑定 IP 和禁用命令取自 arthas.telnetPort、arthas.httpPort、arthas.ip 和 arthas.disabledCommands 配置项，参见配置项。

Method & Url

PUT http://localhost:8080/arthas

Response Status

Response Body

返回生效的 Arthas 配置：

{
    "arthas.telnetPort": "8562",
    "arthas.httpPort": "8561",
    "arthas.ip": "0.0.0.0",
    "arthas.disabledCommands": "jad"
}