AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Operations on Objects

An Amazon S3 object represents a file, which is a collection of data. Every object must reside within a bucket.

Note

These code snippets assume that you understand the material in Getting Started and have configured default AWS credentials using the information in Providing AWS Credentials.

Upload an Object#

Use the S3Client object PutObject method, supplying it with a bucket name, key name, and file to upload. The bucket must exist or an error will result.

Includes

#include <aws/core/Aws.h>
#include <aws/s3/S3Client.h>
#include <aws/s3/model/PutObjectRequest.h>
#include <iostream>
#include <fstream>

Code

{
    Aws::S3::S3Client s3_client;

    Aws::S3::Model::PutObjectRequest object_request;
    object_request.WithBucket(bucket_name).WithKey(key_name);

    // Binary files must also have the std::ios_base::bin flag or'ed in
    auto input_data = Aws::MakeShared<Aws::FStream>("PutObjectInputStream",
            file_name.c_str(), std::ios_base::in);

    object_request.SetBody(input_data);

    auto put_object_outcome = s3_client.PutObject(object_request);

    if (put_object_outcome.IsSuccess()) {
        std::cout << "Done!" << std::endl;
    } else {
        std::cout << "PutObject error: " <<
            put_object_outcome.GetError().GetExceptionName() << " " <<
            put_object_outcome.GetError().GetMessage() << std::endl;
    }
}

See the complete example.

List Objects#

To get a list of objects within a bucket, use the S3Client object ListObjects method. Supply it with a ListObjectsRequest that you set with the name of a bucket to list the contents of.

The ListObjects method returns a ListObjectsOutcome object that you can use to get a list of objects in the form of Object instances.

Includes

#include <aws/core/Aws.h>
#include <aws/s3/S3Client.h>
#include <aws/s3/model/ListObjectsRequest.h>
#include <aws/s3/model/Object.h>

Code

{
    Aws::S3::S3Client s3_client;

    Aws::S3::Model::ListObjectsRequest objects_request;
    objects_request.WithBucket(bucket_name);

    auto list_objects_outcome = s3_client.ListObjects(objects_request);

    if (list_objects_outcome.IsSuccess()) {
        Aws::Vector<Aws::S3::Model::Object> object_list =
            list_objects_outcome.GetResult().GetContents();

        for (auto const &s3_object: object_list) {
            std::cout << "* " << s3_object.GetKey() << std::endl;
        }
    } else {
        std::cout << "ListObjects error: " <<
            list_objects_outcome.GetError().GetExceptionName() << " " <<
            list_objects_outcome.GetError().GetMessage() << std::endl;
    }
}

Aws::ShutdownAPI(options);

See the complete example.

Download an Object#

Use the S3Client object GetObject method, passing it a GetObjectRequest that you set with the name of a bucket and the object key to download. GetObject returns a GetObjectOutcome object that you can use to access the S3 object's data.

The following example downloads an object from Amazon S3 and saves its contents to a file (using the same name as the object's key).

Includes

#include <aws/core/Aws.h>
#include <aws/s3/S3Client.h>
#include <aws/s3/model/GetObjectRequest.h>
#include <fstream>

Code

{
    Aws::S3::S3Client s3_client;

    Aws::S3::Model::GetObjectRequest object_request;
    object_request.WithBucket(bucket_name).WithKey(key_name);

    auto get_object_outcome = s3_client.GetObject(object_request);

    if (get_object_outcome.IsSuccess()) {
        Aws::OFStream local_file;
        local_file.open(key_name.c_str(), std::ios::out | std::ios::binary);
        local_file << get_object_outcome.GetResult().GetBody().rdbuf();
        std::cout << "Done!" << std::endl;
    } else {
        std::cout << "GetObject error: " <<
            get_object_outcome.GetError().GetExceptionName() << " " <<
            get_object_outcome.GetError().GetMessage() << std::endl;
    }
}

Aws::ShutdownAPI(options);

See the complete example.

Delete an Object#

Use the S3Client object's DeleteObject method, passing it a DeleteObjectRequest that you set with the name of a bucket and object to download. The specified bucket and object key must exist or an error will result.

Includes

#include <aws/core/Aws.h>
#include <aws/s3/S3Client.h>
#include <aws/s3/model/DeleteObjectRequest.h>
#include <fstream>

Code

{
    Aws::S3::S3Client s3_client;

    Aws::S3::Model::DeleteObjectRequest object_request;
    object_request.WithBucket(bucket_name).WithKey(key_name);

    auto delete_object_outcome = s3_client.DeleteObject(object_request);

    if (delete_object_outcome.IsSuccess()) {
        std::cout << "Done!" << std::endl;
    } else {
        std::cout << "DeleteObject error: " <<
            delete_object_outcome.GetError().GetExceptionName() << " " <<
            delete_object_outcome.GetError().GetMessage() << std::endl;
    }
}

Aws::ShutdownAPI(options);

See the complete example.