跳到主要内容
版本:当前开发版

S3 API

S3 兼容对象存储辅助能力位于 ptool.s3 和 p.s3 下。

ptool.s3.connect​

v0.10.0 - 引入。

ptool.s3.connect(options) 打开一个 S3 兼容对象存储连接,并返回一个 Connection 对象。

options 字段:

  • bucket(string,必填):bucket 名称。
  • region(string,选填):AWS 区域或服务提供商区域。
  • endpoint(string,选填):自定义的 S3 兼容 endpoint URL,例如 MinIO、R2 或其他对象存储服务。
  • access_key_id(string,选填):访问密钥 ID。
  • secret_access_key(string,选填):访问密钥 secret。
  • session_token(string,选填):会话令牌。
  • root(string,选填):应用到所有对象操作的根前缀。
  • allow_anonymous(boolean,选填):当为 true 时,如果未配置凭证,则允许未签名请求。默认为 false。

环境变量回退:

  • 显式传入的 options 值优先。
  • 缺失的 region、endpoint、access_key_id、secret_access_key 和 session_token 会回退到:
    • AWS_REGION
    • AWS_ENDPOINT、AWS_ENDPOINT_URL 或 AWS_S3_ENDPOINT
    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY
    • AWS_SESSION_TOKEN
  • 环境变量回退使用 ptool 的运行时环境视图,因此通过 p.os.setenv(...) 设置的值也会被 ptool.s3.connect(...) 看到。

示例:

local s3 = ptool.s3.connect({
bucket = "artifacts",
region = "auto",
endpoint = "https://<account>.r2.cloudflarestorage.com",
access_key_id = p.os.getenv("AWS_ACCESS_KEY_ID"),
secret_access_key = p.os.getenv("AWS_SECRET_ACCESS_KEY"),
root = "builds/",
})

Connection​

v0.10.0 - 引入。

Connection 表示由 ptool.s3.connect() 返回的已打开对象存储连接。

它实现为 Lua userdata。

方法:

  • conn:read(path[, options]) -> string
  • conn:presign_read(path[, options]) -> string
  • conn:write(path, content[, options]) -> table
  • conn:delete(path) -> nil
  • conn:exists(path) -> boolean
  • conn:list([prefix]) -> table
  • conn:stat(path) -> table
  • conn:put_bucket_acl(options) -> nil
  • conn:put_object_acl(path, options) -> nil

路径规则:

  • 除非另有说明,对象路径必须是非空字符串。
  • 前导 / 会被忽略,因此 /foo/bar.txt 和 foo/bar.txt 指向同一个对象。
  • 当连接配置了 root 时,路径会相对于 root 解析。

条目 table 结构:

  • path(string):相对于连接根路径的对象路径。
  • size(integer):对象大小,单位为字节。
  • etag(string | nil):对象的 ETag(如果可用)。
  • last_modified(string | nil):最后修改时间戳(如果可用)。
  • content_type(string | nil):对象内容类型(如果可用)。
  • version(string | nil):对象版本(如果可用)。
  • metadata(table | nil):用户定义的对象元信息(如果可用)。
  • is_file(boolean):该条目是否为文件。
  • is_dir(boolean):该条目是否为目录。
  • mode(string):"file"、"dir" 或 "unknown" 之一。

read​

v0.10.0 - 引入。 v0.12.0 - 更改。

规范 API 名称:ptool.s3.Connection:read。

conn:read(path[, options]) 以原始字节读取对象,并返回 Lua 字符串。

  • path(string,必填):对象路径。
  • options(table,选填):读取选项。
  • 返回:string。

options 字段:

  • range(table,选填):使用半开区间 [start, end) 读取字节范围。
    • start(integer,选填):要包含的首个字节偏移。
    • end(integer,选填):要排除的首个字节偏移。

行为:

  • 省略 range 时读取整个对象。
  • { start = N } 从字节 N 读取到结尾。
  • { end = N } 从开头读取到字节 N 之前,但不包含字节 N。
  • { start = A, end = B } 读取从字节 A 到 B - 1 的内容。

示例:

local s3 = ptool.s3.connect({ bucket = "artifacts" })
local content = s3:read("releases/v1.0.0/notes.txt")
print(content)

local prefix = s3:read("releases/v1.0.0/notes.txt", {
range = { start = 0, end = 5 },
})
print(prefix)

