Almacenamiento en la Nube

Acceder a almacenamiento de objetos compatible con S3. Cargar, descargar, listar y gestionar archivos con soporte de URL prefirmadas.

Para configuración de almacenamiento, consulte Almacenamiento en la Nube.

Carga

local cloudstorage = require("cloudstorage")

Adquirir Almacenamiento

Obtener un recurso de almacenamiento en la nube por ID de registro:

local storage, err = cloudstorage.get("app.infra:files")
if err then
    return nil, err
end

storage:upload_object("data/file.txt", "content")
storage:release()

Devuelve: Storage, error

Cargar Objetos

Cargar contenido desde string o archivo:

local storage = cloudstorage.get("app.infra:files")

-- Cargar contenido string
local ok, err = storage:upload_object("reports/daily.json", json.encode({
    date = "2024-01-15",
    total = 1234
}))

-- Cargar desde archivo
local fs = require("fs")
local vol = fs.get("app:data")
local file = vol:open("/large-file.bin", "r")

storage:upload_object("backups/large-file.bin", file)
file:close()

storage:release()

Devuelve: boolean, error

Opciones de Carga

Adjunta metadatos o protege la escritura con una tabla de opciones:

storage:upload_object("reports/daily.json", body, {
    content_type = "application/json",
    cache_control = "max-age=3600",
    metadata = { owner = "team-a", run_id = "1234" },  -- almacenado como x-amz-meta-*
    only_if_absent = true                              -- falla si la clave ya existe
})

Una escritura condicional que falla su precondición devuelve un error precondition_failed.

Descargar Objetos

Descargar un objeto a un escritor de archivo:

local storage = cloudstorage.get("app.infra:files")
local fs = require("fs")
local vol = fs.get("app:temp")

local file = vol:open("/downloaded.json", "w")
local ok, err = storage:download_object("reports/daily.json", file)
file:close()

-- Descargar contenido parcial (primeros 1KB)
local partial = vol:open("/partial.bin", "w")
storage:download_object("backups/large-file.bin", partial, {
    range = "bytes=0-1023"
})
partial:close()

storage:release()

Devuelve: boolean, error

Una precondición fallida (if_match/if_none_match) devuelve un error precondition_failed.

Listar Objetos

Listar objetos con filtro de prefijo opcional:

local storage = cloudstorage.get("app.infra:files")

local result, err = storage:list_objects({
    prefix = "reports/2024/",
    max_keys = 100
})

for _, obj in ipairs(result.objects) do
    print(obj.key, obj.size, obj.etag)
end

-- Paginar a traves de resultados grandes
local token = nil
repeat
    local result = storage:list_objects({
        prefix = "logs/",
        max_keys = 1000,
        continuation_token = token
    })
    for _, obj in ipairs(result.objects) do
        process(obj)
    end
    token = result.next_continuation_token
until not result.is_truncated

storage:release()

Devuelve: table, error

El resultado contiene objects, is_truncated, next_continuation_token. Cada objeto tiene key, size, etag, storage_class, y opcionalmente last_modified, version_id y owner.

Metadatos de Objeto

Obtén los metadatos de un solo objeto sin descargar su cuerpo:

local storage = cloudstorage.get("app.infra:files")

local meta, err = storage:head_object("reports/daily.json")
if err then
    return nil, err
end

print(meta.size, meta.etag, meta.content_type)
for k, v in pairs(meta.metadata) do
    print("meta", k, v)
end

storage:release()

Devuelve: table, error

Campos del resultado:

Un objeto inexistente devuelve un error not_found.

Eliminar Objetos

Eliminar multiples objetos:

local storage = cloudstorage.get("app.infra:files")

storage:delete_objects({
    "temp/file1.txt",
    "temp/file2.txt",
    "temp/file3.txt"
})

storage:release()

Devuelve: boolean, error

URLs de Descarga

Crear una URL temporal que permite descargar un objeto sin credenciales. Util para compartir archivos con usuarios externos o servir contenido a traves de su aplicación.

local storage, err = cloudstorage.get("app.infra:files")
if err then
    return nil, err
end

local url, err = storage:presigned_get_url("reports/quarterly.pdf", {
    expiration = 3600
})

storage:release()

if err then
    return nil, err
end

-- Devolver URL al cliente para descarga directa
return {download_url = url}

Devuelve: string, error

URLs de Carga

Crear una URL temporal que permite cargar un objeto sin credenciales. Permite a los clientes cargar archivos directamente al almacenamiento sin pasar por su servidor.

local storage, err = cloudstorage.get("app.infra:files")
if err then
    return nil, err
end

local url, err = storage:presigned_put_url("uploads/user-123/avatar.jpg", {
    expiration = 600,
    content_type = "image/jpeg",
    content_length = 1024 * 1024
})

storage:release()

if err then
    return nil, err
end

-- Devolver URL al cliente para carga directa
return {upload_url = url}

Devuelve: string, error

Metodos de Storage

Permisos

Las operaciones de almacenamiento en la nube estan sujetas a evaluacion de politica de seguridad.

Errores

Consulte Manejo de Errores para trabajar con errores.