pyGoEdge-UserPanel/reference/goedge 文档/README.md

# GoEdge API 文档

## 协议说明

理解proto3协议
服务和方法
以 Service 结尾的API成为服务，比如 ServerService，每个服务下有很多方法，比如：

createServer
updateServerBasic
updateServerGroupIds
在通过HTTP协议调用API时，你需要组合服务和方法，作为方法的地址：
API接口地址/服务名/方法名
比如：
http://192.168.2.100/ServerService/createServer
接口参数解读
假设我们看到以下的接口参数定义：

// 创建服务
{
    int64 userId;
    int64 adminId;
    string type;
    string name;
    string description;
​
    // 配置相关
    bytes serverNamesJSON;
    bytes httpJSON;
    bytes httpsJSON;
    bytes tcpJSON;
    bytes tlsJSON;
    bytes unixJSON;
    bytes udpJSON;
    int64 webId;
    bytes reverseProxyJSON;
    []int64 serverGroupIds;
    int64 userPlanId;
}
其中：

每个字段定义都至少由两部分组成，最简单的定义为 字段类型 字段名，这里我们省略了字段编号；
int64和 string 等都是字段数据类型，目前支持以下常用的数据类型：
int64 - 64位整型
int32 - 32位整型
uint64 - 无符号的64位整型
uint32 - 无符号的32位整型
double - 双精度浮点数字
float - 单精度浮点数字
string - 字符串
bool - 布尔值，在JSON中为 true 或者 false
bytes - 二进制字节数组，通过JSON调用时，你需要先将数据转换为Base64格式，再传递到接口，比如：
一个字符串的内容为Hello, World，那么传递到 bytes 类型字段的时候就需要传递 base64_encode('Hello, World')，最终值应该为 SGVsbG8sIFdvcmxk
一个JSON数据的内容为{ "name": "goedge.cloud", "type": "domain"}，那么传递到 bytes 类型字段的时候就需要传递 base64_encode('{ "name": "goedge.cloud", "type": "domain"}')，最终值应该为 eyAibmFtZSI6ICJnb2VkZ2UuY24iLCAidHlwZSI6ICJkb21haW4ifQ==
一个文件内容的二进制内容同样也需要Base64编码处理
反之，对于接口返回的响应数据来说，你需要Base64 Decode处理才能得到原始数据
[]字段类型 字段名 表示一个数组，字段类型 部分表示字段值数组中的元素的类型，比如：
[]int64 serverGroupIds 表示 serverGroupIds 是一个数组，通过JSON调用时需要传递[ 1, 2, 3 ]这样格式的数据，其中 int64 规定了数组中的每一项必须是一个整型；
[]string types 表示 types 的值为 [ "type1", "type2" ] 这样的数组
[]ServerGroup serverGroups 表示 serverGroups 的只为 [ serverGroup1, serverGroup2, serverGroup3 ] 这样的数组，因为ServerGroup也是一个对象，所以我们可以展开来，最终的JSON为：[ { "id":1, "name": "分组1" }, { "id":2, "name": "分组2" }, { "id":3, "name": "分组3" } ]
整体转换为JSON
通过JSON调用API时，需要将proto3协议的数据转换为JSON。对于这个示例中，和JSON的对应关系为：

{
  "userId": 35,
  "adminId": 1,
  "type": "httpProxy",
  "name": "My site",
  "description": "This is my site",
​
  "serverNamesJSON": "ewogICJuYW1lIjogImdvZWRnZS5jbiIKfQ==",
  "httpJSON": "...",
  "httpsJSON": "...",
  "tcpJSON": "...",
  "tlsJSON": "...",
  "unixJSON": "...",
  "udpJSON": "...",
  "webId": "...",
  "reverseProxyJSON": "...",
  "serverGroupIds": [1, 3, 5],
  "userPlanId": 12
}
嵌套
JSON数据也支持嵌套：

{
  "name": "Site",
  "addr": {
    "protocol": "http",
    "host": "example.com",
    "portRange": "80"
  }
}
空参数
有些接口参数定义为：

{
​
}
像这样的接口需要传递的JSON为：
{}
即可。
字符集
GoEdge所有API都只支持UTF-8。

API调用概述
接口地址
如果你还没有HTTP接口地址，可以先在API节点中添加一个，请参考 API节点设置。

注意：这里说的HTTP接口地址不是GRPC地址，也不是管理系统地址。

如果想调用某个具体的方法，那么地址就是：

API接口地址/服务名/方法名
比如：
http://192.168.2.100/ServerService/createServer
调用方法
除了 /APIAccessTokenService/getAPIAccessToken 接口外，其他的所有接口都需要：