write​

v0.10.0 - 引入。 v0.12.0 - 更改。

规范 API 名称:ptool.s3.Connection:write。

conn:write(path, content[, options]) 将 Lua 字符串作为原始字节写入对象,并返回条目表。

  • path(string,必填):对象路径。
  • content(string,必填):要上传的字节内容。
  • options(table,选填):写入选项。
  • 返回:table。

options 字段:

  • content_type(string,选填):设置对象内容类型。
  • cache_control(string,选填):设置对象 cache-control 头。
  • content_disposition(string,选填):设置对象 content-disposition 头。
  • content_encoding(string,选填):设置对象 content-encoding 头。
  • metadata(table,选填):将用户定义元信息设置为字符串键值对。
  • if_not_exists(boolean,选填):仅当对象尚不存在时写入。默认为 false。
  • if_match(string,选填):仅当当前 ETag 匹配时写入。
  • if_none_match(string,选填):仅当当前 ETag 不匹配时写入。

行为:

  • content 会按字节原样上传。
  • 嵌入的 NUL 字节和非 UTF-8 字节会被保留。
  • 返回的条目可避免为了常见元信息立刻再调用一次 stat()。
  • 某些 S3 兼容服务可能不会在写入响应中回显用户定义的 metadata 或 etag。发生这种情况时,这些字段会保持为 nil,直到后续调用 stat()。

示例:

local s3 = ptool.s3.connect({ bucket = "artifacts" })
local entry = s3:write("tmp/hello.txt", "hello\n", {
content_type = "text/plain; charset=utf-8",
metadata = { author = "ptool" },
})
print(entry.path, entry.etag, entry.version)

s3:write("tmp/blob.bin", "\x00\xffABC")

delete​

v0.10.0 - 引入。

规范 API 名称:ptool.s3.Connection:delete。

conn:delete(path) 删除一个对象。

  • path(string,必填):对象路径。

exists​

v0.10.0 - 引入。

规范 API 名称:ptool.s3.Connection:exists。

conn:exists(path) 检查对象是否存在。

  • path(string,必填):对象路径。
  • 返回:boolean。

list​

v0.10.0 - 引入。

规范 API 名称:ptool.s3.Connection:list。

conn:list([prefix]) 列出某个前缀下的条目,并返回致密 Lua 数组表。

  • prefix(string,选填):要列出的前缀。默认为连接根路径。
  • 返回:table。

示例:

local s3 = ptool.s3.connect({ bucket = "artifacts", root = "builds/" })
local entries = s3:list("2026/")

for _, entry in ipairs(entries) do
print(entry.path, entry.mode, entry.size)
end

stat​

v0.10.0 - 引入。

规范 API 名称:ptool.s3.Connection:stat。

conn:stat(path) 返回单个对象的元数据。

  • path(string,必填):对象路径。
  • 返回:table。

示例:

local s3 = ptool.s3.connect({ bucket = "artifacts" })
local meta = s3:stat("releases/v1.0.0/app.tar.zst")
print(meta.size, meta.etag, meta.last_modified)

put_bucket_acl​

v0.12.0 - 引入。

规范 API 名称:ptool.s3.Connection:put_bucket_acl。

conn:put_bucket_acl(options) 会替换 bucket ACL,成功时返回 nil。

  • options(table,必填):bucket ACL 选项。
  • 返回:nil。

options 字段:

  • acl(string,选填):预定义 bucket ACL。可选值为 "authenticated-read"、"private"、"public-read" 和 "public-read-write"。
  • expected_bucket_owner(string,选填):如果 bucket 不属于此 AWS 账户 ID,则请求失败。
  • grant_full_control(string,选填):x-amz-grant-full-control 请求头的值。
  • grant_read(string,选填):x-amz-grant-read 请求头的值。
  • grant_read_acp(string,选填):x-amz-grant-read-acp 请求头的值。
  • grant_write(string,选填):x-amz-grant-write 请求头的值。
  • grant_write_acp(string,选填):x-amz-grant-write-acp 请求头的值。

