Cloud-Speicher

Zugriff auf S3-kompatiblen Objektspeicher. Hochladen, Herunterladen, Auflisten und Verwalten von Dateien mit Unterstützung für vorsignierte URLs.

Für Speicherkonfiguration siehe Cloud-Speicher.

Laden

local cloudstorage = require("cloudstorage")

Speicher abrufen

Holen Sie eine Cloud-Speicherressource anhand der Registry-ID:

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

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

Gibt zurück: Storage, error

Objekte hochladen

Inhalt aus String oder Datei hochladen:

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

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

-- Aus Datei hochladen
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()

Gibt zurück: boolean, error

Upload-Optionen

Hängen Sie Metadaten an oder schützen Sie das Schreiben mit einer Optionstabelle:

storage:upload_object("reports/daily.json", body, {
    content_type = "application/json",
    cache_control = "max-age=3600",
    metadata = { owner = "team-a", run_id = "1234" },  -- gespeichert als x-amz-meta-*
    only_if_absent = true                              -- schlägt fehl, wenn der Schlüssel bereits existiert
})

Ein bedingtes Schreiben, dessen Vorbedingung fehlschlägt, gibt einen precondition_failed-Fehler zurück.

Objekte herunterladen

Objekt in einen Datei-Writer herunterladen:

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

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

storage:release()

Gibt zurück: boolean, error

Eine fehlgeschlagene Vorbedingung (if_match/if_none_match) gibt einen precondition_failed-Fehler zurück.

Objekte auflisten

Objekte mit optionaler Präfix-Filterung auflisten:

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

-- Durch große Ergebnisse paginieren
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()

Gibt zurück: table, error

Ergebnis enthält objects, is_truncated, next_continuation_token. Jedes Objekt hat key, size, etag, storage_class sowie optional last_modified, version_id und owner.

Objekt-Metadaten

Die Metadaten eines einzelnen Objekts abrufen, ohne dessen Body herunterzuladen:

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

Gibt zurück: table, error

Ergebnisfelder:

Ein fehlendes Objekt gibt einen not_found-Fehler zurück.

Objekte löschen

Mehrere Objekte entfernen:

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

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

storage:release()

Gibt zurück: boolean, error

Download-URLs

Erstellen Sie eine temporäre URL, die das Herunterladen eines Objekts ohne Anmeldeinformationen ermöglicht. Nützlich zum Teilen von Dateien mit externen Benutzern oder zum Bereitstellen von Inhalten über Ihre Anwendung.

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

-- URL an Client für direkten Download zurückgeben
return {download_url = url}

Gibt zurück: string, error

Upload-URLs

Erstellen Sie eine temporäre URL, die das Hochladen eines Objekts ohne Anmeldeinformationen ermöglicht. Ermöglicht Clients, Dateien direkt in den Speicher hochzuladen, ohne über Ihren Server zu proxyen.

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

-- URL an Client für direkten Upload zurückgeben
return {upload_url = url}

Gibt zurück: string, error

Storage-Methoden

Berechtigungen

Cloud-Speicheroperationen unterliegen der Sicherheitsrichtlinienauswertung.

Fehler

Siehe Fehlerbehandlung für die Arbeit mit Fehlern.