在HTTP Header中传递X-Edge-Access-Token令牌数据，以便于我们认证用户是否有接口访问的权限，此令牌通过 /APIAccessTokenService/getAPIAccessToken 接口获取，具体请参考 认证 一节。
所有请求数据需要以 POST 方法上传一个完整的JSON数据，接口响应数据也是JSON数据
比如：

POST /HTTPAccessLogService/listHTTPAccessLogs
...
X-Edge-Access-Token: n8adDybtPCAGdbORkXjfpJgL28EGkOLz
...
​
{
    "serverId": 23,
    "day": "20210101",
    "size": 100,
    "reverse": true
}
可以在这里查看令牌获取方法。

CURL示例
curl -v -XPOST -H"X-Edge-Access-Token: hZFW3yg1geeKYqLPjhmi5OyAtYoKingiNoemNkqjLWIsCXJcmaHDaUL1ELX6vtPrjvwiXiTuBN9mAVK8cUhn6PpuN1eLYbtN1seAFMpf2h6aZtFgkhAxI3cYUSZIwLQg"  "http://192.168.1.6:8004/HTTPAccessLogService/listHTTPAccessLogs" -d '{
  "size":100, 
  "day":"20211217"
}'
你需要把IP地址、X-Edge-Access-Token换成你自己的。
格式化输出
可以在HTTP Header中增加 X-Edge-Response-Pretty: on 来让输出的JSON更加可读。

HTTP状态码
调用API后，一定 要检查API响应的HTTP状态码（注意是HTTP状态码，不是JSON里面的code），只有200才是响应成功，以下是常见的几种响应状态码错误：

400 - 错误的请求格式（可能是发送的内容过大、或JSON数据格式错误）
404 - API服务或方法不存在，或错误的API路径
常见问题
调用API的时候提示 Received HTTP/0.9 when not allowed 是怎么回事？
答：你没有按照本文开头部分所说的添加HTTP接口地址，请 点击这里 添加HTTP接口地址后再重试。

API认证
在调用API时，需要通过令牌（AccessToken）对用户权限进行认证。

步骤1：创建AccessKey
AccessKey分为两种，一种是是用户AccessKey，可以用来管理跟此用户相关的数据，另外一种是管理员API，可以管理所有管理员能操作的数据。

用户AccessKey
从v0.2.1开始，如果你还没有用户AccessKey，则需要在”平台用户” – 用户”详情” – “API AccessKey”中创建。

商业版的用户可以自行在用户平台”访问控制”页面中点击”创建AccessKey”，然后创建一个AccessKey。

管理员AccessKey
从v0.2.3开始，如果你还没有管理员AccessKey，则需要在”系统用户” – 用户”详情” – “API AccessKey”中创建。

步骤2：调用API获取AccessToken
接口地址
/APIAccessTokenService/getAPIAccessToken
请求方法
POST。

请求参数
{
    "type": "admin",
    "accessKeyId": "zr9cmR42AEZxRyIV",
    "accessKey": "2w5p5NSZZuplUPsfPMzM7dFmTrI7xyja"
}
其中
type - 如果是用户（即平台用户）AccessKey，则值为 user；如果是管理员（即系统用户）AccessKey，则值为 admin；
accessKeyId 和 accessKey 换成你在步骤1中创建的AccessKey对应的数据。
响应结果
{
   "code": 200,
   "data": {
      "token": "IKNSMufZ1vDiXp5rSd9QR01m1174Oum5sah4amWFgbRb7lOKjuk62Spl7hgcazctzGhGG7jPgfmYUPojulC0FK5cLbrj8n7kxW7BtSawH9gWW14IWOzBY6UcpyXQndFu",
      "expiresAt": 1609686945
   },
   "message": "ok"
}
其中：
code - 如果是 200 表示成功，否则表示失败
token - 就是AccessToken，可以在别的接口中通过HTTP Header X-Edge-Access-Token 传入；
expiresAt - 过期时间戳，默认为N个小时，过期后请及时重新获取。
多次调用此接口会导致先前获取的AccessToken失效。

CURL示例
对管理员来说，可以使用curl命令调用接口获得Token：

curl -XPOST "http://192.168.1.6:8004/APIAccessTokenService/getAPIAccessToken" -d '{
   "type":"admin",
   "accessKeyId":"zr9cmR42AEZxRyIV", 
   "accessKey":"2w5p5NSZZuplUPsfPMzM7dFmTrI7xyja"
}'
你需要把API地址、accessKeyId、accessKey换成你自己的。
对平台用户来说，可以使用curl命令调用接口获得Token：

