云存储

云存储

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

参数	类型	描述
id	string	存储资源 ID

返回: 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()

参数	类型	描述
key	string	对象键/路径
content	string 或 Reader	字符串内容或文件读取器
options	table	可选的元数据和条件写入选项

返回: 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
})

选项	类型	描述
content_type	string	MIME 类型
cache_control	string	Cache-Control 头部
content_disposition	string	Content-Disposition 头部
content_encoding	string	Content-Encoding 头部
metadata	table	用户元数据（string 键/值），存储为 x-amz-meta-*
headers	table	额外的请求头部（string 键/值）
if_match	string	仅当当前对象 ETag 匹配时写入
if_none_match	string	仅当没有对象匹配该 ETag 时写入（"*" 表示任意）
only_if_absent	boolean	仅当键不存在时写入（if_none_match = "*" 的别名）

未满足前置条件的条件写入会返回 precondition_failed 错误。

下载对象

将对象下载到文件写入器：

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

参数	类型	描述
key	string	要下载的对象键
writer	Writer	目标文件写入器
options.range	string	字节范围（例如 “bytes=0-1023”）
options.if_match	string	仅当对象 ETag 匹配时下载
options.if_none_match	string	仅当 ETag 不匹配时下载

返回: 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()

参数	类型	描述
options.prefix	string	按键前缀过滤
options.max_keys	integer	返回的最大对象数
options.continuation_token	string	分页令牌
options.include_owner	boolean	包含每个对象的 owner（id、display_name）
options.include_versions	boolean	列出对象版本；每项包含 version_id

返回: table, error

结果包含 objects、is_truncated、next_continuation_token。每个对象都有 key、size、etag、storage_class，以及可选的 last_modified、version_id 和 owner。

在列表结果中 content_type 始终为空——S3 list 操作不返回它。使用 head_object 读取对象的内容类型和元数据。

对象元数据

在不下载对象正文的情况下获取单个对象的元数据：

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

参数	类型	描述
key	string	对象键

返回: table, error

结果字段：

字段	类型	描述
size	integer	对象大小（字节）
etag	string	实体标签
content_type	string	MIME 类型
cache_control	string	Cache-Control 头部
content_disposition	string	Content-Disposition 头部
content_encoding	string	Content-Encoding 头部
storage_class	string	存储类别
version_id	string	版本 ID（启用版本控制时存在）
last_modified	integer	最后修改时间（Unix 秒）
metadata	table	用户元数据（x-amz-meta-*）
headers	table	原始响应头部（键名为小写）

不存在的对象会返回 not_found 错误。

删除对象

删除多个对象：

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

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

storage:release()

参数	类型	描述
keys	string[]	要删除的对象键数组

返回: 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}

参数	类型	描述
key	string	对象键
options.expiration	integer	URL 过期秒数（默认：3600）

返回: 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}

参数	类型	描述
key	string	对象键
options.expiration	integer	URL 过期秒数（默认：3600）
options.content_type	string	上传所需的内容类型
options.content_length	integer	最大上传大小（字节）

返回: string, error

存储方法

方法	返回	描述
upload_object(key, content, opts?)	boolean, error	上传字符串或文件内容
download_object(key, writer, opts?)	boolean, error	下载到文件写入器
head_object(key)	table, error	获取对象元数据
list_objects(opts?)	table, error	列出对象并按前缀过滤
delete_objects(keys)	boolean, error	删除多个对象
presigned_get_url(key, opts?)	string, error	生成临时下载 URL
presigned_put_url(key, opts?)	string, error	生成临时上传 URL
release()	boolean	释放存储资源

权限

云存储操作受安全策略评估约束。

操作	资源	描述
cloudstorage.get	存储 ID	获取存储资源

错误

条件	类型	可重试
资源 ID 为空	errors.INVALID	否
资源未找到	errors.NOT_FOUND	否
不是云存储资源	errors.INVALID	否
存储已释放	errors.INVALID	否
键为空	errors.INVALID	否
内容为 nil	errors.INVALID	否
写入器无效	errors.INVALID	否
对象未找到	errors.NOT_FOUND	否
条件前置条件失败	errors.CONFLICT	否
权限被拒绝	errors.PERMISSION_DENIED	否
操作失败	errors.INTERNAL	否

错误处理请参阅 错误处理。