Go SDK：分析、DNS 与域名

c.Apps.Network 仅适用于 Web 应用。每个方法都以 ctx 和应用 ID 作为前两个参数。下面的每个代码片段都可以在这个程序中单独运行：每次将一个片段粘贴到 main 中，然后运行 goimports（参见运行示例）。

package main

import (
	"context"
	"os"
	"time"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456"
	end   = time.Now()
	start = end.Add(-24 * time.Hour) // the last 24 hours
)

func main() {
	// Paste one snippet here, then run goimports.
}

时间窗口

Analytics、Errors、Logs 和 Performance 接受 start 和 end，每个都是 time.Time（以 UTC 的 RFC 3339 格式发送）。上面的程序将它们设为最近 24 小时。一个窗口最长 7 天，且 start 会被限制为不早于应用的创建日期。无效的窗口会返回 400 INVALID_TIME_RANGE。结果以 5 分钟为单位进行缓存。这四个方法的缓存未命中共享每个账户每 60 秒 20 次请求的限制：超出后返回 429 RATE_LIMITED。

分析

Network.Analytics(ctx, appID, start, end, filters) 以 *NetworkAnalytics 返回流量总计和细分数据。对于没有流量的窗口，它返回 nil（错误也为 nil）。不需要过滤器时，传入空的 squarecloud.AnalyticsFilters{}。

analytics, err := c.Apps.Network.Analytics(ctx, appID, start, end, squarecloud.AnalyticsFilters{})
if err != nil {
	log.Fatal(err)
}

if analytics != nil {
	fmt.Println(analytics.Visits)    // []AnalyticsTimeBucket: Date, Visits, Requests, Bytes
	fmt.Println(analytics.Countries) // []AnalyticsBucket: Type ("BR"), Visits, Requests, Bytes
}

细分维度包括 Countries、Devices、OS、Browsers、Protocols、Methods、Paths、Referers、Providers、IPs、StatusCodes、Bots 和 ContentTypes（JSON 中为 countries、……、status_codes、bots、content_types）。每个分组都有 Type、Visits、Requests 和 Bytes（int64）。

过滤器

过滤器会缩小每个细分维度的范围。每个过滤器接受其对应细分维度中确切的 Type 值。空字段不会被发送：

brazil, err := c.Apps.Network.Analytics(ctx, appID, start, end, squarecloud.AnalyticsFilters{
	Country:  "BR",
	Path:     "/api",
	Provider: "GOOGLE (15169)",
})
if err != nil {
	log.Fatal(err)
}

if brazil != nil {
	fmt.Println(brazil.Paths)
}

过滤器	示例
`Country`	`"BR"`（两个字母的代码）
`IP`	`"203.0.113.7"`
`Path`	`"/api"`（路径前缀）
`Status`	`"404"`
`OS`, `Browser`, `Protocol`, `Bot`	细分维度的 `Type`
`Referer`	`"Direct"` 表示没有来源
`Provider`	`"NAME (ASN)"`，例如 `"GOOGLE (15169)"`
`ContentType`	细分维度的 `Type`

无效的过滤器会返回 400 INVALID_FILTER。

错误

Network.Errors(ctx, appID, start, end, include4xx) 返回该窗口内的 5xx 响应，当 include4xx 为 true 时还包括 4xx。对于空窗口返回 nil。

errs, err := c.Apps.Network.Errors(ctx, appID, start, end, true)
if err != nil {
	log.Fatal(err)
}

if errs != nil {
	fmt.Println(errs.Summary.Total, errs.Summary.ByClass) // ByClass: map[string]int64 with "4xx", "5xx"
	fmt.Println(errs.TopPaths)
}

请求日志

Network.Logs(ctx, appID, start, end) 返回单个请求，包含客户端、请求和响应的详细信息。适用于 Pro 和 Enterprise 套餐（否则返回 403 UPGRADE_REQUIRED）。

logs, err := c.Apps.Network.Logs(ctx, appID, start, end)
if err != nil {
	log.Fatal(err)
}
for _, l := range logs {
	fmt.Println(l.Timestamp, l.Request.Method, l.Request.Path, l.Response.Status)
}

