本文详细介绍了如何在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的对象键进行分组。
-
作用:
- 它会返回所有在Prefix和第一个Delimiter之间没有其他Delimiter的“直接”对象（这些对象会在响应的Contents部分）。
- 更重要的是，它会返回所有在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桶中指定前缀下第一层对象的示例代码。
准备工作
首先，确保你已经安装了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";
}
?>代码解释
- S3客户端初始化: 使用你的AWS凭证和区域初始化S3Client。
- Bucket和Prefix: 指定你想要操作的S3桶名称和目标路径前缀。
- Delimiter: 将Delimiter设置为/。这是关键，它告诉S3将/视为目录分隔符。
-
结果处理:
- 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桶中特定路径下的顶层“目录”变得简单而直接。
