Última actualización: 11 de septiembre

Exporta archivos a Supabase con cURL

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos ·

Supabase es una potente alternativa de código abierto a Firebase que ofrece a los desarrolladores una sólida plataforma de backend como servicio. Una de sus funciones más destacadas es el almacenamiento en la nube, que te permite guardar y gestionar archivos sin esfuerzo. En este DevTip veremos cómo puedes agilizar la exportación de archivos a los buckets de almacenamiento de Supabase con comandos cURL, mejorando tu gestión de datos y tus flujos de trabajo de automatización.

Configura tu cuenta de Supabase y crea buckets

Primero, regístrate para obtener una cuenta de Supabase si aún no lo has hecho. Una vez que hayas iniciado sesión, ve a la sección «Storage» y crea un nuevo bucket. Asegúrate de establecer los permisos adecuados para tu bucket, lo que normalmente permite que los usuarios autenticados suban archivos.

Al crear un bucket, puedes elegir entre políticas de acceso públicas y privadas:

Público: cualquier persona con la URL puede acceder a los archivos.
Privado: los archivos requieren autenticación para acceder a ellos.

Para datos sensibles, usa siempre buckets privados con los controles de acceso adecuados.

Descarga y configura cURL

La mayoría de los sistemas incluyen cURL preinstalado. Los ejemplos de transferencia requieren cURL 7.76.0 o posterior para --fail-with-body. Verifica tu instalación ejecutando:

curl --version

Si cURL no está instalado, puedes instalarlo fácilmente:

macOS: usa Homebrew

brew install curl

Linux (Debian/Ubuntu):

sudo apt-get update && sudo apt-get install curl

Windows: usa Windows Package Manager (winget) o descárgalo desde el sitio web oficial:

winget install --id cURL.cURL --exact

Comprende los fundamentos de cURL

cURL es una herramienta de línea de comandos para transferir datos mediante varios protocolos. Sintaxis básica:

curl -X METHOD [options] URL

Entre los métodos comunes están GET, POST y PUT. Para Supabase, usaremos principalmente POST para subir archivos.

Exporta archivos a Supabase usando cURL

Para subir archivos a Supabase, necesitarás:

El ID de tu proyecto de Supabase (que se encuentra en la URL del proyecto)
Tu clave anon de Supabase (que se encuentra en Project Settings → API)
Un token JWT para la autenticación (que se obtiene tras el inicio de sesión del usuario)
El nombre de tu bucket

Esta es la estructura correcta del comando cURL para subir un archivo:

curl --fail-with-body --show-error -X POST "https://YOUR_PROJECT_ID.supabase.co/storage/v1/object/YOUR_BUCKET_NAME/file.txt" \
  -H "apikey: YOUR_SUPABASE_ANON_KEY" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary "@file.txt"

Reemplaza YOUR_PROJECT_ID, YOUR_BUCKET_NAME, YOUR_SUPABASE_ANON_KEY y YOUR_JWT_TOKEN por tus valores reales. Asegúrate de especificar el Content-Type correcto para tu archivo. Codifica en porcentaje cada segmento de la ruta del bucket o del objeto si contiene espacios o caracteres reservados de URL, conservando / entre las carpetas de objetos. Las políticas de subida deben permitir inserciones para el usuario autenticado.

Gestiona entradas: agrega, sobrescribe y actualiza archivos

El POST anterior crea un objeto nuevo y rechaza una ruta existente. Para sobrescribir un objeto de forma intencionada, agrega -H "x-upsert: true" a ese comando; el usuario también necesita permisos de selección y actualización. Consulta el comportamiento de subida estándar de Supabase. Usa rutas únicas cuando haya que conservar el contenido anterior. Una solicitud HEAD puede comprobar la existencia, pero una comprobación de existencia por separado no puede evitar condiciones de carrera con otro proceso de escritura:

curl --fail-with-body --show-error --head -o /dev/null -w '%{http_code}\n' \
  "https://YOUR_PROJECT_ID.supabase.co/storage/v1/object/YOUR_BUCKET_NAME/file.txt" \
  -H "apikey: YOUR_SUPABASE_ANON_KEY" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Para un objeto accesible, esto imprime 200. Los objetos inexistentes o los permisos insuficientes producen un estado de error y un código de salida de curl distinto de cero. --head le indica correctamente a curl que no espere ningún cuerpo.

Comprende los límites de tamaño de archivo

El tamaño máximo de archivo depende de tu plan, del límite global del proyecto y de cualquier límite de bucket más estricto. Revisa el panel y la documentación actual de Supabase sobre límites de archivos. Para transferencias más grandes, usa las subidas reanudables con el protocolo tus de Supabase. Los comandos --data-binary @file de esta guía almacenan el archivo en memoria y no se reanudan.

Automatiza la exportación de archivos en un flujo de trabajo diario

Automatizar las subidas de archivos puede agilizar considerablemente tu flujo de trabajo. Este es un ejemplo completo de script de bash:

#!/bin/bash
set -u

# Supply credentials through the environment, with a current user access token.
: "${PROJECT_ID:?Set PROJECT_ID}" "${ANON_KEY:?Set ANON_KEY}" "${JWT_TOKEN:?Set a current user JWT}"
BUCKET_NAME="your-bucket"
FILE_PATH="/path/to/daily-report.csv"
FILE_NAME="reports/daily-report-$(date +%Y-%m-%d).csv"

