Envois

`put(file, options)`

put() envoie un fichier et renvoie le nouvel objet.

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

Entrées

Entrée	Environnement	Remarques
`string` (chemin de fichier)	Node.js uniquement	Ouvert avec `fs.openAsBlob` et diffusé en flux depuis le disque, jamais chargé entièrement en mémoire. L’extension provient du nom de base du chemin.
`Blob` / `File`	Node.js et navigateurs	Un `File` fournit son `name` (et son extension).
`Uint8Array` (y compris `Buffer`)	Node.js et navigateurs	Passez `filename` pour définir l’extension.
`ArrayBuffer`	Node.js et navigateurs	Passez `filename` pour définir l’extension.

L’extension de l’objet provient de filename, puis du nom de base du chemin ou du nom du File. Les octets et un Blob simple n’ont pas de nom : passez donc filename (par exemple "data.json") lorsque vous les envoyez.

Dans Node.js, un chemin qui ne peut pas être ouvert lève une Error simple (Cannot open file: <path>, avec l’erreur d’origine dans cause). Dans un navigateur, passer un chemin échoue plus tôt, avec l’erreur de l’import de node:fs. Utilisez plutôt un File issu d’un <input type="file">.

Options

Option	Type	Description
`name`	`string`	Nom de l’objet sans extension, correspondant à `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$`, sans `..`, ne se terminant pas par `-ex<digits>`. Requis, sauf si un jeton d’envoi le fixe.
`prefix`	`string`	Chemin de type dossier : jusqu’à 8 segments de `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$`, 256 caractères.
`private`	`boolean`	`false` par défaut. Les objets privés reçoivent toujours un hash de sécurité et ont `url: null`.
`security_hash`	`boolean`	Ajoute `_<hash>` au nom.
`expire`	`string`	`"30"` (jours), `"30d"` ou `"168h"` ; de 7 à 1825 jours (Enterprise jusqu’à 1 heure). L’expiration fait partie de l’identifiant.
`overwrite`	`boolean`	`false` échoue avec `OBJECT_ALREADY_EXISTS` lorsque le nom est déjà pris. Envois simples uniquement.
`disposition`	`"inline"` \| `"attachment"`	`Content-Disposition` de l’objet.
`auto_download`	`boolean`	Force un téléchargement (`application/octet-stream`).
`cache_control`	`string`	`immutable`, `max-age=60..31536000` ou `no-cache` (Enterprise).
`metadata`	`Record<string, string>`	Pro et Enterprise. Clés `^[a-z0-9-]{1,64}$` (jamais `sq-*`), jusqu’à 5 clés et 512 octets.
`checksum_sha256`	`string`	64 caractères hexadécimaux en minuscules. Une non-correspondance échoue avec `CHECKSUM_MISMATCH` et rien n’est stocké. Envois simples uniquement.
`filename`	`string`	Nom de fichier dont l’extension devient celle de l’objet. Par défaut, le nom du `File` ou le nom de base du chemin.
`mime_type`	`string`	Utilisé uniquement pour choisir l’extension lorsque `filename` n’en a pas. Le serveur déduit le `Content-Type`.

Voir Object Post pour l’ensemble des règles côté serveur.

Résultat

Champ	Type	Description
`id`	`string`	Identifiant opaque de l’objet. Stockez-le tel quel.
`private`	`boolean`	Indique si l’objet est privé.
`url`	`string \| null`	URL publique, ou `null` pour un objet privé (utilisez `downloadUrl()`).
`expires_at`	`string`	Moment où l’objet expire, s’il a une expiration.
`size`	`number`	Taille en octets.
`name`, `prefix`, `sha256`, `replaced`		Envois simples uniquement.
`parts`	`number`	Envois multipart uniquement : nombre de parties envoyées.

Envois simples et multipart

put() choisit le mode d’envoi en fonction de la taille du fichier :

Taille du fichier	Mode	Endpoint
Jusqu’à 90 MiB (94 371 840 octets) inclus	Envoi simple, une seule requête	Object Post
Au-delà de 90 MiB, jusqu’à 10 GiB	Envoi multipart (chunked)	Chunked Init

