如何在Amazon S3 ListObjectsV2中跳过前n个键？

问题背景 #

我当前使用AWS S3 PHP SDK的listObjectsV2方法列出存储桶中的文件，代码如下：

$contents = $this->s3client->listObjectsV2([
    'Bucket' => $this->bucket_name,
    'ContinuationToken' => $continuationToken,
    'Prefix' => $prefix,
    'Delimiter' => $delimiter
]);

return $contents;

我知道可以通过MaxKeys、ContinuationToken和StartAfter控制返回结果，但需要实现跳过前N个键的需求：比如当MaxKeys=5时接口返回[1,2,3,4,5]，我需要跳过前2个，保持MaxKeys为5，最终返回[3,4,5]。而且这个N可能是2、20、200或任意数值，StartAfter无法满足这种任意跳过的需求。

解决方案：手动分页遍历并跳过指定数量 #

S3的listObjectsV2 API本身没有提供直接跳过N个对象的参数，因此需要通过手动分页遍历，累计跳过的对象数量，直到达到目标跳过数后，再收集剩余对象直到满足MaxKeys的限制。

以下是封装好的实现代码：

function listObjectsWithSkip($s3Client, $bucketName, $prefix = '', $delimiter = '', $skipCount = 0, $maxKeys = 1000) {
    $skipped = 0;
    $resultObjects = [];
    $continuationToken = null;

    do {
        // 构建请求参数
        $params = [
            'Bucket' => $bucketName,
            'Prefix' => $prefix,
            'Delimiter' => $delimiter,
            'MaxKeys' => $maxKeys
        ];
        if ($continuationToken) {
            $params['ContinuationToken'] = $continuationToken;
        }

        // 调用S3接口
        $response = $s3Client->listObjectsV2($params);
        $contents = $response['Contents'] ?? [];

        foreach ($contents as $object) {
            if ($skipped < $skipCount) {
                // 跳过当前对象
                $skipped++;
                continue;
            }

            // 收集对象，直到达到MaxKeys限制
            $resultObjects[] = $object;
            if (count($resultObjects) >= $maxKeys) {
                break 2; // 跳出foreach和do-while循环
            }
        }

        // 更新分页令牌
        $continuationToken = $response['NextContinuationToken'] ?? null;
    } while ($continuationToken && count($resultObjects) < $maxKeys);

    return $resultObjects;
}

使用示例 #

// 跳过前2个对象，最多返回5个
$filteredContents = listObjectsWithSkip(
    $this->s3client,
    $this->bucket_name,
    $prefix,
    $delimiter,
    2, // 要跳过的数量
    5  // MaxKeys
);

补充说明 #

1. 边界情况处理：如果要跳过的数量skipCount大于存储桶中符合条件的总对象数，函数会返回空数组。
2. API调用次数：如果skipCount较大（比如200），可能需要多次调用listObjectsV2来遍历足够的对象，这符合S3的分页设计，无需额外优化。
3. 关于StartAfter：如果你的对象键有严格的排序规律（比如按名称连续递增），可以先通过遍历获取第N个对象的键，再用StartAfter直接定位，但这种方法仅适用于键可预测的场景，无法覆盖任意跳过的需求。

内容的提问来源于stack exchange，提问作者Bilaal Abdel Hassan