curl -XPOST "http://192.168.1.6:8004/APIAccessTokenService/getAPIAccessToken" -d '{
   "type":"user",
   "accessKeyId":"JOvsyXIFqkQbh5kl", 
   "accessKey":"t0RY8YO3R58VbJJNp0RqKw9KWNpObwtE"
}'
你需要把API地址、accessKeyId、accessKey换成你自己的。
步骤3：调用API
在 API列表 找到要调用的API，然后以POST方式调用 /服务/方法 组合后的URL，在Header中加入 X-Edge-Access-Token ，值为步骤2中的生成的AccessToken接口，具体可以参考 API调用概述 。

## API 服务列表

- [ACMEProviderAccountService](./ACMEProviderAccountService.md) — ACME服务商账号
- [ACMEProviderService](./ACMEProviderService.md) — ACME服务商
- [ACMETaskService](./ACMETaskService.md) — ACME任务相关服务
- [ACMEUserService](./ACMEUserService.md) — ACME用户相关服务
- [ADNetworkService](./ADNetworkService.md) — 高防线路服务
- [ADPackageInstanceService](./ADPackageInstanceService.md) — 高防实例服务
- [ADPackagePeriodService](./ADPackagePeriodService.md) — 高防实例有效期服务
- [ADPackagePriceService](./ADPackagePriceService.md) — 高防产品价格服务
- [ADPackageService](./ADPackageService.md) — 高防产品服务
- [APIMethodStatService](./APIMethodStatService.md) — API方法统计服务
- [APINodeService](./APINodeService.md) — API节点服务
- [AdminService](./AdminService.md) — 管理员服务
- [ClientAgentIPService](./ClientAgentIPService.md) — Agent IP服务
- [ClientAgentService](./ClientAgentService.md) — Agent服务
- [DBNodeService](./DBNodeService.md) — 数据库节点服务
- [DBService](./DBService.md) — 数据库相关服务
- [DNSDomainService](./DNSDomainService.md) — DNS域名相关
- [DNSProviderService](./DNSProviderService.md) — DNS服务商相关服务
- [DNSService](./DNSService.md) — 域名解析服务
- [DNSTaskService](./DNSTaskService.md) — DNS同步相关任务
- [FileChunkService](./FileChunkService.md) — 文件片段相关服务
- [FileService](./FileService.md) — 文件相关服务
- [FirewallService](./FirewallService.md) — 防火墙全局服务
- [FormalClientBrowserService](./FormalClientBrowserService.md) — 浏览器信息库服务
- [FormalClientSystemService](./FormalClientSystemService.md) — 操作系统信息库服务
- [HTTPAccessLogPolicyService](./HTTPAccessLogPolicyService.md) — 访问日志策略服务
- [HTTPAccessLogService](./HTTPAccessLogService.md) — 访问日志相关服务
- [HTTPAuthPolicyService](./HTTPAuthPolicyService.md) — 服务认证策略服务
- [HTTPCachePolicyService](./HTTPCachePolicyService.md) — 缓存策略服务
- [HTTPCacheTaskKeyService](./HTTPCacheTaskKeyService.md) — 缓存任务Key管理
- [HTTPCacheTaskService](./HTTPCacheTaskService.md) — 缓存任务管理
- [HTTPFastcgiService](./HTTPFastcgiService.md) — Fastcgi服务
- [HTTPFirewallPolicyService](./HTTPFirewallPolicyService.md) — HTTP防火墙（WAF）服务
- [HTTPFirewallRuleGroupService](./HTTPFirewallRuleGroupService.md) — WAF分组服务
- [HTTPFirewallRuleSetService](./HTTPFirewallRuleSetService.md) — WAF规则集服务
- [HTTPHeaderPolicyService](./HTTPHeaderPolicyService.md) — HTTP Header策略服务
- [HTTPHeaderService](./HTTPHeaderService.md) — HTTP Header管理服务
- [HTTPLocationService](./HTTPLocationService.md) — 路由规则服务
- [HTTPPageService](./HTTPPageService.md) — 自定义页面服务
- [HTTPRewriteRuleService](./HTTPRewriteRuleService.md) — 重写规则服务
- [HTTPWebService](./HTTPWebService.md) — HTTP Web相关管理服务
- [HTTPWebsocketService](./HTTPWebsocketService.md) — HTTP Websocket管理服务
- [IPItemService](./IPItemService.md) — IP条目管理
- [IPLibraryArtifactService](./IPLibraryArtifactService.md) — IP库制品
- [IPLibraryFileService](./IPLibraryFileService.md) — IP库文件管理
- [IPLibraryService](./IPLibraryService.md) — IP库
- [IPListService](./IPListService.md) — IP列表
- [LatestItemService](./LatestItemService.md) — 最近使用的条目服务
- [LogService](./LogService.md) — 审计日志服务
- [LoginService](./LoginService.md) — 认证相关服务
- [LoginSessionService](./LoginSessionService.md) — 登录SESSION服务
- [LoginTicketService](./LoginTicketService.md) — 登录票据相关服务
- [MessageMediaInstanceService](./MessageMediaInstanceService.md) — 消息媒介实例
- [MessageMediaService](./MessageMediaService.md) — 消息媒介管理
- [MessageReceiverService](./MessageReceiverService.md) — 消息对象接收者设置
- [MessageRecipientGroupService](./MessageRecipientGroupService.md) — 消息接收人分组
- [MessageRecipientService](./MessageRecipientService.md) — 消息接收人
- [MessageService](./MessageService.md) — 消息相关服务
- [MessageTaskLogService](./MessageTaskLogService.md) — 消息发送任务日志
- [MessageTaskService](./MessageTaskService.md) — 消息发送任务服务
- [MetricChartService](./MetricChartService.md) — 指标图表相关服务
- [MetricItemService](./MetricItemService.md) — 指标相关服务
- [MetricStatService](./MetricStatService.md) — 指标统计数据相关服务
- [NSAccessLogService](./NSAccessLogService.md) — 访问日志相关服务
- [NSClusterService](./NSClusterService.md) — 域名服务集群相关服务
- [NSDomainGroupService](./NSDomainGroupService.md) — 域名分组服务
- [NSDomainService](./NSDomainService.md) — 域名相关服务
- [NSKeyService](./NSKeyService.md) — NS密钥相关服务
- [NSNodeService](./NSNodeService.md) — 域名服务器节点服务
- [NSPlanService](./NSPlanService.md) — DNS套餐服务
- [NSQuestionOptionService](./NSQuestionOptionService.md) — DNS查询选项
- [NSRecordHourlyStatService](./NSRecordHourlyStatService.md) — NS记录小时统计
- [NSRecordService](./NSRecordService.md) — 域名记录相关服务
- [NSRouteCategoryService](./NSRouteCategoryService.md) — 线路分类服务
- [NSRouteService](./NSRouteService.md) — 线路相关服务
- [NSService](./NSService.md) — 域名服务
- [NSUserPlanService](./NSUserPlanService.md) — 用户DNS套餐服务
- [NodeActionService](./NodeActionService.md) — 节点动作服务
- [NodeClusterFirewallActionService](./NodeClusterFirewallActionService.md) — 防火墙动作服务
- [NodeClusterMetricItemService](./NodeClusterMetricItemService.md) — 集群指标
- [NodeClusterService](./NodeClusterService.md) — 边缘节点集群管理服务
- [NodeGrantService](./NodeGrantService.md) — 节点认证信息管理服务
- [NodeGroupService](./NodeGroupService.md) — 节点分组服务
- [NodeIPAddressLogService](./NodeIPAddressLogService.md) — IP地址相关日志
- [NodeIPAddressService](./NodeIPAddressService.md) — 节点IP地址服务
- [NodeIPAddressThresholdService](./NodeIPAddressThresholdService.md) — IP阈值相关服务
- [NodeLogService](./NodeLogService.md) — 节点日志相关服务
- [NodeLoginService](./NodeLoginService.md) — 节点登录相关
- [NodePriceItemService](./NodePriceItemService.md) — 节点区域定价相关服务
- [NodeRegionService](./NodeRegionService.md) — 节点区域相关服务
- [NodeService](./NodeService.md) — 边缘节点管理服务
- [NodeTaskService](./NodeTaskService.md) — 节点同步任务相关服务
- [NodeThresholdService](./NodeThresholdService.md) — 节点阈值服务
- [NodeValueService](./NodeValueService.md) — 节点指标数据服务
- [OrderMethodService](./OrderMethodService.md) — 订单支付方式相关服务
- [OriginService](./OriginService.md) — 源站管理服务
- [PagesService](./PagesService.md) — Pages相关服务
- [PagesStorageService](./PagesStorageService.md) — PagesStorage相关服务
- [PlanService](./PlanService.md) — 套餐相关服务
- [PostCategoryService](./PostCategoryService.md) — 文章分类管理服务
- [PostService](./PostService.md) — 文章管理服务
- [PriceService](./PriceService.md) — 价格相关服务
- [RegionCityService](./RegionCityService.md) — 城市相关服务
- [RegionCountryService](./RegionCountryService.md) — 国家/地区相关服务
- [RegionProviderService](./RegionProviderService.md) — ISP相关服务
- [RegionProvinceService](./RegionProvinceService.md) — 省份相关服务
- [RegionTownService](./RegionTownService.md) — 区县相关服务
- [ReportNodeGroupService](./ReportNodeGroupService.md) — 监控节点分组
- [ReportNodeService](./ReportNodeService.md) — 监控终端服务
- [ReportResultService](./ReportResultService.md) — 区域监控报告结果
- [ReverseProxyService](./ReverseProxyService.md) — 反向代理管理服务
- [SMSSenderService](./SMSSenderService.md) — 短信发送服务
- [SSLCertService](./SSLCertService.md) — SSL证书管理服务
- [SSLPolicyService](./SSLPolicyService.md) — SSL/TLS策略管理服务
- [ScriptService](./ScriptService.md) — 脚本相关服务
- [ServerBandwidthStatService](./ServerBandwidthStatService.md) — 服务带宽统计服务
- [ServerBillService](./ServerBillService.md) — 服务账单相关服务
- [ServerClientBrowserMonthlyStatService](./ServerClientBrowserMonthlyStatService.md) — 浏览器统计
- [ServerClientSystemMonthlyStatService](./ServerClientSystemMonthlyStatService.md) — 操作系统统计
- [ServerDailyStatService](./ServerDailyStatService.md) — 服务统计相关服务
- [ServerDomainHourlyStatService](./ServerDomainHourlyStatService.md) — 服务域名按小时统计服务
- [ServerGroupService](./ServerGroupService.md) — 服务分组服务
- [ServerHTTPFirewallDailyStatService](./ServerHTTPFirewallDailyStatService.md) — WAF统计
- [ServerRegionCityMonthlyStatService](./ServerRegionCityMonthlyStatService.md) — 城市月份统计
- [ServerRegionCountryMonthlyStatService](./ServerRegionCountryMonthlyStatService.md) — 地区月份统计
- [ServerRegionProviderMonthlyStatService](./ServerRegionProviderMonthlyStatService.md) — 运营商月份统计
- [ServerRegionProvinceMonthlyStatService](./ServerRegionProvinceMonthlyStatService.md) — 省份月份统计
- [ServerService](./ServerService.md) — 网站服务相关服务
- [ServerStatBoardChartService](./ServerStatBoardChartService.md) — 统计看板条目
- [ServerStatBoardService](./ServerStatBoardService.md) — 统计看板
- [SysLockerService](./SysLockerService.md) — 互斥锁管理
- [SysSettingService](./SysSettingService.md) — 系统设置管理服务
- [TrafficDailyStatService](./TrafficDailyStatService.md) — 按日统计服务
- [TrafficPackagePeriodService](./TrafficPackagePeriodService.md) — 流量包有效期服务
- [TrafficPackagePriceService](./TrafficPackagePriceService.md) — 流量包价格服务
- [TrafficPackageService](./TrafficPackageService.md) — 流量包服务
- [UserADInstanceService](./UserADInstanceService.md) — 用户高防实例服务
- [UserAccessKeyService](./UserAccessKeyService.md) — 用户AccessKey相关服务
- [UserAccountDailyStatService](./UserAccountDailyStatService.md) — 用户账户统计服务
- [UserAccountLogService](./UserAccountLogService.md) — 用户账户日志服务
- [UserAccountService](./UserAccountService.md) — 用户账户服务
- [UserBillService](./UserBillService.md) — 账单相关服务
- [UserIdentityService](./UserIdentityService.md) — 用户实名认证服务
- [UserNodeService](./UserNodeService.md) — 用户节点管理服务
- [UserOrderService](./UserOrderService.md) — 用户订单相关服务
- [UserPlanService](./UserPlanService.md) — 用户购买的套餐管理服务
- [UserScriptService](./UserScriptService.md) — 用户脚本服务
- [UserService](./UserService.md) — 用户相关服务
- [UserTicketCategoryService](./UserTicketCategoryService.md) — 工单分类服务
- [UserTicketLogService](./UserTicketLogService.md) — 工单日志服务
- [UserTicketService](./UserTicketService.md) — 工单服务
- [UserTrafficBillService](./UserTrafficBillService.md) — 用户流量带宽子账单服务
- [UserTrafficPackageService](./UserTrafficPackageService.md) — 用户流量包服务