使用 Boto3 上手 Amazon S3 Directory Buckets:S3 Express 入门实战指南

原创2026-09-27 19:47:221,373 阅读
文章标签:示例工程教程后端

使用 Boto3 上手 Amazon S3 Directory Buckets:S3 Express 入门实战指南

导读

本文基于 AWS 官方示例仓库 aws-doc-sdk-examples 中 python/example_code/s3-directory-buckets 目录下的完整示例,系统讲解如何用 AWS SDK for Python(Boto3)创建和管理 Amazon S3 Directory Buckets(即 S3 Express One Zone 存储桶)。读完本文,你将掌握 Directory Bucket 与普通 S3 存储桶的核心差异、目录型存储桶的命名与创建规范、VPC Endpoint 与最小权限 IAM 配置,以及一套可交互运行的端到端入门场景的源码级实现。

S3 Directory Buckets 是什么

S3 Directory Buckets(目录桶)是 Amazon S3 的一种特殊存储桶类型,专为单可用区(Single Availability Zone)内的数据存储而设计,对应 S3 Express One Zone 存储类。与普通 S3 桶不同,目录桶将对象按层级组织为目录结构,形态上更像一个本地文件系统,从而带来更快的索引、遍历与检索能力。

在仓库的 README.md 中对该服务给出了精确定位:

S3 Directory Buckets are designed to store data within a single AWS Zone. Directory buckets organize data hierarchically into directories, providing a structure similar to a file system.

这意味着目录桶天然适合将计算资源与存储资源部署在同一个可用区的低延迟场景。示例脚本的欢迎语也特别强调:只有把计算资源放在与目录桶相同的可用区,才能发挥 S3 Express One Zone 的最佳性能。

示例代码结构

本示例位于 python/example_code/s3-directory-buckets/,由四部分构成:

文件 作用
s3_express_getting_started.py 可交互运行的入门场景主脚本,串起全部七个步骤
s3_express_wrapper.py 封装 S3 客户端操作的 S3ExpressWrapper 类
s3_express_template.yaml 用于创建 IAM 用户与策略的 CloudFormation 模板
requirements.txt 依赖清单

与之配套的是 tests/ 目录下的一组 pytest 集成测试,覆盖了场景的每一个环节。

依赖安装与前置条件

按照 python/README.md 中的前置要求配置好 AWS 凭证后,在虚拟环境中执行:

python -m pip install -r requirements.txt

requirements.txt 内容如下:

boto3>=1.35.77
botocore>=1.35.77
pytest>=7.2.1
requests>=2.28.2

其中 boto3>=1.35.77 是保证支持 create_session 等 S3 Express 专用 API 的版本底线,pytest 与 requests 供测试使用。

运行入门场景

在命令行中执行:

python s3_express_getting_started.py

脚本默认以交互方式运行,可通过 --no-art 参数关闭控制台装饰性输出(无障碍场景下更友好):

python s3_express_getting_started.py --no-art

主入口在 s3_express_getting_started.py:依次创建 CloudFormation、EC2、IAM 客户端,实例化 S3ExpressScenario,并在捕获到 ClientError、ParamValidationError、TypeError 时自动调用 cleanup() 清理已创建的资源。

场景包含的七个步骤

README 列出的入门场景目标如下,它们在 s3_express_scenario() 中被依次执行:

  1. 搭建 VPC 与 VPC Endpoint(可选)
  2. 配置可操作 S3 Directory Buckets / S3 Express One Zone 的策略、角色与用户
  3. 创建两个 S3 客户端
  4. 创建两个存储桶(一个目录桶 + 一个普通桶)
  5. 创建对象并跨桶复制
  6. 演示性能差异
  7. 填充对象以展示目录桶与普通桶在排序上的差异
  8. 询问用户是否清理所有资源

下面结合源码逐环节展开。

第一步:VPC 与 VPC Endpoint 搭建

脚本提示"Are you running this in an EC2 instance located in the same AZ as your intended Directory buckets?"——如果确认在目标可用区的 EC2 实例中运行,即可选择自动创建 VPC Endpoint。

setup_vpc() 的实现要点:

  • 创建 CIDR 为 10.0.0.0/16 的 VPC,并使用 vpc_available waiter 等待就绪;
  • 通过 describe_route_tables 获取该 VPC 的默认路由表;
  • 以服务名 com.amazonaws.{region}.s3express 调用 create_vpc_endpoint 创建网关型 VPC Endpoint,并把路由表关联进去。

