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

# Réseau

> Consultez les analytics edge, les erreurs, les logs de requêtes et les performances d'une application web, vérifiez le DNS, définissez un domaine personnalisé et purgez le cache avec client.apps.network.

`client.apps.network` fonctionne **uniquement sur les applications web**. Chaque méthode prend d'abord l'identifiant de l'application.

## Fenêtres temporelles

`analytics`, `errors`, `logs` et `performance` prennent un `start` et un `end`, chacun étant une chaîne ISO 8601 ou un `datetime`. Un `datetime` naïf est considéré comme une heure locale et converti en UTC. 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`.

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

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

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(app_id, start, end, **filters)` renvoie les totaux et les répartitions du trafic. Elle renvoie `None` pour une fenêtre sans trafic.

```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'}]
```

Les répartitions sont `countries`, `devices`, `os`, `browsers`, `protocols`, `methods`, `paths`, `referers`, `providers`, `ips`, `status_codes`, `bots` et `content_types`. Chaque groupe a `type`, `visits`, `requests` et `bytes`.

### Filtres

Les filtres sont des arguments nommés et restreignent chaque répartition. Chacun prend la valeur `type` exacte de sa répartition :

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

| 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)"` |
| `content_type`                     | Le `type` de la répartition                |

Un filtre invalide donne 400 `INVALID_FILTER`. Un filtre défini à `None` ou `''` n'est pas envoyé.

## Erreurs

`network.errors(app_id, start, end, include_4xx=False)` renvoie les réponses 5xx de la fenêtre, plus les 4xx avec `include_4xx=True` (argument uniquement nommé). Elle renvoie `None` pour une fenêtre vide.

```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"])
```

## Logs de requêtes

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

```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"])
```

## Performances

`network.performance(app_id, 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 `None` pour une fenêtre vide. Disponible sur les plans Pro et 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)` renvoie les enregistrements DNS dont votre domaine personnalisé a besoin, avec leur statut. Sans domaine personnalisé, elle donne 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"
```

## Domaine personnalisé

`network.set_domain(app_id, domain)` associe un domaine personnalisé (plan Standard et supérieurs). Passez `"@"` pour le supprimer.

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

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

| 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.purge_cache(app_id)` vide le cache edge de l'application. Elle est limitée à une purge toutes les 60 secondes (429 `KEEP_CALM`).

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

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