Blob Object Post

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

string

requis

La clé d’API de votre compte. Vous pouvez la trouver dans les paramètres de votre compte.

Object Post envoie un seul fichier vers Square Cloud Blob Storage et renvoie une URL servie par le CDN que vous pouvez intégrer ou partager directement, sans avoir à provisionner un bucket ni à gérer les ACL vous-même. Il sert de base aux pièces jointes, aux exports générés et aux médias envoyés par les utilisateurs pour les applications hébergées sur la plateforme. L’extension stockée provient du nom de fichier que vous envoyez dans la partie multipart (avec repli sur le type MIME déclaré, puis sur bin), donc envoyez toujours un vrai nom de fichier. Pratiquement n’importe quel type de fichier est accepté ; seuls les exécutables et les installateurs sont refusés. Les objets peuvent recevoir une expiration automatique entre 7 et 1825 jours (5 ans), après quoi ils ne sont plus servis. Une seule requête accepte les fichiers de 512 octets à 100 Mo, le corps le plus volumineux accepté par la périphérie de Cloudflare. Les fichiers plus gros, jusqu’à 1 GiB, passent par le flux d’upload chunked. Une fois un fichier envoyé, parcourez-le avec Liste d’objets, supprimez-le avec Suppression d’objets, ou suivez son utilisation par rapport au quota de votre plan avec Métriques.

file

requis

Utilisez FormData (multipart/form-data). Un seul fichier par requête.
Envoyez un vrai nom de fichier : l’extension stockée en est dérivée.

string

requis

Une chaîne représentant le nom du fichier. (sans extension)
Doit respecter le motif a à z, A à Z, 0 à 9 et _. (3 à 32 caractères)

string

Une chaîne représentant le préfixe du fichier.
Doit respecter le motif a à z, A à Z, 0 à 9 et _. (3 à 32 caractères)

number

Un nombre indiquant la période d’expiration du fichier, comprise entre 7 et 1825 jours (5 ans).

boolean

Définissez sur true si un hash de sécurité est requis.

boolean

Définissez sur true si le fichier doit être configuré pour un téléchargement automatique.

Limites de débit et concurrence

L’upload nécessite un plan payant.

Un compte peut avoir au plus 4 uploads en cours simultanément. Démarrer un autre upload alors que 4 sont encore en cours renvoie TOO_MANY_CONCURRENT_UPLOADS (429).
Les plans Hobby et Standard sont en plus limités à 1 upload par seconde (RATE_LIMITED, 429). Les plans Pro et Enterprise sont exemptés de la limite par seconde.

Pour des raisons de sécurité, les formats qu’un navigateur rend en ligne (.html, .svg, .xml, .xhtml et similaires) sont toujours délivrés en tant que téléchargements (servis en application/octet-stream) au lieu d’être rendus. Définir auto_download=true applique le même comportement de téléchargement forcé à n’importe quel type de fichier.

Types de fichiers

Pratiquement n’importe quelle extension est acceptée, y compris les formats sans type MIME enregistré (.bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy et ainsi de suite). Il n’y a plus de liste blanche de types MIME.

L’extension stockée est dérivée du nom de fichier envoyé dans la partie multipart, avec repli sur le type MIME déclaré, puis sur bin.
Les suffixes de compression composés sont préservés : reads.fastq.gz est stocké en .fastq.gz, pas en .gz.
Le Content-Type servi est dérivé côté serveur à partir de l’extension. Les formats inconnus sont servis en application/octet-stream, ils sont donc téléchargés au lieu d’être rendus.
Les exécutables et les installateurs sont refusés avec BLOCKED_FILE_TYPE : exe, msi, dll, bat, cmd, com, scr, cpl, pif, hta, vbs, vbe, jse, wsf, wsh, msc, reg, lnk, sys, drv, ps1, apk, xpi.

Réponse

string

Indique si l’appel a réussi. “success” en cas de succès, “error” sinon.

object

Afficher Afficher l'objet

string

L’ID du fichier uploadé.

string

Le nom du fichier uploadé.

string

