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

# S3

> s3Credentials() で S3 認証情報を取得し、s3() ですぐに使える S3Client を取得して、S3 互換ゲートウェイ経由で Blob Storage にアクセスします。

Blob Storage には、任意の S3 クライアントで利用できる [S3 互換ゲートウェイ](/ja/blob-reference/s3-compatibility)があります。SDK はその認証情報、または AWS SDK のすぐに使える `S3Client` を提供します。

<Note>
  どちらのメソッドにも **API キー**が必要です。アップロードトークンで作成したクライアントは `403 UPLOAD_TOKEN_NOT_ALLOWED` になり、古い形式のキーは `LEGACY_API_KEY` になります。
</Note>

## `s3()`

`s3()` は `@aws-sdk/client-s3` の `S3Client` を返します。ゲートウェイの endpoint、リージョン、認証情報が設定済みで、`forcePathStyle: true` も指定されています。

`@aws-sdk/client-s3` は**オプションの peer dependency** です。`s3()` を使う場合にのみインストールしてください。遅延読み込みされるため、SDK 自体は依存関係ゼロのままです。

<Tabs>
  <Tab title="npm">
    ```bash theme={"system"}
    npm install @aws-sdk/client-s3
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"system"}
    yarn add @aws-sdk/client-s3
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm add @aws-sdk/client-s3
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add @aws-sdk/client-s3
    ```
  </Tab>
</Tabs>

```typescript theme={"system"}
import { ListObjectsV2Command } from "@aws-sdk/client-s3";
import { SquareCloudBlob } from "@squarecloud/blob";

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
const s3 = await blob.s3();

const { Contents } = await s3.send(new ListObjectsV2Command({ Bucket: "public" }));
```

### バケット

| バケット      | 内容                          | アクセス         |
| --------- | --------------------------- | ------------ |
| `public`  | 公開オブジェクト                    | 読み取りと書き込み    |
| `private` | プライベートオブジェクト                | 読み取りと書き込み    |
| `legacy`  | 現在のストレージより前にアップロードされたオブジェクト | 読み取り、一覧、削除のみ |

S3 のキーとオブジェクトの対応については[バケット](/ja/blob-reference/s3-compatibility#バケット)と[キー](/ja/blob-reference/s3-compatibility#キー)を、ゲートウェイが受け付ける操作については[サポートされる操作](/ja/blob-reference/s3-compatibility#サポートされる操作)を参照してください。

## `s3Credentials()`

その他の S3 クライアント (aws-cli、rclone、boto3 など) 向けに、`s3Credentials()` は生のキーペアを返します:

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

| フィールド               | 型                 | 説明                                                     |
| ------------------- | ----------------- | ------------------------------------------------------ |
| `access_key_id`     | `string`          | アクセスキー ID。                                             |
| `secret_access_key` | `string`          | **シークレット**アクセスキー。                                      |
| `endpoint`          | `string`          | ゲートウェイの endpoint。                                      |
| `region`            | `string`          | リージョン (`auto`)。                                        |
| `buckets`           | `string[]`        | `public`、`private`、`legacy`。                           |
| `access`            | `{ read, write }` | API キーのスコープに従って、このペアで可能な操作 (型は `boolean \| string[]`)。 |
| `expires_at`        | `string \| null`  | API キー、つまりこのペアが失効する日時。失効しない場合は `null`。                 |

他のクライアントでは**パススタイルのアドレス指定**を使ってください。

<Warning>
  `secret_access_key` は API キーと同じアクセス権を与えます。サーバー上に保管し、キーそのものと同様に保存してください。API キーを取り消したりローテーションしたりすると、このペアも無効になります。
</Warning>

### キャッシュ

このペアは API キーごとに決定的なため、SDK は**クライアントインスタンスごとにキャッシュします**。`s3Credentials()` と `s3()` が API を呼び出すのは 1 回だけで、以降の呼び出しはその結果を再利用します。失敗した呼び出しはキャッシュされないため、次の呼び出しで再試行されます。

<Tip>
  認証情報のルートが受け付けるのは 1 時間あたり 10 リクエストだけです。リクエストごとに `SquareCloudBlob` クライアントを作成するのではなく、1 つ作成して再利用してください。
</Tip>

API リファレンス: [Blob S3 認証情報](/ja/blob-reference/endpoint/s3-credentials)。