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

# Objets

> Listez, inspectez, partagez par lien, mettez à jour, supprimez, copiez et déplacez des objets Blob Storage avec @squarecloud/blob.

<Note>
  Les identifiants d'objet sont opaques (`pub/...`, `prv/...`). Stockez-les tels qu'ils sont renvoyés, ne les construisez ni ne les analysez jamais, et remplacez l'identifiant stocké chaque fois que [`update()`](#mettre-à-jour-des-objets) en renvoie un nouveau. Voir [IDs des objets](/fr/sdks/blob/client#ids-des-objets).
</Note>

## Lister

`list()` est un **générateur asynchrone** qui suit le curseur à travers toutes les pages. L'ordre n'est pas garanti.

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

`listPage()` récupère **une seule page**. Utilisez-la pour une pagination manuelle ou pour obtenir `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 });
}
```

| Option      | Type      | Description                                                             |
| ----------- | --------- | ----------------------------------------------------------------------- |
| `prefix`    | `string`  | Uniquement les objets sous ce préfixe.                                  |
| `delimiter` | `"/"`     | Regroupe par dossier : la page renvoie aussi `folders`.                 |
| `private`   | `boolean` | Uniquement les objets privés (`true`) ou publics (`false`).             |
| `limit`     | `number`  | Objets par page, de 1 à 1000 (1000 par défaut).                         |
| `cursor`    | `string`  | `listPage()` uniquement : le `continuationToken` de la page précédente. |

Une page contient `objects`, `folders` (uniquement avec `delimiter`) et `continuationToken` (**absent sur la dernière page**). Chaque objet listé a `id`, `size`, `created_at`, `expires_at`, `private`, `url` et `etag`. Voir [Liste d'objets](/fr/blob-reference/endpoint/list).

## Détails d'un objet

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

Renvoie `id`, `size`, `content_type`, `etag`, `created_at`, `expires_at`, `private`, `url`, `cache_control`, `content_disposition`, `original_name`, `metadata` et `legacy`. Voir [Informations sur l'objet](/fr/blob-reference/endpoint/info).

<Note>
  `created_at` est l'heure de dernière modification dans le stockage : une mise à jour qui copie l'objet (visibilité, expiration, en-têtes) la réinitialise.
</Note>

## Liens de téléchargement

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

* Un objet **public** obtient son **URL CDN permanente**, avec `expires_at: null`.
* Un objet **privé**, ou tout appel avec `disposition` ou `filename`, obtient un **lien temporaire** valable `expires` secondes (jusqu'à 24 heures).

<Warning>
  Un lien temporaire **ne peut pas être révoqué**. Pour des liens révocables, protégés par mot de passe ou limités en nombre de téléchargements, utilisez un [partage](/fr/sdks/blob/sharing).
</Warning>

| Option        | Type                         | Description                                                            |
| ------------- | ---------------------------- | ---------------------------------------------------------------------- |
| `expires`     | `number`                     | Durée de vie du lien en secondes, de 60 à 86400 (3600 par défaut).     |
| `disposition` | `"inline"` \| `"attachment"` | Remplace `Content-Disposition` pour ce lien.                           |
| `filename`    | `string`                     | Nom de fichier sous lequel le navigateur enregistre le téléchargement. |

Le résultat contient `url`, `expires_at`, `private`, `size` et `content_type`. Voir [Téléchargement d'objet](/fr/blob-reference/endpoint/download).

## Mettre à jour des objets

`update()` modifie la visibilité, l'expiration, le cache, la disposition ou les métadonnées d'**un objet ou jusqu'à 50**. Elle **renvoie toujours un tableau**, un résultat par objet, et chaque résultat indique son propre succès dans `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);
}
```

| Modification    | Type                                     | Description                                                         |
| --------------- | ---------------------------------------- | ------------------------------------------------------------------- |
| `private`       | `boolean`                                | Rend l'objet privé ou public. **Change l'identifiant.**             |
| `expire`        | `string \| null`                         | Nouvelle expiration ; `null` la supprime. **Change l'identifiant.** |
| `cache_control` | `string \| null`                         | `null` le supprime.                                                 |
| `disposition`   | `"inline"` \| `"attachment"` \| `null`   | `null` la supprime.                                                 |
| `metadata`      | `Record<string, string \| null> \| null` | `{ key: null }` supprime une clé ; `null` les supprime toutes.      |

Un résultat réussi (`ok: true`) contient `object` (l'identifiant que vous avez envoyé), `changed`, `id` (**l'identifiant après la modification**), `private`, `url`, `expires_at` et `size`. Un résultat en échec (`ok: false`) contient `object` et `code`. Un lot ne lève pas d'erreur pour les échecs par objet. Voir [Mise à jour d'objet](/fr/blob-reference/endpoint/update).

## Supprimer

La suppression est **immédiate et définitive** : il n'y a pas de corbeille.

```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]);
```

| Appel           | Renvoie                          | Pour un objet manquant                                       |
| --------------- | -------------------------------- | ------------------------------------------------------------ |
| `delete(id)`    | `void`                           | Lève une `SquareCloudBlobError` (`OBJECT_NOT_FOUND`).        |
| `delete([ids])` | `{ deleted, not_found, failed }` | Signalé dans `not_found`. `failed` liste des `{ id, code }`. |

Avec **un seul identifiant dans un tableau**, le SDK renvoie quand même `{ deleted, not_found, failed }` : un objet manquant va dans `not_found`, et `DELETE_FAILED` ou `PREFIX_NOT_ALLOWED` vont dans `failed` au lieu de lever une erreur. Toute autre erreur (authentification, limite de débit, réseau) est toujours levée. Voir [Suppression d'objet](/fr/blob-reference/endpoint/delete).

## Copier, déplacer et renommer

Les deux opérations s'exécutent sur le serveur, sans télécharger le fichier.

```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)` équivaut à `copy()` avec `move: true`.

| Champ de destination | Type             | Description                                                                        |
| -------------------- | ---------------- | ---------------------------------------------------------------------------------- |
| `name`               | `string`         | Requis. Nom **sans extension** : la destination conserve l'extension de la source. |
| `prefix`             | `string`         | Préfixe de destination.                                                            |
| `private`            | `boolean`        | Visibilité de la destination.                                                      |
| `security_hash`      | `boolean`        | Ajoute `_<hash>` au nom.                                                           |
| `expire`             | `string \| null` | Omis, conserve l'expiration de la source ; `null` la supprime.                     |

| Option      | Acceptée par       | Description                                                                        |
| ----------- | ------------------ | ---------------------------------------------------------------------------------- |
| `overwrite` | `copy()`, `move()` | `true` remplace un objet existant à la destination.                                |
| `move`      | `copy()`           | `true` supprime la source une fois la copie réussie (équivaut à appeler `move()`). |

Le résultat contient `id`, `private`, `url`, `expires_at`, `size`, `source`, `moved` et `replaced`. Voir [Copie d'objet](/fr/blob-reference/endpoint/copy).

<Note>
  `update()`, `delete()`, `copy()` et `move()` sont des écritures : elles ont droit à **une seule tentative** et ne sont jamais réessayées. Voir [Politique de nouvelles tentatives](/fr/sdks/blob/errors#politique-de-nouvelles-tentatives).
</Note>