从源码注释可以看出关键设计意图:网关型 VPC Endpoint 是让 S3 Express One Zone 流量无需经过互联网网关或 NAT 设备的推荐方式。tear_done_vpc() 在清理阶段会先 delete_vpc_endpoints 再 delete_vpc。

第二步:用 CloudFormation 创建最小权限的 IAM 用户

场景强调"least privilege"(最小权限):创建两个 IAM 用户,一个仅具备 S3 Express One Zone 权限,另一个仅具备普通 S3 操作权限。这一设计正是为了演示两类桶对权限模型的不同依赖。

deploy_cloudformation_stack() 读取 s3_express_template.yaml 作为模板,以 Capabilities=["CAPABILITY_NAMED_IAM"] 创建 CloudFormation 栈,并用 stack_create_complete waiter 等待完成;栈名带随机 UUID,便于多环境并存与统一销毁。

模板定义的资源与权限如下:

  • RegularUser:普通 S3 用户,绑定 RegularPolicy,拥有 s3:CreateBucket / PutObject / GetObject / ListObjects / DeleteObjects / DeleteObject / ListBucket / DeleteBucket;
  • ExpressUser:S3 Express 用户,绑定 ExpressPolicy,拥有 s3express:CreateBucket / CreateSession / CopyObject / GetObject / PutObject / ListObjects / DeleteObjects / DeleteObject / DeleteBucket,外加跨桶复制所需的 s3:GetObject 与 s3:CopyObject。

值得注意:ExpressPolicy 中的 s3:GetObject 与 s3:CopyObject 是目录桶与普通桶之间复制对象时读取源对象所必需的。栈的输出 RegularUser、ExpressUser 会被读取并转换为后续创建客户端所用的凭证。

第三步:创建两个 S3 客户端

场景通过 create_access_key() 为两个用户分别创建访问密钥,再由 create_s3__client_with_access_key_credentials() 用各自凭证构造独立 S3 客户端,最终包装为两个 S3ExpressWrapper 实例:

self.s3_regular_wrapper = S3ExpressWrapper(s3_regular_client)
self.s3_express_wrapper = S3ExpressWrapper(s3_express_client)

S3ExpressWrapper 定义在 s3_express_wrapper.py,是对 Boto3 S3 客户端底层 API 的轻量封装,提供 create_bucket、put_object、get_object、copy_object、list_objects、create_session、delete_bucket_and_objects 等方法;其类方法 from_client() 也可直接用默认凭证快速实例化。

第四步:创建目录桶与普通桶

创建目录桶与创建普通桶在参数结构上有本质区别。源码在 setup_clients_and_buckets() 中构造了如下配置:

configuration = {
    "Bucket": {
        "Type": "Directory",
        "DataRedundancy": "SingleAvailabilityZone",
    },
    "Location": {
        "Name": availability_zone["ZoneId"],
        "Type": "AvailabilityZone",
    },
}

S3ExpressWrapper.create_bucket() 将其作为 CreateBucketConfiguration 传给底层 create_bucket(见 s3_express_wrapper.py)。

目录桶命名规则

目录桶名与普通桶不同,必须包含可用区标识与 --x-s3 后缀,格式为:

{前缀}-{uuid}--{ZoneId}--x-s3

例如测试中使用的 amzn-s3-demo-bucket-0000--use1-az2--x-s3。源码用 uuid.uuid4() 生成去横线后的十六进制串填充 UUID 段,并计算出长度上限以保证整名不超过 63 个字符(s3_express_getting_started.py):

directory_bucket_suffix = f"--{availability_zone['ZoneId']}--x-s3"
max_uuid_length = 63 - len(bucket_prefix) - len(directory_bucket_suffix) - 1
bucket_uuid = str(uuid.uuid4()).replace("-", "")[:max_uuid_length]
directory_bucket_name = f"{bucket_prefix}-{bucket_uuid}{directory_bucket_suffix}"
regular_bucket_name = f"{bucket_prefix}-regular-{bucket_uuid}"

可用区选择与容错

不是所有可用区都支持目录桶,因此脚本通过 select_availability_zone_id() 用 EC2 的 describe_availability_zones 列出当前区域的可用区供用户选择,并在 create_bucket 抛出 InvalidBucketName 时提示用户另选可用区重试(说明某些可用区不提供该服务)。普通桶则直接用 s3_regular_wrapper.create_bucket(regular_bucket_name) 创建,无需任何额外配置。

第五步:创建对象并跨桶复制

场景向普通桶写入一个文本对象,再复制到目录桶(create_session_and_add_objects()):

