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

# ルールと統計

> blob.rules でプレフィックスごとのルールを取得・置き換えし、blob.stats() でアカウントの使用状況を取得します。

## ルール

ルールは、プレフィックス配下のすべてのオブジェクトに対するデフォルト値と制限を設定します: 公開範囲、有効期限、最大サイズ、許可する拡張子、キャッシュ、自動削除。SDK、アップロードトークン、ダッシュボードのいずれからのアップロードであっても、プレフィックス配下のすべてのアップロードに適用されます。プランの制限とマッチングについては、[Blob 設定の更新](/ja/blob-reference/endpoint/settings-put)を参照してください。

### `rules.get()`

```typescript theme={"system"}
const rules = await blob.rules.get();
```

保存されているルールを配列で返します。各ルールには以下のフィールドに加えて `created_at` があり、`delete_after_days` を持つ場合は `active_from` もあります。

<Note>
  `active_from` は**オプション**です。API は `delete_after_days` を持つルールに対してのみ送信します。TypeScript では `undefined` の場合を処理してください。
</Note>

### `rules.set(rules)`

```typescript theme={"system"}
await blob.rules.set([
    { prefix: "tmp/", delete_after_days: 7 },
    { prefix: "avatars/", max_size: 5 * 1024 * 1024, extensions: ["png", "jpg"] },
]);
```

<Warning>
  `rules.set()` は**リスト全体を置き換えます**。残したいルールはすべて送信してください。`rules.set([])` はすべてのルールを削除します。ルールを 1 つ追加するには、まずリストを取得します:

  ```typescript theme={"system"}
  const current = await blob.rules.get();
  await blob.rules.set([
      ...current.map(({ created_at, active_from, ...rule }) => rule),
      { prefix: "exports/", expire: "30d" },
  ]);
  ```
</Warning>

`rules.get()` と同様に、保存されたリストを返します。

| フィールド               | 型          | 説明                                                                 |
| ------------------- | ---------- | ------------------------------------------------------------------ |
| `prefix`            | `string`   | 必須。ルールを適用するプレフィックス (例: `"a/b/"`)。                                  |
| `private`           | `boolean`  | デフォルトの公開範囲。                                                        |
| `expire`            | `string`   | デフォルトの有効期限 (`"30d"`、`"168h"` など)。                                  |
| `max_size`          | `number`   | 最大ファイルサイズ (バイト)。512 B〜10 GiB。                                      |
| `extensions`        | `string[]` | 許可する拡張子 1〜50 個。`^[a-z0-9]{1,16}(\.[a-z0-9]{1,16})?$` に一致する必要があります。 |
| `cache_control`     | `string`   | デフォルトの `Cache-Control`。                                            |
| `delete_after_days` | `number`   | オブジェクトが書き込まれてからこの日数が経過すると削除します。7〜3650 (Enterprise は 1 から)。         |

<Warning>
  `delete_after_days` が有効になるのは、**ルールが保存されてから 24 時間後**です (`active_from` を参照)。一度有効になると、削除されたオブジェクトは復元できません。
</Warning>

ルールが拒否された場合、エラーの [`extra`](/ja/sdks/blob/errors#squarecloudbloberror) に問題のある `prefix` が含まれます:

```typescript theme={"system"}
import { SquareCloudBlobError } from "@squarecloud/blob";

try {
    await blob.rules.set(rules);
} catch (error) {
    if (error instanceof SquareCloudBlobError) {
        console.error(error.code, error.extra.prefix);
    }
}
```

<Note>
  `rules.get()` は読み取りなので[リトライ](/ja/sdks/blob/errors#リトライポリシー)されます。`rules.set()` は **1 回のみ**試行されます。
</Note>

## 統計

```typescript theme={"system"}
const stats = await blob.stats();

console.log(stats.usage.objects); // total objects
console.log(stats.usage.storage); // storage used, in bytes
```

| フィールド           | 説明                                                            |
| --------------- | ------------------------------------------------------------- |
| `usage.objects` | オブジェクト数。                                                      |
| `usage.storage` | 使用中のストレージ (バイト)。                                              |
| `plan.included` | プランに含まれるストレージ (バイト)。                                          |
| `billing`       | `extraStorage`、`storagePrice`、`objectsPrice`、`totalEstimate`。 |
| `month`         | 当月の `days` と `average_storage`。                               |

<Info>
  統計は**推定値**で、サーバーによって **60 秒間**キャッシュされます。`billing` はプランを超えるストレージの推定値にすぎず、請求書ではありません。
</Info>

[Blob アカウント統計](/ja/blob-reference/endpoint/stats)を参照してください。