Cloud Storage

Acesse armazenamento de objetos compativel com S3. Upload, download, listagem e gerenciamento de arquivos com suporte a URLs pre-assinadas.

Para configuração de armazenamento, veja Cloud Storage.

Carregamento

local cloudstorage = require("cloudstorage")

Adquirindo Storage

Obter um recurso de cloud storage por ID do 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()

Retorna: Storage, error

Fazendo Upload de Objetos

Upload de conteudo de string ou arquivo:

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

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

-- Upload de arquivo
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()

Retorna: boolean, error

Baixando Objetos

Baixar um objeto para um file writer:

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()

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

storage:release()

Retorna: boolean, error

Listando Objetos

Listar objetos com filtragem opcional por prefixo:

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.content_type)
end

-- Paginar através 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()

Retorna: table, error

Resultado contem objects, is_truncated, next_continuation_token.

Deletando Objetos

Remover multiplos objetos:

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

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

storage:release()

Retorna: boolean, error

URLs de Download

Criar uma URL temporaria que permite baixar um objeto sem credenciais. Util para compartilhar arquivos com usuários externos ou servir conteudo através da sua aplicação.

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

-- Retornar URL ao cliente para download direto
return {download_url = url}

Retorna: string, error

URLs de Upload

Criar uma URL temporaria que permite fazer upload de um objeto sem credenciais. Permite que clientes facam upload de arquivos diretamente para o armazenamento sem fazer proxy pelo seu 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

-- Retornar URL ao cliente para upload direto
return {upload_url = url}

Retorna: string, error

Métodos de Storage

Permissões

Operações de cloud storage estao sujeitas a avaliação de política de segurança.

Erros

Veja Error Handling para trabalhar com erros.