使用PHP SDK获取S3桶指定前缀下的单层对象列表

本文详细介绍了如何利用aws php sdk，通过s3 listobjects api的prefix和delimiter参数，高效地获取amazon s3存储桶中指定前缀下的单层对象和“子目录”列表。这种方法能有效避免递归遍历，实现类似文件系统目录结构的单层视图，适用于需要快速定位下一级资源的应用场景。

在Amazon S3中，对象存储的扁平特性意味着没有传统意义上的“文件夹”或“目录”。然而，通过巧妙地利用对象键（Key）中的斜杠（/），我们可以模拟出目录结构。当需要列出某个“目录”下的直接子“目录”或文件，而不深入其内部时，AWS S3的listObjects API提供了两个关键参数：Prefix和Delimiter。

理解核心参数：Prefix 与 Delimiter

Prefix (前缀): 此参数用于筛选结果，使其仅包含以指定字符串开头的对象。例如，设置Prefix为public/uploads/test_company/，则所有返回的对象键都将以此字符串开头。
Delimiter (分隔符): 这是实现单层列表的关键。当设置了Delimiter时（通常是/），S3 API会将其视为一个目录分隔符。这意味着：
- listObjects将只返回在指定Prefix下、且在第一个Delimiter之前结束的对象（即直接位于该“目录”下的文件）。
- 它还会返回一个名为CommonPrefixes的列表，其中包含了所有直接位于Prefix下、以Delimiter结尾的“子目录”名称。这些“子目录”本身并不是对象，而是S3为了模拟目录结构而聚合的键前缀。

结合这两个参数，我们可以实现只获取指定路径下第一级“子目录”和文件的需求。例如，如果我们的对象键有：

public/uploads/test_company/test1
public/uploads/test_company/test2
public/uploads/test_company/test1/test.txt

当设置Prefix为public/uploads/test_company/，Delimiter为/时，S3将返回：

在CommonPrefixes中包含：public/uploads/test_company/test1/ 和 public/uploads/test_company/test2/。
Contents列表将为空（因为没有直接位于public/uploads/test_company/且不包含进一步斜杠的对象）。

通过处理CommonPrefixes，我们就能得到所需的test1和test2。

PHP SDK 实现示例

以下是使用AWS PHP SDK v3实现这一功能的代码示例：

require 'vendor/autoload.php'; // 假设已通过Composer安装AWS SDK

use Aws\S3\S3Client; use Aws\Exception\AwsException;

// 1. 初始化S3客户端 // 请替换为您的AWS区域和凭证信息 $s3Client = new S3Client([ 'version' => 'latest', 'region' => 'your-aws-region', // 例如: 'us-east-1' 'credentials' => [ 'key' => 'YOUR_AWS_ACCESS_KEY_ID', 'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY', ], ]);

$bucketName = 'your-s3-bucket-name'; // 您的S3存储桶名称 $targetPrefix = 'public/uploads/test_company/'; // 目标前缀，通常以'/'结尾

try { // 2. 调用 listObjects 方法，并设置 Prefix 和 Delimiter $result = $s3Client->listObjects([ 'Bucket' => $bucketName, 'Prefix' => $targetPrefix, 'Delimiter' => '/', ]);

echo "在 '{$targetPrefix}' 下找到的顶级子项:\n";

// 3. 处理 CommonPrefixes (模拟的子目录)
if (isset($result['CommonPrefixes'])) {
    foreach ($result['CommonPrefixes'] as $commonPrefix) {
        // commonPrefix['Prefix'] 的格式为 'public/uploads/test_company/test1/'
        // 我们需要提取 'test1'
        $folderName = rtrim(str_replace($targetPrefix, '', $commonPrefix['Prefix']), '/');
        echo "- 子目录: {$folderName}\n";
    }
}

// 4. 处理 Contents (直接位于当前前缀下的文件，不含Delimiter)
// 在本例中，如果 'test1' 和 'test2' 是唯一的顶级项，此列表可能为空。
// 如果有文件如 'public/uploads/test_company/report.pdf'，它将出现在这里。
if (isset($result['Contents'])) {
    foreach ($result['Contents'] as $object) {
        $objectKey = $object['Key'];
        // 确保是直接子文件，而不是深层文件
        // 检查对象键是否直接在目标前缀下，且不包含额外的斜杠
        $relativeKey = str_replace($targetPrefix, '', $objectKey);
        if (!empty($relativeKey) && strpos($relativeKey, '/') === false) {
             echo "- 文件: {$relativeKey}\n";
        }
    }
}

} catch (AwsException $e) { // 错误处理 echo "列出S3对象时发生错误: " . $e->getMessage(); }

注意事项与最佳实践

Prefix的结尾斜杠: 当您希望列出某个“目录”下的内容时，Prefix通常应以/结尾。例如，public/uploads/test_company/。如果不以斜杠结尾，例如public/uploads/test_company，则可能会匹配到以test_company开头的所有对象，包括public/uploads/test_company_new/file.txt，这不是我们期望的“目录”行为。
分页处理: 对于包含大量对象（超过1000个）的存储桶，listObjects API会进行分页。您需要检查返回结果中的IsTruncated字段和NextMarker（或使用listObjectsV2的ContinuationToken）来迭代获取所有结果。
性能考虑: 尽管S3的列表操作速度很快，但频繁或大规模地列出对象仍然会产生开销。设计应用时应考虑缓存机制或事件驱动的更新。
错误处理: 务必在实际应用中加入健壮的错误处理逻辑，捕获AwsException以应对网络问题、权限不足等情况。

总结

通过巧妙地结合使用listObjects API的Prefix和Delimiter参数，AWS PHP SDK能够轻松实现S3存储桶

# php # composer # access # pdf # 网络问题 # red # echo # catch # 字符串 # 递归 # public # 对象 # 事件 # 您的 # 分页 # 为空 # 不包含 # 这是 # 这一 # 分隔符 # 在这里 # 第一个

返回目录在线咨询

上一篇：详解Web使用webpack构建前端项目
下一篇：什么是技术SEO，涉及哪些方面_SEO优化教程

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

全网整合营销服务商

使用PHP SDK获取S3桶指定前缀下的单层对象列表

理解核心参数：Prefix 与 Delimiter

PHP SDK 实现示例

注意事项与最佳实践

总结

您的项目需求