# Upload command with retry logic
if curl --fail-with-body --show-error -X POST \
  "https://$PROJECT_ID.supabase.co/storage/v1/object/$BUCKET_NAME/$FILE_NAME" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: text/csv" \
  --retry 3 --retry-delay 5 \
  --data-binary "@$FILE_PATH"; then
  echo "File uploaded successfully to $BUCKET_NAME/$FILE_NAME"
else
  echo "Error uploading file"
  exit 1
fi

Para ejecuciones desatendidas, usa un wrapper de credenciales que obtenga o renueve el token de acceso del usuario y exporte las variables necesarias antes de invocar este script. Un JWT de inicio de sesión pegado a mano caduca y no es una credencial permanente para cron. Mantén las políticas de Storage del usuario limitadas al bucket y al prefijo necesarios; no recurras a una clave de rol de servicio solo para evitar la renovación del token.

Después de configurar ese wrapper, prográmalo con cron:

crontab -e

Agrega la siguiente línea para ejecutar el script todos los días a medianoche:

0 0 * * * /path/to/your/credential-wrapper.sh

Haz que los scripts sean ejecutables y usa rutas absolutas. Al volver a ejecutar una subida diaria se apunta al mismo nombre de objeto y se rechaza, a menos que actives explícitamente upsert. Un reintento tras una respuesta perdida también puede encontrarse con un objeto creado por el primer intento; verifícalo antes de decidir sobrescribirlo.

Resuelve problemas comunes

Estos son algunos errores comunes que podrías encontrar y cómo resolverlos:

Errores de autenticación (401 no autorizado)

{ "statusCode": "401", "error": "Unauthorized", "message": "Invalid JWT" }

Solución: asegúrate de que tu token JWT sea válido y no haya caducado. Para hacer pruebas, puedes generar un token nuevo a través de la API de Supabase Auth.

Errores de archivo duplicado

{ "statusCode": "409", "error": "Duplicate", "message": "The resource already exists" }

Solución: usa un nombre de archivo único o implementa lógica para gestionar los archivos existentes.

Las versiones de Storage pueden reportar objetos duplicados como 400 Asset Already Exists o 409 Duplicate; gestiona ambos casos en lugar de tratar cualquiera de esos estados como un éxito.

Límites de tamaño de archivo (413 carga útil demasiado grande)

{
  "statusCode": "413",
  "error": "PayloadTooLarge",
  "message": "The file size exceeds the maximum limit"
}

Solución: asegúrate de que tu archivo esté dentro de los límites de tamaño de tu plan de Supabase.

Permiso denegado

Solución: revisa los permisos del bucket en Supabase y asegúrate de que tu token JWT tenga los permisos necesarios.

Aplica las mejores prácticas de seguridad

Cuando trabajes con Supabase y cURL:

Guarda las claves de API y los tokens en variables de entorno; nunca los escribas directamente en el código.
Usa permisos de bucket adecuados (buckets privados para datos sensibles).
Implementa un manejo de errores y un registro de logs adecuados.
Rota tus claves de API con regularidad si existe la posibilidad de que se vean comprometidas.
Usa HTTPS en todas las solicitudes (algo que Supabase exige).

Optimiza los comandos cURL

Usa variables de entorno para los datos sensibles:

export SUPABASE_URL="https://YOUR_PROJECT_ID.supabase.co"
export SUPABASE_ANON_KEY="YOUR_ANON_KEY"
export SUPABASE_JWT="YOUR_JWT_TOKEN"

curl --fail-with-body --show-error -X POST "$SUPABASE_URL/storage/v1/object/YOUR_BUCKET_NAME/file.txt" \
-H "apikey: $SUPABASE_ANON_KEY" \
-H "Authorization: Bearer $SUPABASE_JWT" \
-H "Content-Type: text/plain" \
--data-binary "@file.txt"

Especifica siempre el encabezado Content-Type correcto para tu tipo de archivo.

Implementa reintentos para mayor fiabilidad de la red:

curl --fail-with-body --show-error --retry 3 --retry-delay 5 -X POST "https://YOUR_PROJECT_ID.supabase.co/storage/v1/object/YOUR_BUCKET_NAME/file.txt" \
-H "apikey: $SUPABASE_ANON_KEY" \
-H "Authorization: Bearer $SUPABASE_JWT" \
-H "Content-Type: text/plain" \
--data-binary "@file.txt"

Usa --fail-with-body para que cURL devuelva un código de salida distinto de cero ante errores HTTP y conserve el cuerpo de la respuesta para el diagnóstico.
Agrega la opción -s (modo silencioso) para suprimir los medidores de progreso y obtener logs más limpios.

Conclusión

Usar cURL para exportar archivos a Supabase ofrece un enfoque potente y flexible para la gestión y la automatización de archivos. Con los endpoints de API correctos, los encabezados de autenticación adecuados y las mejores prácticas, puedes crear flujos de trabajo de exportación de archivos sólidos que se integran a la perfección con tus aplicaciones.

Si buscas soluciones de exportación de archivos aún más ágiles, Transloadit ofrece un completo servicio de exportación de archivos compatible con varios proveedores de almacenamiento.