Uploads

`put(file, options)`

put() envia um arquivo e retorna o novo objeto.

const { id, url } = await blob.put("./photo.png", {
    name: "photo",
    prefix: "avatars",
});

Entradas

Entrada	Ambiente	Observações
`string` (caminho de arquivo)	Apenas Node.js	Aberto com `fs.openAsBlob` e transmitido do disco, nunca lido inteiro para a memória. A extensão vem do nome base do caminho.
`Blob` / `File`	Node.js e navegadores	Um `File` fornece seu `name` (e sua extensão).
`Uint8Array` (incluindo `Buffer`)	Node.js e navegadores	Passe `filename` para definir a extensão.
`ArrayBuffer`	Node.js e navegadores	Passe `filename` para definir a extensão.

A extensão do objeto vem de filename, depois do nome base do caminho ou do nome do File. Bytes e um Blob simples não têm nome, então passe filename (por exemplo "data.json") ao enviá-los.

No Node.js, um caminho que não pode ser aberto lança um Error simples (Cannot open file: <path>, com o erro original em cause). No navegador, passar um caminho falha antes, com o erro da importação de node:fs. Use um File de um <input type="file"> em vez disso.

Opções

Opção	Tipo	Descrição
`name`	`string`	Nome do objeto sem extensão, correspondendo a `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$`, sem `..`, sem terminar em `-ex<digits>`. Obrigatório, a menos que um token de upload o fixe.
`prefix`	`string`	Caminho no estilo de pasta: até 8 segmentos de `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$`, 256 caracteres.
`private`	`boolean`	Padrão `false`. Objetos privados sempre recebem um hash de segurança e têm `url: null`.
`security_hash`	`boolean`	Acrescenta `_<hash>` ao nome.
`expire`	`string`	`"30"` (dias), `"30d"` ou `"168h"`; de 7 a 1825 dias (Enterprise a partir de 1 hora). A expiração passa a fazer parte do id.
`overwrite`	`boolean`	`false` falha com `OBJECT_ALREADY_EXISTS` quando o nome já está em uso. Apenas uploads simples.
`disposition`	`"inline"` \| `"attachment"`	`Content-Disposition` do objeto.
`auto_download`	`boolean`	Força um download (`application/octet-stream`).
`cache_control`	`string`	`immutable`, `max-age=60..31536000` ou `no-cache` (Enterprise).
`metadata`	`Record<string, string>`	Pro e Enterprise. Chaves `^[a-z0-9-]{1,64}$` (nunca `sq-*`), até 5 chaves e 512 bytes.
`checksum_sha256`	`string`	64 caracteres hexadecimais em minúsculas. Uma divergência falha com `CHECKSUM_MISMATCH` e nada é armazenado. Apenas uploads simples.
`filename`	`string`	Nome de arquivo cuja extensão se torna a extensão do objeto. Por padrão, o nome do `File` ou o nome base do caminho.
`mime_type`	`string`	Usado apenas para escolher a extensão quando `filename` não tem uma. O servidor deriva o `Content-Type`.

Veja Envio de objeto para todas as regras do lado do servidor.

Resultado

Campo	Tipo	Descrição
`id`	`string`	Id opaco do objeto. Armazene-o como está.
`private`	`boolean`	Se o objeto é privado.
`url`	`string \| null`	URL pública, ou `null` para um objeto privado (use `downloadUrl()`).
`expires_at`	`string`	Quando o objeto expira, se tiver uma expiração.
`size`	`number`	Tamanho em bytes.
`name`, `prefix`, `sha256`, `replaced`		Apenas uploads simples.
`parts`	`number`	Apenas uploads multipart: número de partes enviadas.

Uploads simples e multipart

put() escolhe o fluxo de upload a partir do tamanho do arquivo:

Tamanho do arquivo	Fluxo	Endpoint
Até 90 MiB (94.371.840 bytes), inclusive	Upload simples, uma requisição	Envio de objeto
Acima de 90 MiB, até 10 GiB	Upload multipart (em partes)	Início de upload em partes

