Zaroz
Almacenamiento de objetos

Almacenamiento de objetos desde la API

La guía rápida de almacenamiento de objetos muestra cómo hablar con un bucket con un cliente S3. Esta página es la parte de gestión: crear el bucket y sus claves y leer el uso, todo con la API de Zaroz en lugar de la consola. Los archivos en sí siguen yendo por el endpoint S3 (o los enlaces firmados de abajo). Los ejemplos usan el ayudante de Usar la API de Zaroz.

El almacenamiento de objetos puede faltar en algunos despliegues: comprueba object_storage_buckets en qué ofrece el despliegue. Todo se direcciona con el id de suscripción de tu plan de almacenamiento de objetos, y escribir requiere la autoridad para comprar por la organización (Owner o Admin).

Crear el bucket

Un bucket por suscripción. cap_bytes es el límite de almacenamiento (de 1 GiB a 100 TiB, 100 GiB por defecto); region_id toma por defecto la región del plan.

curl

TerminalCode
curl -sS -X POST "$ZAROZ_API/subscriptions/$SUBSCRIPTION/bucket" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"label": "site-assets", "cap_bytes": 107374182400}'
JSONCode
{
  "data": {
    "id": "…", "label": "site-assets",
    "endpoint": "https://…", "bucket_name": "zb-3f2a…", "s3_region": "us-east-1",
    "addressing_style": "path",
    "cap_bytes": 107374182400, "stored_bytes": null,
    "public_read": false, "public_url": null, "access": "open", "purge_at": null
  }
}

TypeScript

TypeScriptCode
import { call } from "./zaroz";

const b = await call("POST", `/subscriptions/${SUB}/bucket`, { label: "site-assets", cap_bytes: 100 * 1024 ** 3 });
const { endpoint, bucket_name } = b.body.data;
console.log(endpoint, bucket_name); // los dos valores que necesita tu cliente S3

Python

Code
from zaroz import call

_, b = call("POST", f"/subscriptions/{SUB}/bucket", {"label": "site-assets", "cap_bytes": 100 * 1024**3})
print(b["data"]["endpoint"], b["data"]["bucket_name"])   # los dos valores que necesita tu cliente S3

Un segundo bucket responde 409, y una suscripción inactiva 422. bucket_name es el nombre real para las peticiones S3 (no tu etiqueta). access indica lo que permite ahora el plano de datos: open, read_only (por encima del límite), suspended o deleted. GET /subscriptions/{id}/bucket devuelve el mismo objeto (404 si aún no hay bucket).

Cambiar el límite, la etiqueta o la lectura pública

TerminalCode
curl -sS -X PATCH "$ZAROZ_API/subscriptions/$SUBSCRIPTION/bucket" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"public_read": true, "cap_bytes": 214748364800}'
TypeScriptCode
await call("PATCH", `/subscriptions/${SUB}/bucket`, { public_read: true, cap_bytes: 200 * 1024 ** 3 });
Code
call("PATCH", f"/subscriptions/{SUB}/bucket", {"public_read": True, "cap_bytes": 200 * 1024**3})

Los campos ausentes no cambian. Un cambio de límite y uno de lectura pública llegan al plano de datos al instante. Con public_read activado, cualquiera puede descargar un objeto en public_url/KEY sin clave (listar y escribir siguen necesitándola); desactívalo para cerrarlo. No se permite cuando el bucket está programado para borrarse (422).

Claves de acceso

Una clave es read_only o read_write y solo funciona en este bucket. Como máximo 20 claves activas por bucket (429 más allá).

curl

TerminalCode
curl -sS -X POST "$ZAROZ_API/subscriptions/$SUBSCRIPTION/bucket/keys" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "ci-upload", "scope": "read_write"}'
# {"data": {"id": "…", "access_key_id": "…", "scope": "read_write", "name": "ci-upload"}, "secret_access_key": "…"}

curl -sS "$ZAROZ_API/subscriptions/$SUBSCRIPTION/bucket/keys" -H "$AUTH"
curl -sS -X DELETE "$ZAROZ_API/subscriptions/$SUBSCRIPTION/bucket/keys/$KEY" -H "$AUTH"

TypeScript

TypeScriptCode
const k = await call("POST", `/subscriptions/${SUB}/bucket/keys`, { name: "ci-upload", scope: "read_write" });
console.log(k.body.data.access_key_id, k.body.secret_access_key); // el secreto se muestra UNA vez
await call("DELETE", `/subscriptions/${SUB}/bucket/keys/${k.body.data.id}`); // revocar

Python

