使用PHP SDK高效列出S3桶指定前缀下的顶层对象

本文详细介绍了如何在php中使用aws sdk，通过`listobjects`方法结合`prefix`和`delimiter`参数，精准地从amazon s3桶中获取指定路径下的第一层对象（即模拟子目录），而不会递归列出深层文件或子目录。通过实例代码，演示了如何配置请求参数并处理返回结果，以实现对s3对象列表的精细化控制，有效模拟文件系统层级结构。

理解S3的扁平结构与层级模拟

Amazon S3本质上是一个扁平的对象存储服务，它不直接支持传统文件系统中的目录或文件夹概念。所有的"文件"（对象）都存储在一个桶中，并通过唯一的键（Key）来标识。然而，为了方便用户管理和理解，S3允许通过键的命名约定（通常使用斜杠/作为分隔符）来模拟目录结构。

在某些场景下，我们可能需要列出某个特定“目录”下的第一层“子目录”或“文件”，而不希望深入到更深的层级。例如，给定一个路径public/uploads/test_company/，我们只想获取public/uploads/test_company/test1和public/uploads/test_company/test2这样的顶层对象（或模拟的子目录），而忽略public/uploads/test_company/test1/test.txt这类深层文件。

为了实现这一目标，AWS S3的listObjects（或listObjectsV2）API提供了Prefix和Delimiter这两个关键参数。

核心参数详解：Prefix 与 Delimiter

Prefix（前缀）

Prefix参数用于过滤结果，只返回键名以指定字符串开头的所有对象。它相当于在文件系统中进入一个特定目录。

立即学习“PHP免费学习笔记（深入）”；

• 作用: 将列表范围限定在所有键名都以给定前缀开始的对象。
• 示例: 如果Prefix设置为public/uploads/test_company/，则所有以该字符串开头的对象（包括public/uploads/test_company/test1、public/uploads/test_company/test2、public/uploads/test_company/test1/test.txt等）都将被考虑。

Delimiter（分隔符）

Delimiter参数是实现单层列表的关键。当指定了分隔符时，S3会根据这个分隔符对匹配Prefix的对象键进行分组。

• 作用:
  1. 它会返回所有在Prefix和第一个Delimiter之间没有其他Delimiter的“直接”对象（这些对象会在响应的Contents部分）。
  2. 更重要的是，它会返回所有在Prefix之后、第一个Delimiter之前存在一个Delimiter的“共同前缀”（CommonPrefixes）。这些共同前缀实际上就是我们所说的“子目录”。
• 示例: 如果Prefix是public/uploads/test_company/，Delimiter是/：
  • S3会查找所有以public/uploads/test_company/开头，并且在public/uploads/test_company/之后、下一个/之前没有其他/的对象。
  • 对于public/uploads/test_company/test1/test.txt，它的共同前缀是public/uploads/test_company/test1/。
  • 对于public/uploads/test_company/test2，它是一个直接对象（如果test2不是以/结尾的）。但如果test2本身是一个模拟的目录，其内部有文件，那么test2/将作为一个共同前缀返回。

通过同时使用Prefix和Delimiter，我们可以有效地告诉S3：“给我列出在Prefix路径下，以Delimiter作为层级分隔符的第一层所有内容。”

使用PHP SDK实现单层对象列表

下面是使用AWS SDK for PHP 3.x 来获取S3桶中指定前缀下第一层对象的示例代码。

BlessAI

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

89

查看详情

准备工作

首先，确保你已经安装了AWS SDK for PHP：

composer require aws/aws-sdk-php

然后，配置你的AWS凭证和区域。

示例代码

<?php

require 'vendor/autoload.php';

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',
    ],
]);

// 2. 定义桶名和目标前缀
$bucketName = 'your-s3-bucket-name'; // 替换为你的S3桶名
$targetPrefix = 'public/uploads/test_company/'; // 目标路径前缀