Le préfixe sous lequel le fichier a été stocké (renvoyé à partir du paramètre prefix ; omis lorsqu’aucun n’a été envoyé).

number

La taille du fichier uploadé, en octets.

string

L’URL CDN publique du fichier uploadé : https://public-blob.squarecloud.dev/<user_id>/<key>, où la clé est [prefix/]name[_hash][-exN].ext (les suffixes de hash et d’expiration n’apparaissent que s’ils sont utilisés ; l’extension est dérivée du nom de fichier envoyé).

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Dépannage

Lié à l’objet

// The provided object name is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_NAME"
}

// The provided object prefix is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_PREFIX"
}

// The provided expiration value for the object is invalid.
// Must be a number ranging from 7 to 1825. (value in days).
{
    "status": "error",
    "code": "INVALID_OBJECT_EXPIRE"
}

// The provided security hash boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_OBJECT_SECURITY_HASH"
}

// The provided auto-download boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
}

Lié au fichier

Une seule requête accepte jusqu’à 100 Mo. Pour les fichiers jusqu’à 1 GiB, utilisez le flux d’upload chunked.

// The provided file is invalid.
{
    "status": "error",
    "code": "INVALID_FILE"
}

// The file extension is malformed or too long.
{
    "status": "error",
    "code": "INVALID_FILE_TYPE"
}

// Executable/installer extensions (exe, msi, bat, apk, ...) are not accepted.
{
    "status": "error",
    "code": "BLOCKED_FILE_TYPE"
}

// The file size is too small (< 512 bytes).
{
    "status": "error",
    "code": "FILE_TOO_SMALL"
}

Non autorisé

// The API key is missing or invalid. Set a valid key in the Authorization header.
{
    "status": "error",
    "code": "ACCESS_DENIED"
}

// The account has no active paid plan. Uploading to Blob Storage requires a paid plan.
{
    "status": "error",
    "code": "PERMISSION_DENIED"
}

Quota de stockage dépassé

// You have exceeded your storage quota. Delete some files or upgrade your plan.
{
    "status": "error",
    "code": "STORAGE_QUOTA_EXCEEDED"
}

Type de contenu invalide

// This route only accepts multipart/form-data requests with exactly one file.
{
    "status": "error",
    "code": "INVALID_CONTENT_TYPE"
}

Charge utile trop volumineuse

Une seule requête accepte jusqu’à 100 Mo. Pour les fichiers jusqu’à 1 GiB, utilisez le flux d’upload chunked.

// A single request accepts up to 100 MB. Use /v1/objects/chunked for files up to 1 GiB.
{
    "status": "error",
    "code": "FILE_TOO_LARGE"
}

Débit limité

// Per-second upload limit reached (Hobby/Standard: max 1 upload per second).
{
    "status": "error",
    "code": "RATE_LIMITED"
}

// Too many simultaneous uploads (max 4 in progress at a time per account).
{
    "status": "error",
    "code": "TOO_MANY_CONCURRENT_UPLOADS"
}

Échec de l’upload

// Failed to upload object to storage. Please try again later.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

Suppression d'objetsCette documentation fournit un aperçu complet de l'endpoint DELETE /v1/objects de l'API SquareCloud Blob.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Endpoints Blob

Upload par Morceaux

Limites de débit et concurrence

Types de fichiers

Réponse

Dépannage

Lié à l’objet

Lié au fichier

Non autorisé

Quota de stockage dépassé

Type de contenu invalide

Charge utile trop volumineuse

Débit limité

Échec de l’upload

​Limites de débit et concurrence

​Types de fichiers

​Réponse

​Dépannage

​Lié à l’objet

​Lié au fichier

​Non autorisé

​Quota de stockage dépassé

​Type de contenu invalide

​Charge utile trop volumineuse

​Débit limité

​Échec de l’upload

Limites de débit et concurrence

Types de fichiers

Réponse

Dépannage

Lié à l’objet

Lié au fichier

Non autorisé

Quota de stockage dépassé

Type de contenu invalide

Charge utile trop volumineuse

Débit limité

Échec de l’upload