Code
_, k = call("POST", f"/subscriptions/{SUB}/bucket/keys", {"name": "ci-upload", "scope": "read_write"})
print(k["data"]["access_key_id"], k["secret_access_key"])   # el secreto se muestra UNA vez
call("DELETE", f"/subscriptions/{SUB}/bucket/keys/{k['data']['id']}")   # revocar

El secreto se devuelve solo en esta respuesta; listar nunca lo muestra y Zaroz no puede volver a mostrarlo. Usa access_key_id y secret_access_key como AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY en la guía rápida. Revocar detiene esa clave al instante.

Uso y factura

TerminalCode
curl -sS "$ZAROZ_API/subscriptions/$SUBSCRIPTION/bucket/usage" -H "$AUTH"
curl -sS -G "$ZAROZ_API/subscriptions/$SUBSCRIPTION/bucket/usage" -H "$AUTH" \
  --data-urlencode "from=2026-10-01T00:00:00Z" --data-urlencode "to=2026-10-15T00:00:00Z"
TypeScriptCode
const u = await call("GET", `/subscriptions/${SUB}/bucket/usage`);
console.log(u.body.data);
Code
_, u = call("GET", f"/subscriptions/{SUB}/bucket/usage")
print(u["data"])

Sin ventana obtienes lo que va de mes (como máximo 93 días): muestras por hora de bytes almacenados y tráfico, el tamaño medio almacenado en GiB-mes y los bytes enviados, que son los dos contadores facturados. Subir es gratis.

Explorar y firmar transferencias

Si no quieres usar ninguna clave (por ejemplo un backend web que entrega enlaces a navegadores), pide a la API que firme un enlace por objeto. Listar es solo metadatos y no se factura.

curl

TerminalCode
O=/subscriptions/$SUBSCRIPTION/bucket/objects
curl -sS -G "$ZAROZ_API$O" -H "$AUTH" --data-urlencode "prefix=photos/" --data-urlencode "limit=100"

curl -sS -X POST "$ZAROZ_API$O/upload" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"key": "photos/a.jpg", "size_bytes": 482344, "content_type": "image/jpeg"}'
# hasta 64 MiB: un PUT firmado de exactamente esos bytes. Más grande (hasta 625 GiB): subida multiparte.

curl -sS -X POST "$ZAROZ_API$O/download" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"key": "photos/a.jpg", "save_as": "holiday.jpg"}'
# un GET firmado de 15 minutos

TypeScript

TypeScriptCode
const O = `/subscriptions/${SUB}/bucket/objects`;
const start = await call("POST", `${O}/upload`, { key: "photos/a.jpg", size_bytes: file.byteLength, content_type: "image/jpeg" });
// Para una subida con un solo PUT, envía exactamente size_bytes bytes a la URL firmada de start.body.data

const dl = await call("POST", `${O}/download`, { key: "photos/a.jpg" });
console.log(dl.body.data); // la URL firmada, válida 15 minutos

Python

Code
O = f"/subscriptions/{SUB}/bucket/objects"
_, start = call("POST", f"{O}/upload", {"key": "photos/a.jpg", "size_bytes": len(data), "content_type": "image/jpeg"})
# Para una subida con un solo PUT, envía exactamente size_bytes bytes a la URL firmada de start["data"]

_, dl = call("POST", f"{O}/download", {"key": "photos/a.jpg"})
print(dl["data"])   # la URL firmada, válida 15 minutos

Las descargas van directas al endpoint de almacenamiento y se facturan como salida igual que cualquier cliente S3, vistas previas incluidas. Las subidas grandes son multiparte: POST .../objects/upload/parts firma cada parte, .../upload/complete termina y .../upload/abort cancela. POST .../objects/delete borra objetos y POST .../objects/folders crea un marcador de carpeta. Las subidas se rechazan mientras el bucket supera su límite o está suspendido. Para un uso intenso o repetido, una clave de acceso y un cliente S3 son más simples que firmar cada objeto.

Borrar el bucket

TerminalCode
curl -sS -X DELETE "$ZAROZ_API/subscriptions/$SUBSCRIPTION/bucket" -H "$AUTH"      # 204
TypeScriptCode
await call("DELETE", `/subscriptions/${SUB}/bucket`);
Code
call("DELETE", f"/subscriptions/{SUB}/bucket")

Las claves dejan de funcionar de inmediato y el hueco se libera, pero los datos permanecen un periodo de recuperación de siete días (purge_at muestra la fecha) antes de eliminarse para siempre.

Last modified on
Inicio rápido del almacenamiento de objetosOrganizaciones, proyectos e instancias de servicio