クラウドストレージ

S3互換オブジェクトストレージへのアクセス。署名付きURLサポート付きでファイルをアップロード、ダウンロード、一覧表示、管理。

ストレージ設定についてはクラウドストレージを参照。

ロード

local cloudstorage = require("cloudstorage")

ストレージの取得

レジストリ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()

戻り値: Storage, error

オブジェクトのアップロード

文字列またはファイルからコンテンツをアップロード:

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

-- 文字列コンテンツをアップロード
local ok, err = storage:upload_object("reports/daily.json", json.encode({
    date = "2024-01-15",
    total = 1234
}))

-- ファイルからアップロード
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()

戻り値: boolean, error

オブジェクトのダウンロード

ファイルライターにオブジェクトをダウンロード:

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

-- 部分コンテンツをダウンロード（最初の1KB）
local partial = vol:open("/partial.bin", "w")
storage:download_object("backups/large-file.bin", partial, {
    range = "bytes=0-1023"
})
partial:close()

storage:release()

戻り値: boolean, error

オブジェクトの一覧

オプションのプレフィックスフィルタリングでオブジェクトを一覧:

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

-- 大きな結果をページネーション
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()

戻り値: table, error

結果にはobjects、is_truncated、next_continuation_tokenが含まれる。

オブジェクトの削除

複数のオブジェクトを削除:

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

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

storage:release()

戻り値: boolean, error

ダウンロードURL

認証情報なしでオブジェクトをダウンロードできる一時URLを作成。外部ユーザーとファイルを共有したり、アプリケーション経由でコンテンツを提供するのに便利。

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を返す
return {download_url = url}

戻り値: string, error

アップロードURL

認証情報なしでオブジェクトをアップロードできる一時URLを作成。クライアントがサーバーを経由せずに直接ストレージにファイルをアップロードできる。

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を返す
return {upload_url = url}

戻り値: string, error

ストレージメソッド

権限

クラウドストレージ操作はセキュリティポリシー評価の対象。

エラー

エラーの処理についてはエラー処理を参照。