API 可能以 null 发送的字段是指针（Client.IP、Client.Country、Request.Query、Request.Referer、Response.Cache……）。

性能

Network.Performance(ctx, appID, start, end) 返回边缘和源站的延迟百分位数（P50、P95、P99，单位为毫秒），按国家、按位置以及最慢的路径分别统计。对于空窗口返回 nil。适用于 Pro 和 Enterprise 套餐。每个百分位数都是 *float64，没有可测量的请求时为 nil：

performance, err := c.Apps.Network.Performance(ctx, appID, start, end)
if err != nil {
	log.Fatal(err)
}

if performance != nil {
	if p95 := performance.Summary.Edge.P95; p95 != nil {
		fmt.Println("edge p95", *p95)
	}
	if p95 := performance.Summary.Origin.P95; p95 != nil {
		fmt.Println("origin p95", *p95)
	}
}

DNS

Network.DNS(ctx, appID) 返回你的自定义域名所需的 DNS 记录及其状态。没有自定义域名时返回 400 NO_CUSTOM_DOMAIN。

records, err := c.Apps.Network.DNS(ctx, appID)
if err != nil {
	log.Fatal(err)
}
for _, r := range records {
	fmt.Println(r.Type, r.Name, r.Value, r.Status) // Type: "txt" | "cname"
}

自定义域名

Network.SetDomain(ctx, appID, domain) 绑定一个自定义域名（Standard 及以上套餐）。传入 "@" 即可移除。

if err := c.Apps.Network.SetDomain(ctx, appID, "www.example.com"); err != nil {
	log.Fatal(err)
}

// Remove it
if err := c.Apps.Network.SetDomain(ctx, appID, "@"); err != nil {
	log.Fatal(err)
}

状态	代码	触发条件
400	`INVALID_DOMAIN`	不是有效的域名
400	`RESERVED_DOMAIN`	属于 Square Cloud 的域名
403	`UPGRADE_REQUIRED`	该套餐不支持自定义域名
403	`LOAD_BALANCER_LIMIT_REACHED`	已达到套餐在此域名上的应用数量限制
409	`DOMAIN_ALREADY_EXISTS`	该域名属于另一个账户的应用
502	`DNS_FAILED`	边缘服务提供商拒绝了该域名

清除缓存

Network.PurgeCache(ctx, appID) 清除应用的边缘缓存。每 60 秒最多清除一次（429 KEEP_CALM）。

if err := c.Apps.Network.PurgeCache(ctx, appID); err != nil {
	log.Fatal(err)
}

分析方法的错误

状态	代码	触发条件
400	`INVALID_TIME_RANGE`	`start`/`end` 缺失、格式错误或顺序颠倒
400	`INVALID_FILTER`	某个过滤器不符合其格式（`Analytics`）
403	`UPGRADE_REQUIRED`	在 Pro 和 Enterprise 以外的套餐上使用 `Logs` 和 `Performance`
429	`RATE_LIMITED`	已达到缓存未命中的共享限制
500	`UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE`	边缘服务提供商出错
503	`ANALYTICS_BUSY`	边缘分析繁忙：会自动重试

后续步骤

实时

实时流式获取日志和状态。

网络 API 参考

这些方法背后的 REST 端点。

用 CLI 查看边缘分析

在终端中完成同样的操作。

CLI

VS Code

SDKs

Go SDK：分析、DNS 与域名

时间窗口

分析

过滤器

错误

请求日志

性能

DNS

自定义域名

清除缓存

分析方法的错误

后续步骤

实时

网络 API 参考

用 CLI 查看边缘分析

​时间窗口

​分析

​过滤器

​错误

​请求日志

​性能

​DNS

​自定义域名

​清除缓存

​分析方法的错误

​后续步骤

实时

网络 API 参考

用 CLI 查看边缘分析

时间窗口

分析

过滤器

错误

请求日志

性能

DNS

自定义域名

清除缓存

分析方法的错误

后续步骤