JavaScript-SDK: Analytics, DNS und Domains

api.apps.network funktioniert nur mit Web-Apps. Jede Methode nimmt zuerst die App-ID. Die Beispiele verwenden den Client api aus Client erstellen. appId ist die ID einer deiner Apps: api.account.me() listet sie auf.

Zeitfenster

analytics, errors, logs und performance nehmen ein start und ein end, jeweils ein ISO-8601-String oder ein Date. 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.

const end = new Date();
const start = new Date(end.getTime() - 24 * 60 * 60 * 1000); // last 24 h

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(appId, start, end, filters?) gibt Verkehrssummen und Aufschlüsselungen zurück. Für ein Fenster ohne Verkehr gibt die Methode null zurück.

const analytics = await api.apps.network.analytics(appId, start, end);

if (analytics) {
    console.log(analytics.visits);    // [{ visits, requests, bytes, date }]
    console.log(analytics.countries); // [{ type: "BR", visits, requests, bytes }]
}

Die Aufschlüsselungen sind countries, devices, os, browsers, protocols, methods, paths, referers, providers, ips, status_codes, bots und content_types. Jeder Eintrag hat type, visits, requests und bytes.

Filter

Filter schränken jede Aufschlüsselung ein. Jeder nimmt den exakten type-Wert seiner Aufschlüsselung:

const brazil = await api.apps.network.analytics(appId, start, end, {
    country: "BR",
    path: "/api",
    provider: "GOOGLE (15169)",
});

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)"`
`content_type`	Der `type` der Aufschlüsselung

Ein ungültiger Filter ergibt 400 INVALID_FILTER.

Fehler

network.errors(appId, start, end, { include_4xx }) gibt die 5xx-Antworten des Fensters zurück, mit include_4xx: true zusätzlich die 4xx. Für ein leeres Fenster gibt die Methode null zurück.

const errors = await api.apps.network.errors(appId, start, end, { include_4xx: true });

if (errors) {
    console.log(errors.summary.total, errors.summary.by_class);
    console.log(errors.top_paths);
}

Request-Logs

network.logs(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).

for (const log of await api.apps.network.logs(appId, start, end)) {
    console.log(log.timestamp, log.request.method, log.request.path, log.response.status);
}

Performance

network.performance(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 null zurück. Verfügbar in den Plänen Pro und Enterprise.

const performance = await api.apps.network.performance(appId, start, end);

if (performance) {
    console.log(performance.summary.edge.p95, performance.summary.origin.p95);
}

DNS

network.dns(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.

for (const { type, name, value, status } of await api.apps.network.dns(appId)) {
    console.log(type, name, value, status); // type: "txt" | "cname"
}

Eigene Domain

network.setDomain(appId, domain) verbindet eine eigene Domain (ab dem Standard-Plan). Übergib "@", um sie zu entfernen.

await api.apps.network.setDomain(appId, "www.example.com");

// Remove it
await api.apps.network.setDomain(appId, "@");

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(appId) leert den Edge-Cache der App. Das ist auf einen Vorgang alle 60 Sekunden begrenzt (429 KEEP_CALM).

await api.apps.network.purgeCache(appId);

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

JavaScript-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