try {
    // 3. 调用listObjects方法，并设置Prefix和Delimiter
    $result = $s3Client->listObjects([
        'Bucket'    => $bucketName,
        'Prefix'    => $targetPrefix,
        'Delimiter' => '/', // 使用斜杠作为分隔符，模拟目录层级
    ]);

    echo "Listing top-level objects under: " . $targetPrefix . "\n";

    // 4. 处理返回结果：CommonPrefixes 和 Contents

    // CommonPrefixes 包含模拟的子目录
    if (isset($result['CommonPrefixes'])) {
        echo "\n--- Simulated Subdirectories (CommonPrefixes) ---\n";
        foreach ($result['CommonPrefixes'] as $commonPrefix) {
            // CommonPrefixes会包含完整的路径，且通常以分隔符结尾，例如 "public/uploads/test_company/test1/"
            $folderName = rtrim($commonPrefix['Prefix'], '/'); // 移除末尾的斜杠
            echo "Folder: " . $folderName . "\n";
        }
    } else {
        echo "No simulated subdirectories found.\n";
    }

    // Contents 包含直接在该Prefix下的文件（不包含子目录内的文件）
    if (isset($result['Contents'])) {
        echo "\n--- Direct Files (Contents) ---\n";
        foreach ($result['Contents'] as $object) {
            // 确保这个对象不是Prefix本身（如果Prefix以/结尾，S3可能会将其自身作为一个空对象返回）
            if ($object['Key'] !== $targetPrefix) {
                echo "File: " . $object['Key'] . " (Size: " . $object['Size'] . " bytes)\n";
            }
        }
    } else {
        echo "No direct files found at this level.\n";
    }

} catch (AwsException $e) {
    // 捕获S3操作可能抛出的异常
    echo "Error listing objects: " . $e->getMessage() . "\n";
}

?>

代码解释

1. S3客户端初始化: 使用你的AWS凭证和区域初始化S3Client。
2. Bucket和Prefix: 指定你想要操作的S3桶名称和目标路径前缀。
3. Delimiter: 将Delimiter设置为/。这是关键，它告诉S3将/视为目录分隔符。
4. 结果处理:
   • CommonPrefixes: 这是我们主要关注的部分。当Delimiter被使用时，S3会将所有匹配Prefix但被Delimiter分隔的下一级路径作为CommonPrefixes返回。这些就是我们想要的“顶层对象”或“子目录”。注意，CommonPrefixes中的Prefix值通常会以分隔符（/）结尾，你可以使用rtrim()函数去除它，以获得纯粹的目录名。
   • Contents: 这部分会包含直接位于Prefix路径下的文件，即在Prefix之后直到第一个Delimiter之间没有任何Delimiter的对象。如果你的目标是只获取模拟的子目录，可以忽略这部分。

针对原始问题的输出

根据问题中提供的键：

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

如果targetPrefix设置为public/uploads/test_company/，Delimiter设置为/，那么上述代码的$result['CommonPrefixes']部分将包含：

• Prefix: public/uploads/test_company/test1/
• Prefix: public/uploads/test_company/test2/

而$result['Contents']部分将为空，因为test1和test2被视为共同前缀的一部分，而不是直接的文件。如果有一个对象键是public/uploads/test_company/direct_file.txt，那么它会出现在Contents中。

注意事项与最佳实践

• 分页处理: 对于包含大量对象（超过1000个）的桶，listObjects默认只会返回前1000个结果。你需要使用MaxKeys和Marker（或ContinuationToken对于listObjectsV2）参数来实现分页，循环获取所有结果。
• 性能考虑: 频繁地调用listObjects可能会产生额外的费用和延迟。尽可能优化你的存储结构和访问模式。
• 权限: 确保你的AWS凭证拥有对S3桶执行s3:ListBucket操作的权限。
• listObjectsV2: AWS推荐使用listObjectsV2而非listObjects，因为它提供了更好的分页机制（StartAfter和ContinuationToken）。其参数和行为与listObjects在Prefix和Delimiter方面是相同的。

总结

通过巧妙地结合Prefix和Delimiter参数，AWS S3的listObjects（或listObjectsV2）API为我们提供了一种强大而灵活的方式，以模拟文件系统层级结构来浏览和管理S3对象。理解这两个参数的工作原理，特别是Delimiter如何生成CommonPrefixes，是高效利用S3进行对象列表操作的关键。这使得在PHP应用中获取S3桶中特定路径下的顶层“目录”变得简单而直接。

以上就是使用PHP SDK高效列出S3桶指定前缀下的顶层对象的详细内容，更多请关注php中文网其它相关文章！