Amazon Simple Storage Service
开发人员指南 (API 版本 2006-03-01)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

列出启用版本控制的存储桶中的对象

此部分提供从启用版本控制的存储桶列出对象版本的示例。Amazon S3 将对象版本信息存储在与存储桶关联的 versions 子资源中 (请参阅存储桶配置选项)。

使用控制台

有关使用 Amazon S3 控制台列出对象版本的信息,请参阅如何查看 S3 对象的版本? (在 Amazon Simple Storage Service 控制台用户指南 中)。

使用 AWS 开发工具包

此部分中的示例说明如何从启用了版本控制的存储桶中检索对象列表。每个请求最多返回 1000 个版本,除非您指定一个较小的数字。如果存储桶包含的版本数超过此限制,请发送一系列请求来检索所有版本的列表。以“页面”形式返回结果的过程称为分页。为了说明分页的工作原理,该示例将每个响应限制为两个对象版本。在检索第一页结果后,每个示例将检查以确定版本列表是否已被截断。如果是,示例将继续检索页面,直至检索到所有版本。

注意

以下示例还使用未启用版本控制的存储桶或用于没有单独版本的对象。在这些情况下,Amazon S3 将返回版本 ID 为 null 的对象列表。

有关使用其他 AWS 开发工具包的信息,请参阅示例代码和库

使用 AWS SDK for Java

有关创建和测试有效示例的说明,请参阅测试 Amazon S3 Java 代码示例

