Objetos

Os ids de objetos são opacos (pub/..., prv/...). Armazene-os como retornados, nunca os monte nem os interprete, e substitua o id armazenado sempre que update() retornar um novo. Veja Ids de objetos.

Listagem

list() é um async generator que segue o cursor por todas as páginas. A ordem não é garantida.

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

listPage() busca uma página. Use-o para paginação manual ou para obter 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 });
}

Opção	Tipo	Descrição
`prefix`	`string`	Apenas objetos sob este prefixo.
`delimiter`	`"/"`	Agrupa por pasta: a página também retorna `folders`.
`private`	`boolean`	Apenas objetos privados (`true`) ou públicos (`false`).
`limit`	`number`	Objetos por página, de 1 a 1000 (padrão 1000).
`cursor`	`string`	Apenas em `listPage()`: o `continuationToken` da página anterior.

Uma página tem objects, folders (apenas com delimiter) e continuationToken (ausente na última página). Cada objeto listado tem id, size, created_at, expires_at, private, url e etag. Veja Listar objetos.

Detalhes do objeto

const info = await blob.info(id);

Retorna id, size, content_type, etag, created_at, expires_at, private, url, cache_control, content_disposition, original_name, metadata e legacy. Veja Informações do objeto.

created_at é o horário da última modificação no armazenamento: uma atualização que copia o objeto (visibilidade, expiração, headers) o redefine.

Links de download

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

Um objeto público recebe sua URL permanente da CDN, com expires_at: null.
Um objeto privado, ou qualquer chamada com disposition ou filename, recebe um link temporário que dura expires segundos (até 24 horas).

Um link temporário não pode ser revogado. Para links revogáveis, protegidos por senha ou com limite de downloads, use um compartilhamento.

Opção	Tipo	Descrição
`expires`	`number`	Duração do link em segundos, de 60 a 86400 (padrão 3600).
`disposition`	`"inline"` \| `"attachment"`	Sobrescreve o `Content-Disposition` para este link.
`filename`	`string`	Nome com que o navegador salva o download.

O resultado tem url, expires_at, private, size e content_type. Veja Download do objeto.

Atualizando objetos

update() altera a visibilidade, a expiração, o cache, a disposition ou os metadados de um objeto ou até 50. Ele sempre retorna um array, um resultado por objeto, e cada resultado informa seu próprio sucesso em 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);
}

Alteração	Tipo	Descrição
`private`	`boolean`	Torna o objeto privado ou público. Altera o id.
`expire`	`string \| null`	Nova expiração; `null` a remove. Altera o id.
`cache_control`	`string \| null`	`null` o remove.
`disposition`	`"inline"` \| `"attachment"` \| `null`	`null` a remove.
`metadata`	`Record<string, string \| null> \| null`	`{ key: null }` remove uma chave; `null` remove todas.

Um resultado bem-sucedido (ok: true) tem object (o id que você enviou), changed, id (o id após a alteração), private, url, expires_at e size. Um resultado com falha (ok: false) tem object e code. Um lote não lança erro por falhas individuais de objetos. Veja Atualizar objeto.

Excluindo

A exclusão é imediata e permanente: não há lixeira.

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

Chamada	Retorna	Com um objeto inexistente
`delete(id)`	`void`	Lança `SquareCloudBlobError` (`OBJECT_NOT_FOUND`).
`delete([ids])`	`{ deleted, not_found, failed }`	Informado em `not_found`. `failed` lista `{ id, code }`.

Com um único id dentro de um array, o SDK ainda retorna { deleted, not_found, failed }: um objeto inexistente vai para not_found, e DELETE_FAILED ou PREFIX_NOT_ALLOWED vão para failed em vez de lançar erro. Qualquer outro erro (autenticação, rate limit, rede) continua sendo lançado. Veja Excluir objetos.

Copiando, movendo e renomeando

Ambos rodam no servidor, sem baixar o arquivo.

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

Campo de destino	Tipo	Descrição
`name`	`string`	Obrigatório. Nome sem extensão: o destino mantém a extensão da origem.
`prefix`	`string`	Prefixo de destino.
`private`	`boolean`	Visibilidade do destino.
`security_hash`	`boolean`	Acrescenta `_<hash>` ao nome.
`expire`	`string \| null`	Se omitido, mantém a expiração da origem; `null` a remove.

Opção	Aceita por	Descrição
`overwrite`	`copy()`, `move()`	`true` substitui um objeto existente no destino.
`move`	`copy()`	`true` remove a origem assim que a cópia é bem-sucedida (o mesmo que chamar `move()`).

O resultado tem id, private, url, expires_at, size, source, moved e replaced. Veja Copiar objeto.

update(), delete(), copy() e move() são escritas: elas têm uma única tentativa e nunca são repetidas. Veja Política de novas tentativas.

Serviços

Runtimes

Plataforma

Solução de Problemas

CLI

SDKs

Changelog

Listagem

Detalhes do objeto

Links de download

Atualizando objetos

Excluindo

Copiando, movendo e renomeando

​Listagem

​Detalhes do objeto

​Links de download

​Atualizando objetos

​Excluindo

​Copiando, movendo e renomeando

Listagem

Detalhes do objeto

Links de download

Atualizando objetos

Excluindo

Copiando, movendo e renomeando