kariko/pyGoEdge-UserPanel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d17c7efb3cadb2f483fed55a123ae1594026ee0a
pyGoEdge-UserPanel/reference/goedge 文档/README.md

374 lines
20 KiB
Markdown
Raw Normal View History

Initial commit
2025-11-18 03:36:49 +08:00
# 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) — 用户流量包服务
Reference in New Issue Copy Permalink