Upload an object to an Amazon S3 bucket using an Amazon SDK - Amazon Simple Storage Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Upload an object to an Amazon S3 bucket using an Amazon SDK

The following code examples show how to upload an object to an S3 bucket.

.NET
Amazon SDK for .NET
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

/// <summary> /// Shows how to upload a file from the local computer to an Amazon S3 /// bucket. /// </summary> /// <param name="client">An initialized Amazon S3 client object.</param> /// <param name="bucketName">The Amazon S3 bucket to which the object /// will be uploaded.</param> /// <param name="objectName">The object to upload.</param> /// <param name="filePath">The path, including file name, of the object /// on the local computer to upload.</param> /// <returns>A boolean value indicating the success or failure of the /// upload procedure.</returns> public static async Task<bool> UploadFileAsync( IAmazonS3 client, string bucketName, string objectName, string filePath) { var request = new PutObjectRequest { BucketName = bucketName, Key = objectName, FilePath = filePath, }; var response = await client.PutObjectAsync(request); if (response.HttpStatusCode == System.Net.HttpStatusCode.OK) { Console.WriteLine($"Successfully uploaded {objectName} to {bucketName}."); return true; } else { Console.WriteLine($"Could not upload {objectName} to {bucketName}."); return false; } }
  • For API details, see PutObject in Amazon SDK for .NET API Reference.

C++
SDK for C++
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

