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

# アップロード

> put() でファイルをアップロードします: ファイルパス、Blob/File、バイト列に対応し、90 MiB を超えると自動的にマルチパートアップロードになり、アップロードトークンでブラウザから直接アップロードできます。

## `put(file, options)`

`put()` はファイルを 1 つアップロードし、新しいオブジェクトを返します。

```typescript theme={"system"}
const { id, url } = await blob.put("./photo.png", {
    name: "photo",
    prefix: "avatars",
});
```

### 入力

| 入力                          | 環境             | 備考                                                                                    |
| --------------------------- | -------------- | ------------------------------------------------------------------------------------- |
| `string` (ファイルパス)           | **Node.js のみ** | `fs.openAsBlob` で開かれ、**ディスクからストリーミング**されます。全体がメモリに読み込まれることはありません。拡張子はパスのベース名から取得されます。 |
| `Blob` / `File`             | Node.js とブラウザ  | `File` からは `name` (とその拡張子) が取得されます。                                                   |
| `Uint8Array` (`Buffer` を含む) | Node.js とブラウザ  | 拡張子を設定するには `filename` を渡します。                                                          |
| `ArrayBuffer`               | Node.js とブラウザ  | 拡張子を設定するには `filename` を渡します。                                                          |

オブジェクトの拡張子は `filename`、次にパスのベース名または `File` の名前から取得されます。バイト列やプレーンな `Blob` には名前がないため、アップロードする際は **`filename` を渡してください** (例: `"data.json"`)。

<Note>
  Node.js では、開けないパスはプレーンな `Error` (`Cannot open file: <path>`、元のエラーは `cause`) をスローします。ブラウザでは、パスを渡すとそれより前の段階で `node:fs` のインポートエラーにより失敗します。代わりに `<input type="file">` から取得した `File` を使ってください。
</Note>

### オプション

| オプション             | 型                            | 説明                                                                                                                        |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `name`            | `string`                     | **拡張子を除いた**オブジェクト名。`^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$` に一致し、`..` を含まず、`-ex<digits>` で終わらないこと。アップロードトークンで固定されていない限り必須です。 |
| `prefix`          | `string`                     | フォルダーのようなパス: `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$` のセグメントを最大 8 個、256 文字まで。                                                 |
| `private`         | `boolean`                    | デフォルトは `false`。プライベートオブジェクトには常にセキュリティハッシュが付き、`url: null` になります。                                                           |
| `security_hash`   | `boolean`                    | 名前に `_<hash>` を付加します。                                                                                                     |
| `expire`          | `string`                     | `"30"` (日)、`"30d"`、`"168h"`。7〜1825 日 (Enterprise は 1 時間から)。有効期限は ID の一部になります。                                             |
| `overwrite`       | `boolean`                    | `false` の場合、名前が使用済みだと `OBJECT_ALREADY_EXISTS` で失敗します。**シンプルアップロードのみ。**                                                    |
| `disposition`     | `"inline"` \| `"attachment"` | オブジェクトの `Content-Disposition`。                                                                                            |
| `auto_download`   | `boolean`                    | ダウンロードを強制します (`application/octet-stream`)。                                                                                |
| `cache_control`   | `string`                     | `immutable`、`max-age=60..31536000`、または `no-cache` (Enterprise)。                                                           |
| `metadata`        | `Record<string, string>`     | Pro と Enterprise。キーは `^[a-z0-9-]{1,64}$` (`sq-*` は不可)、最大 5 キー、512 バイトまで。                                                  |
| `checksum_sha256` | `string`                     | 小文字の 16 進数 64 文字。一致しない場合は `CHECKSUM_MISMATCH` で失敗し、何も保存されません。**シンプルアップロードのみ。**                                            |
| `filename`        | `string`                     | その拡張子がオブジェクトの拡張子になるファイル名。デフォルトは `File` の名前またはパスのベース名です。                                                                   |
| `mime_type`       | `string`                     | `filename` に拡張子がない場合に、拡張子を決めるためだけに使われます。`Content-Type` はサーバーが決定します。                                                       |

サーバー側の完全なルールについては、[Blob オブジェクトのアップロード](/ja/blob-reference/endpoint/post)を参照してください。

### 結果

