> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 网络与边缘

> 为网站应用管理自定义域名、DNS、边缘分析、错误追踪、请求日志、延迟百分位和缓存失效。

<Note>
  本页的 endpoint 仅适用于**网站应用** —— 即带有 web 域名的应用。对非网站应用调用它们会失败。
</Note>

```go theme={null}
client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
defer client.Close()

api := rest.New(client)
```

## 自定义域名

`api.SetApplicationCustomDomain(appID, domain)` 设置绑定到网站的自定义域名。

```go theme={null}
err := api.SetApplicationCustomDomain("abc123def456abc123def456", "yoursite.com")
if err != nil {
	panic(err)
}
```

## DNS 记录

绑定自定义域名后，你需要在域名注册商处配置 DNS。`api.GetApplicationDNS(appID)` 以 `[]squarecloud.DNSRecord` 返回需要创建的记录。

```go theme={null}
records, err := api.GetApplicationDNS("abc123def456abc123def456")
if err != nil {
	panic(err)
}

for _, record := range records {
	fmt.Printf("%s %s → %s (%s)\n", record.Type, record.Name, record.Value, record.Status)
}
```

| 字段       | 类型       | 说明                                                                               |
| -------- | -------- | -------------------------------------------------------------------------------- |
| `Type`   | `string` | `"txt"` 或 `"cname"` —— TXT 记录覆盖所有权和 SSL 验证；CNAME 承载流量并始终指向 `cname.squareweb.app` |
| `Name`   | `string` | 要创建的记录名称                                                                         |
| `Value`  | `string` | 记录值                                                                              |
| `Status` | `string` | 验证状态：`"pending"`、`"pending_validation"` 或 `"active"`                             |

## 分析

`api.GetApplicationAnalytics(appID, start, end)` 以 `squarecloud.NetworkAnalytics` 返回给定时间窗口内聚合的边缘分析数据。时间窗口是必需的，最大保留期为 **7 天**。

```go theme={null}
end := time.Now()
start := end.Add(-24 * time.Hour)

analytics, err := api.GetApplicationAnalytics("abc123def456abc123def456", start, end)
if err != nil {
	panic(err)
}

fmt.Println(len(analytics.Visits), "time buckets") // 15-minute series
fmt.Println(analytics.Countries)
fmt.Println(analytics.Paths)
```

响应包含 15 分钟粒度的时间序列（`Visits`、`Countries`、`Devices`、`OS`、`Browsers`、`Protocols`、`Methods`、`Paths`、`Referers`、`Providers`）和整个窗口的聚合桶（`IPs`、`StatusCodes`、`Bots`、`ContentTypes`）。

<Note>
  对于完全早于应用创建时间的窗口，API 返回一个空对象 —— 响应中的每个切片都是 `nil`。索引前请先检查长度。
</Note>

### 下钻筛选

除时间窗口外，该 endpoint 还接受作为查询参数的可选筛选条件 —— 使用 `rest.WithQueryParam` 传入。每个筛选条件会同时收窄响应中的每一项细分数据：

| 筛选条件           | 备注                               |
| -------------- | -------------------------------- |
| `country`      | 2 位国家代码，例如 `"BR"`                |
| `ip`           | 精确 IP 匹配                         |
| `path`         | 前缀匹配，例如 `"/api"`                 |
| `status`       | HTTP 状态码，例如 `"404"`              |
| `os`           | 操作系统                             |
| `browser`      | 浏览器名称                            |
| `protocol`     | 请求协议                             |
| `referer`      | 无 referer 的请求使用 `"Direct"`       |
| `provider`     | 网络提供商，例如 `"GOOGLE (15169)"`（ASN） |
| `content_type` | 未分类的内容类型使用 `"Unknown"`           |
| `bot`          | 正常（非机器人）流量使用 `"Unverified"`      |

```go theme={null}
analytics, err := api.GetApplicationAnalytics(
	"abc123def456abc123def456",
	start, end,
	rest.WithQueryParam("country", "BR"),
	rest.WithQueryParam("status", "404"),
	rest.WithQueryParam("bot", "Unverified"),
)
```

## 错误追踪

`api.GetApplicationNetworkErrors(appID, start, end)` 返回边缘错误的细分数据。默认只包含 5xx 错误 —— 添加 `include_4xx=true` 以包含 4xx。

```go theme={null}
errs, err := api.GetApplicationNetworkErrors(
	"abc123def456abc123def456",
	start, end,
	rest.WithQueryParam("include_4xx", "true"),
)
if err != nil {
	panic(err)
}
```

## 逐请求日志

`api.GetApplicationNetworkLogs(appID, start, end)` 返回边缘的逐请求日志。

```go theme={null}
logs, err := api.GetApplicationNetworkLogs("abc123def456abc123def456", start, end)
if err != nil {
	panic(err)
}
```

<Note>
  逐请求日志需要 [Pro 套餐](https://squarecloud.app/plans)或更高级别。
</Note>

## 延迟百分位

`api.GetApplicationNetworkPerformance(appID, start, end)` 返回边缘层和源站层的 p50 / p95 / p99 延迟。

```go theme={null}
perf, err := api.GetApplicationNetworkPerformance("abc123def456abc123def456", start, end)
if err != nil {
	panic(err)
}
```

<Note>
  性能指标需要 [Pro 套餐](https://squarecloud.app/plans)或更高级别。
</Note>

## 清除边缘缓存

`api.PurgeApplicationCache(appID)` 使应用域名的整个边缘缓存失效。

```go theme={null}
err := api.PurgeApplicationCache("abc123def456abc123def456")
if err != nil {
	panic(err)
}
```

## 账户级域名与负载均衡器

以下两个方法作用于账户中的所有应用，而非单个网站。

### 列出所有域名

`api.GetApplicationDomains()` 以 `[]squarecloud.AppDomain` 返回账户所有应用中配置的每一个域名。自定义域名排在前面；没有 web 域名的应用会被省略。

```go theme={null}
domains, err := api.GetApplicationDomains()
if err != nil {
	panic(err)
}

for _, domain := range domains {
	fmt.Println(domain.AppID, domain.Hostname, domain.Type) // "subdomain" | "custom"
}
```

### 负载均衡器

`api.GetLoadBalancers()` 将共享同一自定义域名的应用分组，返回一个 `squarecloud.LoadBalancers`。

```go theme={null}
lb, err := api.GetLoadBalancers()
if err != nil {
	panic(err)
}

fmt.Println("plan limit:", lb.Limit)
for _, balancer := range lb.Balancers {
	fmt.Println(balancer.Hostname, len(balancer.Apps), "apps")
}
```

包含 2 个或更多应用的分组就是一个活跃的负载均衡器：流量在边缘进行均衡，当其中一个应用离线时自动故障转移。`Limit` 是账户套餐允许共享同一域名的最大应用数量：2（Standard）、5（Pro）、10（Enterprise）。