SDK Go : analytics, DNS et domaines

c.Apps.Network fonctionne uniquement sur les applications web. Chaque méthode prend d’abord ctx et l’identifiant de l’application. Chaque extrait ci-dessous s’exécute seul dans ce programme : collez-en un à la fois dans main et lancez goimports (voir Exécuter les exemples).

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

Fenêtres temporelles

Analytics, Errors, Logs et Performance prennent un start et un end, chacun étant un time.Time (envoyé au format RFC 3339 en UTC). Le programme ci-dessus les règle sur les dernières 24 heures. Une fenêtre dure au maximum 7 jours, et start est ramené à la date de création de l’application. Une fenêtre invalide donne 400 INVALID_TIME_RANGE. Les résultats sont mis en cache par tranches de 5 minutes. Les défauts de cache de ces quatre méthodes partagent une limite de 20 requêtes par 60 secondes et par compte : la dépasser donne 429 RATE_LIMITED.

Analytics

Network.Analytics(ctx, appID, start, end, filters) renvoie les totaux et les répartitions du trafic sous forme d’un *NetworkAnalytics. Elle renvoie nil (et une erreur nil) pour une fenêtre sans trafic. Passez un squarecloud.AnalyticsFilters{} vide pour n’appliquer aucun filtre.

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
}

Les répartitions sont Countries, Devices, OS, Browsers, Protocols, Methods, Paths, Referers, Providers, IPs, StatusCodes, Bots et ContentTypes (en JSON countries, …, status_codes, bots, content_types). Chaque groupe a Type, Visits, Requests et Bytes (int64).

Filtres

Les filtres restreignent chaque répartition. Chacun prend la valeur Type exacte de sa répartition. Un champ vide n’est pas envoyé :

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

Filtre	Exemple
`Country`	`"BR"` (code à 2 lettres)
`IP`	`"203.0.113.7"`
`Path`	`"/api"` (préfixe de chemin)
`Status`	`"404"`
`OS`, `Browser`, `Protocol`, `Bot`	Le `Type` de la répartition
`Referer`	`"Direct"` signifie aucun referer
`Provider`	`"NAME (ASN)"`, par ex. `"GOOGLE (15169)"`
`ContentType`	Le `Type` de la répartition

Un filtre invalide donne 400 INVALID_FILTER.

Erreurs

Network.Errors(ctx, appID, start, end, include4xx) renvoie les réponses 5xx de la fenêtre, plus les 4xx lorsque include4xx vaut true. Elle renvoie nil pour une fenêtre vide.

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

Logs de requêtes

Network.Logs(ctx, appID, start, end) renvoie les requêtes individuelles avec les détails du client, de la requête et de la réponse. Disponible sur les plans Pro et Enterprise (403 UPGRADE_REQUIRED sinon).

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

Les champs que l’API peut envoyer à null sont des pointeurs (Client.IP, Client.Country, Request.Query, Request.Referer, Response.Cache, …).

Performances

Network.Performance(ctx, appID, start, end) renvoie les percentiles de latence (P50, P95, P99, en ms) en périphérie et à l’origine, par pays, par emplacement et pour les chemins les plus lents. Elle renvoie nil pour une fenêtre vide. Disponible sur les plans Pro et Enterprise. Chaque percentile est un *float64, nil lorsqu’il n’y avait aucune requête à mesurer :

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) renvoie les enregistrements DNS dont votre domaine personnalisé a besoin, avec leur statut. Sans domaine personnalisé, elle donne 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"
}

Domaine personnalisé

Network.SetDomain(ctx, appID, domain) associe un domaine personnalisé (plan Standard et supérieurs). Passez "@" pour le supprimer.

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

Statut	Code	Quand
400	`INVALID_DOMAIN`	Nom de domaine invalide
400	`RESERVED_DOMAIN`	Un domaine de Square Cloud
403	`UPGRADE_REQUIRED`	Le plan n’inclut pas de domaines personnalisés
403	`LOAD_BALANCER_LIMIT_REACHED`	La limite d’applications du plan sur ce domaine a été atteinte
409	`DOMAIN_ALREADY_EXISTS`	Le domaine appartient à une application d’un autre compte
502	`DNS_FAILED`	Le fournisseur edge a refusé le domaine

Purger le cache

Network.PurgeCache(ctx, appID) vide le cache edge de l’application. Elle est limitée à une purge toutes les 60 secondes (429 KEEP_CALM).

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

Erreurs des méthodes d’analytics

Statut	Code	Quand
400	`INVALID_TIME_RANGE`	`start`/`end` manquant, mal formé ou inversé
400	`INVALID_FILTER`	Un filtre ne respecte pas son format (`Analytics`)
403	`UPGRADE_REQUIRED`	`Logs` et `Performance` en dehors de Pro et Enterprise
429	`RATE_LIMITED`	Limite partagée de défauts de cache atteinte
500	`UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE`	Le fournisseur edge a échoué
503	`ANALYTICS_BUSY`	Les analytics edge sont occupées : nouvelle tentative automatique

Prochaines étapes

Temps réel

Diffusez les logs et le statut en direct.

Référence de l'API réseau

Les endpoints REST derrière ces méthodes.

Analytics edge depuis la CLI

Les mêmes actions depuis le terminal.

CLI

VS Code

SDKs

SDK Go : analytics, DNS et domaines

Fenêtres temporelles

Analytics

Filtres

Erreurs

Logs de requêtes

Performances

DNS

Domaine personnalisé

Purger le cache

Erreurs des méthodes d’analytics

Prochaines étapes

Temps réel

Référence de l'API réseau

Analytics edge depuis la CLI

​Fenêtres temporelles

​Analytics

​Filtres

​Erreurs

​Logs de requêtes

​Performances

​DNS

​Domaine personnalisé

​Purger le cache

​Erreurs des méthodes d’analytics

​Prochaines étapes

Temps réel

Référence de l'API réseau

Analytics edge depuis la CLI

Fenêtres temporelles

Analytics

Filtres

Erreurs

Logs de requêtes

Performances

DNS

Domaine personnalisé

Purger le cache

Erreurs des méthodes d’analytics

Prochaines étapes