Objetos

Los ids de objeto son opacos (pub/..., prv/...). Guárdalos tal como se devuelven, nunca los construyas ni los analices, y reemplaza el id que tengas guardado siempre que update() devuelva uno nuevo. Consulta IDs de objeto.

Listar

list() es un async generator que sigue el cursor a través de todas las páginas. El orden no está garantizado.

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

listPage() obtiene una sola página. Úsalo para la paginación manual o para obtener 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 });
}

Opción	Tipo	Descripción
`prefix`	`string`	Solo los objetos bajo este prefijo.
`delimiter`	`"/"`	Agrupa por carpeta: la página también devuelve `folders`.
`private`	`boolean`	Solo objetos privados (`true`) o públicos (`false`).
`limit`	`number`	Objetos por página, de 1 a 1000 (por defecto 1000).
`cursor`	`string`	Solo en `listPage()`: el `continuationToken` de la página anterior.

Una página tiene objects, folders (solo con delimiter) y continuationToken (ausente en la última página). Cada objeto listado tiene id, size, created_at, expires_at, private, url y etag. Consulta Object List.

Detalles de un objeto

const info = await blob.info(id);

Devuelve id, size, content_type, etag, created_at, expires_at, private, url, cache_control, content_disposition, original_name, metadata y legacy. Consulta Object Info.

created_at es la fecha de última modificación en el almacenamiento: una actualización que copia el objeto (visibilidad, expiración, encabezados) la reinicia.

Enlaces de descarga

const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 });

Un objeto público recibe su URL permanente del CDN, con expires_at: null.
Un objeto privado, o cualquier llamada con disposition o filename, recibe un enlace temporal que dura expires segundos (hasta 24 horas).

Un enlace temporal no se puede revocar. Para enlaces revocables, protegidos con contraseña o con un límite de descargas, usa un enlace compartido.

Opción	Tipo	Descripción
`expires`	`number`	Duración del enlace en segundos, de 60 a 86400 (por defecto 3600).
`disposition`	`"inline"` \| `"attachment"`	Sobrescribe `Content-Disposition` para este enlace.
`filename`	`string`	Nombre de archivo con el que el navegador guarda la descarga.

El resultado tiene url, expires_at, private, size y content_type. Consulta Object Download.

Actualizar objetos

update() cambia la visibilidad, la expiración, la caché, la disposición o los metadatos de un objeto o de hasta 50. Siempre devuelve un array, un resultado por objeto, y cada resultado indica su propio éxito en 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);
}

Cambio	Tipo	Descripción
`private`	`boolean`	Hace el objeto privado o público. Cambia el id.
`expire`	`string \| null`	Nueva expiración; `null` la elimina. Cambia el id.
`cache_control`	`string \| null`	`null` lo elimina.
`disposition`	`"inline"` \| `"attachment"` \| `null`	`null` la elimina.
`metadata`	`Record<string, string \| null> \| null`	`{ key: null }` elimina una clave; `null` las elimina todas.

Un resultado correcto (ok: true) tiene object (el id que enviaste), changed, id (el id después del cambio), private, url, expires_at y size. Un resultado fallido (ok: false) tiene object y code. Un lote no lanza errores por los fallos de objetos individuales. Consulta Object Update.

Eliminar

La eliminación es inmediata y permanente: no hay papelera.

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

Llamada	Devuelve	Con un objeto inexistente
`delete(id)`	`void`	Lanza `SquareCloudBlobError` (`OBJECT_NOT_FOUND`).
`delete([ids])`	`{ deleted, not_found, failed }`	Se indica en `not_found`. `failed` lista `{ id, code }`.

Con un único id dentro de un array, el SDK sigue devolviendo { deleted, not_found, failed }: un objeto inexistente va a not_found, y DELETE_FAILED o PREFIX_NOT_ALLOWED van a failed en lugar de lanzar un error. Cualquier otro error (autenticación, límite de tasa, red) sigue lanzándose. Consulta Delete Objects.

Copiar, mover y renombrar

Ambas operaciones se ejecutan en el servidor, sin descargar el archivo.

// 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) es copy() con move: true.

Campo de destino	Tipo	Descripción
`name`	`string`	Obligatorio. Nombre sin extensión: el destino conserva la extensión del origen.
`prefix`	`string`	Prefijo de destino.
`private`	`boolean`	Visibilidad del destino.
`security_hash`	`boolean`	Añade `_<hash>` al nombre.
`expire`	`string \| null`	Si se omite, se conserva la expiración del origen; `null` la elimina.

Opción	Aceptada por	Descripción
`overwrite`	`copy()`, `move()`	`true` reemplaza un objeto existente en el destino.
`move`	`copy()`	`true` elimina el origen una vez que la copia se completa (igual que llamar a `move()`).

El resultado tiene id, private, url, expires_at, size, source, moved y replaced. Consulta Object Copy.

update(), delete(), copy() y move() son escrituras: tienen un único intento y nunca se reintentan. Consulta Política de reintentos.

Servicios

Runtimes

Plataforma

Solución de problemas

CLI

SDKs

Changelog

Listar

Detalles de un objeto

Enlaces de descarga

Actualizar objetos

Eliminar

Copiar, mover y renombrar

​Listar

​Detalles de un objeto

​Enlaces de descarga

​Actualizar objetos

​Eliminar

​Copiar, mover y renombrar

Listar

Detalles de un objeto

Enlaces de descarga

Actualizar objetos

Eliminar

Copiar, mover y renombrar