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

> @squarecloud/blob をインストールし、API キーまたはアップロードトークンで SquareCloudBlob クライアントを作成します。唯一のオプションは maxRetries です。

<Info>
  このページは **`@squarecloud/blob` v4** を解説しています。v3 からアップグレードする場合は、[v3 → v4 移行ガイド](/ja/sdks/blob/migrating_to_v4)をお読みください。
</Info>

`@squarecloud/blob` は、[Square Cloud Blob Storage](/ja/services/blob) の公式 JavaScript SDK です。すべての [Blob API](/ja/blob-reference/authentication) endpoint と [S3 ゲートウェイ](/ja/blob-reference/s3-compatibility)をカバーします。

## 要件

* **Node.js 20** 以降、または任意のモダンブラウザ。SDK が使用するのは `fetch`、`FormData`、`Blob` だけです。
* **ESM と CommonJS** の両方で提供され、**ランタイム依存関係はゼロ**です。
* `@aws-sdk/client-s3` は**オプションの peer dependency** で、[`s3()`](/ja/sdks/blob/s3) を呼び出す場合にのみ必要です。

## インストール

<Tabs>
  <Tab title="npm">
    ```bash theme={"system"}
    npm install @squarecloud/blob
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"system"}
    yarn add @squarecloud/blob
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm add @squarecloud/blob
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add @squarecloud/blob
    ```
  </Tab>
</Tabs>

## クライアントの作成

<Tabs>
  <Tab title="ESM / TypeScript">
    ```typescript theme={"system"}
    import { SquareCloudBlob } from "@squarecloud/blob";

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>

  <Tab title="CommonJS">
    ```javascript theme={"system"}
    const { SquareCloudBlob } = require("@squarecloud/blob");

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>
</Tabs>

### コンストラクタ

```typescript theme={"system"}
new SquareCloudBlob(credential, { maxRetries: 2 });
```

| パラメーター               | 型        | デフォルト | 説明                                                                                                                                       |
| -------------------- | -------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `credential`         | `string` | 必須    | **API キー**、または `put()` のみを呼び出せる**アップロードトークン** (`squp_...`)。                                                                              |
| `options.maxRetries` | `number` | `2`   | 安全に繰り返せるリクエスト (`GET` またはマルチパートのパート) が、ネットワークエラーや `5xx` の後にリトライされる回数。`0` でリトライを無効にします。[リトライポリシー](/ja/sdks/blob/errors#リトライポリシー)を参照してください。 |

## 認証情報

認証情報は `Bearer` プレフィックスなしで、`Authorization` ヘッダーに**そのまま**送信されます。

| 認証情報                    | 入手元                                                                         | できること                                                                                         |
| ----------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| API キー                  | [Square Cloud ダッシュボード](https://squarecloud.app/account/security)            | すべてのメソッド。ただし `blob:read` / `blob:write` の[スコープ](/ja/blob-reference/authentication#スコープ)に従います。 |
| アップロードトークン (`squp_...`) | サーバー上での [`blob.uploadTokens.create()`](/ja/sdks/blob/uploads#ブラウザからのアップロード) | `put()` のみ。その他のメソッドは `403 UPLOAD_TOKEN_NOT_ALLOWED` で失敗します。                                   |

<Warning>
  API キーを決してブラウザに渡さないでください。サーバーでアップロードトークンを発行し、クライアントにはトークンだけを渡します。
</Warning>

## 設定できないもの

`maxRetries` が**唯一の**オプションです。クライアントは次のものを受け付けません:

* **ベース URL。** `https://blob.squarecloud.app/v1/` に固定されています。
* **カスタム `fetch`。** リクエストにはグローバルの `fetch` が使われます。
* **タイムアウトや `AbortSignal`。** 呼び出しは `fetch` が待機する限り続き、キャンセルする方法はありません。
* **カスタムヘッダー。**

## メソッド

すべてのメソッドはプレーンなデータを返します (クラスはありません)。ただし `s3()` は `S3Client` を返します。オプションと結果には API のフィールド名 (主に snake\_case: `security_hash`、`expires_at`) がそのまま使われるため、[Blob API リファレンス](/ja/blob-reference/authentication)をそのまま適用できます。

| グループ                  | メソッド                                                                                                                                                                                            | ページ                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `blob`                | `put(file, options)`                                                                                                                                                                            | [アップロード](/ja/sdks/blob/uploads)               |
| `blob.uploadTokens`   | `create(options)`                                                                                                                                                                               | [アップロード](/ja/sdks/blob/uploads#ブラウザからのアップロード) |
| `blob`                | `list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)` | [オブジェクト](/ja/sdks/blob/objects)               |
| `blob.shares`         | `create(object, options)`, `list()`, `revoke(id)`                                                                                                                                               | [共有](/ja/sdks/blob/sharing)                   |
| `blob.rules` / `blob` | `get()`, `set(rules)` / `stats()`                                                                                                                                                               | [ルールと統計](/ja/sdks/blob/rules_and_stats)       |
| `blob`                | `s3Credentials()`, `s3()`                                                                                                                                                                       | [S3](/ja/sdks/blob/s3)                        |

パッケージは `SquareCloudBlobError`、`BlobErrorCode` 型、すべてのオプション型と結果型 (`PutOptions`、`PutResult`、`ListedObject`、`ObjectInfo`、`Share`、`Rule` など) もエクスポートしています。[エラー](/ja/sdks/blob/errors)を参照してください。

## オブジェクト ID

すべてのオブジェクトは**不透明な ID** で識別されます。たとえば公開オブジェクトなら `pub/...`、プライベートオブジェクトなら `prv/...` です。

* **ID は返されたとおりに保存してください。** 手作業で組み立てたり、パースしたりしないでください。
* **`private` や `expire` を変更すると ID が変わります。** 保存している ID は、必ず [`update()`](/ja/sdks/blob/objects#オブジェクトの更新) が返す ID で置き換えてください。
* URL を組み立てる代わりに、**レスポンスの `url` を使ってください**。プライベートオブジェクトは `url: null` です。リンクは [`downloadUrl()`](/ja/sdks/blob/objects#ダウンロードリンク) または[共有](/ja/sdks/blob/sharing)で取得します。

```typescript theme={"system"}
const { id, url } = await blob.put("./photo.png", { name: "photo", prefix: "avatars" });
// save `id` as-is; use `url` to serve the file
```