# 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) — 用户流量包服务