API 文档与接口参考

入门指南

API 调用概述

了解 WAFGO HTTP API 的接口地址、认证方式、请求格式与响应状态，完成首次接口调用。

接口地址

调用 API 前，需要先取得已配置的 HTTP API 接口地址。如果还没有该地址，请先在 API 节点中启用并添加 HTTP API 监听地址，具体见下方“API 节点设置”。

这里的 HTTP API 接口地址不是 gRPC 地址，也不是管理系统的访问地址。

调用具体方法时，在 API 接口地址后依次拼接服务名和方法名。

地址格式

API接口地址/服务名/方法名

地址示例

http://192.168.2.100/ServerService/createServer

查看 API 节点设置

API 节点设置

在管理系统的 API 节点配置中启用 HTTP API，并添加供接口调用使用的监听地址。请使用实际配置的协议、主机和端口。

节点定义中的 restIsOn 控制是否启用 API；restHTTPJSON 与 restHTTPSJSON 分别配置 HTTP 和 HTTPS API 地址。不要将普通节点监听配置 httpJSON、httpsJSON 与这些 API 地址配置混淆。

下方链接用于查阅节点配置字段和 HTTP 地址结构；具体设置应在你的管理系统中完成。

查看 API 节点配置字段查看 HTTP 地址配置结构

调用方法

除获取令牌的 /APIAccessTokenService/getAPIAccessToken 接口外，其他接口都需要在 HTTP Header 中传入 X-Edge-Access-Token，以认证调用方是否具有接口访问权限。

使用 POST 方法提交完整的 JSON 请求体，并设置 Content-Type: application/json。接口响应也使用 JSON 格式。

以下示例查询访问日志。请根据实际业务替换 serverId、day、size 等参数；YOUR_ACCESS_TOKEN 需要替换为通过认证接口获取的有效令牌。

HTTP 请求示例

POST /HTTPAccessLogService/listHTTPAccessLogs HTTP/1.1
Host: 192.168.2.100
Content-Type: application/json
X-Edge-Access-Token: YOUR_ACCESS_TOKEN

{
  "serverId": 23,
  "day": "20210101",
  "size": 100,
  "reverse": true
}

查看认证与令牌获取方法查看访问日志接口定义

cURL 示例

将示例中的 IP 地址、端口和 YOUR_ACCESS_TOKEN 替换成你自己的 HTTP API 地址与访问令牌，再按需调整请求数据。

使用 cURL 查询访问日志

curl -v -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Edge-Access-Token: YOUR_ACCESS_TOKEN' \
  'http://192.168.1.6:8004/HTTPAccessLogService/listHTTPAccessLogs' \
  -d '{
    "size": 100,
    "day": "20211217"
  }'

格式化输出

在 HTTP Header 中添加 X-Edge-Response-Pretty: on，可以让响应 JSON 以更易阅读的格式输出。

格式化响应 Header

X-Edge-Response-Pretty: on

HTTP 状态码

每次调用后都应先检查 HTTP 响应状态码。只有 HTTP 200 才表示本次 HTTP 调用成功；这里的状态码不是响应 JSON 中的 code 字段，二者不能互相替代。

收到 HTTP 200 后，再按照对应接口的响应结构检查业务结果。例如，获取令牌接口还需要检查 JSON 中的 code 是否为 200。

200: HTTP 调用成功，继续读取并检查该接口的 JSON 响应。
400: 请求格式错误，可能是请求内容过大或 JSON 数据格式不正确。
404: API 服务或方法不存在，或请求使用了错误的 API 路径。

常见问题

调用时提示 Received HTTP/0.9 when not allowed，应该如何处理？: 先检查是否已在 API 节点中添加 HTTP API 接口地址，并确认当前请求使用的是该地址。不要使用 gRPC 地址或管理系统地址代替；完成 HTTP API 地址配置后再重试。

返回 API 节点设置