本教程详细介绍了如何使用aws sdk for php在amazon s3桶中获取指定路径下的单层对象列表，模拟目录结构。通过巧妙结合`prefix`和`delimiter`参数，您可以有效地筛选出当前层级的文件夹（commonprefixes）和文件（contents），避免返回深层嵌套的对象，从而实现清晰的目录浏览。
引言：理解S3的扁平化存储与目录模拟
Amazon S3（Simple Storage Service）本质上是一个扁平化的对象存储服务，它不具备传统文件系统中的目录（文件夹）概念。S3中的每个“文件”都被视为一个对象，并通过一个唯一的键（Key）来标识，这个键通常包含对象的完整路径，例如public/uploads/test_company/test1/test.txt。
然而，在实际应用中，我们经常需要像操作文件系统一样，以层级结构来浏览和管理S3桶中的对象，例如只查看某个特定路径下的“子目录”和“文件”，而不深入到更深的层级。AWS SDK提供了listObjects或listObjectsV2 API，配合特定的参数，可以有效地模拟这种层级浏览。
核心概念：Prefix与Delimiter
要实现S3桶的单层对象列表，listObjects（或listObjectsV2）API中的两个关键参数是Prefix（前缀）和Delimiter（分隔符）。
-
Prefix (前缀):
立即学习“PHP免费学习笔记（深入）”；
- Prefix参数用于限制API返回结果的范围。只有对象键以指定前缀开头的对象才会被包含在结果集中。
- 例如，如果Prefix设置为public/uploads/test_company/，则所有以该字符串开头的对象（包括public/uploads/test_company/test1、public/uploads/test_company/test2、public/uploads/test_company/test1/test.txt等）都将被S3考虑。
-
Delimiter (分隔符):
- Delimiter参数是模拟目录结构的关键。它告诉S3将指定的字符（通常是/）视为目录分隔符。
- 当指定了Delimiter时，listObjects的返回结果将包含两类信息：
- Contents: 在指定Prefix下，且其键值中不包含Delimiter字符的对象。这些通常被视为当前层级的“文件”。
- CommonPrefixes: 在指定Prefix下，直到遇到第一个Delimiter字符为止的共同前缀。这些通常被视为当前层级的“子目录”。S3会返回这些共同前缀的列表，每个共同前缀都以Delimiter结尾。
通过结合这两个参数，我们可以精确地获取指定路径下的第一层子目录和文件。
PHP代码实现
以下是如何使用AWS SDK for PHP来实现S3桶单层对象列表的示例代码。
假设S3桶中存在以下对象键：
public/uploads/test_company/test1 public/uploads/test_company/test2 public/uploads/test_company/test1/test.txt public/uploads/test_company/file_at_root.jpg
我们的目标是查询public/uploads/test_company/路径下，只获取test1/、test2/（作为子目录）和file_at_root.jpg（作为文件）。
'latest', // 使用最新版本的API
'region' => 'your-aws-region', // 例如 'us-east-1', 'ap-southeast-1'
'credentials' => [
'key' => 'YOUR_AWS_ACCESS_KEY_ID', // 替换为您的Access Key ID
'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY', // 替换为您的Secret Access Key
// 'token' => 'YOUR_AWS_SESSION_TOKEN', // 如果使用临时凭证
],
]);
// 2. 定义桶名、前缀和分隔符
$bucketName = 'your-s3-bucket-name'; // 替换为您的S3桶名称
$prefix = 'public/uploads/test_company/'; // 要查询的路径前缀，注意末尾的斜杠
$delimiter = '/'; // 目录分隔符
echo "正在查询桶 '{$bucketName}' 中路径 '{$prefix}' 下的单层对象...\n";
try {
// 3. 调用 listObjects 方法
$result = $s3Client->listObjects([
'Bucket' => $bucketName, // 必需：S3桶名称
'Prefix' => $prefix, // 限制结果为指定前缀下的对象
'Delimiter' => $delimiter, // 启用目录模拟功能
// 'MaxKeys' => 1000, // 可选：限制每次返回的对象数量，默认1000
// 'Marker' => '', // 可选：用于分页，从指定键之后开始返回
]);
// 4. 处理返回结果：CommonPrefixes (子目录)
if (isset($result['CommonPrefixes'])) {
echo "\n当前层级子目录:\n";
foreach ($result['CommonPrefixes'] as $commonPrefix) {
// CommonPrefixes['Prefix']会包含完整的目录路径，例如 'public/uploads/test_company/test1/'
echo "- " . $commonPrefix['Prefix'] . "\n";
}
} else {
echo "\n当前层级没有子目录。\n";
}
// 5. 处理返回结果：Contents (当前层级的文件)
if (isset($result['Contents'])) {
echo "\n当前层级文件:\n";
foreach ($result['Contents'] as $object) {
// 排除与Prefix完全相同的Key（通常表示一个空目录本身）
// 并且确保对象键在Prefix之后不包含Delimiter，以确认它是当前层级的文件
$relativeKey = substr($object['Key'], strlen($prefix));
if (!empty($relativeKey) && strpos($relativeKey, $delimiter) === false) {
echo "- " . $object['Key'] . " (大小: " . $object['Size'] . " 字节, 上次修改: " . $object['LastModified'] . ")\n";
}
}
} else {
echo "\n当前层级没有直接文件。\n";
}
} catch (AwsException $e) {
// 捕获并输出任何AWS SDK相关的异常
echo "查询S3对象时发生错误: " . $e->getMessage() . "\n";
}
?> 示例分析与预期结果
根据上述代码和示例对象键：
- Prefix: public/uploads/test_company/
- Delimiter: /
listObjects方法将返回：
-
CommonPrefixes:
- public/uploads/test_company/test1/
- public/uploads/test_company/test2/
- 这些是S3识别出的，在Prefix下且由Delimiter分隔出的第一层“目录”。
-
Contents:
- public/uploads/test_company/file_at_root.jpg
- 这是在Prefix下，且其键值中不包含额外Delimiter字符的对象，即当前层级的“文件”。
- 注意：public/uploads/test_company/test1/test.txt不会出现在Contents中，因为它在test1/这个共同前缀之下，属于更深的层级。
因此，代码将输出：
正在查询桶 'your-s3-bucket-name' 中路径 'public/uploads/test_company/' 下的单层对象... 当前层级子目录: - public/uploads/test_company/test1/ - public/uploads/test_company/test2/ 当前层级文件: - public/uploads/test_company/file_at_root.jpg (大小: XXX 字节, 上次修改: YYY)
注意事项
- S3的虚拟目录： 再次强调，S3并没有真正的目录结构。Prefix和Delimiter机制是AWS S3 API层面对目录概念的模拟，方便用户进行分层管理和浏览。
- 分页处理： listObjects默认最多返回1000个对象（包括Contents和CommonPrefixes）。如果您的目录包含大量对象或子目录，您需要处理分页逻辑。listObjects的返回结果中可能包含NextContinuationToken（对于listObjectsV2）或Marker（对于listObjects），您需要将它们作为后续请求的参数，直到所有结果都被获取。
- 权限管理： 确保您的AWS凭证拥有对S3桶的s3:ListBucket权限，否则API调用将失败。
- 性能考量： 对于包含海量对象的大型S3桶，频繁地进行listObjects操作可能会产生一定的性能开销。在设计系统时，考虑缓存列表结果或优化查询逻辑。
- Prefix的末尾斜杠： 在指定Prefix时，通常建议在路径末尾添加斜杠（例如public/uploads/test_company/），以确保只匹配该“目录”下的内容，而不是以该字符串开头但属于不同“目录”的对象（例如public/uploads/test_company_new）。
总结
通过巧妙地结合AWS SDK for PHP的listObjects方法中的Prefix和Delimiter参数，您可以有效地在Amazon S3桶中模拟传统文件系统的目录结构，实现单层对象的精确列表。这种方法不仅有助于清晰地浏览S3数据，也是构建S3文件管理界面或自动化脚本的基础。理解S3的扁平化存储本质以及这些参数的工作原理，是高效利用S3的关键。