行为:

  • 请提供 acl,或者一个或多个 grant_* 字段。这两种形式不能在一次调用中同时使用。
  • 所有已提供的字符串都必须非空。
  • 授权字符串使用 S3 授权请求头语法,例如目标服务提供商接受的账户 ID、电子邮件地址或组 URI。
  • 该操作以连接的 bucket 为目标,不会应用连接的 root 前缀。
  • 许多 S3 兼容服务提供商会禁用 ACL,或未实现 ACL API。在这种情况下,服务提供商错误会以 s3_error 返回。

示例:

local s3 = ptool.s3.connect({ bucket = "artifacts" })

s3:put_bucket_acl({ acl = "private" })

s3:put_bucket_acl({
grant_read = 'uri="http://acs.amazonaws.com/groups/global/AllUsers"',
})

put_object_acl​

v0.12.0 - 引入。

规范 API 名称:ptool.s3.Connection:put_object_acl。

conn:put_object_acl(path, options) 会替换对象的 ACL,成功时返回 nil。

  • path(string,必填):对象路径。
  • options(table,必填):对象 ACL 选项。
  • 返回:nil。

options 字段:

  • acl(string,选填):预定义对象 ACL。可选值为 "authenticated-read"、"aws-exec-read"、"bucket-owner-full-control"、"bucket-owner-read"、"private"、"public-read" 和 "public-read-write"。
  • expected_bucket_owner(string,选填):如果 bucket 不属于此 AWS 账户 ID,则请求失败。
  • grant_full_control(string,选填):x-amz-grant-full-control 请求头的值。
  • grant_read(string,选填):x-amz-grant-read 请求头的值。
  • grant_read_acp(string,选填):x-amz-grant-read-acp 请求头的值。
  • grant_write(string,选填):x-amz-grant-write 请求头的值。
  • grant_write_acp(string,选填):x-amz-grant-write-acp 请求头的值。
  • version_id(string,选填):将 ACL 应用于此对象版本。
  • request_payer(string,选填):仅接受 "requester",并发送请求者付费确认。

行为:

  • 请提供 acl,或者一个或多个 grant_* 字段。这两种形式不能在一次调用中同时使用。
  • 所有已提供的字符串都必须非空。
  • 授权字符串使用目标服务提供商接受的 S3 授权请求头语法。
  • 前导 / 会被忽略,并且连接的 root 前缀会像其他对象操作一样应用到对象 key。
  • 许多 S3 兼容服务提供商会禁用 ACL,或未实现 ACL API。在这种情况下,服务提供商错误会以 s3_error 返回。

示例:

local s3 = ptool.s3.connect({
bucket = "artifacts",
root = "public/",
})

s3:put_object_acl("index.html", { acl = "public-read" })

s3:put_object_acl("release.zip", {
acl = "bucket-owner-full-control",
version_id = "example-version-id",
request_payer = "requester",
})

presign_read​

v0.13.0 - 引入。

规范 API 名称:ptool.s3.Connection:presign_read。

conn:presign_read(path[, options]) 返回一个预签名 GET URL,用于在不共享凭证的情况下下载对象。

  • path(string,必填):对象路径。
  • options(table,选填):预签名选项。
  • 返回:string。

options 字段:

  • expires_in(integer,选填):有效期,单位为秒,范围为 1 到 604800(七天)。默认值为 3600。
  • response_content_type(string,选填):覆盖下载响应的 Content-Type。
  • response_content_disposition(string,选填):覆盖下载响应的 Content-Disposition,例如 attachment; filename="report.pdf"。
  • version_id(string,选填):下载此对象版本。

行为:

  • 忽略开头的 /,并应用连接的 root 前缀。
  • 签名在本地生成:不会下载对象,也不会检查对象是否存在或访问权限。
  • 必须同时提供 access_key_id 和 secret_access_key,即使启用了 allow_anonymous。支持连接的环境变量回退和 session_token。
  • 如果签名凭证过期或访问权限被撤销,URL 可能提前失效。在 URL 有效期间,任何持有者都可以使用它。
  • 可选字符串不得为空。未知选项和无效的有效期值会被拒绝。
  • URL 使用配置的 endpoint,下载者必须能够访问该地址。响应覆盖选项取决于 S3 兼容服务提供商的支持。

示例:

local s3 = p.s3.connect({ bucket = "artifacts", region = "us-east-1" })
local url = s3:presign_read("reports/report.pdf", {
expires_in = 3600,
response_content_type = "application/pdf",
response_content_disposition = 'attachment; filename="report.pdf"',
})
print(url)