上传对象 - Amazon Simple Storage Service
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

欢迎使用新的 Amazon S3 用户指南! Amazon S3 用户指南结合了以下三个已停用的指南中的信息和说明:Amazon S3 开发人员指南Amazon S3 控制台用户指南Amazon S3 入门指南

上传对象

在您将文件上传至 Amazon S3 时,文件会被存储为 S3 对象。对象由文件数据和描述对象的元数据组成。一个存储桶中可以有无限量的对象。您需要拥有存储桶写入权限,才能将文件上传至 Amazon S3 存储桶。有关访问权限的更多信息,请参阅Amazon S3 中的 Identity and Access Management

您可以将任何类型的文件上传至 S3 存储桶,包括映像、备份、数据、电影等。可使用 Amazon S3 控制台上传的文件的最大大小为 160 GB。要上传大于 160 GB 的文件,请使用 AWS CLI、AWS 开发工具包或 Amazon S3 REST API。

如果启用了版本控制的存储桶中已存在所上传对象的键名,则 Amazon S3 会创建该对象的另一个版本,而不是替换现有对象。有关版本控制的更多信息,请参阅使用 S3 控制台

根据上传的数据大小,Amazon S3 提供以下选项:

  • 使用 AWS 开发工具包、REST API 或 AWS CLI 在单个操作中上传对象 — 您可以在单个 PUT 操作中上传最大为 5 GB 的单个对象。

  • 使用 Amazon S3 控制台上传单个对象 — 通过 Amazon S3 控制台,您可以上传最大 160 GB 的单个对象。

  • 使用 AWS 开发工具包、REST API 或 AWS CLI 分段上传对象 — 您可以使用分段上传 API 来上传单个大对象(最大大小为 5 TB)。

    分段上传 API 旨在改进大型对象的上传体验。您可以分段上传对象。这些对象分段可以按任何顺序并行独立上传。您可以对大小在 5 MB 到 5 TB 范围内的对象使用分段上传。有关更多信息,请参阅 使用分段上传来上传和复制对象

在上传对象时,您可以选择请求 Amazon S3 在将对象保存到磁盘之前对其进行加密,并在下载时对其进行解密。有关更多信息,请参阅 使用加密保护数据

此过程介绍了如何使用控制台将对象和文件夹上传到 S3 存储桶。

上传对象时,对象键名称是文件名和任何可选前缀。在 Amazon S3 控制台中,您可以创建文件夹来组织对象。在 Amazon S3 中,文件夹表示为出现在对象键名称中的前缀。如果您将单个对象上传到 Amazon S3 控制台中的文件夹,则文件夹名称将包含在对象键名称中。

例如,如果您将名为的对象上传 sample1.jpg 到名为 backup 的文件夹,则密钥名称为 backup/sample1.jpg。但是在控制台中,对象在 sample1.jpg 文件夹中显示为 backup。有关键名称的更多信息,请参阅使用对象元数据

注意

如果在 S3 控制台中重命名对象或更改存储类加密元数据属性,则将创建一个新对象来替换旧对象。如果启用 S3 版本控制,则会创建对象的新版本,而现有对象将变为旧版本。更改属性的角色还会成为新对象或(对象版本)的拥有者。

上传文件夹时,Amazon S3 会将所有文件和子文件夹从指定文件夹中上传至存储桶。然后,它会分配由上传文件名和文件夹名组成的对象键名。例如,如果您上传包含 sample1.jpgsample2.jpg 这两个文件的名为 /images 的文件夹,则 Amazon S3 会上传这两个文件,然后分配相应的键名 images/sample1.jpgimages/sample2.jpg。键名包括作为前缀的文件夹名。Amazon S3 控制台仅显示最后一个“/”后面的键名部分。例如,在图像文件夹中,images/sample1.jpgimages/sample2.jpg 对象显示为 sample1.jpgsample2.jpg

将文件夹和文件上传到 S3 存储桶

  1. 登录 AWS 管理控制台,并通过以下网址打开 Amazon S3 控制台:https://console.aws.amazon.com/s3/

  2. Buckets (存储桶) 列表中,选择要将文件夹和文件上传到的存储桶的名称。

  3. 选择 Upload

  4. 上传窗口中,执行下列操作之一:

    • 将文件和文件夹拖放到上传窗口。

    • 选择添加文件添加文件夹,选择要上传的文件或文件夹,然后选择打开

  5. 要启用版本控制,请在目标下选择启用存储桶版本控制

  6. 要上传列出的文件和文件夹而不配置其他上传选项,请选择页面底部的上传

    Amazon S3 会上传您的对象和文件夹。上传完成后,您可以在上传:状态页面上看到成功消息。

  7. 要在上传之前配置其他对象属性,请参阅 配置其他对象属性

