Amazon Simple Storage Service
Developer Guide
API Version 20060301Amazon Simple Storage Service Developer GuideAmazon Simple Storage Service Developer Guide
Amazon Simple Storage Service Developer Guide
Copyright © 2016 Amazon Web Services Inc andor its affiliates All rights reserved
Amazon＇s trademarks and trade dress may not be used in connection with any product or service that is not Amazon＇s in any
manner that is likely to cause confusion among customers or in any manner that disparages or discredits Amazon All other
trademarks not owned by Amazon are the property of their respective owners who may or may not be affiliated with connected to
or sponsored by AmazonAmazon Simple Storage Service Developer Guide
Table of Contents
What Is Amazon S3 1
How Do I 1
Introduction 2
Overview of Amazon S3 and This Guide 2
Advantages to Amazon S3 2
Amazon S3 Concepts 3
Buckets 3
Objects 3
Keys 4
Regions 4
Amazon S3 Data Consistency Model 4
Features 6
Reduced Redundancy Storage 6
Bucket Policies 7
AWS Identity and Access Management 8
Access Control Lists 8
Versioning 8
Operations 8
Amazon S3 Application Programming Interfaces (API) 8
The REST Interface 9
The SOAP Interface 9
Paying for Amazon S3 9
Related Services 9
Making Requests 11
About Access Keys 11
AWS Account Access Keys 11
IAM User Access Keys 12
Temporary Security Credentials 12
Request Endpoints 13
Making Requests over IPv6 13
Getting Started with IPv6 13
Using IPv6 Addresses in IAM Policies 14
Testing IP Address Compatibility 15
Using DualStack Endpoints 16
Making Requests Using the AWS SDKs 19
Using AWS Account or IAM User Credentials 20
Using IAM User Temporary Credentials 25
Using Federated User Temporary Credentials 36
Making Requests Using the REST API 49
DualStack Endpoints (REST API) 50
Virtual Hosting of Buckets 50
Request Redirection and the REST API 55
Buckets 58
Creating a Bucket 59
About Permissions 60
Accessing a Bucket 60
Bucket Configuration Options 61
Restrictions and Limitations 62
Rules for Naming 63
Examples of Creating a Bucket 64
Using the Amazon S3 Console 65
Using the AWS SDK for Java 65
Using the AWS SDK for NET 66
Using the AWS SDK for Ruby Version 2 67
Using Other AWS SDKs 67
API Version 20060301
ivAmazon Simple Storage Service Developer Guide
Deleting or Emptying a Bucket 67
Delete a Bucket 68
Empty a Bucket 71
Bucket Website Configuration 73
Using the AWS Management Console 73
Using the SDK for Java 73
Using the AWS SDK for NET 76
Using the SDK for PHP 79
Using the REST API 81
Transfer Acceleration 81
Why use Transfer Acceleration 81
Getting Started 82
Requirements for Using Amazon S3 Transfer Acceleration 83
Transfer Acceleration Examples 83
Requester Pays Buckets 92
Configure with the Console 93
Configure with the REST API 93
DevPay and Requester Pays 96
Charge Details 96
Access Control 96
Billing and Reporting 96
Cost Allocation Tagging 96
Objects 98
Object Key and Metadata 99
Object Keys 99
Object Metadata 101
Storage Classes 103
Subresources 105
Versioning 106
Lifecycle Management 109
What Is Lifecycle Configuration 109
How Do I Configure a Lifecycle 110
Transitioning Objects General Considerations 110
Expiring Objects General Considerations 112
Lifecycle and Other Bucket Configurations 112
Lifecycle Configuration Elements 113
GLACIER Storage Class Additional Considerations 124
Specifying a Lifecycle Configuration 125
CrossOrigin Resource Sharing (CORS) 131
CrossOrigin Resource Sharing Usecase Scenarios 131
How Do I Configure CORS on My Bucket 132
How Does Amazon S3 Evaluate the CORS Configuration On a Bucket 134
Enabling CORS 134
Troubleshooting CORS 142
Operations on Objects 142
Getting Objects 143
Uploading Objects 157
Copying Objects 212
Listing Object Keys 229
Deleting Objects 237
Restoring Archived Objects 259
Managing Access 266
Introduction 266
Overview 267
How Amazon S3 Authorizes a Request 272
Guidelines for Using the Available Access Policy Options 277
Example Walkthroughs Managing Access 280
Using Bucket Policies and User Policies 308
API Version 20060301
vAmazon Simple Storage Service Developer Guide
Access Policy Language Overview 308
Bucket Policy Examples 334
User Policy Examples 343
Managing Access with ACLs 364
Access Control List (ACL) Overview 364
Managing ACLs 369
Protecting Data 380
Data Encryption 380
ServerSide Encryption 381
ClientSide Encryption 409
Reduced Redundancy Storage 420
Setting the Storage Class of an Object You Upload 421
Changing the Storage Class of an Object in Amazon S3 421
Versioning 423
How to Configure Versioning on a Bucket 424
MFA Delete 424
Related Topics 425
Examples 426
Managing Objects in a VersioningEnabled Bucket 428
Managing Objects in a VersioningSuspended Bucket 444
Hosting a Static Website 449
Website Endpoints 450
Key Differences Between the Amazon Website and the REST API Endpoint 451
Configure a Bucket for Website Hosting 452
Overview 452
Syntax for Specifying Routing Rules 454
Index Document Support 457
Custom Error Document Support 459
Configuring a Redirect 460
Permissions Required for Website Access 462
Example Walkthroughs 462
Example Setting Up a Static Website 463
Example Setting Up a Static Website Using a Custom Domain 464
Notifications 472
Overview 472
How to Enable Event Notifications 473
Event Notification Types and Destinations 475
Supported Event Types 475
Supported Destinations 476
Configuring Notifications with Object Key Name Filtering 476
Examples of Valid Notification Configurations with Object Key Name Filtering 477
Examples of Notification Configurations with Invalid PrefixSuffix Overlapping 479
Granting Permissions to Publish Event Notification Messages to a Destination 481
Granting Permissions to Invoke an AWS Lambda Function 481
Granting Permissions to Publish Messages to an SNS Topic or an SQS Queue 481
Example Walkthrough 1 483
Walkthrough Summary 483
Step 1 Create an Amazon SNS Topic 484
Step 2 Create an Amazon SQS Queue 484
Step 3 Add a Notification Configuration to Your Bucket 485
Step 4 Test the Setup 489
Example Walkthrough 2 489
Event Message Structure 489
CrossRegion Replication 492
Usecase Scenarios 492
Requirements 493
Related Topics 493
What Is and Is Not Replicated 493
API Version 20060301
viAmazon Simple Storage Service Developer Guide
What Is Replicated 493
What Is Not Replicated 494
Related Topics 495
How to Set Up 495
Create an IAM Role 495
Add Replication Configuration 497
Walkthrough 1 Same AWS Account 500
Walkthrough 2 Different AWS Accounts 501
Using the Console 505
Using the AWS SDK for Java 505
Using the AWS SDK for NET 507
Replication Status Information 509
Related Topics 510
Troubleshooting 511
Related Topics 511
Replication and Other Bucket Configurations 511
Lifecycle Configuration and Object Replicas 512
Versioning Configuration and Replication Configuration 512
Logging Configuration and Replication Configuration 512
Related Topics 512
Request Routing 513
Request Redirection and the REST API 513
Overview 513
DNS Routing 514
Temporary Request Redirection 514
Permanent Request Redirection 516
DNS Considerations 516
Performance Optimization 518
Request Rate and Performance Considerations 518
Workloads with a Mix of Request Types 519
GETIntensive Workloads 521
TCP Window Scaling 521
TCP Selective Acknowledgement 522
Monitoring with Amazon CloudWatch 523
Amazon S3 CloudWatch Metrics 523
Amazon S3 CloudWatch Dimensions 524
Accessing Metrics in Amazon CloudWatch 524
Related Resources 525
Logging API Calls with AWS CloudTrail 526
Amazon S3 Information in CloudTrail 526
Using CloudTrail Logs with Amazon S3 Server Access Logs and CloudWatch Logs 528
Understanding Amazon S3 Log File Entries 528
Related Resources 530
BitTorrent 531
How You are Charged for BitTorrent Delivery 531
Using BitTorrent to Retrieve Objects Stored in Amazon S3 532
Publishing Content Using Amazon S3 and BitTorrent 533
Amazon DevPay 534
Amazon S3 Customer Data Isolation 534
Example 535
Amazon DevPay Token Mechanism 535
Amazon S3 and Amazon DevPay Authentication 535
Amazon S3 Bucket Limitation 536
Amazon S3 and Amazon DevPay Process 537
Additional Information 537
Error Handling 538
The REST Error Response 538
Response Headers 539
API Version 20060301
viiAmazon Simple Storage Service Developer Guide
Error Response 539
The SOAP Error Response 540
Amazon S3 Error Best Practices 540
Retry InternalErrors 540
Tune Application for Repeated SlowDown errors 540
Isolate Errors 541
Troubleshooting Amazon S3 542
General Getting my Amazon S3 request IDs 542
Using HTTP 542
Using a Web Browser 543
Using an AWS SDK 543
Using the AWS CLI 544
Using Windows PowerShell 544
Related Topics 544
Server Access Logging 546
Overview 546
Log Object Key Format 547
How are Logs Delivered 547
Best Effort Server Log Delivery 547
Bucket Logging Status Changes Take Effect Over Time 548
Related Topics 548
Enabling Logging Using the Console 548
Enabling Logging Programmatically 550
Enabling logging 550
Granting the Log Delivery Group WRITE and READ_ACP Permissions 550
Example AWS SDK for NET 551
Log Format 553
Custom Access Log Information 556
Programming Considerations for Extensible Server Access Log Format 556
Additional Logging for Copy Operations 556
Deleting Log Files 559
AWS SDKs and Explorers 560
Specifying Signature Version in Request Authentication 561
Set Up the AWS CLI 562
Using the AWS SDK for Java 563
The Java API Organization 564
Testing the Java Code Examples 564
Using the AWS SDK for NET 565
The NET API Organization 565
Running the Amazon S3 NET Code Examples 566
Using the AWS SDK for PHP and Running PHP Examples 566
AWS SDK for PHP Levels 566
Running PHP Examples 567
Related Resources 568
Using the AWS SDK for Ruby Version 2 568
The Ruby API Organization 568
Testing the Ruby Script Examples 568
Using the AWS SDK for Python (Boto) 569
Appendices 570
Appendix A Using the SOAP API 570
Common SOAP API Elements 570
Authenticating SOAP Requests 571
Setting Access Policy with SOAP 571
Appendix B Authenticating Requests (AWS Signature Version 2) 573
Authenticating Requests Using the REST API 574
Signing and Authenticating REST Requests 575
BrowserBased Uploads Using POST 586
Resources 602
API Version 20060301
viiiAmazon Simple Storage Service Developer Guide
Document History 604
AWS Glossary 614
API Version 20060301
ixAmazon Simple Storage Service Developer Guide
How Do I
What Is Amazon S3
Amazon Simple Storage Service is storage for the Internet It is designed to make webscale
computing easier for developers
Amazon S3 has a simple web services interface that you can use to store and retrieve any amount
of data at any time from anywhere on the web It gives any developer access to the same highly
scalable reliable fast inexpensive data storage infrastructure that Amazon uses to run its own global
network of web sites The service aims to maximize benefits of scale and to pass those benefits on to
developers
This guide explains the core concepts of Amazon S3 such as buckets and objects and how to work
with these resources using the Amazon S3 application programming interface (API)
How Do I
Information Relevant Sections
General product overview and pricing Amazon S3
Get a quick handson introduction to
Amazon S3
Amazon Simple Storage Service Getting Started Guide
Learn about Amazon S3 key
terminology and concepts
Introduction to Amazon S3 (p 2)
How do I work with buckets Working with Amazon S3 Buckets (p 58)
How do I work with objects Working with Amazon S3 Objects (p 98)
How do I make requests Making Requests (p 11)
How do I manage access to my
resources
Managing Access Permissions to Your Amazon S3
Resources (p 266)
API Version 20060301
1Amazon Simple Storage Service Developer Guide
Overview of Amazon S3 and This Guide
Introduction to Amazon S3
This introduction to Amazon Simple Storage Service is intended to give you a detailed summary of this
web service After reading this section you should have a good idea of what it offers and how it can fit
in with your business
Topics
• Overview of Amazon S3 and This Guide (p 2)
• Advantages to Amazon S3 (p 2)
• Amazon S3 Concepts (p 3)
• Features (p 6)
• Amazon S3 Application Programming Interfaces (API) (p 8)
• Paying for Amazon S3 (p 9)
• Related Services (p 9)
Overview of Amazon S3 and This Guide
Amazon S3 has a simple web services interface that you can use to store and retrieve any amount of
data at any time from anywhere on the web
This guide describes how you send requests to create buckets store and retrieve your objects
and manage permissions on your resources The guide also describes access control and the
authentication process Access control defines who can access objects and buckets within Amazon S3
and the type of access (eg READ and WRITE) The authentication process verifies the identity of a
user who is trying to access Amazon Web Services (AWS)
Advantages to Amazon S3
Amazon S3 is intentionally built with a minimal feature set that focuses on simplicity and robustness
Following are some of advantages of the Amazon S3 service
• Create Buckets – Create and name a bucket that stores data Buckets are the fundamental
container in Amazon S3 for data storage
• Store data in Buckets – Store an infinite amount of data in a bucket Upload as many objects as
you like into an Amazon S3 bucket Each object can contain up to 5 TB of data Each object is stored
and retrieved using a unique developerassigned key
API Version 20060301
2Amazon Simple Storage Service Developer Guide
Amazon S3 Concepts
• Download data – Download your data or enable others to do so Download your data any time you
like or allow others to do the same
• Permissions – Grant or deny access to others who want to upload or download data into your
Amazon S3 bucket Grant upload and download permissions to three types of users Authentication
mechanisms can help keep data secure from unauthorized access
• Standard interfaces – Use standardsbased REST and SOAP interfaces designed to work with any
Internetdevelopment toolkit
Note
SOAP support over HTTP is deprecated but it is still available over HTTPS New Amazon
S3 features will not be supported for SOAP We recommend that you use either the REST
API or the AWS SDKs
Amazon S3 Concepts
Topics
• Buckets (p 3)
• Objects (p 3)
• Keys (p 4)
• Regions (p 4)
• Amazon S3 Data Consistency Model (p 4)
This section describes key concepts and terminology you need to understand to use Amazon S3
effectively They are presented in the order you will most likely encounter them
Buckets
A bucket is a container for objects stored in Amazon S3 Every object is contained in a bucket For
example if the object named photospuppyjpg is stored in the johnsmith bucket then it is
addressable using the URL httpjohnsmiths3amazonawscomphotospuppyjpg
Buckets serve several purposes they organize the Amazon S3 namespace at the highest level they
identify the account responsible for storage and data transfer charges they play a role in access
control and they serve as the unit of aggregation for usage reporting
You can configure buckets so that they are created in a specific region For more information see
Buckets and Regions (p 60) You can also configure a bucket so that every time an object is added
to it Amazon S3 generates a unique version ID and assigns it to the object For more information see
Versioning (p 423)
For more information about buckets see Working with Amazon S3 Buckets (p 58)
Objects
Objects are the fundamental entities stored in Amazon S3 Objects consist of object data and
metadata The data portion is opaque to Amazon S3 The metadata is a set of namevalue pairs
that describe the object These include some default metadata such as the date last modified and
standard HTTP metadata such as ContentType You can also specify custom metadata at the time
the object is stored
An object is uniquely identified within a bucket by a key (name) and a version ID For more information
see Keys (p 4) and Versioning (p 423)
API Version 20060301
3Amazon Simple Storage Service Developer Guide
Keys
Keys
A key is the unique identifier for an object within a bucket Every object in a bucket has exactly
one key Because the combination of a bucket key and version ID uniquely identify each object
Amazon S3 can be thought of as a basic data map between bucket + key + version and the
object itself Every object in Amazon S3 can be uniquely addressed through the combination of
the web service endpoint bucket name key and optionally a version For example in the URL
httpdocs3amazonawscom20060301AmazonS3wsdl doc is the name of the bucket and
20060301AmazonS3wsdl is the key
Regions
You can choose the geographical region where Amazon S3 will store the buckets you create You
might choose a region to optimize latency minimize costs or address regulatory requirements
Amazon S3 currently supports the following regions
• US East (N Virginia) Region Uses Amazon S3 servers in Northern Virginia
• US West (N California) Region Uses Amazon S3 servers in Northern California
• US West (Oregon) Region Uses Amazon S3 servers in Oregon
• Asia Pacific (Mumbai) Region Uses Amazon S3 servers in Mumbai
• Asia Pacific (Seoul) Region Uses Amazon S3 servers in Seoul
• Asia Pacific (Singapore) Region Uses Amazon S3 servers in Singapore
• Asia Pacific (Sydney) Region Uses Amazon S3 servers in Sydney
• Asia Pacific (Tokyo) Region Uses Amazon S3 servers in Tokyo
• EU (Frankfurt) Region Uses Amazon S3 servers in Frankfurt
• EU (Ireland) Region Uses Amazon S3 servers in Ireland
• South America (São Paulo) Region Uses Amazon S3 servers in Sao Paulo
Objects stored in a region never leave the region unless you explicitly transfer them to another region
For example objects stored in the EU (Ireland) region never leave it For more information about
Amazon S3 regions and endpoints go to Regions and Endpoints in the AWS General Reference
Amazon S3 Data Consistency Model
Amazon S3 provides readafterwrite consistency for PUTS of new objects in your S3 bucket in all
regions with one caveat The caveat is that if you make a HEAD or GET request to the key name (to
find if the object exists) before creating the object Amazon S3 provides eventual consistency for read
afterwrite
Amazon S3 offers eventual consistency for overwrite PUTS and DELETES in all regions
Updates to a single key are atomic For example if you PUT to an existing key a subsequent read
might return the old data or the updated data but it will never write corrupted or partial data
Amazon S3 achieves high availability by replicating data across multiple servers within Amazon＇s data
centers If a PUT request is successful your data is safely stored However information about the
changes must replicate across Amazon S3 which can take some time and so you might observe the
following behaviors
• A process writes a new object to Amazon S3 and immediately lists keys within its bucket Until the
change is fully propagated the object might not appear in the list
• A process replaces an existing object and immediately attempts to read it Until the change is fully
propagated Amazon S3 might return the prior data
API Version 20060301
4Amazon Simple Storage Service Developer Guide
Amazon S3 Data Consistency Model
• A process deletes an existing object and immediately attempts to read it Until the deletion is fully
propagated Amazon S3 might return the deleted data
• A process deletes an existing object and immediately lists keys within its bucket Until the deletion is
fully propagated Amazon S3 might list the deleted object
Note
Amazon S3 does not currently support object locking If two PUT requests are simultaneously
made to the same key the request with the latest time stamp wins If this is an issue you will
need to build an objectlocking mechanism into your application
Updates are keybased there is no way to make atomic updates across keys For example
you cannot make the update of one key dependent on the update of another key unless you
design this functionality into your application
The following table describes the characteristics of eventually consistent read and consistent read
Eventually Consistent Read Consistent Read
Stale reads possible No stale reads
Lowest read latency Potential higher read latency
Highest read throughput Potential lower read throughput
Concurrent Applications
This section provides examples of eventually consistent and consistent read requests when multiple
clients are writing to the same items
In this example both W1 (write 1) and W2 (write 2) complete before the start of R1 (read 1) and R2
(read 2) For a consistent read R1 and R2 both return color ruby For an eventually consistent
read R1 and R2 might return color red color ruby or no results depending on the amount
of time that has elapsed
In the next example W2 does not complete before the start of R1 Therefore R1 might return color
ruby or color garnet for either a consistent read or an eventually consistent read Also
depending on the amount of time that has elapsed an eventually consistent read might return no
results
For a consistent read R2 returns color garnet For an eventually consistent read R2 might
return color ruby color garnet or no results depending on the amount of time that has
elapsed
API Version 20060301
5Amazon Simple Storage Service Developer Guide
Features
In the last example Client 2 performs W2 before Amazon S3 returns a success for W1 so the
outcome of the final value is unknown (color garnet or color brick) Any subsequent reads
(consistent read or eventually consistent) might return either value Also depending on the amount of
time that has elapsed an eventually consistent read might return no results
Features
Topics
• Reduced Redundancy Storage (p 6)
• Bucket Policies (p 7)
• AWS Identity and Access Management (p 8)
• Access Control Lists (p 8)
• Versioning (p 8)
• Operations (p 8)
This section describes important Amazon S3 features
Reduced Redundancy Storage
Customers can store their data using the Amazon S3 Reduced Redundancy Storage (RRS) option
RRS enables customers to reduce their costs by storing noncritical reproducible data at lower levels
of redundancy than Amazon S3 standard storage RRS provides a costeffective highly available
API Version 20060301
6Amazon Simple Storage Service Developer Guide
Bucket Policies
solution for distributing or sharing content that is durably stored elsewhere or for storing thumbnails
transcoded media or other processed data that can be easily reproduced The RRS option stores
objects on multiple devices across multiple facilities providing 400 times the durability of a typical disk
drive but does not replicate objects as many times as standard Amazon S3 storage and thus is even
more cost effective
RRS provides 9999 durability of objects over a given year This durability level corresponds to an
average expected loss of 001 of objects annually
AWS charges less for using RRS than for standard Amazon S3 storage For pricing information see
Amazon S3 Pricing
For more information see Storage Classes (p 103)
Bucket Policies
Bucket policies provide centralized access control to buckets and objects based on a variety of
conditions including Amazon S3 operations requesters resources and aspects of the request
(eg IP address) The policies are expressed in our access policy language and enable centralized
management of permissions The permissions attached to a bucket apply to all of the objects in that
bucket
Individuals as well as companies can use bucket policies When companies register with Amazon S3
they create an account Thereafter the company becomes synonymous with the account Accounts
are financially responsible for the Amazon resources they (and their employees) create Accounts have
the power to grant bucket policy permissions and assign employees permissions based on a variety of
conditions For example an account could create a policy that gives a user write access
• To a particular S3 bucket
• From an account＇s corporate network
• During business hours
• From an account＇s custom application (as identified by a user agent string)
An account can grant one application limited read and write access but allow another to create and
delete buckets as well An account could allow several field offices to store their daily reports in a
single bucket allowing each office to write only to a certain set of names (eg Nevada* or Utah*)
and only from the office＇s IP address range
Unlike access control lists (described below) which can add (grant) permissions only on individual
objects policies can either add or deny permissions across all (or a subset) of objects within a bucket
With one request an account can set the permissions of any number of objects in a bucket An account
can use wildcards (similar to regular expression operators) on Amazon resource names (ARNs) and
other values so that an account can control access to groups of objects that begin with a common
prefix or end with a given extension such as html
Only the bucket owner is allowed to associate a policy with a bucket Policies written in the access
policy language allow or deny requests based on
• Amazon S3 bucket operations (such as PUT acl) and object operations (such as PUT Object
or GET Object)
• Requester
• Conditions specified in the policy
An account can control access based on specific Amazon S3 operations such as GetObject
GetObjectVersion DeleteObject or DeleteBucket
API Version 20060301
7Amazon Simple Storage Service Developer Guide
AWS Identity and Access Management
The conditions can be such things as IP addresses IP address ranges in CIDR notation dates user
agents HTTP referrer and transports (HTTP and HTTPS)
For more information see Using Bucket Policies and User Policies (p 308)
AWS Identity and Access Management
For example you can use IAM with Amazon S3 to control the type of access a user or group of users
has to specific parts of an Amazon S3 bucket your AWS account owns
For more information about IAM see the following
• Identity and Access Management (IAM)
• Getting Started
• IAM User Guide
Access Control Lists
For more information see Managing Access with ACLs (p 364)
Versioning
For more information see Object Versioning (p 106)
Operations
Following are the most common operations you＇ll execute through the API
Common Operations
• Create a Bucket – Create and name your own bucket in which to store your objects
• Write an Object – Store data by creating or overwriting an object When you write an object you
specify a unique key in the namespace of your bucket This is also a good time to specify any access
control you want on the object
• Read an Object – Read data back You can download the data via HTTP or BitTorrent
• Deleting an Object – Delete some of your data
• Listing Keys – List the keys contained in one of your buckets You can filter the key list based on a
prefix
Details on this and all other functionality are described in detail later in this guide
Amazon S3 Application Programming Interfaces
(API)
The Amazon S3 architecture is designed to be programming languageneutral using our supported
interfaces to store and retrieve objects
Amazon S3 provides a REST and a SOAP interface They are similar but there are some differences
For example in the REST interface metadata is returned in HTTP headers Because we only support
API Version 20060301
8Amazon Simple Storage Service Developer Guide
The REST Interface
HTTP requests of up to 4 KB (not including the body) the amount of metadata you can supply is
restricted
Note
SOAP support over HTTP is deprecated but it is still available over HTTPS New Amazon S3
features will not be supported for SOAP We recommend that you use either the REST API or
the AWS SDKs
The REST Interface
The REST API is an HTTP interface to Amazon S3 Using REST you use standard HTTP requests to
create fetch and delete buckets and objects
You can use any toolkit that supports HTTP to use the REST API You can even use a browser to fetch
objects as long as they are anonymously readable
The REST API uses the standard HTTP headers and status codes so that standard browsers and
toolkits work as expected In some areas we have added functionality to HTTP (for example we
added headers to support access control) In these cases we have done our best to add the new
functionality in a way that matched the style of standard HTTP usage
The SOAP Interface
Note
SOAP support over HTTP is deprecated but it is still available over HTTPS New Amazon S3
features will not be supported for SOAP We recommend that you use either the REST API or
the AWS SDKs
The SOAP API provides a SOAP 11 interface using document literal encoding The most common
way to use SOAP is to download the WSDL (go to httpdocs3amazonawscom20060301
AmazonS3wsdl) use a SOAP toolkit such as Apache Axis or Microsoft NET to create bindings and
then write code that uses the bindings to call Amazon S3
Paying for Amazon S3
Pricing for Amazon S3 is designed so that you don＇t have to plan for the storage requirements of your
application Most storage providers force you to purchase a predetermined amount of storage and
network transfer capacity If you exceed that capacity your service is shut off or you are charged high
overage fees If you do not exceed that capacity you pay as though you used it all
Amazon S3 charges you only for what you actually use with no hidden fees and no overage charges
This gives developers a variablecost service that can grow with their business while enjoying the cost
advantages of Amazon＇s infrastructure
Before storing anything in Amazon S3 you need to register with the service and provide a payment
instrument that will be charged at the end of each month There are no setup fees to begin using the
service At the end of the month your payment instrument is automatically charged for that month＇s
usage
For information about paying for Amazon S3 storage see Amazon S3 Pricing
Related Services
Once you load your data into Amazon S3 you can use it with other services that we provide The
following services are the ones you might use most frequently
API Version 20060301
9Amazon Simple Storage Service Developer Guide
Related Services
• Amazon Elastic Compute Cloud – This web service provides virtual compute resources in the
cloud For more information go to the Amazon EC2 product details page
• Amazon EMR – This web service enables businesses researchers data analysts and developers
to easily and costeffectively process vast amounts of data It utilizes a hosted Hadoop framework
running on the webscale infrastructure of Amazon EC2 and Amazon S3 For more information go to
the Amazon EMR product details page
• AWS ImportExport – AWS ImportExport enables you to mail a storage device such as a
RAID drive to Amazon so that we can upload your (terabytes) of data into Amazon S3 For more
information go to the AWS ImportExport Developer Guide
API Version 20060301
10Amazon Simple Storage Service Developer Guide
About Access Keys
Making Requests
Topics
• About Access Keys (p 11)
• Request Endpoints (p 13)
• Making Requests to Amazon S3 over IPv6 (p 13)
• Making Requests Using the AWS SDKs (p 19)
• Making Requests Using the REST API (p 49)
Amazon S3 is a REST service You can send requests to Amazon S3 using the REST API or the AWS
SDK (see Sample Code and Libraries) wrapper libraries that wrap the underlying Amazon S3 REST
API simplifying your programming tasks
Every interaction with Amazon S3 is either authenticated or anonymous Authentication is a process
of verifying the identity of the requester trying to access an Amazon Web Services (AWS) product
Authenticated requests must include a signature value that authenticates the request sender The
signature value is in part generated from the requester＇s AWS access keys (access key ID and secret
access key) For more information about getting access keys see How Do I Get Security Credentials
in the AWS General Reference
If you are using the AWS SDK the libraries compute the signature from the keys you provide
However if you make direct REST API calls in your application you must write the code to compute
the signature and add it to the request
About Access Keys
The following sections review the types of access keys that you can use to make authenticated
requests
AWS Account Access Keys
The account access keys provide full access to the AWS resources owned by the account The
following are examples of access keys
• Access key ID (a 20character alphanumeric string) For example AKIAIOSFODNN7EXAMPLE
• Secret access key (a 40character string) For example wJalrXUtnFEMIK7MDENG
bPxRfiCYEXAMPLEKEY
API Version 20060301
11Amazon Simple Storage Service Developer Guide
IAM User Access Keys
The access key ID uniquely identifies an AWS account You can use these access keys to send
authenticated requests to Amazon S3
IAM User Access Keys
You can create one AWS account for your company however there may be several employees in
the organization who need access to your organization＇s AWS resources Sharing your AWS account
access keys reduces security and creating individual AWS accounts for each employee might not
be practical Also you cannot easily share resources such as buckets and objects because they are
owned by different accounts To share resources you must grant permissions which is additional
work
In such scenarios you can use AWS Identity and Access Management (IAM) to create users under
your AWS account with their own access keys and attach IAM user policies granting appropriate
resource access permissions to them To better manage these users IAM enables you to create
groups of users and grant grouplevel permissions that apply to all users in that group
These users are referred as IAM users that you create and manage within AWS The parent account
controls a user＇s ability to access AWS Any resources an IAM user creates are under the control of
and paid for by the parent AWS account These IAM users can send authenticated requests to Amazon
S3 using their own security credentials For more information about creating and managing users
under your AWS account go to the AWS Identity and Access Management product details page
Temporary Security Credentials
In addition to creating IAM users with their own access keys IAM also enables you to grant temporary
security credentials (temporary access keys and a security token) to any IAM user to enable them
to access your AWS services and resources You can also manage users in your system outside
AWS These are referred as federated users Additionally users can be applications that you create to
access your AWS resources
IAM provides the AWS Security Token Service API for you to request temporary security credentials
You can use either the AWS STS API or the AWS SDK to request these credentials The API returns
temporary security credentials (access key ID and secret access key) and a security token These
credentials are valid only for the duration you specify when you request them You use the access key
ID and secret key the same way you use them when sending requests using your AWS account or IAM
user access keys In addition you must include the token in each request you send to Amazon S3
An IAM user can request these temporary security credentials for their own use or hand them out to
federated users or applications When requesting temporary security credentials for federated users
you must provide a user name and an IAM policy defining the permissions you want to associate with
these temporary security credentials The federated user cannot get more permissions than the parent
IAM user who requested the temporary credentials
You can use these temporary security credentials in making requests to Amazon S3 The API libraries
compute the necessary signature value using those credentials to authenticate your request If you
send requests using expired credentials Amazon S3 denies the request
For information on signing requests using temporary security credentials in your REST API requests
see Signing and Authenticating REST Requests (p 575) For information about sending requests
using AWS SDKs see Making Requests Using the AWS SDKs (p 19)
For more information about IAM support for temporary security credentials see Temporary Security
Credentials in the IAM User Guide
For added security you can require multifactor authentication (MFA) when accessing your Amazon S3
resources by configuring a bucket policy For information see Adding a Bucket Policy to Require MFA
Authentication (p 339) After you require MFA to access your Amazon S3 resources the only way
API Version 20060301
12Amazon Simple Storage Service Developer Guide
Request Endpoints
you can access these resources is by providing temporary credentials that are created with an MFA
key For more information see the AWS MultiFactor Authentication detail page and Configuring MFA
Protected API Access in the IAM User Guide
Request Endpoints
You send REST requests to the service＇s predefined endpoint For a list of all AWS services and their
corresponding endpoints go to Regions and Endpoints in the AWS General Reference
Making Requests to Amazon S3 over IPv6
Amazon Simple Storage Service (Amazon S3) supports the ability to access S3 buckets using the
Internet Protocol version 6 (IPv6) in addition to the IPv4 protocol Amazon S3 dualstack endpoints
support requests to S3 buckets over IPv6 and IPv4 There are no additional charges for accessing
Amazon S3 over IPv6 For more information about pricing see Amazon S3 Pricing
Topics
• Getting Started Making Requests over IPv6 (p 13)
• Using IPv6 Addresses in IAM Policies (p 14)
• Testing IP Address Compatibility (p 15)
• Using Amazon S3 DualStack Endpoints (p 16)
Getting Started Making Requests over IPv6
To make a request to an S3 bucket over IPv6 you need to use a dualstack endpoint The next section
describes how to make requests over IPv6 by using dualstack endpoints
The following are some things you should know before trying to access a bucket over IPv6
• The client and the network accessing the bucket must be enabled to use IPv6
• Both virtual hostedstyle and path style requests are supported for IPv6 access For more
information see Amazon S3 DualStack Endpoints (p 16)
• If you use source IP address filtering in your AWS Identity and Access Management (IAM) user
or bucket policies you need to update the policies to include IPv6 address ranges For more
information see Using IPv6 Addresses in IAM Policies (p 14)
• When using IPv6 server access log files output IP addresses in an IPv6 format You need to update
existing tools scripts and software that you use to parse Amazon S3 log files so that they can
parse the IPv6 formatted Remote IP addresses For more information see Server Access Log
Format (p 553) and Server Access Logging (p 546)
Note
If you experience issues related to the presence of IPv6 addresses in log files contact AWS
Support
Making Requests over IPv6 by Using DualStack Endpoints
You make requests with Amazon S3 API calls over IPv6 by using dualstack endpoints The Amazon
S3 API operations work the same way whether you＇re accessing Amazon S3 over IPv6 or over IPv4
Performance should be the same too
API Version 20060301
13Amazon Simple Storage Service Developer Guide
Using IPv6 Addresses in IAM Policies
When using the REST API you access a dualstack endpoint directly For more information see Dual
Stack Endpoints (p 16)
When using the AWS Command Line Interface (AWS CLI) and AWS SDKs you can use a parameter
or flag to change to a dualstack endpoint You can also specify the dualstack endpoint directly as an
override of the Amazon S3 endpoint in the config file
You can use a dualstack endpoint to access a bucket over IPv6 from any of the following
• The AWS CLI see Using DualStack Endpoints from the AWS CLI (p 16)
• The AWS SDKs see Using DualStack Endpoints from the AWS SDKs (p 17)
• The REST API see Making Requests to DualStack Endpoints by Using the REST API (p 50)
Features Not Available over IPv6
The following features are not currently supported when accessing an S3 bucket over IPv6
• Static website hosting from an S3 bucket
• Amazon S3 Transfer Acceleration
• BitTorrent
Amazon S3 IPv6 Access from Amazon EC2
Amazon EC2 instances currently support IPv4 only They cannot reach Amazon S3 over IPv6 If you
use the dualstack endpoints normally the OS or applications automatically establish the connection
over IPv4 Before EC2 (VPC) supports IPv6 we recommend that you continue using the standard
IPv4only endpoints from EC2 instances or conduct sufficient testing before switching to the dual
stack endpoints For a list of Amazon S3 endpoints see Regions and Endpoints in the AWS General
Reference
Using IPv6 Addresses in IAM Policies
Before trying to access a bucket using IPv6 you must ensure that any IAM user or S3 bucket polices
that are used for IP address filtering are updated to include IPv6 address ranges IP address filtering
policies that are not updated to handle IPv6 addresses may result in clients incorrectly losing or
gaining access to the bucket when they start using IPv6 For more information about managing access
permissions with IAM see Managing Access Permissions to Your Amazon S3 Resources (p 266)
IAM policies that filter IP addresses use IP Address Condition Operators The following bucket policy
identifies the 54240143* range of allowed IPv4 addresses by using IP address condition operators
Any IP addresses outside of this range will be denied access to the bucket (examplebucket) Since
all IPv6 addresses are outside of the allowed range this policy prevents IPv6 addresses from being
able to access examplebucket
{
Version 20121017
Statement [
{
Sid IPAllow
Effect Allow
Principal *
Action s3*
Resource arnawss3examplebucket*
Condition {
API Version 20060301
14Amazon Simple Storage Service Developer Guide
Testing IP Address Compatibility
IpAddress {awsSourceIp 54240143024}
}
}
]
}
You can modify the bucket policy＇s Condition element to allow both IPv4 (54240143024) and
IPv6 (2001DB81234567864) address ranges as shown in the following example You can use
the same type of Condition block shown in the example to update both your IAM user and bucket
policies
Condition {
IpAddress {
awsSourceIp [
54240143024
2001DB81234567864
]
}
}
Before using IPv6 you must update all relevant IAM user and bucket policies that use IP address
filtering to allow IPv6 address ranges We recommend that you update your IAM policies with your
organization＇s IPv6 address ranges in addition to your existing IPv4 address ranges For an example
of a bucket policy that allows access over both IPv6 and IPv4 see Restricting Access to Specific IP
Addresses (p 336)
You can review your IAM user policies using the IAM console at httpsconsoleawsamazoncomiam
For more information about IAM see the IAM User Guide For information about editing S3 bucket
policies see Edit Bucket Permissions in the Amazon Simple Storage Service Console User Guide
Testing IP Address Compatibility
If you are using use LinuxUnix or Mac OS X you can test whether you can access a dualstack
endpoint over IPv6 by using the curl command as shown in the following example
curl v https3dualstackuswest2amazonawscom
You get back information similar to the following example If you are connected over IPv6 the
connected IP address will be an IPv6 address
* About to connect() to s3uswest2amazonawscom port 80 (#0)
* Trying IPv6 address connected
* Connected to s3dualstackuswest2amazonawscom (IPv6 address) port 80
(#0)
> GET HTTP11
> UserAgent curl7181 (x86_64unknownlinuxgnu) libcurl7181
OpenSSL101t zlib123
> Host s3dualstackuswest2amazonawscom
If you are using Microsoft Windows 7 you can test whether you can access a dualstack endpoint over
IPv6 or IPv4 by using the ping command as shown in the following example
ping ipv6s3dualstackuswest2amazonawscom
API Version 20060301
15Amazon Simple Storage Service Developer Guide
Using DualStack Endpoints
Using Amazon S3 DualStack Endpoints
Amazon S3 dualstack endpoints support requests to S3 buckets over IPv6 and IPv4 This section
describes how to use dualstack endpoints
Topics
• Amazon S3 DualStack Endpoints (p 16)
• Using DualStack Endpoints from the AWS CLI (p 16)
• Using DualStack Endpoints from the AWS SDKs (p 17)
• Using DualStack Endpoints from the REST API (p 18)
Amazon S3 DualStack Endpoints
When you make a request to a dualstack endpoint the bucket URL resolves to an IPv6 or an IPv4
address For more information about accessing a bucket over IPv6 see Making Requests to Amazon
S3 over IPv6 (p 13)
When using the REST API you directly access an Amazon S3 endpoint by using the endpoint name
(URI) You can access an S3 bucket through a dualstack endpoint by using a virtual hostedstyle or a
pathstyle endpoint name Amazon S3 supports only regional dualstack endpoint names which means
that you must specify the region as part of the name
Use the following naming conventions for the dualstack virtual hostedstyle and pathstyle endpoint
names
• Virtual hostedstyle dualstack endpoint
bucketnames3dualstackawsregionamazonawscom

• Pathstyle dualstack endpoint
s3dualstackawsregionamazonawscombucketname
For more information about endpoint name style see Accessing a Bucket (p 60) For a list of
Amazon S3 endpoints see Regions and Endpoints in the AWS General Reference
When using the AWS Command Line Interface (AWS CLI) and AWS SDKs you can use a parameter
or flag to change to a dualstack endpoint You can also specify the dualstack endpoint directly as an
override of the Amazon S3 endpoint in the config file The following sections describe how to use dual
stack endpoints from the AWS CLI and the AWS SDKs
Using DualStack Endpoints from the AWS CLI
This section provides examples of AWS CLI commands used to make requests to a dualstack
endpoint For instructions on setting up the AWS CLI see Set Up the AWS CLI (p 562)
You set the configuration value use_dualstack_endpoint to true in a profile in your AWS Config
file to direct all Amazon S3 requests made by the s3 and s3api AWS CLI commands to the dualstack
endpoint for the specified region You specify the region in the config file or in a command using the
region option
When using dualstack endpoints with the AWS CLI both path and virtual addressing styles are
supported The addressing style set in the config file controls if the bucket name is in the hostname or
part of the URL By default the CLI will attempt to use virtual style where possible but will fall back to
path style if necessary For more information see AWS CLI Amazon S3 Configuration
API Version 20060301
16Amazon Simple Storage Service Developer Guide
Using DualStack Endpoints
You can also make configuration changes by using a command as shown in the following example
which sets use_dualstack_endpoint to true and addressing_style to virtual in the default
profile
aws configure set defaults3use_dualstack_endpoint true
aws configure set defaults3addressing_style virtual
If you want to use a dualstack endpoint for specified AWS CLI commands only (not all commands)
you can use either of the following methods
• You can use the dualstack endpoint per command by setting the endpointurl parameter
to httpss3dualstackawsregionamazonawscom or https3dualstackaws
regionamazonawscom for any s3 or s3api command
aws s3api listobjects bucket bucketname endpointurl https
s3dualstackawsregionamazonawscom
• You can set up separate profiles in your AWS Config file For example create one profile that sets
use_dualstack_endpoint to true and a profile that does not set use_dualstack_endpoint
When you run a command specify which profile you want to use depending upon whether or not
you want to use the dualstack endpoint
Note
You currently cannot use transfer acceleration with dualstack endpoints For more
information see Using Transfer Acceleration from the AWS Command Line Interface (AWS
CLI) (p 84)
Using DualStack Endpoints from the AWS SDKs
This section provides examples of how to access a dualstack endpoint by using the AWS SDKs
AWS Java SDK DualStack Endpoint Example
You use the setS3ClientOptions method in the AWS Java SDK to enable the use of a dualstack
endpoint when creating an instance of AmazonS3Client as shown in the following example
AmazonS3 s3Client new AmazonS3Client(new ProfileCredentialsProvider())
s3ClientsetRegion(RegiongetRegion(RegionsUS_WEST_2))
s3ClientsetS3ClientOptions(S3ClientOptionsbuilder()enableDualstack()build())
If you are using the AWS Java SDK on Microsoft Windows you might have to set the following Java
virtual machine (JVM) property
javanetpreferIPv6Addressestrue
Note
You currently cannot use transfer acceleration with dualstack endpoints The
Java SDK will throw an exception if you configure both enableDualstack and
setAccelerateModeEnabled on the config object For more information see Using
Transfer Acceleration from the AWS SDK for Java (p 85)
For information about how to create and test a working Java sample see Testing the Java Code
Examples (p 564)
API Version 20060301
17Amazon Simple Storage Service Developer Guide
Using DualStack Endpoints
AWS NET SDK DualStack Endpoint Example
When using the AWS SDK for NET you use the AmazonS3Config class to enable the use of a dual
stack endpoint as shown in the following example
var config new AmazonS3Config
{
UseDualstackEndpoint true
RegionEndpoint RegionEndpointUSWest2
}
using (var s3Client new AmazonS3Client(config))
{
var request new ListObjectsRequest
{
BucketName myBucket
}
var response s3ClientListObjects(request)
}
For a full NET sample for listing objects see Listing Keys Using the AWS SDK for NET (p 233)
Note
You currently cannot use transfer acceleration with dualstack endpoints The NET
SDK will throw an exception if you configure both UseAccelerateEndpoint and
UseDualstackEndpoint on the config object For more information see Using Transfer
Acceleration from the AWS SDK for NET (p 88)
For information about how to create and test a working NET sample see Running the Amazon
S3 NET Code Examples (p 566)
Using DualStack Endpoints from the REST API
For information about making requests to dualstack endpoints by using the REST API see Making
Requests to DualStack Endpoints by Using the REST API (p 50)
API Version 20060301
18Amazon Simple Storage Service Developer Guide
Making Requests Using the AWS SDKs
Making Requests Using the AWS SDKs
Topics
• Making Requests Using AWS Account or IAM User Credentials (p 20)
• Making Requests Using IAM User Temporary Credentials (p 25)
• Making Requests Using Federated User Temporary Credentials (p 36)
You can send authenticated requests to Amazon S3 using either the AWS SDK or by making the
REST API calls directly in your application The AWS SDK API uses the credentials that you provide
to compute the signature for authentication If you use the REST API directly in your applications you
must write the necessary code to compute the signature for authenticating your request For a list of
available AWS SDKs go to Sample Code and Libraries
API Version 20060301
19Amazon Simple Storage Service Developer Guide
Using AWS Account or IAM User Credentials
Making Requests Using AWS Account or IAM User
Credentials
You can use an AWS account or IAM user security credentials to send authenticated requests to
Amazon S3 This section provides examples of how you can send authenticated requests using the
AWS SDK for Java AWS SDK for NET and AWS SDK for PHP For a list of available AWS SDKs go
to Sample Code and Libraries
Topics
• Making Requests Using AWS Account or IAM User Credentials AWS SDK for Java (p 20)
• Making Requests Using AWS Account or IAM User Credentials AWS SDK for NET (p 21)
• Making Requests Using AWS Account or IAM User Credentials AWS SDK for PHP (p 23)
• Making Requests Using AWS Account or IAM User Credentials AWS SDK for Ruby (p 24)
For more information about setting up your AWS credentials for use with the AWS SDK for Java see
Testing the Java Code Examples (p 564)
Making Requests Using AWS Account or IAM User Credentials
AWS SDK for Java
The following tasks guide you through using the Java classes to send authenticated requests using
your AWS account credentials or IAM user credentials
Making Requests Using Your AWS account or IAM user credentials
1 Create an instance of the AmazonS3Client class
2 Execute one of the AmazonS3Client methods to send requests to Amazon S3 The
client generates the necessary signature value from your credentials and includes it in the
request it sends to Amazon S3
The following Java code sample demonstrates the preceding tasks
AmazonS3 s3client new AmazonS3Client(new ProfileCredentialsProvider())

Send sample request (list objects in a given bucket)
ObjectListing objectListing s3clientlistObjects(new
ListObjectsRequest()withBucketName(bucketName))
Note
You can create the AmazonS3Client class without providing your security credentials
Requests sent using this client are anonymous requests without a signature Amazon S3
returns an error if you send anonymous requests for a resource that is not publicly available
To see how to make requests using your AWS credentials within the context of an example of listing
all the object keys in your bucket see Listing Keys Using the AWS SDK for Java (p 231) For
more examples see Working with Amazon S3 Objects (p 98) and Working with Amazon S3
Buckets (p 58) You can test these examples using your AWS Account or IAM user credentials
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
API Version 20060301
20Amazon Simple Storage Service Developer Guide
Using AWS Account or IAM User Credentials
Making Requests Using AWS Account or IAM User Credentials
AWS SDK for NET
The following tasks guide you through using the NET classes to send authenticated requests using
your AWS account or IAM user credentials
Making Requests Using Your AWS Account or IAM User Credentials
1 Create an instance of the AmazonS3Client class
2 Execute one of the AmazonS3Client methods to send requests to Amazon S3 The
client generates the necessary signature from your credentials and includes it in the
request it sends to Amazon S3
The following C# code sample demonstrates the preceding tasks
For information on running the NET examples in this guide and for instructions on how to store your
credentials in a configuration file see Running the Amazon S3 NET Code Examples (p 566)
using System
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class MakeS3Request
{
static string bucketName *** Provide bucket name ***
static IAmazonS3 client
public static void Main(string[] args)
{
using (client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
ConsoleWriteLine(Listing objects stored in a bucket)
ListingObjects()
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static void ListingObjects()
{
try
{
ListObjectsRequest request new ListObjectsRequest
{
BucketName bucketName
MaxKeys 2
}
do
{
ListObjectsResponse response
clientListObjects(request)
API Version 20060301
21Amazon Simple Storage Service Developer Guide
Using AWS Account or IAM User Credentials
Process response
foreach (S3Object entry in responseS3Objects)
{
ConsoleWriteLine(key {0} size {1}
entryKey entrySize)
}
If response is truncated set the marker to get the
next
set of keys
if (responseIsTruncated)
{
requestMarker responseNextMarker
}
else
{
request null
}
} while (request null)
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&
(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS Credentials)
ConsoleWriteLine(
To sign up for service go to httpawsamazoncom
s3)
}
else
{
ConsoleWriteLine(
Error occurred Message＇{0}＇ when listing objects
amazonS3ExceptionMessage)
}
}
}
}
}
Note
You can create the AmazonS3Client client without providing your security credentials
Requests sent using this client are anonymous requests without a signature Amazon S3
returns an error if you send anonymous requests for a resource that is not publicly available
For working examples see Working with Amazon S3 Objects (p 98) and Working with Amazon S3
Buckets (p 58) You can test these examples using your AWS Account or an IAM user credentials
For example to list all the object keys in your bucket see Listing Keys Using the AWS SDK
for NET (p 233)
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
API Version 20060301
22Amazon Simple Storage Service Developer Guide
Using AWS Account or IAM User Credentials
Making Requests Using AWS Account or IAM User Credentials
AWS SDK for PHP
This topic guides you through using a class from the AWS SDK for PHP to send authenticated
requests using your AWS account or IAM user credentials
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
Making Requests Using Your AWS Account or IAM user Credentials
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 Execute one of the Aws＼S3＼S3Client methods to send requests to Amazon S3 For
example you can use the Aws＼S3＼S3ClientlistBuckets() method to send a request to list
all the buckets for your account The client API generates the necessary signature using
your credentials and includes it in the request it sends to Amazon S3
The following PHP code sample demonstrates the preceding tasks and illustrates how the client makes
a request using your security credentials to list all the buckets for your account
use Aws＼S3＼S3Client
Instantiate the S3 client with your AWS credentials
s3 S3Clientfactory()
result s3>listBuckets()
For working examples see Working with Amazon S3 Objects (p 98) and Working with Amazon S3
Buckets (p 58) You can test these examples using your AWS account or IAM user credentials
For an example of listing object keys in a bucket see Listing Keys Using the AWS SDK for
PHP (p 235)
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientlistBuckets() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
API Version 20060301
23Amazon Simple Storage Service Developer Guide
Using AWS Account or IAM User Credentials
Making Requests Using AWS Account or IAM User Credentials
AWS SDK for Ruby
The following tasks guide you through using the AWS SDK for Ruby to send authenticated requests
using your AWS Account credentials or IAM user credentials
Making Requests Using Your AWS Account or IAM user Credentials
1 Create an instance of the AWSS3 class
2 Make a request to Amazon S3 by enumerating objects in a bucket using the buckets
method of AWSS3 The client generates the necessary signature value from your
credentials and includes it in the request it sends to Amazon S3
The following Ruby code sample demonstrates the preceding tasks
# Get an instance of the S3 interface using the specified credentials
configuration
s3 AWSS3new()
# Get a list of all object keys in a bucket
bucket s3buckets[bucket_name]objectscollect(&key)
puts bucket
Note
You can create the AWSS3 client without providing your security credentials Requests sent
using this client are anonymous requests without a signature Amazon S3 returns an error if
you send anonymous requests for a resource that is not publicly available
For working examples see Working with Amazon S3 Objects (p 98) and Working with Amazon S3
Buckets (p 58) You can test these examples using your AWS Account or IAM user credentials
API Version 20060301
24Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials
Making Requests Using IAM User Temporary
Credentials
Topics
• Making Requests Using IAM User Temporary Credentials AWS SDK for Java (p 25)
• Making Requests Using IAM User Temporary Credentials AWS SDK for NET (p 28)
• Making Requests Using AWS Account or IAM User Temporary Credentials AWS SDK for
PHP (p 31)
• Making Requests Using IAM User Temporary Credentials AWS SDK for Ruby (p 34)
An AWS Account or an IAM user can request temporary security credentials and use them to send
authenticated requests to Amazon S3 This section provides examples of how to use the AWS SDK
for Java NET and PHP to obtain temporary security credentials and use them to authenticate your
requests to Amazon S3
Making Requests Using IAM User Temporary Credentials
AWS SDK for Java
An IAM user or an AWS Account can request temporary security credentials (see Making
Requests (p 11)) using AWS SDK for Java and use them to access Amazon S3 These credentials
expire after the session duration By default the session duration is one hour If you use IAM user
credentials you can specify duration between 1 and 36 hours when requesting the temporary security
credentials
Making Requests Using IAM User Temporary Security Credentials
1 Create an instance of the AWS Security Token Service client
AWSSecurityTokenServiceClient
2 Start a session by calling the GetSessionToken method of the STS client you
created in the preceding step You provide session information to this method using a
GetSessionTokenRequest object
The method returns your temporary security credentials
3 Package the temporary security credentials in an instance of the
BasicSessionCredentials object so you can provide the credentials to your Amazon
S3 client
4 Create an instance of the AmazonS3Client class by passing in the temporary security
credentials
You send the requests to Amazon S3 using this client If you send requests using
expired credentials Amazon S3 returns an error
The following Java code sample demonstrates the preceding tasks
In real applications the following code is part of your trusted code It
has
your security credentials you use to obtain temporary security
credentials
AWSSecurityTokenServiceClient stsClient
new AWSSecurityTokenServiceClient(new
ProfileCredentialsProvider())

API Version 20060301
25Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials

Manually start a session
GetSessionTokenRequest getSessionTokenRequest new GetSessionTokenRequest()
Following duration can be set only if temporary credentials are requested
by an IAM user
getSessionTokenRequestsetDurationSeconds(7200)
GetSessionTokenResult sessionTokenResult
stsClientgetSessionToken(getSessionTokenRequest)
Credentials sessionCredentials sessionTokenResultgetCredentials()

Package the temporary security credentials as
a BasicSessionCredentials object for an Amazon S3 client object to use
BasicSessionCredentials basicSessionCredentials
new
BasicSessionCredentials(sessionCredentialsgetAccessKeyId()

sessionCredentialsgetSecretAccessKey()
sessionCredentialsgetSessionToken())
The following will be part of your less trusted code You provide
temporary security
credentials so it can send authenticated requests to Amazon S3
Create Amazon S3 client by passing in the basicSessionCredentials object
AmazonS3Client s3 new AmazonS3Client(basicSessionCredentials)

Test For example get object keys in a bucket
ObjectListing objects s3listObjects(bucketName)
API Version 20060301
26Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials
Example
Note
If you obtain temporary security credentials using your AWS account credentials the
temporary security credentials are valid for only one hour You can specify session duration
only if you use IAM user credentials to request a session
The following Java code example lists the object keys in the specified bucket For illustration the code
example obtains temporary security credentials for a default one hour session and uses them to send
an authenticated request to Amazon S3
If you want to test the sample using IAM user credentials you will need to create an IAM user under
your AWS Account For more information about how to create an IAM user see Creating Your First
IAM User and Administrators Group in the IAM User Guide
import javaioIOException
import comamazonawsauthBasicSessionCredentials
import comamazonawsauthPropertiesCredentials
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicessecuritytokenAWSSecurityTokenServiceClient
import comamazonawsservicessecuritytokenmodelCredentials
import comamazonawsservicessecuritytokenmodelGetSessionTokenRequest
import comamazonawsservicessecuritytokenmodelGetSessionTokenResult
import comamazonawsservicess3modelObjectListing
public class S3Sample {
private static String bucketName *** Provide bucket name ***
public static void main(String[] args) throws IOException {
AWSSecurityTokenServiceClient stsClient
new AWSSecurityTokenServiceClient(new
ProfileCredentialsProvider())

Start a session
GetSessionTokenRequest getSessionTokenRequest
new GetSessionTokenRequest()
GetSessionTokenResult sessionTokenResult

stsClientgetSessionToken(getSessionTokenRequest)
Credentials sessionCredentials sessionTokenResultgetCredentials()
Systemoutprintln(Session Credentials
+
sessionCredentialstoString())


Package the session credentials as a BasicSessionCredentials
object for an S3 client object to use
BasicSessionCredentials basicSessionCredentials
new
BasicSessionCredentials(sessionCredentialsgetAccessKeyId()
sessionCredentialsgetSecretAccessKey()
sessionCredentialsgetSessionToken())
AmazonS3Client s3 new AmazonS3Client(basicSessionCredentials)
Test For example get object keys for a given bucket
ObjectListing objects s3listObjects(bucketName)
Systemoutprintln(No of Objects +

objectsgetObjectSummaries()size())
}
}
API Version 20060301
27Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
Making Requests Using IAM User Temporary Credentials
AWS SDK for NET
An IAM user or an AWS Account can request temporary security credentials (see Making
Requests (p 11)) using the AWS SDK for NET and use them to access Amazon S3 These
credentials expire after the session duration By default the session duration is one hour If you
use IAM user credentials you can specify duration between 1 and 36 hours when requesting the
temporary security credentials
Making Requests Using IAM User Temporary Security Credentials
1 Create an instance of the AWS Security Token Service client
AmazonSecurityTokenServiceClient For information about providing credentials
see Using the AWS SDKs CLI and Explorers (p 560)
2 Start a session by calling the GetSessionToken method of the STS client you
created in the preceding step You provide session information to this method using a
GetSessionTokenRequest object
The method returns you temporary security credentials
3 Package up the temporary security credentials in an instance of the
SessionAWSCredentials object You use this object to provide the temporary
security credentials to your Amazon S3 client
4 Create an instance of the AmazonS3Client class by passing in the temporary security
credentials
You send requests to Amazon S3 using this client If you send requests using expired
credentials Amazon S3 returns an error
The following C# code sample demonstrates the preceding tasks
In real applications the following code is part of your trusted code It
has
your security credentials you use to obtain temporary security
credentials
AmazonSecurityTokenServiceConfig config new
AmazonSecurityTokenServiceConfig()
AmazonSecurityTokenServiceClient stsClient
new AmazonSecurityTokenServiceClient(config)
GetSessionTokenRequest getSessionTokenRequest new GetSessionTokenRequest()
Following duration can be set only if temporary credentials are requested
by an IAM user
getSessionTokenRequestDurationSeconds 7200 seconds
Credentials credentials

stsClientGetSessionToken(getSessionTokenRequest)GetSessionTokenResultCredentials
SessionAWSCredentials sessionCredentials
new SessionAWSCredentials(credentialsAccessKeyId
API Version 20060301
28Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials

credentialsSecretAccessKey

credentialsSessionToken)
The following will be part of your less trusted code You provide
temporary security
credentials so it can send authenticated requests to Amazon S3
Create Amazon S3 client by passing in the basicSessionCredentials object
AmazonS3Client s3Client new AmazonS3Client(sessionCredentials)
Test For example send request to list object key in a bucket
var response s3ClientListObjects(bucketName)
API Version 20060301
29Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials
Example
Note
If you obtain temporary security credentials using your AWS account security credentials the
temporary security credentials are valid for only one hour You can specify session duration
only if you use IAM user credentials to request a session
The following C# code example lists object keys in the specified bucket For illustration the code
example obtains temporary security credentials for a default one hour session and uses them to send
authenticated request to Amazon S3
If you want to test the sample using IAM user credentials you will need to create an IAM user under
your AWS Account For more information about how to create an IAM user see Creating Your First
IAM User and Administrators Group in the IAM User Guide
For instructions on how to create and test a working example see Running the Amazon S3 NET Code
Examples (p 566)
using System
using SystemConfiguration
using SystemCollectionsSpecialized
using AmazonS3
using AmazonSecurityToken
using AmazonSecurityTokenModel
using AmazonRuntime
using AmazonS3Model
using SystemCollectionsGeneric
namespace s3amazoncomdocsamples
{
class TempCredExplicitSessionStart
{
static string bucketName *** Provide bucket name ***
static IAmazonS3 client
public static void Main(string[] args)
{
NameValueCollection appConfig ConfigurationManagerAppSettings
string accessKeyID appConfig[AWSAccessKey]
string secretAccessKeyID appConfig[AWSSecretKey]
try
{
ConsoleWriteLine(Listing objects stored in a bucket)
SessionAWSCredentials tempCredentials
GetTemporaryCredentials(accessKeyID secretAccessKeyID)
Create client by providing temporary security credentials
using (client new AmazonS3Client(tempCredentials
AmazonRegionEndpointUSEast1))
{
ListObjectsRequest listObjectRequest
new ListObjectsRequest()
listObjectRequestBucketName bucketName
Send request to Amazon S3
ListObjectsResponse response
clientListObjects(listObjectRequest)
List objects responseS3Objects
ConsoleWriteLine(Object count {0} objectsCount)
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
}
catch (AmazonS3Exception s3Exception)
{
ConsoleWriteLine(s3ExceptionMessage
s3ExceptionInnerException)
}
catch (AmazonSecurityTokenServiceException stsException)
{
ConsoleWriteLine(stsExceptionMessage
stsExceptionInnerException)
}
}
private static SessionAWSCredentials GetTemporaryCredentials(
string accessKeyId string secretAccessKeyId)
{
AmazonSecurityTokenServiceClient stsClient
new AmazonSecurityTokenServiceClient(accessKeyId
secretAccessKeyId)
GetSessionTokenRequest getSessionTokenRequest
new GetSessionTokenRequest()
getSessionTokenRequestDurationSeconds 7200 seconds
GetSessionTokenResponse sessionTokenResponse
stsClientGetSessionToken(getSessionTokenRequest)
Credentials credentials sessionTokenResponseCredentials
SessionAWSCredentials sessionCredentials
new SessionAWSCredentials(credentialsAccessKeyId
credentialsSecretAccessKey
credentialsSessionToken)
return sessionCredentials
}
}
}
API Version 20060301
30Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
Making Requests Using AWS Account or IAM User Temporary
Credentials AWS SDK for PHP
This topic guides you through using classes from the AWS SDK for PHP to request temporary security
credentials and use them to access Amazon S3
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
An IAM user or an AWS Account can request temporary security credentials (see Making
Requests (p 11)) using the AWS SDK for PHP and use them to access Amazon S3 These credentials
expire when the session duration expires By default the session duration is one hour If you use
IAM user credentials you can specify the duration between 1 and 36 hours when requesting the
temporary security credentials For more information about temporary security credentials see
Temporary Security Credentials in the IAM User Guide
Making Requests Using AWS Account or IAM User Temporary Security Credentials
1 Create an instance of an AWS Security Token Service (AWS STS) client by using the
Aws＼Sts＼StsClient class factory() method
2 Execute the Aws＼Sts＼StsClientgetSessionToken() method to start a session
The method returns you temporary security credentials
3 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class
factory() method with the temporary security credentials you obtained in the preceding
step
Any methods in the S3Client class that you call use the temporary security
credentials to send authenticated requests to Amazon S3
The following PHP code sample demonstrates how to request temporary security credentials and use
them to access Amazon S3
use Aws＼Sts＼StsClient
use Aws＼S3＼S3Client
In real applications the following code is part of your trusted code
It has your security credentials that you use to obtain temporary
security credentials
sts StsClientfactory()
result sts>getSessionToken()
The following will be part of your less trusted code You provide
temporary
security credentials so it can send authenticated requests to Amazon S3
Create an Amazon S3 client using temporary security credentials
credentials result>get(＇Credentials＇)
API Version 20060301
31Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials
s3 S3Clientfactory(array(
＇key＇ > credentials[＇AccessKeyId＇]
＇secret＇ > credentials[＇SecretAccessKey＇]
＇token＇ > credentials[＇SessionToken＇]
))
result s3>listBuckets()
Note
If you obtain temporary security credentials using your AWS account security credentials
the temporary security credentials are valid for only one hour You can specify the session
duration only if you use IAM user credentials to request a session
Example of Making an Amazon S3 Request Using Temporary Security Credentials
The following PHP code example lists object keys in the specified bucket using temporary security
credentials The code example obtains temporary security credentials for a default one hour session
and uses them to send authenticated request to Amazon S3 For information about running the PHP
examples in this guide go to Running PHP Examples (p 567)
If you want to test the example using IAM user credentials you will need to create an IAM user under
your AWS Account For information about how to create an IAM user see Creating Your First IAM
User and Administrators Group in the IAM User Guide For an example of setting session duration
when using IAM user credentials to request a session see Making Requests Using Federated User
Temporary Credentials AWS SDK for PHP (p 43)
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
use Aws＼Sts＼StsClient
use Aws＼S3＼S3Client
use Aws＼S3＼Exception＼S3Exception
bucket ＇*** Your Bucket Name ***＇
sts StsClientfactory()
credentials sts>getSessionToken()>get(＇Credentials＇)
s3 S3Clientfactory(array(
＇key＇ > credentials[＇AccessKeyId＇]
＇secret＇ > credentials[＇SecretAccessKey＇]
＇token＇ > credentials[＇SessionToken＇]
))
try {
objects s3>getIterator(＇ListObjects＇ array(
＇Bucket＇ > bucket
))
echo Keys retrieved＼n
foreach (objects as object) {
echo object[＇Key＇] ＼n
}
} catch (S3Exception e) {
echo e>getMessage() ＼n
}
API Version 20060301
32Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼Sts＼StsClient Class
• AWS SDK for PHP for Amazon S3 Aws＼Sts＼StsClientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼Sts＼StsClientgetSessionToken() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
API Version 20060301
33Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials
Making Requests Using IAM User Temporary Credentials
AWS SDK for Ruby
An IAM user or an AWS Account can request temporary security credentials (see Making
Requests (p 11)) using AWS SDK for Ruby and use them to access Amazon S3 These credentials
expire after the session duration By default the session duration is one hour If you use IAM user
credentials you can specify the duration between 1 and 36 hours when requesting the temporary
security credentials
Making Requests Using IAM User Temporary Security Credentials
1 Create an instance of the AWS Security Token Service client AWSSTSSession by
providing your credentials
2 Start a session by calling the new_session method of the STS client that you
created in the preceding step You provide session information to this method using a
GetSessionTokenRequest object
The method returns your temporary security credentials
3 Use the temporary credentials in a new instance of the AWSS3 class by passing in the
temporary security credentials
You send the requests to Amazon S3 using this client If you send requests using
expired credentials Amazon S3 returns an error
The following Ruby code sample demonstrates the preceding tasks
# Start a session
# In real applications the following code is part of your trusted code It
has
# your security credentials that you use to obtain temporary security
credentials
sts AWSSTSnew()

session stsnew_session()
puts Session expires at #{sessionexpires_atto_s}
# Get an instance of the S3 interface using the session credentials
s3 AWSS3new(sessioncredentials)
# Get a list of all object keys in a bucket
bucket s3buckets[bucket_name]objectscollect(&key)
API Version 20060301
34Amazon Simple Storage Service Developer Guide
Using IAM User Temporary Credentials
Example
Note
If you obtain temporary security credentials using your AWS account security credentials the
temporary security credentials are valid for only one hour You can specify session duration
only if you use IAM user credentials to request a session
The following Ruby code example lists the object keys in the specified bucket For illustration the code
example obtains temporary security credentials for a default one hour session and uses them to send
an authenticated request to Amazon S3
If you want to test the sample using IAM user credentials you will need to create an IAM user under
your AWS Account For more information about how to create an IAM user see Creating Your First
IAM User and Administrators Group in the IAM User Guide
require ＇rubygems＇
require ＇awssdk＇
# In real applications the following code is part of your trusted code It
has
# your security credentials you use to obtain temporary security credentials
bucket_name ＇*** Provide bucket name ***＇
# Start a session
sts AWSSTSnew()
session stsnew_session()
puts Session expires at #{sessionexpires_atto_s}
# get an instance of the S3 interface using the session credentials
s3 AWSS3new(sessioncredentials)
# get a list of all object keys in a bucket
bucket s3buckets[bucket_name]objectscollect(&key)
puts bucket
API Version 20060301
35Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Making Requests Using Federated User Temporary
Credentials
Topics
• Making Requests Using Federated User Temporary Credentials AWS SDK for Java (p 36)
• Making Requests Using Federated User Temporary Credentials AWS SDK for NET (p 40)
• Making Requests Using Federated User Temporary Credentials AWS SDK for PHP (p 43)
• Making Requests Using Federated User Temporary Credentials AWS SDK for Ruby (p 47)
You can request temporary security credentials and provide them to your federated users or
applications who need to access your AWS resources This section provides examples of how you can
use the AWS SDK to obtain temporary security credentials for your federated users or applications and
send authenticated requests to Amazon S3 using those credentials For a list of available AWS SDKs
go to Sample Code and Libraries
Note
Both the AWS account and an IAM user can request temporary security credentials
for federated users However for added security only an IAM user with the necessary
permissions should request these temporary credentials to ensure that the federated user
gets at most the permissions of the requesting IAM user In some applications you might
find suitable to create an IAM user with specific permissions for the sole purpose of granting
temporary security credentials to your federated users and applications
Making Requests Using Federated User Temporary
Credentials AWS SDK for Java
You can provide temporary security credentials for your federated users and applications (see Making
Requests (p 11)) so they can send authenticated requests to access your AWS resources When
requesting these temporary credentials from the IAM service you must provide a user name and an
IAM policy describing the resource permissions you want to grant By default the session duration is
one hour However if you are requesting temporary credentials using IAM user credentials you can
explicitly set a different duration value when requesting the temporary security credentials for federated
users and applications
Note
To request temporary security credentials for federated users and applications for added
security you might want to use a dedicated IAM user with only the necessary access
permissions The temporary user you create can never get more permissions than the IAM
user who requested the temporary security credentials For more information go to AWS
Identity and Access Management FAQs
Making Requests Using Federated User Temporary Security Credentials
1 Create an instance of the AWS Security Token Service client
AWSSecurityTokenServiceClient
2 Start a session by calling the getFederationToken method of the STS client you
created in the preceding step
You will need to provide session information including the user name and an IAM policy
that you want to attach to the temporary credentials
This method returns your temporary security credentials
API Version 20060301
36Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
3 Package the temporary security credentials in an instance of the
BasicSessionCredentials object You use this object to provide the temporary
security credentials to your Amazon S3 client
4 Create an instance of the AmazonS3Client class by passing the temporary security
credentials
You send requests to Amazon S3 using this client If you send requests using expired
credentials Amazon S3 returns an error
The following Java code sample demonstrates the preceding tasks
In real applications the following code is part of your trusted code It
has
your security credentials you use to obtain temporary security
credentials
AWSSecurityTokenServiceClient stsClient
new AWSSecurityTokenServiceClient(new
ProfileCredentialsProvider())
GetFederationTokenRequest getFederationTokenRequest
new GetFederationTokenRequest()
getFederationTokenRequestsetDurationSeconds(7200)
getFederationTokenRequestsetName(User1)
Define the policy and add to the request
Policy policy new Policy()
Define the policy here
Add the policy to the request
getFederationTokenRequestsetPolicy(policytoJson())
GetFederationTokenResult federationTokenResult
stsClientgetFederationToken(getFederationTokenRequest)
Credentials sessionCredentials federationTokenResultgetCredentials()
Package the session credentials as a BasicSessionCredentials object
for an S3 client object to use
BasicSessionCredentials basicSessionCredentials new
BasicSessionCredentials(
sessionCredentialsgetAccessKeyId()
sessionCredentialsgetSecretAccessKey()
sessionCredentialsgetSessionToken())
The following will be part of your less trusted code You provide
temporary security
credentials so it can send authenticated requests to Amazon S3
Create an Amazon S3 client by passing in the basicSessionCredentials
object
AmazonS3Client s3 new AmazonS3Client(basicSessionCredentials)
Test For example send list object keys in a bucket
ObjectListing objects s3listObjects(bucketName)
To set a condition in the policy create a Condition object and associate it with the policy The
following code sample shows a condition that allows users from a specified IP range to list objects
Policy policy new Policy()
API Version 20060301
37Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Allow only a specified IP range
Condition condition new
StringCondition(StringConditionStringComparisonTypeStringLike
ConditionFactorySOURCE_IP_CONDITION_KEY 192168143*)

policywithStatements(new Statement(EffectAllow)
withActions(S3ActionsListObjects)
withConditions(condition)
withResources(new Resource(arnawss3+ bucketName)))
getFederationTokenRequestsetPolicy(policytoJson())
API Version 20060301
38Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Example
The following Java code example lists keys in the specified bucket In the code example you first
obtain temporary security credentials for a twohour session for your federated user (User1) and use
them to send authenticated requests to Amazon S3
When requesting temporary credentials for others for added security you use the security credentials
of an IAM user who has permissions to request temporary security credentials You can also limit the
access permissions of this IAM user to ensure that the IAM user grants only the minimum application
specific permissions when requesting temporary security credentials This sample only lists objects in a
specific bucket Therefore first create an IAM user with the following policy attached
{
Statement[{
Action[s3ListBucket
stsGetFederationToken*
]
EffectAllow
Resource*
}
]
}
The policy allows the IAM user to request temporary security credentials and access permission only to
list your AWS resources For information about how to create an IAM user see Creating Your First IAM
User and Administrators Group in the IAM User Guide
You can now use the IAM user security credentials to test the following example The example sends
authenticated request to Amazon S3 using temporary security credentials The example specifies the
following policy when requesting temporary security credentials for the federated user (User1) which
restricts access to list objects in a specific bucket (YourBucketName) You must update the policy and
provide your own existing bucket name
{
Statement[
{
Sid1
Action[s3ListBucket]
EffectAllow
Resourcearnawss3YourBucketName
}
]
}
You must update the following sample and provide the bucket name that you specified in the preceding
federated user access policy
import javaioIOException
import comamazonawsauthBasicSessionCredentials
import comamazonawsauthPropertiesCredentials
import comamazonawsauthpolicyPolicy
import comamazonawsauthpolicyResource
import comamazonawsauthpolicyStatement
import comamazonawsauthpolicyStatementEffect
import comamazonawsauthpolicyactionsS3Actions
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicessecuritytokenAWSSecurityTokenServiceClient
import comamazonawsservicessecuritytokenmodelCredentials
import comamazonawsservicessecuritytokenmodelGetFederationTokenRequest
import comamazonawsservicessecuritytokenmodelGetFederationTokenResult
import comamazonawsservicess3modelObjectListing
public class S3Sample {
private static String bucketName *** Specify bucket name ***
public static void main(String[] args) throws IOException {
AWSSecurityTokenServiceClient stsClient
new AWSSecurityTokenServiceClient(new
ProfileCredentialsProvider())
GetFederationTokenRequest getFederationTokenRequest
new GetFederationTokenRequest()
getFederationTokenRequestsetDurationSeconds(7200)
getFederationTokenRequestsetName(User1)

Define the policy and add to the request
Policy policy new Policy()
policywithStatements(new Statement(EffectAllow)
withActions(S3ActionsListObjects)
withResources(new Resource(arnawss3ExampleBucket)))
getFederationTokenRequestsetPolicy(policytoJson())

Get the temporary security credentials
GetFederationTokenResult federationTokenResult

stsClientgetFederationToken(getFederationTokenRequest)
Credentials sessionCredentials
federationTokenResultgetCredentials()

Package the session credentials as a BasicSessionCredentials
object for an S3 client object to use
BasicSessionCredentials basicSessionCredentials
new
BasicSessionCredentials(sessionCredentialsgetAccessKeyId()
sessionCredentialsgetSecretAccessKey()
sessionCredentialsgetSessionToken())
AmazonS3Client s3 new AmazonS3Client(basicSessionCredentials)

Test For example send ListBucket request using the temporary
security credentials
ObjectListing objects s3listObjects(bucketName)
Systemoutprintln(No of Objects +
objectsgetObjectSummaries()size())
}
}
API Version 20060301
39Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
Making Requests Using Federated User Temporary
Credentials AWS SDK for NET
You can provide temporary security credentials for your federated users and applications (see Making
Requests (p 11)) so they can send authenticated requests to access your AWS resources When
requesting these temporary credentials you must provide a user name and an IAM policy describing
the resource permissions you want to grant By default the session duration is one hour You can
explicitly set a different duration value when requesting the temporary security credentials for federated
users and applications
Note
To request temporary security credentials for federated users and applications for added
security you might want to use a dedicated IAM user with only the necessary access
permissions The temporary user you create can never get more permissions than the IAM
user who requested the temporary security credentials For more information go to AWS
Identity and Access Management FAQs
Making Requests Using Federated User Temporary Credentials
1 Create an instance of the AWS Security Token Service client
AmazonSecurityTokenServiceClient class For information about providing
credentials see Using the AWS SDK for NET (p 565)
2 Start a session by calling the GetFederationToken method of the STS client
You will need to provide session information including the user name and an IAM
policy that you want to attach to the temporary credentials You can provide an optional
session duration
This method returns your temporary security credentials
3 Package the temporary security credentials in an instance of the
SessionAWSCredentials object You use this object to provide the temporary
security credentials to your Amazon S3 client
4 Create an instance of the AmazonS3Client class by passing the temporary security
credentials
You send requests to Amazon S3 using this client If you send requests using expired
credentials Amazon S3 returns an error
The following C# code sample demonstrates the preceding tasks
In real applications the following code is part of your trusted code It
has
your security credentials you use to obtain temporary security
credentials
AmazonSecurityTokenServiceConfig config new
AmazonSecurityTokenServiceConfig()
AmazonSecurityTokenServiceClient stsClient
new AmazonSecurityTokenServiceClient(config)

GetFederationTokenRequest federationTokenRequest
new GetFederationTokenRequest()
federationTokenRequestName User1
API Version 20060301
40Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
federationTokenRequestPolicy *** Specify policy ***
federationTokenRequestDurationSeconds 7200
GetFederationTokenResponse federationTokenResponse
stsClientGetFederationToken(federationTokenRequest)
GetFederationTokenResult federationTokenResult
federationTokenResponseGetFederationTokenResult
Credentials credentials federationTokenResultCredentials
SessionAWSCredentials sessionCredentials
new SessionAWSCredentials(credentialsAccessKeyId
credentialsSecretAccessKey
credentialsSessionToken)
The following will be part of your less trusted code You provide
temporary security
credentials so it can send authenticated requests to Amazon S3
Create Amazon S3 client by passing in the basicSessionCredentials object
AmazonS3Client s3Client new AmazonS3Client(sessionCredentials)
Test For example send list object keys in a bucket
ListObjectsRequest listObjectRequest new ListObjectsRequest()
listObjectRequestBucketName bucketName
ListObjectsResponse response s3ClientListObjects(listObjectRequest)
API Version 20060301
41Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Example
The following C# code example lists keys in the specified bucket In the code example you first obtain
temporary security credentials for a twohour session for your federated user (User1) and use them to
send authenticated requests to Amazon S3
When requesting temporary credentials for others for added security you use the security credentials
of an IAM user who has permissions to request temporary security credentials You can also limit
the access permissions of this IAM user to ensure that the IAM user grants only the minimum
applicationspecific permissions to the federated user This sample only lists objects in a specific
bucket Therefore first create an IAM user with the following policy attached
{
Statement[{
Action[s3ListBucket
stsGetFederationToken*
]
EffectAllow
Resource*
}
]
}
The policy allows the IAM user to request temporary security credentials and access permission only
to list your AWS resources For more information about how to create an IAM user see Creating Your
First IAM User and Administrators Group in the IAM User Guide
You can now use the IAM user security credentials to test the following example The example sends
authenticated request to Amazon S3 using temporary security credentials The example specifies the
following policy when requesting temporary security credentials for the federated user (User1) which
restricts access to list objects in a specific bucket (YourBucketName) You must update the policy and
provide your own existing bucket name
{
Statement[
{
Sid1
Action[s3ListBucket]
EffectAllow
Resourcearnawss3YourBucketName
}
]
}
You must update the following sample and provide the bucket name that you specified in the preceding
federated user access policy For instructions on how to create and test a working example see
Running the Amazon S3 NET Code Examples (p 566)
using System
using SystemConfiguration
using SystemCollectionsSpecialized
using AmazonS3
using AmazonSecurityToken
using AmazonSecurityTokenModel
using AmazonRuntime
using AmazonS3Model
using SystemCollectionsGeneric
namespace s3amazoncomdocsamples
{
class TempFederatedCredentials
{
static string bucketName *** Provide bucket name ***
static IAmazonS3 client
public static void Main(string[] args)
{
NameValueCollection appConfig ConfigurationManagerAppSettings
string accessKeyID appConfig[AWSAccessKey]
string secretAccessKeyID appConfig[AWSSecretKey]
try
{
ConsoleWriteLine(Listing objects stored in a bucket)
SessionAWSCredentials tempCredentials
GetTemporaryFederatedCredentials(accessKeyID
secretAccessKeyID)

Create client by providing temporary security credentials
using (client new AmazonS3Client(tempCredentials
AmazonRegionEndpointUSEast1))
{
ListObjectsRequest listObjectRequest new
ListObjectsRequest()
listObjectRequestBucketName bucketName
ListObjectsResponse response
clientListObjects(listObjectRequest)
List objects responseS3Objects
ConsoleWriteLine(Object count {0} objectsCount)
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
}
catch (AmazonS3Exception s3Exception)
{
ConsoleWriteLine(s3ExceptionMessage
s3ExceptionInnerException)
}
catch (AmazonSecurityTokenServiceException stsException)
{
ConsoleWriteLine(stsExceptionMessage
stsExceptionInnerException)
}
}
private static SessionAWSCredentials GetTemporaryFederatedCredentials(
string accessKeyId string secretAccessKeyId)
{
AmazonSecurityTokenServiceConfig config new
AmazonSecurityTokenServiceConfig()
AmazonSecurityTokenServiceClient stsClient
new AmazonSecurityTokenServiceClient(
accessKeyId secretAccessKeyId
config)

GetFederationTokenRequest federationTokenRequest
new GetFederationTokenRequest()
federationTokenRequestDurationSeconds 7200
federationTokenRequestName User1
federationTokenRequestPolicy @{
Statement
[
{
SidStmt1311212314284
Action[s3ListBucket]
EffectAllow
Resourcearnawss3YourBucketName
}
]
}


GetFederationTokenResponse federationTokenResponse

stsClientGetFederationToken(federationTokenRequest)
Credentials credentials federationTokenResponseCredentials
SessionAWSCredentials sessionCredentials
new SessionAWSCredentials(credentialsAccessKeyId
credentialsSecretAccessKey
credentialsSessionToken)
return sessionCredentials
}
}
}
API Version 20060301
42Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
Making Requests Using Federated User Temporary
Credentials AWS SDK for PHP
This topic guides you through using classes from the AWS SDK for PHP to request temporary security
credentials for federated users and applications and use them to access Amazon S3
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
You can provide temporary security credentials to your federated users and applications (see Making
Requests (p 11)) so they can send authenticated requests to access your AWS resources When
requesting these temporary credentials you must provide a user name and an IAM policy describing
the resource permissions you want to grant These credentials expire when the session duration
expires By default the session duration is one hour You can explicitly set a different duration value
when requesting the temporary security credentials for federated users and applications For more
information about temporary security credentials see Temporary Security Credentials in the IAM User
Guide
To request temporary security credentials for federated users and applications for added security
you might want to use a dedicated IAM user with only the necessary access permissions The
temporary user you create can never get more permissions than the IAM user who requested the
temporary security credentials For information about identity federation go to AWS Identity and
Access Management FAQs
Making Requests Using Federated User Temporary Credentials
1 Create an instance of an AWS Security Token Service (AWS STS) client by using the
Aws＼Sts＼StsClient class factory() method
2 Execute the Aws＼Sts＼StsClientgetFederationToken() method by providing the name
of the federated user in the array parameter＇s required Name key You can also add
the optional array parameter＇s Policy and DurationSeconds keys
The method returns temporary security credentials that you can provide to your
federated users
3 Any federated user who has the temporary security credentials can send requests to
Amazon S3 by creating an instance of an Amazon S3 client by using Aws＼S3＼S3Client
class factory method with the temporary security credentials
Any methods in the S3Client class that you call use the temporary security
credentials to send authenticated requests to Amazon S3
The following PHP code sample demonstrates obtaining temporary security credentials for a federated
user and using the credentials to access Amazon S3
use Aws＼Sts＼StsClient
use Aws＼S3＼S3Client
In real applications the following code is part of your trusted code It
has
API Version 20060301
43Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
your security credentials that you use to obtain temporary security
credentials
sts StsClientfactory()
Fetch the federated credentials
result sts>getFederationToken(array(
＇Name＇ > ＇User1＇
＇DurationSeconds＇ > 3600
＇Policy＇ > json_encode(array(
＇Statement＇ > array(
array(
＇Sid＇ > ＇randomstatementid＇ time()
＇Action＇ > array(＇s3ListBucket＇)
＇Effect＇ > ＇Allow＇
＇Resource＇ > ＇arnawss3YourBucketName＇
)
)
))
))
The following will be part of your less trusted code You provide
temporary
security credentials so it can send authenticated requests to Amazon S3
credentials result>get(＇Credentials＇)
s3 new S3Clientfactory(array(
＇key＇ > credentials[＇AccessKeyId＇]
＇secret＇ > credentials[＇SecretAccessKey＇]
＇token＇ > credentials[＇SessionToken＇]
))
result s3>listObjects()
API Version 20060301
44Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Example of a Federated User Making an Amazon S3 Request Using Temporary Security
Credentials
The following PHP code example lists keys in the specified bucket In the code example you first
obtain temporary security credentials for an hour session for your federated user (User1) and use them
to send authenticated requests to Amazon S3 For information about running the PHP examples in this
guide go to Running PHP Examples (p 567)
When requesting temporary credentials for others for added security you use the security credentials
of an IAM user who has permissions to request temporary security credentials You can also limit the
access permissions of this IAM user to ensure that the IAM user grants only the minimum application
specific permissions to the federated user This example only lists objects in a specific bucket
Therefore first create an IAM user with the following policy attached
{
Statement[{
Action[s3ListBucket
stsGetFederationToken*
]
EffectAllow
Resource*
}
]
}
The policy allows the IAM user to request temporary security credentials and access permission only
to list your AWS resources For more information about how to create an IAM user see Creating Your
First IAM User and Administrators Group in the IAM User Guide
You can now use the IAM user security credentials to test the following example The example sends
an authenticated request to Amazon S3 using temporary security credentials The example specifies
the following policy when requesting temporary security credentials for the federated user (User1)
which restricts access to list objects in a specific bucket You must update the policy with your own
existing bucket name
{
Statement[
{
Sid1
Action[s3ListBucket]
EffectAllow
Resourcearnawss3YourBucketName
}
]
}
In the following example you must replace YourBucketName with your own existing bucket name when
specifying the policy resource
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
bucket ＇*** Your Bucket Name ***＇
use Aws＼Sts＼StsClient
use Aws＼S3＼S3Client
use Aws＼S3＼Exception＼S3Exception
Instantiate the client
sts StsClientfactory()
result sts>getFederationToken(array(
＇Name＇ > ＇User1＇
＇DurationSeconds＇ > 3600
＇Policy＇ > json_encode(array(
＇Statement＇ > array(
array(
＇Sid＇ > ＇randomstatementid＇ time()
＇Action＇ > array(＇s3ListBucket＇)
＇Effect＇ > ＇Allow＇
＇Resource＇ > ＇arnawss3YourBucketName＇
)
)
))
))
credentials result>get(＇Credentials＇)
s3 S3Clientfactory(array(
＇key＇ > credentials[＇AccessKeyId＇]
＇secret＇ > credentials[＇SecretAccessKey＇]
＇token＇ > credentials[＇SessionToken＇]
))
try {
objects s3>getIterator(＇ListObjects＇ array(
＇Bucket＇ > bucket
))
echo Keys retrieved＼n
foreach (objects as object) {
echo object[＇Key＇] ＼n
}
} catch (S3Exception e) {
echo e>getMessage() ＼n
}
API Version 20060301
45Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼Sts＼StsClient Class
• AWS SDK for PHP for Amazon S3 Aws＼Sts＼StsClientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼Sts＼StsClientgetSessionToken() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
API Version 20060301
46Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Making Requests Using Federated User Temporary
Credentials AWS SDK for Ruby
You can provide temporary security credentials for your federated users and applications (see Making
Requests (p 11)) so that they can send authenticated requests to access your AWS resources When
requesting these temporary credentials from the IAM service you must provide a user name and an
IAM policy describing the resource permissions you want to grant By default the session duration is
one hour However if you are requesting temporary credentials using IAM user credentials you can
explicitly set a different duration value when requesting the temporary security credentials for federated
users and applications
Note
To request temporary security credentials for federated users and applications for added
security you might want to use a dedicated IAM user with only the necessary access
permissions The temporary user you create can never get more permissions than the IAM
user who requested the temporary security credentials For more information go to AWS
Identity and Access Management FAQs
Making Requests Using Federated User Temporary Security Credentials
1 Create an instance of the AWS Security Token Service client AWSSTSSession
2 Start a session by calling the new_federated_session method of the STS client you
created in the preceding step
You will need to provide session information including the user name and an IAM policy
that you want to attach to the temporary credentials
This method returns your temporary security credentials
3 Create an instance of the AWSS3 class by passing the temporary security credentials
You send requests to Amazon S3 using this client If you send requests using expired
credentials Amazon S3 returns an error
The following Ruby code sample demonstrates the preceding tasks
# Start a session with restricted permissions
sts AWSSTSnew()
policy AWSSTSPolicynew
policyallow(
actions > [s3ListBucket]
resources > arnawss3#{bucket_name})

session stsnew_federated_session(
＇User1＇
policy > policy
duration > 2*60*60)
puts Policy #{policyto_json}
# Get an instance of the S3 interface using the session credentials
s3 AWSS3new(sessioncredentials)
# Get a list of all object keys in a bucket
bucket s3buckets[bucket_name]objectscollect(&key)
API Version 20060301
47Amazon Simple Storage Service Developer Guide
Using Federated User Temporary Credentials
Example
The following Ruby code example lists keys in the specified bucket In the code example you first
obtain temporary security credentials for a two hour session for your federated user (User1) and use
them to send authenticated requests to Amazon S3When requesting temporary credentials for others for added security you use the security credentials
of an IAM user who has permissions to request temporary security credentials You can also limit the
access permissions of this IAM user to ensure that the IAM user grants only the minimum application
specific permissions when requesting temporary security credentials This sample only lists objects in a
specific bucket Therefore first create an IAM user with the following policy attached
{
Statement[{
Action[s3ListBucket
stsGetFederationToken*
]
EffectAllow
Resource*
}
]
}The policy allows the IAM user to request temporary security credentials and access permission only
to list your AWS resources For more information about how to create an IAM user see Creating Your
First IAM User and Administrators Group in the IAM User GuideYou can now use the IAM user security credentials to test the following example The example sends
an authenticated request to Amazon S3 using temporary security credentials The example specifies
the following policy when requesting temporary security credentials for the federated user (User1)
which restricts access to listing objects in a specific bucket (YourBucketName) To use this example in
your code update the policy and provide your own bucket name
{
Statement[
{
Sid1
Action[s3ListBucket]
EffectAllow
Resourcearnawss3YourBucketName
}
]
}To use this example in your code provide your access key ID and secret key and the bucket name that
you specified in the preceding federated user access policyrequire ＇rubygems＇
require ＇awssdk＇
# In real applications the following code is part of your trusted code It
has
# your security credentials that you use to obtain temporary security
credentials
bucket_name ＇*** Provide bucket name ***＇
# Start a session with restricted permissions
sts AWSSTSnew()
policy AWSSTSPolicynew
policyallow(
actions > [s3ListBucket]
resources > arnawss3#{bucket_name})
session stsnew_federated_session(
＇User1＇
policy > policy
duration > 2*60*60)
puts Policy #{policyto_json}
# Get an instance of the S3 interface using the session credentials
s3 AWSS3new(sessioncredentials)
# Get a list of all object keys in a bucket
bucket s3buckets[bucket_name]objectscollect(&key)
puts No of Objects #{bucketcountto_s}
puts bucket
API Version 20060301
48Amazon Simple Storage Service Developer Guide
Making Requests Using the REST API
Making Requests Using the REST API
This section contains information on how to make requests to Amazon S3 endpoints by using the
REST API For a list of Amazon S3 endpoints see Regions and Endpoints in the AWS General
Reference
Topics
• Making Requests to DualStack Endpoints by Using the REST API (p 50)
• Virtual Hosting of Buckets (p 50)
• Request Redirection and the REST API (p 55)
When making requests by using the REST API you can use virtual hosted–style or pathstyle URIs for
the Amazon S3 endpoints For more information see Working with Amazon S3 Buckets (p 58)
Example Virtual Hosted–Style Request
Following is an example of a virtual hosted–style request to delete the puppyjpg file from the bucket
named examplebucket
DELETE puppyjpg HTTP11
Host examplebuckets3uswest2amazonawscom
Date Mon 11 Apr 2016 120000 GMT
xamzdate Mon 11 Apr 2016 120000 GMT
Authorization authorization string
Example PathStyle Request
Following is an example of a pathstyle version of the same request
DELETE examplebucketpuppyjpg HTTP11
Host s3uswest2amazonawscom
Date Mon 11 Apr 2016 120000 GMT
xamzdate Mon 11 Apr 2016 120000 GMT
Authorization authorization string

Amazon S3 supports virtual hostedstyle and pathstyle access in all regions The pathstyle syntax
however requires that you use the regionspecific endpoint when attempting to access a bucket
For example if you have a bucket called mybucket that resides in the EU (Ireland) region you want
to use pathstyle syntax and the object is named puppyjpg the correct URI is https3eu
west1amazonawscommybucketpuppyjpg
You will receive an HTTP response code 307 Temporary Redirect error and a message indicating
what the correct URI is for your resource if you try to access a bucket outside the US East (N Virginia)
region with pathstyle syntax that uses either of the following
• https3amazonawscom
• An endpoint for a region different from the one where the bucket resides For example if you use
https3euwest1amazonawscom for a bucket that was created in the US West (N
California) region
API Version 20060301
49Amazon Simple Storage Service Developer Guide
DualStack Endpoints (REST API)
Making Requests to DualStack Endpoints by Using
the REST API
When using the REST API you can directly access a dualstack endpoint by using a virtual hosted–
style or a path style endpoint name (URI) All Amazon S3 dualstack endpoint names include the
region in the name Unlike the standard IPv4only endpoints both virtual hosted–style and a pathstyle
endpoints use regionspecific endpoint names
Example Virtual Hosted–Style DualStack Endpoint Request
You can use a virtual hosted–style endpoint in your REST request as shown in the following example
that retrieves the puppyjpg object from the bucket named examplebucket
GET puppyjpg HTTP11
Host examplebuckets3dualstackuswest2amazonawscom
Date Mon 11 Apr 2016 120000 GMT
xamzdate Mon 11 Apr 2016 120000 GMT
Authorization authorization string
Example PathStyle DualStack Endpoint Request
Or you can use a pathstyle endpoint in your request as shown in the following example
GET examplebucketpuppyjpg HTTP11
Host s3dualstackuswest2amazonawscom
Date Mon 11 Apr 2016 120000 GMT
xamzdate Mon 11 Apr 2016 120000 GMT
Authorization authorization string
For more information about dualstack endpoints see Using Amazon S3 DualStack Endpoints (p 16)
Virtual Hosting of Buckets
Topics
• HTTP Host Header Bucket Specification (p 51)
• Examples (p 51)
• Customizing Amazon S3 URLs with CNAMEs (p 53)
• Limitations (p 54)
• Backward Compatibility (p 55)
In general virtual hosting is the practice of serving multiple web sites from a single web server
One way to differentiate sites is by using the apparent host name of the request instead of just the
path name part of the URI An ordinary Amazon S3 REST request specifies a bucket by using the
first slashdelimited component of the RequestURI path Alternatively you can use Amazon S3
virtual hosting to address a bucket in a REST API call by using the HTTP Host header In practice
Amazon S3 interprets Host as meaning that most buckets are automatically accessible (for limited
types of requests) at httpbucketnames3amazonawscom Furthermore by naming your
bucket after your registered domain name and by making that name a DNS alias for Amazon S3
you can completely customize the URL of your Amazon S3 resources for example http
mybucketnamecom
Besides the attractiveness of customized URLs a second benefit of virtual hosting is the ability to
publish to the root directory of your bucket＇s virtual server This ability can be important because
API Version 20060301
50Amazon Simple Storage Service Developer Guide
Virtual Hosting of Buckets
many existing applications search for files in this standard location For example faviconico
robotstxt crossdomainxml are all expected to be found at the root
Important
Amazon S3 supports virtual hostedstyle and pathstyle access in all regions The pathstyle
syntax however requires that you use the regionspecific endpoint when attempting to access
a bucket For example if you have a bucket called mybucket that resides in the EU (Ireland)
region you want to use pathstyle syntax and the object is named puppyjpg the correct
URI is https3euwest1amazonawscommybucketpuppyjpg
You will receive an HTTP response code 307 Temporary Redirect error and a message
indicating what the correct URI is for your resource if you try to access a bucket outside the
US East (N Virginia) region with pathstyle syntax that uses either of the following
• https3amazonawscom
• An endpoint for a region different from the one where the bucket resides For example if
you use https3euwest1amazonawscom for a bucket that was created in the US
West (N California) region
Note
Amazon S3 routes any virtual hosted–style requests to the US East (N Virginia) region by
default if you use the US East (N Virginia) endpoint (s3amazonawscom) instead of the
regionspecific endpoint (for example s3euwest1amazonawscom) When you create a
bucket in any region Amazon S3 updates DNS to reroute the request to the correct location
which might take time In the meantime the default rule applies and your virtual hosted–style
request goes to the US East (N Virginia) region and Amazon S3 redirects it with HTTP 307
redirect to the correct region For more information see Request Redirection and the REST
API (p 513)
When using virtual hosted–style buckets with SSL the SSL wild card certificate only matches
buckets that do not contain periods To work around this use HTTP or write your own
certificate verification logic
HTTP Host Header Bucket Specification
As long as your GET request does not use the SSL endpoint you can specify the bucket for the request
by using the HTTP Host header The Host header in a REST request is interpreted as follows
• If the Host header is omitted or its value is ＇s3amazonawscom＇ the bucket for the request will be
the first slashdelimited component of the RequestURI and the key for the request will be the rest of
the RequestURI This is the ordinary method as illustrated by the first and second examples in this
section Omitting the Host header is valid only for HTTP 10 requests
• Otherwise if the value of the Host header ends in ＇s3amazonawscom＇ the bucket name is the
leading component of the Host header＇s value up to ＇s3amazonawscom＇ The key for the request
is the RequestURI This interpretation exposes buckets as subdomains of s3amazonawscom as
illustrated by the third and fourth examples in this section
• Otherwise the bucket for the request is the lowercase value of the Host header and the key for the
request is the RequestURI This interpretation is useful when you have registered the same DNS
name as your bucket name and have configured that name to be a CNAME alias for Amazon S3
The procedure for registering domain names and configuring DNS is beyond the scope of this guide
but the result is illustrated by the final example in this section
Examples
This section provides example URLs and requests
API Version 20060301
51Amazon Simple Storage Service Developer Guide
Virtual Hosting of Buckets
Example Path Style Method
This example uses johnsmithnet as the bucket name and homepagehtml as the key name
The URL is as follows
https3amazonawscomjohnsmithnethomepagehtml
The request is as follows
GET johnsmithnethomepagehtml HTTP11
Host s3amazonawscom
The request with HTTP 10 and omitting the host header is as follows
GET johnsmithnethomepagehtml HTTP10
For information about DNScompatible names see Limitations (p 54) For more information about
keys see Keys (p 4)
Example Virtual Hosted–Style Method
This example uses johnsmithnet as the bucket name and homepagehtml as the key name
The URL is as follows
httpjohnsmithnets3amazonawscomhomepagehtml
The request is as follows
GET homepagehtml HTTP11
Host johnsmithnets3amazonawscom
The virtual hosted–style method requires the bucket name to be DNScompliant
API Version 20060301
52Amazon Simple Storage Service Developer Guide
Virtual Hosting of Buckets
Example Virtual Hosted–Style Method for a Bucket in a Region Other Than US East (N
Virginia) region
This example uses johnsmitheu as the name for a bucket in the EU (Ireland) region and
homepagehtml as the key name
The URL is as follows
httpjohnsmitheus3euwest1amazonawscomhomepagehtml
The request is as follows
GET homepagehtml HTTP11
Host johnsmitheus3euwest1amazonawscom
Note that instead of using the regionspecific endpoint you can also use the US East (N Virginia)
region endpoint no matter what region the bucket resides
httpjohnsmitheus3amazonawscomhomepagehtml
The request is as follows
GET homepagehtml HTTP11
Host johnsmitheus3amazonawscom
Example CNAME Method
This example uses wwwjohnsmithnet as the bucket name and homepagehtml as the
key name To use this method you must configure your DNS name as a CNAME alias for
bucketnames3amazonawscom
The URL is as follows
httpwwwjohnsmithnethomepagehtml
The example is as follows
GET homepagehtml HTTP11
Host wwwjohnsmithnet
Customizing Amazon S3 URLs with CNAMEs
Depending on your needs you might not want s3amazonawscom to appear on your website or
service For example if you host your website images on Amazon S3 you might prefer http
imagesjohnsmithnet instead of httpjohnsmithimagess3amazonawscom
The bucket name must be the same as the CNAME So httpimagesjohnsmithnet
filename would be the same as httpimagesjohnsmithnets3amazonawscom
filename if a CNAME were created to map imagesjohnsmithnet to
imagesjohnsmithnets3amazonawscom
Any bucket with a DNScompatible name can be referenced as follows http
[BucketName]s3amazonawscom[Filename] for example http
API Version 20060301
53Amazon Simple Storage Service Developer Guide
Virtual Hosting of Buckets
imagesjohnsmithnets3amazonawscommydogjpg By using CNAME you can map
imagesjohnsmithnet to an Amazon S3 host name so that the previous URL could become
httpimagesjohnsmithnetmydogjpg
The CNAME DNS record should alias your domain name to the appropriate virtual hosted–style
host name For example if your bucket name and domain name are imagesjohnsmithnet the
CNAME record should alias to imagesjohnsmithnets3amazonawscom
imagesjohnsmithnet CNAME imagesjohnsmithnets3amazonawscom
Setting the alias target to s3amazonawscom also works but it may result in extra HTTP redirects
Amazon S3 uses the host name to determine the bucket name For example suppose that you have
configured wwwexamplecom as a CNAME for wwwexamplecoms3amazonawscom When you
access httpwwwexamplecom Amazon S3 receives a request similar to the following
GET HTTP11
Host wwwexamplecom
Date date
Authorization signatureValue
Because Amazon S3 sees only the original host name wwwexamplecom and is unaware of the
CNAME mapping used to resolve the request the CNAME and the bucket name must be the same
Any Amazon S3 endpoint can be used in a CNAME For example s3ap
southeast1amazonawscom can be used in CNAMEs For more information about endpoints see
Request Endpoints (p 13)
To associate a host name with an Amazon S3 bucket using CNAMEs
1 Select a host name that belongs to a domain you control This example uses the images
subdomain of the johnsmithnet domain
2 Create a bucket that matches the host name In this example the host and bucket names are
imagesjohnsmithnet
Note
The bucket name must exactly match the host name
3 Create a CNAME record that defines the host name as an alias for the Amazon S3 bucket For
example
imagesjohnsmithnet CNAME imagesjohnsmithnets3amazonawscom
Important
For request routing reasons the CNAME record must be defined exactly as shown in the
preceding example Otherwise it might appear to operate correctly but will eventually
result in unpredictable behavior
Note
The procedure for configuring DNS depends on your DNS server or DNS provider For
specific information see your server documentation or contact your provider
Limitations
Specifying the bucket for the request by using the HTTP Host header is supported for nonSSL
requests and when using the REST API You cannot specify the bucket in SOAP by using a different
endpoint
API Version 20060301
54Amazon Simple Storage Service Developer Guide
Request Redirection and the REST API
Note
SOAP support over HTTP is deprecated but it is still available over HTTPS New Amazon S3
features will not be supported for SOAP We recommend that you use either the REST API or
the AWS SDKs
Backward Compatibility
Early versions of Amazon S3 incorrectly ignored the HTTP Host header Applications that depend on
this undocumented behavior must be updated to set the Host header correctly Because Amazon S3
determines the bucket name from Host when it is present the most likely symptom of this problem is
to receive an unexpected NoSuchBucket error result code
Request Redirection and the REST API
Topics
• Redirects and HTTP UserAgents (p 55)
• Redirects and 100Continue (p 55)
• Redirect Example (p 56)
This section describes how to handle HTTP redirects by using the Amazon S3 REST API For general
information about Amazon S3 redirects see Request Redirection and the REST API (p 513) in the
Amazon Simple Storage Service API Reference
Redirects and HTTP UserAgents
Programs that use the Amazon S3 REST API should handle redirects either at the application layer
or the HTTP layer Many HTTP client libraries and user agents can be configured to correctly handle
redirects automatically however many others have incorrect or incomplete redirect implementations
Before you rely on a library to fulfill the redirect requirement test the following cases
• Verify all HTTP request headers are correctly included in the redirected request (the second request
after receiving a redirect) including HTTP standards such as Authorization and Date
• Verify nonGET redirects such as PUT and DELETE work correctly
• Verify large PUT requests follow redirects correctly
• Verify PUT requests follow redirects correctly if the 100continue response takes a long time to
arrive
HTTP useragents that strictly conform to RFC 2616 might require explicit confirmation before following
a redirect when the HTTP request method is not GET or HEAD It is generally safe to follow redirects
generated by Amazon S3 automatically as the system will issue redirects only to hosts within the
amazonawscom domain and the effect of the redirected request will be the same as that of the original
request
Redirects and 100Continue
To simplify redirect handling improve efficiencies and avoid the costs associated with sending a
redirected request body twice configure your application to use 100continues for PUT operations
When your application uses 100continue it does not send the request body until it receives an
acknowledgement If the message is rejected based on the headers the body of the message is not
sent For more information about 100continue go to RFC 2616 Section 823
Note
According to RFC 2616 when using Expect Continue with an unknown HTTP server
you should not wait an indefinite period before sending the request body This is because
API Version 20060301
55Amazon Simple Storage Service Developer Guide
Request Redirection and the REST API
some HTTP servers do not recognize 100continue However Amazon S3 does recognize
if your request contains an Expect Continue and will respond with a provisional 100
continue status or a final status code Additionally no redirect error will occur after receiving
the provisional 100 continue goahead This will help you avoid receiving a redirect response
while you are still writing the request body
Redirect Example
This section provides an example of clientserver interaction using HTTP redirects and 100continue
Following is a sample PUT to the quotess3amazonawscom bucket
PUT nelsontxt HTTP11
Host quotess3amazonawscom
Date Mon 15 Oct 2007 221846 +0000
ContentLength 6
Expect 100continue
Amazon S3 returns the following
HTTP11 307 Temporary Redirect
Location httpquotess34c25d83bamazonawscomnelsontxtrk8d47490b
ContentType applicationxml
TransferEncoding chunked
Date Mon 15 Oct 2007 221846 GMT
Server AmazonS3


TemporaryRedirect
Please resend this request to the
specified temporary endpoint Continue to use the
original request endpoint for future requests

quotess34c25d83bamazonawscom
quotes

The client follows the redirect response and issues a new request to the
quotess34c25d83bamazonawscom temporary endpoint
PUT nelsontxtrk8d47490b HTTP11
Host quotess34c25d83bamazonawscom
Date Mon 15 Oct 2007 221846 +0000
ContentLength 6
Expect 100continue
Amazon S3 returns a 100continue indicating the client should proceed with sending the request body
HTTP11 100 Continue
The client sends the request body
API Version 20060301
56Amazon Simple Storage Service Developer Guide
Request Redirection and the REST API
ha ha＼n
Amazon S3 returns the final response
HTTP11 200 OK
Date Mon 15 Oct 2007 221848 GMT
ETag a2c8d6b872054293afd41061e93bc289
ContentLength 0
Server AmazonS3
API Version 20060301
57Amazon Simple Storage Service Developer Guide
Working with Amazon S3 Buckets
Amazon S3 is cloud storage for the Internet To upload your data (photos videos documents etc)
you first create a bucket in one of the AWS Regions You can then upload any number of objects to the
bucket
In terms of implementation buckets and objects are resources and Amazon S3 provides APIs for you
to manage them For example you can create a bucket and upload objects using the Amazon S3 API
You can also use the Amazon S3 console to perform these operations The console internally uses the
Amazon S3 APIs to send requests to Amazon S3
In this section we explain working with buckets For information about working with objects see
Working with Amazon S3 Objects (p 98)
Amazon S3 bucket names are globally unique regardless of the AWS Region in which you create the
bucket You specify the name at the time you create the bucket For bucket naming guidelines see
Bucket Restrictions and Limitations (p 62)
Amazon S3 creates bucket in a region you specify You can choose any AWS Region that is
geographically close to you to optimize latency minimize costs or address regulatory requirements
For example if you reside in Europe you might find it advantageous to create buckets in the EU
(Ireland) or EU (Frankfurt) regions For a list of AWS Amazon S3 regions go to Regions and Endpoints
in the AWS General Reference
Note
Objects belonging to a bucket that you create in a specific AWS Region never leave that
region unless you explicitly transfer them to another region For example objects stored in
the EU (Ireland) region never leave it
Topics
• Creating a Bucket (p 59)
• Accessing a Bucket (p 60)
• Bucket Configuration Options (p 61)
• Bucket Restrictions and Limitations (p 62)
• Examples of Creating a Bucket (p 64)
• Deleting or Emptying a Bucket (p 67)
• Managing Bucket Website Configuration (p 73)
API Version 20060301
58Amazon Simple Storage Service Developer Guide
Creating a Bucket
• Amazon S3 Transfer Acceleration (p 81)
• Requester Pays Buckets (p 92)
• Buckets and Access Control (p 96)
• Billing and Reporting of Buckets (p 96)
Creating a Bucket
Amazon S3 provides APIs for you to create and manage buckets By default you can create up to 100
buckets in each of your AWS accounts If you need additional buckets you can increase your bucket
limit by submitting a service limit increase To learn more about submitting a bucket limit increase go
to AWS Service Limits in the AWS General Reference
When you create a bucket you provide a name and AWS Region where you want the bucket created
For information about naming buckets see Rules for Bucket Naming (p 63)
Within each bucket you can store any number of objects You can create a bucket using any of the
following methods
• Create the bucket using the console
• Create the bucket programmatically using the AWS SDKs
Note
If you need to you can also make the Amazon S3 REST API calls directly from your code
However this can be cumbersome because it requires you to write code to authenticate
your requests For more information go to PUT Bucket in the Amazon Simple Storage
Service API Reference
When using AWS SDKs you first create a client and then send a request to create a bucket using
the client You can specify an AWS Region when you create the client US East (N Virginia) is the
default region You can also specify a region in your create bucket request Note the following
• If you create a client by specifying the US East (N Virginia) Region it uses the following endpoint
to communicate with Amazon S3
s3amazonawscom
You can use this client to create a bucket in any AWS Region In your create bucket request
• If you don’t specify a region Amazon S3 creates the bucket in the US East (N Virginia) Region
• If you specify an AWS Region Amazon S3 creates the bucket in the specified region
• If you create a client by specifying any other AWS Region each of these regions maps to the
regionspecific endpoint
s3amazonawscom
For example if you create a client by specifying the euwest1 region it maps to the following
regionspecific endpoint
s3euwest1amazonawscom
In this case you can use the client to create a bucket only in the euwest1 region Amazon S3
returns an error if you specify any other region in your create bucket request
• If you create a client to access a dualstack endpoint you must specify an AWS Region For more
information see DualStack Endpoints (p 16)
API Version 20060301
59Amazon Simple Storage Service Developer Guide
About Permissions
For a list of available AWS Regions go to Regions and Endpoints in the AWS General Reference
For examples see Examples of Creating a Bucket (p 64)
About Permissions
You can use your AWS account root credentials to create a bucket and perform any other Amazon S3
operation However AWS recommends not using the root credentials of your AWS account to make
requests such as create a bucket Instead create an IAM user and grant that user full access (users
by default have no permissions) We refer to these users as administrator users You can use the
administrator user credentials instead of the root credentials of your account to interact with AWS and
perform tasks such as create a bucket create users and grant them permissions
For more information go to Root Account Credentials vs IAM User Credentials in the AWS General
Reference and IAM Best Practices in the IAM User Guide
The AWS account that creates a resource owns that resource For example if you create an IAM
user in your AWS account and grant the user permission to create a bucket the user can create a
bucket But the user does not own the bucket the AWS account to which the user belongs owns the
bucket The user will need additional permission from the resource owner to perform any other bucket
operations For more information about managing permissions for your Amazon S3 resources see
Managing Access Permissions to Your Amazon S3 Resources (p 266)
Accessing a Bucket
You can access your bucket using the Amazon S3 console Using the console UI you can perform
almost all bucket operations without having to write any code
If you access a bucket programmatically note that Amazon S3 supports RESTful architecture in which
your buckets and objects are resources each with a resource URI that uniquely identify the resource
Amazon S3 supports both virtualhosted–style and pathstyle URLs to access a bucket
• In a virtualhosted–style URL the bucket name is part of the domain name in the URL For example

• httpbuckets3amazonawscom
• httpbuckets3awsregionamazonawscom
In a virtualhosted–style URL you can use either of these endpoints If you make a request to the
httpbuckets3amazonawscom endpoint the DNS has sufficient information to route your
request directly to the region where your bucket resides
For more information see Virtual Hosting of Buckets (p 50)

• In a pathstyle URL the bucket name is not part of the domain (unless you use a regionspecific
endpoint) For example
• US East (N Virginia) region endpoint https3amazonawscombucket
• Regionspecific endpoint https3awsregionamazonawscombucket
In a pathstyle URL the endpoint you use must match the region in which the bucket resides For
example if your bucket is in the South America (São Paulo) region you must use the http
s3saeast1amazonawscombucket endpoint If your bucket is in the US East (N Virginia)
region you must use the https3amazonawscombucket endpoint
API Version 20060301
60Amazon Simple Storage Service Developer Guide
Bucket Configuration Options
Important
Because buckets can be accessed using pathstyle and virtualhosted–style URLs we
recommend you create buckets with DNScompliant bucket names For more information see
Bucket Restrictions and Limitations (p 62)
Accessing an S3 Bucket over IPv6
Amazon S3 has a set of dualstack endpoints which support requests to S3 buckets over both Internet
Protocol version 6 (IPv6) and IPv4 For more information see Making Requests over IPv6 (p 13)
Bucket Configuration Options
Amazon S3 supports various options for you to configure your bucket For example you can configure
your bucket for website hosting add configuration to manage lifecycle of objects in the bucket and
configure the bucket to log all access to the bucket Amazon S3 supports subresources for you to
store and manage the bucket configuration information That is using the Amazon S3 API you can
create and manage these subresources You can also use the console or the AWS SDKs
Note
There are also objectlevel configurations For example you can configure objectlevel
permissions by configuring an access control list (ACL) specific to that object
These are referred to as subresources because they exist in the context of a specific bucket or object
The following table lists subresources that enable you to manage bucketspecific configurations
Subresource Description
location When you create a bucket you specify the AWS Region where you want
Amazon S3 to create the bucket Amazon S3 stores this information in the
location subresource and provides an API for you to retrieve this information
policy and ACL
(Access Control
List)
All your resources (such as buckets and objects) are private by default Amazon
S3 supports both bucket policy and access control list (ACL) options for you to
grant and manage bucketlevel permissions Amazon S3 stores the permission
information in the policy and acl subresources
For more information see Managing Access Permissions to Your Amazon S3
Resources (p 266)
cors (crossorigin
resource sharing)
You can configure your bucket to allow crossorigin requests
For more information see Enabling CrossOrigin Resource Sharing
website You can configure your bucket for static website hosting Amazon S3 stores this
configuration by creating a website subresource
For more information see Hosting a Static Website on Amazon S3
logging Logging enables you to track requests for access to your bucket Each
access log record provides details about a single access request such as the
requester bucket name request time request action response status and
error code if any Access log information can be useful in security and access
audits It can also help you learn about your customer base and understand
your Amazon S3 bill
For more information see Server Access Logging (p 546)
event notification You can enable your bucket to send you notifications of specified bucket events
API Version 20060301
61Amazon Simple Storage Service Developer Guide
Restrictions and Limitations
Subresource Description
For more information see Configuring Amazon S3 Event
Notifications (p 472)
versioning Versioning helps you recover accidental overwrites and deletes
We recommend versioning as a best practice to recover objects from being
deleted or overwritten by mistake
For more information see Using Versioning (p 423)
lifecycle You can define lifecycle rules for objects in your bucket that have a welldefined
lifecycle For example you can define a rule to archive objects one year after
creation or delete an object 10 years after creation
For more information see Object Lifecycle Management
crossregion
replication
Crossregion replication is the automatic asynchronous copying of objects
across buckets in different AWS Regions For more information see Cross
Region Replication (p 492)
tagging You can add cost allocation tags to your bucket to categorize and track your
AWS costs Amazon S3 provides the tagging subresource to store and manage
tags on a bucket Using tags you apply to your bucket AWS generates a cost
allocation report with usage and costs aggregated by your tags
For more information see Billing and Reporting of Buckets (p 96)
requestPayment By default the AWS account that creates the bucket (the bucket owner) pays
for downloads from the bucket Using this subresource the bucket owner
can specify that the person requesting the download will be charged for the
download Amazon S3 provides an API for you to manage this subresource
For more information see Requester Pays Buckets (p 92)
transfer
acceleration
Transfer Acceleration enables fast easy and secure transfers of files over long
distances between your client and an S3 bucket Transfer Acceleration takes
advantage of Amazon CloudFront’s globally distributed edge locations
For more information see Amazon S3 Transfer Acceleration (p 81)
Bucket Restrictions and Limitations
A bucket is owned by the AWS account that created it By default you can create up to 100 buckets
in each of your AWS accounts If you need additional buckets you can increase your bucket limit by
submitting a service limit increase For information about how to increase your bucket limit go to AWS
Service Limits in the AWS General Reference
Bucket ownership is not transferable however if a bucket is empty you can delete it After a bucket
is deleted the name becomes available to reuse but the name might not be available for you to reuse
for various reasons For example some other account could create a bucket with that name Note too
that it might take some time before the name can be reused So if you want to use the same bucket
name don＇t delete the bucket
There is no limit to the number of objects that can be stored in a bucket and no difference in
performance whether you use many buckets or just a few You can store all of your objects in a single
bucket or you can organize them across several buckets
API Version 20060301
62Amazon Simple Storage Service Developer Guide
Rules for Naming
You cannot create a bucket within another bucket
The highavailability engineering of Amazon S3 is focused on get put list and delete operations
Because bucket operations work against a centralized global resource space it is not appropriate to
create or delete buckets on the highavailability code path of your application It is better to create or
delete buckets in a separate initialization or setup routine that you run less often
Note
If your application automatically creates buckets choose a bucket naming scheme that is
unlikely to cause naming conflicts Ensure that your application logic will choose a different
bucket name if a bucket name is already taken
Rules for Bucket Naming
We recommend that all bucket names comply with DNS naming conventions These conventions are
enforced in all regions except for the US East (N Virginia) region
Note
If you use the AWS management console bucket names must be DNS compliant in all
regions
DNScompliant bucket names allow customers to benefit from new features and operational
improvements as well as providing support for virtualhost style access to buckets While the US East
(N Virginia) region currently allows noncompliant DNS bucket naming we are moving to the same
DNScompliant bucket naming convention for the US East (N Virginia) region in the coming months
This will ensure a single consistent naming approach for Amazon S3 buckets The rules for DNS
compliant bucket names are
• Bucket names must be at least 3 and no more than 63 characters long
• Bucket names must be a series of one or more labels Adjacent labels are separated by a single
period () Bucket names can contain lowercase letters numbers and hyphens Each label must
start and end with a lowercase letter or a number
• Bucket names must not be formatted as an IP address (eg 19216854)
• When using virtual hosted–style buckets with SSL the SSL wildcard certificate only matches buckets
that do not contain periods To work around this use HTTP or write your own certificate verification
logic We recommend that you do not use periods () in bucket names
The following examples are valid bucket names
• myawsbucket
• myawsbucket
• myawsbucket1
The following examples are invalid bucket names
Invalid Bucket Name Comment
myawsbucket Bucket name cannot start with a period ()
myawsbucket Bucket name cannot end with a period ()
myexamplebucket There can be only one period between labels
Challenges with Non–DNSCompliant Bucket Names
The US East (N Virginia) region currently allows more relaxed standards for bucket naming which
can result in a bucket name that is not DNScompliant For example MyAWSBucket is a valid bucket
API Version 20060301
63Amazon Simple Storage Service Developer Guide
Examples of Creating a Bucket
name even though it contains uppercase letters If you try to access this bucket by using a virtual
hosted–style request (httpMyAWSBuckets3amazonawscomyourobject) the URL resolves
to the bucket myawsbucket and not the bucket MyAWSBucket In response Amazon S3 will return a
bucket not found error
To avoid this problem we recommend as a best practice that you always use DNScompliant bucket
names regardless of the region in which you create the bucket For more information about virtual
hosted–style access to your buckets see Virtual Hosting of Buckets (p 50)
The name of the bucket used for Amazon S3 Transfer Acceleration must be DNScompliant and
must not contain periods () For more information about transfer acceleration see see Amazon S3
Transfer Acceleration (p 81)
The rules for bucket names in the US East (N Virginia) region allow bucket names to be as long
as 255 characters and bucket names can contain any combination of uppercase letters lowercase
letters numbers periods () hyphens () and underscores (_)
Examples of Creating a Bucket
Topics
• Using the Amazon S3 Console (p 65)
• Using the AWS SDK for Java (p 65)
• Using the AWS SDK for NET (p 66)
• Using the AWS SDK for Ruby Version 2 (p 67)
• Using Other AWS SDKs (p 67)
This section provides code examples of creating a bucket programmatically using the AWS SDKs for
Java NET and Ruby The code examples perform the following tasks
• Create a bucket if it does not exist — The examples create a bucket as follows
• Create a client by explicitly specifying an AWS Region (example uses the s3eu
west1 region) Accordingly the client communicates with Amazon S3 using the s3eu
west1amazonawscom endpoint You can specify any other AWS Region For a list of available
AWS Regions see Regions and Endpoints in the AWS General Reference
• Send a create bucket request by specifying only a bucket name The create bucket request does
not specify another AWS Region therefore the client sends a request to Amazon S3 to create the
bucket in the region you specified when creating the client
Note
If you specify a region in your create bucket request that conflicts with the region you
specify when you create the client you might get an error For more information see
Creating a Bucket (p 59)
The SDK libraries send the PUT bucket request to Amazon S3 (see PUT Bucket) to create the
bucket
• Retrieve bucket location information — Amazon S3 stores bucket location information in the location
subresource associated with the bucket The SDK libraries send the GET Bucket location request
(see GET Bucket location) to retrieve this information
API Version 20060301
64Amazon Simple Storage Service Developer Guide
Using the Amazon S3 Console
Using the Amazon S3 Console
For creating a bucket using Amazon S3 console go to Creating a Bucket in the Amazon Simple
Storage Service Console User Guide
Using the AWS SDK for Java
For instructions on how to create and test a working sample see Testing the Java Code
Examples (p 564)
import javaioIOException
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsregionsRegion
import comamazonawsregionsRegions
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelCreateBucketRequest
import comamazonawsservicess3modelGetBucketLocationRequest
public class CreateBucket {
private static String bucketName *** bucket name ***

public static void main(String[] args) throws IOException {
AmazonS3 s3client new AmazonS3Client(new
ProfileCredentialsProvider())
s3clientsetRegion(RegiongetRegion(RegionsUS_WEST_1))

try {
if((s3clientdoesBucketExist(bucketName)))
{
Note that CreateBucketRequest does not specify region So
bucket is
created in the region specified in the client
s3clientcreateBucket(new CreateBucketRequest(
bucketName))
}
Get location
String bucketLocation s3clientgetBucketLocation(new
GetBucketLocationRequest(bucketName))
Systemoutprintln(bucket location + bucketLocation)
} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException which +
means your request made it +
to Amazon S3 but was rejected with an error response +
for some reason)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException which +
means the client encountered +
API Version 20060301
65Amazon Simple Storage Service Developer Guide
Using the AWS SDK for NET
an internal error while trying to +
communicate with S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
}
Using the AWS SDK for NET
For information about how to create and test a working sample see Running the Amazon S3 NET
Code Examples (p 566)
using System
using AmazonS3
using AmazonS3Model
using AmazonS3Util
namespace s3amazoncomdocsamples
{
class CreateBucket
{
static string bucketName *** bucket name ***
public static void Main(string[] args)
{
using (var client new
AmazonS3Client(AmazonRegionEndpointEUWest1))
{
if ((AmazonS3UtilDoesS3BucketExist(client bucketName)))
{
CreateABucket(client)
}
Retrieve bucket location
string bucketLocation FindBucketLocation(client)
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static string FindBucketLocation(IAmazonS3 client)
{
string bucketLocation
GetBucketLocationRequest request new GetBucketLocationRequest()
{
BucketName bucketName
}
GetBucketLocationResponse response
clientGetBucketLocation(request)
bucketLocation responseLocationToString()
return bucketLocation
}
static void CreateABucket(IAmazonS3 client)
{
API Version 20060301
66Amazon Simple Storage Service Developer Guide
Using the AWS SDK for Ruby Version 2
try
{
PutBucketRequest putRequest1 new PutBucketRequest
{
BucketName bucketName
UseClientRegion true
}
PutBucketResponse response1 clientPutBucket(putRequest1)
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&
(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS Credentials)
ConsoleWriteLine(
For service sign up go to httpawsamazoncom
s3)
}
else
{
ConsoleWriteLine(
Error occurred Message＇{0}＇ when writing an
object
amazonS3ExceptionMessage)
}
}
}
}
}
Using the AWS SDK for Ruby Version 2
For information about how to create and test a working sample see Using the AWS SDK for Ruby
Version 2 (p 568)
require ＇awssdk＇

s3 AwsS3Clientnew(region ＇uswest1＇)
s3create_bucket(bucket ＇bucketname＇)

Using Other AWS SDKs
For information about using other AWS SDKs go to Sample Code and Libraries
Deleting or Emptying a Bucket
Topics
• Delete a Bucket (p 68)
• Empty a Bucket (p 71)
API Version 20060301
67Amazon Simple Storage Service Developer Guide
Delete a Bucket
It is easy to delete an empty bucket however in some situations you may need to delete or empty
a bucket that contains objects In this section we＇ll explain how to delete objects in an unversioned
bucket (the default) and how to delete object versions and delete markers in a bucket that has
versioning enabled For more information about versioning see Using Versioning (p 423) In some
situations you may choose to empty a bucket instead of deleting it This section explains various
options you can use to delete or empty a bucket that contains objects
Delete a Bucket
You can delete a bucket and its content programmatically using AWS SDK You can also use lifecycle
configuration on a bucket to empty its content and then delete the bucket There are additional options
such as using Amazon S3 console and AWS CLI but there are limitations on this method based on the
number of objects in your bucket and the bucket＇s versioning status
Topics
• Delete a Bucket Using the Amazon S3 Console (p 68)
• Delete a Bucket Using the AWS CLI (p 68)
• Delete a Bucket Using Lifecycle Configuration (p 68)
• Delete a Bucket Using the AWS SDKs (p 69)
Delete a Bucket Using the Amazon S3 Console
The Amazon S3 console supports deleting a bucket that may or may not be empty If the bucket is not
empty the Amazon S3 console supports deleting a bucket containing up to 100000 objects If your
bucket contains more than 100000 objects you can use other options such as the AWS CLI bucket
lifecycle configuration or programmatically using AWS SDKs
In the Amazon S3 console open the context (rightclick) menu on the bucket and choose Delete
Bucket or Empty Bucket
Delete a Bucket Using the AWS CLI
You can delete a bucket that contains objects using the AWS CLI only if the bucket does not have
versioning enabled If your bucket does not have versioning enabled you can use the rb (remove
bucket) AWS CLI command with force parameter to remove a nonempty bucket This command
deletes all objects first and then deletes the bucket
aws s3 rb s3bucketname force
For more information see Using HighLevel S3 Commands with the AWS Command Line Interface in
the AWS Command Line Interface User Guide
To delete a nonempty bucket that does not have versioning enabled you have the following options
• Delete the bucket programmatically using the AWS SDK
• First delete all of the objects using the bucket＇s lifecycle configuration and then delete the empty
bucket using the Amazon S3 console
Delete a Bucket Using Lifecycle Configuration
You can configure lifecycle on your bucket to expire objects Amazon S3 then deletes expired objects
You can add lifecycle configuration rules to expire all or a subset of objects with a specific key name
API Version 20060301
68Amazon Simple Storage Service Developer Guide
Delete a Bucket
prefix For example to remove all objects in a bucket you can set a lifecycle rule to expire objects one
day after creation
If your bucket has versioning enabled you can also configure the rule to expire noncurrent objects
After Amazon S3 deletes all of the objects in your bucket you can delete the bucket or keep it
Important
If you just want to empty the bucket and not delete it make sure you remove the lifecycle
configuration rule you added to empty the bucket so that any new objects you create in the
bucket will remain in the bucket
For more information see Object Lifecycle Management (p 109) and Expiring Objects General
Considerations (p 112)
Delete a Bucket Using the AWS SDKs
You can use the AWS SDKs to delete a bucket The following sections provide examples of how to
delete a bucket using the AWS SDK for NET and Java First the code deletes objects in the bucket
and then it deletes the bucket For information about other AWS SDKs see Tools for Amazon Web
Services
Delete a Bucket Using the AWS SDK for Java
The following Java example deletes a nonempty bucket First the code deletes all objects and then it
deletes the bucket The code example also works for buckets with versioning enabled
For instructions on how to create and test a working sample see Testing the Java Code
Examples (p 564)
import javaioIOException
import javautilIterator
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsregionsRegion
import comamazonawsregionsRegions
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelListVersionsRequest
import comamazonawsservicess3modelObjectListing
import comamazonawsservicess3modelS3ObjectSummary
import comamazonawsservicess3modelS3VersionSummary
import comamazonawsservicess3modelVersionListing
public class DeleteBucketAndContent {
private static String bucketName ***bucket name to delete ***

public static void main(String[] args) throws IOException {
AmazonS3 s3client new AmazonS3Client(new
ProfileCredentialsProvider())
s3clientsetRegion(RegiongetRegion(RegionsAWSRegionWhereBucket
Resides))

try {
Systemoutprintln(Deleting S3 bucket + bucketName)
API Version 20060301
69Amazon Simple Storage Service Developer Guide
Delete a Bucket
ObjectListing objectListing
s3clientlistObjects(bucketName)

while (true) {
for ( Iterator<> iterator
objectListinggetObjectSummaries()iterator() iteratorhasNext() ) {
S3ObjectSummary objectSummary (S3ObjectSummary)
iteratornext()
s3clientdeleteObject(bucketName
objectSummarygetKey())
}

if (objectListingisTruncated()) {
objectListing
s3clientlistNextBatchOfObjects(objectListing)
} else {
break
}
}
VersionListing list s3clientlistVersions(new
ListVersionsRequest()withBucketName(bucketName))
for ( Iterator<> iterator
listgetVersionSummaries()iterator() iteratorhasNext() ) {
S3VersionSummary s (S3VersionSummary)iteratornext()
s3clientdeleteVersion(bucketName sgetKey()
sgetVersionId())
}
s3clientdeleteBucket(bucketName)
} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException which +
means your request made it +
to Amazon S3 but was rejected with an error response +
for some reason)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException which +
means the client encountered +
an internal error while trying to +
communicate with S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
}
Delete a Bucket Using the AWS SDK for NET
The following NET example deletes a nonempty bucket First the code deletes all objects and then it
deletes the bucket The code example also works for buckets with versioning enabled
For instructions on how to create and test a working sample see Running the Amazon S3 NET Code
Examples (p 566)
API Version 20060301
70Amazon Simple Storage Service Developer Guide
Empty a Bucket
using System
using AmazonS3
using AmazonS3Model
using AmazonS3Util
namespace s3amazoncomdocsamples
{
class CreateBucket
{
static string bucketName *** bucket name to delete ***
public static void Main(string[] args)
{
try
{
using (var client new
AmazonS3Client(AmazonRegionEndpointAWSregionwherebucketresides))
{
AmazonS3UtilDeleteS3BucketWithObjects(client
bucketName)
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&
(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS Credentials)
ConsoleWriteLine(
For service sign up go to httpawsamazoncom
s3)
}
else
{
ConsoleWriteLine(
Error occurred Message＇{0}＇ when writing an
object
amazonS3ExceptionMessage)
}
}
}
}
}
Empty a Bucket
You can empty a bucket＇s content (that is delete all content but keep the bucket) programmatically
using the AWS SDK You can also specify lifecycle configuration on a bucket to expire objects so that
Amazon S3 can delete them There are additional options such as using Amazon S3 console and
AWS CLI but there are limitations on this method based on the number of objects in your bucket and
the bucket＇s versioning status
Topics
API Version 20060301
71Amazon Simple Storage Service Developer Guide
Empty a Bucket
• Empty a Bucket Using the Amazon S3 console (p 72)
• Empty a Bucket Using the AWS CLI (p 72)
• Empty a Bucket Using Lifecycle Configuration (p 72)
• Empty a Bucket Using the AWS SDKs (p 73)
Empty a Bucket Using the Amazon S3 console
The Amazon S3 console supports emptying your bucket provided that the bucket contains less than
100000 objects The Amazon S3 console returns an error if you attempt to empty a bucket that
contains more than 100000 objects For example if your bucket has versioning enabled you can
have one object with 101000 object versions and you will not be able to empty this bucket using the
Amazon S3 console
In the Amazon S3 console open the context (rightclick) menu on the bucket and choose Empty
Bucket
Empty a Bucket Using the AWS CLI
You can empty a bucket using the AWS CLI only if the bucket does not have versioning enabled If
your bucket does not have versioning enabled you can use the rm (remove) AWS CLI command with
the recursive parameter to empty a bucket (or remove a subset of objects with a specific key
name prefix)
The following rm command removes objects with key name prefix doc for example docdoc1 and
docdoc2
aws s3 rm s3bucketnamedoc recursive
Use the following command to remove all objects without specifying a prefix
aws s3 rm s3bucketname recursive
For more information see Using HighLevel S3 Commands with the AWS Command Line Interface in
the AWS Command Line Interface User Guide
Note
You cannot remove objects from a bucket with versioning enabled Amazon S3 adds a delete
marker when you delete an object which is what this command will do For more information
about versioning see Using Versioning (p 423)
To empty a bucket with versioning enabled you have the following options
• Delete the bucket programmatically using the AWS SDK
• Use the bucket＇s lifecycle configuration to request that Amazon S3 delete the objects
• Use the Amazon S3 console (can only use this option if your bucket contains less than 100000
items—including both object versions and delete markers)
Empty a Bucket Using Lifecycle Configuration
You can configure lifecycle on you bucket to expire objects and request that Amazon S3 delete expired
objects You can add lifecycle configuration rules to expire all or a subset of objects with a specific key
API Version 20060301
72Amazon Simple Storage Service Developer Guide
Bucket Website Configuration
name prefix For example to remove all objects in a bucket you can set lifecycle rule to expire objects
one day after creation
If your bucket has versioning enabled you can also configure the rule to expire noncurrent objects
Caution
After your objects expire Amazon S3 deletes the expired objects If you just want to empty the
bucket and not delete it make sure you remove the lifecycle configuration rule you added to
empty the bucket so that any new objects you create in the bucket will remain in the bucket
For more information see Object Lifecycle Management (p 109) and Expiring Objects General
Considerations (p 112)
Empty a Bucket Using the AWS SDKs
You can use the AWS SDKs to empty a bucket or remove a subset of objects with a specific key name
prefix
For an example of how to empty a bucket using AWS SDK for Java see Delete a Bucket Using the
AWS SDK for Java (p 69) The code deletes all objects regardless of whether the bucket has
versioning enabled or not and then it deletes the bucket To just empty the bucket make sure you
remove the statement that deletes the bucket
For more information about using other AWS SDKs see Tools for Amazon Web Services
Managing Bucket Website Configuration
Topics
• Managing Websites with the AWS Management Console (p 73)
• Managing Websites with the AWS SDK for Java (p 73)
• Managing Websites with the AWS SDK for NET (p 76)
• Managing Websites with the AWS SDK for PHP (p 79)
• Managing Websites with the REST API (p 81)
You can host static websites in Amazon S3 by configuring your bucket for website hosting For more
information see Hosting a Static Website on Amazon S3 (p 449) There are several ways you
can manage your bucket＇s website configuration You can use the AWS Management Console to
manage configuration without writing any code You can programmatically create update and delete
the website configuration by using the AWS SDKs The SDKs provide wrapper classes around the
Amazon S3 REST API If your application requires it you can send REST API requests directly from
your application
Managing Websites with the AWS Management
Console
For more information see Configure a Bucket for Website Hosting (p 452)
Managing Websites with the AWS SDK for Java
The following tasks guide you through using the Java classes to manage website configuration to your
bucket For more information about the Amazon S3 website feature see Hosting a Static Website on
Amazon S3 (p 449)
API Version 20060301
73Amazon Simple Storage Service Developer Guide
Using the SDK for Java
Managing Website Configuration
1 Create an instance of the AmazonS3 class
2 To add website configuration to a bucket execute the
AmazonS3setBucketWebsiteConfiguration method You need to provide the
bucket name and the website configuration information including the index document
and the error document names You must provide the index document but the error
document is optional You provide website configuration information by creating a
BucketWebsiteConfiguration object
To retrieve website configuration execute the
AmazonS3getBucketWebsiteConfiguration method by providing the bucket
name
To delete your bucket website configuration execute the
AmazonS3deleteBucketWebsiteConfiguration method by providing the bucket
name After you remove the website configuration the bucket is no longer available from
the website endpoint For more information see Website Endpoints (p 450)
The following Java code sample demonstrates the preceding tasks
AmazonS3 s3client new AmazonS3Client(new ProfileCredentialsProvider())
Add website configuration
s3ClientsetBucketWebsiteConfiguration(bucketName
new BucketWebsiteConfiguration(indexDoc errorDoc))

Get website configuration
BucketWebsiteConfiguration bucketWebsiteConfiguration
s3ClientgetBucketWebsiteConfiguration(bucketName)

Delete website configuration
s3ClientdeleteBucketWebsiteConfiguration(bucketName)
API Version 20060301
74Amazon Simple Storage Service Developer Guide
Using the SDK for Java
Example
The following Java code example adds a website configuration to the specified bucket retrieves it and
deletes the website configuration For instructions on how to create and test a working sample see
Testing the Java Code Examples (p 564)
import javaioIOException
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelBucketWebsiteConfiguration
public class WebsiteConfiguration {
private static String bucketName *** bucket name ***
private static String indexDoc *** index document name ***
private static String errorDoc *** error document name ***

public static void main(String[] args) throws IOException {
AmazonS3 s3Client new AmazonS3Client(new
ProfileCredentialsProvider())

try {
Get existing website configuration if any
getWebsiteConfig(s3Client)

Set new website configuration
s3ClientsetBucketWebsiteConfiguration(bucketName
new BucketWebsiteConfiguration(indexDoc errorDoc))

Verify (Get website configuration again)
getWebsiteConfig(s3Client)

Delete
s3ClientdeleteBucketWebsiteConfiguration(bucketName)
Verify (Get website configuration again)
getWebsiteConfig(s3Client)



} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException which +
means your request made it +
to Amazon S3 but was rejected with an error response +
for some reason)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException which
means+
the client encountered +
a serious internal problem while trying to +
communicate with Amazon S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
private static BucketWebsiteConfiguration getWebsiteConfig(
AmazonS3 s3Client) {
Systemoutprintln(Get website config)

1 Get website config
BucketWebsiteConfiguration bucketWebsiteConfiguration
s3ClientgetBucketWebsiteConfiguration(bucketName)
if (bucketWebsiteConfiguration null)
{
Systemoutprintln(No website config)
}
else
{
Systemoutprintln(Index doc +
bucketWebsiteConfigurationgetIndexDocumentSuffix())
Systemoutprintln(Error doc +
bucketWebsiteConfigurationgetErrorDocument())
}
return bucketWebsiteConfiguration
}
}
API Version 20060301
75Amazon Simple Storage Service Developer Guide
Using the AWS SDK for NET
Managing Websites with the AWS SDK for NET
The following tasks guide you through using the NET classes to manage website configuration on your
bucket For more information about the Amazon S3 website feature see Hosting a Static Website on
Amazon S3 (p 449)
Managing Bucket Website Configuration
1 Create an instance of the AmazonS3Client class
2 To add website configuration to a bucket execute the PutBucketWebsite method
You need to provide the bucket name and the website configuration information
including the index document and the error document names You must provide the index
document but the error document is optional You provide this information by creating a
PutBucketWebsiteRequest object
To retrieve website configuration execute the GetBucketWebsite method by providing
the bucket name
To delete your bucket website configuration execute the DeleteBucketWebsite
method by providing the bucket name After you remove the website configuration
the bucket is no longer available from the website endpoint For more information see
Website Endpoints (p 450)
The following C# code sample demonstrates the preceding tasks
static IAmazonS3 client
client new AmazonS3Client(AmazonRegionEndpointUSWest2)
Add website configuration
PutBucketWebsiteRequest putRequest new PutBucketWebsiteRequest()
{
BucketName bucketName
WebsiteConfiguration new WebsiteConfiguration()
{
IndexDocumentSuffix indexDocumentSuffix
ErrorDocument errorDocument
}
}
clientPutBucketWebsite(putRequest)
Get bucket website configuration
GetBucketWebsiteRequest getRequest new GetBucketWebsiteRequest()
{
BucketName bucketName
}
GetBucketWebsiteResponse getResponse clientGetBucketWebsite(getRequest)
Print configuration data
ConsoleWriteLine(Index document {0}
getResponseWebsiteConfigurationIndexDocumentSuffix)
ConsoleWriteLine(Error document {0}
getResponseWebsiteConfigurationErrorDocument)
Delete website configuration
DeleteBucketWebsiteRequest deleteRequest new DeleteBucketWebsiteRequest()
{
API Version 20060301
76Amazon Simple Storage Service Developer Guide
Using the AWS SDK for NET
BucketName bucketName
}
clientDeleteBucketWebsite(deleteRequest)
API Version 20060301
77Amazon Simple Storage Service Developer Guide
Using the AWS SDK for NET
Example
The following C# code example adds a website configuration to the specified bucket The configuration
specifies both the index document and the error document names For instructions on how to create
and test a working sample see Running the Amazon S3 NET Code Examples (p 566)
using System
using SystemConfiguration
using SystemCollectionsSpecialized
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class AddWebsiteConfig
{
static string bucketName *** Provide existing bucket name
***
static string indexDocumentSuffix *** Provide index document name
***
static string errorDocument *** Provide error document name
***
static IAmazonS3 client
public static void Main(string[] args)
{
using (client new
AmazonS3Client(AmazonRegionEndpointUSWest2))
{
ConsoleWriteLine(Adding website configuration)
AddWebsiteConfiguration(bucketName indexDocumentSuffix
errorDocument)
}

Get bucket website configuration
GetBucketWebsiteRequest getRequest new
GetBucketWebsiteRequest()
{
BucketName bucketName
}
GetBucketWebsiteResponse getResponse
clientGetBucketWebsite(getRequest)
Print configuration data
ConsoleWriteLine(Index document {0}
getResponseWebsiteConfigurationIndexDocumentSuffix)
ConsoleWriteLine(Error document {0}
getResponseWebsiteConfigurationErrorDocument)

ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static void AddWebsiteConfiguration(string bucketName
string indexDocumentSuffix
string errorDocument)
{
try
{
PutBucketWebsiteRequest putRequest new
PutBucketWebsiteRequest()
{
BucketName bucketName
WebsiteConfiguration new WebsiteConfiguration()
{
IndexDocumentSuffix indexDocumentSuffix
ErrorDocument errorDocument
}
}
clientPutBucketWebsite(putRequest)
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&
(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS Credentials)
ConsoleWriteLine(Sign up for service at http
awsamazoncoms3)
}
else
{
ConsoleWriteLine(
Error{0} occurred when adding website
configuration Message＇{1}
amazonS3ExceptionErrorCode
amazonS3ExceptionMessage)
}
}
}
}
}
API Version 20060301
78Amazon Simple Storage Service Developer Guide
Using the SDK for PHP
Managing Websites with the AWS SDK for PHP
This topic guides you through using classes from the AWS SDK for PHP to configure and manage an
Amazon S3 bucket for website hosting For more information about the Amazon S3 website feature
see Hosting a Static Website on Amazon S3 (p 449)
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
The following tasks guide you through using the PHP SDK classes to configure and manage an
Amazon S3 bucket for website hosting
Configuring a Bucket for Website Hosting
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 To configure a bucket as a website execute the Aws＼S3＼S3ClientputBucketWebsite()
method You need to provide the bucket name and the website configuration information
including the index document and the error document names If you don＇t provide these
document names this method adds the indexhtml and errorhtml default names
to the website configuration You must verify that these documents are present in the
bucket
3 To retrieve existing bucket website configuration execute the Aws
＼S3＼S3ClientgetBucketWebsite() method
4 To delete website configuration from a bucket execute the Aws
＼S3＼S3ClientdeleteBucketWebsite() method passing the bucket name as a parameter
If you remove the website configuration the bucket is no longer accessible from the
website endpoints
The following PHP code sample demonstrates the preceding tasks
use Aws＼S3＼S3Client
bucket ＇*** Your Bucket Name ***＇

1 Instantiate the client
s3 S3Clientfactory()
2 Add website configuration
result s3>putBucketWebsite(array(
＇Bucket＇ > bucket
＇IndexDocument＇ > array(＇Suffix＇ > ＇indexhtml＇)
＇ErrorDocument＇ > array(＇Key＇ > ＇errorhtml＇)
))
3 Retrieve website configuration
result s3>getBucketWebsite(array(
＇Bucket＇ > bucket
))
echo result>getPath(＇IndexDocumentSuffix＇)
API Version 20060301
79Amazon Simple Storage Service Developer Guide
Using the SDK for PHP
4) Delete website configuration
result s3>deleteBucketWebsite(array(
＇Bucket＇ > bucket
))
Example of Configuring an Bucket Amazon S3 for Website Hosting
The following PHP code example first adds a website configuration to the specified bucket The
create_website_config method explicitly provides the index document and error document names
The sample also retrieves the website configuration and prints the response For more information
about the Amazon S3 website feature see Hosting a Static Website on Amazon S3 (p 449)
For instructions on how to create and test a working sample see Using the AWS SDK for PHP and
Running PHP Examples (p 566)
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
use Aws＼S3＼S3Client
bucket ＇*** Your Bucket Name ***＇
Instantiate the client
s3 S3Clientfactory()
1) Add website configuration
result s3>putBucketWebsite(array(
＇Bucket＇ > bucket
＇IndexDocument＇ > array(＇Suffix＇ > ＇indexhtml＇)
＇ErrorDocument＇ > array(＇Key＇ > ＇errorhtml＇)
))
2) Retrieve website configuration
result s3>getBucketWebsite(array(
＇Bucket＇ > bucket
))
echo result>getPath(＇IndexDocumentSuffix＇)
3) Delete website configuration
result s3>deleteBucketWebsite(array(
＇Bucket＇ > bucket
))
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientdeleteBucketWebsite() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientgetBucketWebsite() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientputBucketWebsite() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
API Version 20060301
80Amazon Simple Storage Service Developer Guide
Using the REST API
Managing Websites with the REST API
You can use the AWS Management Console or the AWS SDK to configure a bucket as a website
However if your application requires it you can send REST requests directly For more information
see the following sections in the Amazon Simple Storage Service API Reference
• PUT Bucket website
• GET Bucket website
• DELETE Bucket website
Amazon S3 Transfer Acceleration
Amazon S3 Transfer Acceleration enables fast easy and secure transfers of files over long distances
between your client and an S3 bucket Transfer Acceleration takes advantage of Amazon CloudFront’s
globally distributed edge locations As the data arrives at an edge location data is routed to Amazon
S3 over an optimized network path
When using Transfer Acceleration additional data transfer charges may apply For more information
about pricing see Amazon S3 Pricing
Topics
• Why Use Amazon S3 Transfer Acceleration (p 81)
• Getting Started with Amazon S3 Transfer Acceleration (p 82)
• Requirements for Using Amazon S3 Transfer Acceleration (p 83)
• Amazon S3 Transfer Acceleration Examples (p 83)
Why Use Amazon S3 Transfer Acceleration
You might want to use Transfer Acceleration on a bucket for various reasons including the following
• You have customers that upload to a centralized bucket from all over the world
• You transfer gigabytes to terabytes of data on a regular basis across continents
• You underutilize the available bandwidth over the Internet when uploading to Amazon S3
For more information about when to use Transfer Acceleration see Amazon S3 FAQs
Using the Amazon S3 Transfer Acceleration Speed
Comparison Tool
You can use the Amazon S3 Transfer Acceleration Speed Comparison tool to compare accelerated
and nonaccelerated upload speeds across Amazon S3 regions The Speed Comparison tool uses
multipart uploads to transfer a file from your browser to various Amazon S3 regions with and without
using Transfer Acceleration
You can access the Speed Comparison tool using either of the following methods
• Copy the following URL into your browser window replacing region with the region that you are
using (for example uswest2) and yourBucketName with the name of the bucket that you want to
evaluate
https3acceleratespeedtests3accelerateamazonawscomenaccelerate
speedcomparsionhtmlregionregion&origBucketNameyourBucketName
API Version 20060301
81Amazon Simple Storage Service Developer Guide
Getting Started

For a list of the regions supported by Amazon S3 see Regions and Endpoints in the Amazon Web
Services General Reference
• Use the Amazon S3 console For details see Enabling Transfer Acceleration in the Amazon Simple
Storage Service Console User Guide
Getting Started with Amazon S3 Transfer
Acceleration
To get started using Amazon S3 Transfer Acceleration perform the following steps
1 Enable Transfer Acceleration on a bucket – For your bucket to work with transfer acceleration
the bucket name must conform to DNS naming requirements and must not contain periods ()

You can enable Transfer Acceleration on a bucket any of the following ways
• Use the Amazon S3 console For more information see Enabling Transfer Acceleration in the
Amazon Simple Storage Service Console User Guide
• Use the REST API PUT Bucket accelerate operation
• Use the AWS CLI and AWS SDKs For more information see Using the AWS SDKs CLI and
Explorers (p 560)

2 Transfer data to the accelerationenabled bucket using the bucketnames3
accelerateamazonawscom endpoint – When uploading to or downloading from the Transfer
Acceleration enabled bucket you must use the bucket endpoint domain name bucketnames3
accelerateamazonawscom to get accelerated data transfers You can find the unique Transfer
Acceleration endpoint name for your bucket in the Amazon S3 management console
Note
You can continue to use the regular endpoint in addition to the accelerate endpoint
For example let＇s say you currently have a REST API application using PUT Object that uses the
host name mybuckets3amazonawscom in the PUT request To accelerate the PUT you simply
change the host name in your request to mybuckets3accelerateamazonawscom To go back to
using the standard upload speed simply change the name back to mybuckets3amazonawscom

You can use the new accelerate endpoint in the AWS CLI AWS SDKs and other tools that transfer
data to and from Amazon S3 If you are using the AWS SDKs some of the supported languages
use an accelerate endpoint client configuration flag so you don＇t need to explicitly set the endpoint
for Transfer Acceleration to bucketnames3accelerateamazonawscom For examples of how
to use an accelerate endpoint client configuration flag see Amazon S3 Transfer Acceleration
Examples (p 83)
You can use all of the Amazon S3 operations through the transaction acceleration endpoint except
for the following the operations GET Service (list buckets) PUT Bucket (create bucket) and DELETE
Bucket Also Amazon S3 Transfer Acceleration does not support cross region copies using PUT
Object Copy
API Version 20060301
82Amazon Simple Storage Service Developer Guide
Requirements for Using Amazon S3 Transfer Acceleration
Requirements for Using Amazon S3 Transfer
Acceleration
The following are the requirements for using Transfer Acceleration on an S3 bucket
• Transfer Acceleration is only supported on virtual style requests For more information about virtual
style requests see Making Requests Using the REST API (p 49)
• The name of the bucket used for Transfer Acceleration must be DNScompliant and must not contain
periods ()
• Transfer Acceleration must be enabled on the bucket After enabling Transfer Acceleration on a
bucket it might take up to thirty minutes before the data transfer speed to the bucket increases
• You must use the use the endpoint bucketnames3accelerateamazonawscom to access the
enabled bucket
• You must be the bucket owner to set the transfer acceleration state The bucket owner can
assign permissions to other users to allow them to set the acceleration state on a bucket The
s3PutAccelerateConfiguration permission permits users to enable or disable Transfer
Acceleration on a bucket The s3GetAccelerateConfiguration permission permits users
to return the Transfer Acceleration state of a bucket which is either Enabled or Suspended
For more information about these permissions see Permissions Related to Bucket Subresource
Operations (p 314) and Managing Access Permissions to Your Amazon S3 Resources (p 266)
• Transfer Acceleration is not Health Insurance Portability and Accountability Act (HIPAA) compliant
Important
Transfer Acceleration uses AWS Edge infrastructure (edge locations) which are not Health
Insurance Portability and Accountability Act (HIPAA) compliant If your organization has
personal health information (PHI) workloads covered under the HIPAA Business Associate
Agreement (BAA) you can＇t use Transfer Acceleration For more information contact AWS
Support at Contact Us
Related Topics
• GET Bucket accelerate
• PUT Bucket accelerate
Amazon S3 Transfer Acceleration Examples
This section provides examples of how to enable Amazon S3 Transfer Acceleration on a bucket and
use the acceleration endpoint for the enabled bucket Some of the AWS SDK supported languages
(for example Java and NET) use an accelerate endpoint client configuration flag so you don＇t need to
explicitly set the endpoint for Transfer Acceleration to bucketnames3accelerateamazonawscom
For more information about Transfer Acceleration see Amazon S3 Transfer Acceleration (p 81)
Topics
• Using the Amazon S3 Console (p 84)
• Using Transfer Acceleration from the AWS Command Line Interface (AWS CLI) (p 84)
• Using Transfer Acceleration from the AWS SDK for Java (p 85)
• Using Transfer Acceleration from the AWS SDK for NET (p 88)
• Using Other AWS SDKs (p 92)
API Version 20060301
83Amazon Simple Storage Service Developer Guide
Transfer Acceleration Examples
Using the Amazon S3 Console
For information about enabling Transfer Acceleration on a bucket using the Amazon S3 console see
Enabling Transfer Acceleration in the Amazon Simple Storage Service Console User Guide
Using Transfer Acceleration from the AWS Command Line
Interface (AWS CLI)
This section provides examples of AWS CLI commands used for Transfer Acceleration For
instructions on setting up the AWS CLI see Set Up the AWS CLI (p 562)
Enabling Transfer Acceleration on a Bucket Using the AWS CLI
Use the AWS CLI putbucketaccelerateconfiguration command to enable or suspend Transfer
Acceleration on a bucket The following example sets StatusEnabled to enable Transfer
Acceleration on a bucket You use StatusSuspended to suspend Transfer Acceleration
aws s3api putbucketaccelerateconfiguration bucket bucketname
accelerateconfiguration StatusEnabled
Using the Transfer Acceleration from the AWS CLI
Setting the configuration value use_accelerate_endpoint to true in a profile in your AWS Config
File will direct all Amazon S3 requests made by s3 and s3api AWS CLI commands to the accelerate
endpoint s3accelerateamazonawscom Transfer Acceleration must be enabled on your bucket
to use the accelerate endpoint
All request are sent using the virtual style of bucket addressing mybuckets3
accelerateamazonawscom Any ListBuckets CreateBucket and DeleteBucket requests
will not be sent to the accelerate endpoint as the endpoint does not support those operations For more
information about use_accelerate_endpoint see AWS CLI S3 Configuration
The following example sets use_accelerate_endpoint to true in the default profile
aws configure set defaults3use_accelerate_endpoint true
If you want to use the accelerate endpoint for some AWS CLI commands but not others you can use
either one of the following two methods
• You can use the accelerate endpoint per command by setting the endpointurl parameter to
httpss3accelerateamazonawscom or https3accelerateamazonawscom for
any s3 or s3api command
• You can setup separate profiles in your AWS Config File For example create one
profile that sets use_accelerate_endpoint to true and a profile that does not set
use_accelerate_endpoint When you execute a command specify which profile you want to use
depending upon whether or not you want to use the accelerate endpoint
AWS CLI Examples of Uploading an Object to a Transfer Acceleration Enabled
Bucket
The following example uploads a file to a Transfer Acceleration enabled bucket by using the default
profile that has been configured to use the accelerate endpoint
aws s3 cp filetxt s3bucketnamekeyname region region
API Version 20060301
84Amazon Simple Storage Service Developer Guide
Transfer Acceleration Examples
The following example uploads a file to a Transfer Acceleration enabled bucket by using the
endpointurl parameter to specify the accelerate endpoint
aws configure set s3addressing_style virtual
aws s3 cp filetxt s3bucketnamekeyname region region endpointurl
https3accelerateamazonawscom
Using Transfer Acceleration from the AWS SDK for Java
This section provides examples of using the AWS SDK for Java for Transfer Acceleration For
information about how to create and test a working Java sample see Testing the Java Code
Examples (p 564)
Java Example 1 Enable Amazon S3 Transfer Acceleration on a Bucket
The following Java example shows how to enable Transfer Acceleration on a bucket
import javaioIOException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsregionsRegion
import comamazonawsregionsRegions
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelBucketAccelerateConfiguration
import comamazonawsservicess3modelBucketAccelerateStatus
import
comamazonawsservicess3modelGetBucketAccelerateConfigurationRequest
import
comamazonawsservicess3modelSetBucketAccelerateConfigurationRequest
public class BucketAccelertionConfiguration {
public static String bucketName *** Provide bucket name ***
public static AmazonS3Client s3Client

public static void main(String[] args) throws IOException {

s3Client new AmazonS3Client(new ProfileCredentialsProvider())
s3ClientsetRegion(RegiongetRegion(RegionsUS_WEST_2))

1 Enable bucket for Amazon S3 Transfer Acceleration
s3ClientsetBucketAccelerateConfiguration(new
SetBucketAccelerateConfigurationRequest(bucketName
new BucketAccelerateConfiguration(BucketAccelerateStatusEnabled)))

2 Get the acceleration status of the bucket
String accelerateStatus
s3ClientgetBucketAccelerateConfiguration(new
GetBucketAccelerateConfigurationRequest(bucketName))getStatus()

Systemoutprintln(Acceleration status + accelerateStatus)

}
}
API Version 20060301
85Amazon Simple Storage Service Developer Guide
Transfer Acceleration Examples
Java Example 2 Uploading a Single Object to a Transfer Acceleration Enabled
Bucket
The following Java example shows how to use the accelerate endpoint to upload a single object
import javaioFile
import javaioIOException
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsregionsRegion
import comamazonawsregionsRegions
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3S3ClientOptions
import comamazonawsservicess3modelPutObjectRequest
public class AcceleratedUploadSingleObject {
private static String bucketName *** Provide bucket name ***
private static String keyName *** Provide key name ***
private static String uploadFileName *** Provide file name with full
path ***

public static void main(String[] args) throws IOException {
AmazonS3 s3Client new AmazonS3Client(new
ProfileCredentialsProvider())
s3ClientsetRegion(RegiongetRegion(RegionsUS_WEST_2))

Use Amazon S3 Transfer Acceleration endpoint

s3ClientsetS3ClientOptions(S3ClientOptionsbuilder()setAccelerateModeEnabled(true)build())

try {
Systemoutprintln(Uploading a new object to S3 from a file
＼n)
File file new File(uploadFileName)
s3ClientputObject(new PutObjectRequest(
bucketName keyName file))
} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException which
+
means your request made it +
to Amazon S3 but was rejected with an error
response +
for some reason)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code +
asegetStatusCode())
Systemoutprintln(AWS Error Code +
asegetErrorCode())
Systemoutprintln(Error Type +
asegetErrorType())
Systemoutprintln(Request ID +
asegetRequestId())
API Version 20060301
86Amazon Simple Storage Service Developer Guide
Transfer Acceleration Examples
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException which
+
means the client encountered +
an internal error while trying to +
communicate with S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
}
Java Example 3 Multipart Upload to a Transfer Acceleration Enabled Bucket
The following Java example shows how to use the accelerate endpoint for a multipart upload
import javaioFile

import comamazonawsAmazonClientException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsregionsRegions
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3S3ClientOptions

import comamazonawsservicess3transferTransferManager
import comamazonawsservicess3transferUpload

public class AccelerateMultipartUploadUsingHighLevelAPI {

private static String EXISTING_BUCKET_NAME *** Provide bucket name
***
private static String KEY_NAME *** Provide key name ***
private static String FILE_PATH *** Provide file name with full path
***

public static void main(String[] args) throws Exception {

AmazonS3Client s3Client new AmazonS3Client(new
ProfileCredentialsProvider())
s3ClientconfigureRegion(RegionsUS_WEST_2)

Use Amazon S3 Transfer Acceleration endpoint

s3ClientsetS3ClientOptions(S3ClientOptionsbuilder()setAccelerateModeEnabled(true)build())

TransferManager tm new TransferManager(s3Client)
Systemoutprintln(TransferManager)
TransferManager processes all transfers asynchronously
so this call will return immediately
Upload upload tmupload(
EXISTING_BUCKET_NAME KEY_NAME new File(FILE_PATH))
Systemoutprintln(Upload)

try {
Or you can block and wait for the upload to finish
uploadwaitForCompletion()
Systemoutprintln(Upload complete)
} catch (AmazonClientException amazonClientException) {
API Version 20060301
87Amazon Simple Storage Service Developer Guide
Transfer Acceleration Examples
Systemoutprintln(Unable to upload file upload was aborted)
amazonClientExceptionprintStackTrace()
}
}
}
Using Transfer Acceleration from the AWS SDK for NET
This section provides examples of using the AWS SDK for NET for Transfer Acceleration For
information about how to create and test a working NET sample see Running the Amazon S3 NET
Code Examples (p 566)
NET Example 1 Enable Transfer Acceleration on a Bucket
The following NET example shows how to enable Transfer Acceleration on a bucket
using System
using SystemCollectionsGeneric
using AmazonS3
using AmazonS3Model
using AmazonS3Util

namespace s3amazoncomdocsamples
{

class SetTransferAccelerateState
{
private static string bucketName Provide bucket name

public static void Main(string[] args)
{
using (var s3Client new
AmazonS3Client(AmazonRegionEndpointUSWest2))

try
{
EnableTransferAcclerationOnBucket(s3Client)
BucketAccelerateStatus bucketAcclerationStatus
GetBucketAccelerateState(s3Client)

ConsoleWriteLine(Acceleration state ＇{0}＇
bucketAcclerationStatus)
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&

(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS
Credentials)
ConsoleWriteLine(
To sign up for the service go to httpawsamazoncom
s3)
}
else
API Version 20060301
88Amazon Simple Storage Service Developer Guide
Transfer Acceleration Examples
{
ConsoleWriteLine(
Error occurred Message＇{0}＇ when setting transfer
acceleration
amazonS3ExceptionMessage)
}
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}

static void EnableTransferAcclerationOnBucket(IAmazonS3 s3Client)
{
PutBucketAccelerateConfigurationRequest request new
PutBucketAccelerateConfigurationRequest
{
BucketName bucketName
AccelerateConfiguration new AccelerateConfiguration
{
Status BucketAccelerateStatusEnabled
}
}

PutBucketAccelerateConfigurationResponse response
s3ClientPutBucketAccelerateConfiguration(request)
}

static BucketAccelerateStatus GetBucketAccelerateState(IAmazonS3
s3Client)
{
GetBucketAccelerateConfigurationRequest request new
GetBucketAccelerateConfigurationRequest
{
BucketName bucketName
}

GetBucketAccelerateConfigurationResponse response
s3ClientGetBucketAccelerateConfiguration(request)
return responseStatus
}
}
}
NET Example 2 Uploading a Single Object to a Transfer Acceleration
Enabled Bucket
The following NET example shows how to use the accelerate endpoint to upload a single object
using System
using SystemCollectionsGeneric
using Amazon
using AmazonS3
using AmazonS3Model
using AmazonS3Util

namespace s3amazoncomdocsamples
{

API Version 20060301
89Amazon Simple Storage Service Developer Guide
Transfer Acceleration Examples
public class UploadtoAcceleratedBucket
{
private static RegionEndpoint TestRegionEndpoint
RegionEndpointUSWest2
private static string bucketName Provide bucket name
static string keyName *** Provide key name ***
static string filePath *** Provide filename of file to upload with
the full path ***

public static void Main(string[] args)
{
using (var client new AmazonS3Client(new AmazonS3Config
{
RegionEndpoint TestRegionEndpoint
UseAccelerateEndpoint true
}))

{
WriteObject(client)
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
}

static void WriteObject(IAmazonS3 client)
{
try
{
PutObjectRequest putRequest new PutObjectRequest
{
BucketName bucketName
Key keyName
FilePath filePath
}
clientPutObject(putRequest)
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&

(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS
Credentials)
ConsoleWriteLine(
For service sign up go to httpawsamazoncom
s3)
}
else
{
ConsoleWriteLine(
Error occurred Message＇{0}＇ when writing an
object
amazonS3ExceptionMessage)
}
}
}
API Version 20060301
90Amazon Simple Storage Service Developer Guide
Transfer Acceleration Examples
}
}
NET Example 3 Multipart Upload to a Transfer Acceleration Enabled Bucket
The following NET example shows how to use the accelerate endpoint for a multipart upload
using System
using SystemIO
using Amazon
using AmazonS3
using AmazonS3Model
using AmazonS3Transfer

namespace s3amazoncomdocsamples
{
class AcceleratedUploadFileMPUHAPI
{
private static RegionEndpoint TestRegionEndpoint
RegionEndpointUSWest2
private static string existingBucketName Provide bucket name
private static string keyName *** Provide your object key
***
private static string filePath *** Provide file name with full
path ***

static void Main(string[] args)
{
try
{
var client new AmazonS3Client(new AmazonS3Config
{
RegionEndpoint TestRegionEndpoint
UseAccelerateEndpoint true
})
using (TransferUtility fileTransferUtility new
TransferUtility(client))
{

1 Upload a file file name is used as the object key
name
fileTransferUtilityUpload(filePath
existingBucketName)
ConsoleWriteLine(Upload 1 completed)

2 Specify object key name explicitly
fileTransferUtilityUpload(filePath
existingBucketName keyName)
ConsoleWriteLine(Upload 2 completed)

3 Upload data from a type of SystemIOStream
using (FileStream fileToUpload
new FileStream(filePath FileModeOpen
FileAccessRead))
{
fileTransferUtilityUpload(fileToUpload
existingBucketName
keyName)
API Version 20060301
91Amazon Simple Storage Service Developer Guide
Requester Pays Buckets
}
ConsoleWriteLine(Upload 3 completed)

4Specify advanced settingsoptions
TransferUtilityUploadRequest fileTransferUtilityRequest
new TransferUtilityUploadRequest
{
BucketName existingBucketName
FilePath filePath
StorageClass S3StorageClassReducedRedundancy
PartSize 6291456 6 MB
Key keyName
CannedACL S3CannedACLPublicRead
}
fileTransferUtilityRequestMetadataAdd(param1
Value1)
fileTransferUtilityRequestMetadataAdd(param2
Value2)
fileTransferUtilityUpload(fileTransferUtilityRequest)
ConsoleWriteLine(Upload 4 completed)
}
}
catch (AmazonS3Exception s3Exception)
{
ConsoleWriteLine({0} {1} s3ExceptionMessage
s3ExceptionInnerException)
}
}
}
}
Using Other AWS SDKs
For information about using other AWS SDKs see Sample Code and Libraries
Requester Pays Buckets
Topics
• Configure Requester Pays by Using the Amazon S3 Console (p 93)
• Configure Requester Pays with the REST API (p 93)
• DevPay and Requester Pays (p 96)
• Charge Details (p 96)
In general bucket owners pay for all Amazon S3 storage and data transfer costs associated with
their bucket A bucket owner however can configure a bucket to be a Requester Pays bucket With
Requester Pays buckets the requester instead of the bucket owner pays the cost of the request and
the data download from the bucket The bucket owner always pays the cost of storing data
Typically you configure buckets to be Requester Pays when you want to share data but not incur
charges associated with others accessing the data You might for example use Requester Pays
buckets when making available large data sets such as zip code directories reference data
geospatial information or web crawling data
Important
If you enable Requester Pays on a bucket anonymous access to that bucket is not allowed
API Version 20060301
92Amazon Simple Storage Service Developer Guide
Configure with the Console
You must authenticate all requests involving Requester Pays buckets The request authentication
enables Amazon S3 to identify and charge the requester for their use of the Requester Pays bucket
When the requester assumes an AWS Identity and Access Management (IAM) role prior to making
their request the account to which the role belongs is charged for the request For more information
about IAM roles see IAM Roles in the IAM User Guide
After you configure a bucket to be a Requester Pays bucket requesters must include xamz
requestpayer in their requests either in the header for POST GET and HEAD requests or as a
parameter in a REST request to show that they understand that they will be charged for the request
and the data download
Requester Pays buckets do not support the following
• Anonymous requests
• BitTorrent
• SOAP requests
• You cannot use a Requester Pays bucket as the target bucket for end user logging or vice versa
however you can turn on end user logging on a Requester Pays bucket where the target bucket is
not a Requester Pays bucket
Configure Requester Pays by Using the Amazon S3
Console
You can configure a bucket for Requester Pays by using the Amazon S3 console
To configure a bucket for Requester Pays
1 Sign in to the AWS Management Console and open the Amazon S3 console at https
consoleawsamazoncoms3
2 In the Buckets list click the details icon on the left of the bucket name and then click Properties
to display bucket properties
3 In the Properties pane click Requester Pays
4 Select the Enabled check box
Configure Requester Pays with the REST API
Topics
• Setting the requestPayment Bucket Configuration (p 94)
• Retrieving the requestPayment Configuration (p 94)
• Downloading Objects in Requester Pays Buckets (p 95)
API Version 20060301
93Amazon Simple Storage Service Developer Guide
Configure with the REST API
Setting the requestPayment Bucket Configuration
Only the bucket owner can set the RequestPaymentConfigurationpayer configuration value
of a bucket to BucketOwner the default or Requester Setting the requestPayment resource is
optional By default the bucket is not a Requester Pays bucket
To revert a Requester Pays bucket to a regular bucket you use the value BucketOwner Typically
you would use BucketOwner when uploading data to the Amazon S3 bucket and then you would set
the value to Requester before publishing the objects in the bucket
To set requestPayment
• Use a PUT request to set the Payer value to Requester on a specified bucket
PUT requestPayment HTTP11
Host [BucketName]s3amazonawscom
ContentLength 173
Date Wed 01 Mar 2009 120000 GMT
Authorization AWS [Signature]
doc20060301>
Requester

If the request succeeds Amazon S3 returns a response similar to the following
HTTP11 200 OK
xamzid2 [id]
xamzrequestid [request_id]
Date Wed 01 Mar 2009 120000 GMT
ContentLength 0
Connection close
Server AmazonS3
xamzrequestchargedrequester
You can set Requester Pays only at the bucket level you cannot set Requester Pays for specific
objects within the bucket
You can configure a bucket to be BucketOwner or Requester at any time Realize however that
there might be a small delay on the order of minutes before the new configuration value takes effect
Note
Bucket owners who give out presigned URLs should think twice before configuring a bucket
to be Requester Pays especially if the URL has a very long lifetime The bucket owner
is charged each time the requester uses a presigned URL that uses the bucket owner＇s
credentials
Retrieving the requestPayment Configuration
You can determine the Payer value that is set on a bucket by requesting the resource
requestPayment
To return the requestPayment resource
• Use a GET request to obtain the requestPayment resource as shown in the following request
API Version 20060301
94Amazon Simple Storage Service Developer Guide
Configure with the REST API
GET requestPayment HTTP11
Host [BucketName]s3amazonawscom
Date Wed 01 Mar 2009 120000 GMT
Authorization AWS [Signature]
If the request succeeds Amazon S3 returns a response similar to the following
HTTP11 200 OK
xamzid2 [id]
xamzrequestid [request_id]
Date Wed 01 Mar 2009 120000 GMT
ContentType [type]
ContentLength [length]
Connection close
Server AmazonS3


Requester

This response shows that the payer value is set to Requester
Downloading Objects in Requester Pays Buckets
Because requesters are charged for downloading data from Requester Pays buckets the requests
must contain a special parameter xamzrequestpayer which confirms that the requester knows
he or she will be charged for the download To access objects in Requester Pays buckets requests
must include one of the following
• For GET HEAD and POST requests include xamzrequestpayer requester in the
header
• For signed URLs include xamzrequestpayerrequester in the request
If the request succeeds and the requester is charged the response includes the header xamz
requestchargedrequester If xamzrequestpayer is not in the request Amazon S3 returns
a 403 error and charges the bucket owner for the request
Note
Bucket owners do not need to add xamzrequestpayer to their requests
Ensure that you have included xamzrequestpayer and its value in your signature
calculation For more information see Constructing the CanonicalizedAmzHeaders
Element (p 579)
To download objects from a Requester Pays bucket
• Use a GET request to download an object from a Requester Pays bucket as shown in the following
request
GET [destinationObject] HTTP11
Host [BucketName]s3amazonawscom
xamzrequestpayer requester
Date Wed 01 Mar 2009 120000 GMT
Authorization AWS [Signature]
API Version 20060301
95Amazon Simple Storage Service Developer Guide
DevPay and Requester Pays
If the GET request succeeds and the requester is charged the response includes xamzrequest
chargedrequester
Amazon S3 can return an Access Denied error for requests that try to get objects from a Requester
Pays bucket For more information go to Error Responses
DevPay and Requester Pays
You can use Amazon DevPay to sell content that is stored in your Requester Pays bucket For
more information go to Using Amazon S3 Requester Pays with DevPay in the Using Amazon S3
Requester Pays with DevPay
Charge Details
The charge for successful Requester Pays requests is straightforward the requester pays for the data
transfer and the request the bucket owner pays for the data storage However the bucket owner is
charged for the request under the following conditions
• The requester doesn＇t include the parameter xamzrequestpayer in the header (GET HEAD or
POST) or as a parameter (REST) in the request (HTTP code 403)
• Request authentication fails (HTTP code 403)
• The request is anonymous (HTTP code 403)
• The request is a SOAP request
Buckets and Access Control
Each bucket has an associated access control policy This policy governs the creation deletion and
enumeration of objects within the bucket For more information see Managing Access Permissions to
Your Amazon S3 Resources (p 266)
Billing and Reporting of Buckets
Fees for object storage and network data transfer are always billed to the owner of the bucket that
contains the object unless the bucket was created as a Requester Pays bucket
The reporting tools available at the AWS developer portal organize your Amazon S3 usage reports by
bucket For more information about cost considerations see Amazon S3 Pricing
Cost Allocation Tagging
You can use cost allocation tagging to label Amazon S3 buckets so that you can more easily track their
cost against projects or other criteria
Use tags to organize your AWS bill to reflect your own cost structure To do this sign up to get your
AWS account bill with tag key values included Then to see the cost of combined resources organize
your billing information according to resources with the same tag key values For example you can tag
several resources with a specific application name and then organize your billing information to see
the total cost of that application across several services For more information see Cost Allocation and
Tagging in About AWS Billing and Cost Management
A cost allocation tag is a namevalue pair that you define and associate with an Amazon S3 bucket
We recommend that you use a consistent set of tag keys to make it easier to track costs associated
with your Amazon S3 buckets
API Version 20060301
96Amazon Simple Storage Service Developer Guide
Cost Allocation Tagging
Each Amazon S3 bucket has a tag set which contains all the tags that are assigned to that bucket A
tag set can contain as many as ten tags or it can be empty
If you add a tag that has the same key as an existing tag on a bucket the new value overwrites the old
value
AWS does not apply any semantic meaning to your tags tags are interpreted strictly as character
strings AWS does not automatically set any tags on buckets
You can use the Amazon S3 console the CLI or the Amazon S3 API to add list edit or delete tags
For more information about creating tags in the console go to Managing Cost Allocation Tagging in the
Amazon Simple Storage Service Console User Guide
The following list describes the characteristics of a cost allocation tag
• The tag key is the required name of the tag The string value can contain 1 to 128 Unicode
characters It cannot be prefixed with aws The string can contain only the set of Unicode letters
digits whitespace ＇_＇ ＇＇ ＇＇ ＇＇ ＇+＇ ＇＇ (Java regex ^([＼＼p{L}＼＼p{Z}＼＼p{N}_+＼＼]*))
• The tag value is a required string value of the tag The string value can contain from 1 to 256
Unicode characters It cannot be prefixed with aws The string can contain only the set of Unicode
letters digits whitespace ＇_＇ ＇＇ ＇＇ ＇＇ ＇+＇ ＇＇ (Java regex ^([＼＼p{L}＼＼p{Z}＼＼p{N}_+＼＼]*))
Values do not have to be unique in a tag set and they can be null For example you can have the
same keyvalue pair in tag sets named projectTrinity and costcenterTrinity
API Version 20060301
97Amazon Simple Storage Service Developer Guide
Working with Amazon S3 Objects
Amazon S3 is a simple key value store designed to store as many objects as you want You store
these objects in one or more buckets An object consists of the following
• Key – The name that you assign to an object You use the object key to retrieve the object
For more information see Object Key and Metadata (p 99)
• Version ID – Within a bucket a key and version ID uniquely identify an object
The version ID is a string that Amazon S3 generates when you add an object to a bucket For more
information see Object Versioning (p 106)
• Value – The content that you are storing
An object value can be any sequence of bytes Objects can range in size from zero to 5 TB For
more information see Uploading Objects (p 157)
• Metadata – A set of namevalue pairs with which you can store information regarding the object
You can assign metadata referred to as userdefined metadata to your objects in Amazon S3
Amazon S3 also assigns systemmetadata to these objects which it uses for managing objects For
more information see Object Key and Metadata (p 99)
• Subresources – Amazon S3 uses the subresource mechanism to store objectspecific additional
information
Because subresources are subordinates to objects they are always associated with some other
entity such as an object or a bucket For more information see Object Subresources (p 105)
• Access Control Information – You can control access to the objects you store in Amazon S3
Amazon S3 supports both the resourcebased access control such as an Access Control List (ACL)
and bucket policies and userbased access control For more information see Managing Access
Permissions to Your Amazon S3 Resources (p 266)
For more information about working with objects see the following sections Note that your Amazon
S3 resources (for example buckets and objects) are private by default You will need to explicitly grant
permission for others to access these resources For example you might want to share a video or a
photo stored in your Amazon S3 bucket on your website That will work only if you either make the
object public or use a presigned URL on your website For more information about sharing objects see
Share an Object with Others (p 152)
Topics
API Version 20060301
98Amazon Simple Storage Service Developer Guide
Object Key and Metadata
• Object Key and Metadata (p 99)
• Storage Classes (p 103)
• Object Subresources (p 105)
• Object Versioning (p 106)
• Object Lifecycle Management (p 109)
• CrossOrigin Resource Sharing (CORS) (p 131)
• Operations on Objects (p 142)
Object Key and Metadata
Topics
• Object Keys (p 99)
• Object Metadata (p 101)
Each Amazon S3 object has data a key and metadata Object key (or key name) uniquely identifies
the object in a bucket Object metadata is a set of namevalue pairs You can set object metadata at
the time you upload it After you upload the object you cannot modify object metadata The only way to
modify object metadata is to make a copy of the object and set the metadata
Object Keys
When you create an object you specify the key name which uniquely identifies the object in the
bucket For example in the Amazon S3 console (see AWS Management Console) when you highlight
a bucket a list of objects in your bucket appears These names are the object keys The name for a
key is a sequence of Unicode characters whose UTF8 encoding is at most 1024 bytes long
Note
If you anticipate that your workload against Amazon S3 will exceed 100 requests per second
follow the Amazon S3 key naming guidelines for best performance For information see
Request Rate and Performance Considerations (p 518)
Object Key Naming Guidelines
Although you can use any UTF8 characters in an object key name the following key naming best
practices help ensure maximum compatibility with other applications Each application may parse
special characters differently The following guidelines help you maximize compliance with DNS web
safe characters XML parsers and other APIs
Safe Characters
The following character sets are generally safe for use in key names
• Alphanumeric characters [09azAZ]
• Special characters _ * ＇ ( and )
The following are examples of valid object key names
• 4myorganization
• mygreat_photos2014janmyvacationjpg
API Version 20060301
99Amazon Simple Storage Service Developer Guide
Object Keys
• videos2014birthdayvideo1wmv
Note that the Amazon S3 data model is a flat structure you create a bucket and the bucket stores
objects There is no hierarchy of subbuckets or subfolders however you can infer logical hierarchy
using key name prefixes and delimiters as the Amazon S3 console does The Amazon S3 console
supports a concept of folders Suppose your bucket (companybucket) has four objects with the
following object keys
DevelopmentProjects1xls
Financestatement1pdf
Privatetaxdocumentpdf
s3dgpdf
The console uses the key name prefixes (Development Finance and Private) and delimiter
(＇＇) to present a folder structure as shown
The s3dgpdf key does not have a prefix so its object appears directly at the root level of the
bucket If you open the Development folder you will see the Project1xls object in it
Note
Amazon S3 supports buckets and objects there is no hierarchy in Amazon S3 However the
prefixes and delimiters in an object key name enables the Amazon S3 console and the AWS
SDKs to infer hierarchy and introduce concept of folders
Characters That Might Require Special Handling
The following characters in a key name may require additional code handling and will likely need to be
URL encoded or referenced as HEX Some of these are nonprintable characters and your browser
may not handle them which will also require special handling
Ampersand (&) Dollar () ASCII character ranges 00–1F
hex (0–31 decimal) and 7F (127
decimal)
＇At＇ symbol (@) Equals () Semicolon ()
Colon () Plus (+) Space – Significant sequences
of spaces may be lost in some
uses (especially multiple
spaces)
API Version 20060301
100Amazon Simple Storage Service Developer Guide
Object Metadata
Comma () Question mark ()
Characters to Avoid
You should avoid the following characters in a key name because of significant special handling for
consistency across all applications
Backslash (＼) Left curly brace ({) Nonprintable ASCII characters
(128–255 decimal characters)
Caret (^) Right curly brace (}) Percent character ()
Grave accent back tick (`) Right square bracket (]) Quotation marks
＇Greater Than＇ symbol (>) Left square bracket ([) Tilde (~)
＇Less Than＇ symbol (<) ＇Pound＇ character (#) Vertical bar pipe (|)
Object Metadata
There are two kinds of metadata system metadata and userdefined metadata
SystemDefined Metadata
For each object stored in a bucket Amazon S3 maintains a set of system metadata Amazon S3
processes this system metadata as needed For example Amazon S3 maintains object creation date
and size metadata and uses this information as part of object management
There are two categories of system metadata
• Metadata such as object creation date is system controlled where only Amazon S3 can modify the
value
• Other system metadata such as the storage class configured for the object and whether the object
has serverside encryption enabled are examples of system metadata whose values you control If
you have your bucket configured as a website sometimes you might want to redirect a page request
to another page or an external URL In this case a web page is an object in your bucket Amazon S3
stores the page redirect value as system metadata whose value you control
When you create objects you can configure values of these system metadata items or update the
values when you need For more information about storage class see Storage Classes (p 103)
For more information about serverside encryption see Protecting Data Using Encryption (p 380)
The following table provides a list of systemdefined metadata and whether you can update it
Name Description Can User
Modify the
Value
Date Current date and time No
ContentLength Object size in bytes No
LastModified Object creation date or the last modified date whichever is
the latest
No
API Version 20060301
101Amazon Simple Storage Service Developer Guide
Object Metadata
Name Description Can User
Modify the
Value
ContentMD5 The base64encoded 128bit MD5 digest of the object No
xamzserverside
encryption
Indicates whether serverside encryption is enabled for the
object and whether that encryption is from the AWS Key
Management Service (SSEKMS) or from AWSManaged
Encryption (SSES3) For more information see Protecting
Data Using ServerSide Encryption (p 381)
Yes
xamzversionid Object version When you enable versioning on a
bucket Amazon S3 assigns a version number to objects
added to the bucket For more information see Using
Versioning (p 423)
No
xamzdeletemarker In a bucket that has versioning enabled this Boolean
marker indicates whether the object is a delete marker
No
xamzstorageclass Storage class used for storing the object For more
information see Storage Classes (p 103)
Yes
xamzwebsite
redirectlocation
Redirects requests for the associated object to another
object in the same bucket or an external URL For
more information see Configuring a Web Page
Redirect (p 460)
Yes
xamzserverside
encryptionawskms
keyid
If the xamzserversideencryption is present and has
the value of awskms this indicates the ID of the Key
Management Service (KMS) master encryption key that
was used for the object
Yes
xamzserverside
encryptioncustomer
algorithm
Indicates whether serverside encryption with customer
provided encryption keys (SSEC) is enabled For more
information see Protecting Data Using ServerSide
Encryption with CustomerProvided Encryption Keys (SSE
C) (p 395)
Yes
UserDefined Metadata
When uploading an object you can also assign metadata to the object You provide this optional
information as a namevalue (keyvalue) pair when you send a PUT or POST request to create the
object When uploading objects using the REST API the optional userdefined metadata names must
begin with xamzmeta to distinguish them from other HTTP headers When you retrieve the object
using the REST API this prefix is returned When uploading objects using the SOAP API the prefix is
not required When you retrieve the object using the SOAP API the prefix is removed regardless of
which API you used to upload the object
Note
SOAP support over HTTP is deprecated but it is still available over HTTPS New Amazon S3
features will not be supported for SOAP We recommend that you use either the REST API or
the AWS SDKs
When metadata is retrieved through the REST API Amazon S3 combines headers that have the same
name (ignoring case) into a commadelimited list If some metadata contains unprintable characters it
is not returned Instead the xamzmissingmeta header is returned with a value of the number of
the unprintable metadata entries
API Version 20060301
102Amazon Simple Storage Service Developer Guide
Storage Classes
Userdefined metadata is a set of keyvalue pairs Amazon S3 stores userdefined metadata keys in
lowercase Each keyvalue pair must conform to USASCII when using REST and UTF8 when using
SOAP or browserbased uploads via POST
Note
The PUT request header is limited to 8 KB in size Within the PUT request header the user
defined metadata is limited to 2 KB in size The size of userdefined metadata is measured by
taking the sum of the number of bytes in the UTF8 encoding of each key and value
Storage Classes
Each object in Amazon S3 has a storage class associated with it For example if you list all objects in
the bucket the console shows the storage class for all the objects in the list
Amazon S3 offers the following storage classes for the objects that you store You choose one
depending on your use case scenario and performance access requirements All of these storage
classes offer high durability
• STANDARD – This storage class is ideal for performancesensitive use cases and frequently
accessed data
STANDARD is the default storage class if you don＇t specify storage class at the time that you upload
an object Amazon S3 assumes the STANDARD storage class
• STANDARD_IA – This storage class (IA for infrequent access) is optimized for longlived and less
frequently accessed data for example backups and older data where of access has diminished but
the use case still demands high performance
Note
There is a retrieval fee associated with STANDARD_IA objects which makes it most
suitable for infrequently accessed data For pricing information see Amazon S3 Pricing
For example initially you might upload objects using the STANDARD storage class and then use a
bucket lifecycle configuration rule to transition objects (see Object Lifecycle Management (p 109))
to the STANDARD_IA (or GLACIER) storage class at some point in the object＇s lifetime For more
information about lifecycle management see Object Lifecycle Management (p 109)
The STANDARD_IA objects are available for realtime access The table at the end of this section
highlights some of the differences in these storage classes
The STANDARD_IA storage class is suitable for larger objects greater than 128 Kilobytes that
you want to keep for at least 30 days For example bucket lifecycle configuration has minimum
object size limit for Amazon S3 to transition objects For more information see Supported
Transitions (p 110)
• GLACIER – The GLACIER storage class is suitable for archiving data where data access is
infrequent and retrieval time of several hours is acceptable (Archived objects are not available for
realtime access You must first restore the objects before you can access them)
API Version 20060301
103Amazon Simple Storage Service Developer Guide
Storage Classes
The GLACIER storage class uses the very lowcost Amazon Glacier storage service but you still
manage objects in this storage class through Amazon S3 Note the following about the GLACIER
storage class
• You cannot specify GLACIER as the storage class at the time that you create an object You
create GLACIER objects by first uploading objects using STANDARD RRS or STANDARD_IA as
the storage class Then you transition these objects to the GLACIER storage class using lifecycle
management For more information see Object Lifecycle Management (p 109)
• You must first restore the GLACIER objects before you can access them (STANDARD RRS
and STANDARD_IA objects are available for anytime access) For more information GLACIER
Storage Class Additional Lifecycle Configuration Considerations (p 124)
To learn more about the Amazon Glacier service see the Amazon Glacier Developer Guide
All the preceding storage classes are designed to sustain the concurrent loss of data in two facilities
(for details see the following availability and durability table)
In addition to the performance requirements of your application scenario there is also price
performance considerations For the Amazon S3 storage classes and pricing see Amazon S3 Pricing
Amazon S3 also offers the following storage class that enables you to save costs by maintaining fewer
redundant copies of your data
• REDUCED_REDUNDANCY – The Reduced Redundancy Storage (RRS) storage class is designed
for noncritical reproducible data stored at lower levels of redundancy than the STANDARD storage
class which reduces storage costs For example if you upload an image and use STANDARD
storage class for it you might compute a thumbnail and save it as an object of the RRS storage
class
The durability level (see the following table) corresponds to an average annual expected loss of
001 of objects For example if you store 10000 objects using the RRS option you can on
average expect to incur an annual loss of a single object per year (001 of 10000 objects)
Note
This annual loss represents an expected average and does not guarantee the loss of less
than 001 of objects in a given year
RRS provides a costeffective highly available solution for distributing or sharing content that is
durably stored elsewhere or for storing thumbnails transcoded media or other processed data that
can be easily reproduced
If an RRS object is lost Amazon S3 returns a 405 error on requests made to that object
Amazon S3 can send an event notification to alert a user or start a workflow when it detects that an
RRS object is lost To receive notifications you need to add notification configuration to your bucket
For more information see Configuring Amazon S3 Event Notifications (p 472)
The following table summarizes the durability and availability offered by each of the storage classes
Storage Class Durability (designed for) Availability
(designed for)
Other
Considerations
STANDARD 99999999999 9999 None
STANDARD_IA 99999999999 999 There is a retrieval
fee associated with
API Version 20060301
104Amazon Simple Storage Service Developer Guide
Subresources
Storage Class Durability (designed for) Availability
(designed for)
Other
Considerations
STANDARD_IA
objects which
makes it most
suitable for
infrequently
accessed data For
pricing information
see Amazon S3
Pricing
GLACIER 99999999999 9999 (after
you restore
objects)
GLACIER objects
are not available for
realtime access
You must first
restore archived
objects before
you can access
them and restoring
objects can take
34 hours For more
information see
Restoring Archived
Objects (p 125)
RRS 9999 9999 None
Object Subresources
Amazon S3 defines a set of subresources associated with buckets and objects Subresources are
subordinates to objects that is subresources do not exist on their own they are always associated
with some other entity such as an object or a bucket
The following table lists the subresources associated with Amazon S3 objects
Subresource Description
acl Contains a list of grants identifying the grantees and the permissions granted When
you create an object the acl identifies the object owner as having full control over
the object You can retrieve an object ACL or replace it with updated list of grants
Any update to an ACL requires you to replace the existing ACL For more information
about ACLs see Managing Access with ACLs (p 364)
torrent Amazon S3 supports the BitTorrent protocol Amazon S3 uses the torrent
subresource to return the torrent file associated with the specific object To retrieve a
torrent file you specify the torrent subresource in your GET request Amazon S3
creates a torrent file and returns it You can only retrieve the torrent subresource
you cannot create update or delete the torrent subresource For more information
see Using BitTorrent with Amazon S3 (p 531)
API Version 20060301
105Amazon Simple Storage Service Developer Guide
Versioning
Object Versioning
Versioning enables you to keep multiple versions of an object in one bucket for example my
imagejpg (version 111111) and myimagejpg (version 222222) You might want to enable
versioning to protect yourself from unintended overwrites and deletions or to archive objects so that
you can retrieve previous versions of them
Note
The SOAP API does not support versioning SOAP support over HTTP is deprecated but it is
still available over HTTPS New Amazon S3 features will not be supported for SOAP
Object versioning can be used in combination with Object Lifecycle Management (p 109) allowing
you to customize your data retention needs while controlling your related storage costs For more
information about adding lifecycle configuration to versioningenabled buckets using the AWS
Management Console see Lifecycle Configuration for a Bucket with Versioning in the Amazon Simple
Storage Service Console User Guide
Important
If you have an object expiration lifecycle policy in your nonversioned bucket and you want to
maintain the same permanent delete behavior when you enable versioning you must add a
noncurrent expiration policy The noncurrent expiration lifecycle policy will manage the deletes
of the noncurrent object versions in the versionenabled bucket (A versionenabled bucket
maintains one current and zero or more noncurrent object versions)
You must explicitly enable versioning on your bucket By default versioning is disabled Regardless
of whether you have enabled versioning each object in your bucket has a version ID If you have not
enabled versioning then Amazon S3 sets the version ID value to null If you have enabled versioning
Amazon S3 assigns a unique version ID value for the object When you enable versioning on a bucket
existing objects if any in the bucket are unchanged the version IDs (null) contents and permissions
remain the same
Enabling and suspending versioning is done at the bucket level When you enable versioning
for a bucket all objects added to it will have a unique version ID Unique version IDs are
randomly generated Unicode UTF8 encoded URLready opaque strings that are at most
1024 bytes long An example version ID is 3L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo Only Amazon S3 generates version IDs They cannot be
edited
Note
For simplicity we will use much shorter IDs in all our examples
When you PUT an object in a versioningenabled bucket the noncurrent version is not overwritten
The following figure shows that when a new version of photogif is PUT into a bucket that already
contains an object with the same name the original object (ID 111111) remains in the bucket
Amazon S3 generates a new version ID (121212) and adds the newer version to the bucket
API Version 20060301
106Amazon Simple Storage Service Developer Guide
Versioning
This functionality prevents you from accidentally overwriting or deleting objects and affords you the
opportunity to retrieve a previous version of an object
When you DELETE an object all versions remain in the bucket and Amazon S3 inserts a delete marker
as shown in the following figure
The delete marker becomes the current version of the object By default GET requests retrieve the
most recently stored version Performing a simple GET Object request when the current version is a
delete marker returns a 404 Not Found error as shown in the following figure
API Version 20060301
107Amazon Simple Storage Service Developer Guide
Versioning
You can however GET a noncurrent version of an object by specifying its version ID In the following
figure we GET a specific object version 111111 Amazon S3 returns that object version even though
it＇s not the current version
You can permanently delete an object by specifying the version you want to delete Only the owner
of an Amazon S3 bucket can permanently delete a version The following figure shows how DELETE
versionId permanently deletes an object from a bucket and that Amazon S3 doesn＇t insert a delete
marker
API Version 20060301
108Amazon Simple Storage Service Developer Guide
Lifecycle Management
You can add additional security by configuring a bucket to enable MFA (MultiFactor Authentication)
Delete When you do the bucket owner must include two forms of authentication in any request
to delete a version or change the versioning state of the bucket For more information see MFA
Delete (p 424)
For more information see Using Versioning (p 423)
Object Lifecycle Management
This section provides an overview of the Amazon S3 lifecycle feature that you can use to manage
lifecycle of objects in your bucket
What Is Lifecycle Configuration
You manage an object＇s lifecycle by using a lifecycle configuration which defines how Amazon S3
manages objects during their lifetime Lifecycle configuration enables you to simplify the lifecycle
management of your objects such as automated transition of lessfrequently accessed objects to low
cost storage alternatives and scheduled deletions You can configure as many as 1000 lifecycle rules
per bucket
You can define lifecycle configuration rules for objects that have a welldefined lifecycle You can use
lifecycle configurations for objects you want to switch to different storage classes or delete during their
lifecycle for example
• If you are uploading periodic logs to your bucket your application might need these logs for a week
or a month after creation and after that you might want to delete them
• Some documents are frequently accessed for a limited period of time After that these documents
are less frequently accessed Over time you might not need realtime access to these objects
but your organization or regulations might require you to archive them for a longer period and then
optionally delete them later
• You might also upload some types of data to Amazon S3 primarily for archival purposes for example
digital media archives financial and healthcare records raw genomics sequence data longterm
database backups and data that must be retained for regulatory compliance
API Version 20060301
109Amazon Simple Storage Service Developer Guide
How Do I Configure a Lifecycle
How Do I Configure a Lifecycle
You can specify a lifecycle configuration as XML A lifecycle configuration comprises a set of rules with
predefined actions that you want Amazon S3 to perform on objects during their lifetime These actions
include
• Transition actions in which you define when objects transition to another Amazon S3 storage class
For example you may choose to transition objects to the STANDARD_IA (IA for infrequent access)
storage class 30 days after creation or archive objects to the GLACIER storage class one year after
creation
• Expiration actions in which you specify when the objects expire Then Amazon S3 deletes the
expired objects on your behalf
For more information about lifecycle rules see Lifecycle Configuration Elements (p 113)
Amazon S3 stores the configuration as a lifecycle subresource attached to your bucket Using the
Amazon S3 API you can PUT GET or DELETE a lifecycle configuration For more information see
PUT Bucket lifecycle GET Bucket lifecycle or DELETE Bucket lifecycle You can also configure
the lifecycle by using the Amazon S3 console or programmatically by using the AWS SDK wrapper
libraries and if you need to you can also make the REST API calls directly Then Amazon S3 applies
the lifecycle rules to all or specific objects identified in the rule
Transitioning Objects General Considerations
You can add rules in a lifecycle configuration to transition objects to another Amazon S3 storage
class For example you might transition objects to the STANDARD_IA storage class when you know
those objects are infrequently accessed You might also want to archive objects that don＇t need real
time access to the GLACIER storage class The following sections describe transitioning related
considerations and constraints
Supported Transitions
In a lifecycle configuration you can define rules to transition objects from one storage class to another
The following are supported transitions
• From the STANDARD or REDUCED_REDUNDANCY storage classes to STANDARD_IA The
following constraints apply
• Amazon S3 does not transition objects less than 128 Kilobytes in size to the STANDARD_IA
storage class Cost benefits of transitioning to STANDARD_IA can be realized for larger objects
For smaller objects it is not cost effective and Amazon S3 will not transition them
• Objects must be stored at least 30 days in the current storage class before you can transition
them to STANDARD_IA For example you cannot create a lifecycle rule to transition objects to the
STANDARD_IA storage class one day after creation
Transitions before the first 30 days are not supported because often younger objects are accessed
more frequently or deleted sooner than is suitable for STANDARD_IA
• If you are transitioning noncurrent objects (versioned bucket scenario) you can transition to
STANDARD_IA only objects that are at least 30 days noncurrent
• From any storage class to GLACIER
For more information see GLACIER Storage Class Additional Lifecycle Configuration
Considerations (p 124)
• You can combine these rules to manage an object＇s complete lifecycle including a first transition to
STANDARD_IA a second transition to GLACIER for archival and an expiration
API Version 20060301
110Amazon Simple Storage Service Developer Guide
Transitioning Objects General Considerations
Note
When configuring lifecycle the API will not allow you to create a lifecycle policy in which
you specify both of these transitions but the GLACIER transition occurs less than 30 days
after the STANDARD_IA transition This is because such a lifecycle policy may increase
costs because of the minimum 30 day storage charge associated with the STANDARD_IA
storage class For more information about cost considerations see Amazon S3 Pricing
For example suppose the objects you create have a welldefined lifecycle Initially the objects are
frequently accessed for a period of 30 days After the initial period the frequency of access diminishes
where objects are infrequently accessed for up to 90 days After that the objects are no longer needed
You may choose to archive or delete them You can use a lifecycle configuration to define transition
and expiration of objects that matches this example scenario (transition to STANDARD_IA 30 days
after creation and transition to GLACIER 90 days after creation and perhaps expire them after certain
number of days) As you tier down the object＇s storage class in the transition you can benefit from the
storage cost savings For more information about cost considerations see Amazon S3 Pricing
You can think of lifecycle transitions as supporting storage class tiers (see Storage Classes (p 103))
which offer different costs and benefits You may choose to transition an object to another storage
class in the object＇s lifetime for cost saving considerations and lifecycle configuration enables you to
do that For example to manage storage costs you might configure lifecycle to change an object＇s
storage class from the STANDARD which is most available and durable storage class to the
STANDARD_IA (IA for infrequent access) and then to the GLACIER storage class (where the objects
are archived and only available after you restore) These transitions can lower your storage costs
The following are not supported transitions
• You cannot transition from STANDARD_IA to STANDARD or REDUCED_REDUNDANCY
• You cannot transition from GLACIER to any other storage class
• You cannot transition from any storage class to REDUCED_REDUNDANCY
Transitioning to the GLACIER storage class (Object Archival)
Using lifecycle configuration you can transition objects to the GLACIER storage class—that is archive
data to Amazon Glacier a lowercost storage solution Before you archive objects note the following
• Objects in the GLACIER storage class are not available in real time
Archived objects are Amazon S3 objects but before you can access an archived object you must
first restore a temporary copy of it The restored object copy is available only for the duration you
specify in the restore request After that Amazon S3 deletes the temporary copy and the object
remains archived in Amazon Glacier
Note that object restoration from an archive can take up to five hours
You can restore an object by using the Amazon S3 console or programmatically by using the AWS
SDKs wrapper libraries or the Amazon S3 REST API in your code For more information see POST
Object restore
• The transition of objects to the GLACIER storage class is oneway
You cannot use a lifecycle configuration rule to convert the storage class of an object from
GLACIER to Standard or RRS If you want to change the storage class of an already archived
object to either Standard or RRS you must use the restore operation to make a temporary copy
first Then use the copy operation to overwrite the object as a STANDARD STANDARD_IA or
REDUCED_REDUNDANCY object
API Version 20060301
111Amazon Simple Storage Service Developer Guide
Expiring Objects General Considerations
• The GLACIER storage class objects are visible and available only through Amazon S3 not through
Amazon Glacier
Amazon S3 stores the archived objects in Amazon Glacier however these are Amazon S3 objects
and you can access them only by using the Amazon S3 console or the API You cannot access the
archived objects through the Amazon Glacier console or the API
Expiring Objects General Considerations
When an object reaches the end of its lifetime Amazon S3 queues it for removal and removes it
asynchronously There may be a delay between the expiration date and the date at which Amazon S3
removes an object You are not charged for storage time associated with an object that has expired
To find when an object is scheduled to expire you can use the HEAD Object or the GET Object APIs
These APIs return response headers that provide object expiration information
There are additional cost considerations if you put lifecycle policy to expire objects that have been in
STANDARD_IA for less than 30 days or GLACIER for less than 90 days For more information about
cost considerations see Amazon S3 Pricing
Lifecycle and Other Bucket Configurations
In addition to lifecycle configuration your bucket can have other configurations associated This is
section explains how lifecycle configuration relates to other bucket configurations
Lifecycle and Versioning
You can add lifecycle configuration to nonversioned buckets and versioningenabled buckets For
more information see Object Versioning (p 106) A versioningenabled bucket maintains one current
and zero or more noncurrent object versions You can define separate lifecycle rules for current and
noncurrent versions
For more information see Lifecycle Configuration Elements (p 113) For information about
versioning see Object Versioning (p 106)
Lifecycle and MFA Enabled Buckets
Lifecycle configuration on MFAenabled buckets is not supported
Lifecycle and Logging
If you have logging enabled on your bucket Amazon S3 reports the results of expiration action as
follows
• If the lifecycle expiration action results in Amazon S3 permanently removing the object Amazon S3
reports it as operation S3EXPIREOBJECT in the log record
• For a versioningenabled bucket if the lifecycle expiration action results in a logical deletion of
current version in which Amazon S3 adds a delete marker Amazon S3 reports the logical deletion
as operation S3CREATEDELETEMARKER in the log record For more information see Object
Versioning (p 106)
• When Amazon S3 transitions object to the GLACIER storage class it reports it as operation
S3TRANSITIONOBJECT in the log record to indicate it has initiated the operation When it is
transition to the STANDARD_IA storage class it is reported as S3TRANSITION_SIAOBJECT
API Version 20060301
112Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements
Related Topics
• Lifecycle Configuration Elements (p 113)
• GLACIER Storage Class Additional Lifecycle Configuration Considerations (p 124)
• Specifying a Lifecycle Configuration (p 125)
Lifecycle Configuration Elements
Topics
• ID Element (p 114)
• Status Element (p 114)
• Prefix Element (p 114)
• Elements to Describe Lifecycle Actions (p 115)
• Examples of Lifecycle Configuration (p 117)
You specify a lifecycle policy configuration as XML It consists of one or more lifecycle rules Each rule
consists of the following
• Rule metadata that include a rule ID and status indicating whether the rule is enabled or disabled If
a rule is disabled Amazon S3 will not perform any actions specified in the rule
• Prefix identifying objects by the key prefix to which the rule applies
• One or more transitionexpiration actions with a date or a time period in the object＇s lifetime when
you want Amazon S3 to perform the specified action
The following are two introductory example configurations
Example 1 Lifecycle configuration
Suppose you want to transition objects with key prefix documents to the GLACIER storage class one
year after you create them and then permanently remove them 10 years after you created them You
can accomplish this by attaching the following lifecycle configuration to the bucket


samplerule
documents
Enabled

365
GLACIER


3650



The lifecycle configuration defines one rule that applies to objects with the key name prefix
documents The rule specifies two actions (Transition and Expiration) The rule is in effect because
the rule status is Enabled
API Version 20060301
113Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements
Example 2 Lifecycle configuration on a versioningenabled bucket
If your bucket is versioningenabled you have one current object version and zero or more noncurrent
versions For more information see Object Versioning (p 106)
For a versioningenabled bucket the lifecycle actions apply as follows
• Transition and Expiration actions apply to current versions
• NoncurrentVersionTransition and NoncurrentVersionExpiration actions apply to
noncurrent versions
The following example lifecycle configuration has one rule that applies to objects with key name prefix
logs The rule specifies two actions for noncurrent versions
• The NoncurrentVersionTransition action directs Amazon S3 to transition noncurrent objects to
the GLACIER storage class 30 days after the objects become noncurrent
• The NoncurrentVersionExpiration action directs Amazon S3 to permanently remove the
noncurrent objects 180 days after they become noncurrent


samplerule
logs
Enabled

30
GLACIER


180



The following sections describe these XML elements in a lifecycle configuration
ID Element
A lifecycle configuration can have up to 1000 rules The ID element uniquely identifies a rule
Status Element
The Status element value can be either Enabled or Disabled If a rule is disabled Amazon S3 will not
perform any of the actions defined in the rule
Prefix Element
The Prefix element identifies objects to which the rule applies If you specify an empty prefix the rule
applies to all objects in the bucket If you specify a key name prefix the rule applies only to the objects
whose key name begins with specified string For more information about object keys see Object
Keys (p 99)
API Version 20060301
114Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements
Elements to Describe Lifecycle Actions
You can direct Amazon S3 to perform specific actions in an object＇s lifetime by specifying one or
more of the following predefined actions in a lifecycle rule The effect of these actions depend on the
versioning state of your bucket
• Transition action element – You specify the Transition action to transition objects from
one storage class to another For more information about transitioning objects see Supported
Transitions (p 110) When a specified date or time period in the object＇s lifetime is reached
Amazon S3 performs the transition
For a versioned bucket (versioningenabled or versioningsuspended bucket) the Transition
action applies to the current object version To manage noncurrent versions Amazon S3 defines the
NoncurrentVersionTranstion action (described below)
• Expiration action element – The Expiration action expires objects identified in the rule Amazon
S3 makes all expired objects unavailable Whether the objects are permanently removed depends
on the versioning state of the bucket
Important
Object expiration lifecycle polices do not remove incomplete multipart uploads To remove
incomplete multipart uploads you must use the AbortIncompleteMultipartUpload lifecycle
configuration action that is described later in this section
• Nonversioned bucket – The Expiration action results in Amazon S3 permanently removing
the object
• Versioned bucket – For a versioned bucket versioningenabled or versioningsuspended (see
Using Versioning (p 423)) there are several considerations that guide how Amazon S3 handles
the expiration action Regardless of the version state the following applies
• The expiration action applies only to the current version (no impact on noncurrent object
versions)
• Amazon S3 will not take any action if there are one or more object versions and the delete
marker is the current version
• If the current object version is the only object version and it is also a delete marker (also referred
as the expired object delete marker where all object versions are deleted and you only have
a delete marker remaining) Amazon S3 will remove the expired object delete marker You can
also use the expiration action to direct Amazon S3 to remove any expired object delete markers
For an example see Example 8 Removing Expired Object Delete Markers (p 121)
Important
Amazon S3 will remove an expired object delete marker no sooner than 48 hours after
the object expired
The additional considerations for Amazon S3 to manage expiration are as follows
• Versioningenabled bucket
If current object version is not a delete marker Amazon S3 adds a delete marker with a unique
version ID making the current version noncurrent and the delete marker the current version
• Versioningsuspended bucket
In a versioningsuspended bucket the expiration action causes Amazon S3 to create a delete
marker with null as the version ID This delete marker will replace any object version with a null
version ID in the version hierarchy which effectively deletes the object
API Version 20060301
115Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements
In addition Amazon S3 provides the following actions that you can use to manage noncurrent object
versions in a versioned bucket (versioningenabled and versioningsuspended buckets)
• NoncurrentVersionTransition action element – Use this action to specify how long (from the time
the objects became noncurrent) you want the objects to remain in the current storage class before
Amazon S3 transitions them to the specified storage class For more information about transitioning
objects see Supported Transitions (p 110)
• NoncurrentVersionExpiration action element – Use this action to specify how long (from the time
the objects became noncurrent) you want to retain noncurrent object versions before Amazon S3
permanently removes them The deleted object cannot be recovered
This delayed removal of noncurrent objects can be helpful when you need to correct any accidental
deletes or overwrites For example you can configure an expiration rule to delete noncurrent
versions five days after they become noncurrent For example suppose on 112014 1030 AM
UTC you create an object called photogif (version ID 111111) On 122014 1130 AM UTC
you accidentally delete photogif (version ID 111111) which creates a delete marker with a new
version ID (such as version ID 4857693) You now have five days to recover the original version
of photogif (version ID 111111) before the deletion is permanent On 182014 0000 UTC the
lifecycle rule for expiration executes and permanently deletes photogif (version ID 111111) five
days after it became a noncurrent version
Important
Object expiration lifecycle polices do not remove incomplete multipart uploads To remove
incomplete multipart uploads you must use the AbortIncompleteMultipartUpload lifecycle
configuration action that is described later in this section
In addition to the transition and expiration actions you can use the following lifecycle configuration
action to direct Amazon S3 to abort incomplete multipart uploads
• AbortIncompleteMultipartUpload action element – Use this element to set a maximum time (in
days) that you want to allow multipart uploads to remain in progress If the applicable multipart
uploads (determined by the key name prefix specified in the lifecycle rule) are not successfully
completed within the predefined time period Amazon S3 will abort the incomplete multipart
uploads For more information see Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle
Policy (p 167)
How Amazon S3 Calculates How Long an Object Has Been Noncurrent
In a versioningenabled bucket you can have multiple versions of an object there is always one
current version and zero or more noncurrent versions Each time you upload an object the current
version is retained as noncurrent version and the newly added version the successor become current
To determine the number of days an object is noncurrent Amazon S3 looks at when its successor was
created Amazon S3 uses the number of days since its successor was created as the number of days
an object is noncurrent
Restoring Previous Versions of an Object When Using Lifecycle Configurations
As explained in detail in the topic Restoring Previous Versions (p 442) there are two
methods to retrieve previous versions of an object
1 By copying a noncurrent version of the object into the same bucket The copied object
becomes the current version of that object and all object versions are preserved
2 By permanently deleting the current version of the object When you delete the current
object version you in effect turn the noncurrent version into the current version of that
object
When using lifecycle configuration rules with versioningenabled buckets we recommend as a
best practice that you use the first method
API Version 20060301
116Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements
Because of Amazon S3＇s eventual consistency semantics a current version that you
permanently deleted may not disappear until the changes propagate (Amazon S3 may
be unaware of this deletion) And in the meantime the lifecycle you configured to expire
noncurrent objects may permanently remove noncurrent objects including the one you want
to restore So copying the old version as recommended in the first method is the safer
alternative
Lifecycle Rules Based on the Object Age
You can specify a time period in number of days from the creation (or modification) of the objects when
Amazon S3 can take the action
When you specify number of days in the Transition and Expiration actions in a lifecycle
configuration note the following
• It is the number of days since object creation when the action will be taken
• Amazon S3 calculates the time by adding the number of days specified in the rule to the object
creation time and rounding the resulting time to the next day midnight UTC For example if an
object was created at 1152014 1030 AM UTC and you specify 3 days in a transition rule then the
transition date of the object would be calculated as 1192014 0000 UTC
Note
Amazon S3 maintains only the last modified date for each object For example the Amazon
S3 console shows the Last Modified date in the object Properties pane When you initially
create a new object this date reflects the date the object is created If you replace the object
the date will change accordingly So when we use the term creation date it is synonymous
with the term last modified date
When specifying the number of days in the NoncurrentVersionTransition and
NoncurrentVersionExpiration actions in a lifecycle configuration note the following
• It is the number of days from when the version of the object becomes noncurrent (that is since the
object was overwritten or deleted) as the time period for when Amazon S3 will take the action on the
specified object or objects
• Amazon S3 calculates the time by adding the number of days specified in the rule to the time when
the new successor version of the object is created and rounding the resulting time to the next day
midnight UTC For example in your bucket you have a current version of an object that was created
at 112014 1030 AM UTC if the new successor version of the object that replaces the current
version is created at 1152014 1030 AM UTC and you specify 3 days in a transition rule then the
transition date of the object would be calculated as 1192014 0000 UTC
Lifecycle Rules Based on a Specific Date
When specifying an action in a lifecycle configuration you can specify a date when you want Amazon
S3 to take the action The datebased rules trigger action on all objects created on or before this
date For example a rule to transition to GLACIER on 6302015 will transition all objects created on
or before this date (note that the rule applies every day after the specified date and not just on the
specified date as long as the rule is in effect)
Note
You cannot create the datebased rule using the AWS Management Console but you can
view disable or delete such rules
Examples of Lifecycle Configuration
This section provides examples of lifecycle configuration Each example shows how you can specify
XML in each of the example scenarios
API Version 20060301
117Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements
Example 1 Specify a Lifecycle Rule for a Subset of Objects in a Bucket
The following lifecycle configuration rule is applied to a subset of objects with key name prefix
projectdocs The rule specifies two actions requesting Amazon S3 the following
• Transition objects to the GLACIER storage class 365 days (one year) after creation
• Delete objects (the Expiration action) objects 3650 days (10 years) after creation


Transition and Expiration Rule
projectdocs
Enabled

365
GLACIER


3650



Instead of specifying object age in terms of days after creation you can specify a date for each action
however you cannot use both Date and Days in the same rule
Example 2 Specify a Lifecycle Rule that Applies to All Objects in the Bucket
If you specify an empty Prefix in a lifecycle rule it applies to all objects in the bucket Suppose you
create a bucket only for archiving objects to GLACIER You can set lifecycle configuration requesting
Amazon S3 to transition objects to the GLACIER storage class immediately after creation as shown
The lifecycle configuration defines one rule with an empty Prefix The rule specifies a Transition
action requesting Amazon S3 to transition objects to the GLACIER storage class 0 days after creation
in which case objects are eligible for archival to Amazon Glacier at midnight UTC following creation


Archive all object sameday upon creation

Enabled

0
GLACIER



Example 3 Disable a Lifecycle Rule
You can temporarily disable a lifecycle rule The following lifecycle configuration specifies two rules
however one of them is disabled Amazon S3 will not perform any action specified in a rule that is
disabled


API Version 20060301
118Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements
30 days log objects expire rule
logs
Enabled

0
GLACIER



1 year documents expire rule
documents
Disabled

0
GLACIER



Example 4 Tiering Down Storage Class Over Object Lifetime
In this example you leverage lifecycle configuration to tierdown the storage class of objects over
their lifetime This tiering down can help reduce storage costs For more information about pricing see
Amazon S3 Pricing
The following lifecycle configuration specifies a rule that applies to objects with key name prefix logs
The rule specifies the following actions
• Two transition actions
• Transition objects to the STANDARD_IA storage class 30 days after creation
• Transition objects to the GLACIER storage class 90 days after creation
• An expiration action directing Amazon S3 to delete objects a year after creation


exampleid
logs
Enabled

30
STANDARD_IA


90
GLACIER


365



Note
You can use one rule to describe all lifecycle actions if all actions apply to the same set of
objects (identified by the prefix) Otherwise you can add multiple rules each specify a different
key name prefix
API Version 20060301
119Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements
Example 5 Specify Multiple Rules
You can specify multiple rules if you want different lifecycle actions of different objects The following
lifecycle configuration has two rules
• Rule 1 applies to objects with key name prefix classA It directs Amazon S3 to transition objects to
the GLACIER storage class one year after creation and expire these objects 10 years after creation
• Rule 2 applies to objects with key name prefix classB It directs Amazon S3 to transition objects to
the STANDARD_IA storage class 90 days after creation and delete then one year after creation


ClassADocRule
classA
Enabled

365
GLACIER


3650



ClassBDocRule
classB
Enabled

90
STANDARD_IA


365



Example 6 Specify Multiple Rules with Overlapping Prefixes
In the following example you have two rules that specify overlapping prefixes
• First rule specifies empty prefix indicating all objects in the bucket
• Second rule specifies subset of objects in the bucket with key name prefix logs
These overlapping prefixes are fine there is no conflict Rule 1 requests Amazon S3 to delete all
objects one year after creation and Rule 2 requests Amazon S3 to transition subset of objects to the
STANDARD_IA storage class 30 days after creation


Rule 1

Enabled
API Version 20060301
120Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements

365



Rule 2
logs
Enabled

STANDARD_IA
30



Example 7 Specify a Lifecycle Rule for a VersioningEnable Bucket
Suppose you have a versioningenabled bucket which means that for each object you have a
current version and zero or more noncurrent versions You want to maintain one year worth of
history and then delete the noncurrent versions For more information about versioning see Object
Versioning (p 106)
Also you want to save storage costs by moving noncurrent versions to GLACIER 30 days after they
become noncurrent (assuming cold data for which you will not need realtime access) In addition you
also expect frequency of access of the current versions to diminish 90 days after creation so you might
choose to move these objects to the STANDARD_IA storage class


samplerule

Enabled

90
STANDARD_IA


30
GLACIER


365



Example 8 Removing Expired Object Delete Markers
A versioningenabled bucket has one current version and one or more noncurrent versions for each
object When you delete an object note that
• If you don＇t specify a version ID in your delete request Amazon S3 adds a delete marker instead of
deleting the object The current object version become noncurrent and the delete marker becomes
the current version
• If you specify a version ID in your delete request Amazon S3 deletes the object version permanently
(a delete marker is not created)
• A delete marker with zero noncurrent versions is referred to as the expired object delete marker
API Version 20060301
121Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements
This example shows a scenario that can create expired object delete markers in your bucket and how
you can use lifecycle configuration to direct Amazon S3 to remove the expired object delete markers
Suppose you write a lifecycle policy that specifies the NoncurrentVersionExpiration action to
remove the noncurrent versions 30 days after they become noncurrent as shown




30



Note that the NoncurrentVersionExpiration action does not apply to the current object versions
it only removes noncurrent versions
For current object versions you have the following options to manage their lifetime depending on
whether or not the current object versions follow a welldefined lifecycle
• Current object versions follow a welldefined lifecycle
In this case you can use lifecycle policy with the Expiration action to direct Amazon S3 to remove
current versions as shown in the following example




60


30



Amazon S3 removes current versions 60 days after they are created by adding a delete marker for
each of the current object versions This makes the current version noncurrent and the delete marker
becomes the current version (see Using Versioning (p 423))
The NoncurrentVersionExpiration action in the same lifecycle configuration removes
noncurrent objects 30 days after they become noncurrent Thus all object versions are removed and
you have expired object delete markers but Amazon S3 will detect and remove expired object delete
markers for you
• Current object versions don＇t have a welldefined lifecycle
In this case you might remove the objects manually when you don＇t need them creating
a delete marker with one or more noncurrent versions If lifecycle configuration with
NoncurrentVersionExpiration action removes all the noncurrent versions you now have expired
object delete markers
Specifically for this scenario Amazon S3 lifecycle configuration provides Expiration action where
you can request S3 to remove the expired object delete markers

API Version 20060301
122Amazon Simple Storage Service Developer Guide
Lifecycle Configuration Elements



true


30



By setting the ExpiredObjectDeleteMarker element to true in the Expiration action you direct
Amazon S3 to remove expired object delete markers Amazon S3 will remove an expired object delete
marker no sooner than 48 hours after the object expired
The following putbucketlifecycle CLI command adds the lifecycle configuration for the
specified bucket
aws s3api putbucketlifecycle ＼
bucket bucketname ＼
lifecycleconfiguration filenamecontaininglifecycleconfiguration
Note
If you have trouble getting the following test procedure to work make sure that you have the
latest version of the AWS CLI installed
To test the CLI command do the following
1 Set up the AWS CLI For instructions see Set Up the AWS CLI (p 562)
2 Save the following example lifecycle configuration in a file (lifecyclejson) The example policy
specifies empty prefix so it applies to all objects You could specify a key name prefix to limit
action to a subset of objects
{
Rules [
{
Status Enabled
Prefix
Expiration {
ExpiredObjectDeleteMarker true
}
ID TestOnly
}
]
}
3 Run the following CLI command to set lifecycle configuration on your bucket
aws s3api putbucketlifecycle ＼
bucket bucketname ＼
lifecycleconfiguration filelifecyclejson
4 To verify retrieve the lifecycle configuration using the getbucketlifecycle CLI command
aws s3api getbucketlifecycle ＼
API Version 20060301
123Amazon Simple Storage Service Developer Guide
GLACIER Storage Class Additional Considerations
bucket bucketname
5 To delete the lifecycle configuration use the deletebucketlifecycle CLI command
aws s3api deletebucketlifecycle ＼
bucket bucketname
GLACIER Storage Class Additional Lifecycle
Configuration Considerations
Topics
• Cost Considerations (p 124)
• Restoring Archived Objects (p 125)
For objects that you do not need to access in real time Amazon S3 also offers the GLACIER storage
class This storage class is suitable for objects stored primarily for archival purposes For more
information see Storage Classes (p 103)
The lifecycle configuration enables a oneway transition to the GLACIER storage class To change the
storage class from GLACIER to other storage classes you must restore the object as discussed in the
following section and then make a copy of the restored object
Cost Considerations
If you are planning to archive infrequently accessed data for a period of months or years the GLACIER
storage class will usually reduce your storage costs You should however consider the following in
order to ensure that the GLACIER storage class is appropriate for you
• Storage overhead charges – When you transition objects to the GLACIER storage class a fixed
amount of storage is added to each object to accommodate metadata for managing the object
• For each object archived to Amazon Glacier Amazon S3 uses 8 KB of storage for the name of
the object and other metadata Amazon S3 stores this metadata so that you can get a realtime
list of your archived objects by using the Amazon S3 API (see Get Bucket (List Objects)) You are
charged standard Amazon S3 rates for this additional storage
• For each archived object Amazon Glacier adds 32 KB of storage for index and related metadata
This extra data is necessary to identify and restore your object You are charged Amazon Glacier
rates for this additional storage
If you are archiving small objects consider these storage charges Also consider aggregating a large
number of small objects into a smaller number of large objects in order to reduce overhead costs
• Number of days you plan to keep objects archived – Amazon Glacier is a longterm archival
solution Deleting data that is archived to Amazon Glacier is free if the objects you delete are
archived for three months or longer If you delete or overwrite an object within three months of
archiving it Amazon S3 charges a prorated early deletion fee
• Glacier archive request charges – Each object that you transition to the GLACIER storage class
constitutes one archive request There is a cost for each such request If you plan to transition a
large number of objects consider the request costs
• Glacier data restore charges – Amazon Glacier is designed for longterm archival of data that you
will access infrequently Data restore charges are based on how quickly you restore data which is
measured as your peak billable restore rate in GBhr for the entire month Within a month you are
charged only for the peak billable restore rate and there is no charge for restoring data at less than
API Version 20060301
124Amazon Simple Storage Service Developer Guide
Specifying a Lifecycle Configuration
the monthly peak billable restore rate Before initiating a large restore carefully review the pricing
FAQ to determine how you will be billed for restoring data
When you archive objects to Amazon Glacier by using object lifecycle management Amazon S3
transitions these objects asynchronously There may be a delay between the transition date in the
lifecycle configuration rule and the date of the physical transition You are charged Amazon Glacier
prices based on the transition date specified in the rule
The Amazon S3 product detail page provides pricing information and example calculations for
archiving Amazon S3 objects For more information see the following topics
• How is my storage charge calculated for Amazon S3 objects archived to Amazon Glacier
• How am I charged for deleting objects from Amazon Glacier that are less than 3 months old
• Amazon S3 Pricing for storage costs for the Standard and GLACIER storage classes This page also
provides Glacier Archive Request costs
• How will I be charged for restoring large amounts of data from Amazon Glacier
Restoring Archived Objects
Archived objects are not accessible in realtime You must first initiate a restore request and then wait
until a temporary copy of the object is available for the duration that you specify in the request Restore
jobs typically complete in three to five hours so it is important that you archive only objects that you will
not need to access in real time
After you receive a temporary copy of the restored object the object＇s storage class remains GLACIER
(a GET or HEAD request will return GLACIER as the storage class) Note that when you restore an
archive you are paying for both the archive (GLACIER rate) and a copy you restored temporarily (RRS
rate) For information about pricing see Amazon S3 Pricing
You can restore an object copy programmatically or by using the Amazon S3 console Amazon S3 will
process only one restore request at a time per object You can use both the console and the Amazon
S3 API to check the restoration status and to find out when Amazon S3 will delete the restored copy
Restoring GLACIER Objects by Using Amazon S3 Console
For information about restoring archived objects stored using the GLACIER storage class by using the
Amazon S3 console see Restore an Archived Object Using the Amazon S3 Console (p 259)
Restoring GLACIER Objects Programmatically
You can restore GLACIER objects programmatically directly from your application by using either the
AWS SDKs or the Amazon S3 API When you use the AWS SDKs the Amazon S3 API provides
appropriate wrapper libraries to simplify your programming tasks however when the request is sent
over the wire the SDK sends the preceding XML in the request body For information about restoring
objects programmatically see Restoring Archived Objects (p 259)
Specifying a Lifecycle Configuration
Topics
• Manage an Object＇s Lifecycle Using the AWS Management Console (p 126)
• Manage Object Lifecycle Using the AWS SDK for Java (p 127)
• Manage Object Lifecycle Using the AWS SDK for NET (p 129)
• Manage an Object＇s Lifecycle Using the AWS SDK for Ruby (p 131)
• Manage Object Lifecycle Using the REST API (p 131)
API Version 20060301
125Amazon Simple Storage Service Developer Guide
Specifying a Lifecycle Configuration
You can set a lifecycle configuration on a bucket either by programmatically using the Amazon S3
API or by using the Amazon S3 console When you add a lifecycle configuration to a bucket there is
usually some lag before a new or updated lifecycle configuration is fully propagated to all the Amazon
S3 systems Expect a delay of a few minutes before the lifecycle configuration fully takes effect This
delay can also occur when you delete a lifecycle configuration
When you disable or delete a lifecycle rule after a small delay Amazon S3 stops scheduling new
objects for deletion or transition Any objects that were already scheduled will be unscheduled and will
not be deleted or transitioned
Note
When you add a lifecycle configuration to a bucket the configuration rules apply to
both existing objects and objects that you add later For example if you add a lifecycle
configuration rule with an expiration action today that causes objects with a specific prefix to
expire 30 days after creation Amazon S3 will queue for removal any existing objects that are
more than 30 days old
There may be a lag between when the lifecycle configuration rules are satisfied and when the action
triggered by satisfying the rule is taken However changes in billing happen as soon as the lifecycle
configuration rule is satisfied even if the action is not yet taken One example is you are not charged for
storage after the object expiration time even if the object is not deleted immediately Another example
is you are charged Amazon Glacier storage rates as soon as the object transition time elapses even if
the object is not transitioned to Amazon Glacier immediately
For information about specifying the lifecycle by using the Amazon S3 console or programmatically by
using AWS SDKs click the links provided at the beginning of this topic
Manage an Object＇s Lifecycle Using the AWS Management
Console
You can specify lifecycle rules on a bucket using the Amazon S3 console In the console the bucket
Properties provides a Lifecycle tab as shown in the following example screen shot For more
information see Object Lifecycle Management (p 109)
StepbyStep Instructions
For instructions on how to setup lifecycle rules using the AWS Management Console see Managing
Lifecycle Configuration in the Amazon S3 Console User Guide
API Version 20060301
126Amazon Simple Storage Service Developer Guide
Specifying a Lifecycle Configuration
Manage Object Lifecycle Using the AWS SDK for Java
You can use the AWS SDK for Java to manage lifecycle configuration on a bucket For more
information about managing lifecycle configuration see Object Lifecycle Management (p 109)
The example code in this topic does the following
• Add lifecycle configuration with two rules
• A rule that applies to objects with the glacierobjects key name prefix The rule specifies a
transition action that directs Amazon S3 to transition these objects to the GLACIER storage class
Because the number of days specified is 0 the objects become eligible for archival immediately
• A rule that applies to objects with the projectdocs key name prefix The rule specifies two
transition actions directing Amazon S3 to first transition objects to the STANDARD_IA (IA for
infrequent access) storage class 30 days after creation and then transition to the GLACIER
storage class 365 days after creation The rule also specifies expiration action directing Amazon
S3 to delete these objects 3650 days after creation
• Retrieves the lifecycle configuration
• Updates the configuration by adding another rule that applies to objects with the
YearlyDocuments key name prefix The expiration action in this rule directs Amazon S3 to delete
these objects 3650 days after creation
Note
When you add a lifecycle configuration to a bucket any existing lifecycle configuration
is replaced To update existing lifecycle configuration you must first retrieve the existing
lifecycle configuration make changes and then add the revised lifecycle configuration to the
bucket
API Version 20060301
127Amazon Simple Storage Service Developer Guide
Specifying a Lifecycle Configuration
Example Java Code Example
The following Java code example provides a complete code listing that adds updates and deletes
a lifecycle configuration to a bucket You need to update the code and provide your bucket name to
which the code can add the example lifecycle configuration
For instructions on how to create and test a working sample see Testing the Java Code
Examples (p 564)
import javaioIOException
import javautilArrayList
import javautilArrays
import javautilCalendar
import javautilList
import javautilTimeZone
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelAmazonS3Exception
import comamazonawsservicess3modelBucketLifecycleConfiguration
import
comamazonawsservicess3modelBucketLifecycleConfigurationTransition
import comamazonawsservicess3modelStorageClass
public class LifecycleConfiguration {
public static String bucketName *** Provide bucket name ***
public static AmazonS3Client s3Client
public static void main(String[] args) throws IOException {
s3Client new AmazonS3Client(new ProfileCredentialsProvider())
try {

BucketLifecycleConfigurationRule rule1
new BucketLifecycleConfigurationRule()
withId(Archive immediately rule)
withPrefix(glacierobjects)
addTransition(new Transition()
withDays(0)
withStorageClass(StorageClassGlacier))
withStatus(BucketLifecycleConfigurationENABLEDtoString())
BucketLifecycleConfigurationRule rule2
new BucketLifecycleConfigurationRule()
withId(Archive and then delete rule)
withPrefix(projectdocs)
addTransition(new Transition()
withDays(30)

withStorageClass(StorageClassStandardInfrequentAccess))
addTransition(new Transition()
withDays(365)

withStorageClass(StorageClassGlacier))
withExpirationInDays(3650)
withStatus(BucketLifecycleConfigurationENABLEDtoString())
BucketLifecycleConfiguration configuration
new BucketLifecycleConfiguration()
withRules(ArraysasList(rule1 rule2))

Save configuration
s3ClientsetBucketLifecycleConfiguration(bucketName
configuration)

Retrieve configuration
configuration
s3ClientgetBucketLifecycleConfiguration(bucketName)

Add a new rule
configurationgetRules()add(
new BucketLifecycleConfigurationRule()
withId(NewRule)
withPrefix(YearlyDocuments)
withExpirationInDays(3650)
withStatus(BucketLifecycleConfiguration
ENABLEDtoString())
)
Save configuration
s3ClientsetBucketLifecycleConfiguration(bucketName
configuration)

Retrieve configuration
configuration
s3ClientgetBucketLifecycleConfiguration(bucketName)

Verify there are now three rules
configuration
s3ClientgetBucketLifecycleConfiguration(bucketName)
Systemoutformat(Expected # of rules 3 found s＼n
configurationgetRules()size())
Systemoutprintln(Deleting lifecycle configuration Next we
verify deletion)
Delete configuration
s3ClientdeleteBucketLifecycleConfiguration(bucketName)

Retrieve nonexistent configuration
configuration
s3ClientgetBucketLifecycleConfiguration(bucketName)
String s (configuration null) No configuration found
Configuration found
Systemoutprintln(s)
} catch (AmazonS3Exception amazonS3Exception) {
Systemoutformat(An Amazon S3 error occurred Exception s
amazonS3ExceptiontoString())
} catch (Exception ex) {
Systemoutformat(Exception s extoString())
}
}
}
API Version 20060301
128Amazon Simple Storage Service Developer Guide
Specifying a Lifecycle Configuration
Manage Object Lifecycle Using the AWS SDK for NET
You can use the AWS SDK for NET to manage lifecycle configuration on a bucket For more
information about managing lifecycle configuration see Object Lifecycle Management (p 109) The
example code in this topic does the following
• Add lifecycle configuration with two rules
• A rule that applies to objects with the glacierobjects key name prefix The rule specifies a
transition action that directs Amazon S3 to transition these objects to the GLACIER storage class
Because the number of days specified is 0 the objects become eligible for archival immediately
• A rule that applies to objects with the projectdocs key name prefix The rule specifies two
transition actions directing Amazon S3 to first transition objects to the STANDARD_IA (IA for
infrequent access) storage class 30 days after creation and then transition to the GLACIER
storage class 365 days after creation The rule also specifies expiration action directing Amazon
S3 to delete these objects 3650 days after creation
• Retrieves the lifecycle configuration
• Updates the configuration by adding another rule that applies to objects with the
YearlyDocuments key name prefix The expiration action in this rule directs Amazon S3 to delete
these objects 3650 days after creation
Note
When you add a lifecycle configuration to a bucket any existing lifecycle configuration
is replaced To update existing lifecycle configuration you must first retrieve the existing
lifecycle configuration make changes and then add the revised lifecycle configuration to the
bucket
API Version 20060301
129Amazon Simple Storage Service Developer Guide
Specifying a Lifecycle Configuration
Example NET Code Example
The following C# code example provides complete code listing that adds updates and deletes a
lifecycle configuration to a bucket You need to update the code and provide your bucket name to
which the code can add the example lifecycle configuration
Note
The following code works with the latest version of the NET SDK
For instructions on how to create and test a working sample see Running the Amazon S3 NET Code
Examples (p 566)
using System
using SystemCollectionsGeneric
using SystemDiagnostics
using AmazonS3
using AmazonS3Model
namespace awsamazoncoms3documentation
{
class LifeCycleTest
{
static string bucketName *** provide bucket name ***
public static void Main(string[] args)
{
try
{
using (var client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
var lifeCycleConfiguration new LifecycleConfiguration()
{
Rules new List
{
new LifecycleRule
{
Id Archive immediately rule
Prefix glacierobjects
Status LifecycleRuleStatusEnabled
Transitions new List
{
new LifecycleTransition
{
Days 0
StorageClass
S3StorageClassGlacier
}
}
}
new LifecycleRule
{
Id Archive and then delete rule
Prefix projectdocs
Status LifecycleRuleStatusEnabled
Transitions new List
{
new LifecycleTransition
{
Days 30
StorageClass
S3StorageClassStandardInfrequentAccess
}
new LifecycleTransition
{
Days 365
StorageClass S3StorageClassGlacier
}
}
Expiration new LifecycleRuleExpiration()
{
Days 3650
}
}
}
}
Add the configuration to the bucket
PutLifeCycleConfiguration(client
lifeCycleConfiguration)
Retrieve an existing configuration
lifeCycleConfiguration
GetLifeCycleConfiguration(client)
Add a new rule
lifeCycleConfigurationRulesAdd(new LifecycleRule
{
Id NewRule
Prefix YearlyDocuments
Expiration new LifecycleRuleExpiration()
{
Days 3650
}
})
Add the configuration to the bucket
PutLifeCycleConfiguration(client
lifeCycleConfiguration)
Verify that there are now three rules
lifeCycleConfiguration
GetLifeCycleConfiguration(client)
ConsoleWriteLine(Expected # of rulest3 found{0}
lifeCycleConfigurationRulesCount)
Delete the configuration
DeleteLifecycleConfiguration(client)
Retrieve a nonexistent configuration
lifeCycleConfiguration
GetLifeCycleConfiguration(client)
DebugAssert(lifeCycleConfiguration null)
}
ConsoleWriteLine(Example complete To continue click
Enter)
ConsoleReadKey()
}
catch (AmazonS3Exception amazonS3Exception)
{
ConsoleWriteLine(S3 error occurred Exception +
amazonS3ExceptionToString())
}
catch (Exception e)
{
ConsoleWriteLine(Exception + eToString())
}
}
static void PutLifeCycleConfiguration(IAmazonS3 client
LifecycleConfiguration configuration)
{
PutLifecycleConfigurationRequest request new
PutLifecycleConfigurationRequest
{
BucketName bucketName
Configuration configuration
}
var response clientPutLifecycleConfiguration(request)
}
static LifecycleConfiguration GetLifeCycleConfiguration(IAmazonS3
client)
{
GetLifecycleConfigurationRequest request new
GetLifecycleConfigurationRequest
{
BucketName bucketName
}
var response clientGetLifecycleConfiguration(request)
var configuration responseConfiguration
return configuration
}
static void DeleteLifecycleConfiguration(IAmazonS3 client)
{
DeleteLifecycleConfigurationRequest request new
DeleteLifecycleConfigurationRequest
{
BucketName bucketName
}
clientDeleteLifecycleConfiguration(request)
}
}
}
API Version 20060301
130Amazon Simple Storage Service Developer Guide
CrossOrigin Resource Sharing (CORS)
Manage an Object＇s Lifecycle Using the AWS SDK for Ruby
You can use the AWS SDK for Ruby to manage lifecycle configuration on a bucket by using the class
AWSS3BucketLifecycleConfiguration For more information about using the AWS SDK for Ruby with
Amazon S3 go to Using the AWS SDK for Ruby Version 2 (p 568) For more information about
managing lifecycle configuration see Object Lifecycle Management (p 109)
Manage Object Lifecycle Using the REST API
You can use the AWS Management Console to set the lifecycle configuration on your bucket If your
application requires it you can also send REST requests directly The following sections in the Amazon
Simple Storage Service API Reference describe the REST API related to the lifecycle configuration
• PUT Bucket lifecycle
• GET Bucket lifecycle
• DELETE Bucket lifecycle
CrossOrigin Resource Sharing (CORS)
Crossorigin resource sharing (CORS) defines a way for client web applications that are loaded in one
domain to interact with resources in a different domain With CORS support in Amazon S3 you can
build rich clientside web applications with Amazon S3 and selectively allow crossorigin access to your
Amazon S3 resources
This section provides an overview of CORS The subtopics describe how you can enable CORS using
the Amazon S3 console or programmatically using the Amazon S3 REST API and the AWS SDKs
Topics
• CrossOrigin Resource Sharing Usecase Scenarios (p 131)
• How Do I Configure CORS on My Bucket (p 132)
• How Does Amazon S3 Evaluate the CORS Configuration On a Bucket (p 134)
• Enabling CrossOrigin Resource Sharing (CORS) (p 134)
• Troubleshooting CORS Issues (p 142)
CrossOrigin Resource Sharing Usecase
Scenarios
The following are example scenarios for using CORS
• Scenario 1 Suppose you are hosting a website in an Amazon S3 bucket named website as
described in Hosting a Static Website on Amazon S3 (p 449) Your users load the website
endpoint httpwebsites3websiteuseast1amazonawscom Now you want to use
JavaScript on the web pages that are stored in this bucket to be able to make authenticated GET
and PUT requests against the same bucket by using the Amazon S3＇s API endpoint for the bucket
websites3amazonawscom A browser would normally block JavaScript from allowing those
requests but with CORS you can configure your bucket to explicitly enable crossorigin requests
from websites3websiteuseast1amazonawscom
• Scenario 2 Suppose you want to host a web font from your S3 bucket Again browsers require a
CORS check (also referred as a preflight check) for loading web fonts so you would configure the
bucket that is hosting the web font to allow any origin to make these requests
API Version 20060301
131Amazon Simple Storage Service Developer Guide
How Do I Configure CORS on My Bucket
How Do I Configure CORS on My Bucket
To configure your bucket to allow crossorigin requests you create a CORS configuration an XML
document with rules that identify the origins that you will allow to access your bucket the operations
(HTTP methods) will support for each origin and other operationspecific information
You can add up to 100 rules to the configuration You add the XML document as the cors subresource
to the bucket either programmatically or by using the Amazon S3 console For more information see
Enabling CrossOrigin Resource Sharing (CORS) (p 134)
The following example cors configuration has three rules which are specified as CORSRule elements
• The first rule allows crossorigin PUT POST and DELETE requests from the https
wwwexample1com origin The rule also allows all headers in a preflight OPTIONS request through
the AccessControlRequestHeaders header In response to any preflight OPTIONS request
Amazon S3 will return any requested headers
• The second rule allows same crossorigin requests as the first rule but the rule applies to another
origin httpswwwexample2com
• The third rule allows crossorigin GET requests from all origins The ＇*＇ wildcard character refers to all
origins


httpwwwexample1com
PUT
POST
DELETE
*


httpwwwexample2com
PUT
POST
DELETE
*


*
GET


The CORS configuration also allows optional configuration parameters as shown in the following
CORS configuration In this example the following CORS configuration allows crossorigin PUT and
POST requests from the httpwwwexamplecom origin


httpwwwexamplecom
PUT
POST
API Version 20060301
132Amazon Simple Storage Service Developer Guide
How Do I Configure CORS on My Bucket
DELETE
*
3000
xamzserversideencryption<
ExposeHeader>
xamzrequestid<
ExposeHeader>
xamzid2


The CORSRule element in the preceding configuration includes the following optional elements
• MaxAgeSeconds—Specifies the amount of time in seconds (in this example 3000) that the browser
will cache an Amazon S3 response to a preflight OPTIONS request for the specified resource By
caching the response the browser does not have to send preflight requests to Amazon S3 if the
original request is to be repeated
• ExposeHeader—Identifies the response headers (in this example xamzserverside
encryption xamzrequestid and xamzid2) that customers will be able to access from
their applications (for example from a JavaScript XMLHttpRequest object)
AllowedMethod Element
In the CORS configuration you can specify the following values for the AllowedMethod element
• GET
• PUT
• POST
• DELETE
• HEAD
AllowedOrigin Element
In the AllowedOrigin element you specify the origins that you want to allow crossdomain requests
from for example httpwwwexamplecom The origin string can contain at most one * wildcard
character such as http*examplecom You can optionally specify * as the origin to enable all
the origins to send crossorigin requests You can also specify https to enable only secure origins
AllowedHeader Element
The AllowedHeader element specifies which headers are allowed in a preflight request through
the AccessControlRequestHeaders header Each header name in the AccessControl
RequestHeaders header must match a corresponding entry in the rule Amazon S3 will send only
the allowed headers in a response that were requested For a sample list of headers that can be used
in requests to Amazon S3 go to Common Request Headers in the Amazon Simple Storage Service
API Reference guide
Each AllowedHeader string in the rule can contain at most one * wildcard character For example
xamz* will enable all Amazonspecific headers
ExposeHeader Element
Each ExposeHeader element identifies a header in the response that you want customers to be able
to access from their applications (for example from a JavaScript XMLHttpRequest object) For a list
API Version 20060301
133Amazon Simple Storage Service Developer Guide
How Does Amazon S3 Evaluate the
CORS Configuration On a Bucket
of common Amazon S3 response headers go to Common Response Headers in the Amazon Simple
Storage Service API Reference guide
MaxAgeSeconds Element
The MaxAgeSeconds element specifies the time in seconds that your browser can cache the response
for a preflight request as identified by the resource the HTTP method and the origin
How Does Amazon S3 Evaluate the CORS
Configuration On a Bucket
When Amazon S3 receives a preflight request from a browser it evaluates the CORS configuration for
the bucket and uses the first CORSRule rule that matches the incoming browser request to enable a
crossorigin request For a rule to match the following conditions must be met
• The request＇s Origin header must match an AllowedOrigin element
• The request method (for example GET or PUT) or the AccessControlRequestMethod
header in case of a preflight OPTIONS request must be one of the AllowedMethod elements
• Every header listed in the request＇s AccessControlRequestHeaders header on the preflight
request must match an AllowedHeader element
Note
The ACLs and policies continue to apply when you enable CORS on the bucket
Enabling CrossOrigin Resource Sharing (CORS)
Enable crossorigin resource sharing by setting a CORS configuration on your bucket using the AWS
Management Console the REST API or the AWS SDKs
Topics
• Enabling CrossOrigin Resource Sharing (CORS) Using the AWS Management Console (p 134)
• Enabling CrossOrigin Resource Sharing (CORS) Using the AWS SDK for Java (p 134)
• Enabling CrossOrigin Resource Sharing (CORS) Using the AWS SDK for NET (p 138)
• Enabling CrossOrigin Resource Sharing (CORS) Using the REST API (p 142)
Enabling CrossOrigin Resource Sharing (CORS) Using the
AWS Management Console
You can use the AWS Management Console to set a CORS configuration on your bucket For
instructions see Editing Bucket Permissions in the Amazon S3 Console User Guide
Enabling CrossOrigin Resource Sharing (CORS) Using the
AWS SDK for Java
You can use the AWS SDK for Java to manage crossorigin resource sharing (CORS) for a bucket For
more information about CORS see CrossOrigin Resource Sharing (CORS) (p 131)
This section provides sample code snippets for following tasks followed by a complete example
program demonstrating all tasks
API Version 20060301
134Amazon Simple Storage Service Developer Guide
Enabling CORS
• Creating an instance of the Amazon S3 client class
• Creating and adding a CORS configuration to a bucket
• Updating an existing CORS configuration
CrossOrigin Resource Sharing Methods
AmazonS3Client() Constructs an AmazonS3Client object
setBucketCrossOriginConfiguration()Sets the CORS configuration that to be applied to the bucket If
a configuration already exists for the specified bucket the new
configuration will replace the existing one
getBucketCrossOriginConfiguration()Retrieves the CORS configuration for the specified bucket If no
configuration has been set for the bucket the Configuration header
in the response will be null
deleteBucketCrossOriginConfiguration()Deletes the CORS configuration for the specified bucket
For more information about the AWS SDK for Java API go to AWS SDK for Java API Reference
Creating an Instance of the Amazon S3 Client Class
The following snippet creates a new AmazonS3Client instance for a class called CORS_JavaSDK
This example retrieves the values for accessKey and secretKey from the AwsCredentialsproperties
file
AmazonS3Client client
client new AmazonS3Client(new ProfileCredentialsProvider())
Creating and Adding a CORS Configuration to a Bucket
To add a CORS configuration to a bucket
1 Create a CORSRule object that describes the rule
2 Create a BucketCrossOriginConfiguration object and then add the rule to the configuration
object
3 Add the CORS configuration to the bucket by calling the
clientsetBucketCrossOriginConfiguration method
The following snippet creates two rules CORSRule1 and CORSRule2 and then adds each rule to the
rules array By using the rules array it then adds the rules to the bucket bucketName
Add a sample configuration
BucketCrossOriginConfiguration configuration new
BucketCrossOriginConfiguration()
List rules new ArrayList()
CORSRule rule1 new CORSRule()
withId(CORSRule1)
withAllowedMethods(ArraysasList(new CORSRuleAllowedMethods[] {
CORSRuleAllowedMethodsPUT CORSRuleAllowedMethodsPOST
CORSRuleAllowedMethodsDELETE}))
API Version 20060301
135Amazon Simple Storage Service Developer Guide
Enabling CORS
withAllowedOrigins(ArraysasList(new String[] {http
*examplecom}))
CORSRule rule2 new CORSRule()
withId(CORSRule2)
withAllowedMethods(ArraysasList(new CORSRuleAllowedMethods[] {
CORSRuleAllowedMethodsGET}))
withAllowedOrigins(ArraysasList(new String[] {*}))
withMaxAgeSeconds(3000)
withExposedHeaders(ArraysasList(new String[] {xamzserverside
encryption}))
configurationsetRules(ArraysasList(new CORSRule[] {rule1 rule2}))
Save the configuration
clientsetBucketCrossOriginConfiguration(bucketName configuration)
Updating an Existing CORS Configuration
To update an existing CORS configuration
1 Get a CORS configuration by calling the clientgetBucketCrossOriginConfiguration
method
2 Update the configuration information by adding or deleting rules to the list of rules
3 Add the configuration to a bucket by calling the
clientgetBucketCrossOriginConfiguration method
The following snippet gets an existing configuration and then adds a new rule with the ID NewRule
Get configuration
BucketCrossOriginConfiguration configuration
clientgetBucketCrossOriginConfiguration(bucketName)

Add new rule
CORSRule rule3 new CORSRule()
withId(CORSRule3)
withAllowedMethods(ArraysasList(new CORSRuleAllowedMethods[] {
CORSRuleAllowedMethodsHEAD}))
withAllowedOrigins(ArraysasList(new String[] {httpwwwexamplecom}))
List rules configurationgetRules()
rulesadd(rule3)
configurationsetRules(rules)
Save configuration
clientsetBucketCrossOriginConfiguration(bucketName configuration)
API Version 20060301
136Amazon Simple Storage Service Developer Guide
Enabling CORS
Example Program Listing
The following Java program incorporates the preceding tasks
For information about creating and testing a working sample see Testing the Java Code
Examples (p 564)
import javaioIOException
import javautilArrayList
import javautilArrays
import javautilList
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelBucketCrossOriginConfiguration
import comamazonawsservicess3modelCORSRule
public class Cors {
**
* @param args
* @throws IOException
*
public static AmazonS3Client client
public static String bucketName ***provide bucket name***

public static void main(String[] args) throws IOException {
client new AmazonS3Client(new ProfileCredentialsProvider())
Create a new configuration request and add two rules
BucketCrossOriginConfiguration configuration new
BucketCrossOriginConfiguration()

List rules new ArrayList()

CORSRule rule1 new CORSRule()
withId(CORSRule1)
withAllowedMethods(ArraysasList(new CORSRuleAllowedMethods[]
{
CORSRuleAllowedMethodsPUT
CORSRuleAllowedMethodsPOST CORSRuleAllowedMethodsDELETE}))
withAllowedOrigins(ArraysasList(new String[] {http
*examplecom}))

CORSRule rule2 new CORSRule()
withId(CORSRule2)
withAllowedMethods(ArraysasList(new CORSRuleAllowedMethods[] {
CORSRuleAllowedMethodsGET}))
withAllowedOrigins(ArraysasList(new String[] {*}))
withMaxAgeSeconds(3000)
withExposedHeaders(ArraysasList(new String[] {xamzserverside
encryption}))

configurationsetRules(ArraysasList(new CORSRule[] {rule1 rule2}))

Add the configuration to the bucket
clientsetBucketCrossOriginConfiguration(bucketName configuration)
Retrieve an existing configuration
configuration clientgetBucketCrossOriginConfiguration(bucketName)
printCORSConfiguration(configuration)

Add a new rule
CORSRule rule3 new CORSRule()
withId(CORSRule3)
withAllowedMethods(ArraysasList(new CORSRuleAllowedMethods[] {
CORSRuleAllowedMethodsHEAD}))
withAllowedOrigins(ArraysasList(new String[] {http
wwwexamplecom}))
rules configurationgetRules()
rulesadd(rule3)
configurationsetRules(rules)
clientsetBucketCrossOriginConfiguration(bucketName configuration)
Systemoutformat(Added another rule s＼n rule3getId())

Verify that the new rule was added
configuration clientgetBucketCrossOriginConfiguration(bucketName)
Systemoutformat(Expected # of rules 3 found s
configurationgetRules()size())
Delete the configuration
clientdeleteBucketCrossOriginConfiguration(bucketName)

Try to retrieve configuration
configuration clientgetBucketCrossOriginConfiguration(bucketName)
Systemoutprintln(＼nRemoved CORS configuration)
printCORSConfiguration(configuration)
}

static void printCORSConfiguration(BucketCrossOriginConfiguration
configuration)
{
if (configuration null)
{
Systemoutprintln(＼nConfiguration is null)
return
}
Systemoutformat(＼nConfiguration has s rules＼n
configurationgetRules()size())
for (CORSRule rule configurationgetRules())
{
Systemoutformat(Rule ID s＼n rulegetId())
Systemoutformat(MaxAgeSeconds s＼n
rulegetMaxAgeSeconds())
Systemoutformat(AllowedMethod s＼n
rulegetAllowedMethods()toArray())
Systemoutformat(AllowedOrigins s＼n
rulegetAllowedOrigins())
Systemoutformat(AllowedHeaders s＼n
rulegetAllowedHeaders())
Systemoutformat(ExposeHeader s＼n
rulegetExposedHeaders())
}
}
}
API Version 20060301
137Amazon Simple Storage Service Developer Guide
Enabling CORS
Enabling CrossOrigin Resource Sharing (CORS) Using the
AWS SDK for NET
You can use the AWS SDK for NET to manage crossorigin resource sharing (CORS) for a bucket
For more information about CORS see CrossOrigin Resource Sharing (CORS) (p 131)
This section provides sample code for the tasks in the following table followed by a complete example
program listing
Managing CrossOrigin Resource Sharing
1 Create an instance of the AmazonS3Client class
2 Create a new CORS configuration
3 Retrieve and modify an existing CORS configuration
4 Add the configuration to the bucket
CrossOrigin Resource Sharing Methods
AmazonS3Client() Constructs AmazonS3Client with the credentials defined in the
Appconfig file
PutCORSConfiguration() Sets the CORS configuration that should be applied to the bucket
If a configuration already exists for the specified bucket the new
configuration will replace the existing one
GetCORSConfiguration() Retrieves the CORS configuration for the specified bucket If no
configuration has been set for the bucket the Configuration header
in the response will be null
DeleteCORSConfiguration() Deletes the CORS configuration for the specified bucket
For more information about the AWS SDK for NET API go to Using the AWS SDK for NET (p 565)
Creating an Instance of the AmazonS3 Class
The following sample creates an instance of the AmazonS3Client class
static IAmazonS3 client
using (client new AmazonS3Client(AmazonRegionEndpointUSWest2))
Adding a CORS Configuration to a Bucket
To add a CORS configuration to a bucket
1 Create a CORSConfiguration object describing the rule
2 Create a PutCORSConfigurationRequest object that provides the bucket name and the CORS
configuration
3 Add the CORS configuration to the bucket by calling clientPutCORSConfiguration
The following sample creates two rules CORSRule1 and CORSRule2 and then adds each rule to the
rules array By using the rules array it then adds the rules to the bucket bucketName
Add a sample configuration
API Version 20060301
138Amazon Simple Storage Service Developer Guide
Enabling CORS
CORSConfiguration configuration new CORSConfiguration
{
Rules new SystemCollectionsGenericList
{
new CORSRule
{
Id CORSRule1
AllowedMethods new List {PUT POST DELETE}
AllowedOrigins new List {http*examplecom}
}
new CORSRule
{
Id CORSRule2
AllowedMethods new List {GET}
AllowedOrigins new List {*}
MaxAgeSeconds 3000
ExposeHeaders new List {xamzserversideencryption}
}
}
}
Save the configuration
PutCORSConfiguration(configuration)
static void PutCORSConfiguration(CORSConfiguration configuration)
{
PutCORSConfigurationRequest request new PutCORSConfigurationRequest
{
BucketName bucketName
Configuration configuration
}
var response clientPutCORSConfiguration(request)
}
Updating an Existing CORS Configuration
To update an existing CORS configuration
1 Get a CORS configuration by calling the clientGetCORSConfiguration method
2 Update the configuration information by adding or deleting rules
3 Add the configuration to a bucket by calling the clientPutCORSConfiguration method
The following snippet gets an existing configuration and then adds a new rule with the ID NewRule
Get configuration
configuration GetCORSConfiguration()
Add new rule
configurationRulesAdd(new CORSRule
{
Id NewRule
AllowedMethods new List { HEAD }
AllowedOrigins new List { httpwwwexamplecom }
})
Save configuration
API Version 20060301
139Amazon Simple Storage Service Developer Guide
Enabling CORS
PutCORSConfiguration(configuration)
API Version 20060301
140Amazon Simple Storage Service Developer Guide
Enabling CORS
Example Program Listing
The following C# program incorporates the preceding tasks
For information about creating and testing a working sample see Running the Amazon S3 NET Code
Examples (p 566)
using System
using SystemConfiguration
using SystemCollectionsSpecialized
using SystemNet
using AmazonS3
using AmazonS3Model
using AmazonS3Util
using SystemDiagnostics
using SystemCollectionsGeneric
namespace s3amazoncomdocsamples
{
class CORS
{
static string bucketName *** Provide bucket name ***
static IAmazonS3 client
public static void Main(string[] args)
{
try
{
using (client new
AmazonS3Client(AmazonRegionEndpointUSWest2))
{
Create a new configuration request and add two rules

CORSConfiguration configuration new CORSConfiguration
{
Rules new SystemCollectionsGenericList
{
new CORSRule
{
Id CORSRule1
AllowedMethods new List {PUT POST
DELETE}
AllowedOrigins new List {http
*examplecom}
}
new CORSRule
{
Id CORSRule2
AllowedMethods new List {GET}
AllowedOrigins new List {*}
MaxAgeSeconds 3000
ExposeHeaders new List {xamzserver
sideencryption}
}
}
}
Add the configuration to the bucket
PutCORSConfiguration(configuration)
Retrieve an existing configuration
configuration GetCORSConfiguration()
Add a new rule
configurationRulesAdd(new CORSRule
{
Id CORSRule3
AllowedMethods new List { HEAD }
AllowedOrigins new List { http
wwwexamplecom }
})
Add the configuration to the bucket
PutCORSConfiguration(configuration)
Verify that there are now three rules
configuration GetCORSConfiguration()
ConsoleWriteLine()
ConsoleWriteLine(Expected # of rulest3 found{0}
configurationRulesCount)
ConsoleWriteLine()
ConsoleWriteLine(Pause before configuration delete To
continue click Enter)
ConsoleReadKey()
Delete the configuration
DeleteCORSConfiguration()
Retrieve a nonexistent configuration
configuration GetCORSConfiguration()
DebugAssert(configuration null)
}
ConsoleWriteLine(Example complete)
}
catch (AmazonS3Exception amazonS3Exception)
{
ConsoleWriteLine(S3 error occurred Exception +
amazonS3ExceptionToString())
ConsoleReadKey()
}
catch (Exception e)
{
ConsoleWriteLine(Exception + eToString())
ConsoleReadKey()
}

ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static void PutCORSConfiguration(CORSConfiguration configuration)
{
PutCORSConfigurationRequest request new
PutCORSConfigurationRequest
{
BucketName bucketName
Configuration configuration
}
var response clientPutCORSConfiguration(request)
}
static CORSConfiguration GetCORSConfiguration()
{
GetCORSConfigurationRequest request new
GetCORSConfigurationRequest
{
BucketName bucketName
}
var response clientGetCORSConfiguration(request)
var configuration responseConfiguration
PrintCORSRules(configuration)
return configuration
}
static void DeleteCORSConfiguration()
{
DeleteCORSConfigurationRequest request new
DeleteCORSConfigurationRequest
{
BucketName bucketName
}
clientDeleteCORSConfiguration(request)
}
static void PrintCORSRules(CORSConfiguration configuration)
{
ConsoleWriteLine()
if (configuration null)
{
ConsoleWriteLine(＼nConfiguration is null)
return
}
ConsoleWriteLine(Configuration has {0} rules
configurationRulesCount)
foreach (CORSRule rule in configurationRules)
{
ConsoleWriteLine(Rule ID {0} ruleId)
ConsoleWriteLine(MaxAgeSeconds {0} ruleMaxAgeSeconds)
ConsoleWriteLine(AllowedMethod {0} stringJoin(
ruleAllowedMethodsToArray()))
ConsoleWriteLine(AllowedOrigins {0} stringJoin(
ruleAllowedOriginsToArray()))
ConsoleWriteLine(AllowedHeaders {0} stringJoin(
ruleAllowedHeadersToArray()))
ConsoleWriteLine(ExposeHeader {0} stringJoin(
ruleExposeHeadersToArray()))
}
}
}
}
API Version 20060301
141Amazon Simple Storage Service Developer Guide
Troubleshooting CORS
Enabling CrossOrigin Resource Sharing (CORS) Using the
REST API
You can use the AWS Management Console to set CORS configuration on your bucket If your
application requires it you can also send REST requests directly The following sections in the
Amazon Simple Storage Service API Reference describe the REST API actions related to the CORS
configuration
• PUT Bucket cors
• GET Bucket cors
• DELETE Bucket cors
• OPTIONS object
Troubleshooting CORS Issues
When you are accessing buckets set with the CORS configuration if you encounter unexpected
behavior the following are some troubleshooting actions you can take
1 Verify that the CORS configuration is set on the bucket
For instructions go to Editing Bucket Permissions in the Amazon Simple Storage Service
Console User Guide If you have the CORS configuration set the console displays an Edit CORS
Configuration link in the Permissions section of the Properties bucket
2 Capture the complete request and response using a tool of your choice For each request Amazon
S3 receives there must exist one CORS rule matching the data in your request as follows
a Verify the request has the Origin header
If the header is missing Amazon S3 does not treat the request as a crossorigin request and
does not send CORS response headers back in the response
b Verify that the Origin header in your request matches at least one of the AllowedOrigin
elements in the specific CORSRule
The scheme the host and the port values in the Origin request header must match the
AllowedOrigin in the CORSRule For example if you set the CORSRule to allow the
origin httpwwwexamplecom then both httpswwwexamplecom and http
wwwexamplecom80 origins in your request do not match the allowed origin in your
configuration
c Verify that the Method in your request (or the method specified in the AccessControl
RequestMethod in case of a preflight request) is one of the AllowedMethod elements in the
same CORSRule
d For a preflight request if the request includes an AccessControlRequestHeaders header
verify that the CORSRule includes the AllowedHeader entries for each value in the Access
ControlRequestHeaders header
Operations on Objects
Amazon S3 enables you to store retrieve and delete objects You can retrieve an entire object or a
portion of an object If you have enabled versioning on your bucket you can retrieve a specific version
of the object You can also retrieve a subresource associated with your object and update it where
applicable You can make a copy of your existing object Depending on the object size the following
upload and copy related considerations apply
API Version 20060301
142Amazon Simple Storage Service Developer Guide
Getting Objects
• Uploading objects—You can upload objects of up to 5 GB in size in a single operation For objects
greater than 5 GB you must use the multipart upload API
Using the multipart upload API you can upload objects up to 5 TB each For more information see
Uploading Objects Using Multipart Upload API (p 165)
• Copying objects—The copy operation creates a copy of an object that is already stored in Amazon
S3
You can create a copy of your object up to 5 GB in size in a single atomic operation However for
copying an object greater than 5 GB you must use the multipart upload API For more information
see Copying Objects (p 212)
You can use the REST API (see Making Requests Using the REST API (p 49)) to work with objects or
use one of the following AWS SDK libraries
• AWS SDK for Java
• AWS SDK for NET
• AWS SDK for PHP
These libraries provide a highlevel abstraction that makes working with objects easy However if your
application requires you can use the REST API directly
Getting Objects
Topics
• Related Resources (p 144)
• Get an Object Using the AWS SDK for Java (p 144)
• Get an Object Using the AWS SDK for NET (p 147)
• Get an Object Using the AWS SDK for PHP (p 150)
• Get an Object Using the REST API (p 152)
• Share an Object with Others (p 152)
You can retrieve objects directly from Amazon S3 You have the following options when retrieving an
object
• Retrieve an entire object—A single GET operation can return you the entire object stored in
Amazon S3
• Retrieve object in parts—Using the Range HTTP header in a GET request you can retrieve a
specific range of bytes in an object stored in Amazon S3
You resume fetching other parts of the object whenever your application is ready This resumable
download is useful when you need only portions of your object data It is also useful where network
connectivity is poor and you need to react to failures
Note
Amazon S3 doesn＇t support retrieving multiple ranges of data per GET request
When you retrieve an object its metadata is returned in the response headers There are times when
you want to override certain response header values returned in a GET response For example you
might override the ContentDisposition response header value in your GET request The REST
GET Object API (see GET Object) allows you to specify query string parameters in your GET request
to override these values
The AWS SDK for Java NET and PHP also provide necessary objects you can use to specify values
for these response headers in your GET request
API Version 20060301
143Amazon Simple Storage Service Developer Guide
Getting Objects
When retrieving objects that are stored encrypted using serverside encryption you will need to provide
appropriate request headers For more information see Protecting Data Using Encryption (p 380)
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
Get an Object Using the AWS SDK for Java
When you download an object you get all of object＇s metadata and a stream from which to read
the contents You should read the content of the stream as quickly as possible because the data is
streamed directly from Amazon S3 and your network connection will remain open until you read all the
data or close the input stream
Downloading Objects
1 Create an instance of the AmazonS3Client class
2 Execute one of the AmazonS3ClientgetObject() method You need to provide the
request information such as bucket name and key name You provide this information by
creating an instance of the GetObjectRequest class
3 Execute one of the getObjectContent() methods on the object returned to get a
stream on the object data and process the response
The following Java code sample demonstrates the preceding tasks
AmazonS3 s3Client new AmazonS3Client(new ProfileCredentialsProvider())

S3Object object s3ClientgetObject(
new GetObjectRequest(bucketName key))
InputStream objectData objectgetObjectContent()
Process the objectData stream
objectDataclose()
The GetObjectRequest object provides several options including conditional downloading of objects
based on modification times ETags and selectively downloading a range of an object The following
Java code sample demonstrates how you can specify a range of data bytes to retrieve from an object
AmazonS3 s3Client new AmazonS3Client(new ProfileCredentialsProvider())

GetObjectRequest rangeObjectRequest new GetObjectRequest(
bucketName key)
rangeObjectRequestsetRange(0 10) retrieve 1st 11 bytes
S3Object objectPortion s3ClientgetObject(rangeObjectRequest)
InputStream objectData objectPortiongetObjectContent()
Process the objectData stream
objectDataclose()
When retrieving an object you can optionally override the response header values (see Getting
Objects (p 143)) by using the ResponseHeaderOverrides object and setting the corresponding
request property as shown in the following Java code sample
GetObjectRequest request new GetObjectRequest(bucketName key)
API Version 20060301
144Amazon Simple Storage Service Developer Guide
Getting Objects

ResponseHeaderOverrides responseHeaders new ResponseHeaderOverrides()
responseHeaderssetCacheControl(Nocache)
responseHeaderssetContentDisposition(attachment filenametestingtxt)
Add the ResponseHeaderOverides to the request
requestsetResponseHeaders(responseHeaders)
API Version 20060301
145Amazon Simple Storage Service Developer Guide
Getting Objects
Example
The following Java code example retrieves an object from a specified Amazon S3 bucket
For instructions on how to create and test a working sample see Testing the Java Code
Examples (p 564)
import javaioBufferedReader
import javaioIOException
import javaioInputStream
import javaioInputStreamReader
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelGetObjectRequest
import comamazonawsservicess3modelS3Object
public class GetObject {
private static String bucketName *** provide bucket name ***
private static String key *** provide object key ***

public static void main(String[] args) throws IOException {
AmazonS3 s3Client new AmazonS3Client(new
ProfileCredentialsProvider())
try {
Systemoutprintln(Downloading an object)
S3Object s3object s3ClientgetObject(new GetObjectRequest(
bucketName key))
Systemoutprintln(ContentType +
s3objectgetObjectMetadata()getContentType())
displayTextInputStream(s3objectgetObjectContent())

Get a range of bytes from an object

GetObjectRequest rangeObjectRequest new GetObjectRequest(
bucketName key)
rangeObjectRequestsetRange(0 10)
S3Object objectPortion s3ClientgetObject(rangeObjectRequest)

Systemoutprintln(Printing bytes retrieved)
displayTextInputStream(objectPortiongetObjectContent())

} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException which +
means your request made it +
to Amazon S3 but was rejected with an error response +
for some reason)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException which
means+
the client encountered +
an internal error while trying to +
communicate with S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
private static void displayTextInputStream(InputStream input)
throws IOException {
Read one text line at a time and display
BufferedReader reader new BufferedReader(new
InputStreamReader(input))
while (true) {
String line readerreadLine()
if (line null) break
Systemoutprintln( + line)
}
Systemoutprintln()
}
}
API Version 20060301
146Amazon Simple Storage Service Developer Guide
Getting Objects
Get an Object Using the AWS SDK for NET
The following tasks guide you through using the NET classes to retrieve an object or a portion of the
object and save it locally to a file
Downloading Objects
1 Create an instance of the AmazonS3 class
2 Execute one of the AmazonS3GetObject methods You need to provide information
such as bucket name file path or a stream You provide this information by creating an
instance of the GetObjectRequest class
3 Execute one of the GetObjectResponseWriteResponseStreamToFile methods to
save the stream to a file
The following C# code sample demonstrates the preceding tasks The examples saves the object to a
file on your desktop
static IAmazonS3 client
using (client new AmazonS3Client(AmazonRegionEndpointUSEast1))
{
GetObjectRequest request new GetObjectRequest
{
BucketName bucketName
Key keyName
}
using (GetObjectResponse response clientGetObject(request))
{
string dest
PathCombine(EnvironmentGetFolderPath(EnvironmentSpecialFolderDesktop)
keyName)
if (FileExists(dest))
{
responseWriteResponseStreamToFile(dest)
}
}
}
Instead of reading the entire object you can read only the portion of the object data by specifying the
byte range in the request as shown in the following C# code sample
GetObjectRequest request new GetObjectRequest
{
BucketName bucketName
Key keyName
ByteRange new ByteRange(0 10)
}
When retrieving an object you can optionally override the response header values (see Getting
Objects (p 143)) by using the ResponseHeaderOverrides object and setting the corresponding
request property as shown in the following C# code sample You can use this feature to indicate the
object should be downloaded into a different filename that the object key name
GetObjectRequest request new GetObjectRequest
{
API Version 20060301
147Amazon Simple Storage Service Developer Guide
Getting Objects
BucketName bucketName
Key keyName
}
ResponseHeaderOverrides responseHeaders new ResponseHeaderOverrides()
responseHeadersCacheControl Nocache
responseHeadersContentDisposition attachment filenametestingtxt
requestResponseHeaderOverrides responseHeaders
API Version 20060301
148Amazon Simple Storage Service Developer Guide
Getting Objects
ExampleThe following C# code example retrieves an object from an Amazon S3 bucket From the response
the example reads the object data using the GetObjectResponseResponseStream property The
example also shows how you can use the GetObjectResponseMetadata collection to read object
metadata If the object you retrieve has the xamzmetatitle metadata the code will print the
metadata valueFor instructions on how to create and test a working sample see Running the Amazon S3 NET Code
Examples (p 566)
using System
using SystemIO
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class GetObject
{
static string bucketName *** bucket name ***
static string keyName *** object key ***
static IAmazonS3 client
public static void Main(string[] args)
{
try
{
ConsoleWriteLine(Retrieving (GET) an object)
string data ReadObjectData()
}
catch (AmazonS3Exception s3Exception)
{
ConsoleWriteLine(s3ExceptionMessage
s3ExceptionInnerException)
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static string ReadObjectData()
{
string responseBody
using (client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
GetObjectRequest request new GetObjectRequest
{
BucketName bucketName
Key keyName
}
using (GetObjectResponse response
clientGetObject(request))
using (Stream responseStream responseResponseStream)
using (StreamReader reader new
StreamReader(responseStream))
{
string title responseMetadata[xamzmetatitle]
ConsoleWriteLine(The object＇s title is {0} title)
responseBody readerReadToEnd()
}
}
return responseBody
}
}
}
API Version 20060301
149Amazon Simple Storage Service Developer Guide
Getting Objects
Get an Object Using the AWS SDK for PHP
This topic guides you through using a class from the AWS SDK for PHP to retrieve an object You can
retrieve an entire object or specify a byte range to retrieve from the object
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
Downloading an Object
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 Execute the Aws＼S3＼S3ClientgetObject() method You must provide a bucket name and
a key name in the array parameter＇s required keys Bucket and Key
Instead of retrieving the entire object you can retrieve a specific byte range from the
object data You provide the range value by specifying the array parameter＇s Range key
in addition to the required keys
You can save the object you retrieved from Amazon S3 to a file in your local file system
by specifying a file path to where to save the file in the array parameter＇s SaveAs key in
addition to the required keys Bucket and Key
The following PHP code sample demonstrates the preceding tasks for downloading an object
use Aws＼S3＼S3Client
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇
filepath ＇*** Your File Path ***＇

Instantiate the client
s3 S3Clientfactory()
Get an object
result s3>getObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
))
Get a range of bytes from an object
result s3>getObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇Range＇ > ＇bytes099＇
))
Save object to a file
result s3>getObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇SaveAs＇ > filepath
))

API Version 20060301
150Amazon Simple Storage Service Developer Guide
Getting Objects
When retrieving an object you can optionally override the response header values (see Getting
Objects (p 143)) by adding the array parameter＇s response keys ResponseContentType
ResponseContentLanguage ResponseContentDisposition ResponseCacheControl and
ResponseExpires to the getObject() method as shown in the following PHP code sample
result s3>getObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇ResponseContentType＇ > ＇textplain＇
＇ResponseContentLanguage＇ > ＇enUS＇
＇ResponseContentDisposition＇ > ＇attachment filenametestingtxt＇
＇ResponseCacheControl＇ > ＇Nocache＇
＇ResponseExpires＇ > gmdate(DATE_RFC2822 time() + 3600)
))
Example of Downloading an Object Using PHP
The following PHP example retrieves an object and displays object content in the browser The
example illustrates the use of the getObject() method For information about running the PHP
examples in this guide go to Running PHP Examples (p 567)
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
use Aws＼S3＼S3Client
use Aws＼S3＼Exception＼S3Exception
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇
Instantiate the client
s3 S3Clientfactory()
try {
Get the object
result s3>getObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
))
Display the object in the browser
header(ContentType {result[＇ContentType＇]})
echo result[＇Body＇]
} catch (S3Exception e) {
echo e>getMessage() ＼n
}
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientgetObject() Method
• AWS SDK for PHP for Amazon S3 Downloading Objects
API Version 20060301
151Amazon Simple Storage Service Developer Guide
Getting Objects
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
Get an Object Using the REST API
You can use the AWS SDK to retrieve object keys from a bucket However if your application requires
it you can send REST requests directly You can send a GET request to retrieve object keys For more
information about the request and response format go to Get Object
Share an Object with Others
Topics
• Generate a Presigned Object URL using AWS Explorer for Visual Studio (p 152)
• Generate a Presigned Object URL using AWS SDK for Java (p 152)
• Generate a Presigned Object URL using AWS SDK for NET (p 155)
All objects by default are private Only the object owner has permission to access these objects
However the object owner can optionally share objects with others by creating a presigned URL
using their own security credentials to grant timelimited permission to download the objects
When you create a presigned URL for your object you must provide your security credentials specify
a bucket name an object key specify the HTTP method (GET to download the object) and expiration
date and time The presigned URLs are valid only for the specified duration
Anyone who receives the presigned URL can then access the object For example if you have a video
in your bucket and both the bucket and the object are private you can share the video with others by
generating a presigned URL
Note
Anyone with valid security credentials can create a presigned URL However in order to
successfully access an object the presigned URL must be created by someone who has
permission to perform the operation that the presigned URL is based upon
You can generate presigned URL programmatically using the AWS SDK for Java and NET
Generate a Presigned Object URL using AWS Explorer for Visual Studio
If you are using Visual Studio you can generate a presigned URL for an object without writing any
code by using AWS Explorer for Visual Studio Anyone with this URL can download the object For
more information go to Using Amazon S3 from AWS Explorer
For instructions about how to install the AWS Explorer see Using the AWS SDKs CLI and
Explorers (p 560)
Generate a Presigned Object URL using AWS SDK for Java
The following tasks guide you through using the Java classes to generate a presigned URL
Downloading Objects
1 Create an instance of the AmazonS3 class For information about providing credentials
see Using the AWS SDK for Java (p 563) These credentials are used in creating a
signature for authentication when you generate a presigned URL
2 Execute the AmazonS3generatePresignedUrl method to generate a presigned
URL
API Version 20060301
152Amazon Simple Storage Service Developer Guide
Getting Objects
You provide information including a bucket name an object key and an expiration date
by creating an instance of the GeneratePresignedUrlRequest class The request
by default sets the verb to GET To use the presigned URL for other operations for
example PUT you must explicitly set the verb when you create the request
The following Java code sample demonstrates the preceding tasks
AmazonS3 s3client new AmazonS3Client(new ProfileCredentialsProvider())

javautilDate expiration new javautilDate()
long msec expirationgetTime()
msec + 1000 * 60 * 60 1 hour
expirationsetTime(msec)

GeneratePresignedUrlRequest generatePresignedUrlRequest
new GeneratePresignedUrlRequest(bucketName objectKey)
generatePresignedUrlRequestsetMethod(HttpMethodGET) Default
generatePresignedUrlRequestsetExpiration(expiration)

URL s s3clientgeneratePresignedUrl(generatePresignedUrlRequest)
API Version 20060301
153Amazon Simple Storage Service Developer Guide
Getting Objects
ExampleThe following Java code example generates a presigned URL that you can give to others so that they
can retrieve the object You can use the generated presigned URL to retrieve the object To use the
presigned URL for other operations such as put an object you must explicitly set the verb in the
GetPreSignedUrlRequest For instructions about how to create and test a working sample see
Testing the Java Code Examples (p 564)
import javaioIOException
import javanetURL
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsHttpMethod
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelGeneratePresignedUrlRequest
public class GeneratePreSignedUrl {
private static String bucketName *** Provide a bucket name ***
private static String objectKey *** Provide an object key ***
public static void main(String[] args) throws IOException {
AmazonS3 s3client new AmazonS3Client(new ProfileCredentialsProvider())
try {
Systemoutprintln(Generating presigned URL)
javautilDate expiration new javautilDate()
long milliSeconds expirationgetTime()
milliSeconds + 1000 * 60 * 60 Add 1 hour
expirationsetTime(milliSeconds)
GeneratePresignedUrlRequest generatePresignedUrlRequest
new GeneratePresignedUrlRequest(bucketName objectKey)
generatePresignedUrlRequestsetMethod(HttpMethodGET)
generatePresignedUrlRequestsetExpiration(expiration)
URL url s3clientgeneratePresignedUrl(generatePresignedUrlRequest)
Systemoutprintln(PreSigned URL + urltoString())
} catch (AmazonServiceException exception) {
Systemoutprintln(Caught an AmazonServiceException +
which means your request made it +
to Amazon S3 but was rejected with an error response +
for some reason)
Systemoutprintln(Error Message + exceptiongetMessage())
Systemoutprintln(HTTP Code + exceptiongetStatusCode())
Systemoutprintln(AWS Error Code + exceptiongetErrorCode())
Systemoutprintln(Error Type + exceptiongetErrorType())
Systemoutprintln(Request ID + exceptiongetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException +
which means the client encountered +
an internal error while trying to communicate +
with S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
}
API Version 20060301
154Amazon Simple Storage Service Developer Guide
Getting Objects
Generate a Presigned Object URL using AWS SDK for NET
The following tasks guide you through using the NET classes to generate a presigned URL
Downloading Objects
1 Create an instance of the AmazonS3 class For information about providing your
credentials see Using the AWS SDK for NET (p 565) These credentials are used in
creating a signature for authentication when you generate a presigned URL
2 Execute the AmazonS3GetPreSignedURL method to generate a presigned URL
You provide information including a bucket name an object key and an expiration date
by creating an instance of the GetPreSignedUrlRequest class
The following C# code sample demonstrates the preceding tasks
static IAmazonS3 s3Client
s3Client new AmazonS3Client(AmazonRegionEndpointUSEast1)
GetPreSignedUrlRequest request1 new GetPreSignedUrlRequest()
{
BucketName bucketName
Key objectKey
Expires DateTimeNowAddMinutes(5)
}
string url s3ClientGetPreSignedURL(request1)
API Version 20060301
155Amazon Simple Storage Service Developer Guide
Getting Objects
Example
The following C# code example generates a presigned URL for a specific object For instructions
about how to create and test a working sample see Running the Amazon S3 NET Code
Examples (p 566)
using System
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class GeneratePresignedURL
{
static string bucketName *** Provide a bucket name ***
static string objectKey *** Provide an object name ***
static IAmazonS3 s3Client
public static void Main(string[] args)
{

using (s3Client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
string urlString GeneratePreSignedURL()
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static string GeneratePreSignedURL()
{
string urlString
GetPreSignedUrlRequest request1 new GetPreSignedUrlRequest
{
BucketName bucketName
Key objectKey
Expires DateTimeNowAddMinutes(5)

}
try
{
urlString s3ClientGetPreSignedURL(request1)
string url s3ClientGetPreSignedURL(request1)
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&
(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS Credentials)
ConsoleWriteLine(
To sign up for service go to httpawsamazoncom
s3)
}
else
{
ConsoleWriteLine(
Error occurred Message＇{0}＇ when listing objects
amazonS3ExceptionMessage)
}
}
catch (Exception e)
{
ConsoleWriteLine(eMessage)
}
return urlString
}
}
}
API Version 20060301
156Amazon Simple Storage Service Developer Guide
Uploading Objects
Uploading Objects
Depending on the size of the data you are uploading Amazon S3 offers the following options
• Upload objects in a single operation—With a single PUT operation you can upload objects up to 5
GB in size
For more information see Uploading Objects in a Single Operation (p 157)
• Upload objects in parts—Using the Multipart upload API you can upload large objects up to 5 TB
The Multipart Upload API is designed to improve the upload experience for larger objects You can
upload objects in parts These object parts can be uploaded independently in any order and in
parallel You can use a Multipart Upload for objects from 5 MB to 5 TB in size For more information
see Uploading Objects Using Multipart Upload API (p 165)
We encourage Amazon S3 customers to use Multipart Upload for objects greater than 100 MB
Topics
• Uploading Objects in a Single Operation (p 157)
• Uploading Objects Using Multipart Upload API (p 165)
• Uploading Objects Using PreSigned URLs (p 206)
When uploading objects you optionally request Amazon S3 to encrypt your object before saving it
on disks in its data centers and decrypt it when you download the objects For more information see
Protecting Data Using Encryption (p 380)
Related Topics
• Using the AWS SDKs CLI and Explorers (p 560)
Uploading Objects in a Single Operation
Topics
• Upload an Object Using the AWS SDK for Java (p 157)
• Upload an Object Using the AWS SDK for NET (p 159)
• Upload an Object Using the AWS SDK for PHP (p 161)
• Upload an Object Using the AWS SDK for Ruby (p 163)
• Upload an Object Using the REST API (p 164)
You can use the AWS SDK to upload objects The SDK provides wrapper libraries for you to upload
data easily However if your application requires it you can use the REST API directly in your
application
Upload an Object Using the AWS SDK for Java
The following tasks guide you through using the Java classes to upload a file The API provides several
variations called overloads of the putObject method to easily upload your data
Uploading Objects
1 Create an instance of the AmazonS3Client
2 Execute one of the AmazonS3ClientputObject overloads depending on whether you
are uploading data from a file or a stream
API Version 20060301
157Amazon Simple Storage Service Developer Guide
Uploading Objects
The following Java code sample demonstrates the preceding tasks
AmazonS3 s3client new AmazonS3Client(new ProfileCredentialsProvider())

s3clientputObject(new PutObjectRequest(bucketName keyName file))
Example
The following Java code example uploads a file to an Amazon S3 bucket For instructions on how to
create and test a working sample see Testing the Java Code Examples (p 564)
import javaioFile
import javaioIOException
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelPutObjectRequest
public class UploadObjectSingleOperation {
private static String bucketName *** Provide bucket name ***
private static String keyName *** Provide key ***
private static String uploadFileName *** Provide file name ***

public static void main(String[] args) throws IOException {
AmazonS3 s3client new AmazonS3Client(new
ProfileCredentialsProvider())
try {
Systemoutprintln(Uploading a new object to S3 from a file＼n)
File file new File(uploadFileName)
s3clientputObject(new PutObjectRequest(
bucketName keyName file))
} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException which +
means your request made it +
to Amazon S3 but was rejected with an error response +
for some reason)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException which +
means the client encountered +
an internal error while trying to +
communicate with S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
}
API Version 20060301
158Amazon Simple Storage Service Developer Guide
Uploading Objects
Upload an Object Using the AWS SDK for NET
The tasks in the following process guide you through using the NET classes to upload an object The
API provides several variations overloads of the PutObject method to easily upload your data
Uploading Objects
1 Create an instance of the AmazonS3 class
2 Execute one of the AmazonS3PutObject You need to provide information such as a
bucket name file path or a stream You provide this information by creating an instance
of the PutObjectRequest class
The following C# code sample demonstrates the preceding tasks
static IAmazonS3 client
client new AmazonS3Client(AmazonRegionEndpointUSEast1)
PutObjectRequest request new PutObjectRequest()
{
BucketName bucketName
Key keyName
FilePath filePath
}
PutObjectResponse response2 clientPutObject(request)
API Version 20060301
159Amazon Simple Storage Service Developer Guide
Uploading Objects
Example
The following C# code example uploads an object The object data is provided as a text string in the
code The example uploads the object twice
• The first PutObjectRequest specifies only the bucket name key name and a text string
embedded in the code as sample object data
• The second PutObjectRequest provides additional information including the optional object
metadata and a ContentType header The request specifies a file name to upload
Each successive call to AmazonS3PutObject replaces the previous upload For instructions on how
to create and test a working sample see Running the Amazon S3 NET Code Examples (p 566)
using System
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class UploadObject
{
static string bucketName *** bucket name ***
static string keyName *** key name when object is created ***
static string filePath *** absolute path to a sample file to
upload ***
static IAmazonS3 client
public static void Main(string[] args)
{
using (client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
ConsoleWriteLine(Uploading an object)
WritingAnObject()
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static void WritingAnObject()
{
try
{
PutObjectRequest putRequest1 new PutObjectRequest
{
BucketName bucketName
Key keyName
ContentBody sample text
}
PutObjectResponse response1 clientPutObject(putRequest1)
2 Put objectset ContentType and add metadata
PutObjectRequest putRequest2 new PutObjectRequest
{
BucketName bucketName
Key keyName
FilePath filePath
ContentType textplain
}
putRequest2MetadataAdd(xamzmetatitle someTitle)

PutObjectResponse response2 clientPutObject(putRequest2)
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&
(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS Credentials)
ConsoleWriteLine(
For service sign up go to httpawsamazoncom
s3)
}
else
{
ConsoleWriteLine(
Error occurred Message＇{0}＇ when writing an
object
amazonS3ExceptionMessage)
}
}
}
}
}
API Version 20060301
160Amazon Simple Storage Service Developer Guide
Uploading Objects
Upload an Object Using the AWS SDK for PHP
This topic guides you through using classes from the AWS SDK for PHP to upload an object of up to
5 GB in size For larger files you must use multipart upload API For more information see Uploading
Objects Using Multipart Upload API (p 165)
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
Uploading Objects
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 Execute the Aws＼S3＼S3ClientputObject() method You must provide a bucket name and
a key name in the array parameter＇s required keys Bucket and Key
If you are uploading a file you specify the file name by adding the array parameter with
the SourceFile key You can also provide the optional object metadata using the array
parameter
The following PHP code sample demonstrates how to create an object by uploading a file specified in
the SourceFile key in the putObject method＇s array parameter
use Aws＼S3＼S3Client
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇
filepath should be absolute path to a file on disk
filepath ＇*** Your File Path ***＇

Instantiate the client
s3 S3Clientfactory()
Upload a file
result s3>putObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇SourceFile＇ > filepath
＇ContentType＇ > ＇textplain＇
＇ACL＇ > ＇publicread＇
＇StorageClass＇ > ＇REDUCED_REDUNDANCY＇
＇Metadata＇ > array(
＇param1＇ > ＇value 1＇
＇param2＇ > ＇value 2＇
)
))
echo result[＇ObjectURL＇]
Instead of specifying a file name you can provide object data inline by specifying the array parameter
with the Body key as shown in the following PHP code example
use Aws＼S3＼S3Client
API Version 20060301
161Amazon Simple Storage Service Developer Guide
Uploading Objects
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇

Instantiate the client
s3 S3Clientfactory()
Upload data
result s3>putObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇Body＇ > ＇Hello world＇
))
echo result[＇ObjectURL＇]
Example of Creating an Object in an Amazon S3 bucket by Uploading Data
The following PHP example creates an object in a specified bucket by uploading data using the
putObject() method For information about running the PHP examples in this guide go to Running
PHP Examples (p 567)
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
use Aws＼S3＼S3Client
use Aws＼S3＼Exception＼S3Exception
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇

Instantiate the client
s3 S3Clientfactory()
try {
Upload data
result s3>putObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇Body＇ > ＇Hello world＇
＇ACL＇ > ＇publicread＇
))
Print the URL to the object
echo result[＇ObjectURL＇] ＼n
} catch (S3Exception e) {
echo e>getMessage() ＼n
}
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientputObject() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
API Version 20060301
162Amazon Simple Storage Service Developer Guide
Uploading Objects
Upload an Object Using the AWS SDK for Ruby
The following tasks guide you through using a Ruby script to upload an object for either version of the
SDK for Ruby
Using AWS SDK for Ruby Version 2
The AWS SDK for Ruby Version 2 has two ways of uploading an object to Amazon S3 The first is a
managed file uploader which makes it easy to upload files of any size from disk
Uploading a File
1 Create an instance of the AwsS3Resource class
2 Reference the target object by bucket name and key
2 Call#upload_file on the object
require ＇awssdk＇
s3 AwsS3Resourcenew(region＇uswest2＇)
obj s3bucket(＇bucketname＇)object(＇key＇)
objupload_file(＇pathtosourcefile＇)
The second way that SDK for Ruby Version 2 can upload an object is to use the #put method of
AwsS3Object This is useful if the object is a string or an IO object that is not a file on disk
Put Object
1 Create an instance of the AwsS3Resource class
2 Reference the target object by bucket name and key
2 Call#put passing in the string or IO object
require ＇awssdk＇
s3 AwsS3Resourcenew(region＇uswest2＇)
obj s3bucket(＇bucketname＇)object(＇key＇)
# string data
objput(body ＇Hello World＇)
# IO object
Fileopen(＇source＇ ＇rb＇) do |file|
objput(body file)
end
Using AWS SDK for Ruby Version 1
The API provides a #write method that can take options that you can use to specify how to upload
your data
Uploading Objects SDK for Ruby Version 1
1 Create an instance of the AWSS3 class by providing your AWS credentials
API Version 20060301
163Amazon Simple Storage Service Developer Guide
Uploading Objects
2 Use the AWSS3S3Object#write method which takes a data parameter and options
hash which allow you to upload data from a file or a stream
The following code sample for the SDK for Ruby Version 1 demonstrates the preceding tasks and
uses the options hash file to specify the path to the file to upload
s3 AWSS3new
# Upload a file
key Filebasename(file_name)
s3buckets[bucket_name]objects[key]write(file > file_name)
Example
The following SDK for Ruby Version 1 script example uploads a file to an Amazon S3 bucket For
instructions about how to create and test a working sample see Using the AWS SDK for Ruby
Version 2 (p 568)
#usrbinenv ruby
require ＇rubygems＇
require ＇awssdk＇
bucket_name ＇*** Provide bucket name ***＇
file_name ＇*** Provide file name ****＇
# Get an instance of the S3 interface
s3 AWSS3new
# Upload a file
key Filebasename(file_name)
s3buckets[bucket_name]objects[key]write(file > file_name)
puts Uploading file #{file_name} to bucket #{bucket_name}
Upload an Object Using the REST API
You can use AWS SDK to upload an object However if your application requires it you can send
REST requests directly You can send a PUT request to upload data in a single operation For more
information see PUT Object
API Version 20060301
164Amazon Simple Storage Service Developer Guide
Uploading Objects
Uploading Objects Using Multipart Upload API
Topics
• Multipart Upload Overview (p 165)
• Using the AWS Java SDK for Multipart Upload (HighLevel API) (p 172)
• Using the AWS Java SDK for Multipart Upload (LowLevel API) (p 177)
• Using the AWS NET SDK for Multipart Upload (HighLevel API) (p 181)
• Using the AWS NET SDK for Multipart Upload (LowLevel API) (p 190)
• Using the AWS PHP SDK for Multipart Upload (HighLevel API) (p 196)
• Using the AWS PHP SDK for Multipart Upload (LowLevel API) (p 200)
• Using the AWS SDK for Ruby for Multipart Upload (p 204)
• Using the REST API for Multipart Upload (p 205)
Multipart upload allows you to upload a single object as a set of parts Each part is a contiguous portion
of the object＇s data You can upload these object parts independently and in any order If transmission
of any part fails you can retransmit that part without affecting other parts After all parts of your object
are uploaded Amazon S3 assembles these parts and creates the object In general when your object
size reaches 100 MB you should consider using multipart uploads instead of uploading the object in a
single operation
Using multipart upload provides the following advantages
• Improved throughput—You can upload parts in parallel to improve throughput
• Quick recovery from any network issues—Smaller part size minimizes the impact of restarting a
failed upload due to a network error
• Pause and resume object uploads—You can upload object parts over time Once you initiate a
multipart upload there is no expiry you must explicitly complete or abort the multipart upload
• Begin an upload before you know the final object size—You can upload an object as you are
creating it
For more information see Multipart Upload Overview (p 165)
Multipart Upload Overview
Topics
• Concurrent Multipart Upload Operations (p 167)
• Multipart Upload and Pricing (p 167)
• Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle Policy (p 167)
• Quick Facts (p 169)
• API Support for Multipart Upload (p 169)
• Multipart Upload API and Permissions (p 169)
The Multipart upload API enables you to upload large objects in parts You can use this API to upload
new large objects or make a copy of an existing object (see Operations on Objects (p 142))
Multipart uploading is a threestep process You initiate the upload you upload the object parts and
after you have uploaded all the parts you complete the multipart upload Upon receiving the complete
multipart upload request Amazon S3 constructs the object from the uploaded parts and you can then
access the object just as you would any other object in your bucket
API Version 20060301
165Amazon Simple Storage Service Developer Guide
Uploading Objects
You can list of all your inprogress multipart uploads or get a list of the parts that you have uploaded for
a specific multipart upload Each of these operations is explained in this section
Multipart Upload Initiation
When you send a request to initiate a multipart upload Amazon S3 returns a response with an upload
ID which is a unique identifier for your multipart upload You must include this upload ID whenever
you upload parts list the parts complete an upload or abort an upload If you want to provide any
metadata describing the object being uploaded you must provide it in the request to initiate multipart
upload
Parts Upload
When uploading a part in addition to the upload ID you must specify a part number You can choose
any part number between 1 and 10000 A part number uniquely identifies a part and its position in
the object you are uploading If you upload a new part using the same part number as a previously
uploaded part the previously uploaded part is overwritten Whenever you upload a part Amazon S3
returns an ETag header in its response For each part upload you must record the part number and
the ETag value You need to include these values in the subsequent request to complete the multipart
upload
Note
After you initiate a multipart upload and upload one or more parts you must either complete
or abort the multipart upload in order to stop getting charged for storage of the uploaded parts
Only after you either complete or abort a multipart upload will Amazon S3 free up the parts
storage and stop charging you for the parts storage
Multipart Upload Completion (or Abort)
When you complete a multipart upload Amazon S3 creates an object by concatenating the parts in
ascending order based on the part number If any object metadata was provided in the initiate multipart
upload request Amazon S3 associates that metadata with the object After a successful complete
request the parts no longer exist Your complete multipart upload request must include the upload
ID and a list of both part numbers and corresponding ETag values Amazon S3 response includes an
ETag that uniquely identifies the combined object data This ETag will not necessarily be an MD5 hash
of the object data You can optionally abort the multipart upload After aborting a multipart upload you
cannot upload any part using that upload ID again All storage that any parts from the aborted multipart
upload consumed is then freed If any part uploads were inprogress they can still succeed or fail even
after you aborted To free all storage consumed by all parts you must abort a multipart upload only
after all part uploads have completed
Multipart Upload Listings
You can list the parts of a specific multipart upload or all inprogress multipart uploads The list parts
operation returns the parts information that you have uploaded for a specific multipart upload For each
list parts request Amazon S3 returns the parts information for the specified multipart upload up to a
maximum of 1000 parts If there are more than 1000 parts in the multipart upload you must send a
series of list part requests to retrieve all the parts Note that the returned list of parts doesn＇t include
parts that haven＇t completed uploading
Note
Only use the returned listing for verification You should not use the result of this listing
when sending a complete multipart upload request Instead maintain your own list of the
part numbers you specified when uploading parts and the corresponding ETag values that
Amazon S3 returns
Using the list multipart uploads operation you can obtain a list of multipart uploads in progress An in
progress multipart upload is an upload that you have initiated but have not yet completed or aborted
Each request returns at most 1000 multipart uploads If there are more than 1000 multipart uploads in
progress you need to send additional requests to retrieve the remaining multipart uploads
API Version 20060301
166Amazon Simple Storage Service Developer Guide
Uploading Objects
Concurrent Multipart Upload Operations
In a distributed development environment it is possible for your application to initiate several updates
on the same object at the same time Your application might initiate several multipart uploads using
the same object key For each of these uploads your application can then upload parts and send
a complete upload request to Amazon S3 to create the object When the buckets have versioning
enabled completing a multipart upload always creates a new version For buckets that do not have
versioning enabled it is possible that some other request received between the time when a multipart
upload is initiated and when it is completed might take precedence
Note
It is possible for some other request received between the time you initiated a multipart upload
and completed it to take precedence For example if another operation deletes a key after
you initiate a multipart upload with that key but before you complete it the complete multipart
upload response might indicate a successful object creation without you ever seeing the
object
Multipart Upload and Pricing
Once you initiate a multipart upload Amazon S3 retains all the parts until you either complete or
abort the upload Throughout its lifetime you are billed for all storage bandwidth and requests for
this multipart upload and its associated parts If you abort the multipart upload Amazon S3 deletes
upload artifacts and any parts that you have uploaded and you are no longer billed for them For more
information about pricing see Amazon S3 Pricing
Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle Policy
After you initiate a multipart upload you begin uploading parts Amazon S3 stores these parts but it
creates the object from the parts only after you upload all of them and send a successful request
to complete the multipart upload (you should verify that your request to complete multipart upload is
successful) Upon receiving the complete multipart upload request Amazon S3 assembles the parts
and creates an object
If you don＇t send the complete multipart upload request successfully Amazon S3 will not assemble
the parts and will not create any object Therefore the parts remain in Amazon S3 and you pay for the
parts that are stored in Amazon S3 As a best practice we recommend you configure a lifecycle rule
(using the AbortIncompleteMultipartUpload action) to minimize your storage costs
Amazon S3 supports a bucket lifecycle rule that you can use to direct Amazon S3 to abort multipart
uploads that don＇t complete within a specified number of days after being initiated When a multipart
upload is not completed within the time frame it becomes eligible for an abort operation and Amazon
S3 aborts the multipart upload (and deletes the parts associated with the multipart upload)
The following is an example lifecycle configuration that specifies a rule with the
AbortIncompleteMultipartUpload action


samplerule

Enabled

7



In the example the rule does not specify a value for the Prefix element (object key name prefix) and
therefore it applies to all objects in the bucket for which you initiated multipart uploads Any multipart
API Version 20060301
167Amazon Simple Storage Service Developer Guide
Uploading Objects
uploads that were initiated and did not complete within seven days become eligible for an abort
operation (the action has no effect on completed multipart uploads)
For more information about the bucket lifecycle configuration see Object Lifecycle
Management (p 109)
Note
if the multipart upload is completed within the number of days specified in the rule the
AbortIncompleteMultipartUpload lifecycle action does not apply (that is Amazon S3
will not take any action) Also this action does not apply to objects no objects are deleted by
this lifecycle action
The following putbucketlifecycle CLI command adds the lifecycle configuration for the
specified bucket
aws s3api putbucketlifecycle ＼
bucket bucketname ＼
lifecycleconfiguration filenamecontaininglifecycle
configuration
To test the CLI command do the following
1 Set up the AWS CLI For instructions see Set Up the AWS CLI (p 562)
2 Save the following example lifecycle configuration in a file (lifecyclejson) The example
configuration specifies empty prefix and therefore it applies to all objects in the bucket You can
specify a prefix to restrict the policy to a subset of objects
{
Rules [
{
ID Test Rule
Status Enabled
Prefix
AbortIncompleteMultipartUpload {
DaysAfterInitiation 7
}
}
]
}
3 Run the following CLI command to set lifecycle configuration on your bucket
aws s3api putbucketlifecycle ＼
bucket bucketname ＼
lifecycleconfiguration filelifecyclejson
4 To verify retrieve the lifecycle configuration using the getbucketlifecycle CLI command
aws s3api getbucketlifecycle ＼
bucket bucketname
5 To delete the lifecycle configuration use the deletebucketlifecycle CLI command
aws s3api deletebucketlifecycle ＼
API Version 20060301
168Amazon Simple Storage Service Developer Guide
Uploading Objects
bucket bucketname
Quick Facts
The following table provides multipart upload core specifications For more information see Multipart
Upload Overview (p 165)
Item Specification
Maximum object size 5 TB
Maximum number of parts per upload 10000
Part numbers 1 to 10000 (inclusive)
Part size 5 MB to 5 GB last part can be < 5 MB
Maximum number of parts returned
for a list parts request
1000
Maximum number of multipart
uploads returned in a list multipart
uploads request
1000
API Support for Multipart Upload
You can use an AWS SDK to upload an object in parts The following AWS SDK libraries support
multipart upload
• AWS SDK for Java
• AWS SDK for NET
• AWS SDK for PHP
These libraries provide a highlevel abstraction that makes uploading multipart objects easy However
if your application requires you can use the REST API directly The following sections in the Amazon
Simple Storage Service API Reference describe the REST API for multipart upload
• Initiate Multipart Upload
• Upload Part
• Upload Part (Copy)
• Complete Multipart Upload
• Abort Multipart Upload
• List Parts
• List Multipart Uploads
Multipart Upload API and Permissions
An individual must have the necessary permissions to use the multipart upload operations You can
use ACLs the bucket policy or the user policy to grant individuals permissions to perform these
operations The following table lists the required permissions for various multipart upload operations
when using ACLs bucket policy or the user policy
API Version 20060301
169Amazon Simple Storage Service Developer Guide
Uploading Objects
Action Required Permissions
Initiate
Multipart
Upload
You must be allowed to perform the s3PutObject action on an object to initiate
multipart upload
The bucket owner can allow other principals to perform the s3PutObject action
Initiator Container element that identifies who initiated the multipart upload If the initiator is
an AWS account this element provides the same information as the Owner element
If the initiator is an IAM User this element provides the user ARN and display name
Upload Part You must be allowed to perform the s3PutObject action on an object to upload a
part
Only the initiator of a multipart upload can upload parts The bucket owner must
allow the initiator to perform the s3PutObject action on an object in order for the
initiator to upload a part for that object
Upload Part
(Copy)
You must be allowed to perform the s3PutObject action on an object to upload
a part Because your are uploading a part from an existing object you must be
allowed s3GetObject on the source object
Only the initiator of a multipart upload can upload parts The bucket owner must
allow the initiator to perform the s3PutObject action on an object in order for the
initiator to upload a part for that object
Complete
Multipart
Upload
You must be allowed to perform the s3PutObject action on an object to complete
a multipart upload
Only the initiator of a multipart upload can complete that multipart upload The
bucket owner must allow the initiator to perform the s3PutObject action on an
object in order for the initiator to complete a multipart upload for that object
Abort
Multipart
Upload
You must be allowed to perform the s3AbortMultipartUpload action to abort a
multipart upload
By default the bucket owner and the initiator of the multipart upload are allowed to
perform this action If the initiator is an IAM user that user＇s AWS account is also
allowed to abort that multipart upload
In addition to these defaults the bucket owner can allow other principals to perform
the s3AbortMultipartUpload action on an object The bucket owner can deny
any principal the ability to perform the s3AbortMultipartUpload action
List Parts You must be allowed to perform the s3ListMultipartUploadParts action to
list parts in a multipart upload
By default the bucket owner has permission to list parts for any multipart upload to
the bucket The initiator of the multipart upload has the permission to list parts of the
specific multipart upload If the multipart upload initiator is an IAM user the AWS
account controlling that IAM user also has permission to list parts of that upload
In addition to these defaults the bucket owner can allow other principals to perform
the s3ListMultipartUploadParts action on an object The bucket owner can
also deny any principal the ability to perform the s3ListMultipartUploadParts
action
List Multipart
Uploads
You must be allowed to perform the s3ListBucketMultipartUploads action on
a bucket to list multipart uploads in progress to that bucket
In addition to the default the bucket owner can allow other principals to perform the
s3ListBucketMultipartUploads action on the bucket
API Version 20060301
170Amazon Simple Storage Service Developer Guide
Uploading Objects
For information on the relationship between ACL permissions and permissions in access policies see
Mapping of ACL Permissions and Access Policy Permissions (p 366) For information on IAM users
go to Working with Users and Groups
API Version 20060301
171Amazon Simple Storage Service Developer Guide
Uploading Objects
Using the AWS Java SDK for Multipart Upload (HighLevel API)
Topics
• Upload a File (p 172)
• Abort Multipart Uploads (p 173)
• Track Multipart Upload Progress (p 174)
The AWS SDK for Java exposes a highlevel API that simplifies multipart upload (see Uploading
Objects Using Multipart Upload API (p 165)) You can upload data from a file or a stream You
can also set advanced options such as the part size you want to use for the multipart upload or
the number of threads you want to use when uploading the parts concurrently You can also set
optional object properties the storage class or ACL You use the PutObjectRequest and the
TransferManagerConfiguration classes to set these advanced options The TransferManager
class of the Java API provides the highlevel API for you to upload data
When possible TransferManager attempts to use multiple threads to upload multiple parts of a
single upload at once When dealing with large content sizes and high bandwidth this can have a
significant increase on throughput
In addition to file upload functionality the TransferManager class provides a method for you to abort
multipart upload in progress You must provide a Date value and then the API aborts all the multipart
uploads that were initiated before the specified date
Upload a File
The following tasks guide you through using the highlevel Java classes to upload a file The API
provides several variations called overloads of the upload method to easily upload your data
HighLevel API File Uploading Process
1 Create an instance of the TransferManager class
2 Execute one of the TransferManagerupload overloads depending on whether you
are uploading data from a file or a stream
The following Java code example demonstrates the preceding tasks
API Version 20060301
172Amazon Simple Storage Service Developer Guide
Uploading Objects
Example
The following Java code example uploads a file to an Amazon S3 bucket For instructions on how to
create and test a working sample see Testing the Java Code Examples (p 564)
import javaioFile
import comamazonawsAmazonClientException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3transferTransferManager
import comamazonawsservicess3transferUpload
public class UploadObjectMultipartUploadUsingHighLevelAPI {
public static void main(String[] args) throws Exception {
String existingBucketName *** Provide existing bucket name ***
String keyName *** Provide object key ***
String filePath *** Path to and name of the file to
upload ***

TransferManager tm new TransferManager(new
ProfileCredentialsProvider())
Systemoutprintln(Hello)
TransferManager processes all transfers asynchronously
so this call will return immediately
Upload upload tmupload(
existingBucketName keyName new File(filePath))
Systemoutprintln(Hello2)
try {
Or you can block and wait for the upload to finish
uploadwaitForCompletion()
Systemoutprintln(Upload complete)
} catch (AmazonClientException amazonClientException) {
Systemoutprintln(Unable to upload file upload was aborted)
amazonClientExceptionprintStackTrace()
}
}
}
Abort Multipart Uploads
The TransferManager class provides a method abortMultipartUploads to abort multipart
uploads in progress An upload is considered to be in progress once you initiate it and until you
complete it or abort it You provide a Date value and this API aborts all the multipart uploads on that
bucket that were initiated before the specified Date and are still in progress
Because you are billed for all storage associated with uploaded parts (see Multipart Upload and
Pricing (p 167)) it is important that you either complete the multipart upload to have the object created
or abort the multipart upload to remove any uploaded parts
The following tasks guide you through using the highlevel Java classes to abort multipart uploads
HighLevel API Multipart Uploads Aborting Process
1 Create an instance of the TransferManager class
2 Execute the TransferManagerabortMultipartUploads method by passing the
bucket name and a Date value
API Version 20060301
173Amazon Simple Storage Service Developer Guide
Uploading Objects
The following Java code example demonstrates the preceding tasks
Example
The following Java code aborts all multipart uploads in progress that were initiated on a specific bucket
over a week ago For instructions on how to create and test a working sample see Testing the Java
Code Examples (p 564)
import javautilDate
import comamazonawsAmazonClientException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3transferTransferManager
public class AbortMPUUsingHighLevelAPI {
public static void main(String[] args) throws Exception {
String existingBucketName *** Provide existing bucket name ***

TransferManager tm new TransferManager(new
ProfileCredentialsProvider())
int sevenDays 1000 * 60 * 60 * 24 * 7
Date oneWeekAgo new Date(SystemcurrentTimeMillis() sevenDays)

try {
tmabortMultipartUploads(existingBucketName oneWeekAgo)
} catch (AmazonClientException amazonClientException) {
Systemoutprintln(Unable to upload file upload was aborted)
amazonClientExceptionprintStackTrace()
}
}
}
Note
You can also abort a specific multipart upload For more information see Abort a Multipart
Upload (p 180)
Track Multipart Upload Progress
The highlevel multipart upload API provides a listen interface ProgressListener to track the
upload progress when uploading data using the TransferManager class To use the event in
your code you must import the comamazonawsservicess3modelProgressEvent and
comamazonawsservicess3modelProgressListener types
Progress events occurs periodically and notify the listener that bytes have been transferred
The following Java code sample demonstrates how you can subscribe to the ProgressEvent event
and write a handler
TransferManager tm new TransferManager(new ProfileCredentialsProvider())

PutObjectRequest request new PutObjectRequest(
existingBucketName keyName new File(filePath))
Subscribe to the event and provide event handler
requestsetProgressListener(new ProgressListener() {
public void progressChanged(ProgressEvent event) {
Systemoutprintln(Transferred bytes +
API Version 20060301
174Amazon Simple Storage Service Developer Guide
Uploading Objects
eventgetBytesTransfered())
}
})
API Version 20060301
175Amazon Simple Storage Service Developer Guide
Uploading Objects
Example
The following Java code uploads a file and uses the ProgressListener to track the upload
progress For instructions on how to create and test a working sample see Testing the Java Code
Examples (p 564)
import javaioFile
import comamazonawsAmazonClientException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawseventProgressEvent
import comamazonawseventProgressListener
import comamazonawsservicess3modelPutObjectRequest
import comamazonawsservicess3transferTransferManager
import comamazonawsservicess3transferUpload
public class TrackMPUProgressUsingHighLevelAPI {
public static void main(String[] args) throws Exception {
String existingBucketName *** Provide bucket name ***
String keyName *** Provide object key ***
String filePath *** file to upload ***

TransferManager tm new TransferManager(new
ProfileCredentialsProvider())
For more advanced uploads you can create a request object
and supply additional request parameters (ex progress listeners
canned ACLs etc)
PutObjectRequest request new PutObjectRequest(
existingBucketName keyName new File(filePath))

You can ask the upload for its progress or you can
add a ProgressListener to your request to receive notifications
when bytes are transferred
requestsetGeneralProgressListener(new ProgressListener() {
@Override
public void progressChanged(ProgressEvent progressEvent) {
Systemoutprintln(Transferred bytes +
progressEventgetBytesTransferred())
}
})
TransferManager processes all transfers asynchronously
so this call will return immediately
Upload upload tmupload(request)

try {
You can block and wait for the upload to finish
uploadwaitForCompletion()
} catch (AmazonClientException amazonClientException) {
Systemoutprintln(Unable to upload file upload aborted)
amazonClientExceptionprintStackTrace()
}
}
}
API Version 20060301
176Amazon Simple Storage Service Developer Guide
Uploading Objects
Using the AWS Java SDK for Multipart Upload (LowLevel API)
Topics
• Upload a File (p 177)
• List Multipart Uploads (p 180)
• Abort a Multipart Upload (p 180)
The AWS SDK for Java exposes a lowlevel API that closely resembles the Amazon S3 REST API
for multipart upload (see Uploading Objects Using Multipart Upload API (p 165) Use the lowlevel
API when you need to pause and resume multipart uploads vary part sizes during the upload or do
not know the size of the data in advance Use the highlevel API (see Using the AWS Java SDK for
Multipart Upload (HighLevel API) (p 172)) whenever you don＇t have these requirements
Upload a File
The following tasks guide you through using the lowlevel Java classes to upload a file
LowLevel API File Uploading Process
1 Create an instance of the AmazonS3Client class
2 Initiate multipart upload by executing the
AmazonS3ClientinitiateMultipartUpload method You will need to provide the
required information ie bucket name and key name to initiate the multipart upload by
creating an instance of the InitiateMultipartUploadRequest class
3 Save the upload ID that the AmazonS3ClientinitiateMultipartUpload method
returns You will need to provide this upload ID for each subsequent multipart upload
operation
4 Upload parts For each part upload execute the AmazonS3ClientuploadPart
method You need to provide part upload information such as upload ID bucket
name and the part number You provide this information by creating an instance of the
UploadPartRequest class
5 Save the response of the AmazonS3ClientuploadPart method in a list This
response includes the ETag value and the part number you will need to complete the
multipart upload
6 Repeat tasks 4 and 5 for each part
7 Execute the AmazonS3ClientcompleteMultipartUpload method to complete the
multipart upload
The following Java code sample demonstrates the preceding tasks
AmazonS3 s3Client new AmazonS3Client(new ProfileCredentialsProvider())
Create a list of UploadPartResponse objects You get one of these for
each part upload
List partETags new ArrayList()
Step 1 Initialize
InitiateMultipartUploadRequest initRequest new
InitiateMultipartUploadRequest(
existingBucketName
keyName)
InitiateMultipartUploadResult initResponse
API Version 20060301
177Amazon Simple Storage Service Developer Guide
Uploading Objects
s3ClientinitiateMultipartUpload(initRequest)
File file new File(filePath)
long contentLength filelength()
long partSize 5 * 1024 * 1024 Set part size to 5 MB
try {
Step 2 Upload parts
long filePosition 0
for (int i 1 filePosition < contentLength i++) {
Last part can be less than 5 MB Adjust part size
partSize Mathmin(partSize (contentLength filePosition))

Create request to upload a part
UploadPartRequest uploadRequest new UploadPartRequest()
withBucketName(existingBucketName)withKey(keyName)
withUploadId(initResponsegetUploadId())withPartNumber(i)
withFileOffset(filePosition)
withFile(file)
withPartSize(partSize)
Upload part and add response to our list
partETagsadd(s3ClientuploadPart(uploadRequest)getPartETag())
filePosition + partSize
}
Step 3 Complete
CompleteMultipartUploadRequest compRequest new
CompleteMultipartUploadRequest(existingBucketName
keyName
initResponsegetUploadId()
partETags)
s3ClientcompleteMultipartUpload(compRequest)
} catch (Exception e) {
s3ClientabortMultipartUpload(new AbortMultipartUploadRequest(
existingBucketName keyName initResponsegetUploadId()))
}
API Version 20060301
178Amazon Simple Storage Service Developer Guide
Uploading Objects
Example
The following Java code example uploads a file to an Amazon S3 bucket For instructions on how to
create and test a working sample see Testing the Java Code Examples (p 564)
import javaioFile
import javaioIOException
import javautilArrayList
import javautilList
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelAbortMultipartUploadRequest
import comamazonawsservicess3modelCompleteMultipartUploadRequest
import comamazonawsservicess3modelInitiateMultipartUploadRequest
import comamazonawsservicess3modelInitiateMultipartUploadResult
import comamazonawsservicess3modelPartETag
import comamazonawsservicess3modelUploadPartRequest
public class UploadObjectMPULowLevelAPI {
public static void main(String[] args) throws IOException {
String existingBucketName *** ProvideYourExistingBucketName
***
String keyName *** ProvideKeyName ***
String filePath *** ProvideFilePath ***

AmazonS3 s3Client new AmazonS3Client(new
ProfileCredentialsProvider())
Create a list of UploadPartResponse objects You get one of these
for each part upload
List partETags new ArrayList()
Step 1 Initialize
InitiateMultipartUploadRequest initRequest new
InitiateMultipartUploadRequest(existingBucketName keyName)
InitiateMultipartUploadResult initResponse
s3ClientinitiateMultipartUpload(initRequest)
File file new File(filePath)
long contentLength filelength()
long partSize 5242880 Set part size to 5 MB
try {
Step 2 Upload parts
long filePosition 0
for (int i 1 filePosition < contentLength i++) {
Last part can be less than 5 MB Adjust part size
partSize Mathmin(partSize (contentLength filePosition))

Create request to upload a part
UploadPartRequest uploadRequest new UploadPartRequest()
withBucketName(existingBucketName)withKey(keyName)

withUploadId(initResponsegetUploadId())withPartNumber(i)
withFileOffset(filePosition)
withFile(file)
withPartSize(partSize)
Upload part and add response to our list
partETagsadd(
s3ClientuploadPart(uploadRequest)getPartETag())
filePosition + partSize
}
Step 3 Complete
CompleteMultipartUploadRequest compRequest new
CompleteMultipartUploadRequest(
existingBucketName
keyName
initResponsegetUploadId()
partETags)
s3ClientcompleteMultipartUpload(compRequest)
} catch (Exception e) {
s3ClientabortMultipartUpload(new AbortMultipartUploadRequest(
existingBucketName keyName
initResponsegetUploadId()))
}
}
}
API Version 20060301
179Amazon Simple Storage Service Developer Guide
Uploading Objects
List Multipart Uploads
The following tasks guide you through using the lowlevel Java classes to list all inprogress multipart
uploads on a bucket
LowLevel API Multipart Uploads Listing Process
1 Create an instance of the ListMultipartUploadsRequest class and provide the
bucket name
2 Execute the AmazonS3ClientlistMultipartUploads method The method returns
an instance of the MultipartUploadListing class that gives you information about
the multipart uploads in progress
The following Java code sample demonstrates the preceding tasks
ListMultipartUploadsRequest allMultpartUploadsRequest
new ListMultipartUploadsRequest(existingBucketName)
MultipartUploadListing multipartUploadListing
s3ClientlistMultipartUploads(allMultpartUploadsRequest)
Abort a Multipart Upload
You can abort an inprogress multipart upload by calling the AmazonS3abortMultipartUpload
method This method deletes any parts that were uploaded to Amazon S3 and frees up the resources
You must provide the upload ID bucket name and key name The following Java code sample
demonstrates how to abort an inprogress multipart upload
InitiateMultipartUploadRequest initRequest
new InitiateMultipartUploadRequest(existingBucketName keyName)
InitiateMultipartUploadResult initResponse
s3ClientinitiateMultipartUpload(initRequest)
AmazonS3 s3Client new AmazonS3Client(new ProfileCredentialsProvider())
s3ClientabortMultipartUpload(new AbortMultipartUploadRequest(
existingBucketName keyName initResponsegetUploadId()))
Note
Instead of a specific multipart upload you can abort all your multipart uploads initiated before
a specific time that are still in progress This cleanup operation is useful to abort old multipart
uploads that you initiated but neither completed nor aborted For more information see Abort
Multipart Uploads (p 173)
API Version 20060301
180Amazon Simple Storage Service Developer Guide
Uploading Objects
Using the AWS NET SDK for Multipart Upload (HighLevel API)
Topics
• Upload a File (p 181)
• Upload a Directory (p 183)
• Abort Multipart Uploads (p 185)
• Track Multipart Upload Progress (p 186)
The AWS SDK for NET exposes a highlevel API that simplifies multipart upload (see Uploading
Objects Using Multipart Upload API (p 165)) You can upload data from a file directory or a stream
When uploading data from a file if you don＇t provide the object＇s key name the API uses the file
name for the object＇s key name You must provide the object＇s key name if you are uploading data
from a stream You can optionally set advanced options such as the part size you want to use for the
multipart upload number of threads you want to use when uploading the parts concurrently optional
file metadata the storage class (STANDARD or REDUCED_REDUNDANCY) or ACL The highlevel
API provides the TransferUtilityUploadRequest class to set these advanced options
The TransferUtility class provides a method for you to abort multipart uploads in progress You
must provide a DateTime value and then the API aborts all the multipart uploads that were initiated
before the specified date and time
Upload a File
The following tasks guide you through using the highlevel NET classes to upload a file The API
provides several variations overloads of the Upload method to easily upload your data
HighLevel API File Uploading Process
1 Create an instance of the TransferUtility class by providing your AWS credentials
2 Execute one of the TransferUtilityUpload overloads depending on whether you
are uploading data from a file a stream or a directory
The following C# code sample demonstrates the preceding tasks
TransferUtility utility new TransferUtility()
utilityUpload(filePath existingBucketName)
When uploading large files using the NET API timeout might occur even while
data is being written to the request stream You can set explicit timeout using the
TransferUtilityConfigDefaultTimeout as demonstrated in the following C# code sample
TransferUtilityConfig config new TransferUtilityConfig()
configDefaultTimeout 11111
TransferUtility utility new TransferUtility(config)
API Version 20060301
181Amazon Simple Storage Service Developer Guide
Uploading Objects
Example
The following C# code example uploads a file to an Amazon S3 bucket The example illustrates
the use of various TransferUtilityUpload overloads to upload a file each successive call to
upload replaces the previous upload For instructions on how to create and test a working sample see
Running the Amazon S3 NET Code Examples (p 566)
using System
using SystemIO
using AmazonS3
using AmazonS3Transfer
namespace s3amazoncomdocsamples
{
class UploadFileMPUHighLevelAPI
{
static string existingBucketName *** Provide bucket name ***
static string keyName *** Provide your object key ***
static string filePath *** Provide file name ***
static void Main(string[] args)
{
try
{
TransferUtility fileTransferUtility new
TransferUtility(new
AmazonS3Client(AmazonRegionEndpointUSEast1))
1 Upload a file file name is used as the object key
name
fileTransferUtilityUpload(filePath existingBucketName)
ConsoleWriteLine(Upload 1 completed)
2 Specify object key name explicitly
fileTransferUtilityUpload(filePath
existingBucketName keyName)
ConsoleWriteLine(Upload 2 completed)
3 Upload data from a type of SystemIOStream
using (FileStream fileToUpload
new FileStream(filePath FileModeOpen FileAccessRead))
{
fileTransferUtilityUpload(fileToUpload
existingBucketName keyName)
}
ConsoleWriteLine(Upload 3 completed)
4Specify advanced settingsoptions
TransferUtilityUploadRequest fileTransferUtilityRequest new
TransferUtilityUploadRequest
{
BucketName existingBucketName
FilePath filePath
StorageClass S3StorageClassReducedRedundancy
PartSize 6291456 6 MB
Key keyName
CannedACL S3CannedACLPublicRead
}
fileTransferUtilityRequestMetadataAdd(param1 Value1)
fileTransferUtilityRequestMetadataAdd(param2 Value2)
fileTransferUtilityUpload(fileTransferUtilityRequest)
ConsoleWriteLine(Upload 4 completed)
}
catch (AmazonS3Exception s3Exception)
{
ConsoleWriteLine(s3ExceptionMessage
s3ExceptionInnerException)
}
}
}
}
API Version 20060301
182Amazon Simple Storage Service Developer Guide
Uploading Objects
Upload a Directory
Using the TransferUtility class you can also upload an entire directory By default Amazon S3
only uploads the files at the root of the specified directory You can however specify to recursively
upload files in all the subdirectories
You can also specify filtering expressions to select files in the specified directory based on some
filtering criteria For example to upload only the pdf files from a directory you specify a *pdf filter
expression
When uploading files from a directory you cannot specify the object＇s key name It is constructed from
the file＇s location in the directory as well as its name For example assume you have a directory c
＼myfolder with the following structure
C＼myfolder
＼atxt
＼bpdf
＼media＼
Anmp3
When you upload this directory Amazon S3 uses the following key names
atxt
bpdf
mediaAnmp3
The following tasks guide you through using the highlevel NET classes to upload a directory
HighLevel API Directory Uploading Process
1 Create an instance of the TransferUtility class by providing your AWS credentials
2 Execute one of the TransferUtilityUploadDirectory overloads
The following C# code sample demonstrates the preceding tasks
TransferUtility utility new TransferUtility()
utilityUploadDirectory(directoryPath existingBucketName)
API Version 20060301
183Amazon Simple Storage Service Developer Guide
Uploading Objects
ExampleThe following C# code example uploads a directory to an Amazon S3 bucket The example illustrates
the use of various TransferUtilityUploadDirectory overloads to upload a directory each
successive call to upload replaces the previous upload For instructions on how to create and test a
working sample see Running the Amazon S3 NET Code Examples (p 566)using System
using SystemIO
using AmazonS3
using AmazonS3Transfer
namespace s3amazoncomdocsamples
{
class UploadDirectoryMPUHighLevelAPI
{
static string existingBucketName *** Provide bucket name ***
static string directoryPath *** Provide directory name ***
static void Main(string[] args)
{
try
{
TransferUtility directoryTransferUtility
new TransferUtility(new
AmazonS3Client(AmazonRegionEndpointUSEast1))
1 Upload a directory
directoryTransferUtilityUploadDirectory(directoryPath
existingBucketName)
ConsoleWriteLine(Upload statement 1 completed)
2 Upload only the txt files from a directory
Also search recursively
directoryTransferUtilityUploadDirectory(
directoryPath
existingBucketName
*txt
SearchOptionAllDirectories)
ConsoleWriteLine(Upload statement 2 completed)
3 Same as 2 and some optional configuration
Search recursively for txt files to upload)
TransferUtilityUploadDirectoryRequest request
new TransferUtilityUploadDirectoryRequest
{
BucketName existingBucketName
Directory directoryPath
SearchOption SearchOptionAllDirectories
SearchPattern *txt
}
directoryTransferUtilityUploadDirectory(request)
ConsoleWriteLine(Upload statement 3 completed)
}
catch (AmazonS3Exception e)
{
ConsoleWriteLine(eMessage eInnerException)
}
}
}
}
API Version 20060301
184Amazon Simple Storage Service Developer Guide
Uploading Objects
Abort Multipart Uploads
The TransferUtility class provides a method AbortMultipartUploads to abort multipart
uploads in progress An upload is considered to be inprogress once you initiate it and until you
complete it or abort it You provide a DateTime value and this API aborts all the multipart uploads on
that bucket that were initiated before the specified DateTime and in progress
Because you are billed for all storage associated with uploaded parts (see Multipart Upload and
Pricing (p 167)) it is important that you either complete the multipart upload to have the object created
or abort the multipart upload to remove any uploaded parts
The following tasks guide you through using the highlevel NET classes to abort multipart uploads
HighLevel API Multipart Uploads Aborting Process
1 Create an instance of the TransferUtility class by providing your AWS credentials
2 Execute the TransferUtilityAbortMultipartUploads method by passing the
bucket name and a DateTime value
The following C# code sample demonstrates the preceding tasks
TransferUtility utility new TransferUtility()
utilityAbortMultipartUploads(existingBucketName DateTimeNowAddDays(7))
API Version 20060301
185Amazon Simple Storage Service Developer Guide
Uploading Objects
Example
The following C# code aborts all multipart uploads in progress that were initiated on a specific bucket
over a week ago For instructions on how to create and test a working sample see Running the
Amazon S3 NET Code Examples (p 566)
using System
using AmazonS3
using AmazonS3Transfer
namespace s3amazoncomdocsamples
{
class AbortMPUUsingHighLevelAPI
{
static string existingBucketName ***Provide bucket name***
static void Main(string[] args)
{
try
{
TransferUtility transferUtility
new TransferUtility(new
AmazonS3Client(AmazonRegionEndpointUSEast1))
Aborting uploads that were initiated over a week ago
transferUtilityAbortMultipartUploads(
existingBucketName DateTimeNowAddDays(7))
}
catch (AmazonS3Exception e)
{
ConsoleWriteLine(eMessage eInnerException)
}
}
}
}
Note
You can also abort a specific multipart upload For more information see List Multipart
Uploads (p 194)
Track Multipart Upload Progress
The highlevel multipart upload API provides an event
TransferUtilityUploadRequestUploadProgressEvent to track the upload progress when
uploading data using the TransferUtility class
The event occurs periodically and returns multipart upload progress information such as the total
number of bytes to transfer and the number of bytes transferred at the time event occurred
The following C# code sample demonstrates how you can subscribe to the UploadProgressEvent
event and write a handler
TransferUtility fileTransferUtility
new TransferUtility(new AmazonS3Client(AmazonRegionEndpointUSEast1))
Use TransferUtilityUploadRequest to configure options
In this example we subscribe to an event
TransferUtilityUploadRequest uploadRequest
new TransferUtilityUploadRequest
API Version 20060301
186Amazon Simple Storage Service Developer Guide
Uploading Objects
{
BucketName existingBucketName
FilePath filePath
Key keyName
}

uploadRequestUploadProgressEvent +
new EventHandler
(uploadRequest_UploadPartProgressEvent)
fileTransferUtilityUpload(uploadRequest)
static void uploadRequest_UploadPartProgressEvent(object sender
UploadProgressArgs e)
{
Process event
ConsoleWriteLine({0}{1} eTransferredBytes eTotalBytes)
}
API Version 20060301
187Amazon Simple Storage Service Developer Guide
Uploading Objects
ExampleThe following C# code example uploads a file to an Amazon S3 bucket and tracks the progress
by subscribing to the TransferUtilityUploadRequestUploadProgressEvent event For
instructions on how to create and test a working sample see Running the Amazon S3 NET Code
Examples (p 566)using System
using SystemCollectionsSpecialized
using SystemConfiguration
using AmazonS3
using AmazonS3Transfer
namespace s3amazoncomdocsamples
{
class TrackMPUUsingHighLevelAPI
{
static string existingBucketName *** Provide bucket name ***
static string keyName *** Provide key name ***
static string filePath *** Provide file to upload ***
static void Main(string[] args)
{
try
{
TransferUtility fileTransferUtility
new TransferUtility(new
AmazonS3Client(AmazonRegionEndpointUSEast1))
Use TransferUtilityUploadRequest to configure options
In this example we subscribe to an event
TransferUtilityUploadRequest uploadRequest
new TransferUtilityUploadRequest
{
BucketName existingBucketName
FilePath filePath
Key keyName
}

uploadRequestUploadProgressEvent +
new EventHandler
(uploadRequest_UploadPartProgressEvent)
fileTransferUtilityUpload(uploadRequest)
ConsoleWriteLine(Upload completed)
}
catch (AmazonS3Exception e)
{
ConsoleWriteLine(eMessage eInnerException)
}
}
static void uploadRequest_UploadPartProgressEvent(
object sender UploadProgressArgs e)
{
Process event
ConsoleWriteLine({0}{1} eTransferredBytes eTotalBytes)
}
}
}
API Version 20060301
188Amazon Simple Storage Service Developer Guide
Uploading Objects
API Version 20060301
189Amazon Simple Storage Service Developer Guide
Uploading Objects
Using the AWS NET SDK for Multipart Upload (LowLevel API)
Topics
• Upload a File (p 190)
• List Multipart Uploads (p 194)
• Track Multipart Upload Progress (p 194)
• Abort a Multipart Upload (p 194)
The AWS SDK for NET exposes a lowlevel API that closely resembles the Amazon S3 REST API for
multipart upload (see Using the REST API for Multipart Upload (p 205) ) Use the lowlevel API when
you need to pause and resume multipart uploads vary part sizes during the upload or do not know the
size of the data in advance Use the highlevel API (see Using the AWS NET SDK for Multipart Upload
(HighLevel API) (p 181)) whenever you don＇t have these requirements
Upload a File
The following tasks guide you through using the lowlevel NET classes to upload a file
LowLevel API File UploadingProcess
1 Create an instance of the AmazonS3Client class by providing your AWS credentials
2 Initiate multipart upload by executing the
AmazonS3ClientInitiateMultipartUpload method You will need to provide
information required to initiate the multipart upload by creating an instance of the
InitiateMultipartUploadRequest class
3 Save the Upload ID that the AmazonS3ClientInitiateMultipartUpload method
returns You will need to provide this upload ID for each subsequent multipart upload
operation
4 Upload the parts For each part upload execute the AmazonS3ClientUploadPart
method You will need to provide part upload information such as upload ID bucket
name and the part number You provide this information by creating an instance of the
UploadPartRequest class
5 Save the response of the AmazonS3ClientUploadPart method in a list This
response includes the ETag value and the part number you will later need to complete
the multipart upload
6 Repeat tasks 4 and 5 for each part
7 Execute the AmazonS3ClientCompleteMultipartUpload method to complete the
multipart upload
The following C# code sample demonstrates the preceding tasks
IAmazonS3 s3Client new AmazonS3Client(AmazonRegionEndpointUSEast1)
List to store upload part responses
List uploadResponses new List()
1 Initialize
InitiateMultipartUploadRequest initiateRequest new
InitiateMultipartUploadRequest
{
BucketName existingBucketName
API Version 20060301
190Amazon Simple Storage Service Developer Guide
Uploading Objects
Key keyName
}
InitiateMultipartUploadResponse initResponse
s3ClientInitiateMultipartUpload(initRequest)
2 Upload Parts
long contentLength new FileInfo(filePath)Length
long partSize 5242880 5 MB
try
{
long filePosition 0
for (int i 1 filePosition < contentLength i++)
{
Create request to upload a part
UploadPartRequest uploadRequest new UploadPartRequest
{
BucketName existingBucketName
Key keyName
UploadId initResponseUploadId
PartNumber i
PartSize partSize
FilePosition filePosition
FilePath filePath
}
Upload part and add response to our list
uploadResponsesAdd(s3ClientUploadPart(uploadRequest))
filePosition + partSize
}
Step 3 complete
CompleteMultipartUploadRequest completeRequest new
CompleteMultipartUploadRequest
{
BucketName existingBucketName
Key keyName
UploadId initResponseUploadId
}
CompleteMultipartUploadResponse completeUploadResponse
s3ClientCompleteMultipartUpload(completeRequest)

}
catch (Exception exception)
{
ConsoleWriteLine(Exception occurred {0} exceptionMessage)
AbortMultipartUploadRequest abortMPURequest new
AbortMultipartUploadRequest
{
BucketName existingBucketName
Key keyName
UploadId initResponseUploadId
}
s3ClientAbortMultipartUpload(abortMPURequest)
API Version 20060301
191Amazon Simple Storage Service Developer Guide
Uploading Objects
}
Note
When uploading large objects using the NET API timeout might occur even while
data is being written to the request stream You can set explicit timeout using the
UploadPartRequest
API Version 20060301
192Amazon Simple Storage Service Developer Guide
Uploading Objects
Example
The following C# code example uploads a file to an Amazon S3 bucket For instructions on how to
create and test a working sample see Running the Amazon S3 NET Code Examples (p 566)
using System
using SystemCollectionsGeneric
using SystemIO
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class UploadFileMPULowLevelAPI
{
static string existingBucketName *** bucket name ***
static string keyName *** key name ***
static string filePath *** file path ***
static void Main(string[] args)
{
IAmazonS3 s3Client new
AmazonS3Client(AmazonRegionEndpointUSEast1)
List to store upload part responses
List uploadResponses new
List()
1 Initialize
InitiateMultipartUploadRequest initiateRequest new
InitiateMultipartUploadRequest
{
BucketName existingBucketName
Key keyName
}
InitiateMultipartUploadResponse initResponse
s3ClientInitiateMultipartUpload(initiateRequest)
2 Upload Parts
long contentLength new FileInfo(filePath)Length
long partSize 5 * (long)MathPow(2 20) 5 MB
try
{
long filePosition 0
for (int i 1 filePosition < contentLength i++)
{
UploadPartRequest uploadRequest new UploadPartRequest
{
BucketName existingBucketName
Key keyName
UploadId initResponseUploadId
PartNumber i
PartSize partSize
FilePosition filePosition
FilePath filePath
}
Upload part and add response to our list
uploadResponsesAdd(s3ClientUploadPart(uploadRequest))
filePosition + partSize
}
Step 3 complete
CompleteMultipartUploadRequest completeRequest new
CompleteMultipartUploadRequest
{
BucketName existingBucketName
Key keyName
UploadId initResponseUploadId
PartETags new List(uploadResponses)
}
completeRequestAddPartETags(uploadResponses)
CompleteMultipartUploadResponse completeUploadResponse
s3ClientCompleteMultipartUpload(completeRequest)
}
catch (Exception exception)
{
ConsoleWriteLine(Exception occurred {0}
exceptionMessage)
AbortMultipartUploadRequest abortMPURequest new
AbortMultipartUploadRequest
{
BucketName existingBucketName
Key keyName
UploadId initResponseUploadId
}
s3ClientAbortMultipartUpload(abortMPURequest)
}
}
}
}
API Version 20060301
193Amazon Simple Storage Service Developer Guide
Uploading Objects
List Multipart Uploads
The following tasks guide you through using the lowlevel NET classes to list all inprogress multipart
uploads on a bucket
LowLevel API Multipart Uploads Listing Process
1 Create an instance of the ListMultipartUploadsRequest class and provide the
bucket name
2 Execute the AmazonS3ClientListMultipartUploads method The method
returns an instance of the ListMultipartUploadsResponse class providing you the
information about the inprogress multipart uploads
The following C# code sample demonstrates the preceding tasks
ListMultipartUploadsRequest request new ListMultipartUploadsRequest
{
BucketName existingBucketName
}
Track Multipart Upload Progress
The lowlevel multipart upload API provides an event
UploadPartRequestStreamTransferProgress to track the upload progress
The event occurs periodically and returns multipart upload progress information such as the total
number of bytes to transfer and the number of bytes transferred at the time event occurred
The following C# code sample demonstrates how you can subscribe to the
StreamTransferProgress event and write a handler
UploadPartRequest uploadRequest new UploadPartRequest
{
provide request data
}
uploadRequestStreamTransferProgress +
new
EventHandler(UploadPartProgressEventCallback)

public static void UploadPartProgressEventCallback(object sender
StreamTransferProgressArgs e)
{
Process event
ConsoleWriteLine({0}{1} eTransferredBytes eTotalBytes)
}
Abort a Multipart Upload
You can abort an inprogress multipart upload by calling the AmazonS3ClientAbortMultipartUpload
method This method deletes any parts that were uploaded to S3 and free up the resources You must
provide the upload ID bucket name and the key name The following C# code sample demonstrates
how you can abort a multipart upload in progress
s3ClientAbortMultipartUpload(new AbortMultipartUploadRequest
API Version 20060301
194Amazon Simple Storage Service Developer Guide
Uploading Objects
{
BucketName existingBucketName
Key keyName
UploadId uploadID
}
Note
Instead of a specific multipart upload you can abort all your inprogress multipart uploads
initiated prior to a specific time This clean up operation is useful to abort old multipart uploads
that you initiated but neither completed or aborted For more information see Abort Multipart
Uploads (p 185)
API Version 20060301
195Amazon Simple Storage Service Developer Guide
Uploading Objects
Using the AWS PHP SDK for Multipart Upload (HighLevel API)
Amazon S3 allows you to upload large files in multiple parts You must use a multipart upload for
files larger than 5 GB The AWS SDK for PHP exposes the highlevel Aws＼S3＼Model＼MultipartUpload
＼UploadBuilder class that simplifies multipart uploads
The Aws＼S3＼Model＼MultipartUpload＼UploadBuilder class is best used for a simple multipart
upload If you need to pause and resume multipart uploads vary part sizes during the upload or do not
know the size of the data in advance you should use the lowlevel PHP API For more information see
Using the AWS PHP SDK for Multipart Upload (LowLevel API) (p 200)
For more information about multipart uploads see Uploading Objects Using Multipart Upload
API (p 165) For information on uploading files that are less than 5GB in size see Upload an Object
Using the AWS SDK for PHP (p 161)
Upload a File Using the HighLevel Multipart Upload
This topic guides you through using the highlevel Aws＼S3＼Model＼MultipartUpload
＼UploadBuilder class from the AWS SDK for PHP for multipart file uploads
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
HighLevel Multipart File Upload Process
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 Create an instance of the UploadBuilder using the Amazon S3 Aws＼S3＼Model
＼MultipartUpload＼UploadBuilder class newInstance() method which is inherited
from the Aws＼Common＼Model＼MultipartUpload＼AbstractUploadBuilder class For the
UploadBuilder object set the client the bucket name and the key name using the
setClient() setBucket() and setKey() methods Set the path and name of the file you
want to upload with the setSource() method
3 Execute the UploadBuilder object＇s build() method to build the appropriate uploader
transfer object based on the builder options you set (The transfer object is of a subclass
of the Aws＼S3＼Model＼MultipartUpload＼AbstractTransfer class)
4 Execute the upload() method of the built transfer object to perform the upload
The following PHP code sample demonstrates how to upload a file using the highlevel
UploadBuilder object
use Aws＼Common＼Exception＼MultipartUploadException
use Aws＼S3＼Model＼MultipartUpload＼UploadBuilder
use Aws＼S3＼S3Client
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇

Instantiate the client
s3 S3Clientfactory()
Prepare the upload parameters
uploader UploadBuildernewInstance()
>setClient(s3)
>setSource(＇pathtolargefilemov＇)
API Version 20060301
196Amazon Simple Storage Service Developer Guide
Uploading Objects
>setBucket(bucket)
>setKey(keyname)
>build()
Perform the upload Abort the upload if something goes wrong
try {
uploader>upload()
echo Upload complete＼n
} catch (MultipartUploadException e) {
uploader>abort()
echo Upload failed＼n
echo e>getMessage() ＼n
}
API Version 20060301
197Amazon Simple Storage Service Developer Guide
Uploading Objects
Example of a Multipart Upload of a File to an Amazon S3 Bucket Using the Highlevel
UploadBuilder
The following PHP example uploads a file to an Amazon S3 bucket The example demonstrates how
to set advanced options for the UploadBuilder object For example you can use the setMinPartSize()
method to set the part size you want to use for the multipart upload and the setOption() method to set
optional file metadata or an access control list (ACL)
The example also demonstrates how to upload file parts in parallel by setting the concurrency option
using the setConcurrency() method for the UploadBuilder object The example creates a transfer object
that will attempt to upload three parts in parallel until the entire file has been uploaded For information
about running the PHP examples in this guide go to Running PHP Examples (p 567)
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
use Aws＼Common＼Exception＼MultipartUploadException
use Aws＼S3＼Model＼MultipartUpload＼UploadBuilder
use Aws＼S3＼S3Client
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇

Instantiate the client
s3 S3Clientfactory()

Prepare the upload parameters
uploader UploadBuildernewInstance()
>setClient(s3)
>setSource(＇pathtolargefilemov＇)
>setBucket(bucket)
>setKey(keyname)
>setMinPartSize(25 * 1024 * 1024)
>setOption(＇Metadata＇ array(
＇param1＇ > ＇value1＇
＇param2＇ > ＇value2＇
))
>setOption(＇ACL＇ ＇publicread＇)
>setConcurrency(3)
>build()
Perform the upload Abort the upload if something goes wrong
try {
uploader>upload()
echo Upload complete＼n
} catch (MultipartUploadException e) {
uploader>abort()
echo Upload failed＼n
echo e>getMessage() ＼n
}
Related Resources
• AWS SDK for PHP Aws＼Common＼Model＼MultipartUpload＼AbstractUploadBuilder Class
• AWS SDK for PHP Aws＼Common＼Model＼MultipartUpload＼AbstractUploadBuildernewInstance()
Method
API Version 20060301
198Amazon Simple Storage Service Developer Guide
Uploading Objects
• AWS SDK for PHP Aws＼Common＼Model＼MultipartUpload＼AbstractUploadBuilderSetSource()
Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼Model＼MultipartUpload＼UploadBuilder Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼Model＼MultipartUpload＼UploadBuilderbuild() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼Model＼MultipartUpload＼UploadBuildersetMinPartSize()
Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼Model＼MultipartUpload＼UploadBuildersetOption() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼Model＼MultipartUpload＼UploadBuildersetConcurrency()
Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Uploading Large Files Using Multipart Uploads
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
API Version 20060301
199Amazon Simple Storage Service Developer Guide
Uploading Objects
Using the AWS PHP SDK for Multipart Upload (LowLevel API)
Topics
• Upload a File in Multiple Parts Using the PHP SDK LowLevel API (p 200)
• List Multipart Uploads Using the LowLevel AWS SDK for PHP API (p 203)
• Abort a Multipart Upload (p 203)
The AWS SDK for PHP exposes a lowlevel API that closely resembles the Amazon S3 REST API for
multipart upload (see Using the REST API for Multipart Upload (p 205) ) Use the lowlevel API when
you need to pause and resume multipart uploads vary part sizes during the upload or do not know the
size of the data in advance Use the AWS SDK for PHP highlevel abstractions (see Using the AWS
PHP SDK for Multipart Upload (HighLevel API) (p 196)) whenever you don＇t have these requirements
Upload a File in Multiple Parts Using the PHP SDK LowLevel API
This topic guides you through using lowlevel multipart upload classes from the AWS SDK for PHP to
upload a file in multiple parts
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
PHP SDK LowLevel API Multipart File Upload Process
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 Initiate multipart upload by executing the Aws＼S3＼S3ClientcreateMultipartUpload()
method You must provide a bucket name and a key name in the array parameter＇s
required keys Bucket and Key
Retrieve and save the UploadID from the response body The UploadID is used in
each subsequent multipart upload operation
3 Upload the file in parts by executing the Aws＼S3＼S3ClientuploadPart() method for
each file part until the end of the file is reached The required array parameter keys for
upload_part() are Bucket Key UploadId and PartNumber You must increment
the value passed as the argument for the PartNumber key for each subsequent call to
upload_part() to upload each successive file part
Save the response of each of the upload_part() methods calls in an array Each
response includes the ETag value you will later need to complete the multipart upload
4 Execute the Aws＼S3＼S3ClientcompleteMultipartUpload() method to complete the
multipart upload The required array parameters for completeMultipartUpload()
are Bucket Key and UploadId
The following PHP code example demonstrates uploading a file in multiple parts using the PHP SDK
lowlevel API
use Aws＼S3＼S3Client
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇
filename ＇*** Path to and Name of the File to Upload ***＇

1 Instantiate the client
API Version 20060301
200Amazon Simple Storage Service Developer Guide
Uploading Objects
s3 S3Clientfactory()
2 Create a new multipart upload and get the upload ID
response s3>createMultipartUpload(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
))
uploadId response[＇UploadId＇]
3 Upload the file in parts
file fopen(filename ＇r＇)
parts array()
partNumber 1
while (feof(file)) {
result s3>uploadPart(array(
＇Bucket＇ > bucket
＇Key＇ > key
＇UploadId＇ > uploadId
＇PartNumber＇ > partNumber
＇Body＇ > fread(file 5 * 1024 * 1024)
))
parts[] array(
＇PartNumber＇ > partNumber++
＇ETag＇ > result[＇ETag＇]
)
}
4 Complete multipart upload
result s3>completeMultipartUpload(array(
＇Bucket＇ > bucket
＇Key＇ > key
＇UploadId＇ > uploadId
＇Parts＇ > parts
))
url result[＇Location＇]
fclose(file)
API Version 20060301
201Amazon Simple Storage Service Developer Guide
Uploading Objects
Example of Uploading a File to an Amazon S3 Bucket Using the Lowlevel Multipart
Upload PHP SDK API
The following PHP code example uploads a file to an Amazon S3 bucket using the lowlevel PHP API
multipart upload For information about running the PHP examples in this guide go to Running PHP
Examples (p 567)
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
use Aws＼S3＼S3Client
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇
filename ＇*** Path to and Name of the File to Upload ***＇
1 Instantiate the client
s3 S3Clientfactory()
2 Create a new multipart upload and get the upload ID
result s3>createMultipartUpload(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇StorageClass＇ > ＇REDUCED_REDUNDANCY＇
＇ACL＇ > ＇publicread＇
＇Metadata＇ > array(
＇param1＇ > ＇value 1＇
＇param2＇ > ＇value 2＇
＇param3＇ > ＇value 3＇
)
))
uploadId result[＇UploadId＇]
3 Upload the file in parts
try {
file fopen(filename ＇r＇)
parts array()
partNumber 1
while (feof(file)) {
result s3>uploadPart(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇UploadId＇ > uploadId
＇PartNumber＇ > partNumber
＇Body＇ > fread(file 5 * 1024 * 1024)
))
parts[] array(
＇PartNumber＇ > partNumber++
＇ETag＇ > result[＇ETag＇]
)
echo Uploading part {partNumber} of {filename}＼n
}
fclose(file)
} catch (S3Exception e) {
result s3>abortMultipartUpload(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇UploadId＇ > uploadId
))
echo Upload of {filename} failed＼n
}
4 Complete multipart upload
result s3>completeMultipartUpload(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇UploadId＇ > uploadId
＇Parts＇ > parts
))
url result[＇Location＇]
echo Uploaded {filename} to {url}＼n
API Version 20060301
202Amazon Simple Storage Service Developer Guide
Uploading Objects
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientcreateMultipartUpload() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientuploadPart()Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientcompleteMultipartUpload() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
List Multipart Uploads Using the LowLevel AWS SDK for PHP API
This topic guides you through using the lowlevel API classes from the AWS SDK for PHP to list all in
progress multipart uploads on a bucket
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
PHP SDK LowLevel API Multipart Uploads Listing Process
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 Execute the Aws＼S3＼S3ClientlistMultipartUploads() method by providing a bucket
name The method returns all of the inprogress multipart uploads on the specified
bucket
The following PHP code sample demonstrates listing all inprogress multipart uploads on a bucket
use Aws＼S3＼S3Client
s3 S3Clientfactory()
bucket ＇*** Your Bucket Name ***＇
result s3>listMultipartUploads(array(＇Bucket＇ > bucket))
print_r(result>toArray())
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientlistMultipartUploads() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
Abort a Multipart Upload
This topic describes how to use a class from the AWS SDK for PHP to abort a multipart upload that is
in progress
API Version 20060301
203Amazon Simple Storage Service Developer Guide
Uploading Objects
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
Aborting a Multipart Upload
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 Execute the Aws＼S3＼S3ClientabortMultipartUpload() method You must provide a bucket
name a key name and the upload ID in the array parameter＇s required keys Bucket
Key and UploadId
The abortMultipartUpload() method deletes any parts that were uploaded to
Amazon S3 and frees up the resources
Example of Aborting a Multipart Upload
The following PHP code example demonstrates how you can abort a multipart upload in progress The
example illustrates the use of the abortMultipartUpload() method For information about running
the PHP examples in this guide go to Running PHP Examples (p 567)
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇
Instantiate the client
s3 S3Clientfactory()
Abort the multipart upload
s3>abortMultipartUpload(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
＇UploadId＇ >
＇VXBsb2FkIElExampleBlbHZpbmcncyBtExamplepZS5tMnRzIHVwbG9hZ＇
))
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientabortMultipartUpload() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
Using the AWS SDK for Ruby for Multipart Upload
The AWS SDK for Ruby supports Amazon S3 multipart uploads by using the class
AWSS3MultipartUpload For more information about using the AWS SDK for Ruby with Amazon S3
go to Using the AWS SDK for Ruby Version 2 (p 568)
API Version 20060301
204Amazon Simple Storage Service Developer Guide
Uploading Objects
Using the REST API for Multipart Upload
The following sections in the Amazon Simple Storage Service API Reference describe the REST API
for multipart upload
• Initiate Multipart Upload
• Upload Part
• Complete Multipart Upload
• Abort Multipart Upload
• List Parts
• List Multipart Uploads
You can use these APIs to make your own REST requests or you can use one the SDKs we provide
For more information about the SDKs see API Support for Multipart Upload (p 169)
API Version 20060301
205Amazon Simple Storage Service Developer Guide
Uploading Objects
Uploading Objects Using PreSigned URLs
Topics
• Upload an Object Using a PreSigned URL (AWS SDK for Java) (p 206)
• Upload an Object Using a PreSigned URL (AWS SDK for NET) (p 209)
• Upload an Object Using a PreSigned URL (AWS SDK for Ruby) (p 211)
A presigned URL gives you access to the object identified in the URL provided that the creator
of the presigned URL has permissions to access that object That is if you receive a presigned
URL to upload an object you can upload the object only if the creator of the presigned URL has the
necessary permissions to upload that object
All objects and buckets by default are private The presigned URLs are useful if you want your user
customer to be able upload a specific object to your bucket but you don＇t require them to have AWS
security credentials or permissions When you create a presigned URL you must provide your
security credentials specify a bucket name an object key an HTTP method (PUT for uploading
objects) and an expiration date and time The presigned URLs are valid only for the specified
duration
You can generate a presigned URL programmatically using the AWS SDK for Java or the AWS
SDK for NET If you are using Visual Studio you can also use AWS Explorer to generate a pre
signed object URL without writing any code Anyone who receives a valid presigned URL can then
programmatically upload an object
For more information go to Using Amazon S3 from AWS Explorer
For instructions about how to install AWS Explorer see Using the AWS SDKs CLI and
Explorers (p 560)
Note
Anyone with valid security credentials can create a presigned URL However in order to
successfully upload an object the presigned URL must be created by someone who has
permission to perform the operation that the presigned URL is based upon
Upload an Object Using a PreSigned URL (AWS SDK for Java)
The following tasks guide you through using the Java classes to upload an object using a presigned
URL
Uploading Objects
1 Create an instance of the AmazonS3 class
2 Generate a presigned URL by executing the AmazonS3generatePresignedUrl
method
You provide a bucket name an object key and an expiration date by creating an instance
of the GeneratePresignedUrlRequest class You must specify the HTTP verb PUT
when creating this URL if you want to use it to upload an object
3 Anyone with the presigned URL can upload an object
The upload creates an object or replaces any existing object with the same key that is
specified in the presigned URL
The following Java code sample demonstrates the preceding tasks
AmazonS3 s3Client new AmazonS3Client(new ProfileCredentialsProvider())
javautilDate expiration new javautilDate()
API Version 20060301
206Amazon Simple Storage Service Developer Guide
Uploading Objects
long msec expirationgetTime()
msec + 1000 * 60 * 60 Add 1 hour
expirationsetTime(msec)
GeneratePresignedUrlRequest generatePresignedUrlRequest new
GeneratePresignedUrlRequest(bucketName objectKey)
generatePresignedUrlRequestsetMethod(HttpMethodPUT)
generatePresignedUrlRequestsetExpiration(expiration)

URL s s3clientgeneratePresignedUrl(generatePresignedUrlRequest)
Use the presigned URL to upload an object
API Version 20060301
207Amazon Simple Storage Service Developer Guide
Uploading Objects
Example
The following Java code example generates a presigned URL The example code then uses the
presigned URL to upload sample data as an object For instructions about how to create and test a
working sample see Testing the Java Code Examples (p 564)
import javaioIOException
import javaioOutputStreamWriter
import javanetHttpURLConnection
import javanetURL
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsHttpMethod
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelGeneratePresignedUrlRequest
public class GeneratePresignedUrlAndUploadObject {
private static String bucketName *** bucket name ***
private static String objectKey *** object key ***
public static void main(String[] args) throws IOException {
AmazonS3 s3client new AmazonS3Client(new ProfileCredentialsProvider())
try {
Systemoutprintln(Generating presigned URL)
javautilDate expiration new javautilDate()
long milliSeconds expirationgetTime()
milliSeconds + 1000 * 60 * 60 Add 1 hour
expirationsetTime(milliSeconds)
GeneratePresignedUrlRequest generatePresignedUrlRequest
new GeneratePresignedUrlRequest(bucketName objectKey)
generatePresignedUrlRequestsetMethod(HttpMethodPUT)
generatePresignedUrlRequestsetExpiration(expiration)
URL url s3clientgeneratePresignedUrl(generatePresignedUrlRequest)
UploadObject(url)
Systemoutprintln(PreSigned URL + urltoString())
} catch (AmazonServiceException exception) {
Systemoutprintln(Caught an AmazonServiceException +
which means your request made it +
to Amazon S3 but was rejected with an error response +
for some reason)
Systemoutprintln(Error Message + exceptiongetMessage())
Systemoutprintln(HTTP Code + exceptiongetStatusCode())
Systemoutprintln(AWS Error Code + exceptiongetErrorCode())
Systemoutprintln(Error Type + exceptiongetErrorType())
Systemoutprintln(Request ID + exceptiongetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException +
which means the client encountered +
an internal error while trying to communicate +
with S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
public static void UploadObject(URL url) throws IOException
{
HttpURLConnection connection(HttpURLConnection) urlopenConnection()
connectionsetDoOutput(true)
connectionsetRequestMethod(PUT)
OutputStreamWriter out new OutputStreamWriter(
connectiongetOutputStream())
outwrite(This text uploaded as object)
outclose()
int responseCode connectiongetResponseCode()
Systemoutprintln(Service returned response code + responseCode)
}
}
API Version 20060301
208Amazon Simple Storage Service Developer Guide
Uploading Objects
Upload an Object Using a PreSigned URL (AWS SDK for NET)
The following tasks guide you through using the NET classes to upload an object using a presigned
URL
Uploading Objects
1 Create an instance of the AmazonS3 class
These credentials are used in creating a signature for authentication when you generate
a presigned URL
2 Generate a presigned URL by executing the AmazonS3GetPreSignedURL method
You provide a bucket name an object key and an expiration date by creating an instance
of the GetPreSignedUrlRequest class You must specify the HTTP verb PUT when
creating this URL if you plan to use it to upload an object
3 Anyone with the presigned URL can upload an object You can create an instance of the
HttpWebRequest class by providing the presigned URL and uploading the object
The following C# code sample demonstrates the preceding tasks
IAmazonS3 client
client new AmazonS3Client(AmazonRegionEndpointUSEast1)
Generate a presigned URL
GetPreSignedUrlRequest request new GetPreSignedUrlRequest
{
BucketName bucketName
Key objectKey
Verb HttpVerbPUT
Expires DateTimeNowAddMinutes(5)
}
string url null
url s3ClientGetPreSignedURL(request)
Upload a file using the presigned URL
HttpWebRequest httpRequest WebRequestCreate(url) as HttpWebRequest
httpRequestMethod PUT
using (Stream dataStream httpRequestGetRequestStream())
{
Upload object
}
HttpWebResponse response httpRequestGetResponse() as HttpWebResponse
API Version 20060301
209Amazon Simple Storage Service Developer Guide
Uploading Objects
Example
The following C# code example generates a presigned URL for a specific object and uses it to upload
a file For instructions about how to create and test a working sample see Running the Amazon
S3 NET Code Examples (p 566)
using System
using SystemIO
using SystemNet
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class UploadObjcetUsingPresignedURL
{
static IAmazonS3 s3Client
File to upload
static string filePath *** Specify file to upload ***
Information to generate presigned object URL
static string bucketName *** Provide bucket name ***
static string objectKey *** Provide object key for the new object
***
public static void Main(string[] args)
{
try
{
using (s3Client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
string url GeneratePreSignedURL()
UploadObject(url)
}
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&
(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS Credentials)
ConsoleWriteLine(
To sign up for service go to httpawsamazoncom
s3)
}
else
{
ConsoleWriteLine(
Error occurred Message＇{0}＇ when listing objects
amazonS3ExceptionMessage)
}
}
catch (Exception e)
{
ConsoleWriteLine(eMessage)
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static void UploadObject(string url)
{
HttpWebRequest httpRequest WebRequestCreate(url) as
HttpWebRequest
httpRequestMethod PUT
using (Stream dataStream httpRequestGetRequestStream())
{
byte[] buffer new byte[8000]
using (FileStream fileStream new FileStream(filePath
FileModeOpen FileAccessRead))
{
int bytesRead 0
while ((bytesRead fileStreamRead(buffer 0
bufferLength)) > 0)
{
dataStreamWrite(buffer 0 bytesRead)
}
}
}
HttpWebResponse response httpRequestGetResponse() as
HttpWebResponse
}
static string GeneratePreSignedURL()
{
GetPreSignedUrlRequest request new GetPreSignedUrlRequest
{
BucketName bucketName
Key objectKey
Verb HttpVerbPUT
Expires DateTimeNowAddMinutes(5)
}

string url null
url s3ClientGetPreSignedURL(request)
return url
}
}
}
API Version 20060301
210Amazon Simple Storage Service Developer Guide
Uploading Objects
Upload an Object Using a PreSigned URL (AWS SDK for Ruby)
The following tasks guide you through using a Ruby script to upload an object using a presigned URL
for either version of the SDK for Ruby
Topics
• Using AWS SDK for Ruby Version 2 (p 211)
• Using AWS SDK for Ruby Version 1 (p 212)
Using AWS SDK for Ruby Version 2
The following tasks guide you through using a Ruby script to upload an object using a presigned URL
for SDK for Ruby Version 2
Uploading Objects SDK for Ruby Version 2
1 Create an instance of the AwsS3Resource class
2 You provide a bucket name and an object key by calling the #bucket[] and the
#object[] methods of your AwsS3Resource class instance
Generate a presigned URL by creating an instance of the URI class and use it to parse
the presigned_url method of your AwsS3Resource class instance You
must specify put as an argument to presigned_url and you must specify PUT to
NetHTTPSession#send_request if you want to upload an object
3 Anyone with the presigned URL can upload an object
The upload creates an object or replaces any existing object with the same key that is
specified in the presigned URL
The following Ruby code sample demonstrates the preceding tasks for SDK for Ruby Version 2
#Uploading an object using a presigned URL for SDK for Ruby Version 2
require ＇awssdkresources＇
require ＇nethttp＇
s3 AwsS3Resourcenew(region＇uswest2＇)
obj s3bucket(＇BucketName＇)object(＇KeyName＇)
# Replace BucketName with the name of your bucket
# Replace KeyName with the name of the object you are creating or replacing
url URIparse(objpresigned_url(put))
body Hello World
# This is the contents of your object In this case it＇s a simple string
NetHTTPstart(urlhost) do |http|
httpsend_request(PUT urlrequest_uri body {
# This is required or NetHTTP will add a default unsigned contenttype
contenttype >
})
end
puts objgetbodyread
API Version 20060301
211Amazon Simple Storage Service Developer Guide
Copying Objects
# This will print out the contents of your object to the terminal window
Using AWS SDK for Ruby Version 1
Uploading Objects SDK for Ruby Version 1
1 Create an instance of the AWSS3 class
2 You provide a bucket name and an object key by calling the #bucket[] and the
#object[] methods of your AWSS3S3Object class instance
Generate a presigned URL by calling the url_for method of your AWSS3 class
instance You must specify put as an argument to url_for and you must specify
PUT to NetHTTPSession#send_request if you want to upload an object
3 Anyone with the presigned URL can upload an object
The upload creates an object or replaces any existing object with the same key that is
specified in the presigned URL
The following Ruby code sample demonstrates the preceding tasks for AWS SDK for Ruby Version 1
#Uploading an object using a presigned URL for SDK for Ruby Version 1

require ＇awssdkv1＇
require ＇nethttp＇
s3 AWSS3new(region＇uswest2＇)
obj s3buckets[＇BucketName＇]objects[＇KeyName＇]
# Replace BucketName with the name of your bucket
# Replace KeyName with the name of the object you are creating or replacing
url objurl_for(write content_type > textplain)
body Hello World
# This is the contents of your object In this case it＇s a simple string
NetHTTPstart(urlhost) do |http|
httpsend_request(PUT urlrequest_uri body {contenttype > text
plain})
# The contenttype must be specified in the presigned url
end

puts objread
# This will print out the contents of your object to the terminal window

puts objcontent_type
# This will print out the content type of your object to the terminal window
Copying Objects
Topics
• Related Resources (p 213)
• Copying Objects in a Single Operation (p 213)
API Version 20060301
212Amazon Simple Storage Service Developer Guide
Copying Objects
• Copying Objects Using the Multipart Upload API (p 223)
The copy operation creates a copy of an object that is already stored in Amazon S3 You can create
a copy of your object up to 5 GB in a single atomic operation However for copying an object that is
greater than 5 GB you must use the multipart upload API Using the copy operation you can
• Create additional copies of objects
• Rename objects by copying them and deleting the original ones
• Move objects across Amazon S3 locations (eg uswest1 and EU)
• Change object metadata
Each Amazon S3 object has metadata It is a set of namevalue pairs You can set object metadata
at the time you upload it After you upload the object you cannot modify object metadata The only
way to modify object metadata is to make copy of the object and set the metadata In the copy
operation you set the same object as the source and target
Each object has metadata Some of it is system metadata and other userdefined Users control
some of the system metadata such as storage class configuration to use for the object and configure
serverside encryption When you copy an object usercontrolled system metadata and userdefined
metadata are also copied Amazon S3 resets the system controlled metadata For example when you
copy an object Amazon S3 resets creation date of copied object You don＇t need to set any of these
values in your copy request
When copying an object you might decide to update some of the metadata values For example
if your source object is configured to use standard storage you might choose to use reduced
redundancy storage for the object copy You might also decide to alter some of the userdefined
metadata values present on the source object Note that if you choose to update any of the object＇s
user configurable metadata (system or userdefined) during the copy then you must explicitly specify
all the user configurable metadata even if you are only changing only one of the metadata values
present on the source object in your request
For more information about the object metadata see Object Key and Metadata (p 99)
Note
Copying objects across locations incurs bandwidth charges
Note
If the source object is archived in Amazon Glacier (the storage class of the object is
GLACIER) you must first restore a temporary copy before you can copy the object to another
bucket For information about archiving objects see GLACIER Storage Class Additional
Lifecycle Configuration Considerations (p 124)
When copying objects you can request Amazon S3 to save the target object encrypted using an
AWS Key Management Service (KMS) encryption key an Amazon S3managed encryption key
or a customerprovided encryption key Accordingly you must specify encryption information in
your request If the copy source is an object that stored in Amazon S3 using serverside encryption
with customer provided key you will need to provide encryption information in your request so
Amazon S3 can decrypt the object for copying For more information see Protecting Data Using
Encryption (p 380)
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
Copying Objects in a Single Operation
Topics
API Version 20060301
213Amazon Simple Storage Service Developer Guide
Copying Objects
• Copy an Object Using the AWS SDK for Java (p 214)
• Copy an Object Using the AWS SDK for NET (p 215)
• Copy an Object Using the AWS SDK for PHP (p 218)
• Copy an Object Using the AWS SDK for Ruby (p 221)
• Copy an Object Using the REST API (p 221)
The examples in this section show how to copy objects up to 5 GB in a single operation For copying
objects greater than 5 GB you must use multipart upload API For more information see Copying
Objects Using the Multipart Upload API (p 223)
Copy an Object Using the AWS SDK for Java
The following tasks guide you through using the Java classes to copy an object in Amazon S3
Copying Objects
1 Create an instance of the AmazonS3Client class
2 Execute one of the AmazonS3ClientcopyObject methods You need to provide the
request information such as source bucket name source key name destination bucket
name and destination key You provide this information by creating an instance of the
CopyObjectRequest class or optionally providing this information directly with the
AmazonS3ClientcopyObject method
The following Java code sample demonstrates the preceding tasks
AmazonS3 s3client new AmazonS3Client(new ProfileCredentialsProvider())
s3clientcopyObject(sourceBucketName sourceKey
destinationBucketName destinationKey)
API Version 20060301
214Amazon Simple Storage Service Developer Guide
Copying Objects
Example
The following Java code example makes a copy of an object The copied object with a different key
is saved in the same source bucket For instructions on how to create and test a working sample see
Testing the Java Code Examples (p 564)
import javaioIOException
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelCopyObjectRequest
public class CopyObjectSingleOperation {
private static String bucketName *** Provide bucket name ***
private static String key *** Provide key ***
private static String destinationKey *** Provide dest key ***
public static void main(String[] args) throws IOException {
AmazonS3 s3client new AmazonS3Client(new
ProfileCredentialsProvider())
try {
Copying object
CopyObjectRequest copyObjRequest new CopyObjectRequest(
bucketName key bucketName destinationKey)
Systemoutprintln(Copying object)
s3clientcopyObject(copyObjRequest)
} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException +
which means your request made it +
to Amazon S3 but was rejected with an error +
response for some reason)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException +
which means the client encountered +
an internal error while trying to +
communicate with S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
}
Copy an Object Using the AWS SDK for NET
The following tasks guide you through using the highlevel NET classes to upload a file The API
provides several variations overloads of the Upload method to easily upload your data
API Version 20060301
215Amazon Simple Storage Service Developer Guide
Copying Objects
Copying Objects
1 Create an instance of the AmazonS3 class
2 Execute one of the AmazonS3CopyObject You need to provide information such as
source bucket source key name target bucket and target key name You provide this
information by creating an instance of the CopyObjectRequest class
The following C# code sample demonstrates the preceding tasks
static IAmazonS3 client
client new AmazonS3Client(AmazonRegionEndpointUSEast1)
CopyObjectRequest request new CopyObjectRequest()
{
SourceBucket bucketName
SourceKey objectKey
DestinationBucket bucketName
DestinationKey destObjectKey
}
CopyObjectResponse response clientCopyObject(request)
API Version 20060301
216Amazon Simple Storage Service Developer Guide
Copying Objects
Example
The following C# code example makes a copy of an object You will need to update code and provide
your bucket names and object keys For instructions on how to create and test a working sample see
Running the Amazon S3 NET Code Examples (p 566)
using System
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class CopyObject
{
static string sourceBucket *** Bucket on which to enable
logging ***
static string destinationBucket *** Bucket where you want logs
stored ***
static string objectKey *** Provide key name ***
static string destObjectKey *** Provide destination key name
***
static IAmazonS3 client
public static void Main(string[] args)
{
using (client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
ConsoleWriteLine(Copying an object)
CopyingObject()
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static void CopyingObject()
{
try
{
CopyObjectRequest request new CopyObjectRequest
{
SourceBucket sourceBucket
SourceKey objectKey
DestinationBucket destinationBucket
DestinationKey destObjectKey
}
CopyObjectResponse response clientCopyObject(request)
}
catch (AmazonS3Exception s3Exception)
{
ConsoleWriteLine(s3ExceptionMessage
s3ExceptionInnerException)
}
}
}
}
API Version 20060301
217Amazon Simple Storage Service Developer Guide
Copying Objects
Copy an Object Using the AWS SDK for PHP
This topic guides you through using classes from the AWS SDK for PHP to copy a single object and
multiple objects within Amazon S3 from one bucket to another or within the same bucket
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
The following tasks guide you through using PHP SDK classes to copy an object that is already stored
in Amazon S3
Copying an Object
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 To copy an object execute the Aws＼S3＼S3ClientcopyObject() method You need to
provide information such as source bucket source key name target bucket and target
key name
The following PHP code sample demonstrates using the copyObject() method to copy an object that
is already stored in Amazon S3
use Aws＼S3＼S3Client
sourceBucket ＇*** Your Source Bucket Name ***＇
sourceKeyname ＇*** Your Source Object Key ***＇
targetBucket ＇*** Your Target Bucket Name ***＇
targetKeyname ＇*** Your Target Key Name ***＇

Instantiate the client
s3 S3Clientfactory()
Copy an object
s3>copyObject(array(
＇Bucket＇ > targetBucket
＇Key＇ > targetKeyname
＇CopySource＇ > {sourceBucket}{sourceKeyname}
))
The following tasks guide you through using PHP classes to make multiple copies of an object within
Amazon S3
Copying Objects
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class
factory() method
2 To make multiple copies of an object you execute a batch of calls to the Amazon S3
client getCommand() method which is inherited from the Guzzle＼Service＼Client class
You provide the CopyObject command as the first argument and an array containing
the source bucket source key name target bucket and target key name as the second
argument
The following PHP code sample demonstrates making multiple copies of an object that is stored in
Amazon S3
API Version 20060301
218Amazon Simple Storage Service Developer Guide
Copying Objects
use Aws＼S3＼S3Client
sourceBucket ＇*** Your Source Bucket Name ***＇
sourceKeyname ＇*** Your Source Object Key ***＇
targetBucket ＇*** Your Target Bucket Name ***＇
targetKeyname ＇*** Your Target Key Name ***＇
Instantiate the client
s3 S3Clientfactory()
Perform a batch of CopyObject operations
batch array()
for (i 1 i < 3 i++) {
batch[] s3>getCommand(＇CopyObject＇ array(
＇Bucket＇ > targetBucket
＇Key＇ > {targetKeyname}{i}
＇CopySource＇ > {sourceBucket}{sourceKeyname}
))
}
try {
successful s3>execute(batch)
failed array()
} catch (＼Guzzle＼Service＼Exception＼CommandTransferException e) {
successful e>getSuccessfulCommands()
failed e>getFailedCommands()
}
API Version 20060301
219Amazon Simple Storage Service Developer Guide
Copying Objects
Example of Copying Objects within Amazon S3
The following PHP example illustrates the use of the copyObject() method to copy a single object
within Amazon S3 and using a batch of calls to CopyObject using the getcommand() method to
make multiple copies of an object
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
use Aws＼S3＼S3Client
sourceBucket ＇*** Your Source Bucket Name ***＇
sourceKeyname ＇*** Your Source Object Key ***＇
targetBucket ＇*** Your Target Bucket Name ***＇
Instantiate the client
s3 S3Clientfactory()
Copy an object
s3>copyObject(array(
＇Bucket＇ > targetBucket
＇Key＇ > {sourceKeyname}copy
＇CopySource＇ > {sourceBucket}{sourceKeyname}
))
Perform a batch of CopyObject operations
batch array()
for (i 1 i < 3 i++) {
batch[] s3>getCommand(＇CopyObject＇ array(
＇Bucket＇ > targetBucket
＇Key＇ > {sourceKeyname}copy{i}
＇CopySource＇ > {sourceBucket}{sourceKeyname}
))
}
try {
successful s3>execute(batch)
failed array()
} catch (＼Guzzle＼Service＼Exception＼CommandTransferException e) {
successful e>getSuccessfulCommands()
failed e>getFailedCommands()
}
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientcopyObject() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Guzzle＼Service＼Client Class
• AWS SDK for PHP for Amazon S3 Guzzle＼Service＼ClientgetCommand() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
API Version 20060301
220Amazon Simple Storage Service Developer Guide
Copying Objects
Copy an Object Using the AWS SDK for Ruby
The following tasks guide you through using the Ruby classes to copy an object in Amazon S3 from
one bucket to another or to copy an object within the same bucket
Copying Objects
1 Create an instance of the AWSS3 class by providing your AWS credentials
2 Execute either the AWSS3S3Object#copy_to or
AWSS3S3Object#copy_from method You need to provide the request
information such as source bucket name source key name destination bucket name
and destination key
The following Ruby code sample demonstrates the preceding tasks using the #copy_to method to
copy an object from one bucket to another
s3 AWSS3new
# Upload a file and set serverside encryption
bucket1 s3buckets[source_bucket]
bucket2 s3buckets[target_bucket]
obj1 bucket1objects[source_key]
obj2 bucket2objects[target_key]
obj1copy_to(obj2)
Example
The following Ruby script example makes a copy of an object using the #copy_from method The
copied object with a different key is saved in the same source bucket For instructions about how to
create and test a working sample see Using the AWS SDK for Ruby Version 2 (p 568)
#usrbinenv ruby
require ＇rubygems＇
require ＇awssdk＇
bucket_name ＇*** Provide bucket name ***＇
source_key ＇*** Provide source key ***＇
target_key ＇*** Provide target key ***＇
# Get an instance of the S3 interface
s3 AWSS3new
# Copy the object
s3buckets[bucket_name]objects[target_key]copy_from(source_key)
puts Copying file #{source_key} to #{target_key}
Copy an Object Using the REST API
This example describes how to copy an object using REST For more information about the REST API
go to PUT Object (Copy)
This example copies the flotsam object from the pacific bucket to the jetsam object of the
atlantic bucket preserving its metadata
API Version 20060301
221Amazon Simple Storage Service Developer Guide
Copying Objects
PUT jetsam HTTP11
Host atlantics3amazonawscom
xamzcopysource pacificflotsam
Authorization AWS AKIAIOSFODNN7EXAMPLEENoSbxYByFA0UGLZUqJN5EUnLDg
Date Wed 20 Feb 2008 221221 +0000
The signature was generated from the following information
PUT＼r＼n
＼r＼n
＼r＼n
Wed 20 Feb 2008 221221 +0000＼r＼n
xamzcopysourcepacificflotsam＼r＼n
atlanticjetsam
Amazon S3 returns the following response that specifies the ETag of the object and when it was last
modified
HTTP11 200 OK
xamzid2 Vyaxt7qEbzv34BnSu5hctyyNSlHTYZFMWK4FtzO+iX8JQNyaLdTshL0KxatbaOZt
xamzrequestid 6B13C3C5B34AF333
Date Wed 20 Feb 2008 221301 +0000
ContentType applicationxml
TransferEncoding chunked
Connection close
Server AmazonS3


20080220T221301
7e9c608af58950deeb370c98608ed097

API Version 20060301
222Amazon Simple Storage Service Developer Guide
Copying Objects
Copying Objects Using the Multipart Upload API
Topics
• Copy an Object Using the AWS SDK for Java Multipart Upload API (p 223)
• Copy an Object Using the AWS SDK for NET Multipart Upload API (p 226)
• Copy Object Using the REST Multipart Upload API (p 229)
The examples in this section show you how to copy objects greater than 5 GB using the multipart
upload API You can copy objects less than 5 GB in a single operation For more information see
Copying Objects in a Single Operation (p 213)
Copy an Object Using the AWS SDK for Java Multipart Upload API
The following task guides you through using the Java SDK to copy an Amazon S3 object from one
source location to another such as from one bucket to another You can use the code demonstrated
here to copy objects greater than 5 GB For objects less than 5 GB use the single operation copy
described in Copy an Object Using the AWS SDK for Java (p 214)
Copying Objects
1 Create an instance of the AmazonS3Client class by providing your AWS credentials
2 Initiate a multipart copy by executing the
AmazonS3ClientinitiateMultipartUpload method Create an instance of
InitiateMultipartUploadRequest You will need to provide a bucket name and a
key name
3 Save the upload ID from the response object that the
AmazonS3ClientinitiateMultipartUpload method returns You will need to
provide this upload ID for each subsequent multipart upload operation
4 Copy all the parts For each part copy create a new instance of the CopyPartRequest
class and provide part information including source bucket destination bucket object key
uploadID first byte of the part last byte of the part and the part number
5 Save the response of the CopyPartRequest method in a list The response includes the
ETag value and the part number You will need the part number to complete the multipart
upload
6 Repeat tasks 4 and 5 for each part
7 Execute the AmazonS3ClientcompleteMultipartUpload method to complete the
copy
The following Java code sample demonstrates the preceding tasks
Step 1 Create instance and provide credentials
AmazonS3Client s3Client new AmazonS3Client(new
PropertiesCredentials(
LowLevel_LargeObjectCopyclassgetResourceAsStream(
AwsCredentialsproperties)))
Create lists to hold copy responses
List copyResponses
new ArrayList()
API Version 20060301
223Amazon Simple Storage Service Developer Guide
Copying Objects
Step 2 Initialize
InitiateMultipartUploadRequest initiateRequest
new InitiateMultipartUploadRequest(targetBucketName targetObjectKey)

InitiateMultipartUploadResult initResult
s3ClientinitiateMultipartUpload(initiateRequest)
Step 3 Save upload Id
String uploadId initResultgetUploadId()
try {

Get object size
GetObjectMetadataRequest metadataRequest
new GetObjectMetadataRequest(sourceBucketName sourceObjectKey)
ObjectMetadata metadataResult
s3ClientgetObjectMetadata(metadataRequest)
long objectSize metadataResultgetContentLength() in bytes
Step 4 Copy parts
long partSize 5 * (long)Mathpow(20 200) 5 MB
long bytePosition 0
for (int i 1 bytePosition < objectSize i++)
{
Step 5 Save copy response
CopyPartRequest copyRequest new CopyPartRequest()
withDestinationBucketName(targetBucketName)
withDestinationKey(targetObjectKey)
withSourceBucketName(sourceBucketName)
withSourceKey(sourceObjectKey)
withUploadId(initResultgetUploadId())
withFirstByte(bytePosition)
withLastByte(bytePosition + partSize 1 > objectSize
objectSize 1 bytePosition + partSize 1)
withPartNumber(i)
copyResponsesadd(s3ClientcopyPart(copyRequest))
bytePosition + partSize
}
Step 7 Complete copy operation
CompleteMultipartUploadResult completeUploadResponse
s3ClientcompleteMultipartUpload(completeRequest)
} catch (Exception e) {
Systemoutprintln(egetMessage())
}
API Version 20060301
224Amazon Simple Storage Service Developer Guide
Copying Objects
Example
The following Java code example copies an object from one Amazon S3 bucket to another
For instructions on how to create and test a working sample see Testing the Java Code
Examples (p 564)
import javaioIOException
import javautilArrayList
import javautilList
import comamazonawsauthPropertiesCredentials
import comamazonawsservicess3*
import comamazonawsservicess3model*
public class LowLevel_LargeObjectCopy {
public static void main(String[] args) throws IOException {
String sourceBucketName *** SourceBucketName ***
String targetBucketName *** TargetBucketName ***
String sourceObjectKey *** SourceObjectKey ***
String targetObjectKey *** TargetObjectKey ***
AmazonS3Client s3Client new AmazonS3Client(new
PropertiesCredentials(
LowLevel_LargeObjectCopyclassgetResourceAsStream(
AwsCredentialsproperties)))

List to store copy part responses
List copyResponses
new ArrayList()

InitiateMultipartUploadRequest initiateRequest
new InitiateMultipartUploadRequest(targetBucketName
targetObjectKey)

InitiateMultipartUploadResult initResult
s3ClientinitiateMultipartUpload(initiateRequest)
try {
Get object size
GetObjectMetadataRequest metadataRequest
new GetObjectMetadataRequest(sourceBucketName sourceObjectKey)
ObjectMetadata metadataResult
s3ClientgetObjectMetadata(metadataRequest)
long objectSize metadataResultgetContentLength() in bytes
Copy parts
long partSize 5 * (long)Mathpow(20 200) 5 MB
long bytePosition 0
for (int i 1 bytePosition < objectSize i++)
{
CopyPartRequest copyRequest new CopyPartRequest()
withDestinationBucketName(targetBucketName)
withDestinationKey(targetObjectKey)
withSourceBucketName(sourceBucketName)
withSourceKey(sourceObjectKey)
withUploadId(initResultgetUploadId())
withFirstByte(bytePosition)
withLastByte(bytePosition + partSize 1 > objectSize
objectSize 1 bytePosition + partSize 1)
withPartNumber(i)
copyResponsesadd(s3ClientcopyPart(copyRequest))
bytePosition + partSize
}
CompleteMultipartUploadRequest completeRequest new
CompleteMultipartUploadRequest(
targetBucketName
targetObjectKey
initResultgetUploadId()
GetETags(copyResponses))
CompleteMultipartUploadResult completeUploadResponse
s3ClientcompleteMultipartUpload(completeRequest)
} catch (Exception e) {
Systemoutprintln(egetMessage())
}
}

Helper function that constructs ETags
static List GetETags(List responses)
{
List etags new ArrayList()
for (CopyPartResult response responses)
{
etagsadd(new PartETag(responsegetPartNumber()
responsegetETag()))
}
return etags
}
}
API Version 20060301
225Amazon Simple Storage Service Developer Guide
Copying Objects
Copy an Object Using the AWS SDK for NET Multipart Upload API
The following task guides you through using the NET SDK to copy an Amazon S3 object from one
source location to another such as from one bucket to another You can use the code demonstrated
here to copy objects that are greater than 5 GB For objects less than 5 GB use the single operation
copy described in Copy an Object Using the AWS SDK for NET (p 215)
Copying Objects
1 Create an instance of the AmazonS3Client class by providing your AWS credentials
2 Initiate a multipart copy by executing the
AmazonS3ClientInitiateMultipartUpload method Create an instance of the
InitiateMultipartUploadRequest You will need to provide a bucket name and key
name
3 Save the upload ID from the response object that the
AmazonS3ClientInitiateMultipartUpload method returns You will need to
provide this upload ID for each subsequent multipart upload operation
4 Copy all the parts For each part copy create a new instance of the CopyPartRequest
class and provide part information including source bucket destination bucket object key
uploadID first byte of the part last byte of the part and the part number
5 Save the response of the CopyPartRequest method in a list The response includes the
ETag value and the part number you will need to complete the multipart upload
6 Repeat tasks 4 and 5 for each part
7 Execute the AmazonS3ClientCompleteMultipartUpload method to complete the
copy
The following C# code sample demonstrates the preceding tasks
Step 1 Create instance and provide credentials
IAmazonS3 s3Client new AmazonS3Client(AmazonRegionEndpointUSEast1)
List to store upload part responses
List uploadResponses new List()
List copyResponses new List()
InitiateMultipartUploadRequest initiateRequest
new InitiateMultipartUploadRequest
{
BucketName targetBucket
Key targetObjectKey
}
Step 2 Initialize
InitiateMultipartUploadResponse initResponse
s3ClientInitiateMultipartUpload(initiateRequest)
Step 3 Save Upload Id
String uploadId initResponseUploadId
try
{
Get object size
GetObjectMetadataRequest metadataRequest new GetObjectMetadataRequest
API Version 20060301
226Amazon Simple Storage Service Developer Guide
Copying Objects
{
BucketName sourceBucket
Key sourceObjectKey
}
GetObjectMetadataResponse metadataResponse
s3ClientGetObjectMetadata(metadataRequest)
long objectSize metadataResponseContentLength in bytes
Copy parts
long partSize 5 * (long)MathPow(2 20) 5 MB
long bytePosition 0
for (int i 1 bytePosition < objectSize i++)
{
CopyPartRequest copyRequest new CopyPartRequest
{
DestinationBucket targetBucket
DestinationKey targetObjectKey
SourceBucket sourceBucket
SourceKey sourceObjectKey
UploadId uploadId
FirstByte bytePosition
LastByte bytePosition + partSize 1 > objectSize
objectSize 1 bytePosition + partSize 1
PartNumber i
}
copyResponsesAdd(s3ClientCopyPart(copyRequest))
bytePosition + partSize
}
CompleteMultipartUploadRequest completeRequest
new CompleteMultipartUploadRequest
{
BucketName targetBucket
Key targetObjectKey
UploadId initResponseUploadId
}
completeRequestAddPartETags(copyResponses)
CompleteMultipartUploadResponse completeUploadResponse
s3ClientCompleteMultipartUpload(completeRequest)
}
catch (Exception e) {
ConsoleWriteLine(eMessage)
}
API Version 20060301
227Amazon Simple Storage Service Developer Guide
Copying Objects
Example
The following C# code example copies an object from one Amazon S3 bucket to another For
instructions on how to create and test a working sample see Running the Amazon S3 NET Code
Examples (p 566)
using System
using SystemCollectionsGeneric
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class CopyObjectUsingMPUapi
{
static string sourceBucket *** Source bucket name ***
static string targetBucket *** Target bucket name ***
static string sourceObjectKey *** Source object key ***
static string targetObjectKey *** Target object key ***
static void Main(string[] args)
{
IAmazonS3 s3Client new
AmazonS3Client(AmazonRegionEndpointUSEast1)
List to store upload part responses
List uploadResponses new
List()
List copyResponses new
List()
InitiateMultipartUploadRequest initiateRequest
new InitiateMultipartUploadRequest
{
BucketName targetBucket
Key targetObjectKey
}
InitiateMultipartUploadResponse initResponse
s3ClientInitiateMultipartUpload(initiateRequest)
String uploadId initResponseUploadId
try
{
Get object size
GetObjectMetadataRequest metadataRequest new
GetObjectMetadataRequest
{
BucketName sourceBucket
Key sourceObjectKey
}
GetObjectMetadataResponse metadataResponse
s3ClientGetObjectMetadata(metadataRequest)
long objectSize metadataResponseContentLength in bytes
Copy parts
long partSize 5 * (long)MathPow(2 20) 5 MB
long bytePosition 0
for (int i 1 bytePosition < objectSize i++)
{
CopyPartRequest copyRequest new CopyPartRequest
{
DestinationBucket targetBucket
DestinationKey targetObjectKey
SourceBucket sourceBucket
SourceKey sourceObjectKey
UploadId uploadId
FirstByte bytePosition
LastByte bytePosition + partSize 1 >
objectSize objectSize 1 bytePosition + partSize 1
PartNumber i
}
copyResponsesAdd(s3ClientCopyPart(copyRequest))
bytePosition + partSize
}
CompleteMultipartUploadRequest completeRequest
new CompleteMultipartUploadRequest
{
BucketName targetBucket
Key targetObjectKey
UploadId initResponseUploadId
}
completeRequestAddPartETags(copyResponses)
CompleteMultipartUploadResponse completeUploadResponse
s3ClientCompleteMultipartUpload(completeRequest)
}
catch (Exception e)
{
ConsoleWriteLine(eMessage)
}
}
Helper function that constructs ETags
static List GetETags(List responses)
{
List etags new List()
foreach (CopyPartResponse response in responses)
{
etagsAdd(new PartETag(responsePartNumber responseETag))
}
return etags
}
}
}
API Version 20060301
228Amazon Simple Storage Service Developer Guide
Listing Object Keys
Copy Object Using the REST Multipart Upload API
The following sections in the Amazon Simple Storage Service API Reference describe the REST API
for multipart upload For copying an existing object you use the Upload Part (Copy) API and specify the
source object by adding the xamzcopysource request header in your request
• Initiate Multipart Upload
• Upload Part
• Upload Part (Copy)
• Complete Multipart Upload
• Abort Multipart Upload
• List Parts
• List Multipart Uploads
You can use these APIs to make your own REST requests or you can use one the SDKs we provide
For more information about the SDKs see API Support for Multipart Upload (p 169)
Listing Object Keys
Keys can be listed by prefix By choosing a common prefix for the names of related keys and marking
these keys with a special character that delimits hierarchy you can use the list operation to select and
browse keys hierarchically This is similar to how files are stored in directories within a file system
Amazon S3 exposes a list operation that lets you enumerate the keys contained in a bucket Keys
are selected for listing by bucket and prefix For example consider a bucket named dictionary that
contains a key for every English word You might make a call to list all the keys in that bucket that start
with the letter q List results are always returned in UTF8 binary order
Both the SOAP and REST list operations return an XML document that contains the names of
matching keys and information about the object identified by each key
Note
SOAP support over HTTP is deprecated but it is still available over HTTPS New Amazon S3
features will not be supported for SOAP We recommend that you use either the REST API or
the AWS SDKs
Groups of keys that share a prefix terminated by a special delimiter can be rolled up by that common
prefix for the purposes of listing This enables applications to organize and browse their keys
hierarchically much like how you would organize your files into directories in a file system For
example to extend the dictionary bucket to contain more than just English words you might form
keys by prefixing each word with its language and a delimiter such as Frenchlogical Using this
naming scheme and the hierarchical listing feature you could retrieve a list of only French words You
could also browse the toplevel list of available languages without having to iterate through all the
lexicographically intervening keys
For more information on this aspect of listing see Listing Keys Hierarchically Using a Prefix and
Delimiter (p 230)
List Implementation Efficiency
List performance is not substantially affected by the total number of keys in your bucket nor by the
presence or absence of the prefix marker maxkeys or delimiter arguments For information on
improving overall bucket performance including the list operation see Request Rate and Performance
Considerations (p 518)
API Version 20060301
229Amazon Simple Storage Service Developer Guide
Listing Object Keys
Iterating Through MultiPage Results
As buckets can contain a virtually unlimited number of keys the complete results of a list query can
be extremely large To manage large result sets Amazon S3 API support pagination to split them
into multiple responses Each list keys response returns a page of up to 1000 keys with an indicator
indicating if the response is truncated You send a series of list keys requests until you have received
all the keys AWS SDK wrapper libraries provide the same pagination
The following Java and NET SDK examples show how to use pagination when listing keys in a bucket
• Listing Keys Using the AWS SDK for Java (p 231)
• Listing Keys Using the AWS SDK for NET (p 233)
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
Listing Keys Hierarchically Using a Prefix and Delimiter
The prefix and delimiter parameters limit the kind of results returned by a list operation Prefix limits
results to only those keys that begin with the specified prefix and delimiter causes list to roll up all keys
that share a common prefix into a single summary list result
The purpose of the prefix and delimiter parameters is to help you organize and then browse your keys
hierarchically To do this first pick a delimiter for your bucket such as slash () that doesn＇t occur in
any of your anticipated key names Next construct your key names by concatenating all containing
levels of the hierarchy separating each level with the delimiter
For example if you were storing information about cities you might naturally organize them by
continent then by country then by province or state Because these names don＇t usually contain
punctuation you might select slash () as the delimiter The following examples use a slash ()
delimiter
• EuropeFranceAquitaineBordeaux
• North AmericaCanadaQuebecMontreal
• North AmericaUSAWashingtonBellevue
• North AmericaUSAWashingtonSeattle
If you stored data for every city in the world in this manner it would become awkward to manage
a flat key namespace By using Prefix and Delimiter with the list operation you can use the
hierarchy you＇ve created to list your data For example to list all the states in USA set Delimiter＇＇
and Prefix＇North AmericaUSA＇ To list all the provinces in Canada for which you have data set
Delimiter＇＇ and Prefix＇North AmericaCanada＇
A list request with a delimiter lets you browse your hierarchy at just one level skipping over and
summarizing the (possibly millions of) keys nested at deeper levels For example assume you have a
bucket (ExampleBucket) the following keys
samplejpg
photos2006Januarysamplejpg
photos2006Februarysample2jpg
photos2006Februarysample3jpg
API Version 20060301
230Amazon Simple Storage Service Developer Guide
Listing Object Keys
photos2006Februarysample4jpg
The sample bucket has only the samplejpg object at the root level To list only the root level
objects in the bucket you send a GET request on the bucket with delimiter character In response
Amazon S3 returns the samplejpg object key because it does not contain the delimiter character
All other keys contain the delimiter character Amazon S3 groups these keys and return a single
CommonPrefixes element with prefix value photos that is a substring from the beginning of these
keys to the first occurrence of the specified delimiter

ExampleBucket


1000

false

samplejpg
20110724T193930000Z
"d1a7fb5eab1c16cb4f7cf341cf188c3d"
6

75cc57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a<
ID>
displayname

STANDARD


photos


Listing Keys Using the AWS SDK for Java
The following Java code example lists object keys in a bucket If the response is truncated
( is true in the response) the code loop continues Each subsequent request specifies
the continuationtoken in the request and sets its value to the
returned by Amazon S3 in the previous response
API Version 20060301
231Amazon Simple Storage Service Developer Guide
Listing Object Keys
Example
For instructions on how to create and test a working sample see Testing the Java Code
Examples (p 564)import javaioIOException
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelListObjectsRequest
import comamazonawsservicess3modelListObjectsV2Request
import comamazonawsservicess3modelListObjectsV2Result
import comamazonawsservicess3modelObjectListing
import comamazonawsservicess3modelS3ObjectSummary
public class ListKeys {
private static String bucketName ***bucket name***

public static void main(String[] args) throws IOException {
AmazonS3 s3client new AmazonS3Client(new
ProfileCredentialsProvider())
try {
Systemoutprintln(Listing objects)
final ListObjectsV2Request req new
ListObjectsV2Request()withBucketName(bucketName)withMaxKeys(2)
ListObjectsV2Result result
do {
result s3clientlistObjectsV2(req)

for (S3ObjectSummary objectSummary
resultgetObjectSummaries()) {
Systemoutprintln( + objectSummarygetKey() + +
(size + objectSummarygetSize() +
))
}
Systemoutprintln(Next Continuation Token +
resultgetNextContinuationToken())
reqsetContinuationToken(resultgetNextContinuationToken())
} while(resultisTruncated() true )

} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException +
which means your request made it +
to Amazon S3 but was rejected with an error response
+
for some reason)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException +
which means the client encountered +
an internal error while trying to communicate +
with S3 +
such as not being able to access the network)
Systemoutprintln(Error Message + acegetMessage())
}
}
}
API Version 20060301
232Amazon Simple Storage Service Developer Guide
Listing Object Keys
Listing Keys Using the AWS SDK for NET
The following C# code example lists object keys in a bucket If the response is truncated
( is true in the response) the code loop continues Each subsequent request specifies
the continuationtoken in the request and sets its value to the
returned by Amazon S3 in the previous response
API Version 20060301
233Amazon Simple Storage Service Developer Guide
Listing Object Keys
Example
For instructions on how to create and test a working sample see Running the Amazon S3 NET Code
Examples (p 566)
using System
using AmazonS3
using AmazonS3Model

namespace s3amazoncomdocsamples
{
class ListObjects
{
static string bucketName ***bucket name***
static IAmazonS3 client

public static void Main(string[] args)
{
using (client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
ConsoleWriteLine(Listing objects stored in a bucket)
ListingObjects()
}

ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}

static void ListingObjects()
{
try
{
ListObjectsV2Request request new ListObjectsV2Request
{
BucketName bucketName
MaxKeys 10
}
ListObjectsV2Response response
do
{
response clientListObjectsV2(request)

Process response
foreach (S3Object entry in responseS3Objects)
{
ConsoleWriteLine(key {0} size {1}
entryKey entrySize)
}
ConsoleWriteLine(Next Continuation Token {0}
responseNextContinuationToken)
requestContinuationToken
responseNextContinuationToken
} while (responseIsTruncated true)
}
catch (AmazonS3Exception amazonS3Exception)
{
if (amazonS3ExceptionErrorCode null &&

(amazonS3ExceptionErrorCodeEquals(InvalidAccessKeyId)
||
amazonS3ExceptionErrorCodeEquals(InvalidSecurity)))
{
ConsoleWriteLine(Check the provided AWS
Credentials)
ConsoleWriteLine(
To sign up for service go to httpawsamazoncom
s3)
}
else
{
ConsoleWriteLine(
Error occurred Message＇{0}＇ when listing objects
amazonS3ExceptionMessage)
}
}
}
}
}

API Version 20060301
234Amazon Simple Storage Service Developer Guide
Listing Object Keys
Listing Keys Using the AWS SDK for PHP
This topic guides you through using classes from the AWS SDK for PHP to list the object keys
contained in an Amazon S3 bucket
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
To list the object keys contained in a bucket using the AWS SDK for PHP you first must list the objects
contained in the bucket and then extract the key from each of the listed objects When listing objects in
a bucket you have the option of using the lowlevel Aws＼S3＼S3ClientlistObjects() method or the high
level Aws＼S3＼Iterator＼ListObjects iterator
The lowlevel listObjects() method maps to the underlying Amazon S3 REST API Each
listObjects() request returns a page of up to 1000 objects If you have more than 1000 objects
in the bucket your response will be truncated and you will need to send another listObjects()
request to retrieve the next set of 1000 objects
You can use the highlevel ListObjects iterator to make your task of listing the objects contained
in a bucket a bit easier To use the ListObjects iterator to create a list of objects you execute
the Amazon S3 client getIterator() method that is inherited from Guzzle＼Service＼Client class with
the ListObjects command as the first argument and an array to contain the returned objects
from the specified bucket as the second argument When used as a ListObjects iterator the
getIterator() method returns all the objects contained in the specified bucket There is no 1000
object limit so you don＇t need to worry if the response is truncated or not
The following tasks guide you through using the PHP Amazon S3 client methods to list the objects
contained in a bucket from which you can list the object keys
Listing Object Keys
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory
method
2 Execute the highlevel Amazon S3 client getIterator() method with the
ListObjects command as the first argument and an array to contain the returned
objects from the specified bucket as the second argument
Or you can execute the lowlevel Amazon S3 client listObjects() method with an
array to contain the returned objects from the specified bucket as the argument
3 Extract the object key from each object in the list of returned objects
The following PHP code sample demonstrates how to list the objects contained in a bucket from which
you can list the object keys
use Aws＼S3＼S3Client
Instantiate the client
s3 S3Clientfactory()
bucket ＇*** Bucket Name ***＇

Use the highlevel iterators (returns ALL of your objects)
objects s3>getIterator(＇ListObjects＇ array(＇Bucket＇ > bucket))
echo Keys retrieved＼n
foreach (objects as object) {
API Version 20060301
235Amazon Simple Storage Service Developer Guide
Listing Object Keys
echo object[＇Key＇] ＼n
}
Use the plain API (returns ONLY up to 1000 of your objects)
result s3>listObjects(array(＇Bucket＇ > bucket))
echo Keys retrieved＼n
foreach (result[＇Contents＇] as object) {
echo object[＇Key＇] ＼n
}
Example of Listing Object Keys
The following PHP example demonstrates how to list the keys from a specified bucket It shows how
to use the highlevel getIterator() method to list the objects in a bucket and then how to extract
the key from each of the objects in the list It also show how to use the lowlevel listObjects()
method to list the objects in a bucket and then how to extract the key from each of the objects in
the list returned For information about running the PHP examples in this guide go to Running PHP
Examples (p 567)
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
use Aws＼S3＼S3Client
use Aws＼S3＼Exception＼S3Exception
bucket ＇*** Your Bucket Name ***＇
Instantiate the client
s3 S3Clientfactory()
Use the highlevel iterators (returns ALL of your objects)
try {
objects s3>getIterator(＇ListObjects＇ array(
＇Bucket＇ > bucket
))
echo Keys retrieved＼n
foreach (objects as object) {
echo object[＇Key＇] ＼n
}
} catch (S3Exception e) {
echo e>getMessage() ＼n
}
Use the plain API (returns ONLY up to 1000 of your objects)
try {
result s3>listObjects(array(＇Bucket＇ > bucket))
echo Keys retrieved＼n
foreach (result[＇Contents＇] as object) {
echo object[＇Key＇] ＼n
}
} catch (S3Exception e) {
echo e>getMessage() ＼n
}
API Version 20060301
236Amazon Simple Storage Service Developer Guide
Deleting Objects
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼Iterator＼ListObjects
• AWS SDK for PHP for Amazon S3 Guzzle＼Service＼Client Class
• AWS SDK for PHP for Amazon S3 Guzzle＼Service＼ClientgetIterator() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientlistObjects() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
Listing Keys Using the REST API
You can use the AWS SDK to list the object keys in a bucket However if your application requires it
you can send REST requests directly You can send a GET request to return some or all of the objects
in a bucket or you can use selection criteria to return a subset of the objects in a bucket For more
information go to GET Bucket (List Objects) Version 2
Deleting Objects
Topics
• Deleting Objects from a VersionEnabled Bucket (p 237)
• Deleting Objects from an MFAEnabled Bucket (p 238)
• Related Resources (p 238)
• Deleting One Object Per Request (p 238)
• Deleting Multiple Objects Per Request (p 246)
You can delete one or more objects directly from Amazon S3 You have the following options when
deleting an object
• Delete a single object—Amazon S3 provides the DELETE API that you can use to delete one
object in a single HTTP request
• Delete multiple objects—Amazon S3 also provides the MultiObject Delete API that you can use to
delete up to 1000 objects in a single HTTP request
When deleting objects from a bucket that is not versionenabled you provide only the object key name
however when deleting objects from a versionenabled bucket you can optionally provide version ID
of the object to delete a specific version of the object
Deleting Objects from a VersionEnabled Bucket
If your bucket is versionenabled then multiple versions of the same object can exist in the bucket
When working with versionenabled buckets the delete API enables the following options
• Specify a nonversioned delete request—That is you specify only the object＇s key and not
the version ID In this case Amazon S3 creates a delete marker and returns its version ID in the
response This makes your object disappear from the bucket For information about object versioning
and the delete marker concept see Object Versioning (p 106)
• Specify a versioned delete request—That is you specify both the key and also a version ID In this
case the following two outcomes are possible
API Version 20060301
237Amazon Simple Storage Service Developer Guide
Deleting Objects
• If the version ID maps to a specific object version then Amazon S3 deletes the specific version of
the object
• If the version ID maps to the delete marker of that object Amazon S3 deletes the delete marker
This makes the object reappear in your bucket
Deleting Objects from an MFAEnabled Bucket
When deleting objects from an Multi Factor Authentication (MFA) enabled bucket note the following
• If you provide an invalid MFA token the request always fails
• If you have MFAenabled bucket and you make a versioned delete request (you provide an object
key and version ID) the request will fail if you don＇t provide a valid MFA token In addition when
using the MultiObject Delete API on an MFAenabled bucket if any of the deletes is a versioned
delete request (that is you specify object key and version ID) the entire request will fail if you don＇t
provide MFA token
On the other hand in the following cases the request succeeds
• If you have an MFA enabled bucket and you make a nonversioned delete request (you are not
deleting a versioned object) and you don＇t provide MFA token the delete succeeds
• If you have a MultiObject Delete request specifying only nonversioned objects to delete from an
MFAenabled bucket and you don＇t provide an MFA token the deletions succeed
For information on MFA delete see MFA Delete (p 424)
Related Resources
• Using the AWS SDKs CLI and Explorers (p 560)
Deleting One Object Per Request
Topics
• Deleting an Object Using the AWS SDK for Java (p 238)
• Deleting an Object Using the AWS SDK for NET (p 242)
• Deleting an Object Using the AWS SDK for PHP (p 245)
• Deleting an Object Using the REST API (p 246)
Amazon S3 provides the DELETE API (see DELETE Object) for you to delete one object per request
To learn more about object deletion see Deleting Objects (p 237)
You can use the REST API directly or use the wrapper libraries provided by the AWS SDKs that can
simplify your application development
Deleting an Object Using the AWS SDK for Java
The following tasks guide you through using the AWS SDK for Java classes to delete an object
Deleting an Object (NonVersioned Bucket)
1 Create an instance of the AmazonS3Client class
API Version 20060301
238Amazon Simple Storage Service Developer Guide
Deleting Objects
2 Execute one of the AmazonS3ClientdeleteObject methods
You can provide a bucket name and an object name as parameters or provide the same
information in a DeleteObjectRequest object and pass the object as a parameter
If you have not enabled versioning on the bucket the operation deletes the object If you
have enabled versioning the operation adds a delete marker For more information see
Deleting One Object Per Request (p 238)
The following Java sample demonstrates the preceding steps The sample uses the
DeleteObjectRequest class to provide a bucket name and an object key
AmazonS3 s3client new AmazonS3Client(new ProfileCredentialsProvider())

s3clientdeleteObject(new DeleteObjectRequest(bucketName keyName))
Deleting a Specific Version of an Object (VersionEnabled Bucket)
1 Create an instance of the AmazonS3Client class
2 Execute one of the AmazonS3ClientdeleteVersion methods
You can provide a bucket name and an object key directly as parameters or use the
DeleteVersionRequest to provide the same information
The following Java sample demonstrates the preceding steps The sample uses the
DeleteVersionRequest class to provide a bucket name an object key and a version Id
AmazonS3 s3client new AmazonS3Client(new ProfileCredentialsProvider())

s3clientdeleteObject(new DeleteVersionRequest(bucketName keyName
versionId))
API Version 20060301
239Amazon Simple Storage Service Developer Guide
Deleting Objects
Example 1 Deleting an Object (NonVersioned Bucket)
The following Java example deletes an object from a bucket If you have not enabled versioning on
the bucket Amazon S3 deletes the object If you have enabled versioning Amazon S3 adds a delete
marker and the object is not deleted For information about how to create and test a working sample
see Testing the Java Code Examples (p 564)
import javaioIOException
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelDeleteObjectRequest
public class DeleteAnObjectNonVersionedBucket {
private static String bucketName *** Provide a Bucket Name ***
private static String keyName *** Provide a Key Name ****
public static void main(String[] args) throws IOException {
AmazonS3 s3Client new AmazonS3Client(new
ProfileCredentialsProvider())
try {
s3ClientdeleteObject(new DeleteObjectRequest(bucketName
keyName))
} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException)
Systemoutprintln(Error Message + acegetMessage())
}
}
}
API Version 20060301
240Amazon Simple Storage Service Developer Guide
Deleting Objects
Example 2 Deleting an Object (Versioned Bucket)
The following Java example deletes a specific version of an object from a versioned bucket The
deleteObject request removes the specific object version from the bucket
To test the sample you must provide a bucket name The code sample performs the following tasks
1 Enable versioning on the bucket
2 Add a sample object to the bucket In response Amazon S3 returns the version ID of the newly
added object
3 Delete the sample object using the deleteVersion method The DeleteVersionRequest class
specifies both an object key name and a version ID
For information about how to create and test a working sample see Testing the Java Code
Examples (p 564)
import javaioByteArrayInputStream
import javaioIOException
import javautilRandom
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelBucketVersioningConfiguration
import comamazonawsservicess3modelCannedAccessControlList
import comamazonawsservicess3modelDeleteVersionRequest
import comamazonawsservicess3modelObjectMetadata
import comamazonawsservicess3modelPutObjectRequest
import comamazonawsservicess3modelPutObjectResult
import
comamazonawsservicess3modelSetBucketVersioningConfigurationRequest
public class DeleteAnObjectVersionEnabledBucket {
static String bucketName *** Provide a Bucket Name ***
static String keyName *** Provide a Key Name ****
static AmazonS3Client s3Client

public static void main(String[] args) throws IOException {
s3Client new AmazonS3Client(new ProfileCredentialsProvider())
try {
Make the bucket versionenabled
enableVersioningOnBucket(s3Client bucketName)

Add a sample object
String versionId putAnObject(keyName)
s3ClientdeleteVersion(
new DeleteVersionRequest(
bucketName
keyName
versionId))

} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException)
Systemoutprintln(Error Message + acegetMessage())
}
}

static void enableVersioningOnBucket(AmazonS3Client s3Client
String bucketName) {
BucketVersioningConfiguration config new
BucketVersioningConfiguration()
withStatus(BucketVersioningConfigurationENABLED)
SetBucketVersioningConfigurationRequest
setBucketVersioningConfigurationRequest new
SetBucketVersioningConfigurationRequest(
bucketName config)

s3ClientsetBucketVersioningConfiguration(setBucketVersioningConfigurationRequest)
}

static String putAnObject(String keyName) {
String content This is the content body
String key ObjectToDelete + new Random()nextInt()
ObjectMetadata metadata new ObjectMetadata()
metadatasetHeader(Subject ContentAsObject)
metadatasetHeader(ContentLength contentlength())
PutObjectRequest request new PutObjectRequest(bucketName key
new ByteArrayInputStream(contentgetBytes()) metadata)
withCannedAcl(CannedAccessControlListAuthenticatedRead)
PutObjectResult response s3ClientputObject(request)
return responsegetVersionId()
}
}
API Version 20060301
241Amazon Simple Storage Service Developer Guide
Deleting Objects
Deleting an Object Using the AWS SDK for NET
You can delete an object from a bucket If you have versioning enabled on the bucket you can also
delete a specific version of an object
The following tasks guide you through using the NET classes to delete an object
Deleting an Object (NonVersioned Bucket)
1 Create an instance of the AmazonS3Client class by providing your AWS credentials
2 Execute the AmazonS3DeleteObject method by providing a bucket name and an
object key in an instance of DeleteObjectRequest
If you have not enabled versioning on the bucket the operation deletes the object If you
have enabled versioning the operation adds a delete marker For more information see
Deleting One Object Per Request (p 238)
The following C# code sample demonstrates the preceding steps
static IAmazonS3 client
client new AmazonS3Client(AmazonRegionEndpointUSEast1)
DeleteObjectRequest deleteObjectRequest
new DeleteObjectRequest
{
BucketName bucketName
Key keyName
}
using (client AmazonAWSClientFactoryCreateAmazonS3Client(
accessKeyID secretAccessKeyID))
{
clientDeleteObject(deleteObjectRequest)
}
Deleting a Specific Version of an Object (VersionEnabled Bucket)
1 Create an instance of the AmazonS3Client class by providing your AWS credentials
2 Execute the AmazonS3DeleteObject method by providing a bucket name an object
key name and object version Id in an instance of DeleteObjectRequest
The DeleteObject method deletes the specific version of the object
The following C# code sample demonstrates the preceding steps
IAmazonS3 client
client new AmazonS3Client(AmazonRegionEndpointUSEast1)
DeleteObjectRequest deleteObjectRequest new DeleteObjectRequest
{
BucketName bucketName
Key keyName
VersionId versionID
}
API Version 20060301
242Amazon Simple Storage Service Developer Guide
Deleting Objects
using (client new AmazonS3Client(AmazonRegionEndpointUSEast1))
{
clientDeleteObject(deleteObjectRequest)
ConsoleWriteLine(Deleting an object)
}
Example 1 Deleting an Object (NonVersioned Bucket)
The following C# code example deletes an object from a bucket It does not provide a version Id in
the delete request If you have not enabled versioning on the bucket Amazon S3 deletes the object
If you have enabled versioning Amazon S3 adds a delete marker and the object is not deleted For
information about how to create and test a working sample see Running the Amazon S3 NET Code
Examples (p 566)
using System
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class DeleteObjectNonVersionedBucket
{
static string bucketName *** Provide a bucket name ***
static string keyName *** Provide a key name ****
static IAmazonS3 client
public static void Main(string[] args)
{
using (client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
DeleteObjectRequest deleteObjectRequest new
DeleteObjectRequest
{
BucketName bucketName
Key keyName
}
try
{
clientDeleteObject(deleteObjectRequest)
ConsoleWriteLine(Deleting an object)
}
catch (AmazonS3Exception s3Exception)
{
ConsoleWriteLine(s3ExceptionMessage
s3ExceptionInnerException)
}
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
}
}
API Version 20060301
243Amazon Simple Storage Service Developer Guide
Deleting Objects
Example 2 Deleting an Object (Versioned Bucket)
The following C# code example deletes an object from a versioned bucket The
DeleteObjectRequest instance specifies an object key name and a version ID The DeleteObject
method removes the specific object version from the bucket
To test the sample you must provide a bucket name The code sample performs the following tasks
1 Enable versioning on the bucket
2 Add a sample object to the bucket In response Amazon S3 returns the version ID of the newly
added object You can also obtain version IDs of an object by sending a ListVersions request
var listResponse clientListVersions(new ListVersionsRequest { BucketName
bucketName Prefix keyName })
3 Delete the sample object using the DeleteObject method The DeleteObjectRequest class
specifies both an object key name and a version ID
For information about how to create and test a working sample see Running the Amazon S3 NET
Code Examples (p 566)
using System
using AmazonS3
using AmazonS3Model
namespace s3amazoncomdocsamples
{
class DeleteObjectVersion
{
static string bucketName *** Provide a Bucket Name ***
static string keyName *** Provide a Key Name ***
static IAmazonS3 client
public static void Main(string[] args)
{
using (client new
AmazonS3Client(AmazonRegionEndpointUSEast1))
{
try
{
Make the bucket versionenabled
EnableVersioningOnBucket(bucketName)
Add a sample object
string versionID PutAnObject(keyName)
Delete the object by specifying an object key and a
version ID
DeleteObjectRequest request new DeleteObjectRequest
{
BucketName bucketName
Key keyName
VersionId versionID
}
ConsoleWriteLine(Deleting an object)
clientDeleteObject(request)
}
catch (AmazonS3Exception s3Exception)
{
ConsoleWriteLine(s3ExceptionMessage
s3ExceptionInnerException)
}
}
ConsoleWriteLine(Press any key to continue)
ConsoleReadKey()
}
static void EnableVersioningOnBucket(string bucketName)
{
PutBucketVersioningRequest setBucketVersioningRequest new
PutBucketVersioningRequest
{
BucketName bucketName
VersioningConfig new S3BucketVersioningConfig { Status
VersionStatusEnabled }
}
clientPutBucketVersioning(setBucketVersioningRequest)
}
static string PutAnObject(string objectKey)
{
PutObjectRequest request new PutObjectRequest
{
BucketName bucketName
Key objectKey
ContentBody This is the content body
}
PutObjectResponse response clientPutObject(request)
return responseVersionId
}
}
}
API Version 20060301
244Amazon Simple Storage Service Developer Guide
Deleting Objects
Deleting an Object Using the AWS SDK for PHP
This topic guides you through using classes from the AWS SDK for PHP to delete an object from a
nonversioned bucket For information on deleting an object from a versioned bucket see Deleting an
Object Using the REST API (p 246)
Note
This topic assumes that you are already following the instructions for Using the AWS SDK
for PHP and Running PHP Examples (p 566) and have the AWS SDK for PHP properly
installed
Deleting One Object (NonVersioned Bucket)
1 Create an instance of an Amazon S3 client by using the Aws＼S3＼S3Client class factory()
method
2 Execute the Aws＼S3＼S3ClientdeleteObject() method You must provide a bucket name
and a key name in the array parameter＇s required keys Bucket and Key
If you have not enabled versioning on the bucket the operation deletes the object If you
have enabled versioning the operation adds a delete marker For more information see
Deleting Objects (p 237)
The following PHP code sample demonstrates how to delete an object from an Amazon S3 bucket
using the deleteObject() method
use Aws＼S3＼S3Client
s3 S3Clientfactory()
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇
result s3>deleteObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
))
API Version 20060301
245Amazon Simple Storage Service Developer Guide
Deleting Objects
Example Deleting an Object from a NonVersioned Bucket
The following PHP code example deletes an object from a bucket It does not provide a version Id in
the delete request If you have not enabled versioning on the bucket Amazon S3 deletes the object
If you have enabled versioning Amazon S3 adds a delete marker and the object is not deleted For
information about running the PHP examples in this guide go to Running PHP Examples (p 567)
For information on deleting an object from a versioned bucket see Deleting an Object Using the REST
API (p 246)
Include the AWS SDK using the Composer autoloader
require ＇vendorautoloadphp＇
use Aws＼S3＼S3Client
s3 S3Clientfactory()
bucket ＇*** Your Bucket Name ***＇
keyname ＇*** Your Object Key ***＇
result s3>deleteObject(array(
＇Bucket＇ > bucket
＇Key＇ > keyname
))
Related Resources
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Client Class
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3Clientfactory() Method
• AWS SDK for PHP for Amazon S3 Aws＼S3＼S3ClientdeleteObject() Method
• AWS SDK for PHP for Amazon S3
• AWS SDK for PHP Documentation
Deleting an Object Using the REST API
You can use the AWS SDKs to delete an object However if your application requires it you can send
REST requests directly For more information go to DELETE Object in the Amazon Simple Storage
Service API Reference
Deleting Multiple Objects Per Request
Topics
• Deleting Multiple Objects Using the AWS SDK for Java (p 247)
• Deleting Multiple Objects Using the AWS SDK for NET (p 251)
• Deleting Multiple Objects Using the AWS SDK for PHP (p 255)
• Deleting Multiple Objects Using the REST API (p 259)
Amazon S3 provides the MultiObject Delete API (see Delete MultiObject Delete) that enables you to
delete multiple objects in a single request The API supports two modes for the response verbose and
quiet By default the operation uses verbose mode in which the response includes the result each keys
deletion that was encountered in your request In quiet mode the response includes only keys where
the delete operation encountered an error
API Version 20060301
246Amazon Simple Storage Service Developer Guide
Deleting Objects
If all keys were successfully deleted when using the quiet mode Amazon S3 returns empty response
To learn more about object deletion see Deleting Objects (p 237)
You can use the REST API directly or use the AWS SDKs
Deleting Multiple Objects Using the AWS SDK for Java
The following tasks guide you through using the AWS SDK for Java classes to delete multiple objects
in a single HTTP request
Deleting Multiple Objects (NonVersioned Bucket)
1 Create an instance of the AmazonS3Client class
2 Create an instance of the DeleteObjectsRequest class and provide a list of objects
keys you want to delete
3 Execute the AmazonS3ClientdeleteObjects method
The following Java code sample demonstrates the preceding steps
DeleteObjectsRequest multiObjectDeleteRequest new
DeleteObjectsRequest(bucketName)
List keys new ArrayList()
keysadd(new KeyVersion(keyName1))
keysadd(new KeyVersion(keyName2))
keysadd(new KeyVersion(keyName3))

multiObjectDeleteRequestsetKeys(keys)
try {
DeleteObjectsResult delObjRes
s3ClientdeleteObjects(multiObjectDeleteRequest)
Systemoutformat(Successfully deleted all the s items＼n
delObjResgetDeletedObjects()size())

} catch (MultiObjectDeleteException e) {
Process exception
}
In the event of an exception you can review the MultiObjectDeleteException to determine which
objects failed to delete and why as shown in the following Java example
Systemoutformat(s ＼n egetMessage())
Systemoutformat(No of objects successfully deleted s＼n
egetDeletedObjects()size())
Systemoutformat(No of objects failed to delete s＼n
egetErrors()size())
Systemoutformat(Printing error data＼n)
for (DeleteError deleteError egetErrors()){
Systemoutformat(Object Key s＼ts＼ts＼n
deleteErrorgetKey() deleteErrorgetCode()
deleteErrorgetMessage())
}
API Version 20060301
247Amazon Simple Storage Service Developer Guide
Deleting Objects
The following tasks guide you through deleting objects from a versionenabled bucket
Deleting Multiple Objects (VersionEnabled Bucket)
1 Create an instance of the AmazonS3Client class
2 Create an instance of the DeleteObjectsRequest class and provide a list of objects
keys and optionally the version IDs of the objects that you want to delete
If you specify the version ID of the object that you want to delete Amazon S3 deletes the
specific object version If you don＇t specify the version ID of the object that you want to
delete Amazon S3 adds a delete marker For more information see Deleting One Object
Per Request (p 238)
3 Execute the AmazonS3ClientdeleteObjects method
The following Java code sample demonstrates the preceding steps
List keys new ArrayList()
Provide a list of object keys and versions
DeleteObjectsRequest multiObjectDeleteRequest new
DeleteObjectsRequest(bucketName)
withKeys(keys)

try {
DeleteObjectsResult delObjRes
s3ClientdeleteObjects(multiObjectDeleteRequest)
Systemoutformat(Successfully deleted all the s items＼n
delObjResgetDeletedObjects()size())

} catch (MultiObjectDeleteException e) {
Process exception
}
API Version 20060301
248Amazon Simple Storage Service Developer Guide
Deleting Objects
Example 1 MultiObject Delete (NonVersioned Bucket)
The following Java code example uses the MultiObject Delete API to delete objects from a non
versioned bucket The example first uploads the sample objects to the bucket and then uses the
deleteObjects method to delete the objects in a single request
For information about how to create and test a working sample see Testing the Java Code
Examples (p 564)
import javaioByteArrayInputStream
import javaioIOException
import javautilArrayList
import javautilList
import javautilRandom
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelCannedAccessControlList
import comamazonawsservicess3modelDeleteObjectsRequest
import comamazonawsservicess3modelDeleteObjectsRequestKeyVersion
import comamazonawsservicess3modelDeleteObjectsResult
import comamazonawsservicess3modelMultiObjectDeleteException
import
comamazonawsservicess3modelMultiObjectDeleteExceptionDeleteError
import comamazonawsservicess3modelObjectMetadata
import comamazonawsservicess3modelPutObjectRequest
import comamazonawsservicess3modelPutObjectResult
public class DeleteMultipleObjectsNonVersionedBucket {
static String bucketName *** Provide a bucket name ***
static AmazonS3Client s3Client
public static void main(String[] args) throws IOException {
try {
s3Client new AmazonS3Client(new ProfileCredentialsProvider())
Upload sample objectsBecause the bucket is not version
enabled
the KeyVersions list returned will have null values for
version IDs
List keysAndVersions1 putObjects(3)
Delete specific object versions
multiObjectNonVersionedDelete(keysAndVersions1)
} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException)
Systemoutprintln(Error Message + acegetMessage())
}
}
static List putObjects(int number) {
List keys new ArrayList()
String content This is the content body
for (int i 0 i < number i++) {
String key ObjectToDelete + new Random()nextInt()
ObjectMetadata metadata new ObjectMetadata()
metadatasetHeader(Subject ContentAsObject)
metadatasetHeader(ContentLength (long)contentlength())
PutObjectRequest request new PutObjectRequest(bucketName key
new ByteArrayInputStream(contentgetBytes()) metadata)

withCannedAcl(CannedAccessControlListAuthenticatedRead)
PutObjectResult response s3ClientputObject(request)
KeyVersion keyVersion new KeyVersion(key
responsegetVersionId())
keysadd(keyVersion)
}
return keys
}
static void multiObjectNonVersionedDelete(List keys) {
Multiobject delete by specifying only keys (no version ID)
DeleteObjectsRequest multiObjectDeleteRequest new
DeleteObjectsRequest(
bucketName)withQuiet(false)
Create request that include only object key names
List justKeys new ArrayList()
for (KeyVersion key keys) {
justKeysadd(new KeyVersion(keygetKey()))
}
multiObjectDeleteRequestsetKeys(justKeys)
Execute DeleteObjects Amazon S3 add delete marker for each
object
deletion The objects no disappear from your bucket (verify)
DeleteObjectsResult delObjRes null
try {
delObjRes s3ClientdeleteObjects(multiObjectDeleteRequest)
Systemoutformat(Successfully deleted all the s items＼n
delObjResgetDeletedObjects()size())
} catch (MultiObjectDeleteException mode) {
printDeleteResults(mode)
}
}
static void printDeleteResults(MultiObjectDeleteException mode) {
Systemoutformat(s ＼n modegetMessage())
Systemoutformat(No of objects successfully deleted s＼n
modegetDeletedObjects()size())
Systemoutformat(No of objects failed to delete s＼n
modegetErrors()size())
Systemoutformat(Printing error data＼n)
for (DeleteError deleteError modegetErrors()){
Systemoutformat(Object Key s＼ts＼ts＼n
deleteErrorgetKey() deleteErrorgetCode()
deleteErrorgetMessage())
}
}
}
API Version 20060301
249Amazon Simple Storage Service Developer Guide
Deleting Objects
Example 2 MultiObject Delete (VersionEnabled Bucket)
The following Java code example uses the MultiObject Delete API to delete objects from a version
enabled bucket
Before you can test the sample you must create a sample bucket and provide the bucket name in the
example You can use the AWS Management Console to create a bucket
The example performs the following actions
1 Enable versioning on the bucket
2 Perform a versioneddelete
The example first uploads the sample objects In response Amazon S3 returns the version IDs for
each sample object that you uploaded The example then deletes these objects using the Multi
Object Delete API In the request it specifies both the object keys and the version IDs (that is
versioned delete)
3 Perform a nonversioned delete
The example uploads the new sample objects Then it deletes the objects using the MultiObject
API However in the request it specifies only the object keys In this case Amazon S3 adds the
delete markers and the objects disappear from your bucket
4 Delete the delete markers
To illustrate how the delete markers work the sample deletes the delete markers In the MultiObject
Delete request it specifies the object keys and the version IDs of the delete markers it received in
the response in the preceding step This action makes the objects reappear in your bucket
For information about how to create and test a working sample see Testing the Java Code
Examples (p 564)
import javaioByteArrayInputStream
import javaioIOException
import javautilArrayList
import javautilList
import javautilRandom
import comamazonawsAmazonClientException
import comamazonawsAmazonServiceException
import comamazonawsauthprofileProfileCredentialsProvider
import comamazonawsservicess3AmazonS3Client
import comamazonawsservicess3modelBucketVersioningConfiguration
import comamazonawsservicess3modelCannedAccessControlList
import comamazonawsservicess3modelDeleteObjectsRequest
import comamazonawsservicess3modelDeleteObjectsRequestKeyVersion
import comamazonawsservicess3modelDeleteObjectsResult
import comamazonawsservicess3modelDeleteObjectsResultDeletedObject
import comamazonawsservicess3modelMultiObjectDeleteException
import
comamazonawsservicess3modelMultiObjectDeleteExceptionDeleteError
import comamazonawsservicess3modelObjectMetadata
import comamazonawsservicess3modelPutObjectRequest
import comamazonawsservicess3modelPutObjectResult
import
comamazonawsservicess3modelSetBucketVersioningConfigurationRequest
public class DeleteMultipleObjectsVersionEnabledBucket {
static String bucketName *** Provide a bucket name ***
static AmazonS3Client s3Client
public static void main(String[] args) throws IOException {
try {
s3Client new AmazonS3Client(new ProfileCredentialsProvider())
1 Enable versioning on the bucket
enableVersioningOnBucket(s3Client bucketName)
2a Upload sample objects
List keysAndVersions1 putObjects(3)
2b Delete specific object versions
multiObjectVersionedDelete(keysAndVersions1)
3a Upload samples objects
List keysAndVersions2 putObjects(3)
3b Delete objects using only keys Amazon S3 creates a delete
marker and
returns its version Id in the response
DeleteObjectsResult response
multiObjectNonVersionedDelete(keysAndVersions2)
3c Additional exercise using multiobject versioned delete
remove the
delete markers received in the preceding response This
results in your objects
reappear in your bucket
multiObjectVersionedDeleteRemoveDeleteMarkers(response)

} catch (AmazonServiceException ase) {
Systemoutprintln(Caught an AmazonServiceException)
Systemoutprintln(Error Message + asegetMessage())
Systemoutprintln(HTTP Status Code + asegetStatusCode())
Systemoutprintln(AWS Error Code + asegetErrorCode())
Systemoutprintln(Error Type + asegetErrorType())
Systemoutprintln(Request ID + asegetRequestId())
} catch (AmazonClientException ace) {
Systemoutprintln(Caught an AmazonClientException)
Systemoutprintln(Error Message + acegetMessage())
}
}
static void enableVersioningOnBucket(AmazonS3Client s3Client
String bucketName) {
BucketVersioningConfiguration config new
BucketVersioningConfiguration()
withStatus(BucketVersioningConfigurationENABLED)
SetBucketVersioningConfigurationRequest
setBucketVersioningConfigurationRequest new
SetBucketVersioningConfigurationRequest(
bucketName config)

s3ClientsetBucketVersioningConfiguration(setBucketVersioningConfigurationRequest)
}
static List putObjects(int number) {
List keys new ArrayList()
String content This is the content body
for (int i 0 i < number i++) {
String key ObjectToDelete + new Random()nextInt()
ObjectMetadata metadata new ObjectMetadata()
metadatasetHeader(Subject ContentAsObject)
metadatasetHeader(ContentLength (long)contentlength())
PutObjectRequest request new PutObjectRequest(bucketName key
new ByteArrayInputStream(contentgetBytes()) metadata)

withCannedAcl(CannedAccessControlListAuthenticatedRead)
PutObjectResult response s3ClientputObject(request)
KeyVersion keyVersion new KeyVersion(key
responsegetVersionId())
keysadd(keyVersion)
}
return keys
}
static void multiObjectVersionedDelete(List keys) {
DeleteObjectsRequest multiObjectDeleteRequest new
DeleteObjectsRequest(
bucketName)withKeys(keys)
DeleteObjectsResult delObjRes null
try {
delObjRes s3ClientdeleteObjects(multiObjectDeleteRequest)
Systemoutformat(Successfully deleted all the s items＼n
delObjResgetDeletedObjects()size())
} catch(MultiObjectDeleteException mode) {
printDeleteResults(mode)
}
}
static DeleteObjectsResult multiObjectNonVersionedDelete(List
keys) {
Multiobject delete by specifying only keys (no version ID)
DeleteObjectsRequest multiObjectDeleteRequest new
DeleteObjectsRequest(
bucketName)
Create request that include only object key names
List justKeys new ArrayList()
for (KeyVersion key keys) {
justKeysadd(new KeyVersion(keygetKey()))
}
multiObjectDeleteRequestsetKeys(justKeys)
Execute DeleteObjects Amazon S3 add delete marker for each
object
deletion The objects no disappear from your bucket (verify)
DeleteObjectsResult delObjRes null
try {
delObjRes s3ClientdeleteObjects(multiObjectDeleteRequest)
Systemoutformat(Successfully deleted all the s items＼n
delObjResgetDeletedObjects()size())
} catch (MultiObjectDeleteException mode) {
printDeleteResults(mode)
}
return delObjRes
}
static void multiObjectVersionedDeleteRemoveDeleteMarkers(
DeleteObjectsResult response) {
List keyVersionList new ArrayList()
for (DeletedObject deletedObject responsegetDeletedObjects()) {
keyVersionListadd(new KeyVersion(deletedObjectgetKey()
deletedObjectgetDeleteMarkerVersionId()))
}
Create a request to delete the delete markers
DeleteObjectsRequest multiObjectDeleteRequest2 new
DeleteObjectsRequest(
bucketName)withKeys(keyVersionList)
Now delete the delete marker bringing your objects back to the
bucket
DeleteObjectsResult delObjRes null
try {
delObjRes s3ClientdeleteObjects(multiObjectDeleteRequest2)
Systemoutformat(Successfully deleted all the s items＼n
delObjResgetDeletedObjects()size())
} catch (MultiObjectDeleteException mode) {
printDeleteResults(mode)
}
}
static void printDeleteResults(MultiObjectDeleteException mode) {
Systemoutformat(s ＼n modegetMessage())
Systemoutformat(No of objects successfully deleted s＼n
modegetDeletedObjects()size())
Systemoutformat(No of objects failed to delete s＼n
modegetErrors()size())
Systemoutformat(Printing error data＼n)
for (DeleteError deleteError modegetErrors()){
Systemoutformat(Object Key s＼ts＼ts＼n
deleteErrorgetKey() deleteErrorgetCode()
deleteErrorgetMessage())
}
}
}
API Version 20060301
250Amazon Simple Storage Service Developer Guide
Deleting Objects
Deleting Multiple Objects Using the AWS SDK for NET
The following tasks guide you through using the AWS SDK for NET classes to delete multiple objects
in a single HTTP request
Deleting Multiple Objects (NonVersioned Bucket)
1 Create an instance of the AmazonS3Client class
2 Create an instance of the DeleteObjectsRequest class and provide list of the object
keys you want to delete
3 Execute the AmazonS3ClientDeleteObjects method
If one or more objects fail to delete Amazon S3 throws a DeleteObjectsException
The following C# code sample demonstrates the preceding steps
DeleteObjectsRequest multiObjectDeleteRequest new DeleteObjectsRequest()
multiObjectDeleteRequestBucketName bucketName

multiObjectDeleteRequestAddKey(