本教程详细介绍了如何利用 AWS SDK for PHP，通过巧妙结合 `Prefix` 和 `Delimiter` 参数，高效地从 Amazon S3 存储桶中仅获取指定路径下的第一层对象（包括文件和模拟目录）。文章将提供具体的代码示例，并解释如何解析返回结果以区分实际文件和子目录，确保开发者能够准确实现单层对象列表的需求，避免不必要的递归操作。
理解 S3 存储桶的层级结构与列表需求
Amazon S3 存储桶本身是一个扁平的存储空间，但通过对象键（Key）中的斜杠（/）可以模拟出目录结构。在实际应用中，我们经常需要像文件系统一样，只查看某个“目录”下的直接子文件和子目录，而不希望列出所有深层嵌套的对象。例如，如果你的 S3 存储桶中有以下对象键：
public/uploads/test_company/test1public/uploads/test_company/test2public/uploads/test_company/test1/test.txt
当你希望获取 public/uploads/test_company/ 路径下的第一层内容时，理想的结果是只得到 public/uploads/test_company/test1 和 public/uploads/test_company/test2，而忽略 public/uploads/test_company/test1/test.txt。
核心参数：Prefix 与 Delimiter
AWS S3 API 提供了 listObjects (或 listObjectsV2) 方法来检索存储桶中的对象。要实现单层列表，我们需要利用其两个关键参数：Prefix 和 Delimiter。
立即学习“PHP免费学习笔记（深入）”；
Prefix (前缀): 此参数用于筛选以指定字符串开头的所有对象。例如，设置 Prefix = ‘public/uploads/test_company/’ 将只返回所有以 public/uploads/test_company/ 开头的对象。Delimiter (分隔符): 这是实现单层列表的关键。当指定 Delimiter 时，S3 会将所有包含该分隔符且在 Prefix 范围内的对象进行分组。它不会返回包含分隔符的完整对象键，而是返回两类信息：Contents: 直接位于指定 Prefix 下且不包含 Delimiter 的对象。CommonPrefixes: 模拟的子目录。这些是 Prefix 后第一个 Delimiter 之前的部分，代表了下一级目录的名称。
通过同时设置 Prefix 和 Delimiter = ‘/’，S3 API 能够智能地返回指定路径下的直接文件和下一级目录。
PHP 实现单层对象列表
使用 AWS SDK for PHP 3.x，我们可以通过 S3Client 的 listObjects 方法来实现。
首先，确保你的 PHP 项目中已经安装了 AWS SDK：
composer require aws/aws-sdk-php
接下来，以下是一个 PHP 代码示例，展示如何获取 public/uploads/test_company/ 路径下的第一层对象：
'your-aws-region', // 例如 'us-east-1' 'version' => 'latest', // 如果需要，可以在这里指定凭证，但推荐使用环境变量或IAM角色 /* 'credentials' => [ 'key' => 'YOUR_AWS_ACCESS_KEY_ID', 'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY', ] */]);$bucketName = 'your-s3-bucket-name';$targetPrefix = 'public/uploads/test_company/'; // 注意以斜杠结尾，表示一个目录try { // 2. 调用 listObjects 方法，设置 Prefix 和 Delimiter $result = $s3Client->listObjects([ 'Bucket' => $bucketName, 'Prefix' => $targetPrefix, 'Delimiter' => '/', // 关键：指定斜杠作为分隔符 // 'MaxKeys' => 100, // 可选：限制返回的最大对象数量 ]); echo "Listing objects under: s3://{$bucketName}/{$targetPrefix}n"; echo "---------------------------------------------------n"; // 3. 处理返回结果 // 3.1 打印直接位于当前前缀下的文件 (Contents) if (isset($result['Contents'])) { foreach ($result['Contents'] as $object) { // 确保只打印当前层级的文件，不包括子目录本身作为文件 // S3 返回的 Key 会包含 Prefix，所以需要检查 $keyWithoutPrefix = substr($object['Key'], strlen($targetPrefix)); if (!empty($keyWithoutPrefix) && strpos($keyWithoutPrefix, '/') === false) { echo "File: " . $object['Key'] . " (Size: " . $object['Size'] . " bytes)n"; } } } else { echo "No direct files found at this level.n"; } // 3.2 打印子目录 (CommonPrefixes) if (isset($result['CommonPrefixes'])) { foreach ($result['CommonPrefixes'] as $commonPrefix) { // CommonPrefixes 已经是下一级目录的完整路径，以斜杠结尾 echo "Directory: " . $commonPrefix['Prefix'] . "n"; } } else { echo "No subdirectories found at this level.n"; } echo "---------------------------------------------------n";} catch (AwsException $e) { // 捕获并处理 AWS SDK 异常 echo "Error listing objects: " . $e->getMessage() . "n";} catch (Exception $e) { // 捕获其他通用异常 echo "An unexpected error occurred: " . $e->getMessage() . "n";}?>
示例输出（基于问题描述的键）：
假设你的 S3 存储桶中有以下对象：
public/uploads/test_company/test1public/uploads/test_company/test2public/uploads/test_company/test1/test.txtpublic/uploads/test_company/another_file.pdf
当 targetPrefix 设置为 public/uploads/test_company/ 时，你可能会得到类似这样的输出：
Listing objects under: s3://your-s3-bucket-name/public/uploads/test_company/---------------------------------------------------File: public/uploads/test_company/another_file.pdf (Size: XXX bytes)Directory: public/uploads/test_company/test1/Directory: public/uploads/test_company/test2/---------------------------------------------------
请注意，test1 和 test2 在 S3 中实际上是对象键的一部分，但由于 Delimiter 的作用，它们被识别为 CommonPrefixes，模拟了目录。如果 public/uploads/test_company/test1 实际上是一个零字节文件，它会出现在 Contents 中，而 public/uploads/test_company/test1/ 作为一个 CommonPrefix 出现。
注意事项与最佳实践
Prefix 的结尾斜杠: 强烈建议 Prefix 以斜杠 / 结尾，这明确表示你正在查找一个“目录”下的内容。如果 Prefix 不以斜杠结尾，例如 public/uploads/test_company，那么 S3 会返回所有以该字符串开头的对象，包括 public/uploads/test_company_backup 等，这可能不是你期望的结果。
分页处理: 对于包含大量对象的存储桶，listObjects 的结果是分页的。默认情况下，MaxKeys 可能限制为 1000 个结果。如果返回结果中存在 IsTruncated 字段且为 true，则表示还有更多结果。你需要使用 Marker (或 ContinuationToken 对于 listObjectsV2) 参数进行后续请求来获取所有数据。
$marker = null;do { $params = [ 'Bucket' => $bucketName, 'Prefix' => $targetPrefix, 'Delimiter' => '/', 'Marker' => $marker, // 在后续请求中使用上一次的 NextMarker ]; $result = $s3Client->listObjects($params); // 处理 $result['Contents'] 和 $result['CommonPrefixes'] $marker = $result['NextMarker'] ?? null; // 获取下一次请求的 Marker} while ($marker);
错误处理: 务必在代码中加入 try-catch 块来捕获 AwsException 或其他潜在的异常，以提高代码的健壮性。
权限: 确保你的 AWS 凭证拥有对目标 S3 存储桶执行 s3:ListBucket 操作的权限。
listObjectsV2: AWS 推荐使用 listObjectsV2 方法，它提供了更现代的翻页机制 (ContinuationToken)。其参数和用法与 listObjects 类似。
总结
通过精确设置 Prefix 和 Delimiter 参数，AWS SDK for PHP 提供了强大而灵活的方式来控制 S3 对象列表的行为。这种方法不仅能帮助你高效地获取指定路径下的单层对象，还能清晰地区分文件和模拟目录，从而更好地管理和展示 S3 存储桶中的内容。理解并熟练运用这两个参数是进行 S3 开发的关键技能之一。
以上就是使用 PHP 在 S3 存储桶中获取单层对象列表教程的详细内容，更多请关注php中文网其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1337772.html
微信扫一扫 
支付宝扫一扫 
