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

# Rete

> Leggi analytics dell'edge, errori, log delle richieste e prestazioni di un'applicazione web, controlla il DNS, imposta un dominio personalizzato e svuota la cache con client.apps.network.

`client.apps.network` funziona **solo con le app web**. Ogni metodo accetta come primo argomento l'id dell'app.

## Finestre temporali

`analytics`, `errors`, `logs` e `performance` accettano uno `start` e un `end`, ciascuno una stringa ISO 8601 o un `datetime`. Un `datetime` naive è in ora locale e viene convertito in UTC. Una finestra è al massimo di **7 giorni**, e `start` viene limitato alla data di creazione dell'app. Una finestra non valida produce 400 `INVALID_TIME_RANGE`.

```python theme={"system"}
from datetime import UTC, datetime, timedelta

end = datetime.now(UTC)
start = end - timedelta(hours=24)  # last 24 h
```

I risultati vengono messi in cache in intervalli di 5 minuti. I cache miss di questi quattro metodi condividono un limite di 20 richieste ogni 60 secondi per account: superarlo produce 429 `RATE_LIMITED`.

## Analytics

`network.analytics(app_id, start, end, **filters)` restituisce i totali del traffico e le relative suddivisioni. Restituisce `None` per una finestra senza traffico.

```python theme={"system"}
analytics = client.apps.network.analytics(app_id, start, end)

if analytics:
    print(analytics["visits"])     # [{'visits', 'requests', 'bytes', 'date'}]
    print(analytics["countries"])  # [{'type': 'BR', 'visits', 'requests', 'bytes'}]
```

Le suddivisioni sono `countries`, `devices`, `os`, `browsers`, `protocols`, `methods`, `paths`, `referers`, `providers`, `ips`, `status_codes`, `bots` e `content_types`. Ogni gruppo ha `type`, `visits`, `requests` e `bytes`.

### Filtri

I filtri sono argomenti keyword e restringono ogni suddivisione. Ciascuno accetta il valore `type` esatto della sua suddivisione:

```python theme={"system"}
brazil = client.apps.network.analytics(
    app_id,
    start,
    end,
    country="BR",
    path="/api",
    provider="GOOGLE (15169)",
)
```

| Filtro                             | Esempio                                   |
| ---------------------------------- | ----------------------------------------- |
| `country`                          | `"BR"` (codice di 2 lettere)              |
| `ip`                               | `"203.0.113.7"`                           |
| `path`                             | `"/api"` (prefisso del percorso)          |
| `status`                           | `"404"`                                   |
| `os`, `browser`, `protocol`, `bot` | Il `type` della suddivisione              |
| `referer`                          | `"Direct"` significa nessun referer       |
| `provider`                         | `"NAME (ASN)"`, ad es. `"GOOGLE (15169)"` |
| `content_type`                     | Il `type` della suddivisione              |

Un filtro non valido produce 400 `INVALID_FILTER`. Un filtro impostato a `None` o `''` non viene inviato.

## Errori

`network.errors(app_id, start, end, include_4xx=False)` restituisce le risposte 5xx della finestra, più le 4xx con `include_4xx=True` (solo keyword). Restituisce `None` per una finestra vuota.

```python theme={"system"}
errors = client.apps.network.errors(app_id, start, end, include_4xx=True)

if errors:
    print(errors["summary"]["total"], errors["summary"]["by_class"])
    print(errors["top_paths"])
```

## Log delle richieste

`network.logs(app_id, start, end)` restituisce le singole richieste con i dettagli di client, richiesta e risposta. Disponibile nei piani Pro ed Enterprise (altrimenti 403 `UPGRADE_REQUIRED`).

```python theme={"system"}
for log in client.apps.network.logs(app_id, start, end):
    print(log["timestamp"], log["request"]["method"], log["request"]["path"], log["response"]["status"])
```

## Prestazioni

`network.performance(app_id, start, end)` restituisce i percentili di latenza (`p50`, `p95`, `p99`, in ms) all'edge e all'origine, per paese, per località e per i percorsi più lenti. Restituisce `None` per una finestra vuota. Disponibile nei piani Pro ed Enterprise.

```python theme={"system"}
performance = client.apps.network.performance(app_id, start, end)

if performance:
    print(performance["summary"]["edge"]["p95"], performance["summary"]["origin"]["p95"])
```

## DNS

`network.dns(app_id)` restituisce i record DNS di cui ha bisogno il tuo dominio personalizzato, con il loro stato. Senza un dominio personalizzato produce 400 `NO_CUSTOM_DOMAIN`.

```python theme={"system"}
for record in client.apps.network.dns(app_id):
    print(record["type"], record["name"], record["value"], record["status"])  # type: "txt" | "cname"
```

## Dominio personalizzato

`network.set_domain(app_id, domain)` associa un dominio personalizzato (dal piano Standard in su). Passa `"@"` per rimuoverlo.

```python theme={"system"}
client.apps.network.set_domain(app_id, "www.example.com")

# Remove it
client.apps.network.set_domain(app_id, "@")
```

| Status | Codice                        | Quando                                                                  |
| ------ | ----------------------------- | ----------------------------------------------------------------------- |
| 400    | `INVALID_DOMAIN`              | Non è un nome di dominio valido                                         |
| 400    | `RESERVED_DOMAIN`             | Un dominio di Square Cloud                                              |
| 403    | `UPGRADE_REQUIRED`            | Il piano non include domini personalizzati                              |
| 403    | `LOAD_BALANCER_LIMIT_REACHED` | È stato raggiunto il limite di app su questo dominio previsto dal piano |
| 409    | `DOMAIN_ALREADY_EXISTS`       | Il dominio appartiene a un'app di un altro account                      |
| 502    | `DNS_FAILED`                  | Il provider edge ha rifiutato il dominio                                |

## Svuotare la cache

`network.purge_cache(app_id)` svuota la cache edge dell'app. È limitato a uno svuotamento ogni 60 secondi (429 `KEEP_CALM`).

```python theme={"system"}
client.apps.network.purge_cache(app_id)
```

## Errori dei metodi di analytics

| Status | Codice                                                                               | Quando                                                         |
| ------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| 400    | `INVALID_TIME_RANGE`                                                                 | `start`/`end` mancanti, malformati o invertiti                 |
| 400    | `INVALID_FILTER`                                                                     | Un filtro non rispetta il suo formato (`analytics`)            |
| 403    | `UPGRADE_REQUIRED`                                                                   | `logs` e `performance` al di fuori dei piani Pro ed Enterprise |
| 429    | `RATE_LIMITED`                                                                       | Raggiunto il limite condiviso di cache miss                    |
| 500    | `UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE` | Il provider edge ha avuto un errore                            |
| 503    | `ANALYTICS_BUSY`                                                                     | Le analytics dell'edge sono occupate: ripetuto automaticamente |