bucket_object = "basic-text-object"
self.s3_regular_wrapper.put_object(
    self.regular_bucket_name, bucket_object, "Look Ma, I'm a bucket!"
)
self.s3_express_wrapper.create_session(self.directory_bucket_name)
self.s3_express_wrapper.copy_object(
    self.regular_bucket_name, bucket_object,
    self.directory_bucket_name, bucket_object,
)

这里体现了目录桶权限模型的精髓:普通桶每次调用都会校验权限,而目录桶通过 create_session 建立会话令牌,凭据 + 会话令牌一次性校验。单次调用收益不大,但在大量并发调用下能节省可观的连接开销。

create_session 是 README 中单独列出的 Single Action 示例(对应 s3_express_wrapper.py#L162 的 S3ExpressWrapper.create_session),底层即调用 Boto3 的 create_session(Bucket=bucket_name)。配套测试 test_s3_express_getting_started_create_session_and_add_objects.py 通过 stub 验证了 put_object → create_session → copy_object 的完整调用链,并分别模拟三处 ClientError 的错误路径。

第六步:演示性能差异

demonstrate_performance() 对同一个对象分别从两个桶各下载 downloads 次,用 time.time_ns() 统计纳秒级耗时对比。默认 downloads = 1000,用户可输入 1 到 1,000,000 之间的自定义次数;每下载 10 次打印一次进度。脚本会输出两个桶各自的耗时与差值,并诚实提示:如果差值小于 0(目录桶更慢),通常是因为没有运行在 VPC 内的云上环境中。对应测试 test_s3_express_getting_started_demonstrate_performance.py 以 10 次下载为样本 stub 了两组 get_object 调用并逐点注入错误。

第七步:展示字典序差异

这是最能直观体现目录桶"目录化"结构的环节。脚本向两个桶各放入三个带路径前缀的对象(show_lexicographical_differences()):

other_object = f"other/{bucket_object}"
alt_object = f"alt/{bucket_object}"
other_alt_object = f"other/alt/{bucket_object}"

随后分别调用 list_objects_v2 并打印内容。运行结果会揭示两类桶在 ListObjects 上的行为差异:

  • 普通桶:把完整 Key 视为对象标识符,列表结果按 Key 的字典序(lexicographical order)返回;
  • 目录桶:真正创建了目录层级,把 Key 当作指向对象的"路径",因此列表顺序并不遵循整 Key 的字典序。

目录越分层、对象越多,目录桶的索引与遍历优势越明显——这就是"Directory"命名背后的结构本质。测试文件 test_s3_express_getting_started_show_lexicographical_differences.py 同样覆盖了 6 次 put_object 与 2 次 list_objects_v2 的成功与错误路径。

资源清理

场景结尾会询问用户是否删除全部资源,确认后执行 cleanup():

  1. 通过 delete_bucket_and_objects 删除目录桶(先分页列出对象再批量 delete_objects,最后 delete_bucket,实现见 s3_express_wrapper.py);
  2. 以同样方式删除普通桶;
  3. 删除 CloudFormation 栈(用 stack_delete_complete waiter 等待完成);
  4. 拆除 VPC Endpoint 与 VPC。

在异常退出路径下,主入口也会自动触发 cleanup(),避免留下孤儿资源。

测试与验证方式

测试位于 tests/ 目录,运行前请阅读 python/README.md 中的测试说明。测试基础设施在 conftest.py 中定义:通过 scenario_data fixture 装配 CloudFormation、EC2、IAM、S3 的 stubber,并关闭交互式"按回车继续"提示;六个测试文件分别对应场景的六个环节(建 VPC 与用户、建客户端与桶、建会话与加对象、性能演示、字典序差异、清理),且每个环节都包含正常路径与逐点注入 ClientError 的错误路径用例,保证场景的每一步都被验证。

实践要点总结

  • 目录桶只存于单个可用区:把计算资源放到与目录桶相同的可用区,是发挥性能的前提;
  • 命名必须合规:{前缀}-{uuid}--{ZoneId}--x-s3,总长不超过 63 字符,且需确认目标可用区支持该服务;
  • 权限模型不同:目录桶依赖 create_session 的会话令牌校验,权限策略使用 s3express: 前缀的动作;
  • 网关 VPC Endpoint:com.amazonaws.{region}.s3express 服务名是打通 S3 Express 流量的推荐方式;
  • 清理务必彻底:先删对象再删桶、再删栈与 VPC,否则会产生持续计费资源。

如需进一步了解服务级 API 细节,可参考 S3 Directory Buckets 官方用户指南与 API 参考,以及仓库中 README.md 提供的 Boto3 S3 Directory Buckets 客户端参考链接。

登录后查看全文
aws-doc-sdk-examples