Chaque fichier doit faire au moins 512 octets ; les fichiers plus petits échouent avec FILE_TOO_SMALL. Le max_size d’une règle ou d’un jeton d’envoi, ou votre quota de stockage, peut abaisser le plafond de 10 GiB.

Déroulement d’un envoi multipart

Le SDK démarre l’envoi, et le serveur répond avec ses limites de parties (max_size, max_parts).
Le fichier est découpé en parties de min(max_size, max(16 MiB, ceil(size / max_parts))) octets. Une partie fait généralement 16 MiB ou plus, mais elle est plus petite lorsque le max_size du serveur est plus petit.
Les parties sont envoyées 6 à la fois, la limite du serveur pour les parties en cours. Une partie échouée fait l’objet de nouvelles tentatives dans la limite de maxRetries.
Lorsque toutes les parties sont arrivées, le SDK finalise l’envoi.

Si une partie échoue définitivement, ou si la finalisation échoue, le SDK attend les parties encore en cours puis annule l’envoi, de sorte qu’aucune partie n’arrive après l’annulation. L’erreur d’origine est levée. Il n’y a pas de reprise : appelez à nouveau put().

Un envoi multipart ne vérifie ni overwrite: false ni checksum_sha256. Il remplace toujours un objet existant portant le même nom.

Un compte peut avoir au maximum 32 envois multipart ouverts (partagés avec la passerelle S3) ; un de plus échoue avec TOO_MANY_OPEN_UPLOADS. Comme les parties partent 6 à la fois par compte, effectuez un seul gros envoi à la fois.

Envoyer depuis le navigateur

N’envoyez jamais la clé API à un navigateur. À la place, votre serveur génère un jeton d’envoi de courte durée et le navigateur envoie avec celui-ci.

Serveur
Navigateur

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" });

Un client créé avec un jeton ne peut appeler que put(), envois multipart compris. Toute autre méthode échoue avec 403 UPLOAD_TOKEN_NOT_ALLOWED.

`uploadTokens.create(options)`

Le jeton fige toutes les options avec lesquelles il a été généré.

Option	Type	Description
`name`	`string`	Fixe le nom de l’objet. Sans lui, le hash de sécurité est toujours appliqué.
`prefix`	`string`	Fixe le préfixe.
`private`	`boolean`	Fixe la visibilité.
`security_hash`	`boolean`	Ajoute `_<hash>` au nom.
`expire`	`string`	Expiration de l’objet, comme dans `put()`.
`max_size`	`number`	Taille maximale du fichier en octets.
`allowed_extensions`	`string[]`	De 1 à 20 extensions.
`metadata`	`Record<string, string>`	Métadonnées appliquées à l’objet envoyé.
`expires_in`	`number`	Durée de vie du jeton en secondes, de 60 à 3600 (900 par défaut).
`max_uses`	`number`	Envois autorisés, de 1 à 100 (1 par défaut). Au-delà, le jeton échoue avec `UPLOAD_TOKEN_USED`.

Elle renvoie { token, expires_at, max_uses }. Voir Jetons d’envoi pour les règles côté serveur.

uploadTokens.create() est une écriture et a droit à une seule tentative : elle n’est jamais réessayée.

Services

Runtimes

Plateforme

Dépannage

CLI

SDKs

Changelog

`put(file, options)`

Entrées

Options

Résultat

Envois simples et multipart

Déroulement d’un envoi multipart

Envoyer depuis le navigateur

`uploadTokens.create(options)`

​put(file, options)

​Entrées

​Options

​Résultat

​Envois simples et multipart

​Déroulement d’un envoi multipart

​Envoyer depuis le navigateur

​uploadTokens.create(options)

`put(file, options)`

Entrées

Options

Résultat

Envois simples et multipart

Déroulement d’un envoi multipart

Envoyer depuis le navigateur

`uploadTokens.create(options)`