bool AwsDoc::S3::PutObject(const Aws::String &bucketName, const Aws::String &fileName, const Aws::Client::ClientConfiguration &clientConfig) { Aws::S3::S3Client s3_client(clientConfig); Aws::S3::Model::PutObjectRequest request; request.SetBucket(bucketName); //We are using the name of the file as the key for the object in the bucket. //However, this is just a string and can be set according to your retrieval needs. request.SetKey(fileName); std::shared_ptr<Aws::IOStream> inputData = Aws::MakeShared<Aws::FStream>("SampleAllocationTag", fileName.c_str(), std::ios_base::in | std::ios_base::binary); if (!*inputData) { std::cerr << "Error unable to read file " << fileName << std::endl; return false; } request.SetBody(inputData); Aws::S3::Model::PutObjectOutcome outcome = s3_client.PutObject(request); if (!outcome.IsSuccess()) { std::cerr << "Error: PutObject: " << outcome.GetError().GetMessage() << std::endl; } else { std::cout << "Added object '" << fileName << "' to bucket '" << bucketName << "'."; } return outcome.IsSuccess(); }
  • For API details, see PutObject in Amazon SDK for C++ API Reference.

Go
SDK for Go V2
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

// Place an object in a bucket. fmt.Println("Upload an object to the bucket") // Get the object body to upload. // Image credit: https://unsplash.com/photos/iz58d89q3ss stat, err := os.Stat("image.jpg") if err != nil { panic("Couldn't stat image: " + err.Error()) } file, err := os.Open("image.jpg") if err != nil { panic("Couldn't open local file") } _, err = client.PutObject(context.TODO(), &s3.PutObjectInput{ Bucket: aws.String(name), Key: aws.String("path/myfile.jpg"), Body: file, ContentLength: stat.Size(), }) file.Close() if err != nil { panic("Couldn't upload file: " + err.Error()) }
  • For API details, see PutObject in Amazon SDK for Go API Reference.

Java
SDK for Java 2.x
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

Upload an object to a bucket.

public static String putS3Object(S3Client s3, String bucketName, String objectKey, String objectPath) { try { Map<String, String> metadata = new HashMap<>(); metadata.put("x-amz-meta-myVal", "test"); PutObjectRequest putOb = PutObjectRequest.builder() .bucket(bucketName) .key(objectKey) .metadata(metadata) .build(); PutObjectResponse response = s3.putObject(putOb, RequestBody.fromBytes(getObjectFile(objectPath))); return response.eTag(); } catch (S3Exception e) { System.err.println(e.getMessage()); System.exit(1); } return ""; } // Return a byte array. private static byte[] getObjectFile(String filePath) { FileInputStream fileInputStream = null; byte[] bytesArray = null; try { File file = new File(filePath); bytesArray = new byte[(int) file.length()]; fileInputStream = new FileInputStream(file); fileInputStream.read(bytesArray); } catch (IOException e) { e.printStackTrace(); } finally { if (fileInputStream != null) { try { fileInputStream.close(); } catch (IOException e) { e.printStackTrace(); } } } return bytesArray; }

Upload an object to a bucket and set tags.

public static void putS3ObjectTags(S3Client s3, String bucketName, String objectKey, String objectPath) { try { Tag tag1 = Tag.builder() .key("Tag 1") .value("This is tag 1") .build(); Tag tag2 = Tag.builder() .key("Tag 2") .value("This is tag 2") .build(); List<Tag> tags = new ArrayList<>(); tags.add(tag1); tags.add(tag2); Tagging allTags = Tagging.builder() .tagSet(tags) .build(); PutObjectRequest putOb = PutObjectRequest.builder() .bucket(bucketName) .key(objectKey) .tagging(allTags) .build(); s3.putObject(putOb, RequestBody.fromBytes(getObjectFile(objectPath))); } catch (S3Exception e) { System.err.println(e.getMessage()); System.exit(1); } } public static void updateObjectTags(S3Client s3, String bucketName, String objectKey) { try { GetObjectTaggingRequest taggingRequest = GetObjectTaggingRequest.builder() .bucket(bucketName) .key(objectKey) .build(); GetObjectTaggingResponse getTaggingRes = s3.getObjectTagging(taggingRequest); List<Tag> obTags = getTaggingRes.tagSet(); for (Tag sinTag: obTags) { System.out.println("The tag key is: "+sinTag.key()); System.out.println("The tag value is: "+sinTag.value()); } // Replace the object's tags with two new tags. Tag tag3 = Tag.builder() .key("Tag 3") .value("This is tag 3") .build(); Tag tag4 = Tag.builder() .key("Tag 4") .value("This is tag 4") .build(); List<Tag> tags = new ArrayList<>(); tags.add(tag3); tags.add(tag4); Tagging updatedTags = Tagging.builder() .tagSet(tags) .build(); PutObjectTaggingRequest taggingRequest1 = PutObjectTaggingRequest.builder() .bucket(bucketName) .key(objectKey) .tagging(updatedTags) .build(); s3.putObjectTagging(taggingRequest1); GetObjectTaggingResponse getTaggingRes2 = s3.getObjectTagging(taggingRequest); List<Tag> modTags = getTaggingRes2.tagSet(); for (Tag sinTag: modTags) { System.out.println("The tag key is: "+sinTag.key()); System.out.println("The tag value is: "+sinTag.value()); } } catch (S3Exception e) { System.err.println(e.getMessage()); System.exit(1); } }

Upload an object to a bucket and set metadata.

public static String putS3Object(S3Client s3, String bucketName, String objectKey, String objectPath) { try { Map<String, String> metadata = new HashMap<>(); metadata.put("author", "Mary Doe"); metadata.put("version", "1.0.0.0"); PutObjectRequest putOb = PutObjectRequest.builder() .bucket(bucketName) .key(objectKey) .metadata(metadata) .build(); PutObjectResponse response = s3.putObject(putOb, RequestBody.fromBytes(getObjectFile(objectPath))); return response.eTag(); } catch (S3Exception e) { System.err.println(e.getMessage()); System.exit(1); } return ""; } // Return a byte array. private static byte[] getObjectFile(String filePath) { FileInputStream fileInputStream = null; byte[] bytesArray = null; try { File file = new File(filePath); bytesArray = new byte[(int) file.length()]; fileInputStream = new FileInputStream(file); fileInputStream.read(bytesArray); } catch (IOException e) { e.printStackTrace(); } finally { if (fileInputStream != null) { try { fileInputStream.close(); } catch (IOException e) { e.printStackTrace(); } } } return bytesArray; }

Upload an object to a bucket and set an object retention value.

public static void setRentionPeriod(S3Client s3, String key, String bucket) { try{ LocalDate localDate = LocalDate.parse("2020-07-17"); LocalDateTime localDateTime = localDate.atStartOfDay(); Instant instant = localDateTime.toInstant(ZoneOffset.UTC); ObjectLockRetention lockRetention = ObjectLockRetention.builder() .mode("COMPLIANCE") .retainUntilDate(instant) .build(); PutObjectRetentionRequest retentionRequest = PutObjectRetentionRequest.builder() .bucket(bucket) .key(key) .bypassGovernanceRetention(true) .retention(lockRetention) .build(); // To set Retention on an object, the Amazon S3 bucket must support object locking, otherwise an exception is thrown. s3.putObjectRetention(retentionRequest); System.out.print("An object retention configuration was successfully placed on the object"); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } }
  • For API details, see PutObject in Amazon SDK for Java 2.x API Reference.

JavaScript
SDK for JavaScript V3
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

Create the client.

// Create service client module using ES6 syntax. import { S3Client } from "@aws-sdk/client-s3"; // Set the AWS Region. const REGION = "us-east-1"; // Create an Amazon S3 service client object. const s3Client = new S3Client({ region: REGION }); export { s3Client };

Create and upload the object.

// Import required AWS SDK clients and commands for Node.js. import { PutObjectCommand } from "@aws-sdk/client-s3"; import { s3Client } from "./libs/s3Client.js"; // Helper function that creates an Amazon S3 service client module. // Set the parameters. export const bucketParams = { Bucket: "BUCKET_NAME", // Specify the name of the new object. For example, 'index.html'. // To create a directory for the object, use '/'. For example, 'myApp/package.json'. Key: "OBJECT_NAME", // Content of the new object. Body: "BODY", }; // Create and upload the object to the S3 bucket. export const run = async () => { try { const data = await s3Client.send(new PutObjectCommand(bucketParams)); return data; // For unit tests. console.log( "Successfully uploaded object: " + bucketParams.Bucket + "/" + bucketParams.Key ); } catch (err) { console.log("Error", err); } }; run();

Upload the object.

// Import required AWS SDK clients and commands for Node.js. import { PutObjectCommand } from "@aws-sdk/client-s3"; import { s3Client } from "./libs/s3Client.js"; // Helper function that creates an Amazon S3 service client module. import {path} from "path"; import {fs} from "fs"; const file = "OBJECT_PATH_AND_NAME"; // Path to and name of object. For example '../myFiles/index.js'. const fileStream = fs.createReadStream(file); // Set the parameters export const uploadParams = { Bucket: "BUCKET_NAME", // Add the required 'Key' parameter using the 'path' module. Key: path.basename(file), // Add the required 'Body' parameter Body: fileStream, }; // Upload file to specified bucket. export const run = async () => { try { const data = await s3Client.send(new PutObjectCommand(uploadParams)); console.log("Success", data); return data; // For unit tests. } catch (err) { console.log("Error", err); } }; run();
Kotlin
SDK for Kotlin
Note

This is prerelease documentation for a feature in preview release. It is subject to change.

Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

suspend fun putS3Object(bucketName: String, objectKey: String, objectPath: String) { val metadataVal = mutableMapOf<String, String>() metadataVal["myVal"] = "test" val request = PutObjectRequest { bucket = bucketName key = objectKey metadata = metadataVal body = File(objectPath).asByteStream() } S3Client { region = "us-east-1" }.use { s3 -> val response = s3.putObject(request) println("Tag information is ${response.eTag}") } }
  • For API details, see PutObject in Amazon SDK for Kotlin API reference.

PHP
SDK for PHP
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

Upload an object to a bucket.

$s3client = new Aws\S3\S3Client(['region' => 'us-west-2', 'version' => 'latest']); $file_name = "local-file-" . uniqid(); try { $s3client->putObject([ 'Bucket' => $bucket_name, 'Key' => $file_name, 'SourceFile' => 'testfile.txt' ]); echo "Uploaded $file_name to $bucket_name.\n"; } catch (Exception $exception) { echo "Failed to upload $file_name with error: " . $exception->getMessage(); exit("Please fix error with file upload before continuing."); }
  • For API details, see PutObject in Amazon SDK for PHP API Reference.

Python
SDK for Python (Boto3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

class ObjectWrapper: """Encapsulates S3 object actions.""" def __init__(self, s3_object): """ :param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3 that wraps object actions in a class-like structure. """ self.object = s3_object self.key = self.object.key def put(self, data): """ Upload data to the object. :param data: The data to upload. This can either be bytes or a string. When this argument is a string, it is interpreted as a file name, which is opened in read bytes mode. """ put_data = data if isinstance(data, str): try: put_data = open(data, 'rb') except IOError: logger.exception("Expected file name or binary data, got '%s'.", data) raise try: self.object.put(Body=put_data) self.object.wait_until_exists() logger.info( "Put object '%s' to bucket '%s'.", self.object.key, self.object.bucket_name) except ClientError: logger.exception( "Couldn't put object '%s' to bucket '%s'.", self.object.key, self.object.bucket_name) raise finally: if getattr(put_data, 'close', None): put_data.close()
  • For API details, see PutObject in Amazon SDK for Python (Boto3) API Reference.

Ruby
SDK for Ruby
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

Upload a file using a managed uploader (Object.upload_file).

require "aws-sdk-s3" # Wraps Amazon S3 object actions. class ObjectUploadFileWrapper attr_reader :object # @param object [Aws::S3::Object] An existing Amazon S3 object. def initialize(object) @object = object end # Uploads a file to an Amazon S3 object by using a managed uploader. # # @param file_path [String] The path to the file to upload. # @return [Boolean] True when the file is uploaded; otherwise false. def upload_file(file_path) @object.upload_file(file_path) true rescue Aws::Errors::ServiceError => e puts "Couldn't upload file #{file_path} to #{@object.key}. Here's why: #{e.message}" false end end def run_demo bucket_name = "doc-example-bucket" object_key = "my-uploaded-file" file_path = "object_upload_file.rb" wrapper = ObjectUploadFileWrapper.new(Aws::S3::Object.new(bucket_name, object_key)) return unless wrapper.upload_file(file_path) puts "File #{file_path} successfully uploaded to #{bucket_name}:#{object_key}." end run_demo if $PROGRAM_NAME == __FILE__

Upload a file using Object.put.

require "aws-sdk-s3" # Wraps Amazon S3 object actions. class ObjectPutWrapper attr_reader :object # @param object [Aws::S3::Object] An existing Amazon S3 object. def initialize(object) @object = object end def put_object(source_file_path) File.open(source_file_path, "rb") do |file| @object.put(body: file) end true rescue Aws::Errors::ServiceError => e puts "Couldn't put #{source_file_path} to #{object.key}. Here's why: #{e.message}" false end end def run_demo bucket_name = "doc-example-bucket" object_key = "my-object-key" file_path = "my-local-file.txt" wrapper = ObjectPutWrapper.new(Aws::S3::Object.new(bucket_name, object_key)) success = wrapper.put_object(file_path) return unless success puts "Put file #{file_path} into #{object_key} in #{bucket_name}." end run_demo if $PROGRAM_NAME == __FILE__

Upload a file using Object.put and add server-side encryption.

require "aws-sdk-s3" # Wraps Amazon S3 object actions. class ObjectPutSseWrapper attr_reader :object # @param object [Aws::S3::Object] An existing Amazon S3 object. def initialize(object) @object = object end def put_object_encrypted(object_content, encryption) @object.put(body: object_content, server_side_encryption: encryption) true rescue Aws::Errors::ServiceError => e puts "Couldn't put your content to #{object.key}. Here's why: #{e.message}" false end end def run_demo bucket_name = "doc-example-bucket" object_key = "my-encrypted-content" object_content = "This is my super-secret content." encryption = "AES256" wrapper = ObjectPutSseWrapper.new(Aws::S3::Object.new(bucket_name, object_content)) return unless wrapper.put_object_encrypted(object_content, encryption) puts "Put your content into #{bucket_name}:#{object_key} and encrypted it with #{encryption}." end run_demo if $PROGRAM_NAME == __FILE__
  • For API details, see PutObject in Amazon SDK for Ruby API Reference.

Rust
SDK for Rust
Note

This documentation is for an SDK in preview release. The SDK is subject to change and should not be used in production.

Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

pub async fn upload_object( client: &Client, bucket_name: &str, file_name: &str, key: &str, ) -> Result<(), Error> { let body = ByteStream::from_path(Path::new(file_name)).await; client .put_object() .bucket(bucket_name) .key(key) .body(body.unwrap()) .send() .await?; println!("Uploaded file: {}", file_name); Ok(()) }
  • For API details, see PutObject in Amazon SDK for Rust API reference.

Swift
SDK for Swift
Note

This is prerelease documentation for an SDK in preview release. It is subject to change.

Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

Upload a file from local storage to a bucket.

public func uploadFile(bucket: String, key: String, file: String) async throws { let fileUrl = URL(fileURLWithPath: file) let fileData = try Data(contentsOf: fileUrl) let dataStream = ByteStream.from(data: fileData) let input = PutObjectInput( body: dataStream, bucket: bucket, key: key ) _ = try await client.putObject(input: input) }

Upload the contents of a Swift Data object to a bucket.

public func createFile(bucket: String, key: String, withData data: Data) async throws { let dataStream = ByteStream.from(data: data) let input = PutObjectInput( body: dataStream, bucket: bucket, key: key ) _ = try await client.putObject(input: input) }
  • For API details, see PutObject in Amazon SDK for Swift API reference.

For a complete list of Amazon SDK developer guides and code examples, see Using this service with an Amazon SDK. This topic also includes information about getting started and details about previous SDK versions.