使用 PHP 在 S3 存储桶中获取单层对象列表教程

本教程详细介绍了如何利用 AWS SDK for PHP，通过巧妙结合 `Prefix` 和 `Delimiter` 参数，高效地从 Amazon S3 存储桶中仅获取指定路径下的第一层对象（包括文件和模拟目录）。文章将提供具体的代码示例，并解释如何解析返回结果以区分实际文件和子目录，确保开发者能够准确实现单层对象列表的需求，避免不必要的递归操作。

理解 S3 存储桶的层级结构与列表需求

Amazon S3 存储桶本身是一个扁平的存储空间，但通过对象键（Key）中的斜杠（/）可以模拟出目录结构。在实际应用中，我们经常需要像文件系统一样，只查看某个“目录”下的直接子文件和子目录，而不希望列出所有深层嵌套的对象。例如，如果你的 S3 存储桶中有以下对象键：

• public/uploads/test_company/test1
• public/uploads/test_company/test2
• public/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免费学习笔记（深入）”；

1. Prefix (前缀): 此参数用于筛选以指定字符串开头的所有对象。例如，设置 Prefix = 'public/uploads/test_company/' 将只返回所有以 public/uploads/test_company/ 开头的对象。
2. 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/ 路径下的第一层对象：

<?php

require 'vendor/autoload.php';

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

// 1. 配置 S3 客户端
// 确保你的 AWS 凭证已通过环境变量、配置文件或直接在代码中配置
// 例如：AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY
$s3Client = new S3Client([
    'region' => '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";
}

?>

示例输出（基于问题描述的键）：

BlessAI

Bless AI 提供五个独特的功能：每日问候、庆祝问候、祝福、祷告和名言的文本生成和图片生成。

89

查看详情

假设你的 S3 存储桶中有以下对象：

• public/uploads/test_company/test1
• public/uploads/test_company/test2
• public/uploads/test_company/test1/test.txt
• public/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 出现。

注意事项与最佳实践

1. Prefix 的结尾斜杠: 强烈建议 Prefix 以斜杠 / 结尾，这明确表示你正在查找一个“目录”下的内容。如果 Prefix 不以斜杠结尾，例如 public/uploads/test_company，那么 S3 会返回所有以该字符串开头的对象，包括 public/uploads/test_company_backup 等，这可能不是你期望的结果。

2. 分页处理: 对于包含大量对象的存储桶，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);

   登录后复制

3. 错误处理: 务必在代码中加入 try-catch 块来捕获 AwsException 或其他潜在的异常，以提高代码的健壮性。

4. 权限: 确保你的 AWS 凭证拥有对目标 S3 存储桶执行 s3:ListBucket 操作的权限。

5. listObjectsV2: AWS 推荐使用 listObjectsV2 方法，它提供了更现代的翻页机制 (ContinuationToken)。其参数和用法与 listObjects 类似。

总结

通过精确设置 Prefix 和 Delimiter 参数，AWS SDK for PHP 提供了强大而灵活的方式来控制 S3 对象列表的行为。这种方法不仅能帮助你高效地获取指定路径下的单层对象，还能清晰地区分文件和模拟目录，从而更好地管理和展示 S3 存储桶中的内容。理解并熟练运用这两个参数是进行 S3 开发的关键技能之一。

以上就是使用 PHP 在 S3 存储桶中获取单层对象列表教程的详细内容，更多请关注php中文网其它相关文章！