| フィールド                                  | 型                | 説明                                                                                               |
| -------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| `id`                                   | `string`         | 不透明なオブジェクト ID。[そのまま保存してください](/ja/sdks/blob/client#オブジェクト-id)。                                    |
| `private`                              | `boolean`        | オブジェクトがプライベートかどうか。                                                                               |
| `url`                                  | `string \| null` | 公開 URL。プライベートオブジェクトの場合は `null` です ([`downloadUrl()`](/ja/sdks/blob/objects#ダウンロードリンク) を使ってください)。 |
| `expires_at`                           | `string`         | 有効期限がある場合、オブジェクトが失効する日時。                                                                         |
| `size`                                 | `number`         | バイト単位のサイズ。                                                                                       |
| `name`, `prefix`, `sha256`, `replaced` |                  | シンプルアップロードのみ。                                                                                    |
| `parts`                                | `number`         | マルチパートアップロードのみ: 送信したパートの数。                                                                       |

## シンプルアップロードとマルチパートアップロード

`put()` はファイルサイズに応じてアップロード方式を選びます:

| ファイルサイズ                        | 方式                 | Endpoint                                                       |
| ------------------------------ | ------------------ | -------------------------------------------------------------- |
| **90 MiB** (94,371,840 バイト) 以下 | シンプルアップロード、1 リクエスト | [Blob オブジェクトのアップロード](/ja/blob-reference/endpoint/post)         |
| 90 MiB 超、**10 GiB** まで         | マルチパート (分割) アップロード | [Blob チャンクアップロードの開始](/ja/blob-reference/endpoint/chunked-init) |

すべてのファイルは**最低 512 バイト**必要で、それより小さいファイルは `FILE_TOO_SMALL` で失敗します。ルールやアップロードトークンの `max_size`、またはストレージの割り当てによって、10 GiB の上限が下がることがあります。

### マルチパートアップロードの流れ

1. SDK がアップロードを開始し、サーバーがパートの制限 (`max_size`、`max_parts`) を返します。
2. ファイルは `min(max_size, max(16 MiB, ceil(size / max_parts)))` バイトのパートに分割されます。パートは通常 16 MiB 以上ですが、サーバーの `max_size` がそれより小さい場合は小さくなります。
3. パートは、サーバーが処理中のパートに設けている上限である **6 個ずつ**送信されます。失敗したパートは `maxRetries` の範囲内で[リトライ](/ja/sdks/blob/errors#リトライポリシー)されます。
4. すべてのパートが届くと、SDK がアップロードを完了します。

パートが最終的に失敗した場合や完了処理が失敗した場合、SDK は**処理中のパートを待ってから**アップロードを**中止**するため、中止後にパートが届くことはありません。元のエラーがスローされます。**再開機能はありません**: もう一度 `put()` を呼び出してください。

<Warning>
  マルチパートアップロードは **`overwrite: false` や `checksum_sha256` をチェックしません**。同じ名前の既存オブジェクトを常に置き換えます。
</Warning>

<Note>
  1 つのアカウントで同時に開いておけるマルチパートアップロードは最大 **32 個**です (S3 ゲートウェイと共有)。それを超えると `TOO_MANY_OPEN_UPLOADS` で失敗します。パートはアカウントごとに 6 個ずつ送信されるため、**大きなアップロードは 1 つずつ**実行してください。
</Note>

## ブラウザからのアップロード

API キーを決してブラウザに送らないでください。代わりに、サーバーが短期間有効な**アップロードトークン**を発行し、ブラウザはそれを使ってアップロードします。

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

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

    // e.g. inside your API route
    const { token } = await blob.uploadTokens.create({
        prefix: "avatars/",
        security_hash: true,
        max_size: 5 * 1024 * 1024,
        allowed_extensions: ["png", "jpg"],
    });
    // send only `token` to the browser
    ```
  </Tab>

  <Tab title="ブラウザ">
    ```typescript theme={"system"}
    import { SquareCloudBlob } from "@squarecloud/blob";

    const upload = new SquareCloudBlob(token);
    const { url } = await upload.put(input.files[0], { name: "avatar" });
    ```
  </Tab>
</Tabs>

トークンで作成したクライアントは、マルチパートアップロードを含め、**`put()` しか呼び出せません**。その他のメソッドは `403 UPLOAD_TOKEN_NOT_ALLOWED` で失敗します。

### `uploadTokens.create(options)`

トークンは、発行時に指定されたすべてのオプションを固定します。

| オプション                | 型                        | 説明                                                                    |
| -------------------- | ------------------------ | --------------------------------------------------------------------- |
| `name`               | `string`                 | オブジェクト名を固定します。指定しない場合、セキュリティハッシュが常に適用されます。                            |
| `prefix`             | `string`                 | プレフィックスを固定します。                                                        |
| `private`            | `boolean`                | 公開範囲を固定します。                                                           |
| `security_hash`      | `boolean`                | 名前に `_<hash>` を付加します。                                                 |
| `expire`             | `string`                 | オブジェクトの有効期限。`put()` と同じ形式です。                                          |
| `max_size`           | `number`                 | 最大ファイルサイズ (バイト)。                                                      |
| `allowed_extensions` | `string[]`               | 拡張子 1〜20 個。                                                           |
| `metadata`           | `Record<string, string>` | アップロードされたオブジェクトに適用されるメタデータ。                                           |
| `expires_in`         | `number`                 | トークンの有効期間 (秒)。60〜3600 (デフォルト 900)。                                    |
| `max_uses`           | `number`                 | 許可するアップロード回数。1〜100 (デフォルト 1)。それを超えるとトークンは `UPLOAD_TOKEN_USED` で失敗します。 |

`{ token, expires_at, max_uses }` を返します。サーバー側のルールについては [Blob アップロードトークン](/ja/blob-reference/endpoint/upload-tokens)を参照してください。

<Note>
  `uploadTokens.create()` は書き込みなので、**1 回のみ**試行され、リトライされることはありません。
</Note>