Démarrage rapide de l'API Blob Storage

Blob Storage conserve vos fichiers, sert les fichiers publics depuis un CDN et fournit des liens vers les fichiers privés. Cette page vous emmène d’une clé API à un fichier envoyé et à un lien de téléchargement, avec curl. Le stockage est inclus dans chaque plan : consultez Blob Storage pour les plans, les prix et la FAQ.

URL de base

Chaque endpoint de cette référence est relatif à :

https://blob.squarecloud.app/v1

Authentification

Blob Storage accepte les mêmes clés API que l’API Square Cloud, dans l’en-tête Authorization. La clé a besoin du scope blob:write pour envoyer et de blob:read pour lister et télécharger, et elle ne peut pas être restreinte à des applications précises. Créez-en une dans les paramètres de sécurité de votre compte et gardez-la dans une variable d’environnement :

export SQUARECLOUD_API_KEY="your-api-key"

Pour en savoir plus sur les scopes et les jetons d’envoi, consultez Authentification.

Envoyer un fichier

Object Post reçoit le fichier en multipart/form-data et son nom, sans extension, dans la query :

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'

{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}

Le fichier est public par défaut : url fonctionne immédiatement dans un navigateur ou une balise <img>. Conservez l’id tel quel, car toutes les autres routes l’utilisent. Une seule requête accepte des fichiers de 512 octets à 100 Mo. Les fichiers plus volumineux, jusqu’à 10 GiB, passent par l’envoi chunked ou par la passerelle S3.

Envoyer un fichier privé

Ajoutez private=true et le fichier n’a pas d’URL publique (url vaut null) :

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'

Télécharger un fichier

Un fichier public se télécharge depuis son url. Pour un fichier privé, Téléchargement d’objet signe un lien temporaire qui fonctionne sans identifiants et redirige vers lui, donc curl -L enregistre le fichier :

curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

Remplacez <id> par l’id de l’envoi. Ajoutez redirect=false pour obtenir le lien en JSON et le transmettre à quelqu’un d’autre. Pour des liens révocables ou protégés par un mot de passe, créez un lien de partage.

Lister et supprimer des fichiers

Liste d’objets renvoie vos fichiers page par page :

curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

Suppression d’objets supprime un fichier, ou jusqu’à 100 en une seule requête :

curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'

En cas d’échec

Les erreurs arrivent sous la forme { "status": "error", "code": "..." }. Celles que vous risquez de rencontrer en premier :

Code	HTTP	Solution
`ACCESS_DENIED`	401	La clé est manquante ou n’est pas reconnue. Vérifiez l’en-tête `Authorization`.
`PERMISSION_DENIED`	401	Le compte n’a pas de plan actif, il ne peut donc pas envoyer de fichiers.
`MISSING_SCOPE`	403	La clé n’a pas `blob:write` ou `blob:read`. Créez une clé avec ce scope.
`RESOURCE_NOT_ALLOWED`	403	La clé est restreinte à des applications. Utilisez une clé sans cette restriction.
`FILE_TOO_LARGE`	413	Le fichier dépasse 100 Mo. Utilisez l’envoi chunked.

Tous les codes figurent dans Erreurs.

Étapes suivantes

SDK Blob

Envoyez et gérez des fichiers depuis JavaScript, avec les envois chunked gérés pour vous.

Compatibilité S3

Utilisez aws-cli, boto3, rclone ou n’importe quel SDK AWS.

Liens et partage

Liens temporaires, liens de partage et quand utiliser chacun.

Envoyer depuis le navigateur

Laissez les visiteurs envoyer des fichiers sans exposer votre clé API.

Premiers pas

Objets

Uploads par morceaux

Compte

Liens de partage

S3

Démarrage rapide de l'API Blob Storage

URL de base

Authentification

Envoyer un fichier

Envoyer un fichier privé

Télécharger un fichier

Lister et supprimer des fichiers

En cas d’échec

Étapes suivantes

SDK Blob

Compatibilité S3

Liens et partage

Envoyer depuis le navigateur

​URL de base

​Authentification

​Envoyer un fichier

​Envoyer un fichier privé

​Télécharger un fichier

​Lister et supprimer des fichiers

​En cas d’échec

​Étapes suivantes

SDK Blob

Compatibilité S3

Liens et partage

Envoyer depuis le navigateur

URL de base

Authentification

Envoyer un fichier

Envoyer un fichier privé

Télécharger un fichier

Lister et supprimer des fichiers

En cas d’échec

Étapes suivantes