配置其他对象属性

  1. 要配置其他对象属性,请选择其他上传选项

  2. 存储类下,为正在上传的文件选择存储类。

    有关存储类别的更多信息,请参阅 使用 Amazon S3 存储类

  3. 要更新对象的加密设置,请在服务器端加密设置下执行以下操作:

    1. 选择覆盖默认加密存储桶设置

    2. 要使用由 Amazon S3 托管的密钥加密上传的文件,请选择 Amazon S3 key (SSE-S3)

      有关更多信息,请参阅 使用具有 Amazon S3 托管加密密钥的服务器端加密 (SSE-S3) 保护数据

    3. 要使用 AWS Key Management Service (AWS KMS) 加密上传的文件,请选择 AWS Key Management Service key (SSE-KMS)。然后为 AWS KMS 密钥选择一个选项。

      • AWS 托管密钥 (aws/s3) – 选择 AWS 托管的 CMK

      • 从 KMS 主密钥中进行选择 – 从与存储桶位于同一区域的 CMK 列表中选择客户托管的 CMK

        有关创建客户托管 AWS KMS CMK 的更多信息,请参阅《AWS Key Management Service 开发人员指南》中的创建密钥。有关使用 AWS KMS 保护数据的更多信息,请参阅使用在 AWS Key Management Service 中存储 CMK 的服务器端加密 (SSE-KMS) 保护数据

      • 输入 KMS 主密钥 ARN – 为客户托管的 CMK 指定 AWS KMS 密钥 ARN,然后输入 Amazon 资源名称 (ARN)。

        您可以使用 KMS 主密钥 ARN 授权外部账户使用由 AWS KMS CMK 保护的对象。为此,请选择输入 KMS 主密钥 ARN,然后输入用于外部账户的 Amazon 资源名称 (ARN)。如果外部账户管理员对由您的 AWS KMS CMK 保护的对象有使用权限,则可通过创建资源级 IAM 策略来进一步限制访问权限。

      注意

      要加密存储桶中的对象,您只能使用存储桶所在相同 AWS 区域提供的 CMK。

  4. 要更改访问控制列表权限,请在访问控制列表 (ACL) 下编辑权限。

    有关对象访问权限的信息,请参阅 使用 S3 控制台为对象设置 ACL 权限。您可以向一般公众(世界上的每一个人)授予对您的对象的读取访问权限,使其能够获取您正在上传的所有文件。我们建议您不要更改公共读取访问的默认设置。授予公有读取访问权限适用于一小部分的用例 (如存储桶用于网站时)。您始终可以在上传对象后更改对象权限。

  5. 要向上传的所有对象添加标签,请选择 Add tag (添加标签)。在 Key (键) 字段中键入标签名称。键入标签的值。

    对象标签为您提供了对存储进行分类的方法。每个标签都是一个键-值对。键和标签值区分大小写。对于每个对象,您最多可以有 10 个标签。标签键的长度最大可以为 128 个 Unicode 字符,标签值的长度最大可以为 255 个 Unicode 字符。有关对象标签的更多信息,请参阅 使用标签对存储进行分类

  6. 要添加元数据,请选择添加元数据

    1. 类型下,选择系统定义用户定义

      对于系统定义元数据,您可以选择通用的 HTTP 标头,如 Content-TypeContent-Disposition。有关系统定义元数据的列表以及您能否添加值的信息,请参阅系统定义的对象元数据。以前缀 x-amz-meta- 开头的任何元数据都被视为用户定义的元数据。用户定义元数据会与对象存储在一起,并会在您下载该对象时返回。密钥及其值均必须符合 US-ASCII 标准。用户定义元数据最大可为 2 KB。如需详细了解系统定义和用户定义的元数据,请参阅 使用对象元数据

    2. 对于,选择一个键。

    3. 键入该键的值。

  7. 要上传对象,请选择上传

    Amazon S3 将上传您的对象。上传完成后,您可以在上传:状态页面上看到成功消息。

  8. 选择 Exit (退出)