import java.io.IOException; import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.model.ListVersionsRequest; import com.amazonaws.services.s3.model.S3VersionSummary; import com.amazonaws.services.s3.model.VersionListing; public class ListKeysVersioningEnabledBucket { public static void main(String[] args) throws IOException { String clientRegion = "*** Client region ***"; String bucketName = "*** Bucket name ***"; try { AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withCredentials(new ProfileCredentialsProvider()) .withRegion(clientRegion) .build(); // Retrieve the list of versions. If the bucket contains more versions // than the specified maximum number of results, Amazon S3 returns // one page of results per request. ListVersionsRequest request = new ListVersionsRequest() .withBucketName(bucketName) .withMaxResults(2); VersionListing versionListing = s3Client.listVersions(request); int numVersions = 0, numPages = 0; while(true) { numPages++; for (S3VersionSummary objectSummary : versionListing.getVersionSummaries()) { System.out.printf("Retrieved object %s, version %s\n", objectSummary.getKey(), objectSummary.getVersionId()); numVersions++; } // Check whether there are more pages of versions to retrieve. If // there are, retrieve them. Otherwise, exit the loop. if(versionListing.isTruncated()) { versionListing = s3Client.listNextBatchOfVersions(versionListing); } else { break; } } System.out.println(numVersions + " object versions retrieved in " + numPages + " pages"); } catch(AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it, so it returned an error response. e.printStackTrace(); } catch(SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } }

使用适用于 .NET 的 AWS 开发工具包

有关如何创建和测试有效示例的信息,请参阅 运行 Amazon S3 .NET 代码示例

// Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-s3-developer-guide/blob/master/LICENSE-SAMPLECODE.) using Amazon.S3; using Amazon.S3.Model; using System; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class ListObjectsVersioningEnabledBucketTest { static string bucketName = "*** bucket name ***"; // Specify your bucket region (an example region is shown). private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2; private static IAmazonS3 s3Client; public static void Main(string[] args) { s3Client = new AmazonS3Client(bucketRegion); GetObjectListWithAllVersionsAsync().Wait(); } static async Task GetObjectListWithAllVersionsAsync() { try { ListVersionsRequest request = new ListVersionsRequest() { BucketName = bucketName, // You can optionally specify key name prefix in the request // if you want list of object versions of a specific object. // For this example we limit response to return list of 2 versions. MaxKeys = 2 }; do { ListVersionsResponse response = await s3Client.ListVersionsAsync(request); // Process response. foreach (S3ObjectVersion entry in response.Versions) { Console.WriteLine("key = {0} size = {1}", entry.Key, entry.Size); } // If response is truncated, set the marker to get the next // set of keys. if (response.IsTruncated) { request.KeyMarker = response.NextKeyMarker; request.VersionIdMarker = response.NextVersionIdMarker; } else { request = null; } } while (request != null); } catch (AmazonS3Exception e) { Console.WriteLine("Error encountered on server. Message:'{0}' when writing an object", e.Message); } catch (Exception e) { Console.WriteLine("Unknown encountered on server. Message:'{0}' when writing an object", e.Message); } } } }

使用 REST API

要列出存储桶中所有对象的所有版本,请在 GET Bucket 请求中使用 versions 子资源。Amazon S3 最多只能检索 1000 个对象,且每个对象版本都将计为一个完整的对象。因此,如果存储桶包含两个键 (例如 photo.gifpicture.jpg),并且第一个键有 990 个版本,第二个键有 400 个版本,则单个请求将检索 photo.gif 的所有 990 个版本,另加 picture.jpg 的最近 10 个版本。

Amazon S3 按照存储顺序返回对象版本,最先返回最近存储的版本。

在存储桶中列出所有对象版本的步骤

  • GET Bucket 请求中,包含 versions 子资源。

    GET /?versions HTTP/1.1 Host: bucketName.s3.amazonaws.com.cn Date: Wed, 28 Oct 2009 22:32:00 +0000 Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

检索存储桶中对象的子集

此部分讨论以下两个示例场景:

  • 您希望检索存储桶中所有对象版本的子集,例如检索特定对象的所有版本。

  • 响应中对象版本的数目超过 max-key 的值 (默认情况下为 1000),因此您必须再提交一个请求以检索其余的对象版本。

要检索对象版本的子集,请为 GET Bucket 使用请求参数。有关更多信息,请参阅 GET Bucket

示例 1:仅检索特定对象的所有版本

您可以通过以下过程,使用 versions 子资源和 prefix 请求参数检索某对象的所有版本。有关 prefix 的更多信息,请参阅 GET Bucket

检索键的所有版本

1 prefix 参数设置为您要检索的对象的键。
2

使用 versions 子资源和 prefix 发送 GET Bucket 请求。

GET /?versions&prefix=objectName HTTP/1.1

例 使用前缀检索对象

以下示例将检索其键是 myObject 或由它开头的对象。

GET /?versions&prefix=myObject HTTP/1.1 Host: bucket.s3.amazonaws.com.cn Date: Wed, 28 Oct 2009 22:32:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

您可以使用其他请求参数来检索对象的所有版本的子集。有关更多信息,请参阅 GET Bucket

示例 2:在响应截断时检索其他对象的列表

如果可以在 GET 请求中返回的对象数量超过 max-keys 的值,则响应将包含 <isTruncated>true</isTruncated>,并包含满足该请求但不会返回的第一个键 (在 NextKeyMarker 中) 和第一个版本 ID (在 NextVersionIdMarker 中)。您可以在后续请求中将这些返回的值用作开始位置,以检索满足 GET 请求的其他对象。

使用以下过程从存储桶中检索满足原始 GET Bucket versions 请求的其他对象。有关 key-markerversion-id-markerNextKeyMarkerNextVersionIdMarker 的更多信息,请参阅 GET Bucket

检索满足原始 GET 请求的其他响应

1 key-marker 的值设置为在上一个响应中的 NextKeyMarker 中返回的键。
2 version-id-marker 的值设置为在上一个响应中的 NextVersionIdMarker 中返回的版本 ID。
3 使用 key-markerversion-id-marker 发送 GET Bucket versions 请求。

例 检索从指定的密钥和版本 ID 开始的数据元

GET /?versions&key-marker=myObject&version-id-marker=298459348571 HTTP/1.1 Host: bucket.s3.amazonaws.com.cn Date: Wed, 28 Oct 2009 22:32:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=