Go-SDK: Analytics, DNS und Domains

c.Apps.Network funktioniert nur mit Web-Apps. Jede Methode nimmt zuerst ctx und die App-ID. Jedes Snippet unten läuft für sich allein in diesem Programm: Füge jeweils eines in main ein und führe goimports aus (siehe Beispiele ausführen).

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.
}

Zeitfenster

Analytics, Errors, Logs und Performance nehmen ein start und ein end, jeweils ein time.Time (gesendet als RFC 3339 in UTC). Das Programm oben setzt sie auf die letzten 24 Stunden. Ein Fenster umfasst höchstens 7 Tage, und start wird auf das Erstellungsdatum der App begrenzt. Ein ungültiges Fenster ergibt 400 INVALID_TIME_RANGE. Ergebnisse werden in 5-Minuten-Intervallen gecacht. Cache-Misses dieser vier Methoden teilen sich ein Limit von 20 Anfragen pro 60 Sekunden pro Konto: Wird es überschritten, ergibt das 429 RATE_LIMITED.

Analytics

Network.Analytics(ctx, appID, start, end, filters) gibt Verkehrssummen und Aufschlüsselungen als *NetworkAnalytics zurück. Für ein Fenster ohne Verkehr gibt die Methode nil zurück (und einen nil-Fehler). Übergib ein leeres squarecloud.AnalyticsFilters{}, wenn du keine Filter brauchst.

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
}

Die Aufschlüsselungen sind Countries, Devices, OS, Browsers, Protocols, Methods, Paths, Referers, Providers, IPs, StatusCodes, Bots und ContentTypes (JSON countries, …, status_codes, bots, content_types). Jeder Eintrag hat Type, Visits, Requests und Bytes (int64).

Filter

Filter schränken jede Aufschlüsselung ein. Jeder nimmt den exakten Type-Wert seiner Aufschlüsselung. Ein leeres Feld wird nicht gesendet:

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)
}

Filter	Beispiel
`Country`	`"BR"` (Code aus 2 Buchstaben)
`IP`	`"203.0.113.7"`
`Path`	`"/api"` (Pfadpräfix)
`Status`	`"404"`
`OS`, `Browser`, `Protocol`, `Bot`	Der `Type` der Aufschlüsselung
`Referer`	`"Direct"` bedeutet kein Referer
`Provider`	`"NAME (ASN)"`, z. B. `"GOOGLE (15169)"`
`ContentType`	Der `Type` der Aufschlüsselung

Ein ungültiger Filter ergibt 400 INVALID_FILTER.

Fehler

Network.Errors(ctx, appID, start, end, include4xx) gibt die 5xx-Antworten des Fensters zurück, zusätzlich die 4xx, wenn include4xx true ist. Für ein leeres Fenster gibt die Methode nil zurück.

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)
}

Request-Logs

Network.Logs(ctx, appID, start, end) gibt einzelne Anfragen mit Details zu Client, Anfrage und Antwort zurück. Verfügbar in den Plänen Pro und Enterprise (sonst 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)
}

Felder, die die API als null senden kann, sind Zeiger (Client.IP, Client.Country, Request.Query, Request.Referer, Response.Cache, …).

Performance

Network.Performance(ctx, appID, start, end) gibt Latenzperzentile (P50, P95, P99, in ms) an der Edge und am Ursprung zurück, nach Land, nach Standort und für die langsamsten Pfade. Für ein leeres Fenster gibt die Methode nil zurück. Verfügbar in den Plänen Pro und Enterprise. Jedes Perzentil ist ein *float64, nil, wenn es keine Anfragen zu messen gab:

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) gibt die DNS-Einträge zurück, die deine eigene Domain benötigt, zusammen mit ihrem Status. Ohne eigene Domain ergibt das 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"
}

Eigene Domain

Network.SetDomain(ctx, appID, domain) verbindet eine eigene Domain (ab dem Standard-Plan). Übergib "@", um sie zu entfernen.

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)
}

Status	Code	Wann
400	`INVALID_DOMAIN`	Kein gültiger Domainname
400	`RESERVED_DOMAIN`	Eine Domain von Square Cloud
403	`UPGRADE_REQUIRED`	Der Plan hat keine eigenen Domains
403	`LOAD_BALANCER_LIMIT_REACHED`	Das Limit des Plans für Apps auf dieser Domain wurde erreicht
409	`DOMAIN_ALREADY_EXISTS`	Die Domain gehört zu einer App eines anderen Kontos
502	`DNS_FAILED`	Der Edge-Anbieter hat die Domain abgelehnt

Cache leeren

Network.PurgeCache(ctx, appID) leert den Edge-Cache der App. Das ist auf einen Vorgang alle 60 Sekunden begrenzt (429 KEEP_CALM).

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

Fehler der Analytics-Methoden

Status	Code	Wann
400	`INVALID_TIME_RANGE`	`start`/`end` fehlt, ist fehlerhaft oder vertauscht
400	`INVALID_FILTER`	Ein Filter entspricht nicht seinem Format (`Analytics`)
403	`UPGRADE_REQUIRED`	`Logs` und `Performance` außerhalb von Pro und Enterprise
429	`RATE_LIMITED`	Gemeinsames Limit für Cache-Misses erreicht
500	`UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE`	Der Edge-Anbieter ist fehlgeschlagen
503	`ANALYTICS_BUSY`	Die Edge-Analytics sind ausgelastet: wird automatisch wiederholt

Nächste Schritte

Realtime

Live-Logs und -Status streamen.

API-Referenz für das Netzwerk

Die REST-Endpunkte hinter diesen Methoden.

Edge-Analytics über die CLI

Dieselben Aktionen im Terminal.

CLI

VS Code

SDKs

Go-SDK: Analytics, DNS und Domains

Zeitfenster

Analytics

Filter

Fehler

Request-Logs

Performance

DNS

Eigene Domain

Cache leeren

Fehler der Analytics-Methoden

Nächste Schritte

Realtime

API-Referenz für das Netzwerk

Edge-Analytics über die CLI

​Zeitfenster

​Analytics

​Filter

​Fehler

​Request-Logs

​Performance

​DNS

​Eigene Domain

​Cache leeren

​Fehler der Analytics-Methoden

​Nächste Schritte

Realtime

API-Referenz für das Netzwerk

Edge-Analytics über die CLI

Zeitfenster

Analytics

Filter

Fehler

Request-Logs

Performance

DNS

Eigene Domain

Cache leeren

Fehler der Analytics-Methoden

Nächste Schritte