Get an object from 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.

Get an object from an Amazon S3 bucket using an Amazon SDK

The following code examples show how to read data from an object in 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 download an object from an Amazon S3 bucket to the /// local computer. /// </summary> /// <param name="client">An initialized Amazon S3 client object.</param> /// <param name="bucketName">The name of the bucket where the object is /// currently stored.</param> /// <param name="objectName">The name of the object to download.</param> /// <param name="filePath">The path, including filename, where the /// downloaded object will be stored.</param> /// <returns>A boolean value indicating the success or failure of the /// download process.</returns> public static async Task<bool> DownloadObjectFromBucketAsync( IAmazonS3 client, string bucketName, string objectName, string filePath) { // Create a GetObject request var request = new GetObjectRequest { BucketName = bucketName, Key = objectName, }; // Issue request and remember to dispose of the response using GetObjectResponse response = await client.GetObjectAsync(request); try { // Save object to local file await response.WriteResponseStreamToFileAsync($"{filePath}\\{objectName}", true, System.Threading.CancellationToken.None); return response.HttpStatusCode == System.Net.HttpStatusCode.OK; } catch (AmazonS3Exception ex) { Console.WriteLine($"Error saving {objectName}: {ex.Message}"); return false; } }
  • For API details, see GetObject 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::GetObject(const Aws::String &objectKey, const Aws::String &fromBucket, const Aws::Client::ClientConfiguration &clientConfig) { Aws::S3::S3Client client(clientConfig); Aws::S3::Model::GetObjectRequest request; request.SetBucket(fromBucket); request.SetKey(objectKey); Aws::S3::Model::GetObjectOutcome outcome = client.GetObject(request); if (!outcome.IsSuccess()) { const Aws::S3::S3Error &err = outcome.GetError(); std::cerr << "Error: GetObject: " << err.GetExceptionName() << ": " << err.GetMessage() << std::endl; } else { std::cout << "Successfully retrieved '" << objectKey << "' from '" << fromBucket << "'." << std::endl; } return outcome.IsSuccess(); }
  • For API details, see GetObject in Amazon SDK for C++ 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.

Read data as a byte array.

