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

# オブジェクト

> @squarecloud/blob で Blob Storage のオブジェクトを一覧、確認、リンク、更新、削除、コピー、移動します。

<Note>
  オブジェクト ID は不透明です (`pub/...`、`prv/...`)。返されたとおりに保存し、組み立てたりパースしたりせず、[`update()`](#オブジェクトの更新) が新しい ID を返したら保存している ID を置き換えてください。[オブジェクト ID](/ja/sdks/blob/client#オブジェクト-id) を参照してください。
</Note>

## 一覧

`list()` は、カーソルをたどってすべてのページを取得する**非同期ジェネレーター**です。順序は保証されません。

```typescript theme={"system"}
for await (const object of blob.list({ prefix: "avatars/" })) {
    console.log(object.id, object.size, object.url);
}
```

`listPage()` は **1 ページ**を取得します。手動でページ送りをする場合や、`folders` を取得する場合に使います:

```typescript theme={"system"}
const { objects, folders, continuationToken } = await blob.listPage({
    prefix: "avatars/",
    delimiter: "/",
});

// next page
if (continuationToken) {
    const next = await blob.listPage({ prefix: "avatars/", delimiter: "/", cursor: continuationToken });
}
```

| オプション       | 型         | 説明                                           |
| ----------- | --------- | -------------------------------------------- |
| `prefix`    | `string`  | このプレフィックス配下のオブジェクトのみ。                        |
| `delimiter` | `"/"`     | フォルダーごとにグループ化します。ページは `folders` も返します。       |
| `private`   | `boolean` | プライベート (`true`) または公開 (`false`) のオブジェクトのみ。   |
| `limit`     | `number`  | 1 ページあたりのオブジェクト数。1〜1000 (デフォルト 1000)。        |
| `cursor`    | `string`  | `listPage()` のみ: 前のページの `continuationToken`。 |

ページには `objects`、`folders` (`delimiter` を指定した場合のみ)、`continuationToken` (**最後のページには存在しません**) があります。一覧の各オブジェクトには `id`、`size`、`created_at`、`expires_at`、`private`、`url`、`etag` があります。[Blob オブジェクトの一覧](/ja/blob-reference/endpoint/list)を参照してください。

## オブジェクトの詳細

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

`id`、`size`、`content_type`、`etag`、`created_at`、`expires_at`、`private`、`url`、`cache_control`、`content_disposition`、`original_name`、`metadata`、`legacy` を返します。[Blob オブジェクト情報](/ja/blob-reference/endpoint/info)を参照してください。

<Note>
  `created_at` はストレージ上の最終更新日時です。オブジェクトをコピーする更新 (公開範囲、有効期限、ヘッダー) を行うとリセットされます。
</Note>

## ダウンロードリンク

```typescript theme={"system"}
const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 });
```

* **公開**オブジェクトには、`expires_at: null` の**恒久的な CDN URL** が返されます。
* **プライベート**オブジェクト、または `disposition` か `filename` を指定した呼び出しには、`expires` 秒間 (最大 24 時間) 有効な**一時リンク**が返されます。

<Warning>
  一時リンクは**取り消せません**。取り消し可能なリンク、パスワード保護されたリンク、ダウンロード回数を制限したリンクには、[共有](/ja/sdks/blob/sharing)を使ってください。
</Warning>

| オプション         | 型                            | 説明                                    |
| ------------- | ---------------------------- | ------------------------------------- |
| `expires`     | `number`                     | リンクの有効期間 (秒)。60〜86400 (デフォルト 3600)。   |
| `disposition` | `"inline"` \| `"attachment"` | このリンクの `Content-Disposition` を上書きします。 |
| `filename`    | `string`                     | ブラウザがダウンロードを保存するときのファイル名。             |

結果には `url`、`expires_at`、`private`、`size`、`content_type` があります。[Blob オブジェクトのダウンロード](/ja/blob-reference/endpoint/download)を参照してください。

## オブジェクトの更新

`update()` は、**1 つ、または最大 50 個のオブジェクト**の公開範囲、有効期限、キャッシュ、disposition、メタデータを変更します。**常に配列を返し**、オブジェクトごとに 1 つの結果が含まれ、各結果は自身の成否を `ok` で報告します。

```typescript theme={"system"}
const [result] = await blob.update(id, { private: true, expire: null });

if (result.ok) {
    id = result.id; // the id changed: store the new one
} else {
    console.error(result.code);
}
```

| 変更              | 型                                        | 説明                                             |
| --------------- | ---------------------------------------- | ---------------------------------------------- |
| `private`       | `boolean`                                | オブジェクトをプライベートまたは公開にします。**ID が変わります。**          |
| `expire`        | `string \| null`                         | 新しい有効期限。`null` で削除します。**ID が変わります。**           |
| `cache_control` | `string \| null`                         | `null` で削除します。                                 |
| `disposition`   | `"inline"` \| `"attachment"` \| `null`   | `null` で削除します。                                 |
| `metadata`      | `Record<string, string \| null> \| null` | `{ key: null }` で 1 つのキーを削除し、`null` ですべて削除します。 |

成功した結果 (`ok: true`) には、`object` (送信した ID)、`changed`、`id` (**変更後の ID**)、`private`、`url`、`expires_at`、`size` があります。失敗した結果 (`ok: false`) には `object` と `code` があります。バッチは、オブジェクトごとの失敗では例外をスローしません。[Blob オブジェクトの更新](/ja/blob-reference/endpoint/update)を参照してください。

## 削除

削除は**即時かつ恒久的**です。ゴミ箱はありません。

```typescript theme={"system"}
// Single id: resolves to nothing, throws OBJECT_NOT_FOUND when missing
await blob.delete(id);

// Batch, up to 100 ids
const { deleted, not_found, failed } = await blob.delete([id1, id2]);
```

| 呼び出し            | 戻り値                              | オブジェクトが存在しない場合                                          |
| --------------- | -------------------------------- | ------------------------------------------------------- |
| `delete(id)`    | `void`                           | `SquareCloudBlobError` (`OBJECT_NOT_FOUND`) をスローします。    |
| `delete([ids])` | `{ deleted, not_found, failed }` | `not_found` で報告されます。`failed` には `{ id, code }` が列挙されます。 |

**配列に ID が 1 つだけ**の場合も、SDK は `{ deleted, not_found, failed }` を返します。存在しないオブジェクトは `not_found` に入り、`DELETE_FAILED` や `PREFIX_NOT_ALLOWED` は例外をスローする代わりに `failed` に入ります。その他のエラー (認証、レート制限、ネットワーク) は引き続きスローされます。[Blob オブジェクトの削除](/ja/blob-reference/endpoint/delete)を参照してください。

## コピー、移動、名前変更

どちらもファイルをダウンロードせずに、サーバー上で実行されます。

```typescript theme={"system"}
// Copy: counts toward your storage quota
await blob.copy(id, { name: "photo_copy", prefix: "backup" });

// Move or rename: does not count toward the quota
const moved = await blob.move(id, { name: "renamed" });
id = moved.id;
```

`move(source, destination, options)` は、`move: true` を指定した `copy()` です。

| コピー先のフィールド      | 型                | 説明                                     |
| --------------- | ---------------- | -------------------------------------- |
| `name`          | `string`         | 必須。**拡張子を除いた**名前。コピー先はコピー元の拡張子を引き継ぎます。 |
| `prefix`        | `string`         | コピー先のプレフィックス。                          |
| `private`       | `boolean`        | コピー先の公開範囲。                             |
| `security_hash` | `boolean`        | 名前に `_<hash>` を付加します。                  |
| `expire`        | `string \| null` | 省略するとコピー元の有効期限を維持し、`null` で削除します。      |

| オプション       | 受け付けるメソッド          | 説明                                                     |
| ----------- | ------------------ | ------------------------------------------------------ |
| `overwrite` | `copy()`, `move()` | `true` にすると、コピー先の既存オブジェクトを置き換えます。                      |
| `move`      | `copy()`           | `true` にすると、コピーが成功した時点でコピー元を削除します (`move()` の呼び出しと同じ)。 |

結果には `id`、`private`、`url`、`expires_at`、`size`、`source`、`moved`、`replaced` があります。[Blob オブジェクトのコピー](/ja/blob-reference/endpoint/copy)を参照してください。

<Note>
  `update()`、`delete()`、`copy()`、`move()` は書き込みです。**1 回のみ**試行され、リトライされることはありません。[リトライポリシー](/ja/sdks/blob/errors#リトライポリシー)を参照してください。
</Note>