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

# ネットワーク

> client.apps.network で Web アプリケーションのエッジアナリティクス、エラー、リクエストログ、パフォーマンスを取得し、DNS の確認、カスタムドメインの設定、キャッシュのパージを行います。

`client.apps.network` は **Web アプリでのみ**機能します。すべてのメソッドは第 1 引数にアプリ ID を取ります。

## 期間

`analytics`、`errors`、`logs`、`performance` は `start` と `end` を取り、それぞれ ISO 8601 文字列または `datetime` を指定します。naive な `datetime` はローカル時刻として扱われ、UTC に変換されます。期間は最大 **7 日**で、`start` はアプリの作成日より前にならないよう切り詰められます。無効な期間は 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
```

結果は 5 分単位でキャッシュされます。これら 4 つのメソッドのキャッシュミスは、アカウントごとに 60 秒あたり 20 リクエストの制限を共有しており、超過すると 429 `RATE_LIMITED` になります。

## アナリティクス

`network.analytics(app_id, start, end, **filters)` は、トラフィックの合計と内訳を返します。トラフィックのない期間では `None` を返します。

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

内訳は `countries`、`devices`、`os`、`browsers`、`protocols`、`methods`、`paths`、`referers`、`providers`、`ips`、`status_codes`、`bots`、`content_types` です。各バケットには `type`、`visits`、`requests`、`bytes` があります。

### フィルター

フィルターはキーワード引数で、すべての内訳を絞り込みます。各フィルターには、対応する内訳の `type` の値をそのまま指定します:

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

| フィルター                              | 例                                    |
| ---------------------------------- | ------------------------------------ |
| `country`                          | `"BR"` (2 文字のコード)                    |
| `ip`                               | `"203.0.113.7"`                      |
| `path`                             | `"/api"` (パスのプレフィックス)                |
| `status`                           | `"404"`                              |
| `os`, `browser`, `protocol`, `bot` | 内訳の `type`                           |
| `referer`                          | `"Direct"` はリファラーなしを意味します            |
| `provider`                         | `"NAME (ASN)"`、例: `"GOOGLE (15169)"` |
| `content_type`                     | 内訳の `type`                           |

無効なフィルターは 400 `INVALID_FILTER` になります。`None` または `''` に設定したフィルターは送信されません。

## エラー

`network.errors(app_id, start, end, include_4xx=False)` は期間内の 5xx レスポンスを返し、`include_4xx=True` (キーワード専用) を指定すると 4xx も含めます。空の期間では `None` を返します。

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

## リクエストログ

`network.logs(app_id, start, end)` は、クライアント、リクエスト、レスポンスの詳細を含む個々のリクエストを返します。Pro プランと Enterprise プランで利用できます (それ以外では 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"])
```

## パフォーマンス

`network.performance(app_id, start, end)` は、エッジとオリジンでのレイテンシーのパーセンタイル (`p50`、`p95`、`p99`、ミリ秒) を、国別、ロケーション別、最も遅いパス別に返します。空の期間では `None` を返します。Pro プランと 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)` は、カスタムドメインに必要な DNS レコードをそのステータスとともに返します。カスタムドメインがない場合は 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"
```

## カスタムドメイン

`network.set_domain(app_id, domain)` はカスタムドメインを設定します (Standard プラン以上)。削除するには `"@"` を渡します。

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

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

| ステータス | コード                           | 発生条件                    |
| ----- | ----------------------------- | ----------------------- |
| 400   | `INVALID_DOMAIN`              | 有効なドメイン名ではない            |
| 400   | `RESERVED_DOMAIN`             | Square Cloud のドメインである   |
| 403   | `UPGRADE_REQUIRED`            | プランでカスタムドメインを利用できない     |
| 403   | `LOAD_BALANCER_LIMIT_REACHED` | このドメイン上のアプリ数がプランの上限に達した |
| 409   | `DOMAIN_ALREADY_EXISTS`       | ドメインが別のアカウントのアプリに属している  |
| 502   | `DNS_FAILED`                  | エッジプロバイダーがドメインを拒否した     |

## キャッシュのパージ

`network.purge_cache(app_id)` はアプリのエッジキャッシュを消去します。パージは 60 秒に 1 回までに制限されています (429 `KEEP_CALM`)。

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

## アナリティクス系メソッドのエラー

| ステータス | コード                                                                                  | 発生条件                                         |
| ----- | ------------------------------------------------------------------------------------ | -------------------------------------------- |
| 400   | `INVALID_TIME_RANGE`                                                                 | `start`/`end` がない、形式が不正、または前後が逆になっている        |
| 400   | `INVALID_FILTER`                                                                     | フィルターが形式に一致しない (`analytics`)                 |
| 403   | `UPGRADE_REQUIRED`                                                                   | Pro と Enterprise 以外での `logs` と `performance` |
| 429   | `RATE_LIMITED`                                                                       | キャッシュミスの共有制限に達した                             |
| 500   | `UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE` | エッジプロバイダーで障害が発生した                            |
| 503   | `ANALYTICS_BUSY`                                                                     | エッジアナリティクスがビジー状態: 自動的にリトライされます               |