您可以使用 AWS 开发工具包在 Amazon S3 中上传对象。开发工具包向您提供了包装程序库,使您可以更轻松地上传数据。有关信息,请参阅支持的开发工具包列表

以下是几个精选开发工具包的示例:

.NET

以下 C# 代码示例将使用两个 PutObjectRequest 请求创建两个对象:

  • 第一个 PutObjectRequest 请求将文本字符串保存为示例对象数据。它还指定存储桶和对象键名。

  • 第二个 PutObjectRequest 请求通过指定文件名上传文件。此请求还指定 ContentType 标头和可选对象元数据(标题)。

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

using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class UploadObjectTest { private const string bucketName = "*** bucket name ***"; // For simplicity the example creates two objects from the same file. // You specify key names for these objects. private const string keyName1 = "*** key name for first object created ***"; private const string keyName2 = "*** key name for second object created ***"; private const string filePath = @"*** file path ***"; private static readonly RegionEndpoint bucketRegion = RegionEndpoint.EUWest1; private static IAmazonS3 client; public static void Main() { client = new AmazonS3Client(bucketRegion); WritingAnObjectAsync().Wait(); } static async Task WritingAnObjectAsync() { try { // 1. Put object-specify only key name for the new object. var putRequest1 = new PutObjectRequest { BucketName = bucketName, Key = keyName1, ContentBody = "sample text" }; PutObjectResponse response1 = await client.PutObjectAsync(putRequest1); // 2. Put the object-set ContentType and add metadata. var putRequest2 = new PutObjectRequest { BucketName = bucketName, Key = keyName2, FilePath = filePath, ContentType = "text/plain" }; putRequest2.Metadata.Add("x-amz-meta-title", "someTitle"); PutObjectResponse response2 = await client.PutObjectAsync(putRequest2); } catch (AmazonS3Exception e) { Console.WriteLine( "Error encountered ***. 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); } } } }
Java

以下示例将创建两个对象。第一个对象将一个文本字符串作为数据,第二对象是一个文件。该示例通过在对 AmazonS3Client.putObject() 的调用中直接指定存储桶名称、对象键和文本数据来创建第一个对象。该示例通过使用指定存储桶、对象键和文件路径的 PutObjectRequest 来创建第二个对象。PutObjectRequest 还指定 ContentType 标头和标题元数据。

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

import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.model.ObjectMetadata; import com.amazonaws.services.s3.model.PutObjectRequest; import java.io.File; import java.io.IOException; public class UploadObject { public static void main(String[] args) throws IOException { Regions clientRegion = Regions.DEFAULT_REGION; String bucketName = "*** Bucket name ***"; String stringObjKeyName = "*** String object key name ***"; String fileObjKeyName = "*** File object key name ***"; String fileName = "*** Path to file to upload ***"; try { //This code expects that you have AWS credentials set up per: // https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withRegion(clientRegion) .build(); // Upload a text string as a new object. s3Client.putObject(bucketName, stringObjKeyName, "Uploaded String Object"); // Upload a file as a new object with ContentType and title specified. PutObjectRequest request = new PutObjectRequest(bucketName, fileObjKeyName, new File(fileName)); ObjectMetadata metadata = new ObjectMetadata(); metadata.setContentType("plain/text"); metadata.addUserMetadata("title", "someTitle"); request.setMetadata(metadata); s3Client.putObject(request); } 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(); } } }
JavaScript

以下示例将现有文件上传到了特定区域中的 Amazon S3 存储桶。

// Import required AWS SDK clients and commands for Node.js. const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3"); const path = require("path"); // Set the AWS Region. const REGION = "REGION"; //e.g. "us-east-1" // Set the parameters const uploadParams = { Bucket: "BUCKET_NAME" }; const file = "OBJECT_PATH_AND_NAME"; // Path to and name of object. For example '../myFiles/index.js'. // Create an Amazon S3 service client object. const s3 = new S3Client({ region: REGION }); // Upload file to specified bucket. const run = async () => { // Add the required 'Key' parameter using the 'path' module. uploadParams.Key = path.basename(file); try { const data = await s3.send(new PutObjectCommand(uploadParams)); console.log("Success", data); } catch (err) { console.log("Error", err); } }; run();
PHP

此主题将指导您使用适用于 PHP 的 AWS 开发工具包中的类上传最大 5 GB 的对象。对于大型文件,您必须使用分段上传 API。有关更多信息,请参阅 使用分段上传来上传和复制对象

此主题假定您已按照使用适用于 PHP 的 AWS 开发工具包和运行 PHP 示例中的说明执行操作,并正确安装了适用于 PHP 的 AWS 开发工具包。

例 — 通过上传数据在 Amazon S3 存储桶中创建对象

通过使用 putObject() 方法来上传数据,以下 PHP 示例在指定存储桶中创建对象。有关运行本指南中的 PHP 示例的信息,请参阅运行 PHP 示例

require 'vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $bucket = '*** Your Bucket Name ***'; $keyname = '*** Your Object Key ***'; $s3 = new S3Client([ 'version' => 'latest', 'region' => 'us-east-1' ]); try { // Upload data. $result = $s3->putObject([ 'Bucket' => $bucket, 'Key' => $keyname, 'Body' => 'Hello, world!', 'ACL' => 'public-read' ]); // Print the URL to the object. echo $result['ObjectURL'] . PHP_EOL; } catch (S3Exception $e) { echo $e->getMessage() . PHP_EOL; }
Ruby

适用于 Ruby 的 AWS 开发工具包(版本 3)通过两种方式将对象上传到 Amazon S3。第一种方式使用托管的文件上传程序,从而能轻松从磁盘上传任何大小的文件。使用托管文件上传程序方法:

  1. 创建 Aws::S3::Resource 类的实例。

  2. 按存储桶名称和键引用目标对象。位于存储桶中的对象具有可识别每个对象的唯一密钥。

  3. 在对象上调用 #upload_file

require 'aws-sdk-s3' # Uploads an object to a bucket in Amazon Simple Storage Service (Amazon S3). # # Prerequisites: # # - An S3 bucket. # - An object to upload to the bucket. # # @param s3_client [Aws::S3::Resource] An initialized S3 resource. # @param bucket_name [String] The name of the bucket. # @param object_key [String] The name of the object. # @param file_path [String] The path and file name of the object to upload. # @return [Boolean] true if the object was uploaded; otherwise, false. # @example # exit 1 unless object_uploaded?( # Aws::S3::Resource.new(region: 'us-east-1'), # 'doc-example-bucket', # 'my-file.txt', # './my-file.txt' # ) def object_uploaded?(s3_resource, bucket_name, object_key, file_path) object = s3_resource.bucket(bucket_name).object(object_key) object.upload_file(file_path) return true rescue StandardError => e puts "Error uploading object: #{e.message}" return false end

适用于 Ruby 的 AWS 开发工具包(版本 3)上传对象的第二种方式是使用 Aws::S3::Object#put 方法。如果对象为字符串或者为不是磁盘上的文件的 I/O 对象,此方式很有用。要使用此方法,请执行以下操作:

  1. 创建 Aws::S3::Resource 类的实例。

  2. 按存储桶名称和键引用目标对象。

  3. 调用 #put,从而传入字符串或 I/O 对象。

require 'aws-sdk-s3' # Uploads an object to a bucket in Amazon Simple Storage Service (Amazon S3). # # Prerequisites: # # - An S3 bucket. # - An object to upload to the bucket. # # @param s3_client [Aws::S3::Resource] An initialized S3 resource. # @param bucket_name [String] The name of the bucket. # @param object_key [String] The name of the object. # @param file_path [String] The path and file name of the object to upload. # @return [Boolean] true if the object was uploaded; otherwise, false. # @example # exit 1 unless object_uploaded?( # Aws::S3::Resource.new(region: 'us-east-1'), # 'doc-example-bucket', # 'my-file.txt', # './my-file.txt' # ) def object_uploaded?(s3_resource, bucket_name, object_key, file_path) object = s3_resource.bucket(bucket_name).object(object_key) File.open(file_path, 'rb') do |file| object.put(body: file) end return true rescue StandardError => e puts "Error uploading object: #{e.message}" return false end

您可以发送 REST 请求以上传对象。您可以发送 PUT 请求以在单个操作中上传数据。有关更多信息,请参阅 PUT Object

如果您的应用程序需要它,则可以发送 AWS 命令行界面 (AWS CLI) 请求以上传对象。您可以发送 PUT 请求以在单个操作中上传数据。有关更多信息,请参阅 AWS CLI 命令参考中的 PutObject