클라우드 스토리지

S3 호환 오브젝트 스토리지에 접근합니다. presigned 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

업로드 옵션

옵션 테이블로 메타데이터를 첨부하거나 쓰기를 보호할 수 있습니다:

storage:upload_object("reports/daily.json", body, {
    content_type = "application/json",
    cache_control = "max-age=3600",
    metadata = { owner = "team-a", run_id = "1234" },  -- stored as x-amz-meta-*
    only_if_absent = true                              -- fail if the key already exists
})

조건부 쓰기가 전제 조건을 충족하지 못하면 precondition_failed 오류를 반환합니다.

오브젝트 다운로드

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

-- 부분 콘텐츠 다운로드 (처음 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

전제 조건(if_match/if_none_match)을 충족하지 못하면 precondition_failed 오류를 반환합니다.

오브젝트 목록 조회

선택적 접두사 필터링으로 오브젝트 목록 조회:

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

-- 대용량 결과 페이징
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을 포함합니다. 각 오브젝트에는 key, size, etag, storage_class가 있으며, 선택적으로 last_modified, version_id, owner가 포함됩니다.

오브젝트 메타데이터

본문을 다운로드하지 않고 단일 오브젝트의 메타데이터를 가져옵니다:

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

반환: table, error

결과 필드:

존재하지 않는 오브젝트는 not_found 오류를 반환합니다.

오브젝트 삭제

여러 오브젝트 제거:

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

스토리지 메서드

권한

클라우드 스토리지 작업은 보안 정책 평가 대상입니다.

에러

에러 처리는 에러 처리를 참조하세요.