public static void getObjectBytes (S3Client s3, String bucketName, String keyName, String path) { try { GetObjectRequest objectRequest = GetObjectRequest .builder() .key(keyName) .bucket(bucketName) .build(); ResponseBytes<GetObjectResponse> objectBytes = s3.getObjectAsBytes(objectRequest); byte[] data = objectBytes.asByteArray(); // Write the data to a local file. File myFile = new File(path ); OutputStream os = new FileOutputStream(myFile); os.write(data); System.out.println("Successfully obtained bytes from an S3 object"); os.close(); } catch (IOException ex) { ex.printStackTrace(); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } }

Read tags that belong to an object.

public static void listTags(S3Client s3, String bucketName, String keyName) { try { GetObjectTaggingRequest getTaggingRequest = GetObjectTaggingRequest .builder() .key(keyName) .bucket(bucketName) .build(); GetObjectTaggingResponse tags = s3.getObjectTagging(getTaggingRequest); List<Tag> tagSet= tags.tagSet(); for (Tag tag : tagSet) { System.out.println(tag.key()); System.out.println(tag.value()); } } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } }

Get a URL for an object.

public static void getURL(S3Client s3, String bucketName, String keyName ) { try { GetUrlRequest request = GetUrlRequest.builder() .bucket(bucketName) .key(keyName) .build(); URL url = s3.utilities().getUrl(request); System.out.println("The URL for "+keyName +" is "+ url); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } }

Get an object by using the S3Presigner client object.

public static void getPresignedUrl(S3Presigner presigner, String bucketName, String keyName ) { try { GetObjectRequest getObjectRequest = GetObjectRequest.builder() .bucket(bucketName) .key(keyName) .build(); GetObjectPresignRequest getObjectPresignRequest = GetObjectPresignRequest.builder() .signatureDuration(Duration.ofMinutes(60)) .getObjectRequest(getObjectRequest) .build(); PresignedGetObjectRequest presignedGetObjectRequest = presigner.presignGetObject(getObjectPresignRequest); String theUrl = presignedGetObjectRequest.url().toString(); System.out.println("Presigned URL: " + theUrl); HttpURLConnection connection = (HttpURLConnection) presignedGetObjectRequest.url().openConnection(); presignedGetObjectRequest.httpRequest().headers().forEach((header, values) -> { values.forEach(value -> { connection.addRequestProperty(header, value); }); }); // Send any request payload that the service needs (not needed when isBrowserExecutable is true). if (presignedGetObjectRequest.signedPayload().isPresent()) { connection.setDoOutput(true); try (InputStream signedPayload = presignedGetObjectRequest.signedPayload().get().asInputStream(); OutputStream httpOutputStream = connection.getOutputStream()) { IoUtils.copy(signedPayload, httpOutputStream); } } // Download the result of executing the request. try (InputStream content = connection.getInputStream()) { System.out.println("Service returned response: "); IoUtils.copy(content, System.out); } } catch (S3Exception | IOException e) { e.getStackTrace(); } }
  • For API details, see GetObject 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 };

Download the object.

// Import required AWS SDK clients and commands for Node.js. import { GetObjectCommand } from "@aws-sdk/client-s3"; import { s3Client } from "./libs/s3Client.js"; // Helper function that creates an Amazon S3 service client module. export const bucketParams = { Bucket: "BUCKET_NAME", Key: "KEY", }; export const run = async () => { try { // Get the object} from the Amazon S3 bucket. It is returned as a ReadableStream. const data = await s3Client.send(new GetObjectCommand(bucketParams)); // Convert the ReadableStream to a string. return await data.Body.transformToString(); } 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 getObjectBytes(bucketName: String, keyName: String, path: String) { val request = GetObjectRequest { key = keyName bucket = bucketName } S3Client { region = "us-east-1" }.use { s3 -> s3.getObject(request) { resp -> val myFile = File(path) resp.body?.writeToFile(myFile) println("Successfully read $keyName from $bucketName") } } }
  • For API details, see GetObject 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.

Get an object.

$s3client = new Aws\S3\S3Client(['region' => 'us-west-2', 'version' => 'latest']); try { $file = $s3client->getObject([ 'Bucket' => $bucket_name, 'Key' => $file_name, ]); $body = $file->get('Body'); $body->rewind(); echo "Downloaded the file and it begins with: {$body->read(26)}.\n"; } catch (Exception $exception) { echo "Failed to download $file_name from $bucket_name with error: " . $exception->getMessage(); exit("Please fix error with file downloading before continuing."); }
  • For API details, see GetObject 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 get(self): """ Gets the object. :return: The object data in bytes. """ try: body = self.object.get()['Body'].read() logger.info( "Got object '%s' from bucket '%s'.", self.object.key, self.object.bucket_name) except ClientError: logger.exception( "Couldn't get object '%s' from bucket '%s'.", self.object.key, self.object.bucket_name) raise else: return body
  • For API details, see GetObject 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.

Get an object.

require "aws-sdk-s3" # Wraps Amazon S3 object actions. class ObjectGetWrapper attr_reader :object # @param object [Aws::S3::Object] An existing Amazon S3 object. def initialize(object) @object = object end # Gets the object directly to a file. # # @param target_path [String] The path to the file where the object is downloaded. # @return [Aws::S3::Types::GetObjectOutput, nil] The retrieved object data if successful; otherwise nil. def get_object(target_path) @object.get(response_target: target_path) rescue Aws::Errors::ServiceError => e puts "Couldn't get object #{@object.key}. Here's why: #{e.message}" end end # Replace bucket name and object key with an existing bucket and object that you own. def run_demo bucket_name = "doc-example-bucket" object_key = "my-object.txt" target_path = "my-object-as-file.txt" wrapper = ObjectGetWrapper.new(Aws::S3::Object.new(bucket_name, object_key)) obj_data = wrapper.get_object(target_path) return unless obj_data puts "Object #{object_key} (#{obj_data.content_length} bytes} downloaded to #{target_path}." end run_demo if $PROGRAM_NAME == __FILE__

Get an object and report its server-side encryption state.

require "aws-sdk-s3" # Wraps Amazon S3 object actions. class ObjectGetEncryptionWrapper attr_reader :object # @param object [Aws::S3::Object] An existing Amazon S3 object. def initialize(object) @object = object end # Gets the object into memory. # # @return [Aws::S3::Types::GetObjectOutput, nil] The retrieved object data if successful; otherwise nil. def get_object @object.get rescue Aws::Errors::ServiceError => e puts "Couldn't get object #{@object.key}. Here's why: #{e.message}" end end # Replace bucket name and object key with an existing bucket and object that you own. def run_demo bucket_name = "doc-example-bucket" object_key = "my-object.txt" wrapper = ObjectGetEncryptionWrapper.new(Aws::S3::Object.new(bucket_name, object_key)) obj_data = wrapper.get_object return unless obj_data encryption = obj_data.server_side_encryption.nil? ? "no" : obj_data.server_side_encryption puts "Object #{object_key} uses #{encryption} encryption." end run_demo if $PROGRAM_NAME == __FILE__
  • For API details, see GetObject 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 download_object(client: &Client, bucket_name: &str, key: &str) -> GetObjectOutput { let resp = client .get_object() .bucket(bucket_name) .key(key) .send() .await; resp.unwrap() }
  • For API details, see GetObject 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.

Download an object from a bucket to a local file.

public func downloadFile(bucket: String, key: String, to: String) async throws { let fileUrl = URL(fileURLWithPath: to).appendingPathComponent(key) let input = GetObjectInput( bucket: bucket, key: key ) let output = try await client.getObject(input: input) // Get the data stream object. Return immediately if there isn't one. guard let body = output.body else { return } let data = body.toBytes().toData() try data.write(to: fileUrl) }

Read an object into a Swift Data object.

public func readFile(bucket: String, key: String) async throws -> Data { let input = GetObjectInput( bucket: bucket, key: key ) let output = try await client.getObject(input: input) // Get the stream and return its contents in a `Data` object. If // there is no stream, return an empty `Data` object instead. guard let body = output.body else { return "".data(using: .utf8)! } let data = body.toBytes().toData() return data }
  • For API details, see GetObject 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.