本文详细介绍了如何使用php aws sdk获取amazon s3存储桶中指定路径下的第一级对象，包括文件和子目录，同时避免递归获取深层内容。通过配置`listobjects`方法的`prefix`和`delimiter`参数，开发者可以精确控制s3对象的列表行为，实现高效、有针对性的数据检索。
理解S3对象列表机制
Amazon S3采用扁平化的对象存储结构，没有传统文件系统中的“目录”概念。然而，通过对象键（Key）中的斜杠（/），S3提供了一种模拟目录层级的方式。当我们需要列出特定“目录”下的第一级内容时，就需要利用S3 API提供的Prefix和Delimiter参数。
- Prefix (前缀)：此参数用于过滤结果，只返回键以指定字符串开始的对象。例如，如果Prefix设置为public/uploads/test_company/，则只会返回该路径下的所有对象，包括子目录中的文件。
- Delimiter (分隔符)：这是实现“第一级”列表的关键。当设置了Delimiter参数（通常为/）时，S3会将所有在Prefix之后但在下一个Delimiter之前的内容视为一个“共同前缀”（CommonPrefix），并将其作为子目录返回。同时，它还会返回直接位于Prefix下且不包含Delimiter的实际对象（文件）。这样，我们就可以区分出第一级的文件和子目录。
例如，对于以下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.txt
如果Prefix设置为public/uploads/test_company/，并且Delimiter设置为/，S3将返回：
- CommonPrefixes：public/uploads/test_company/test1/ 和 public/uploads/test_company/test2/
- Contents：public/uploads/test_company/file_at_root.txt
这样，我们就能精确地获取到public/uploads/test_company/下的第一级子目录和文件。
立即学习“PHP免费学习笔记（深入）”；
使用PHP AWS SDK实现
使用PHP AWS SDK列出S3存储桶中指定路径下的第一级对象和子目录，主要通过S3Client的listObjects方法（或listObjectsV2方法，推荐用于分页）来完成。
1. 初始化S3客户端
首先，确保你的项目中已安装AWS SDK for PHP（通过Composer）。然后，初始化S3Client实例，提供你的AWS凭证和区域信息。
'latest', // 使用最新版本的API
'region' => 'your-aws-region', // 替换为你的AWS区域，例如 'us-east-1'
'credentials' => [
'key' => 'YOUR_AWS_ACCESS_KEY_ID', // 替换为你的AWS访问密钥ID
'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY', // 替换为你的AWS秘密访问密钥
],
]);
// 定义存储桶名称和目标路径前缀
$bucketName = 'your-s3-bucket-name'; // 替换为你的S3存储桶名称
$targetPrefix = 'public/uploads/test_company/'; // 目标路径，务必以斜杠结尾
// 如果要列出根目录，则Prefix为空字符串''2. 调用listObjects方法并解析结果
调用listObjects方法时，关键在于设置Bucket、Prefix和Delimiter参数。Prefix应是你希望列出其第一级内容的路径，并且通常以斜杠结尾以表示一个“目录”。Delimiter设置为/。
try {
// 调用listObjects方法，使用Prefix和Delimiter
$result = $s3Client->listObjects([
'Bucket' => $bucketName,
'Prefix' => $targetPrefix,
'Delimiter' => '/', // 关键参数，用于模拟目录结构
]);
echo "在路径 '{$targetPrefix}' 下找到的第一级对象和子目录：\n";
// 处理CommonPrefixes（代表子目录）
if (isset($result['CommonPrefixes'])) {
foreach ($result['CommonPrefixes'] as $commonPrefix) {
// commonPrefix['Prefix'] 会是 'public/uploads/test_company/test1/'
// 我们可以提取出子目录的相对名称
$fullPath = $commonPrefix['Prefix'];
$relativePath = rtrim(substr($fullPath, strlen($targetPrefix)), '/'); // 获取相对路径名
echo " - 子目录: {$fullPath} (相对名称: {$relativePath})\n";
}
}
// 处理Contents（代表直接位于当前Prefix下的文件）
if (isset($result['Contents'])) {
foreach ($result['Contents'] as $object) {
$key = $object['Key'];
// 确保不是Prefix本身（如果Prefix是一个空目录对象）
// 并且确保它不包含Delimeter在Prefix之后，这意味着它是直接的文件
if ($key !== $targetPrefix && strpos(substr($key, strlen($targetPrefix)), '/') === false) {
echo " - 文件: {$key}\n";
}
}
}
// 检查是否还有更多结果（分页）
if (isset($result['IsTruncated']) && $result['IsTruncated']) {
echo "\n注意：结果已被截断，可能还有更多对象。请处理分页。\n";
// 对于listObjects，可以使用 $result['NextMarker'] 作为下一次请求的 'Marker' 参数
// 推荐使用 listObjectsV2 并处理 'ContinuationToken' 进行更简洁的分页
}
} catch (AwsException $e) {
// 捕获并处理AWS SDK异常
echo "获取S3对象时发生错误: " . $e->getMessage() . "\n";
}
?>示例代码详解
- $s3Client->listObjects([...])：这是核心的API调用。
- 'Bucket' => $bucketName：指定要操作的S3存储桶。
- 'Prefix' => $targetPrefix：定义了我们想要搜索的“目录”路径。请注意，为了正确模拟目录行为，这个前缀通常需要以斜杠/结尾。如果Prefix是空字符串''，则会列出存储桶根目录下的第一级对象。
-
'Delimiter' => '/'：这个参数至关重要。它告诉S3将/视为路径分隔符。S3会根据这个分隔符将结果分为两部分：
- CommonPrefixes：包含所有直接子目录的前缀，例如public/uploads/test_company/test1/。这些是我们要找的“第一级子目录”。
- Contents：包含所有直接位于Prefix下且不包含Delimiter的实际文件。这些是我们要找的“第一级文件”。
-
结果处理：
- 遍历$result['CommonPrefixes']可以获取所有第一级子目录的完整路径。
- 遍历$result['Contents']可以获取所有直接位于$targetPrefix下的文件。我们通过strpos(substr($key, strlen($targetPrefix)), '/') === false来进一步过滤，确保这些文件确实是第一级的，而不是深层目录中的文件。
注意事项
- Prefix的末尾斜杠：当Prefix代表一个目录时，强烈建议以/结尾（例如myfolder/）。如果Prefix是myfolder，S3会返回所有以myfolder开头的对象，包括myfolder_backup/、myfolder_data/等，这可能不是你想要的结果。
-
分页处理：S3的listObjects操作默认最多返回1000个结果。如果你的目录包含大量对象，你需要处理分页。
- 对于listObjects，可以使用IsTruncated和NextMarker参数。当IsTruncated为true时，将NextMarker的值作为下一次请求的Marker参数，直到IsTruncated为false。
- 更推荐使用listObjectsV2方法，它提供了更现代的ContinuationToken机制来处理分页，逻辑更清晰。
- 错误处理：在实际应用中，务必使用try-catch块来捕获AwsException，处理可能发生的网络问题、权限不足等错误。
- 性能考虑：对于非常大的存储桶或频繁的列表操作，请注意API请求的成本和性能。合理设计Prefix可以减少不必要的扫描。
总结
通过巧妙地结合Prefix和Delimiter参数，PHP开发者可以利用AWS SDK for PHP高效且精确地获取S3存储桶中指定路径下的第一级对象（包括文件和模拟的子目录）。这种方法避免了递归遍历整个S3存储桶，显著提高了数据检索的效率和针对性，是管理S3内容的重要技巧。在实现时，请务必考虑分页和错误处理，以构建健壮的应用程序。