Todo arquivo precisa ter pelo menos 512 bytes; arquivos menores falham com FILE_TOO_SMALL. Um max_size de uma regra ou de um token de upload, ou sua cota de armazenamento, pode reduzir o teto de 10 GiB.

Como um upload multipart funciona

O SDK inicia o upload, e o servidor responde com seus limites de partes (max_size, max_parts).
O arquivo é dividido em partes de min(max_size, max(16 MiB, ceil(size / max_parts))) bytes. Uma parte geralmente tem 16 MiB ou mais, mas é menor quando o max_size do servidor é menor.
As partes são enviadas 6 por vez, o limite do servidor para partes em andamento. Uma parte que falha é tentada novamente dentro de maxRetries.
Quando todas as partes chegam, o SDK conclui o upload.

Se uma parte falhar definitivamente, ou se a conclusão falhar, o SDK aguarda as partes ainda em andamento e então cancela o upload, para que nenhuma parte chegue depois do cancelamento. O erro original é lançado. Não há retomada: chame put() novamente.

Um upload multipart não verifica overwrite: false nem checksum_sha256. Ele sempre substitui um objeto existente com o mesmo nome.

Uma conta pode ter no máximo 32 uploads multipart abertos (compartilhados com o gateway S3); mais um falha com TOO_MANY_OPEN_UPLOADS. Como as partes vão 6 por vez por conta, execute um upload grande por vez.

Upload a partir do navegador

Nunca envie a chave de API para um navegador. Em vez disso, seu servidor gera um token de upload de curta duração e o navegador faz o upload com ele.

Servidor
Navegador

import { SquareCloudBlob } from "@squarecloud/blob";

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);

// e.g. inside your API route
const { token } = await blob.uploadTokens.create({
    prefix: "avatars/",
    security_hash: true,
    max_size: 5 * 1024 * 1024,
    allowed_extensions: ["png", "jpg"],
});
// send only `token` to the browser

import { SquareCloudBlob } from "@squarecloud/blob";

const upload = new SquareCloudBlob(token);
const { url } = await upload.put(input.files[0], { name: "avatar" });

Um cliente criado com um token só pode chamar put(), incluindo uploads multipart. Qualquer outro método falha com 403 UPLOAD_TOKEN_NOT_ALLOWED.

`uploadTokens.create(options)`

O token fixa todas as opções com que foi gerado.

Opção	Tipo	Descrição
`name`	`string`	Fixa o nome do objeto. Sem ele, o hash de segurança é sempre aplicado.
`prefix`	`string`	Fixa o prefixo.
`private`	`boolean`	Fixa a visibilidade.
`security_hash`	`boolean`	Acrescenta `_<hash>` ao nome.
`expire`	`string`	Expiração do objeto, como em `put()`.
`max_size`	`number`	Tamanho máximo do arquivo em bytes.
`allowed_extensions`	`string[]`	De 1 a 20 extensões.
`metadata`	`Record<string, string>`	Metadados aplicados ao objeto enviado.
`expires_in`	`number`	Duração do token em segundos, de 60 a 3600 (padrão 900).
`max_uses`	`number`	Uploads permitidos, de 1 a 100 (padrão 1). Depois disso, o token falha com `UPLOAD_TOKEN_USED`.

Retorna { token, expires_at, max_uses }. Veja Tokens de upload para as regras do lado do servidor.

uploadTokens.create() é uma escrita e tem uma única tentativa: nunca é repetido.

Serviços

Runtimes

Plataforma

Solução de Problemas

CLI

SDKs

Changelog

`put(file, options)`

Entradas

Opções

Resultado

Uploads simples e multipart

Como um upload multipart funciona

Upload a partir do navegador

`uploadTokens.create(options)`

​put(file, options)

​Entradas

​Opções

​Resultado

​Uploads simples e multipart

​Como um upload multipart funciona

​Upload a partir do navegador

​uploadTokens.create(options)

`put(file, options)`

Entradas

Opções

Resultado

Uploads simples e multipart

Como um upload multipart funciona

Upload a partir do navegador

`uploadTokens.create(options)`