Objets

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() en renvoie un nouveau. Voir IDs des objets.

Lister

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

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 :

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.

Détails d’un objet

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.

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.

Liens de téléchargement

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

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.

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.

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.

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.

Supprimer

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

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

Copier, déplacer et renommer

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

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

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.

Services

Runtimes

Plateforme

Dépannage

CLI

SDKs

Changelog

Lister

Détails d’un objet

Liens de téléchargement

Mettre à jour des objets

Supprimer

Copier, déplacer et renommer

​Lister

​Détails d’un objet

​Liens de téléchargement

​Mettre à jour des objets

​Supprimer

​Copier, déplacer et renommer

Lister

Détails d’un objet

Liens de téléchargement

Mettre à jour des objets

Supprimer

Copier, déplacer et renommer