s3 Api

Amazon Simple Storage Service
API Reference
API Version 2006-03-01
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service: API Reference

Copyright © 2019 Amazon Web Services, Inc. and/or 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 Amazon.
Table of Contents
Amazon S3 REST API Introduction ....................................................................................................... 1
Common Request Headers .................................................................................................................. 2
Common Response Headers ................................................................................................................ 4
Error Responses ................................................................................................................................. 6
REST Error Responses ................................................................................................................. 6
List of Error Codes ..................................................................................................................... 7
Authenticating Requests (AWS Signature Version 4) .............................................................................. 14
Authentication Methods ............................................................................................................ 15
Introduction to Signing Requests ............................................................................................... 15
Using an Authorization Header .................................................................................................. 16
Overview ......................................................................................................................... 16
Signature Calculation: Transfer Payload in a Single Chunk ..................................................... 18
Signature Calculation: Transfer Payload in Multiple Chunks .................................................... 29
Using Query Parameters ........................................................................................................... 36
Calculating a Signature ..................................................................................................... 38
An Example ..................................................................................................................... 40
Examples: Signature Calculations ................................................................................................ 41
Signature Calculation Examples Using Java .......................................................................... 41
Signature Calculation Examples Using C# ............................................................................ 42
Authenticating HTTP POST Requests .......................................................................................... 43
Calculating a Signature ..................................................................................................... 44
Amazon S3 Signature Version 4 Authentication Specific Policy Keys ................................................ 45
Bucket Policy Examples Using Signature Version 4 Related Condition Keys ............................... 47
Browser-Based Uploads Using POST ................................................................................................... 49
Browser-Based Uploads Using HTTP POST ................................................................................... 49
Calculating a Signature ............................................................................................................. 50
Creating HTML Forms ............................................................................................................... 51
HTML Form Declaration .................................................................................................... 52
HTML Form Fields ............................................................................................................ 52
Creating a POST Policy ............................................................................................................. 56
Expiration ........................................................................................................................ 56
Condition Matching .......................................................................................................... 56
Conditions ....................................................................................................................... 57
Character Escaping ........................................................................................................... 59
POST Upload Example .............................................................................................................. 61
Uploading a File to Amazon S3 Using HTTP POST ................................................................ 61
Using POST with Adobe Flash .................................................................................................... 63
Using POST with Adobe Flash ............................................................................................ 63
Browser-Based Uploads Using AWS Amplify ................................................................................ 63
Using the AWS Amplify JavaScript library to Upload Files to Amazon S3 .................................. 64
More Info ........................................................................................................................ 64
Operations on the Service ................................................................................................................. 65
GET Service ............................................................................................................................. 65
Description ...................................................................................................................... 65
Requests ......................................................................................................................... 65
Responses ....................................................................................................................... 65
Examples ......................................................................................................................... 67
Related Resources ............................................................................................................ 67
Operations on AWS Accounts ............................................................................................................. 68
Block Public Access ................................................................................................................... 68
DELETE PublicAccessBlock ................................................................................................. 68
GET PublicAccessBlock ...................................................................................................... 69
PUT PublicAccessBlock ...................................................................................................... 72
Batch Operations ..................................................................................................................... 75

iii
CreateJob ........................................................................................................................ 77
DescribeJob ..................................................................................................................... 81
ListJobs ........................................................................................................................... 84
UpdateJobStatus .............................................................................................................. 87
UpdateJobPriority ............................................................................................................. 90
Batch Operations Common Elements .................................................................................. 92
Operations on Buckets .................................................................................................................... 102
DELETE Bucket ....................................................................................................................... 104
Description .................................................................................................................... 104
Requests ........................................................................................................................ 104
Responses ...................................................................................................................... 104
Examples ....................................................................................................................... 104
Related Resources ........................................................................................................... 105
DELETE Bucket analytics .......................................................................................................... 106
Description .................................................................................................................... 106
Requests ........................................................................................................................ 106
Responses ...................................................................................................................... 107
Examples ....................................................................................................................... 107
DELETE Bucket cors ................................................................................................................ 108
Description .................................................................................................................... 108
Requests ........................................................................................................................ 108
Responses ...................................................................................................................... 108
Examples ....................................................................................................................... 108
DELETE Bucket encryption ....................................................................................................... 110
Description .................................................................................................................... 110
Requests ........................................................................................................................ 110
Responses ...................................................................................................................... 110
Examples ....................................................................................................................... 110
DELETE Bucket inventory ......................................................................................................... 112
Description .................................................................................................................... 112
Requests ........................................................................................................................ 112
Responses ...................................................................................................................... 113
Examples ....................................................................................................................... 113
DELETE Bucket lifecycle ........................................................................................................... 114
Description .................................................................................................................... 114
Requests ........................................................................................................................ 114
Responses ...................................................................................................................... 114
Examples ....................................................................................................................... 115
DELETE PublicAccessBlock ....................................................................................................... 115
Description .................................................................................................................... 115
Requests ........................................................................................................................ 115
Responses ...................................................................................................................... 116
DELETE Bucket metrics ............................................................................................................ 116
Description .................................................................................................................... 116
Requests ........................................................................................................................ 117
DELETE Bucket policy .............................................................................................................. 119
Description .................................................................................................................... 119
Requests ........................................................................................................................ 119
Responses ...................................................................................................................... 119
Examples ....................................................................................................................... 120

iv
DELETE Bucket replication ....................................................................................................... 121

Description .................................................................................................................... 121
Requests ........................................................................................................................ 121
Responses ...................................................................................................................... 121
Examples ....................................................................................................................... 121
DELETE Bucket tagging ........................................................................................................... 123
Description .................................................................................................................... 123
Requests ........................................................................................................................ 123
Responses ...................................................................................................................... 123
Examples ....................................................................................................................... 123
DELETE Bucket website ........................................................................................................... 125
Description .................................................................................................................... 125
Requests ........................................................................................................................ 125
Responses ...................................................................................................................... 125
Examples ....................................................................................................................... 126
GET Bucket (List Objects) Version 2 .......................................................................................... 127
Description .................................................................................................................... 127
Requests ........................................................................................................................ 127
Responses ...................................................................................................................... 129
Examples ....................................................................................................................... 132
More Info ...................................................................................................................... 136
GET Bucket (List Objects) Version 1 .................................................................................. 137
GET Bucket accelerate ............................................................................................................. 146
Description .................................................................................................................... 146
Requests ........................................................................................................................ 146
Responses ...................................................................................................................... 147
Examples ....................................................................................................................... 147
GET Bucket acl ....................................................................................................................... 149
Description .................................................................................................................... 149
Requests ........................................................................................................................ 149
Responses ...................................................................................................................... 149
Examples ....................................................................................................................... 151
GET Bucket analytics ............................................................................................................... 152
Description .................................................................................................................... 152
Requests ........................................................................................................................ 152
Responses ...................................................................................................................... 153
Examples ....................................................................................................................... 155
GET Bucket cors ..................................................................................................................... 157
Description .................................................................................................................... 157
Requests ........................................................................................................................ 157
Responses ...................................................................................................................... 157
Special Errors ................................................................................................................. 159
Examples ....................................................................................................................... 159
GET Bucket encryption ............................................................................................................ 161
Description .................................................................................................................... 161
Requests ........................................................................................................................ 161
Responses ...................................................................................................................... 161
Examples ....................................................................................................................... 163
GET Bucket Inventory .............................................................................................................. 165

v
Description .................................................................................................................... 165

Requests ........................................................................................................................ 165
Responses ...................................................................................................................... 166
Examples ....................................................................................................................... 169
GET Bucket lifecycle ................................................................................................................ 171
Description .................................................................................................................... 171
Requests ........................................................................................................................ 171
Responses ...................................................................................................................... 171
Special Errors ................................................................................................................. 176
Examples ....................................................................................................................... 176
GET Bucket location ................................................................................................................ 178
Description .................................................................................................................... 178
Requests ........................................................................................................................ 178
GET PublicAccessBlock ............................................................................................................ 179
Description .................................................................................................................... 179
Requests ........................................................................................................................ 180
Responses ...................................................................................................................... 180
Examples ....................................................................................................................... 181
GET Bucket logging ................................................................................................................ 183
Description .................................................................................................................... 183
Requests ........................................................................................................................ 183
Responses ...................................................................................................................... 183
Examples ....................................................................................................................... 185
GET Bucket metrics ................................................................................................................. 186
Description .................................................................................................................... 186
Requests ........................................................................................................................ 186
Responses ...................................................................................................................... 186
Examples ....................................................................................................................... 188
GET Bucket notification ........................................................................................................... 190
Description .................................................................................................................... 190
Requests ........................................................................................................................ 190
Responses ...................................................................................................................... 190
Examples ....................................................................................................................... 193
GET Bucket object lock configuration ........................................................................................ 195
Request Syntax .............................................................................................................. 195
URI Request Parameters .................................................................................................. 195
Request Body ................................................................................................................. 195
Response Syntax ............................................................................................................ 195
Response Elements ......................................................................................................... 195
GET BucketPolicyStatus ........................................................................................................... 195
Description .................................................................................................................... 195
Requests ........................................................................................................................ 196
Responses ...................................................................................................................... 196
Examples ....................................................................................................................... 197
GET Bucket Object versions ..................................................................................................... 198
Description .................................................................................................................... 198
Requests ........................................................................................................................ 198
Responses ...................................................................................................................... 199
Examples ....................................................................................................................... 203

vi

GET Bucket policy ................................................................................................................... 210
Description .................................................................................................................... 210
Requests ........................................................................................................................ 210
Responses ...................................................................................................................... 210
Examples ....................................................................................................................... 211
GET Bucket replication ............................................................................................................ 212
Description .................................................................................................................... 212
Requests ........................................................................................................................ 212
Responses ...................................................................................................................... 212
Special Errors ................................................................................................................. 217
Examples ....................................................................................................................... 217
GET Bucket requestPayment .................................................................................................... 219
Description .................................................................................................................... 219
Requests ........................................................................................................................ 219
Responses ...................................................................................................................... 219
Examples ....................................................................................................................... 220
GET Bucket tagging ................................................................................................................ 221
Description .................................................................................................................... 221
Requests ........................................................................................................................ 221
Responses ...................................................................................................................... 221
Examples ....................................................................................................................... 222
GET Bucket versioning ............................................................................................................. 224
Description .................................................................................................................... 224
Requests ........................................................................................................................ 224
Responses ...................................................................................................................... 225
Examples ....................................................................................................................... 225
GET Bucket website ................................................................................................................ 227
Description .................................................................................................................... 227
Requests ........................................................................................................................ 227
Responses ...................................................................................................................... 227
Examples ....................................................................................................................... 228
HEAD Bucket .......................................................................................................................... 229
Description .................................................................................................................... 229
Requests ........................................................................................................................ 229
Responses ...................................................................................................................... 229
Examples ....................................................................................................................... 230
List Bucket Analytics Configurations .......................................................................................... 231
Description .................................................................................................................... 231
Requests ........................................................................................................................ 231
Responses ...................................................................................................................... 232
Examples ....................................................................................................................... 233
List Bucket Inventory Configurations ......................................................................................... 235
Description .................................................................................................................... 235
Requests ........................................................................................................................ 235
Responses ...................................................................................................................... 236
Examples ....................................................................................................................... 237
List Bucket Metrics Configurations ............................................................................................ 240
Description .................................................................................................................... 240

vii
Requests ........................................................................................................................ 240

Responses ...................................................................................................................... 241
Examples ....................................................................................................................... 241
List Multipart Uploads ............................................................................................................. 243
Description .................................................................................................................... 243
Requests ........................................................................................................................ 243
Responses ...................................................................................................................... 245
Examples ....................................................................................................................... 248
Related Actions .............................................................................................................. 251
PUT Bucket ............................................................................................................................ 252
Description .................................................................................................................... 252
Requests ........................................................................................................................ 252
Examples ....................................................................................................................... 255
PUT Bucket accelerate ............................................................................................................. 257
Description .................................................................................................................... 257
Requests ........................................................................................................................ 257
Responses ...................................................................................................................... 258
Examples ....................................................................................................................... 258
PUT Bucket acl ....................................................................................................................... 260
Description .................................................................................................................... 260
Requests ........................................................................................................................ 260
Responses ...................................................................................................................... 264
Examples ....................................................................................................................... 264
PUT Bucket analytics .............................................................................................................. 267
Description .................................................................................................................... 267
Requests ........................................................................................................................ 267
Responses ...................................................................................................................... 270
Examples ....................................................................................................................... 271
PUT Bucket cors ..................................................................................................................... 273
Description .................................................................................................................... 273
Requests ........................................................................................................................ 274
Responses ...................................................................................................................... 276
Examples ....................................................................................................................... 277
PUT Bucket encryption ............................................................................................................ 279
Description .................................................................................................................... 279
Requests ........................................................................................................................ 279
Responses ...................................................................................................................... 281
Examples ....................................................................................................................... 281
PUT Bucket inventory ............................................................................................................. 283
Description .................................................................................................................... 283
Requests ........................................................................................................................ 283
Responses ...................................................................................................................... 287
Examples ....................................................................................................................... 288
PUT Bucket lifecycle ............................................................................................................... 290
Description .................................................................................................................... 290
Requests ........................................................................................................................ 290
Responses ...................................................................................................................... 298
Examples ....................................................................................................................... 299

viii
PUT PublicAccessBlock ............................................................................................................ 302

Description .................................................................................................................... 302
Requests ........................................................................................................................ 302
Responses ...................................................................................................................... 304
Examples ....................................................................................................................... 304
PUT Bucket logging ................................................................................................................ 306
Description .................................................................................................................... 306
Requests ........................................................................................................................ 306
Responses ...................................................................................................................... 309
Examples ....................................................................................................................... 309
PUT Bucket metrics ................................................................................................................ 310
Description .................................................................................................................... 310
Requests ........................................................................................................................ 310
Responses ...................................................................................................................... 312
Examples ....................................................................................................................... 313
PUT Bucket notification ........................................................................................................... 315
Description .................................................................................................................... 315
Requests ........................................................................................................................ 315
Responses ...................................................................................................................... 319
Examples ....................................................................................................................... 320
PUT Bucket object lock configuration ........................................................................................ 323
Request Syntax .............................................................................................................. 323
Request Body ................................................................................................................. 323
Response Syntax ............................................................................................................ 323
PUT Bucket policy .................................................................................................................. 325
Description .................................................................................................................... 325
Requests ........................................................................................................................ 325
Responses ...................................................................................................................... 325
Examples ....................................................................................................................... 326
PUT Bucket replication ............................................................................................................ 327
Description .................................................................................................................... 327
Requests ........................................................................................................................ 327
Responses ...................................................................................................................... 334
Examples ....................................................................................................................... 334
PUT Bucket requestPayment .................................................................................................... 336
Description .................................................................................................................... 336
Requests ........................................................................................................................ 336
Responses ...................................................................................................................... 337
Examples ....................................................................................................................... 337
PUT Bucket tagging ................................................................................................................ 338
Description .................................................................................................................... 338
Requests ........................................................................................................................ 338
Responses ...................................................................................................................... 339
Examples ....................................................................................................................... 340
PUT Bucket versioning ............................................................................................................ 341
Description .................................................................................................................... 341

ix
Requests ........................................................................................................................ 341

Responses ...................................................................................................................... 343
Examples ....................................................................................................................... 343
PUT Bucket website ................................................................................................................ 345
Description .................................................................................................................... 345
Requests ........................................................................................................................ 345
Responses ...................................................................................................................... 349
Examples ....................................................................................................................... 350
Operations on Objects .................................................................................................................... 354
Delete Multiple Objects ........................................................................................................... 354
Description .................................................................................................................... 354
Requests ........................................................................................................................ 355
Responses ...................................................................................................................... 357
Examples ....................................................................................................................... 359
Related Actions .............................................................................................................. 362
DELETE Object ....................................................................................................................... 364
Description .................................................................................................................... 364
Requests ........................................................................................................................ 364
Responses ...................................................................................................................... 365
Examples ....................................................................................................................... 365
DELETE Object tagging ........................................................................................................... 368
Description .................................................................................................................... 368
Requests ........................................................................................................................ 368
Responses ...................................................................................................................... 368
Examples ....................................................................................................................... 368
GET Object ............................................................................................................................ 370
Description .................................................................................................................... 370
Versioning ..................................................................................................................... 371
Requests ........................................................................................................................ 371
Responses ...................................................................................................................... 375
Examples ....................................................................................................................... 378
GET Object ACL ...................................................................................................................... 383
Description .................................................................................................................... 383
Versioning ..................................................................................................................... 383
Requests ........................................................................................................................ 383
Responses ...................................................................................................................... 383
Examples ....................................................................................................................... 385
GET Object legal hold ............................................................................................................. 387
Request Syntax .............................................................................................................. 387
Request Body ................................................................................................................. 387
Response Syntax ............................................................................................................ 387
GET Object retention .............................................................................................................. 388
Request Syntax .............................................................................................................. 388
Request Body ................................................................................................................. 388
Response Syntax ............................................................................................................ 388
GET Object tagging ................................................................................................................ 389

x
Description .................................................................................................................... 389

Requests ........................................................................................................................ 389
Responses ...................................................................................................................... 389
Examples ....................................................................................................................... 390
GET Object torrent ................................................................................................................. 392
Description .................................................................................................................... 392
Requests ........................................................................................................................ 392
Responses ...................................................................................................................... 392
Examples ....................................................................................................................... 393
HEAD Object .......................................................................................................................... 394
Description .................................................................................................................... 394
Versioning ..................................................................................................................... 394
Requests ........................................................................................................................ 394
Responses ...................................................................................................................... 398
Examples ....................................................................................................................... 401
Sample Request for an Glacier Object ............................................................................... 402
Sample Response - Glacier Object .................................................................................... 402
OPTIONS object ..................................................................................................................... 404
Description .................................................................................................................... 404
Requests ........................................................................................................................ 404
Responses ...................................................................................................................... 405
Examples ....................................................................................................................... 406
POST Object .......................................................................................................................... 407
Description .................................................................................................................... 407
Versioning ..................................................................................................................... 407
Requests ........................................................................................................................ 407
Examples ....................................................................................................................... 417
POST Object restore ............................................................................................................... 419
Description .................................................................................................................... 419
Querying Archives with Select Requests ............................................................................ 419
Restoring Archives .......................................................................................................... 420
Requests ........................................................................................................................ 421
Responses ...................................................................................................................... 430
Examples ....................................................................................................................... 431
More Info ...................................................................................................................... 433
PUT Object ............................................................................................................................ 434
Description .................................................................................................................... 434
Versioning ..................................................................................................................... 434
Storage Class Options ..................................................................................................... 434
Access Permissions .......................................................................................................... 434
Requests ........................................................................................................................ 435
Responses ...................................................................................................................... 444
Examples ....................................................................................................................... 445
PUT Object legal hold ............................................................................................................. 449
Request Syntax .............................................................................................................. 449
Request Body ................................................................................................................. 449
Response Syntax ............................................................................................................ 449
PUT Object retention .............................................................................................................. 450

xi
Request Syntax .............................................................................................................. 450

Request Body ................................................................................................................. 450
Response Syntax ............................................................................................................ 450
PUT Object - Copy .................................................................................................................. 451
Description .................................................................................................................... 451
Versioning ..................................................................................................................... 452
Access Permissions .......................................................................................................... 452
Requests ........................................................................................................................ 452
Responses ...................................................................................................................... 462
Examples ....................................................................................................................... 464
PUT Object acl ....................................................................................................................... 467
Description .................................................................................................................... 467
Versioning ..................................................................................................................... 467
Requests ........................................................................................................................ 467
Responses ...................................................................................................................... 471
Examples ....................................................................................................................... 472
PUT Object tagging ................................................................................................................ 474
Description .................................................................................................................... 474
Requests ........................................................................................................................ 474
Responses ...................................................................................................................... 475
Examples ....................................................................................................................... 476
SELECT Object Content ........................................................................................................... 477
Description .................................................................................................................... 477
Requests ........................................................................................................................ 477
Responses ...................................................................................................................... 485
Examples ....................................................................................................................... 501
Notes ............................................................................................................................ 503
Abort Multipart Upload ........................................................................................................... 504
Description .................................................................................................................... 504
Requests ........................................................................................................................ 504
Responses ...................................................................................................................... 504
Examples ....................................................................................................................... 505
Related Actions .............................................................................................................. 505
Complete Multipart Upload ..................................................................................................... 506
Description .................................................................................................................... 506
Requests ........................................................................................................................ 506
Responses ...................................................................................................................... 507
Examples ....................................................................................................................... 509
Related Actions .............................................................................................................. 511
Initiate Multipart Upload ......................................................................................................... 512
Description .................................................................................................................... 512
Requests ........................................................................................................................ 512
Responses ...................................................................................................................... 518
Examples ....................................................................................................................... 520
Related Actions .............................................................................................................. 521
List Parts ............................................................................................................................... 522
Description .................................................................................................................... 522
Requests ........................................................................................................................ 522
Responses ...................................................................................................................... 523
Examples ....................................................................................................................... 526

xii
Related Actions .............................................................................................................. 527

Upload Part ........................................................................................................................... 528
Description .................................................................................................................... 528
Requests ........................................................................................................................ 528
Responses ...................................................................................................................... 530
Examples ....................................................................................................................... 531
Related Actions .............................................................................................................. 532
Upload Part - Copy ................................................................................................................. 534
Description .................................................................................................................... 534
Requests ........................................................................................................................ 534
Versioning ..................................................................................................................... 538
Responses ...................................................................................................................... 538
Examples ....................................................................................................................... 540
Related Actions .............................................................................................................. 541
Data Types .................................................................................................................................... 542
DefaultRetention .................................................................................................................... 543
Contents ........................................................................................................................ 543
ObjectLockConfiguration ......................................................................................................... 544
Contents ........................................................................................................................ 544
ObjectLockLegalHold .............................................................................................................. 545
Contents ........................................................................................................................ 545
ObjectLockRetention ............................................................................................................... 546
Contents ........................................................................................................................ 546
ObjectLockRule ...................................................................................................................... 547
Contents ........................................................................................................................ 547
Resources ...................................................................................................................................... 548
Document History .......................................................................................................................... 549
Appendix ....................................................................................................................................... 565
Appendix: SOAP API ................................................................................................................ 565
Operations on the Service (SOAP API) ............................................................................... 565
Operations on Buckets (SOAP API) .................................................................................... 566
Operations on Objects (SOAP API) .................................................................................... 575
SOAP Error Responses ..................................................................................................... 590
Appendix: Lifecycle Configuration APIs (Deprecated) ................................................................... 592
PUT Bucket lifecycle (Deprecated) ..................................................................................... 593
GET Bucket lifecycle (Deprecated) ..................................................................................... 603
Glossary ........................................................................................................................................ 610
API Reference ................................................................................................................................. 612
Data Types ............................................................................................................................ 612
Amazon Simple Storage Service ....................................................................................... 615
AWS S3 Control ............................................................................................................. 754

xiii
Amazon S3 REST API Introduction

Welcome to the Amazon Simple Storage Service API Reference. This guide explains the Amazon Simple
Storage Service (Amazon S3) application programming interface (API). It describes various API
operations, related request and response structures, and error codes. The current version of the Amazon
S3 API is 2006-03-01.
Amazon S3 supports the REST API.

Note
Support for SOAP over HTTP is deprecated, but it is still available over HTTPS. However, new
Amazon S3 features will not be supported for SOAP. We recommend that you use either the
REST API or the AWS SDKs.
Read the following about authentication and access control before going to specific API topics.
Requests to Amazon S3 can be authenticated or anonymous. Authenticated access requires credentials

that AWS can use to authenticate your requests. When making REST API calls directly from your code,
you create a signature using valid credentials and include the signature in your request. For information
about various authentication methods and signature calculations, see Authenticating Requests (AWS
Signature Version 4) (p. 14).
Making REST API calls directly from your code can be cumbersome. It requires you to write the necessary
code to calculate a valid signature to authenticate your requests. We recommend the following
alternatives instead:
• Use the AWS SDKs to send your requests (see Sample Code and Libraries). With this option, you
don't need to write code to calculate a signature for request authentication because the SDK clients
authenticate your requests by using access keys that you provide. Unless you have a good reason not
to, you should always use the AWS SDKs.
• Use the AWS CLI to make Amazon S3 API calls. For information about setting up the AWS CLI and
example Amazon S3 commands see the following topics:
Set Up the AWS CLI in the Amazon Simple Storage Service Developer Guide.
Using Amazon S3 with the AWS Command Line Interface in the AWS Command Line Interface User
Guide.
You can have valid credentials to authenticate your requests, but unless you have permissions you cannot
create or access Amazon S3 resources. For example, you must have permissions to create an S3 bucket
or get an object from your bucket. If you use root credentials of your AWS account, you have all the
permissions. However, using root credentials is not recommended. Instead, we recommend that you
create IAM users in your account and manage user permissions. For more information, see Managing
Access Permissions to Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.

1
Common Request Headers

The following table describes headers that can be used by various types of Amazon S3 REST requests.
Header Name Description
Authorization The information required for request authentication. For more

information, go to The Authentication Header in the Amazon
Simple Storage Service Developer Guide. For anonymous requests
this header is not required.
Content-Length Length of the message (without the headers) according to RFC

2616. This header is required for PUTs and operations that load
XML, such as logging and ACLs.
Content-Type The content type of the resource in case the request content in
the body. Example: text/plain
Content-MD5 The base64 encoded 128-bit MD5 digest of the message (without
the headers) according to RFC 1864. This header can be used as a
message integrity check to verify that the data is the same data
that was originally sent. Although it is optional, we recommend
using the Content-MD5 mechanism as an end-to-end integrity
check. For more information about REST request authentication,
go to REST Authentication in the Amazon Simple Storage Service
Developer Guide.
Date The current date and time according to the requester. Example:
Wed, 01 Mar 2006 12:00:00 GMT. When you specify the
Authorization header, you must specify either the x-amz-
date or the Date header.
Expect When your application uses 100-continue, it does not send the
request body until it receives an acknowledgment. If the message
is rejected based on the headers, the body of the message is not
sent. This header can be used only if you are sending a body.
Valid Values: 100-continue
Host For path-style requests, the value is s3.amazonaws.com.

For virtual-style requests, the value is
BucketName.s3.amazonaws.com. For more information, go to
Virtual Hosting in the Amazon Simple Storage Service Developer
Guide.
This header is required for HTTP 1.1 (most toolkits add this header
automatically); optional for HTTP/1.0 requests.
x-amz-content-sha256 When using signature version 4 to authenticate request, this

header provides a hash of the request payload. For more
information see Signature Calculations for the Authorization
Header: Transferring Payload in a Single Chunk (AWS Signature
Version 4) (p. 18). When uploading object in chunks, you set
the value to STREAMING-AWS4-HMAC-SHA256-PAYLOAD to
indicate that the signature covers only headers and that there is

2
Header Name Description

no payload. For more information, see Signature Calculations for
the Authorization Header: Transferring Payload in Multiple Chunks
(Chunked Upload) (AWS Signature Version 4) (p. 29).
x-amz-date The current date and time according to the requester. Example:
Wed, 01 Mar 2006 12:00:00 GMT. When you specify the
Authorization header, you must specify either the x-amz-
date or the Date header. If you specify both, the value specified
for the x-amz-date header takes precedence.
x-amz-security-token This header can be used in the following scenarios:
• Provide security tokens for Amazon DevPay operations -

Each request that uses Amazon DevPay requires two x-amz-
security-token headers: one for the product token and one
for the user token. When Amazon S3 receives an authenticated
request, it compares the computed signature with the provided
signature. Improperly formatted multi-value headers used to
calculate a signature can cause authentication issues.
• Provide security token when using temporary security
credentials - When making requests using temporary security
credentials you obtained from IAM you must provide a security
token using this header. To learn more about temporary security
credentials, go to Making Requests.
This header is required for requests that use Amazon DevPay and
requests that are signed using temporary security credentials.

3
Common Response Headers

The following table describes response headers that are common to most AWS S3 responses.
Name Description
Content-Length The length in bytes of the body in the response.
Type: String
Default: None
Content-Type The MIME type of the content. For example, Content-Type: text/html;
charset=utf-8
Type: String
Default: None
Connection specifies whether the connection to the server is open or closed.
Type: Enum
Valid Values: open | close
Default: None
Date The date and time Amazon S3 responded, for example, Wed, 01 Mar 2006
12:00:00 GMT.
Type: String
Default: None
ETag The entity tag is a hash of the object. The ETag reflects changes only to the
contents of an object, not its metadata. The ETag may or may not be an MD5
digest of the object data. Whether or not it is depends on how the object was
created and how it is encrypted as described below:
• Objects created by the PUT Object, POST Object, or Copy operation, or

through the AWS Management Console, and are encrypted by SSE-S3 or
plaintext, have ETags that are an MD5 digest of their object data.
• Objects created by the PUT Object, POST Object, or Copy operation, or
through the AWS Management Console, and are encrypted by SSE-C or SSE-
KMS, have ETags that are not an MD5 digest of their object data.
• If an object is created by either the Multipart Upload or Part Copy operation,
the ETag is not an MD5 digest, regardless of the method of encryption.
Type: String
Server The name of the server that created the response.
Type: String
Default: AmazonS3

4
Name Description
x-amz-delete- Specifies whether the object returned was (true) or was not (false) a delete
marker marker.
Type: Boolean
Valid Values: true | false
Default: false
x-amz-id-2 A special token that is used together with the x-amz-request-id header to
help AWS troubleshoot problems. For information about AWS support using
these request IDs, see Troubleshooting Amazon S3.
Type: String
Default: None
x-amz-request- A value created by Amazon S3 that uniquely identifies the request. This value
id is used together with the x-amz-id-2 header to help AWS troubleshoot
problems. For information about AWS support using these request IDs, see
Troubleshooting Amazon S3.
Type: String
Default: None
x-amz-version- The version of the object. When you enable versioning, Amazon S3 generates
id a random number for objects added to a bucket. The value is UTF-8 encoded
and URL ready. When you PUT an object in a bucket where versioning has been
suspended, the version ID is always null.
Type: String
Valid Values: null | any URL-ready, UTF-8 encoded string
Default: null

5
REST Error Responses
Error Responses
This section provides reference information about Amazon S3 errors.
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.
Topics
• REST Error Responses (p. 6)
• List of Error Codes (p. 7)
REST Error Responses

When an error occurs, the header information contains the following:
• Content-Type: application/xml
• An appropriate 3xx, 4xx, or 5xx HTTP status code
The body or the response also contains information about the error. The following sample error response
shows the structure of response elements common to all REST error responses.
<?xml version="1.0" encoding="UTF-8"?>

<Error>
<Code>NoSuchKey</Code>
<Message>The resource you requested does not exist</Message>
<Resource>/mybucket/myfoto.jpg</Resource>
<RequestId>4442587FB7D0A2F9</RequestId>
</Error>
The following table explains the REST error response elements.
Name Description
Code The error code is a string that uniquely identifies an error condition. It is meant to
be read and understood by programs that detect and handle errors by type. For
more information, see List of Error Codes (p. 7).
Type: String
Ancestor: Error
Error Container for all error elements.
Type: Container
Ancestor: None
Message The error message contains a generic description of the error condition in English. It
is intended for a human audience. Simple programs display the message directly to
the end user if they encounter an error condition they don't know how or don't care

6
List of Error Codes
Name Description
to handle. Sophisticated programs with more exhaustive error handling and proper
internationalization are more likely to ignore the error message.
Type: String
Ancestor: Error
RequestId ID of the request associated with the error.
Type: String
Ancestor: Error
Resource The bucket or object that is involved in the error.
Type: String
Ancestor: Error
Many error responses contain additional structured data meant to be read and understood by a
developer diagnosing programming errors. For example, if you send a Content-MD5 header with a REST
PUT request that doesn't match the digest calculated on the server, you receive a BadDigest error. The
error response also includes as detail elements the digest we calculated, and the digest you told us to
expect. During development, you can use this information to diagnose the error. In production, a well-
behaved program might include this information in its error log.
For information about general response elements, go to Error Responses.
List of Error Codes

The following table lists Amazon S3 error codes.
Error Code Description HTTP SOAP

Status Fault
Code Code
Prefix
AccessDenied Access Denied 403 Client

Forbidden
AccountProblem There is a problem with your AWS 403 Client

account that prevents the operation Forbidden
from completing successfully. Please
contact AWS Support for further
assistance, see Contact Us.
AllAccessDisabled All access to this Amazon S3 resource 403 Client

has been disabled. Please contact Forbidden
AWS Support for further assistance,
see Contact Us.
AmbiguousGrantByEmailAddress The email address you provided 400 Bad Client

is associated with more than one Request
account.

7
List of Error Codes

Status Fault
Code Code
Prefix
AuthorizationHeaderMalformed The authorization header you 400 Bad N/A

provided is invalid. Request
BadDigest The Content-MD5 you specified did 400 Bad Client

not match what we received. Request
BucketAlreadyExists The requested bucket name is not 409 Client

available. The bucket namespace is Conflict
shared by all users of the system.
Please select a different name and try
again.
BucketAlreadyOwnedByYou The bucket you tried to create already 409 Client

exists, and you own it. Amazon S3 Conflict
returns this error in all AWS Regions (in all
except us-east-1 (N. Virginia). For regions
legacy compatibility, if you re-create except us-
an existing bucket that you already east-1)
own in us-east-1, Amazon S3 returns
200 OK and resets the bucket access
control lists (ACLs).
BucketNotEmpty The bucket you tried to delete is not 409 Client

empty. Conflict
CredentialsNotSupported This request does not support 400 Bad Client

credentials. Request
CrossLocationLoggingProhibited Cross-location logging not allowed. 403 Client

Buckets in one geographic location Forbidden
cannot log information to a bucket in
another location.
EntityTooSmall Your proposed upload is smaller than 400 Bad Client

the minimum allowed object size. Request
EntityTooLarge Your proposed upload exceeds the 400 Bad Client

maximum allowed object size. Request
ExpiredToken The provided token has expired. 400 Bad Client

Request
Indicates that the versioning

IllegalVersioningConfigurationException 400 Bad Client
configuration specified in the request Request
is invalid.
IncompleteBody You did not provide the number of 400 Bad Client
bytes specified by the Content-Length Request
HTTP header
POST requires exactly one file upload

IncorrectNumberOfFilesInPostRequest 400 Bad Client
per request. Request

8
List of Error Codes

Status Fault
Code Code
Prefix
InlineDataTooLarge Inline data exceeds the maximum 400 Bad Client

allowed size. Request
InternalError We encountered an internal error. 500 Server

Please try again. Internal
Server
Error
InvalidAccessKeyId The AWS access key ID you provided 403 Client

does not exist in our records. Forbidden
InvalidAddressingHeader You must specify the Anonymous role. N/A Client
InvalidArgument Invalid Argument 400 Bad Client

Request
InvalidBucketName The specified bucket is not valid. 400 Bad Client

Request
InvalidBucketState The request is not valid with the 409 Client

current state of the bucket. Conflict
InvalidDigest The Content-MD5 you specified is not 400 Bad Client

valid. Request
InvalidEncryptionAlgorithmError The encryption request you specified 400 Bad Client

is not valid. The valid value is AES256. Request
InvalidLocationConstraint The specified location constraint is 400 Bad Client

not valid. For more information about Request
Regions, see How to Select a Region
for Your Buckets.
InvalidObjectState The operation is not valid for the 403 Client

current state of the object. Forbidden
InvalidPart One or more of the specified parts 400 Bad Client

could not be found. The part might Request
not have been uploaded, or the
specified entity tag might not have
matched the part's entity tag.
InvalidPartOrder The list of parts was not in ascending 400 Bad Client
order. Parts list must be specified in Request
order by part number.
InvalidPayer All access to this object has been 403 Client

disabled. Please contact AWS Support Forbidden
for further assistance, see Contact Us.
InvalidPolicyDocument The content of the form does not 400 Bad Client
meet the conditions specified in the Request
policy document.

9
List of Error Codes

Status Fault
Code Code
Prefix
InvalidRange The requested range cannot be 416 Client

satisfied. Requested
Range
Not
Satisfiable
InvalidRequest Please use AWS4-HMAC-SHA256. 400 Bad N/A

Request
InvalidRequest SOAP requests must be made over an 400 Bad Client

HTTPS connection. Request
InvalidRequest Amazon S3 Transfer Acceleration is 400 Bad N/A

not supported for buckets with non- Request
DNS compliant names.
InvalidRequest Amazon S3 Transfer Acceleration 400 Bad N/A

is not supported for buckets with Request
periods (.) in their names.
InvalidRequest Amazon S3 Transfer Accelerate 400 Bad N/A

endpoint only supports virtual style Request
requests.
InvalidRequest Amazon S3 Transfer Accelerate is not 400 Bad N/A

configured on this bucket. Request
InvalidRequest Amazon S3 Transfer Accelerate is 400 Bad N/A

disabled on this bucket. Request
InvalidRequest Amazon S3 Transfer Acceleration is 400 Bad N/A

not supported on this bucket. Contact Request
AWS Support for more information.
InvalidRequest Amazon S3 Transfer Acceleration 400 Bad N/A

cannot be enabled on this bucket. Request
Contact AWS Support for more
information.
InvalidSecurity The provided security credentials are 403 Client

not valid. Forbidden
InvalidSOAPRequest The SOAP request body is invalid. 400 Bad Client

Request
InvalidStorageClass The storage class you specified is not 400 Bad Client
valid. Request
InvalidTargetBucketForLogging The target bucket for logging does 400 Bad Client
not exist, is not owned by you, or does Request
not have the appropriate grants for
the log-delivery group.
InvalidToken The provided token is malformed or 400 Bad Client

otherwise invalid. Request

10
List of Error Codes

Status Fault
Code Code
Prefix
InvalidURI Couldn't parse the specified URI. 400 Bad Client

Request
KeyTooLongError Your key is too long. 400 Bad Client

Request
MalformedACLError The XML you provided was not well- 400 Bad Client
formed or did not validate against our Request
published schema.
MalformedPOSTRequest The body of your POST request is not 400 Bad Client
well-formed multipart/form-data. Request
MalformedXML This happens when the user sends 400 Bad Client
malformed XML (XML that doesn't Request
conform to the published XSD) for the
configuration. The error message is,
"The XML you provided was not well-
formed or did not validate against our
published schema."
MaxMessageLengthExceeded Your request was too big. 400 Bad Client

Request
MaxPostPreDataLengthExceededErrorYour POST request fields preceding 400 Bad Client

the upload file were too large. Request
MetadataTooLarge Your metadata headers exceed the 400 Bad Client

maximum allowed metadata size. Request
MethodNotAllowed The specified method is not allowed 405 Client

against this resource. Method
Not
Allowed
MissingAttachment A SOAP attachment was expected, N/A Client

but none were found.
MissingContentLength You must provide the Content-Length 411 Client

HTTP header. Length
Required
MissingRequestBodyError This happens when the user sends an 400 Bad Client
empty XML document as a request. Request
The error message is, "Request body is
empty."
MissingSecurityElement The SOAP 1.1 request is missing a 400 Bad Client

security element. Request
MissingSecurityHeader Your request is missing a required 400 Bad Client

header. Request
NoLoggingStatusForKey There is no such thing as a logging 400 Bad Client

status subresource for a key. Request

11
List of Error Codes

Status Fault
Code Code
Prefix
NoSuchBucket The specified bucket does not exist. 404 Not Client
Found
NoSuchBucketPolicy The specified bucket does not have a 404 Not Client
bucket policy. Found
NoSuchKey The specified key does not exist. 404 Not Client
Found
NoSuchLifecycleConfiguration The lifecycle configuration does not 404 Not Client

exist. Found
NoSuchUpload The specified multipart upload does 404 Not Client

not exist. The upload ID might be Found
invalid, or the multipart upload might
have been aborted or completed.
NoSuchVersion Indicates that the version ID specified 404 Not Client

in the request does not match an Found
existing version.
NotImplemented A header you provided implies 501 Not Server

functionality that is not implemented. Implemented
NotSignedUp Your account is not signed up for the 403 Client

Amazon S3 service. You must sign Forbidden
up before you can use Amazon S3.
You can sign up at the following URL:
https://aws.amazon.com/s3
OperationAborted A conflicting conditional operation 409 Client

is currently in progress against this Conflict
resource. Try again.
PermanentRedirect The bucket you are attempting to 301 Client

access must be addressed using the Moved
specified endpoint. Send all future Permanently
requests to this endpoint.
PreconditionFailed At least one of the preconditions you 412 Client

specified did not hold. Precondition
Failed
Redirect Temporary redirect. 307 Client

Moved
Temporarily
RestoreAlreadyInProgress Object restore is already in progress. 409 Client

Conflict
RequestIsNotMultiPartContent Bucket POST must be of the 400 Bad Client

enclosure-type multipart/form-data. Request

12
List of Error Codes

Status Fault
Code Code
Prefix
RequestTimeout Your socket connection to the server 400 Bad Client

was not read from or written to Request
within the timeout period.
RequestTimeTooSkewed The difference between the request 403 Client

time and the server's time is too large. Forbidden
RequestTorrentOfBucketError Requesting the torrent file of a bucket 400 Bad Client

is not permitted. Request
SignatureDoesNotMatch The request signature we calculated 403 Client

does not match the signature Forbidden
you provided. Check your AWS
secret access key and signing
method. For more information, see
REST Authentication and SOAP
Authentication for details.
ServiceUnavailable Reduce your request rate. 503 Server

Service
Unavailable
SlowDown Reduce your request rate. 503 Slow Server

Down
TemporaryRedirect You are being redirected to the bucket 307 Client

while DNS updates. Moved
Temporarily
TokenRefreshRequired The provided token must be 400 Bad Client

refreshed. Request
TooManyBuckets You have attempted to create more 400 Bad Client

buckets than allowed. Request
UnexpectedContent This request does not support 400 Bad Client

content. Request
UnresolvableGrantByEmailAddress The email address you provided does 400 Bad Client
not match any account on record. Request
UserKeyMustBeSpecified The bucket POST must contain the 400 Bad Client
specified field name. If it is specified, Request
check the order of the fields.
The server side encryption

ServerSideEncryptionConfigurationNotFoundError 400 Bad Client
configuration was not found. Request

13
Authenticating Requests (AWS

Signature Version 4)
Topics
• Authentication Methods (p. 15)
• Introduction to Signing Requests (p. 15)
• Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) (p. 16)
• Authenticating Requests: Using Query Parameters (AWS Signature Version 4) (p. 36)
• Examples: Signature Calculations in AWS Signature Version 4 (p. 41)
• Authenticating Requests: Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 43)
• Amazon S3 Signature Version 4 Authentication Specific Policy Keys (p. 45)
Every interaction with Amazon S3 is either authenticated or anonymous. This section explains request
authentication with the AWS Signature Version 4 algorithm.
Note
If you use the AWS SDKs (see Sample Code and Libraries) to send your requests, you don't
need to read this section because the SDK clients authenticate your requests by using access
keys that you provide. Unless you have a good reason not to, you should always use the AWS
SDKs. In regions that support both signature versions, you can request AWS SDKs to use
specific signature version. For more information, see Specifying Signature Version in Request
Authentication in the Amazon Simple Storage Service Developer Guide. You need to read this
section only if you are implementing the AWS Signature Version 4 algorithm in your custom
client.
Authentication with AWS Signature version 4 provides some or all of the following, depending on how
you choose to sign your request:
• Verification of the identity of the requester – Authenticated requests require a signature that you
create by using your access keys (access key ID, secret access key). For information about getting access
keys, see Understanding and Getting Your Security Credentials in the AWS General Reference. If you are
using temporary security credentials, the signature calculations also require a security token. For more
information, see Requesting Temporary Security Credentials in the IAM User Guide.
• In-transit data protection – In order to prevent tampering with a request while it is in transit, you use
some of the request elements to calculate the request signature. Upon receiving the request, Amazon
S3 calculates the signature by using the same request elements. If any request component received by
Amazon S3 does not match the component that was used to calculate the signature, Amazon S3 will
reject the request.
• Protect against reuse of the signed portions of the request – The signed portions (using AWS
Signatures) of requests are valid within 15 minutes of the timestamp in the request. An unauthorized
party who has access to a signed request can modify the unsigned portions of the request without
affecting the request's validity in the 15 minute window. Because of this, we recommend that you
maximize protection by signing request headers and body, making HTTPS requests to Amazon S3,
and by using the s3:x-amz-content-sha256 condition key (see Amazon S3 Signature Version
4 Authentication Specific Policy Keys (p. 45)) in AWS policies to require users to sign S3 request
bodies.
Note
Amazon S3 supports Signature Version 4, a protocol for authenticating inbound API requests to
AWS services, in all AWS regions. At this time, AWS regions created before January 30, 2014 will

14
Authentication Methods
continue to support the previous protocol, Signature Version 2. Any new regions after January
30, 2014 will support only Signature Version 4 and therefore all requests to those regions must
be made with Signature Version 4. For more information about AWS Signature Version 2, see
Signing and Authenticating REST Requests in the Amazon Simple Storage Service Developer
Guide.
Authentication Methods
You can express authentication information by using one of the following methods:
• HTTP Authorization header – Using the HTTP Authorization header is the most common
method of authenticating an Amazon S3 request. All of the Amazon S3 REST operations (except for
browser-based uploads using POST requests) require this header. For more information about the
Authorization header value, and how to calculate signature and related options, see Authenticating
Requests: Using the Authorization Header (AWS Signature Version 4) (p. 16).
• Query string parameters – You can use a query string to express a request entirely in a URL. In
this case, you use query parameters to provide request information, including the authentication
information. Because the request signature is part of the URL, this type of URL is often referred to as
a presigned URL. You can use presigned URLs to embed clickable links, which can be valid for up to
seven days, in HTML. For more information, see Authenticating Requests: Using Query Parameters
(AWS Signature Version 4) (p. 36).
Amazon S3 also supports browser-based uploads that use an HTTP POST requests. With an HTTP
POST request, you can upload content to Amazon S3 directly from the browser. For information about
authenticating POST requests, see Browser-Based Uploads Using POST in the Amazon Simple Storage
Service Developer Guide.
Introduction to Signing Requests

Authentication information that you send in a request must include a signature. To calculate a signature,
you first concatenate select request elements to form a string, referred to as the string to sign. You then
use a signing key to calculate the hash-based message authentication code (HMAC) of the string to sign.
In AWS Signature Version 4, you don't use your secret access key to sign the request. Instead, you first
use your secret access key to create a signing key. The signing key is scoped to a specific region and
service, and it never expires.
The following diagram illustrates the general process of computing a signature.
The string to sign depends on the request type. For example, when you use the HTTP Authorization
header or the query parameters for authentication, you use a varying combination of request elements
to create the string to sign. For an HTTP POST request, the POST policy in the request is the string you

15
Using an Authorization Header
sign. For more information about computing string to sign, follow links provided at the end of this
section.
For signing key, the diagram shows series of calculations, where result of each step you feed into the
next step.The final step is the signing key.
Upon receiving an authenticated request, Amazon S3 servers re-create the signature by using the
authentication information that is contained in the request. If the signatures match, Amazon S3
processes your request; otherwise, the request is rejected.
For more information about authenticating requests, see the following topics:
• Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) (p. 16)
• Authenticating Requests: Using Query Parameters (AWS Signature Version 4) (p. 36)
• Authenticating Requests in Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 49)
Authenticating Requests: Using the Authorization

Header (AWS Signature Version 4)
Topics
• Overview (p. 16)
• Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 18)
• Signature Calculations for the Authorization Header: Transferring Payload in Multiple Chunks
(Chunked Upload) (AWS Signature Version 4) (p. 29)
Overview
Using the HTTP Authorization header is the most common method of providing authentication
information. Except for POST requests (p. 407) and requests that are signed by using query parameters,
all Amazon S3 bucket operations (p. 102) and object operations (p. 354) use the Authorization
request header to provide authentication information.
The following is an example of the Authorization header value. Line breaks are added to this example
for readability:
Authorization: AWS4-HMAC-SHA256
Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request,
SignedHeaders=host;range;x-amz-date,
Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
The following table describes the various components of the Authorization header value in the
preceding example:
Component Description
AWS4-HMAC-SHA256 The algorithm that was used to calculate the signature. You must
provide this value when you use AWS Signature Version 4 for
authentication.
The string specifies AWS Signature Version 4 (AWS4) and the

signing algorithm (HMAC-SHA256).

16
Overview
Component Description
Credential Your access key ID and the scope information, which includes the
date, region, and service that were used to calculate the signature.
This string has the following form:
<your-access-key-id>/<date>/<aws-region>/<aws-service>/
aws4_request
Where:
• <date> value is specified using YYYYMMDD format.

• <aws-service> value is s3 when sending request to Amazon
S3.
SignedHeaders A semicolon-separated list of request headers that you used to

compute Signature. The list includes header names only, and the
header names must be in lowercase. For example:
host;range;x-amz-date
Signature The 256-bit signature expressed as 64 lowercase hexadecimal

characters. For example:
fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
Note that the signature calculations vary depending on the option

you choose to transfer the payload.
The signature calculations vary depending on the method you choose to transfer the request payload. S3
supports the following options:
• Transfer payload in a single chunk – In this case, you have the following signature calculation options:
• Signed payload option – You can optionally compute the entire payload checksum and include it in
signature calculation. This provides added security but you need to read your payload twice or buffer
it in memory.
For example, in order to upload a file, you need to read the file first to compute a payload hash for
signature calculation and again for transmission when you create the request. For smaller payloads,
this approach might be preferable. However, for large files, reading the file twice can be inefficient,
so you might want to upload data in chunks instead.
We recommend you include payload checksum for added security.

• Unsigned payload option – Do not include payload checksum in signature calculation.
For step-by-step instructions to calculate signature and construct the Authorization header value, see
Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS
• Transfer payload in multiple chunks (chunked upload) – In this case you transfer payload in chunks.
You can transfer a payload in chunks regardless of the payload size.
You can break up your payload into chunks. These can be fixed or variable-size chunks. By uploading
data in chunks, you avoid reading the entire payload to calculate the signature. Instead, for the first
chunk, you calculate a seed signature that uses only the request headers. The second chunk contains

17
Signature Calculation: Transfer Payload in a Single Chunk
the signature for the first chunk, and each subsequent chunk contains the signature for the chunk
that precedes it. At the end of the upload, you send a final chunk with 0 bytes of data that contains
the signature of the last chunk of the payload. For more information, see Signature Calculations for
the Authorization Header: Transferring Payload in Multiple Chunks (Chunked Upload) (AWS Signature
Version 4) (p. 29).
When you send a request, you must tell Amazon S3 which of the preceding options you have chosen in
your signature calculation, by adding the x-amz-content-sha256 header with one of the following
values:
• If you choose chunked upload options, set the header value to STREAMING-AWS4-HMAC-SHA256-
PAYLOAD.
• If you choose to upload payload in a single chunk, set the header value to the payload checksum
(signed payload option), or set the value to the literal string UNSIGNED-PAYLOAD (unsigned payload
option).
Upon receiving the request, Amazon S3 re-creates the string to sign using information in the
Authorization header and the date header. It then verifies with authentication service the signatures
match. The request date can be specified by using either the HTTP Date or the x-amz-date header. If
both headers are present, x-amz-date takes precedence.
If the signatures match, Amazon S3 processes your request; otherwise, your request will fail.
For more information, see the following topics:
Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 18)
Signature Calculations for the Authorization Header: Transferring Payload in Multiple Chunks (Chunked
Upload) (AWS Signature Version 4) (p. 29)
Signature Calculations for the Authorization Header:

Transferring Payload in a Single Chunk (AWS
When using the Authorization header to authenticate requests, the header value includes, among
other things, a signature. The signature calculations vary depending on the choice you make for
transferring the payload (Overview (p. 16)). This section explains signature calculations when
you choose to transfer the payload in a single chunk. The example section (see Examples: Signature
Calculations (p. 23)) shows signature calculations and resulting Authorization headers that you can
use as a test suite to verify your code.
Important
When transferring payload in a single chunk, you can optionally choose to include the payload
hash in the signature calculations, referred as signed payload (if you don't include it, the payload
is considered unsigned). The signing procedure discussed in the following section applies to
both, but note the following differences:
• Signed payload option – You include the payload hash when constructing the canonical
request (that then becomes part of StringToSign, as explained in the signature calculation
section). You also specify the same value as the x-amz-content-sha256 header value when
sending the request to S3.
• Unsigned payload option – You include the literal string UNSIGNED-PAYLOAD when
constructing a canonical request, and set the same value as the x-amz-content-sha256
header value when sending the request to S3.

18
When you send your request to S3, the x-amz-content-sha256 header value informs S3
whether the payload is signed or not. Amazon S3 can then create signature accordingly for
verification.
Calculating a Signature
To calculate a signature, you first need a string to sign. You then calculate a HMAC-SHA256 hash of the
string to sign by using a signing key. The following diagram illustrates the process, including the various
components of the string that you create for signing
When Amazon S3 receives an authenticated request, it computes the signature and then compares it
with the signature that you provided in the request. For that reason, you must compute the signature by
using the same method that is used by Amazon S3. The process of putting a request in an agreed-upon
form for signing is called canonicalization.
The following table describes the functions that are shown in the diagram. You need to implement code
for these functions.
Function Description
Lowercase() Convert the string to lowercase.
Hex() Lowercase base 16 encoding.
SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function.
HMAC-SHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided. This is the final signature.
Trim() Remove any leading or trailing whitespace.
UriEncode() URI encode every byte. UriEncode() must enforce the following
rules:

19
• URI encode every byte except the unreserved characters: 'A'-'Z',
'a'-'z', '0'-'9', '-', '.', '_', and '~'.
• The space character is a reserved character and must be encoded
as "%20" (and not as "+").
• Each URI encoded byte is formed by a '%' and the two-digit
hexadecimal value of the byte.
• Letters in the hexadecimal value must be uppercase, for example
"%1A".
• Encode the forward slash character, '/', everywhere except in the
object key name. For example, if the object key name is photos/
Jan/sample.jpg, the forward slash in the key name is not
encoded.
Important
The standard UriEncode functions provided by your
development platform may not work because of
differences in implementation and related ambiguity
in the underlying RFCs. We recommend that you write
your own custom UriEncode function to ensure that your
encoding will work.
The following is an example UriEncode() function in Java.
public static String UriEncode(CharSequence input, boolean

encodeSlash) {
StringBuilder result = new StringBuilder();
for (int i = 0; i < input.length(); i++) {
char ch = input.charAt(i);
if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a'
&& ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '_' ||
ch == '-' || ch == '~' || ch == '.') {
result.append(ch);
} else if (ch == '/') {
result.append(encodeSlash ? "%2F" : ch);
} else {
result.append(toHexUTF8(ch));
}
}
return result.toString();
}
Task 1: Create a Canonical Request

This section provides an overview of creating a canonical request.
The following is the canonical request format that Amazon S3 uses to calculate a signature. For
signatures to match, you must create a canonical request in this format:
<HTTPMethod>\n
<CanonicalURI>\n
<CanonicalQueryString>\n
<CanonicalHeaders>\n
<SignedHeaders>\n
<HashedPayload>

20
Where:
• HTTPMethod is one of the HTTP methods, for example GET, PUT, HEAD, and DELETE.
• CanonicalURI is the URI-encoded version of the absolute path component of the URI—everything
starting with the "/" that follows the domain name and up to the end of the string or to the question
mark character ('?') if you have query string parameters. The URI in the following example, /
examplebucket/myphoto.jpg, is the absolute path and you don't encode the "/" in the absolute
path:
http://s3.amazonaws.com/examplebucket/myphoto.jpg
Note
You do not normalize URI paths for requests to Amazon S3. For example, you may have a
bucket with an object named "my-object//example//photo.user". Normalizing the path
changes the object name in the request to "my-object/example/photo.user". This is an
incorrect path for that object.
• CanonicalQueryString specifies the URI-encoded query string parameters. You URI-encode name
and values individually. You must also sort the parameters in the canonical query string alphabetically
by key name. The sorting occurs after encoding. The query string in the following URI example is
prefix=somePrefix&marker=someMarker&max-keys=20:
http://s3.amazonaws.com/examplebucket?prefix=somePrefix&marker=someMarker&max-keys=20
The canonical query string is as follows (line breaks are added to this example for readability):
UriEncode("marker")+"="+UriEncode("someMarker")+"&"+
UriEncode("max-keys")+"="+UriEncode("20") + "&" +
UriEncode("prefix")+"="+UriEncode("somePrefix")
When a request targets a subresource, the corresponding query parameter value will be an empty
string (""). For example, the following URI identifies the ACL subresource on the examplebucket
bucket:
http://s3.amazonaws.com/examplebucket?acl
The CanonicalQueryString in this case is as follows:
UriEncode("acl") + "=" + ""
If the URI does not include a '?', there is no query string in the request, and you set the canonical query
string to an empty string (""). You will still need to include the "\n".
• CanonicalHeaders is a list of request headers with their values. Individual header name and value
pairs are separated by the newline character ("\n"). Header names must be in lowercase. You must sort
the header names alphabetically to construct the string, as shown in the following example:
Lowercase(<HeaderName1>)+":"+Trim(<value>)+"\n"
Lowercase(<HeaderName2>)+":"+Trim(<value>)+"\n"
...
Lowercase(<HeaderNameN>)+":"+Trim(<value>)+"\n"
The Lowercase() and Trim() functions used in this example are described in the preceding section.
The CanonicalHeaders list must include the following:

21
• HTTP host header.

• If the Content-Type header is present in the request, you must add it to the CanonicalHeaders
list.
• Any x-amz-* headers that you plan to include in your request must also be added. For example, if
you are using temporary security credentials, you need to include x-amz-security-token in your
request. You must add this header in the list of CanonicalHeaders.
Note
The x-amz-content-sha256 header is required for all AWS Signature Version 4 requests. It
provides a hash of the request payload. If there is no payload, you must provide the hash of
an empty string.
The following is an example CanonicalHeaders string. The header names are in lowercase and
sorted.
host:s3.amazonaws.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b785
2b855
x-amz-date:20130708T220855Z
Note
For the purpose of calculating an authorization signature, only the host and any x-amz-
* headers are required; however, in order to prevent data tampering, you should consider
including all the headers in the signature calculation.
• SignedHeaders is an alphabetically sorted, semicolon-separated list of lowercase request
header names. The request headers in the list are the same headers that you included in the
CanonicalHeaders string. For example, for the previous example, the value of SignedHeaders
would be as follows:
host;x-amz-content-sha256;x-amz-date
• HashedPayload is the hexadecimal value of the SHA256 hash of the request payload.
Hex(SHA256Hash(<payload>)
If there is no payload in the request, you compute a hash of the empty string as follows:
Hex(SHA256Hash(""))
The hash returns the following value:
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
For example, when you upload an object by using a PUT request, you provide object data in the body.
When you retrieve an object by using a GET request, you compute the empty string hash.
Task 2: Create a String to Sign

This section provides an overview of creating a string to sign. For step-by-step instructions, see Task 2:
Create a String to Sign in the AWS General Reference.
The string to sign is a concatenation of the following strings:
"AWS4-HMAC-SHA256" + "\n" +

22
timeStampISO8601Format + "\n" +
<Scope> + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))
The constant string AWS4-HMAC-SHA256 specifies the hash algorithm that you are using,
HMAC-SHA256. The timeStamp is the current UTC time in ISO 8601 format (for example,
20130524T000000Z).
Scope binds the resulting signature to a specific date, an AWS region, and a service. Thus, your resulting
signature will work only in the specific region and for a specific service. The signature is valid for seven
days after the specified date.
date.Format(<YYYYMMDD>) + "/" + <region> + "/" + <service> + "/aws4_request"
For Amazon S3, the service string is s3. For a list of region strings, see Regions and Endpoints in the
AWS General Reference. The region column in this table provides the list of valid region strings.
The following scope restricts the resulting signature to the us-east-1 region and Amazon S3.
20130606/us-east-1/s3/aws4_request
Note
Scope must use the same date that you use to compute the signing key, as discussed in the
following section.
Task 3: Calculate Signature

In AWS Signature Version 4, instead of using your AWS access keys to sign a request, you first create a
signing key that is scoped to a specific region and service. For more information about signing keys, see
Introduction to Signing Requests (p. 15).
DateKey = HMAC-SHA256("AWS4"+"<SecretAccessKey>", "<YYYYMMDD>")

DateRegionKey = HMAC-SHA256(<DateKey>, "<aws-region>")
DateRegionServiceKey = HMAC-SHA256(<DateRegionKey>, "<aws-service>")
SigningKey = HMAC-SHA256(<DateRegionServiceKey>, "aws4_request")
Note
This signing key is valid for seven days from the date specified in the DateKey hash.
For a list of region strings, see Regions and Endpoints in the AWS General Reference.
Using a signing key enables you to keep your AWS credentials in one safe place. For example, if you have
multiple servers that communicate with Amazon S3, you share the signing key with those servers; you
don’t have to keep a copy of your secret access key on each server. Signing key is valid for up to seven
days. So each time you calculate signing key you will need to share the signing key with your servers. For
more information, see Authenticating Requests (AWS Signature Version 4) (p. 14).
The final signature is the HMAC-SHA256 hash of the string to sign, using the signing key as the key.
HMAC-SHA256(SigningKey, StringToSign)
For step-by-step instructions on creating a signature, see Task 3: Create a Signature in the AWS General
Reference.
Examples: Signature Calculations

You can use the examples in this section as a reference to check signature calculations in your code. For
additional references, see Signature Version 4 Test Suite of the AWS General Reference. The calculations
shown in the examples use the following data:

23
• Example access keys.
Parameter Value
AWSAccessKeyId AKIAIOSFODNN7EXAMPLE
AWSSecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
• Request timestamp of 20130524T000000Z (Fri, 24 May 2013 00:00:00 GMT).

• Bucket name examplebucket.
• The bucket is assumed to be in the US East (N. Virginia) region. The credential Scope and the Signing
Key calculations use us-east-1 as the region specifier. For information about other regions, see
Regions and Endpoints in the AWS General Reference.
• You can use either path-style or virtual hosted–style requests. The following examples show how to
sign a virtual hosted–style request, for example:
https://examplebucket.s3.amazonaws.com/photos/photo1.jpg
For more information, see Virtual Hosting of Buckets in the Amazon Simple Storage Service Developer
Guide.
Example: GET Object
The following example gets the first 10 bytes of an object (test.txt) from examplebucket. For more
information about the API action, see GET Object (p. 370).
GET /test.txt HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date:20130524T000000Z
Authorization: SignatureToBeCalculated
Range: bytes=0-9
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20130524T000000Z
Because this GET request does not provide any body content, the x-amz-content-sha256 value is the
hash of the empty request body. The following steps show signature calculations and construction of the
Authorization header.
1. StringToSign
a. CanonicalRequest
GET
/test.txt
host:examplebucket.s3.amazonaws.com
range:bytes=0-9
x-amz-content-
sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20130524T000000Z
host;range;x-amz-content-sha256;x-amz-date
In the canonical request string, the last line is the hash of the empty request body. The third line
is empty because there are no query parameters in the request.

24
b. StringToSign
AWS4-HMAC-SHA256
20130524T000000Z
7344ae5b7ee6c3e7e6b0fe0640412a37625d1fbfff95c48bbb2dc43964946972
2. SigningKey
signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")
3. Signature
f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41
4. Authorization header
The resulting Authorization header is as follows:
AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/
s3/aws4_request,SignedHeaders=host;range;x-amz-content-sha256;x-amz-
date,Signature=f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41
Example: PUT Object
This example PUT request creates an object (test$file.text) in examplebucket . The example
assumes the following:
• You are requesting REDUCED_REDUNDANCY as the storage class by adding the x-amz-storage-
class request header. For information about storage classes, see Storage Classes in the Amazon
Simple Storage Service Developer Guide.
• The content of the uploaded file is a string, "Welcome to Amazon S3." The value of x-amz-
content-sha256 in the request is based on this string.
For information about the API action, see PUT Object (p. 434).
PUT test$file.text HTTP/1.1

Date: Fri, 24 May 2013 00:00:00 GMT
x-amz-date: 20130524T000000Z
x-amz-storage-class: REDUCED_REDUNDANCY
x-amz-content-sha256: 44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072
<Payload>
The following steps show signature calculations.
1. StringToSign
a. CanonicalRequest
PUT
/test%24file.text
date:Fri, 24 May 2013 00:00:00 GMT

25
x-amz-content-
sha256:44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072
x-amz-date:20130524T000000Z
x-amz-storage-class:REDUCED_REDUNDANCY
date;host;x-amz-content-sha256;x-amz-date;x-amz-storage-class
44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072
In the canonical request, the third line is empty because there are no query parameters in the
request. The last line is the hash of the body, which should be same as the x-amz-content-
sha256 header value.
b. StringToSign
AWS4-HMAC-SHA256
20130524T000000Z
9e0e90d9c76de8fa5b200d8c849cd5b8dc7a3be3951ddb7f6a76b4158342019d
2. SigningKey

3. Signature
98ad721746da40c64f1a55b78f14c238d841ea1380cd77a1b5971af0ece108bd
AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/
aws4_request,SignedHeaders=date;host;x-amz-content-sha256;x-amz-date;x-amz-storage-
class,Signature=98ad721746da40c64f1a55b78f14c238d841ea1380cd77a1b5971af0ece108bd
Example: GET Bucket Lifecycle

The following GET request retrieves the lifecycle configuration of examplebucket. For information
about the API action, see GET Bucket lifecycle (p. 171).
GET ?lifecycle HTTP/1.1

x-amz-date: 20130524T000000Z
Because the request does not provide any body content, the x-amz-content-sha256 header value is
the hash of the empty request body. The following steps show signature calculations.
1. StringToSign
a. CanonicalRequest
GET
/
lifecycle=

26
x-amz-content-
x-amz-date:20130524T000000Z
In the canonical request, the last line is the hash of the empty request body.
b. StringToSign
AWS4-HMAC-SHA256
20130524T000000Z
9766c798316ff2757b517bc739a67f6213b4ab36dd5da2f94eaebf79c77395ca
2. SigningKey

3. Signature
fea454ca298b7da1c68078a5d1bdbfbbe0d65c699e0f91ac7a200a0136783543
s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-
date,Signature=fea454ca298b7da1c68078a5d1bdbfbbe0d65c699e0f91ac7a200a0136783543
Example: Get Bucket (List Objects)
The following example retrieves a list of objects from examplebucket bucket. For information about
the API action, see GET Bucket (List Objects) Version 1 (p. 137).
GET ?max-keys=2&prefix=J HTTP/1.1

x-amz-date: 20130524T000000Z
Because the request does not provide a body, the value of x-amz-content-sha256 is the hash of the
empty request body. The following steps show signature calculations.
1. StringToSign
a. CanonicalRequest
GET
/
max-keys=2&prefix=J
x-amz-content-
x-amz-date:20130524T000000Z

27
In the canonical string, the last line is the hash of the empty request body.
b. StringToSign
AWS4-HMAC-SHA256
20130524T000000Z
df57d21db20da04d7fa30298dd4488ba3a2b47ca3a489c74750e0f1e7df1b9b7
2. SigningKey

3. Signature
34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7
s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-
date,Signature=34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7

28
Signature Calculation: Transfer Payload in Multiple Chunks
Signature Calculations for the Authorization Header:

Transferring Payload in Multiple Chunks (Chunked
Upload) (AWS Signature Version 4)
As described in the Overview (p. 16), when authenticating requests using the Authorization header,
you have an option of uploading the payload in chunks. You can send data in fixed size or variable size
chunks. This section describes the signature calculation process in chunked upload, how you create the
chunk body, and how the delayed signing works where you first upload the chunk, and send its signature
in the subsequent chunk. The example section (see Example: PUT Object (p. 33)) shows signature
calculations and resulting Authorization headers that you can use as a test suite to verify your code.
Note
When transferring data in a series of chunks, you must use the Content-Length HTTP
header to explicitly specify the total content length (object length in bytes plus metadata
in each chunk). This requires you to pre-compute the total length of the payload, including
the metadata you send in each chunk, before starting your request. The x-amz-decoded-
content-length header contains the size of the object length in bytes.
Each chunk signature calculation includes the signature of the previous chunk. To begin, you create a
seed signature using only the headers. You use the seed signature in the signature calculation of the
first chunk. For each subsequent chunk, you create a chunk signature that includes the signature of the
previous chunk. Thus, the chunk signatures are chained together; that is, the signature of chunk n is a
function F(chunk n, signature(chunk n-1)). The chaining ensures that you send the chunks in the correct
order.
To perform a chunked upload, do the following:
1. Decide the payload chunk size. You need this when you write the code.
Chunk size must be at least 8 KB. We recommend a chunk size of a least 64 KB for better performance.
This chunk size applies to all chunks except the last one. The last chunk you send can be smaller than
8 KB. If your payload is small and can fit into one chunk, then it can be smaller than the 8 KB.
2. Create the seed signature for inclusion in the first chunk. For more information, see Calculating the
Seed Signature (p. 29).
3. Create the first chunk and stream it. For more information, see Defining the Chunk Body (p. 32).
4. For each subsequent chunk, calculate the chunk signature that includes the previous signature in
the string you sign, construct the chunk, and send it. For more information, see Defining the Chunk
Body (p. 32).
5. Send the final additional chunk, which is the same as the other chunks in the construction, but it has
zero data bytes. For more information, see Defining the Chunk Body (p. 32).
Calculating the Seed Signature

The following diagram illustrates the process of calculating the seed signature.

29
rules:

'a'-'z', '0'-'9', '-', '.', '_', and '~'.
as "%20" (and not as "+").
"%1A".

30
encoded.
Important
encoding will work.

encodeSlash) {
if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a'
&& ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '_' ||
ch == '-' || ch == '~' || ch == '.') {
result.append(ch);
} else if (ch == '/') {
} else {
}
}
}
For information about the signing process, see Signature Calculations for the Authorization Header:
Transferring Payload in a Single Chunk (AWS Signature Version 4) (p. 18). The process is the same, except
that the creation of CanonicalRequest differs as follows:
• In addition to the request headers you plan to add, you must include the following headers:
Header Description
x-amz-content- This header is required for all AWS Signature Version 4 requests. Set the
sha256 value to STREAMING-AWS4-HMAC-SHA256-PAYLOAD to indicate that the
signature covers only headers and that there is no payload.

31
Header Description
Content-Encoding Set the value to aws-chunked.
Amazon S3 supports multiple content encodings. For example:
Content-Encoding : aws-chunked,gzip
That is, you can specify your custom content-encoding when using
Signature Version 4 streaming API.
Note
Amazon S3 stores the resulting object without the aws-chunked
encoding. Therefore, when you retrieve the object, it is not aws-
chunked encoded.
x-amz-decoded- Set the value to the length, in bytes, of the data to be chunked, without
content-length counting any metadata. For example, if you are uploading a 4 GB file, set
the value to 4294967296. This is the raw size of the object to be uploaded
(data you want to store in Amazon S3).
Content-Length Set the value to the actual size of the transmitted HTTP body, which
includes the length of your data (value set for x-amz-decoded-content-
length) plus, chunk metadata. Each chunk has metadata, such as the
signature of the previous chunk. Chunk calculations are discussed in the
following section.
You send the first chunk with the seed signature. You must construct the chunk as described in the
following section.
Defining the Chunk Body

All chunks include some metadata. Each chunk must conform to the following structure:
string(IntHexBase(chunk-size)) + ";chunk-signature=" + signature + \r\n + chunk-data + \r\n
Where:
• IntHexBase() is a function that you write to convert an integer chunk-size to hexadecimal. For
example, if chunk-size is 65536, hexadecimal string is "10000".
• chunk-size is the size, in bytes, of the chunk-data, without metadata. For example, if you are
uploading a 65 KB object and using a chunk size of 64 KB, you upload the data in three chunks: the
first would be 64 KB, the second 1 KB, and the final chunk with 0 bytes.
• signature For each chunk, you calculate the signature using the following string to sign. For the first
chunk, you use the seed-signature as the previous signature.

32
The size of the final chunk data that you send is 0, although the chunk body still contains metadata,
including the signature of the previous chunk.
Example: PUT Object

You can use the examples in this section as a reference to check signature calculations in your code.
Before you review the examples, note the following:
• The signature calculations in these examples use the following example security credentials.
Parameter Value
• All examples use the request time stamp 20130524T000000Z (Fri, 24 May 2013 00:00:00 GMT).
• All examples use examplebucket as the bucket name.
• The bucket is assumed to be in the US East (N. Virginia) Region, and the credential Scope and the
Signing Key calculations use us-east-1 as the Region specifier. For more information, see Regions
and Endpoints in the Amazon Web Services General Reference.
• You can use either path style or virtual-hosted style requests. The following examples use virtual-
hosted style requests, for example:
https://examplebucket.s3.amazonaws.com/photos/photo1.jpg
For more information, see Virtual Hosting of Buckets in the Amazon Simple Storage Service Developer
Guide.
Example: PUT Object

The following example sends a PUT request to upload an object. The signature calculations assume the
following:
• You are uploading a 65 KB text file, and the file content is a one-character string made up of the letter
'a'.
• The chunk size is 64 KB. As a result, the payload is uploaded in three chunks, 64 KB, 1 KB, and the final
chunk with 0 bytes of chunk data.
• The resulting object has the key name chunkObject.txt.

33
• You are requesting REDUCED_REDUNDANCY as the storage class by adding the x-amz-storage-
class request header.
For information about the API action, see PUT Object (p. 434). The general request syntax is as follows:
PUT /examplebucket/chunkObject.txt HTTP/1.1

Host: s3.amazonaws.com
x-amz-date: 20130524T000000Z
x-amz-content-sha256: STREAMING-AWS4-HMAC-SHA256-PAYLOAD
Content-Encoding: aws-chunked
x-amz-decoded-content-length: 66560
Content-Length: 66824
<Payload>
The following steps show signature calculations.
1. Seed signature — Create String to Sign
a. CanonicalRequest
PUT
/examplebucket/chunkObject.txt
content-encoding:aws-chunked
content-length:66824
host:s3.amazonaws.com
x-amz-content-sha256:STREAMING-AWS4-HMAC-SHA256-PAYLOAD
x-amz-date:20130524T000000Z
x-amz-decoded-content-length:66560
x-amz-storage-class:REDUCED_REDUNDANCY
content-encoding;content-length;host;x-amz-content-sha256;x-amz-date;x-amz-decoded-
content-length;x-amz-storage-class
STREAMING-AWS4-HMAC-SHA256-PAYLOAD
In the canonical request, the third line is empty because there are no query parameters in the
request. The last line is the constant string provided as the value of the hashed Payload, which
should be same as the value of x-amz-content-sha256 header.
b. StringToSign
AWS4-HMAC-SHA256
20130524T000000Z
cee3fed04b70f867d036f722359b0b1f2f0e5dc0efadbc082b76c4c60e316455
Note
For information about each of line in the string to sign, see the diagram that explains
seed signature calculation.
2. SigningKey


34
3. Seed Signature
4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9
AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/
aws4_request,SignedHeaders=content-encoding;content-length;host;x-amz-
content-sha256;x-amz-date;x-amz-decoded-content-length;x-amz-storage-
class,Signature=4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9
5. Chunk 1: (65536 bytes, with value 97 for letter 'a')
a. Chunk string to sign:
AWS4-HMAC-SHA256-PAYLOAD
20130524T000000Z
4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9
bf718b6f653bebc184e1479f1935b8da974d701b893afcf49e701f3e2f9f9c5a
Note
For information about each line in the string to sign, see the preceding diagram that
shows various components of the string to sign (for example, the last three lines are,
previous-signature, hash(""), and hash(current-chunk-data)).
b. Chunk signature:
ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648
c. Chunk data sent:
10000;chunk-
signature=ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648
<65536-bytes>
6. Chunk 2: (1024 bytes, with value 97 for letter 'a')
20130524T000000Z
ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648
2edc986847e209b4016e141a6dc8716d3207350f416969382d431539bf292e4a
b. Chunk signature:
0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497
c. Chunk data sent:
400;chunk-
signature=0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497
<1024 bytes>
35
Using Query Parameters
7. Chunk 3: (0 byte data)
20130524T000000Z
0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497
b. Chunk signature:
b6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9
c. Chunk data sent:
0;chunk-signature=b6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9
Authenticating Requests: Using Query Parameters

(AWS Signature Version 4)
As described in the authentication overview (see Authentication Methods (p. 15)), you can provide
authentication information using query string parameters. Using query parameters to authenticate
requests is useful when you want to express a request entirely in a URL. This method is also referred as
presigning a URL.
A use case scenario for presigned URLs is that you can grant temporary access to your Amazon S3
resources. For example, you can embed a presigned URL on your website or alternatively use it in
command line client (such as Curl) to download objects.
The following is an example presigned URL.
https://s3.amazonaws.com/examplebucket/test.txt
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=<your-access-key-id>/20130721/us-east-1/s3/aws4_request
&X-Amz-Date=20130721T201207Z
&X-Amz-Expires=86400
&X-Amz-SignedHeaders=host
&X-Amz-Signature=<signature-value>
In the example URL, note the following:
• The line feeds are added for readability.

• The X-Amz-Credential value in the URL shows the "/" character only for readability. In practice, it
should be encoded as %2F. For example:
&X-Amz-Credential=<your-access-key-id>%2F20130721%2Fus-east-1%2Fs3%2Faws4_request
The following table describes the query parameters in the URL that provide authentication information.

36
Using Query Parameters
Query String Parameter Name Example Value
X-Amz-Algorithm Identifies the version of AWS Signature and the algorithm that you
used to calculate the signature.
For AWS Signature Version 4, you set this parameter value to

AWS4-HMAC-SHA256. This string identifies AWS Signature Version
4 (AWS4) and the HMAC-SHA256 algorithm (HMAC-SHA256).
X-Amz-Credential In addition to your access key ID, this parameter also provides
scope (AWS region and service) for which the signature is valid.
This value must match the scope you use in signature calculations,
discussed in the following section. The general form for this
parameter value is as follows:
<your-access-key-id>/<date>/<AWS-region>/<AWS-service>/
aws4_request
For example:
AKIAIOSFODNN7EXAMPLE/20130721/us-east-1/s3/aws4_request
For Amazon S3, the AWS-service string is s3. For a list of S3 AWS-
region strings, see Regions and Endpoints in the AWS General
Reference.
X-Amz-Date The date and time format must follow the ISO 8601 standard, and
must be formatted with the "yyyyMMddTHHmmssZ" format. For
example if the date and time was "08/01/2016 15:32:41.982-700"
then it must first be converted to UTC (Coordinated Universal Time)
and then submitted as "20160801T083241Z".
X-Amz-Expires Provides the time period, in seconds, for which the generated
presigned URL is valid. For example, 86400 (24 hours). This value is
an integer. The minimum value you can set is 1, and the maximum
is 604800 (seven days).
A presigned URL can be valid for a maximum of seven days because

the signing key you use in signature calculation is valid for up to
seven days.
X-Amz-SignedHeaders Lists the headers that you used to calculate the signature. The
following headers are required in the signature calculations:
• The HTTP host header.

• Any x-amz-* headers that you plan to add to the request.
Note
For added security, you should sign all the request headers
that you plan to include in your request.
X-Amz-Signature Provides the signature to authenticate your request. This

signature must match the signature Amazon S3 calculates;
otherwise, Amazon S3 denies the request. For example,
733255ef022bec3f2a8701cd61d4b371f3f28c9f193a1f02279211d48d5193

37
Query String Parameter Name Example Value

Signature calculations are described in the following section.
The following diagram illustrates the signature calculation process.
rules:

'a'-'z', '0'-'9', '-', '.', '_', and '~'.
as "%20" (and not as "+").

38
"%1A".
encoded.
Important
encoding will work.

encodeSlash) {
if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a'
&& ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '_' ||
ch == '-' || ch == '~' || ch == '.') {
result.append(ch);
} else if (ch == '/') {
} else {
}
}
}
For more information about the signing process (details of creating a canonical request, string to sign,
and signature calculations), see Signature Calculations for the Authorization Header: Transferring
Payload in a Single Chunk (AWS Signature Version 4) (p. 18). The process is generally the same except
that the creation of CanonicalRequest in a presigned URL differs as follows:
• You don't include a payload hash in the Canonical Request, because when you create a presigned URL,
you don't know the payload content because the URL is used to upload an arbitrary payload. Instead,
you use a constant string UNSIGNED-PAYLOAD.
• The Canonical Query String must include all the query parameters from the preceding table except
for X-Amz-Signature.
• Canonical Headers must include the HTTP host header. If you plan to include any of the x-amz-*
headers, these headers must also be added for signature calculation. You can optionally add all other
headers that you plan to include in your request. For added security, you should sign as many headers
as possible.

39
An Example
An Example
Suppose you have an object test.txt in your examplebucket bucket. You want to share this object
with others for a period of 24 hours (86400 seconds) by creating a presigned URL.
https://s3.amazonaws.com/examplebucket/test.txt
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20130524%2Fus-east-1%2Fs3%2Faws4_request
&X-Amz-Date=20130524T000000Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host
&X-Amz-Signature=<signature-value>
The following steps illustrate first the signature calculations and then construction of the presigned URL.
The example makes the following additional assumptions:
• Request timestamp is Fri, 24 May 2013 00:00:00 GMT.

• The bucket is in the US East (N. Virginia) region, and the credential Scope and the Signing Key
calculations use us-east-1 as the region specifier. For more information, see Regions and Endpoints
in the AWS General Reference.
You can use this example as a test case to verify the signature that your code calculates; however, you
must use the same bucket name, object key, time stamp, and the following example credentials:
Parameter Value
1. StringToSign
a. CanonicalRequest
GET
/test.txt
X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE
%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20130524T000000Z&X-Amz-
Expires=86400&X-Amz-SignedHeaders=host
host
UNSIGNED-PAYLOAD
b. StringToSign
AWS4-HMAC-SHA256
20130524T000000Z
3bfa292879f6447bbcda7001decf97f4a54dc650c8942174ae0a9121cf58ad04
2. SigningKey


40
Examples: Signature Calculations
3. Signature
aeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404
Now you have all information to construct a presigned URL. The resulting URL for this example is
shown as follows (you can use this to compare your presigned URL):
https://examplebucket.s3.amazonaws.com/test.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-
Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&X-
Amz-Date=20130524T000000Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-
Signature=aeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404
Examples: Signature Calculations in AWS Signature

Version 4
Topics
• Signature Calculation Examples Using Java (AWS Signature Version 4) (p. 41)
• Examples of Signature Calculations Using C# (AWS Signature Version 4) (p. 42)
For authenticated requests, unless you are using the AWS SDKs, you have to write code to calculate
signatures that provide authentication information in your requests. Signature calculation in AWS
Signature Version 4 (see Authenticating Requests (AWS Signature Version 4) (p. 14)) can be a complex
undertaking, and we recommend that you use the AWS SDKs whenever possible.
This section provides examples of signature calculations written in Java and C#. The code samples send
the following requests and use the HTTP Authorization header to provide authentication information:
• PUT object – Separate examples illustrate both uploading the full payload at once and uploading
the payload in chunks. For information about using the Authorization header for authentication, see
Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) (p. 16).
• GET object – This example generates a presigned URL to get an object. Query parameters provide the
signature and other authentication information. Users can paste a presigned URL in their browser to
retrieve the object, or you can use the URL to create a clickable link. For information about using query
parameters for authentication, see Authenticating Requests: Using Query Parameters (AWS Signature
Version 4) (p. 36).
The rest of this section describes the examples in Java and C#. The topics include instructions for
downloading the samples and for executing them.
Signature Calculation Examples Using Java (AWS

The Java sample that shows signature calculation can be downloaded at https://s3.amazonaws.com/
aws-java-sdk/samples/AWSS3SigV4JavaSamples.jar. In RunAllSamples.java, the main() function
executes sample requests to create an object, retrieve an object, and create a presigned URL for the
object. The sample creates an object from the text string provided in the code:
PutS3ObjectSample.putS3Object(bucketName, regionName, awsAccessKey, awsSecretKey);

GetS3ObjectSample.getS3Object(bucketName, regionName, awsAccessKey, awsSecretKey);
PresignedUrlSample.getPresignedUrlToS3Object(bucketName, regionName, awsAccessKey,
awsSecretKey);

41
Signature Calculation Examples Using C#
PutS3ObjectChunkedSample.putS3ObjectChunked(bucketName, regionName, awsAccessKey,

awsSecretKey);
To test the examples on a Linux-based computer
The following instructions are for the Linux operating system.
1. At a command prompt, change the directory to the directory that contains

AWSS3SigV4JavaSamples.jar.
2. Extract the source files from AWSS3SigV4JavaSamples.jar.
jar xvf AWSS3SigV4JavaSamples.jar
3. In a text editor, open the file ./com/amazonaws/services/s3/samples/RunAllSamples.java.

Update code with the following information:
• The name of a bucket where the new object can be created.
Note
The examples use a virtual-hosted style request to access the bucket. To avoid potential
errors, ensure that your bucket name conforms to the bucket naming rules as explained in
Bucket Restrictions and Limitations in the Amazon Simple Storage Service Developer Guide.
• AWS region where the bucket resides.
If bucket is in the US East (N. Virginia) region, use us-east-1 to specify the region. For a list of other
AWS regions, go to Amazon Simple Storage Service (S3) in the AWS General Reference.
4. Compile the source code and store the compiled classes into the bin/ directory.
javac -d bin -source 6 -verbose com
5. Change the directory to bin/, and then execute RunAllSamples.
java com.amazonaws.services.s3.sample.RunAllSamples
The code runs all the methods in main(). For each request, the output will show the canonical
request, the string to sign, and the signature.
Examples of Signature Calculations Using C# (AWS

The C# sample that shows signature calculation can be downloaded at https://docs.aws.amazon.com/
AmazonS3/latest/API/samples/AmazonS3SigV4_Samples_CSharp.zip. In Program.cs, the main()
function executes sample requests to create an object, retrieve an object, and create a presigned URL for
the object. The code for signature calculation is in the \Signers folder.
PutS3ObjectSample.Run(awsRegion, bucketName, "MySampleFile.txt");
Console.WriteLine("\n\n************************************************");
PutS3ObjectChunkedSample.Run(awsRegion, bucketName, "MySampleFileChunked.txt");
GetS3ObjectSample.Run(awsRegion, bucketName, "MySampleFile.txt");
PresignedUrlSample.Run(awsRegion bucketName, "MySampleFile.txt");

42
Authenticating HTTP POST Requests
To test the examples with Microsoft Visual Studio 2010 or later
1. Extract the .zip file.

2. Start Visual Studio, and then open the .sln file.
3. Update the App.config file with valid security credentials.
4. Update the code as follows:
• In Program.cs, provide the bucket name and the AWS region where the bucket resides. The sample
creates an object in this bucket.
5. Execute the code.
6. To verify that the object was created, copy the presigned URL that the program creates, and then
paste it in a browser window.
Authenticating Requests: Browser-Based Uploads

Using POST (AWS Signature Version 4)
Amazon S3 supports HTTP POST requests so that users can upload content directly to Amazon S3. Using
HTTP POST to upload content simplifies uploads and reduces upload latency where users upload data
to store in Amazon S3. This section describes how you authenticate HTTP POST requests. For more
information about HTTP POST requests, how to create a form, create a POST policy, and an example, see
Authenticating Requests in Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 49).
To authenticate an HTTP POST request you do the following:
1. The form must include the following fields to provide signature and relevant information that Amazon
S3 can use to re-calculate the signature upon receiving the request:
Element Name Description
policy The Base64-encoded security policy that describes what

is permitted in the request. For signature calculation this
policy is the string you sign. Amazon S3 must get this
policy so it can re-calculate the signature.
x-amz-algorithm The signing algorithm used. For AWS Signature Version 4,

the value is AWS4-HMAC-SHA256.
x-amz-credential In addition to your access key ID, this provides scope

information you used in calculating the signing key for
signature calculation.
It is a string of the following form:
<your-access-key-id>/<date>/<aws-
region>/<aws-service>/aws4_request
For example:
AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/
aws4_request. .
For Amazon S3, the aws-service string is s3. For a list

of Amazon S3 aws-region strings, see Regions and
Endpoints in the AWS General Reference.

43
x-amz-date It is the date value in ISO8601 format. For example,

20130728T000000Z.
It is the same date you used in creating the signing key.

This must also be the same value you provide in the policy
(x-amz-date) that you signed.
x-amz-signature (AWS Signature Version 4) The HMAC-SHA256 hash of the

security policy.
2. The POST policy must include the following elements:
x-amz-algorithm The signing algorithm that you used to calculation the

signature. For AWS Signature Version 4, the value is
AWS4-HMAC-SHA256.
x-amz-credential In addition to your access key ID, this provides scope

information you used in calculating the signing key for
For example,
aws4_request. .
x-amz-date The date value specified in the ISO8601 formatted string.

For example, "20130728T000000Z". The date must
be same that you used in creating the signing key for
3. For signature calculation the POST policy is the string to sign.
The following diagram illustrates the signature calculation process.

44
Amazon S3 Signature Version 4
Authentication Specific Policy Keys
To Calculate a signature
1. Create a policy using UTF-8 encoding.

2. Convert the UTF-8-encoded policy to Base64. The result is the string to sign.
3. Create the signature as an HMAC-SHA256 hash of the string to sign. You will provide the signing key
as key to the hash function.
4. Encode the signature by using hex encoding.
For more information about creating HTML forms, security policies, and an example, see the following
subtopics:
• Creating an HTML Form (Using AWS Signature Version 4) (p. 51)

• Creating a POST Policy (p. 56)
• Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 61)
• Using POST with Adobe Flash to Upload Objects (p. 63)
Amazon S3 Signature Version 4 Authentication

Specific Policy Keys
The following table shows the policy keys related Amazon S3 Signature Version 4 authentication
that can be in Amazon S3 policies. In a bucket policy, you can add these conditions to enforce specific
behavior when requests are authenticated by using Signature Version 4. For example policies, see Bucket
Policy Examples Using Signature Version 4 Related Condition Keys (p. 47).
Applicable Keys for s3:* Actions or any of the Amazon S3 Actions
Applicable Keys Description
s3:signatureversion Identifies the version of AWS Signature that you

want to support for authenticated requests. For
authenticated requests, Amazon S3 supports both
Signature Version 4 and Signature Version 2. You
can add this condition in your bucket policy to
require a specific signature version.
Valid values:

45
Amazon S3 Signature Version 4
Authentication Specific Policy Keys

"AWS" identifies Signature Version 2
"AWS4-HMAC-SHA256" identifies Signature

Version 4
s3:authType Amazon S3 supports various methods of

authentication (see Authenticating Requests (AWS
Signature Version 4) (p. 14). You can optionally use
this condition key to restrict incoming requests to
use a specific authentication method. For example,
you can allow only the HTTP Authorization
header to be used in request authentication.
Valid values:
REST-HEADER
REST-QUERY-STRING
POST
s3:signatureAge The length of time, in milliseconds, that a

signature is valid in an authenticated request.
This condition works only for presigned URLs (the

most restrictive condition wins).
In Signature Version 4, the signing key is valid

for up to seven days (see Introduction to Signing
Requests (p. 15). Therefore, the signatures are
also valid for up to seven days. You can use this
condition to further limit the signature age.
Example value: 100

46
Bucket Policy Examples Using Signature
Version 4 Related Condition Keys
s3:x-amz-content-sha256 You can use this condition key to disallow

unsigned content in your bucket.
When you use Signature Version 4, for requests

that use the Authorization header, you add the
x-amz-content-sha256 header in the signature
calculation and then set its value to the hash
payload.
You can use this condition key in your bucket

policy to deny any uploads where payloads are not
signed. For example:
• Deny uploads that use presigned URLs. For

more information, see Authenticating Requests:
Using Query Parameters (AWS Signature Version
4) (p. 36).
• Deny uploads that use Authorization header
to authenticate requests but don't sign the
payload. For more information, see Signature
Calculations for the Authorization Header:
Transferring Payload in a Single Chunk (AWS
Valid value: UNSIGNED-PAYLOAD
Bucket Policy Examples Using Signature Version 4

Related Condition Keys
Deny any Amazon S3 action on the examplebucket to anyone if request is authenticated using
Signature Version 4.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Test",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Resource": "arn:aws:s3:::examplebucket/*",
"Condition": {
"StringEquals": {
"s3:signatureversion": "AWS4-HMAC-SHA256"
}
}
}
]
}
The following bucket policy denies any Amazon S3 presigned URL request on objects in examplebucket
if the signature is more than ten minutes old.

47
Bucket Policy Examples Using Signature
Version 4 Related Condition Keys
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Deny a presigned URL request if the signature is more than 10 min old",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Resource": "arn:aws:s3:::examplebucket3/*",
"Condition": {
"NumericGreaterThan": {
"s3:signatureAge": 600000
}
}
}
]
}
The following bucket policy allows only requests that use the Authorization header for request
authentication. Any POST or presigned URL requests will be denied.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Allow only requests that use Authorization header for request
authentication. Deny POST or presigned URL requests.",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Condition": {
"StringNotEquals": {
"s3:authType": "REST-HEADER"
}
}
}
]
}
The following bucket policy denies any uploads that use presigned URLs.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Allow only requests that use Authorization header for request
authentication. Deny POST or presigned URL requests.",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Condition": {
"StringNotEquals": {
"s3:x-amz-content-sha256": "UNSIGNED-PAYLOAD"
}
}
}
]
}

48
Browser-Based Uploads Using HTTP POST
Authenticating Requests in Browser-

Based Uploads Using POST (AWS
This section discusses how to upload files directly to Amazon S3 through a browser using HTTP POST
requests. It also contains information about how to use the AWS Amplify JavaScript library for browser-
based file uploads to Amazon S3.
Topics
• Browser-Based Uploads Using HTTP POST (p. 49)
• Calculating a Signature (p. 50)
• Browser-Based Uploads to Amazon S3 Using the AWS Amplify Library (p. 63)
Browser-Based Uploads Using HTTP POST

Amazon S3 supports HTTP POST requests so that users can upload content directly to Amazon S3.
By using POST, end users can authenticate requests without having to pass data through a secure
intermediary node that protects your credentials. Thus, HTTP POST has the potential to reduce latency.
The following figure shows an Amazon S3 upload using a POST request.

49
Uploading Using POST
1 The user accesses your page from a web browser.
2 Your webpage contains an HTML form that contains all the information necessary for the
user to upload content to Amazon S3.
3 The user uploads content to Amazon S3 through the web browser.
The process for sending browser-based POST requests is as follows:
1. Create a security policy specifying conditions that restrict what you want to allow in the request, such
as the bucket name where objects can be uploaded, and key name prefixes that you want to allow for
the object that is being created.
2. Create a signature that is based on the policy. For authenticated requests, the form must include a
valid signature and the policy.
3. Create an HTML form that your users can access in order to upload objects to your Amazon S3 bucket.
The following section describes how to create a signature to authenticate a request. For information
about creating forms and security policies, see Creating an HTML Form (Using AWS Signature Version
4) (p. 51).
For authenticated requests, the HTML form must include fields for a security policy and a signature.
• A security policy (see Creating a POST Policy (p. 56)) controls what is allowed in the request.

50
Creating HTML Forms
• The security policy is the StringToSign (see Introduction to Signing Requests (p. 15)) in your
To Calculate a signature
1. Create a policy using UTF-8 encoding.

2. Convert the UTF-8-encoded policy bytes to base64. The result is the StringToSign.
3. Create a signing key.
4. Use the signing key to sign the StringToSign using HMAC-SHA256 signing algorithm.
For more information about creating HTML forms, security policies, and an example, see the following:

Creating an HTML Form (Using AWS Signature

Version 4)
Topics
• HTML Form Declaration (p. 52)
• HTML Form Fields (p. 52)
To allow users to upload content to Amazon S3 by using their browsers (HTTP POST requests), you use
HTML forms. HTML forms consist of a form declaration and form fields. The form declaration contains
high-level information about the request. The form fields contain detailed request information.
This section describes how to create HTML forms. For a working example of browser-based upload using
HTTP POST and related signature calculations for request authentication, see Example: Browser-Based
Upload using HTTP POST (Using AWS Signature Version 4) (p. 61).

51
HTML Form Declaration
The form and policy must be UTF-8 encoded. You can apply UTF-8 encoding to the form by specifying
charset=UTF-8 in the content attribute. The following is an example of UTF-8 encoding in the HTML
heading.
<html>
<head>
...
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
...
</head>
<body>
Following is an example of UTF-8 encoding in a request header.
Content-Type: text/html; charset=UTF-8
Note
The form data and boundaries (excluding the contents of the file) cannot exceed 20KB.
HTML Form Declaration

The HTML form declaration has the following three attributes:
• action – The URL that processes the request, which must be set to the URL of the
bucket. For example, if the name of your bucket is examplebucket, the URL is http://
examplebucket.s3.amazonaws.com/.
Note
The key name is specified in a form field.
• method – The method must be POST.
• enctype – The enclosure type (enctype) must be set to multipart/form-data for both file uploads
and text area uploads. For more information about enctype, see RFC 1867.
This is a form declaration for the bucket examplebucket.
<form action="http://examplebucket.s3.amazonaws.com/" method="post"
enctype="multipart/form-data">
HTML Form Fields

The following table describes a list of fields that you can use within a form. Among other fields, there is a
signature field that you can use to authenticate requests. There are fields for you to specify the signature
calculation algorithm (x-amz-algorithm), the credential scope (x-amz-credential) that you used to
generate the signing key, and the date (x-amz-date) used to calculate the signature. Amazon S3 uses
this information to re-create the signature. If the signatures match, Amazon S3 processes the request.
Note
The variable ${filename} is automatically replaced with the name of the file provided by the
user and is recognized by all form fields. If the browser or client provides a full or partial path
to the file, only the text following the last slash (/) or backslash (\) is used (for example, C:
\Program Files\directory1\file.txt is interpreted as file.txt). If no file or file name
is provided, the variable is replaced with an empty string.
If you don't provide elements required for authenticated requests, such as the policy element, the
request is assumed to be anonymous and will succeed only if you have configured the bucket for public
read and write.

52
HTML Form Fields
Element Name Description Required
acl An Amazon S3 access control list (ACL). If an No

invalid ACL is specified, Amazon S3 denies the
request. For more information about ACLs, see
Using Amazon S3 ACLs.
Type: String
Default: private
Valid Values: private | public-read |

public-read-write | aws-exec-read |
authenticated-read | bucket-owner-
read | bucket-owner-full-control
Cache-Control REST-specific headers. For more information, see No

PUT Object (p. 434).
Content-Type
Content-Disposition
Content-Encoding
Expires
key The key name of the uploaded object. Yes
To use the file name provided by the user, use

the ${filename} variable. For example, if you
upload a file photo1.jpg and you specify /
user/user1/${filename} as key name, the
file is stored as /user/user1/photo1.jpg.
For more information, see Object Key and

Metadata in the Amazon Simple Storage Service
Developer Guide.
policy The base64-encoded security policy that Required for

describes what is permitted in the request. For authenticated
authenticated requests, a policy is required. requests
Requests without a security policy are considered

anonymous and will succeed only on a publicly
writable bucket.
success_action_redirect The URL to which the client is redirected upon No

successful upload.
If success_action_redirect is not specified,

or Amazon S3 cannot interpret the URL, Amazon
S3 returns the empty document type that is
specified in the success_action_status field.
If the upload fails, Amazon S3 returns an error

and does not redirect the user to another URL.
success_action_status The status code returned to the No

client upon successful upload if
success_action_redirect is not specified.

53
HTML Form Fields

Valid values are 200, 201, or 204 (default).
If the value is set to 200 or 204, Amazon S3

returns an empty document with the specified
status code.
If the value is set to 201, Amazon S3 returns

an XML document with a 201 status code. For
information about the content of the XML
document, see POST Object (p. 407).
If the value is not set or is invalid, Amazon S3

returns an empty document with a 204 status
code.
Note
Some versions of the Adobe Flash player
do not properly handle HTTP responses
with an empty body. To support uploads
through Adobe Flash, we recommend
setting success_action_status to
201.
x-amz-algorithm The signing algorithm used to authenticate the Required for

request. For AWS Signature Version 4, the value authenticated
is AWS4-HMAC-SHA256. requests
This field is required if a policy document is

included with the request.
x-amz-credential In addition to your access key ID, this field also Required for
provides scope information identifying region authenticated
and service for which the signature is valid. This requests
should be the same scope you used in calculating
the signing key for signature calculation.
For example:
AKIAIOSFODNN7EXAMPLE/20130728/us-
east-1/s3/aws4_request
For Amazon S3, the aws-service string is s3.
For a list of Amazon S3 aws-region strings,
see Regions and Endpoints in the AWS General
Reference. This is required if a policy document is

54
HTML Form Fields
x-amz-date It is the date value in ISO8601 format. For Required for

example, 20130728T000000Z. authenticated
requests
It is the same date you used in creating the
signing key (for example, 20130728). This must
also be the same value you provide in the policy
(x-amz-date) that you signed.
This is required if a policy document is included

with the request.
x-amz-security-token A security token used by Amazon DevPay and No

session credentials
If the request is using Amazon DevPay, it requires

two x-amz-security-token form fields: one
for the product token and one for the user token.
For more information, see Using DevPay in the
Amazon Simple Storage Service Developer Guide.
If the request is using session credentials, it

requires one x-amz-security-token form.
For more information, see Requesting Temporary
Security Credentials in the IAM User Guide.
x-amz-signature (AWS Signature Version 4) The HMAC-SHA256 Required for

hash of the security policy. authenticated
requests
This field is required if a policy document is
x-amz-meta-* Field names starting with this prefix are user- No

defined metadata. Each one is stored and
returned as a set of key-value pairs. Amazon
S3 doesn't validate or interpret user-defined
metadata. For more information, see PUT
Object (p. 434).
x-amz-* See POST Object (POST Object (p. 407) for No

other x-amz-* headers.
file File or text content. Yes
The file or content must be the last field in the

form.
You cannot upload more than one file at a time.
Conditional items are required for authenticated requests and are optional for anonymous requests.
Now that you know how to create forms, next you can create a security policy that you can sign. For
more information, see Creating a POST Policy (p. 56).

55
Creating a POST Policy
Creating a POST Policy

Topics
• Expiration (p. 56)
• Condition Matching (p. 56)
• Conditions (p. 57)
• Character Escaping (p. 59)
The policy required for making authenticated requests using HTTP POST is a UTF-8 and base64-encoded
document written in JavaScript Object Notation (JSON) that specifies conditions that the request must
meet. Depending on how you design your policy document, you can control the access granularity per-
upload, per-user, for all uploads, or according to other designs that meet your needs.
This section describes the POST policy. For example signature calculations using POST policy, see
Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 61).
Note
Although the policy document is optional, we highly recommend that you use one in order to
control what is allowed in the request. If you make the bucket publicly writable, you have no
control at all over which users can write to your bucket.
The following is an example of a POST policy document.
{ "expiration": "2007-12-01T12:00:00.000Z",
"conditions": [
{"acl": "public-read" },
{"bucket": "johnsmith" },
["starts-with", "$key", "user/eric/"],
]
}
The POST policy always contains the expiration and conditions elements. The example policy
uses two condition matching types (exact matching and starts-with matching). The following sections
describe these elements.
Expiration
The expiration element specifies the expiration date and time of the POST policy in ISO8601 GMT
date format. For example, 2013-08-01T12:00:00.000Z specifies that the POST policy is not valid
after midnight GMT on August 1, 2013.
Condition Matching
Following is a table that describes condition matching types that you can use to specify POST policy
conditions (described in the next section). Although you must specify one condition for each form field
that you specify in the form, you can create more complex matching criteria by specifying multiple
conditions for a form field.
Condition Description
Match Type
Exact Matches The form field value must match the value specified. This example indicates that
the ACL must be set to public-read:

56
Conditions
Condition Description
Match Type
{"acl": "public-read" }
This example is an alternate way to indicate that the ACL must be set to public-read:
[ "eq", "$acl", "public-read" ]
Starts With The value must start with the specified value. This example indicates that the object
key must start with user/user1:
["starts-with", "$key", "user/user1/"]
Matching Any To configure the POST policy to allow any content within a form field, use
Content starts-with with an empty value (""). This example allows any value for
success_action_redirect:
["starts-with", "$success_action_redirect", ""]
Specifying For form fields that accept a range, separate the upper and lower limit with a
Ranges comma. This example allows a file size from 1 to 10 MiB:
["content-length-range", 1048579, 10485760]
The specific conditions supported in a POST policy are described in Conditions (p. 57).
Conditions
The conditions in a POST policy is an array of objects, each of which is used to validate the request.
You can use these conditions to restrict what is allowed in the request. For example, the preceding policy
conditions require the following:
• Request must specify the johnsmith bucket name.

• Object key name must have the user/eric prefix.
• Object ACL must be set to public-read.
Each form field that you specify in a form (except x-amz-signature, file, policy, and field names
that have an x-ignore- prefix) must appear in the list of conditions.
Note
All variables within the form are expanded prior to validating the POST policy. Therefore, all
condition matching should be against the expanded form fields. Suppose that you want to
restrict your object key name to a specific prefix (user/user1). In this case, you set the key
form field to user/user1/${filename}. Your POST policy should be [ "starts-with",
"$key", "user/user1/" ] (do not enter [ "starts-with", "$key", "user/user1/
${filename}" ]). For more information, see Condition Matching (p. 56).
Policy document conditions are described in the following table.

57
Conditions
acl Specifies the ACL value that must be used in the form
submission.
This condition supports exact matching and starts-with

condition match type discussed in the following section.
bucket Specifies the acceptable bucket name.
This condition supports exact matching condition match type.
content-length-range The minimum and maximum allowable size for the uploaded
content.
This condition supports content-length-range condition

match type.
Cache-Control REST-specific headers. For more information, see POST

Object (p. 407).
Content-Type
Content-Disposition condition match type.
Content-Encoding
Expires
key The acceptable key name or a prefix of the uploaded object.

condition match type.
success_action_redirect The URL to which the client is redirected upon successful

upload.
redirect
success_action_status The status code returned to the client upon successful upload if
success_action_redirect is not specified.
This condition supports exact matching.
x-amz-algorithm The signing algorithm that must be used during signature

calculation. For AWS Signature Version 4, the value is AWS4-
HMAC-SHA256.
x-amz-credential The credentials that you used to calculate the signature. It

provides access key ID and scope information identifying region
and service for which the signature is valid. This should be the
same scope you used in calculating the signing key for signature
calculation.
<your-access-key-id>/<date>/<aws-region>/<aws-
service>/aws4_request

58
Character Escaping

For example:
aws4_request
For Amazon S3, the aws-service string is s3. For a list of

Amazon S3 aws-region strings, see Regions and Endpoints
in the AWS General Reference. This is required if a POST policy
document is included with the request.
x-amz-date The date value specified in the ISO8601 formatted string. For
example, 20130728T000000Z. The date must be same that you
used in creating the signing key for signature calculation.
This is required if a POST policy document is included with the

request.
x-amz-security-token Amazon DevPay security token.
Each request that uses Amazon DevPay requires two x-amz-

security-token form fields: one for the product token
and one for the user token. As a result, the values must
be separated by commas. For example, if the user token is
eW91dHViZQ== and the product token is b0hnNVNKWVJIQTA=,
you set the POST policy entry to: { "x-amz-security-
token": "eW91dHViZQ==,b0hnNVNKWVJIQTA=" }.
For more information about Amazon DevPay, see Using DevPay

in the Amazon Simple Storage Service Developer Guide.
x-amz-meta-* User-specified metadata.

x-amz-* See POST Object (POST Object (p. 407) for other x-amz-*
headers.
Note
If your toolkit adds more form fields (for example, Flash adds filename), you must add them to
the POST policy document. If you can control this functionality, prefix x-ignore- to the field
so Amazon S3 ignores the feature and it won't affect future versions of this feature.
Character Escaping
Characters that must be escaped within a POST policy document are described in the following table.

59
Character Escaping
Escape Description
Sequence
\\ Backslash
\$ Dollar symbol
\b Backspace
\f Form feed
\n New line
\r Carriage return
\t Horizontal tab
\v Vertical tab
\uxxxx All Unicode characters
Now that you are acquainted with forms and policies, and understand how signing works, you can try
a POST upload example. You need to write the code to calculate the signature. The example provides
a sample form, and a POST policy that you can use to test your signature calculations. For more
information, see Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version
4) (p. 61).

60
POST Upload Example
Example: Browser-Based Upload using HTTP POST

(Using AWS Signature Version 4)
This section shows an example of using an HTTP POST request to upload content directly to Amazon S3.
Uploading a File to Amazon S3 Using HTTP POST

This example provides a sample POST policy and a form that you can use to upload a file. The topic uses
the example policy and fictitious credentials to show you the workflow and resulting signature and policy
hash. You can use this data as test suite to verify your signature calculation code.
The example uses the following example credentials the signature calculations. You can use these
credentials to verify your signature calculation code. However, you must then replace these with your
own credentials when sending requests to AWS.
Parameter Value
Sample Policy and Form

The following POST policy supports uploads to Amazon S3 with specific conditions.
{ "expiration": "2015-12-30T12:00:00.000Z",
"conditions": [
{"bucket": "sigv4examplebucket"},
["starts-with", "$key", "user/user1/"],
{"acl": "public-read"},
{"success_action_redirect": "http://sigv4examplebucket.s3.amazonaws.com/
successful_upload.html"},
["starts-with", "$Content-Type", "image/"],
{"x-amz-meta-uuid": "14365123651274"},
{"x-amz-server-side-encryption": "AES256"},
["starts-with", "$x-amz-meta-tag", ""],
{"x-amz-credential": "AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request"},
{"x-amz-algorithm": "AWS4-HMAC-SHA256"},
{"x-amz-date": "20151229T000000Z" }
]
}
This POST policy sets the following conditions on the request:
• The upload must occur before noon UTC on December 30, 2015.
• The content can be uploaded only to the sigv4examplebucket. The bucket must be in the region
that you specified in the credential scope (x-amz-credential form parameter), because the
signature you provided is valid only within this scope.
• You can provide any key name that starts with user/user1. For example, user/user1/
MyPhoto.jpg.
• The ACL must be set to public-read.
• If the upload succeeds, the user's browser is redirected to http://
sigv4examplebucket.s3.amazonaws.com/successful_upload.html.

61
Uploading a File to Amazon S3 Using HTTP POST
• The object must be an image file.

• The x-amz-meta-uuid tag must be set to 14365123651274.
• The x-amz-meta-tag can contain any value.
The following is a Base64-encoded version of this POST policy. You use this value as your StringToSign in
eyAiZXhwaXJhdGlvbiI6ICIyMDE1LTEyLTMwVDEyOjAwOjAwLjAwMFoiLA0KICAiY29uZGl0aW9ucyI6IFsNCiAgICB7ImJ1Y2tldCI
When you copy/paste the preceding policy, it should only have newlines (not carriage return and new
line) for your computed hash to match this value.
Using example credentials to create a signature, the signature value is as follows (in signature
calculation, the date is same as the x-amz-date in the policy (20151229):
8afdbf4008c03f22c2cd3cdb72e4afbb1f6a588f3255ac628749a66d7f09699e
The following example form specifies the preceding POST policy and supports a POST request to the
sigv4examplebucket. Copy/paste the content in a text editor and save it as exampleform.html. You
can then upload image files to the specific bucket using the exampleform.html. Your request will succeed
if the signature you provide matches the signature Amazon S3 calculates.
Note
You must update the bucket name, dates, credential, policy, and signature with valid values for
this to successfully upload to S3.
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>
<form action="http://sigv4examplebucket.s3.amazonaws.com/" method="post"

enctype="multipart/form-data">
Key to upload:
<input type="input" name="key" value="user/user1/${filename}" /><br />
<input type="hidden" name="acl" value="public-read" />
<input type="hidden" name="success_action_redirect" value="http://
sigv4examplebucket.s3.amazonaws.com/successful_upload.html" />
Content-Type:
<input type="input" name="Content-Type" value="image/jpeg" /><br />
<input type="hidden" name="x-amz-meta-uuid" value="14365123651274" />
<input type="hidden" name="x-amz-server-side-encryption" value="AES256" />
<input type="text" name="X-Amz-Credential" value="AKIAIOSFODNN7EXAMPLE/20151229/us-
east-1/s3/aws4_request" />
<input type="text" name="X-Amz-Algorithm" value="AWS4-HMAC-SHA256" />
<input type="text" name="X-Amz-Date" value="20151229T000000Z" />
Tags for File:

<input type="input" name="x-amz-meta-tag" value="" /><br />
<input type="hidden" name="Policy" value='<Base64-encoded policy string>' />
<input type="hidden" name="X-Amz-Signature" value="<signature-value>" />
File:
<input type="file" name="file" /> <br />

<input type="submit" name="submit" value="Upload to Amazon S3" />
</form>

62
Using POST with Adobe Flash
</html>
The post parameters are case insensitive. For example, you can specify x-amz-signature or X-Amz-
Signature.
Using POST with Adobe Flash to Upload Objects

This section discusses uploading objects with an HTTP POST request when using Adobe Flash.
Using POST with Adobe Flash

This section describes how to use POST with Adobe Flash.
Adobe Flash Player Security

By default, the Adobe Flash Player security model prohibits making network connections to servers
outside the domain that serves the Adobe Flash (.swf) file.
To override the default, you must upload a publicly readable crossdomain.xml file to the bucket that
will accept POST uploads. Here is a sample crossdomain.xml file:
<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
<allow-access-from domain="*" secure="false" />
</cross-domain-policy>
For more information about the Adobe Flash security model, go to the Adobe web site.
When you add the crossdomain.xml file to your bucket, any Adobe Flash Player can connect to the
crossdomain.xml file within your bucket. However, crossdomain.xml does not grant access to the
Amazon S3 bucket.
Other Adobe Flash Considerations

The FileReference class in the Adobe Flash API adds the Filename form field to the POST request. When
you build an Adobe Flash application that uploads files to Amazon S3 by using the FileReference
class, include the following condition in your policy:
['starts-with', '$Filename', '']
Some versions of the Adobe Flash Player do not properly handle HTTP responses that have an
empty body. To configure POST to return a response that does not have an empty body, set
success_action_status to 201. Then, Amazon S3 will return an XML document with a 201 status
code. For information about using this as an optional element (currently the only allowed value is the
content of the XML document), see POST Object (p. 407). For information about form fields, see HTML
Form Fields (p. 52).
Browser-Based Uploads to Amazon S3 Using the

AWS Amplify Library
This section describes how to upload files to Amazon S3 using the AWS Amplify JavaScript library.

63
Using the AWS Amplify JavaScript
library to Upload Files to Amazon S3
For information about setting up the AWS Amplify library, see AWS Amplify Installation and
Configuration.
Using the AWS Amplify JavaScript library to Upload

Files to Amazon S3
The AWS Amplify library Storage module gives a simple browser-based upload mechanism for
managing user content in public or private Amazon S3 storage.
Example : AWS Amplify Manual Setup
The following example shows the manual setup for using the AWS Amplify Storage module. The default
implementation of the Storage module uses Amazon S3.
import Amplify from 'aws-amplify';

Amplify.configure(
Auth: {
identityPoolId: 'XX-XXXX-X:XXXXXXXX-XXXX-1234-abcd-1234567890ab', //REQUIRED -
Amazon Cognito Identity Pool ID
region: 'XX-XXXX-X', // REQUIRED - Amazon Cognito Region
userPoolId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito User Pool ID
userPoolWebClientId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito Web Client
ID
},
Storage: {
bucket: '', //REQUIRED - Amazon S3 bucket
region: 'XX-XXXX-X', //OPTIONAL - Amazon service region
}
);
Example : Put data into Amazon S3
The following example shows how to put public data into Amazon S3.
Storage.put('test.txt', 'Hello')
.then (result => console.log(result))
.catch(err => console.log(err));
The following example shows how to put private data into Amazon S3.
Storage.put('test.txt', 'Private Content', {

level: 'private',
contentType: 'text/plain'
})
.then (result => console.log(result))
.catch(err => console.log(err));
For more information about using the AWS Amplify Storage module, see AWS Amplify Storage.
More Info
AWS Amplify Quick Start

64
GET Service
Operations on the Service

This section describes operations you can perform on the Amazon S3 service.
Topics
• GET Service (p. 65)
GET Service
Description
This implementation of the GET operation returns a list of all buckets owned by the authenticated
sender of the request.
To authenticate a request, you must use a valid AWS Access Key ID that is registered with Amazon S3.
Anonymous requests cannot list buckets, and you cannot list buckets that you did not create.
Requests
Syntax
GET / HTTP/1.1
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Request Parameters
This implementation of the operation does not use request parameters.
Request Headers
This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 2).
Request Elements
This implementation of the operation does not use request elements.
Responses
Response Elements
Name Description
Bucket Container for bucket information.
Type: Container

65
Responses
Name Description
Children: Name, CreationDate
Ancestor: ListAllMyBucketsResult.Buckets
Buckets Container for one or more buckets.
Type: Container
Children: Bucket
Ancestor: ListAllMyBucketsResult
CreationDate Date the bucket was created.
Type: date ( of the form yyyy-mm-ddThh:mm:ss.timezone, e.g.,

2009-02-03T16:45:09.000Z)
Ancestor: ListAllMyBucketsResult.Buckets.Bucket
DisplayName Bucket owner's display name.

Important
This value is only included in the response in the US East
(N. Virginia), US West (N. California), US West (Oregon), Asia
Pacific (Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo),
EU (Ireland), and South America (São Paulo) regions.
For a list of all the Amazon S3 supported regions and
endpoints, see Regions and Endpoints in the AWS General
Reference.
Type: String
Ancestor: ListAllMyBucketsResult.Owner
ID Bucket owner's canonical user ID.
Type: String
Ancestor: ListAllMyBucketsResult.Owner
ListAllMyBucketsResult Container for response.
Type: Container
Children: Owner, Buckets
Ancestor: None
Name Bucket's name.
Type: String
Ancestor: ListAllMyBucketsResult.Buckets.Bucket
Owner Container for bucket owner information.
Type: Container
Ancestor: ListAllMyBucketsResult

66
Examples
Special Errors
This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 6).
Examples
Sample Request
The GET operation on the Service endpoint (s3.amazonaws.com) returns a list of all of the buckets owned
by the authenticated sender of the request.
GET / HTTP/1.1
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string
Sample Response
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Owner>
<ID>bcaf1ffd86f461ca5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
<Buckets>
<Bucket>
<Name>quotes</Name>
<CreationDate>2006-02-03T16:45:09.000Z</CreationDate>
</Bucket>
<Bucket>
<Name>samples</Name>
</Bucket>
</Buckets>
</ListAllMyBucketsResult>
Related Resources
• GET Bucket (List Objects) Version 1 (p. 137)
• GET Object (p. 370)

67
Block Public Access
Operations on AWS Accounts

This section describes the REST operations related to Amazon S3 that you can perform on Amazon Web
Services accounts.
Topics
• Block Public Access (p. 68)
• Batch Operations (p. 75)
Block Public Access

This section describes how to use Amazon S3 block public access.
Topics
• DELETE PublicAccessBlock (p. 68)
• GET PublicAccessBlock (p. 69)
• PUT PublicAccessBlock (p. 72)
DELETE PublicAccessBlock
Description
This operation removes the PublicAccessBlock configuration for an Amazon Web Services account.
In order to use this operation, you must have the s3:PutAccountPublicAccessBlock permission. For
more information about Amazon S3 permissions, see Specifying Permissions in a Policy in the Amazon
Requests
Syntax
DELETE /v20180820/configuration/publicAccessBlock HTTP/1.1

Host: <account-id>.s3-control.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version
4))
Note
For information about locating your AWS account ID, see Finding your AWS Account ID in the
Amazon Web Services General Reference.
Request Parameters
This operation does not use request parameters.
Request Headers

68
GET PublicAccessBlock
Request Elements
Responses
Response Headers
The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 4).
Response Elements
This operation does not return response elements.
Special Errors
Related Resources
• Using Amazon S3 Block Public Access in the Amazon Simple Storage Service Developer Guide.
• GET BucketPolicyStatus (p. 195)
Description
This operation retrieves the PublicAccessBlock configuration for an Amazon Web Services account.
In order to use this operation, you must have the s3:GetAccountPublicAccessBlock permission. For
Important
When Amazon S3 evaluates the PublicAccessBlock configuration for a bucket or an object, it
checks the PublicAccessBlock configuration for both the bucket (or the bucket that contains
the object) and the bucket owner's account. If the PublicAccessBlock settings are different
between the bucket and the account, Amazon S3 uses the most restrictive combination of the
bucket-level and account-level settings.
For more information about when Amazon S3 considers a bucket or an object public, see The Meaning of
"Public" in the Amazon Simple Storage Service Developer Guide.
Requests
Syntax
GET /v20180820/configuration/publicAccessBlock HTTP/1.1


69

4))
Note
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
A PublicAccessBlock configuration.
PublicAccessBlockConfiguration
Type: Container
Children: BlockPublicAcls, IgnorePublicAcls, BlockPublicPolicy,

RestrictPublicBuckets
BlockPublicAcls Specifies whether Amazon S3 will block public access control lists (ACLs) for
buckets and objects that are owned by this account.
Type: Boolean
Ancestor: PublicAccessBlockConfiguration
Valid values: TRUE | FALSE
IgnorePublicAcls Specifies whether Amazon S3 will ignore public ACLs for buckets and objects
that are owned by this account.
Type: Boolean
BlockPublicPolicy Specifies whether Amazon S3 will block public bucket policies for buckets that
are owned by this account.

70
Name Description
Type: Boolean
Specifies whether Amazon S3 will restrict public bucket policies for buckets that
are owned by this account.
Type: Boolean
Special Errors
Examples
Sample Request
The following request gets an account PublicAccessBlock configuration.
GET /v20180820/configuration/publicAccessBlock HTTP/1.1

Authorization: <signatureValue>
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0
<PublicAccessBlockConfiguration>
<BlockPublicAcls>TRUE</BlockPublicAcls>
<IgnorePublicAcls>FALSE</IgnorePublicAcls>
<BlockPublicPolicy>FALSE</BlockPublicPolicy>
<RestrictPublicBuckets>FALSE</RestrictPublicBuckets>
</PublicAccessBlockConfiguration>
Related Resources

71
PUT PublicAccessBlock
Description
This operation creates or modifies the PublicAccessBlock configuration for an Amazon Web Services
account. In order to use this operation, you must have the s3:PutAccountPublicAccessBlock
permission. For more information about Amazon S3 permissions, see Specifying Permissions in a Policy
Important
the object) and the bucket owner's account. If the PublicAccessBlock configurations are
different between the bucket and the account, Amazon S3 uses the most restrictive combination
of the bucket-level and account-level settings.
For more information about when Amazon S3 considers a bucket or object public, see The Meaning of
Requests
Syntax
PUT /v20180820/configuration/publicAccessBlock HTTP/1.1

4))
Note
Request Parameters
Request Headers
Request Elements
This operation uses the following request elements. You can enable BlockPublicAcls,
IgnorePublicAcls, BlockPublicPolicy, and RestrictPublicBuckets in any combination.
Name Description Required
A PublicAccessBlock configuration. You can enable the

PublicAccessBlockConfiguration Yes
configuration elements in any combination.
Type: Container

72

Children: BlockPublicAcls, IgnorePublicAcls,
BlockPublicPolicy, RestrictPublicBuckets
BlockPublicAcls Specifies whether Amazon S3 should block public access control lists No
(ACLs) for buckets and objects in this account. Setting this element to
TRUE causes the following behavior:
• PUT Bucket acl (p. 260) and PUT Object acl (p. 467) calls fail if
the specified ACL is public.
• PUT Object (p. 434) calls fail if the request includes a public ACL.
• PUT Bucket (p. 252) calls fail if the request includes a public ACL.
Important
Enabling this setting doesn't affect existing policies or ACLs.
Type: Boolean
IgnorePublicAclsSpecifies whether Amazon S3 should ignore public ACLs for buckets No

and objects in this account. Setting this element to TRUE causes
Amazon S3 to ignore all public ACLs on buckets in this account and
objects in those buckets.
Important
Enabling this setting doesn't affect the persistence of any
existing ACLs and doesn't prevent new public ACLs from
being set.
Type: Boolean
Specifies whether Amazon S3 should block public bucket policies for

BlockPublicPolicy No
buckets in this account. Setting this element to TRUE causes Amazon
S3 to reject calls to PUT Bucket policy (p. 325) if the specified bucket
policy allows public access.
Important
Enabling this setting doesn't affect existing bucket policies.
Type: Boolean

73
Specifies whether Amazon S3 should restrict public bucket policies for

RestrictPublicBuckets No
buckets in this account. If this element is set to TRUE, then only AWS
services and authorized users within this account can access buckets
with public policies.
Important
Enabling this setting doesn't affect previously stored bucket
policies, except that public and cross-account access within
any public bucket policy, including non-public delegation to
specific accounts, is blocked.
Type: Boolean
Responses
Response Headers
Response Elements
Special Errors
Examples
First Sample Request
The following request puts an account PublicAccessBlock configuration that blocks public ACLs for
buckets in the specified account.


First Sample Response
HTTP/1.1 200 OK

74
Batch Operations
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0
Second Sample Request

The following request puts an account PublicAccessBlock configuration that ignores public ACLs and
restricts public bucket policies for buckets in the specified account.


<BlockPublicAcls>FALSE</BlockPublicAcls>
<IgnorePublicAcls>TRUE</IgnorePublicAcls>
<RestrictPublicBuckets>TRUE</RestrictPublicBuckets>
Second Sample Response
HTTP/1.1 200 OK
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0
Related Resources
Batch Operations
This section describes how to use perform batch operations with Amazon S3 accounts.
Topics
• CreateJob (p. 77)
• DescribeJob (p. 81)
• ListJobs (p. 84)
• UpdateJobStatus (p. 87)
• UpdateJobPriority (p. 90)

75
Batch Operations
• Batch Operations Common Elements (p. 92)

76
CreateJob
CreateJob
Service: AWS S3 Control
Creates an Amazon S3 batch operations job.
Request Syntax
POST /v20180820/jobs HTTP/1.1
x-amz-account-id: AccountId
<CreateJobRequest xmlns="http://awss3control.amazonaws.com/doc/2018-08-20/">
<ClientRequestToken>string</ClientRequestToken>
<ConfirmationRequired>boolean</ConfirmationRequired>
<Description>string</Description>
<Manifest>
<Location>
<ETag>string</ETag>
<ObjectArn>string</ObjectArn>
<ObjectVersionId>string</ObjectVersionId>
</Location>
<Spec>
<Fields>
<INVALID-TYPE-NAME>string</INVALID-TYPE-NAME>
</Fields>
<Format>string</Format>
</Spec>
</Manifest>
<Operation>
<S3PutObjectAcl>
<AccessControlPolicy>
<AccessControlList>
<Grants>
<S3Grant>
<Grantee>
<DisplayName>string</DisplayName>
<Identifier>string</Identifier>
<TypeIdentifier>string</TypeIdentifier>
</Grantee>
<Permission>string</Permission>
</S3Grant>
</Grants>
<Owner>
<ID>string</ID>
</Owner>
</AccessControlList>
<CannedAccessControlList>string</CannedAccessControlList>
</AccessControlPolicy>
</S3PutObjectAcl>
</Operation>
<Priority>integer</Priority>
<Report>
<Bucket>string</Bucket>
<Enabled>boolean</Enabled>
<Prefix>string</Prefix>
<ReportScope>string</ReportScope>
</Report>
<RoleArn>string</RoleArn>
</CreateJobRequest>

77
CreateJob
URI Request Parameters

The request requires the following URI parameters.
x-amz-account-id (p. 77)
Length constraints: Minimum length of 1. Maximum length of 64.
Request Body
The request accepts the following data in XML format.
CreateJobRequest (p. 77)
A root-level tag for the CreateJobRequest parameters.
Required: Yes
ClientRequestToken (p. 77)
An idempotency token to ensure that you don't accidentally submit the same request twice. You can
use any string up to the maximum length.
Type: String
Required: Yes
ConfirmationRequired (p. 77)
Indicates whether confirmation is required before Amazon S3 runs the job. By default,
ConfirmationRequired is false.
Type: Boolean
Required: No
Description (p. 77)
A description for this job. You can use any string within the permitted length. Descriptions don't
need to be unique and can be used for multiple jobs.
Type: String
Required: No
Manifest (p. 77)
Configuration parameters for the manifest.
Type: JobManifest (p. 762) object
Required: Yes
Operation (p. 77)
The operation that you want this job to perform on each object listed in the manifest. For more
information about the available operations, see Available Operations in the Amazon Simple Storage

78
CreateJob
Type: JobOperation (p. 765) object
Required: Yes
Priority (p. 77)
The numerical priority for this job. Higher numbers indicate higher priority.
Type: Integer
Valid range: Minimum value of 0. Maximum value of 2147483647.
Required: Yes
Report (p. 77)
Configuration parameters for the optional job-completion report.
Type: JobReport (p. 767) object
Required: Yes
RoleArn (p. 77)
The Amazon Resource Name (ARN) for the AWS Identity and Access Management (IAM) role that
batch operations use to execute this job's operation on each object in the manifest.
Type: String
Required: Yes
Response Syntax
HTTP/1.1 200
<CreateJobResult>
<JobId>string</JobId>
</CreateJobResult>
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in XML format by the service.
CreateJobResult (p. 79)
Root level tag for the CreateJobResult parameters.
Required: Yes
JobId (p. 79)
The ID for this job. Amazon S3 generates this ID automatically and returns it after a successful
Create Job request.
Type: String

79
CreateJob
Errors
BadRequestException
HTTP Status Code: 400

IdempotencyException

InternalServiceException

TooManyRequestsException
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

80
DescribeJob
DescribeJob
Retrieves the configuration parameters and status for an Amazon S3 batch operations job.
Request Syntax
GET /v20180820/jobs/id HTTP/1.1

id (p. 81)
The ID for the job whose information you want to retrieve.

Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
<DescribeJobResult>
<Job>
<ConfirmationRequired>boolean</ConfirmationRequired>
<CreationTime>timestamp</CreationTime>
<FailureReasons>
<JobFailure>
<FailureCode>string</FailureCode>
<FailureReason>string</FailureReason>
</JobFailure>
</FailureReasons>
<JobArn>string</JobArn>
<Manifest>
<Location>
<ETag>string</ETag>
<ObjectArn>string</ObjectArn>
<ObjectVersionId>string</ObjectVersionId>
</Location>
<Spec>
<Fields>
<INVALID-TYPE-NAME>string</INVALID-TYPE-NAME>
</Fields>
</Spec>

81
DescribeJob
</Manifest>
<Operation>
<S3PutObjectAcl>
<AccessControlList>
<Grants>
<S3Grant>
<Grantee>
<Identifier>string</Identifier>
<TypeIdentifier>string</TypeIdentifier>
</Grantee>
<Permission>string</Permission>
</S3Grant>
</Grants>
<Owner>
<ID>string</ID>
</Owner>
<CannedAccessControlList>string</CannedAccessControlList>
</S3PutObjectAcl>
</Operation>
<ProgressSummary>
<NumberOfTasksFailed>long</NumberOfTasksFailed>
<NumberOfTasksSucceeded>long</NumberOfTasksSucceeded>
<TotalNumberOfTasks>long</TotalNumberOfTasks>
</ProgressSummary>
<Report>
<Bucket>string</Bucket>
<Enabled>boolean</Enabled>
<Prefix>string</Prefix>
<ReportScope>string</ReportScope>
</Report>
<RoleArn>string</RoleArn>
<Status>string</Status>
<StatusUpdateReason>string</StatusUpdateReason>
<SuspendedCause>string</SuspendedCause>
<SuspendedDate>timestamp</SuspendedDate>
<TerminationDate>timestamp</TerminationDate>
</Job>
</DescribeJobResult>
Response Elements
DescribeJobResult (p. 81)
Root level tag for the DescribeJobResult parameters.
Required: Yes
Job (p. 81)
Contains the configuration parameters and status for the job specified in the Describe Job
request.
Type: JobDescriptor (p. 756) object

82
DescribeJob
Errors
BadRequestException


NotFoundException

See Also

• AWS SDK for C++
• AWS SDK for Go

83
ListJobs
ListJobs
Lists current jobs and jobs that have ended within the last 30 days for the AWS account that is making
the request. The job list that is returned is sorted by creation date, with the newest job first.
Request Syntax
GET /v20180820/jobs?jobStatuses=JobStatuses&maxResults=MaxResults&nextToken=NextToken
HTTP/1.1

jobStatuses (p. 84)
The List Jobs request returns jobs that match the statuses listed in this element. If you don't
provide jobStatuses, the API returns all jobs. You can specify one or more jobStatuses as
follows:
https://acct-id.s3-control.us-west-2.amazonaws.com/v20180820/jobs?
jobStatuses=Active&jobStatuses=Complete&maxResults=2
Valid values: Active | Cancelled | Cancelling | Complete | Completing | Failed

| Failing | New | Paused | Pausing | Preparing | Ready | Suspended
maxResults (p. 84)
The maximum number of jobs that Amazon S3 includes in the List Jobs response. If the number
of jobs is higher than this number, the response includes a pagination token in the NextToken field
to enable you to retrieve the next page of results. The operation might return fewer results than
maxResults, but as long as the nextToken returned is not empty, there are more results that you
can fetch.

nextToken (p. 84)
A pagination token to request the next page of results. Use the token that Amazon S3 returned in
the NextToken element of the ListJobsResult from the previous List Jobs request.

Request Body
Response Syntax
HTTP/1.1 200

84
ListJobs
<ListJobsResult>
<Jobs>
<JobListDescriptor>
<CreationTime>timestamp</CreationTime>
<Operation>string</Operation>
<ProgressSummary>
<NumberOfTasksFailed>long</NumberOfTasksFailed>
<NumberOfTasksSucceeded>long</NumberOfTasksSucceeded>
<TotalNumberOfTasks>long</TotalNumberOfTasks>
</ProgressSummary>
<TerminationDate>timestamp</TerminationDate>
</JobListDescriptor>
</Jobs>
<NextToken>string</NextToken>
</ListJobsResult>
Response Elements
ListJobsResult (p. 84)
A root-level tag for the ListJobsResult parameters.
Required: Yes
Jobs (p. 84)
The list of current jobs and jobs that have ended within the last 30 days. This is the list of jobs that
match the job statuses specified in the request, if any.
Type: Array of JobListDescriptor (p. 760) objects

NextToken (p. 84)
If the List Jobs request produced more than the maximum number of results, you can pass this
value into a subsequent List Jobs request to retrieve the next page of results. As long as the
NextToken is not empty, there are more results you can fetch (regardless of the number of jobs that
the operation produces in comparison to maxResults specified in the request).
Type: String
Errors

InvalidNextTokenException

InvalidRequestException

85
ListJobs
See Also

• AWS SDK for C++
• AWS SDK for Go

86
UpdateJobStatus
UpdateJobStatus
Updates the status for the specified job. Use this operation to confirm that you want to run a job or to
cancel an existing job.
Request Syntax
POST /v20180820/jobs/id/status?
requestedJobStatus=RequestedJobStatus&statusUpdateReason=StatusUpdateReason HTTP/1.1

id (p. 87)
The ID of the job whose status you want to update.

requestedJobStatus (p. 87)
The status that you want to move the specified job to. You move the job to the Ready state to
confirm the job. Amazon S3 then makes the job eligible for execution. You move the job to the
Cancelled state to cancel a job. This is a required parameter.
Valid Values: Cancelled | Ready

statusUpdateReason (p. 87)
A description of the reason why you want to change the specified job's status. This field can be any
string up to the maximum length.

The ID is required.
Request Body
Response Syntax
HTTP/1.1 200
<UpdateJobStatusResult>
<StatusUpdateReason>string</StatusUpdateReason>
</UpdateJobStatusResult>

87
UpdateJobStatus
Response Elements
UpdateJobStatusResult (p. 87)
A root-level tag for the UpdateJobStatusResult parameters.
Required: Yes
JobId (p. 87)
The ID for the job whose status was updated.
Type: String

Status (p. 87)
The current status for the specified job.
Type: String
Valid Values: Active | Cancelled | Cancelling | Complete | Completing | Failed

StatusUpdateReason (p. 87)
The reason that the specified job's status was updated.
Type: String
Errors
BadRequestException


JobStatusException

NotFoundException

See Also

88
UpdateJobStatus

• AWS SDK for C++
• AWS SDK for Go

89
UpdateJobPriority
UpdateJobPriority
Updates an existing job's priority.
Request Syntax
POST /v20180820/jobs/id/priority?priority=Priority HTTP/1.1

id (p. 90)
The ID for the job whose priority you want to update. The id is required.

priority (p. 90)
The priority that you want to assign to this job. The priority is required.

Request Body
Response Syntax
HTTP/1.1 200
<UpdateJobPriorityResult>
</UpdateJobPriorityResult>
Response Elements
UpdateJobPriorityResult (p. 90)
A root-level tag for the UpdateJobPriorityResult parameters.
Required: Yes
JobId (p. 90)
The ID for the job whose priority Amazon S3 updated.

90
UpdateJobPriority
Type: String

Priority (p. 90)
The new priority assigned to the specified job.
Type: Integer
Errors
BadRequestException


NotFoundException

See Also

• AWS SDK for C++
• AWS SDK for Go

91
Batch Operations Common Elements

Description
The following tables list common request, response, and special error elements for Amazon S3 control
operations.
Requests
Element Description
AccountId The account ID for the Amazon S3 account that is associated with the batch operations
job.
Type: String
FunctionArn The Amazon Resource Name (ARN) of the AWS Lambda function that you want to
invoke with a batch operations job.
Type: String
Default: None
Restrictions: Max length is 1,024 characters.
LogType The type of log that you want Lambda to produce when invoked by a batch operations
job.
Type: String
Valid values: None | Tail
The arguments that you want to pass to each invocation of a Lambda function by a
UserArguments
batch operations job.
Restrictions: The total length of arguments must be fewer than or equal to 20,480
characters
A container element used to specify the parameters of a batch operations Copy Object
S3CopyObjectAction
request.
Type: Container
Child Elements
Element Type Restrictions
TargetResource S3BucketArnString
AccessControlList S3AccessControlList
CannedAccessControlList
S3CannedAccessControlList
MetadataDirective S3MetadataDirective
TimeStamp
ModifiedSinceConstraint
NewObjectMetadata S3ObjectMetadata

92
Element Description
NewObjectTagging S3TagSet
RedirectLocation String Must be between 1 and

2,048 characters
RequesterPays Boolean
StorageClass S3StorageClass
TimeStamp
UnmodifiedSinceConstraint
The ARN of the Amazon S3 bucket that you want to use with a batch operations job.
TargetResource
Type: String
Restrictions: The value must be between 1 and 128 characters long.
A container element that is used to specify the permission grants for an object copied
AccessControlList
as part of a batch operations job.
Type: Container
Child Elements
Owner S3ObjectOwner Required
Grants S3GrantList Required
Type: Container
S3ObjectOwner
Child Elements
ID String Required
Maximum length is 1,024
characters
DisplayName String Required

characters
S3GrantList Type: List
List Item Type: S3Grant

93
Element Description
S3Grant A permission grant for an Amazon S3 resource.
Type: Container
Child Elements
Grantee S3Grantee Required
Permission S3Permission Required
S3Grantee A grantee for an S3Grant.
Type: Container
Child Elements
TypeIdentifier S3GranteeTypeIdentifier Required
Identifier String Required

characters
DisplayName String Required

characters
Identifies the type of grantee that is used to grant permissions for an Amazon S3
S3GranteeTypeIdentifier
resource.
Type: String
Valid values: CANONICAL | EMAIL_ADDRESS | GROUP
S3PermissionSpecifies an access permission to be granted for an Amazon S3 resource.
Type: String
Valid values: FULL_CONTROL | READ | WRITE | READ_ACP | WRITE_ACP
Type: String
S3MetadataDirective
Valid values: COPY | REPLACE
Type: String
S3StorageClass
Valid values: STANDARD | STANDARD_IA | ONEZONE_IA | GLACIER |

INTELLIGENT_TIERING | DEEP_ARCHIVE
JobId The ID of the batch operations job that you want to perform an action on.
Type: String
Restrictions: Must be between 5 and 36 characters long.

94
Element Description
JobPriority Type: Integer
Restrictions: The value must be between 0 and 2^31 - 1 (2147483647)
JobReport
JobStatus Type: String
Valid values: Active | Cancelled | Cancelling | Complete | Completing | Failed

| Failing | New | Paused | Pausing | Preparing | Ready
Type: String
JobStatusUpdateReason
Restrictions: Maximum length is 256 characters
JobReport Type: Container
Child Elements
AccountId AccountId
Bucket String Required

Must be between 1 and
128 characters
Format String Required

Valid values:
JobReport_CSV_20180820
Prefix String Required

512 characters long
ReportScope String Required

Valid values: AllTasks |
FailedTasksOnly
Responses
Element Description
Type: Container
JobDescriptor
Child Elements
JobId JobId
Name String Must be between 1 and

256 characters

95
Element Description
JobArn String Must be between 1 and

1,250 characters
Status JobStatus
Manifest JobManifest
Action JobAction
Priority JobPriority
ProgressSummary JobProgressSummary
StatusUpdateReason JobStatusUpdateReason
FailureReasons JobFailureReasonList
Report JobReport
CreationTime JobCreationTime
TerminationTime JobTerminationTime
Type: Container
JobProgressSummary
Child Elements
Element Type
TotalNumberOfTasks Long
NumberOfTasksSucceeded Long
NumberOfTasksFailed Long
Type: List
JobFailureReasonList
List Item Type: JobFailureReason
Type: String
JobFailureReason
Valid values: ErrorReadingManifest | ErrorWritingReport |

TaskFailureThresholdExceeded
Elements Common to Requests and Responses
Element Description
JobAction A container element that is used to specify what action you want batch operations or
Amazon S3 public lockdown to perform.
Type: Container

96
Element Description
Child Elements
LambdaInvoke LambdaInvokeAction
S3CopyObject S3CopyObjectAction
S3SetObjectAcl S3SetObjectAclAction
S3SetObjectTagging
S3SetObjectTaggingAction
S3InitiateRestoreObject
S3InitiateRestoreObjectAction
Restrictions: Exactly one child element is required when JobAction is used in a

request.
JobManifest Type: Container
Child Elements
Spec JobManifestSpec Required in requests
Location JobManifestLocation Required in requests
Type: Container
JobManifestSpec
Child Elements
Format String Required in requests
Valid values:
S3Foreman_CSV_20180820
|
S3InventoryReport_CSV_20161130
Fields List Each entry must be

between 1 and 1,024
List Item Type: String characters

97
Element Description
Type: Container
JobManifestLocation
Child Elements
AccountId AccountId
ObjectArn String Required in requests

2,000 characters
ObjectVersionId String Must be between 1 and

2,000 characters
ETag String Must be between 1 and

1,024 characters
Type: String
S3BucketArnString
Restrictions: Must be between 1 and 128 characters
Type: Container
S3AccessControlPolicy
Child Elements
Element Type
CannedAccessControlList S3CannedAccessControlList
Type: Container
S3AccessControlList
Child Elements
Element Type
Owner S3ObjectOwner
Grants S3GrantList
Type: String
Valid values: PRIVATE | PUBLIC_READ | PUBLIC_READ_WRITE | AWS_EXEC_READ |

AUTHENTICATED_READ | BUCKET_OWNER_READ | BUCKET_OWNER_FULL_CONTROL
S3TagSet Type: List
List Item Type: S3Tag

98
Element Description
S3Tag Type: Container
Child Elements
Key String Required

1,024 characters
Value String Required

1,024 characters
Type: Container
S3ObjectMetadata
Child Elements
CacheControl String Must be between 1 and

1,024 characters
ContentDisposition String Must be between 1 and

1,024 characters
ContentEncoding String Must be between 1 and

1,024 characters
ContentLanguage String Must be between 1 and

1,024 characters
UserMetadata S3UserMetadata
ContentLength Integer Must be greater than or

equal to 0
ContentMD5 String Must be between 1 and

1,024 characters
ContentType String Must be between 1 and

1,024 characters
HttpExpiresDate TimeStamp
RequesterCharged Boolean
Type: Map
S3UserMetadata
Restrictions: The total length of the key + value must be fewer than or equal to 8,192
characters

99
Actions
Action Description
A container element that is used to specify the AWS Lambda action that you want to
LambdaInvokeAction
invoke with a batch operations job.
Type: Container
Child Elements
FunctionArn String Required

1,024 characters
LogType String Required

Valid values: None | Tail
UserArguments UserArguments Required
S3CopyObjectA container element that is used to specify the parameters of a batch operations Copy
Object request.
Type: Container
Child Elements
TargetResource S3BucketArnString (p. 96)
MetadataDirective S3MetadataDirective
TimeStamp
ModifiedSinceConstraint
NewObjectMetadata S3ObjectMetadata
NewObjectTagging S3TagSet
RedirectLocation String Must be between 1 and

2,048 characters
RequesterPays Boolean
StorageClass S3StorageClass
TimeStamp
UnmodifiedSinceConstraint
Type: Container
S3SetObjectAcl

100
Action Description
Child Elements
AccessControlPolicy S3AccessControlPolicy Required
Type: Container
S3SetObjectTagging
Child Elements
TagSet S3TagSet
Type: Container
Child Elements
ExpirationInDays Integer Must be greater than or

equal to 0
Special Errors
Error Description
Type: Container
Child elements: Message (type: String)
Type: Container
BadRequestException
Type: Container
IdempotencyException
Type: Container
Type: Container
NotFoundException
Type: Container
NoSuchAccount

101
Operations on Buckets
This section describes operations you can perform on Amazon S3 buckets.
Topics
• DELETE Bucket (p. 104)
• DELETE Bucket analytics (p. 106)
• DELETE Bucket cors (p. 108)
• DELETE Bucket encryption (p. 110)
• DELETE Bucket inventory (p. 112)
• DELETE Bucket lifecycle (p. 114)
• DELETE Bucket metrics (p. 116)
• DELETE Bucket policy (p. 119)
• DELETE Bucket replication (p. 121)
• DELETE Bucket tagging (p. 123)
• DELETE Bucket website (p. 125)
• GET Bucket accelerate (p. 146)
• GET Bucket acl (p. 149)
• GET Bucket analytics (p. 152)
• GET Bucket cors (p. 157)
• GET Bucket encryption (p. 161)
• GET Bucket Inventory (p. 165)
• GET Bucket lifecycle (p. 171)
• GET Bucket location (p. 178)
• GET Bucket logging (p. 183)
• GET Bucket metrics (p. 186)
• GET Bucket notification (p. 190)
• GET Bucket object lock configuration (p. 195)
• GET Bucket Object versions (p. 198)
• GET Bucket policy (p. 210)
• GET Bucket replication (p. 212)
• GET Bucket requestPayment (p. 219)
• GET Bucket tagging (p. 221)
• GET Bucket versioning (p. 224)
• GET Bucket website (p. 227)
• HEAD Bucket (p. 229)
• List Bucket Analytics Configurations (p. 231)
• List Bucket Inventory Configurations (p. 235)
• List Bucket Metrics Configurations (p. 240)
• List Multipart Uploads (p. 243)

102
• PUT Bucket (p. 252)

• PUT Bucket accelerate (p. 257)
• PUT Bucket acl (p. 260)
• PUT Bucket analytics (p. 267)
• PUT Bucket cors (p. 273)
• PUT Bucket encryption (p. 279)
• PUT Bucket inventory (p. 283)
• PUT Bucket lifecycle (p. 290)
• PUT Bucket logging (p. 306)
• PUT Bucket metrics (p. 310)
• PUT Bucket notification (p. 315)
• PUT Bucket object lock configuration (p. 323)
• PUT Bucket policy (p. 325)
• PUT Bucket replication (p. 327)
• PUT Bucket requestPayment (p. 336)
• PUT Bucket tagging (p. 338)
• PUT Bucket versioning (p. 341)
• PUT Bucket website (p. 345)

103
DELETE Bucket
DELETE Bucket
Description
Deletes the bucket named in the URI. All objects (including all object versions and delete markers) in the
bucket must be deleted before the bucket itself can be deleted.
Requests
Syntax
DELETE / HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 4).
Response Elements
This implementation of the operation does not return response elements.
Special Errors
Examples
Sample Request
This request deletes the bucket named "quotes".

104
Related Resources
DELETE / HTTP/1.1
Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Sample Response
HTTP/1.1 204 No Content
x-amz-id-2: JuKZqmXuiwFeDQxhD7M8KtsKobSzWA1QEjLbTMTagkKdBX2z7Il/jGhDeJ3j6s80
x-amz-request-id: 32FE2CEB32F5EE25
Date: Wed, 01 Mar 2006 12:00:00 GMT
Connection: close
Server: AmazonS3
Related Resources
• DELETE Object (p. 364)

105
DELETE Bucket analytics
DELETE Bucket analytics

Description
This implementation of the DELETE operation deletes an analytics configuration (identified by the
analytics configuration ID) from the bucket.
To use this operation, you must have permissions to perform the s3:PutAnalyticsConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.
For information about Amazon S3 analytics feature, see Amazon S3 Analytics – Storage Class Analysis in
the Amazon Simple Storage Service Developer Guide.
Requests
Syntax
DELETE /?analytics&id=analytics-configuration-ID HTTP/1.1
Host: bucketname.s3.amazonaws.com
Date: date
4))
Request Parameters
This implementation of DELETE uses the parameter in the following table.
Parameter Description Required
id The ID that identifies the analytics configuration. Yes
Type: String
Default: None
Valid Characters for id: a-z A-Z 0-9 - _ .
Request Headers
Request Elements

106
Responses
Responses
Response Headers
Examples
Sample Request
The following DELETE request deletes the analytics configuration with the ID list1.
DELETE ?/analytics&id=list1 HTTP/1.1

Date: Wed, 14 May 2014 02:11:22 GMT
Authorization: signatureValue
Sample Response
The following successful response shows Amazon S3 returning a 204 No Content response. The
analytics configuration with the ID list1 for the bucket has been removed.

x-amz-id-2: 0FmFIWsh/PpBuzZ0JFRC55ZGVmQW4SHJ7xVDqKwhEdJmf3q63RtrvH8ZuxW1Bol5
x-amz-request-id: 0CF038E9BCF63097
Date: Wed, 14 May 2014 02:11:22 GMT
Server: AmazonS3
Related Resources

107
DELETE Bucket cors
DELETE Bucket cors

Description
Deletes the cors configuration information set for the bucket.
To use this operation, you must have permission to perform the s3:PutBucketCORS action. The bucket
owner has this permission by default and can grant this permission to others.
For information more about cors, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple
Requests
Syntax
DELETE /?cors HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Examples
Example 1: Retrieve cors subresource
The following DELETE request deletes the cors subresource from the specified bucket. This action
removes cors configuration that is stored in the subresource.
Sample Request
DELETE /?cors HTTP/1.1

108
Related Resources
Date: Tue, 13 Dec 2011 19:14:42 GMT
Sample Response

Date: Tue, 13 Dec 2011 19:14:42 GMT
Server: AmazonS3
Content-Length: 0
Related Resources
• OPTIONS object (p. 404)

109
DELETE Bucket encryption
DELETE Bucket encryption

Description
This implementation of the DELETE operation removes default encryption from the bucket. For
information about the Amazon S3 default encryption feature, see Amazon S3 Default Bucket Encryption
To use this operation, you must have permissions to perform the s3:PutEncryptionConfiguration
Requests
Syntax
DELETE /?encryption HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Examples
Sample Request
The following DELETE request deletes default encryption from the bucket.
DELETE ?/encryption HTTP/1.1

110
Related Resources
Date: Wed, 06 Sep 2017 12:00:00 GMT
Sample Response
The following successful response shows Amazon S3 returning a 204 No Content response confirming
that default encryption has been removed from the bucket.

Date: Wed, 06 Sep 2017 12:00:00 GMT
Server: AmazonS3
Related Resources

111
DELETE Bucket inventory
DELETE Bucket inventory

Description
This implementation of the DELETE operation deletes an inventory configuration (identified by the
inventory configuration ID) from the bucket.
To use this operation, you must have permissions to perform the s3:PutInventoryConfiguration
For information about the Amazon S3 inventory feature, see Amazon S3 Inventory in the Amazon Simple
Requests
Syntax
DELETE /?inventory&id=inventory-configuration-ID HTTP/1.1
Date: date
4))
Request Parameters
This implementation of DELETE uses the parameter in the following table.
id The ID that identifies the inventory configuration. Yes
Type: String
Default: None
Request Headers
Request Elements

112
Responses
Responses
Response Headers
Examples
Sample Request
The following DELETE request deletes the inventory configuration with the ID list1.
DELETE ?/inventory&id=list1 HTTP/1.1

Date: Wed, 14 May 2014 02:11:22 GMT
Sample Response
The following successful response shows Amazon S3 returning a 204 No Content response. The
inventory configuration with the ID list1 for the bucket has been removed.

Date: Wed, 14 May 2014 02:11:22 GMT
Server: AmazonS3
Related Resources

113
DELETE Bucket lifecycle
DELETE Bucket lifecycle

Description
Deletes the lifecycle configuration from the specified bucket. Amazon S3 removes all the lifecycle
configuration rules in the lifecycle subresource associated with the bucket. Your objects never expire, and
Amazon S3 no longer automatically deletes any objects on the basis of rules contained in the deleted
lifecycle configuration.
To use this operation, you must have permission to perform the s3:PutLifecycleConfiguration
action. By default, the bucket owner has this permission and the bucket owner can grant this permission
to others.
There is usually some time lag before lifecycle configuration deletion is fully propagated to all the
Amazon S3 systems.
For more information about the object expiration, go to Elements to Describe Lifecycle Actions in the
Requests
Syntax
DELETE /?lifecycle HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers

114
Examples
Examples
Sample Request
The following DELETE request deletes the lifecycle subresource from the specified bucket. This
removes lifecycle configuration stored in the subresource.
DELETE /?lifecycle HTTP/1.1

Date: Wed, 14 Dec 2011 05:37:16 GMT
Sample Response
The following successful response shows Amazon S3 returning a 204 No Content response. Objects in
your bucket no longer expire.

x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOAa==
x-amz-request-id: 656c76696e672SAMPLE5657374
Date: Wed, 14 Dec 2011 05:37:16 GMT
Connection: keep-alive
Server: AmazonS3
Related Resources
DELETE PublicAccessBlock
Description
This operation removes the PublicAccessBlock configuration for an Amazon S3 bucket. In order
to use this operation, you must have the s3:PutBucketPublicAccessBlock permission. For more
information about Amazon S3 permissions, see Specifying Permissions in a Policy in the Amazon Simple
Requests
Syntax
DELETE /<bucket-name>?publicAccessBlock HTTP/1.1
Host: <bucket-name>.s3.amazonaws.com
4))
Request Parameters

115
Responses
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Special Errors
Related Resources
DELETE Bucket metrics

Description
Deletes a metrics configuration for the Amazon CloudWatch request metrics (specified by the metrics
configuration ID) from the bucket. Note that this doesn't include the daily storage metrics.
To use this operation, you must have permissions to perform the s3:PutMetricsConfiguration
For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon
CloudWatch in the Amazon Simple Storage Service Developer Guide.

116
Requests
Requests
Syntax
DELETE /?metrics&id=Id HTTP/1.1
HOST: BucketName.s3.amazonaws.com
Content-Length: length
Date: date
4))
Request Parameters
id The ID used to identify the metrics configuration. Yes
Request Headers
This operation uses only Request Headers common to most requests. For more information, see Common
Request Headers (p. 2).
Request Elements
This operation does not use request elements.
Responses
Response Headers
Response Elements
Special Errors
Examples
Sample Request
Delete the metric configuration with a specified ID, which disables the CloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.
DELETE /?metrics&id=ExampleMetrics HTTP/1.1

x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT

117
Requests
Sample Response
Delete the metric configuration with a specified ID, which disables the CloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Related Resources
• Monitoring Metrics with Amazon CloudWatch in the Amazon Simple Storage Service Developer Guide.

118
DELETE Bucket policy
DELETE Bucket policy

Description
This implementation of the DELETE operation uses the policy subresource to delete the policy of a
specified bucket. If you are using an identity other than the root user of the AWS account that owns the
bucket, the calling identity must have the DeleteBucketPolicy permissions on the specified bucket
and belong to the bucket owner's account in order to use this operation.
If you don't have DeleteBucketPolicy permissions, Amazon S3 returns a 403 Access Denied error.
If you have the correct permissions, but you're not using an identity that belongs to the bucket owner's
account, Amazon S3 returns a 405 Method Not Allowed error.
Important
As a security precaution, the root user of the AWS account that owns a bucket can always use
this operation, even if the policy explicitly denies the root user the ability to perform this action.
For more information about bucket policies, see Using Bucket Policies and User Policies in the Amazon
Requests
Syntax
DELETE /?policy HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
The response elements contain the status of the DELETE operation including the error code if the
request failed.

119
Examples
Special Errors
Examples
Sample Request
This request deletes the bucket named BucketName.
DELETE /?policy HTTP/1.1

Date: Tue, 04 Apr 2010 20:34:56 GMT
Sample Response
x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOFg==
Date: Tue, 04 Apr 2010 20:34:56 GMT
Server: AmazonS3
Related Resources

120
DELETE Bucket replication
DELETE Bucket replication

Description
Deletes the replication subresource associated with the specified bucket. This deletes the replication
configuration from the bucket.
To use this operation, you must have permissions to perform the s3:PutReplicationConfiguration
action. The bucket owner has these permissions by default and can grant it to others. For information
about permissions, see Permissions Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.
Note
It can take a while for the deletion of a replication configuration to fully propagate.
For information about replication configuration, see Cross-Region Replication in the Amazon Simple
Requests
Syntax
DELETE /?replication HTTP/1.1
Date: date
For more information about authorization, see Authenticating Requests (AWS Signature Version
4) (p. 14).
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Examples
The following DELETE request deletes the replication subresource from the specified bucket. This
removes the replication configuration that is set for the bucket.

121
Related Resources
DELETE /?replication HTTP/1.1

Date: Wed, 11 Feb 2015 05:37:16 GMT
20150211T171320Z
When the replication subresource has been deleted, Amazon S3 returns a 204 No Content
response. It will not replicate new objects that are stored in the examplebucket bucket.

x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOAa==
x-amz-request-id: 656c76696e672example
Date: Wed, 11 Feb 2015 05:37:16 GMT
Server: AmazonS3
Related Resources

122
DELETE Bucket tagging
DELETE Bucket tagging

Description
This implementation of the DELETE operation uses the tagging subresource to remove a tag set from
the specified bucket.
To use this operation, you must have permission to perform the s3:PutBucketTagging action. By
default, the bucket owner has this permission and can grant this permission to others.
Requests
Syntax
DELETE /?tagging HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Examples
Sample Request
The following DELETE request deletes the tag set from the specified bucket.
DELETE /?tagging HTTP/1.1

Date: Wed, 14 Dec 2011 05:37:16 GMT

123
Related Resources
Sample Response
The following successful response shows Amazon S3 returning a 204 No Content response. The tag set
for the bucket has been removed.

Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3
Related Resources

124
DELETE Bucket website
DELETE Bucket website

Description
This operation removes the website configuration for a bucket. Amazon S3 returns a 200 OK response
upon successfully deleting a website configuration on the specified bucket. You will get a 200 OK
response if the website configuration you are trying to delete does not exist on the bucket. Amazon S3
returns a 404 response if the bucket specified in the request does not exist.
This DELETE operation requires the S3:DeleteBucketWebsite permission. By default, only the bucket
owner can delete the website configuration attached to a bucket. However, bucket owners can grant
other users permission to delete the website configuration by writing a bucket policy granting them the
S3:DeleteBucketWebsite permission.
For more information about hosting websites, go to Hosting Websites on Amazon S3 in the Amazon
Simple Storage Service Developer Guide .
Requests
Syntax
DELETE /?website HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements

125
Examples
Examples
Sample Request
This request deletes the website configuration on the specified bucket.
DELETE ?website HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Thu, 27 Jan 2011 12:00:00 GMT
Sample Response
x-amz-id-2: aws-s3integ-s3ws-31008.sea31.amazon.com
x-amz-request-id: AF1DD829D3B49707
Date: Thu, 03 Feb 2011 22:10:26 GMT
Server: AmazonS3
Related Resources

126
GET Bucket (List Objects) Version 2

Description
This implementation of the GET operation returns some or all (up to 1,000) of the objects in a bucket.
You can use the request parameters as selection criteria to return a subset of the objects in a bucket. A
200 OK response can contain valid or invalid XML. Make sure to design your application to parse the
contents of the response and handle it appropriately.
To use this implementation of the operation, you must have READ access to the bucket.
To use this operation in an AWS Identity and Access Management (IAM) policy, you must have
permissions to perform the s3:ListBucket action. The bucket owner has this permission by default
and can grant this permission to others. For more information about permissions, see Permissions
Related to Bucket Operations and Managing Access Permissions to Your Amazon S3 Resources in the
Important
This section describes the latest revision of the API. We recommend that you use this
revised API, GET Bucket (List Objects) version 2, for application development. For backward
compatibility, Amazon S3 continues to support the prior version of this API, GET Bucket (List
Objects) version 1. For more information about the previous version, see GET Bucket (List
Objects) Version 1 (p. 137).
Note
To get a list of your buckets, see GET Service (p. 65).
Requests
Syntax
GET /?list-type=2 HTTP/1.1
Date: date
4))
Request Parameters
This implementation of GET uses the parameters in the following table.
delimiter A delimiter is a character you use to group keys. No
If you specify a prefix, all of the keys that contain the same string between
the prefix and the first occurrence of the delimiter after the prefix are
grouped under a single result element called CommonPrefixes. If you don't
specify the prefix parameter, the substring starts at the beginning of the
key. The keys that are grouped under the CommonPrefixes result element
are not returned elsewhere in the response.
Type: String
Default: None

127
Requests
encoding- Requests Amazon S3 to encode the response and specifies the encoding No
type method to use.
An object key can contain any Unicode character. However, XML 1.0 parsers
cannot parse some characters, such as characters with an ASCII value from
0 to 10. For characters that are not supported in XML 1.0, you can add this
parameter to request that Amazon S3 encode the keys in the response.
Type: String
Default: None
Valid value: url
max-keys Sets the maximum number of keys returned in the response body. If you No
want to retrieve fewer than the default 1,000 keys, you can add this to your
request.
The response might contain fewer keys, but it never contains more. If there
are additional keys that satisfy the search criteria, but these keys were
not returned because max-keys was exceeded, the response contains
<IsTruncated>true</IsTruncated>. To return the additional keys, see
NextContinuationToken.
Type: String
Default: 1000
prefix Limits the response to keys that begin with the specified prefix. You can use No
prefixes to separate a bucket into different groupings of keys. (You can think
of using prefix to make groups in the same way you'd use a folder in a file
system.)
Type: String
Default: None
list- Version 2 of the API requires this parameter and you must set its value to 2. Yes
type
Type: String
Default: The value is always 2.
When the response to this API call is truncated (that is, the IsTruncated
continuation- No
token response element value is true), the response also includes the
NextContinuationToken element. To list the next set of objects, you
can use the NextContinuationToken element in the next request as the
continuation-token.
• The continuation token is an opaque value that Amazon S3 understands.

• Amazon S3 lists objects in UTF-8 character encoding in lexicographical
order.
Type: String
Default: None

128
Responses
fetch- By default, the API does not return the Owner information in the response. No
owner If you want the owner information in the response, you can specify this
parameter with the value set to true.
Type: String
Default: false
start- If you want the API to return key names after a specific object key in your No
after key space, you can add this parameter. Amazon S3 lists objects in UTF-8
character encoding in lexicographical order.
This parameter is valid only in your first request. If the response is truncated,
you can specify this parameter along with the continuation-token
parameter, and then Amazon S3 ignores this parameter.
Type: String
Default: None
Request Elements
Request Headers
Responses
Response Headers
Response Elements
Name Description
Contents Metadata about each object returned.
Type: XML metadata
Ancestor: ListBucketResult
CommonPrefixes All of the keys rolled up into a common prefix count as a single return
when calculating the number of returns. See MaxKeys.
• A response can contain CommonPrefixes only if you specify a

delimiter.
• CommonPrefixes contains all (if there are any) keys between
Prefix and the next occurrence of the string specified by a delimiter.

129
Responses
Name Description
• CommonPrefixes lists keys that act like subdirectories in the
directory specified by Prefix.
For example, if the prefix is notes/ and the delimiter is a slash (/) as in
notes/summer/july, the common prefix is notes/summer/. All of
the keys that roll up into a common prefix count as a single return when
calculating the number of returns. See MaxKeys.
Type: String
Delimiter Causes keys that contain the same string between the prefix and the
first occurrence of the delimiter to be rolled up into a single result
element in the CommonPrefixes collection. These rolled-up keys are
not returned elsewhere in the response. Each rolled-up result counts as
only one return against the MaxKeys value.
Type: String
DisplayName Object owner's name.

Important
This value is only included in the response in the US East (N.
Virginia), US West (N. California), US West (Oregon), Asia Pacific
(Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo), EU
(Ireland), and South America (São Paulo) regions.
Reference.
Type: String
Ancestor: ListBucketResult.Contents.Owner
Encoding-Type Encoding type used by Amazon S3 to encode object key names in the
XML response.
If you specify encoding-type request parameter, Amazon S3 includes

this element in the response, and returns encoded key name values in
the following response elements:
Delimiter, Prefix, Key, and StartAfter.
Type: String
ETag The entity tag is an MD5 hash of the object. ETag reflects only changes
to the contents of an object, not its metadata.
Type: String
Ancestor: ListBucketResult.Contents

130
Responses
Name Description
ID Object owner's ID.
Type: String
IsTruncated Set to false if all of the results were returned. Set to true if more
keys are available to return. If the number of results exceeds that
specified by MaxKeys, all of the results might not be returned.
Type: Boolean
Key The object's key.
Type: String
LastModified Date and time the object was last modified.
Type: Date
MaxKeys The maximum number of keys returned in the response body.
Type: String
Name Name of the bucket.
Type: String
Owner Bucket owner.
Type: String
Children: DisplayName, ID
Ancestor: ListBucketResult.Contents | CommonPrefixes
Prefix Keys that begin with the indicated prefix.
Type: String
Size Size in bytes of the object.
Type: String

131
Examples
Name Description
StorageClass The storage class used to store the object.
Type: String
Valid values: STANDARD | REDUCED_REDUNDANCY | GLACIER

| STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING |
DEEP_ARCHIVE
ContinuationToken If ContinuationToken was sent with the request, it is included in the

response.
Type: String
KeyCount Returns the number of keys included in the response. The value is
always less than or equal to the MaxKeys value.
Type: String
NextContinuationToken If the response is truncated, Amazon S3 returns this parameter with a

continuation token. You can specify the token as the continuation-
token in your next request to retrieve the next set of keys.
Type: String
StartAfter If StartAfter was sent with the request, it is included in the response.
Type: String
Special Errors
Examples
Example 1: Listing Keys
This request returns the objects in BucketName. The request specifies the list-type parameter, which
indicates version 2 of the API.
Sample Request

Host: bucket.s3.amazonaws.com
x-amz-date: 20160430T233541Z

132
Examples

Content-Type: text/plain
Sample Response

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>bucket</Name>
<Prefix/>
<KeyCount>205</KeyCount>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>my-image.jpg</Key>
<LastModified>2009-10-12T17:50:30.000Z</LastModified>
<ETag>"fba9dede5f27731c9771645a39863328"</ETag>
<Size>434234</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>
<Contents>
...
</Contents>
...
</ListBucketResult>
Example 2: Listing Keys Using the max-keys, prefix, and start-

after Parameters
In addition to the list-type parameter that indicates version 2 of the API, the request also specifies
additional parameters to retrieve up to three keys in the quotes bucket that start with E and occur
lexicographically after ExampleGuide.pdf.
Sample Request
GET /?list-type=2&max-keys=3&prefix=E&start-after=ExampleGuide.pdf HTTP/1.1

x-amz-date: 20160430T232933Z
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: gyB+3jRPnrkN98ZajxHXr3u7EFM67bNgSAxexeEHndCX/7GRnfTXxReKUQF28IfP
x-amz-request-id: 3B3C7C725673C630
Date: Sat, 30 Apr 2016 23:29:37 GMT
Content-Type: application/xml
Connection: close
Server: AmazonS3

<Name>quotes</Name>
<Prefix>E</Prefix>
<StartAfter>ExampleGuide.pdf</StartAfter>
<Contents>

133
Examples
<Key>ExampleObject.txt</Key>
<ETag>"599bab3ed2c697f1d26842727561fd94"</ETag>
<Size>857</Size>
<StorageClass>REDUCED_REDUNDANCY</StorageClass>
</Contents>
</ListBucketResult>
Example 3: Listing Keys Using the prefix and delimiter

Parameters
This example illustrates the use of the prefix and the delimiter parameters in the request. For this
example, we assume that you have the following keys in your bucket:
sample.jpg
photos/2006/January/sample.jpg
photos/2006/February/sample2.jpg
The following GET request specifies the delimiter parameter with value /.
GET /?list-type=2&delimiter=/ HTTP/1.1

x-amz-date: 20160430T235931Z
The key sample.jpg does not contain the delimiter character, and Amazon S3 returns it in the
Contents element in the response. However, all other keys contain the delimiter character. Amazon S3
groups these keys and returns a single CommonPrefixes element with the prefix value photos/. The
element is a substring that starts at the beginning of these keys and ends at the first occurrence of the
specified delimiter.
<Name>example-bucket</Name>
<Prefix></Prefix>
<Delimiter>/</Delimiter>
<Contents>
<Key>sample.jpg</Key>
<ETag>"bf1d737a4d46a19f3bced6905cc8b902"</ETag>
<Size>142863</Size>
</Contents>
<CommonPrefixes>
<Prefix>photos/</Prefix>
</CommonPrefixes>
</ListBucketResult>
The following GET request specifies the delimiter parameter with value /, and the prefix parameter
with value photos/2006/.
GET /?list-type=2&prefix=photos/2006/&delimiter=/ HTTP/1.1

134
Examples
x-amz-date: 20160501T000433Z
In response, Amazon S3 returns only the keys that start with the specified prefix. Further, it uses the
delimiter character to group keys that contain the same substring until the first occurrence of
the delimiter character after the specified prefix. For each such key group Amazon S3 returns one
CommonPrefixes element in the response. The keys grouped under this CommonPrefixes element
are not returned elsewhere in the response. The value returned in the CommonPrefixes element is
a substring that starts at the beginning of the key and ends at the first occurrence of the specified
delimiter after the prefix.
<Prefix>photos/2006/</Prefix>
<Contents>
<Key>photos/2006/</Key>
<ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
<Size>0</Size>
</Contents>
<CommonPrefixes>
<Prefix>photos/2006/February/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/January/</Prefix>
</CommonPrefixes>
</ListBucketResult>
Example 4: Using a Continuation Token

In this example, the initial request returns more than 1,000 keys. In response to this request, Amazon
S3 returns the IsTruncated element with the value set to true and with a NextContinuationToken
element.

Date: Mon, 02 May 2016 23:17:07 GMT
The following is a sample response:
HTTP/1.1 200 OK
Date: Sat, 30 Apr 2016 23:29:37 GMT
Connection: close
Server: AmazonS3
<Name>bucket</Name>
<Prefix></Prefix>

135
More Info
<NextContinuationToken>1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM=</
NextContinuationToken>
<IsTruncated>true</IsTruncated>
<Contents>
<Key>happyface.jpg</Key>
<ETag>"70ee1738b6b21e2c8a43f3a5ab0eee71"</ETag>
<Size>11</Size>
</Contents>
...
</ListBucketResult>
In the following subsequent request, we include a continuation-token query parameter in the

request with value of the <NextContinuationToken> from the preceding response.

GET /?list-type=2&continuation-token=1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM= HTTP/1.1
Date: Mon, 02 May 2016 23:17:07 GMT
Amazon S3 returns a list of the next set of keys starting where the previous request ended.
HTTP/1.1 200 OK
Date: Sat, 30 Apr 2016 23:29:37 GMT
Connection: close
Server: AmazonS3
<Name>bucket</Name>
<Prefix></Prefix>
<ContinuationToken>1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM=</ContinuationToken>
<Contents>
<Key>happyfacex.jpg</Key>
<ETag>"70ee1738b6b21e2c8a43f3a5ab0eee71"</ETag>
<Size>1111</Size>
</Contents>
...
</ListBucketResult>
More Info
• PUT Object (p. 434)

136

Description
Important
This API has been revised. We recommend that you use the newer version, GET Bucket (List
Objects) version 2, when developing applications. For more information, see GET Bucket (List
Objects) Version 2 (p. 127). For backward compatibility, Amazon S3 continues to support GET
Bucket (List Objects) version 1.
This implementation of the GET operation returns some or all (up to 1,000) of the objects in a bucket.
You can use the request parameters as selection criteria to return a subset of the objects in a bucket.
A 200 OK response can contain valid or invalid XML. Be sure to design your application to parse the
contents of the response and handle it appropriately.
To use this implementation of the operation, you must have READ access to the bucket.
Note
To get a list of your buckets, see GET Service (p. 65).
Requests
Syntax
GET / HTTP/1.1
Date: date
4))
Request Parameters
This implementation of GET uses the parameters in the following table to return a subset of the objects
in a bucket.
delimiter A delimiter is a character you use to group keys. No
If you specify a prefix, all keys that contain the same string between the
prefix and the first occurrence of the delimiter after the prefix are grouped
under a single result element called CommonPrefixes. If you don't specify
the prefix parameter, the substring starts at the beginning of the key. The
keys that are grouped under the CommonPrefixes result element are not
returned elsewhere in the response.
Type: String
Default: None
encoding- Requests Amazon S3 to encode the response and specifies the encoding No
type method to use.
An object key can contain any Unicode character. However, XML 1.0 parsers
cannot parse some characters, such as characters with an ASCII value from

137

0 to 10. For characters that are not supported in XML 1.0, you can add this
parameter to request that Amazon S3 encode the keys in the response.
Type: String
Default: None
Valid value: url
marker Specifies the key to start with when listing objects in a bucket. Amazon S3 No
returns object keys in UTF-8 binary order, starting with key after the marker
in order.
Type: String
Default: None
max-keys Sets the maximum number of keys returned in the response body. If you No
want to retrieve fewer than the default 1,000 keys, you can add this to your
request.
The response might contain fewer keys, but it never contains more. If there
are additional keys that satisfy the search criteria, but these keys were
not returned because max-keys was exceeded, the response contains
<IsTruncated>true</IsTruncated>. To return the additional keys, see
marker.
Type: String
Default: 1,000
prefix Limits the response to keys that begin with the specified prefix. You can use No
prefixes to separate a bucket into different groupings of keys. (You can think
of using prefix to make groups in the same way you would use a folder in a
file system.)
Type: String
Default: None
Request Elements
Request Headers
Responses
Response Headers

138
Response Elements
Name Description
Type: XML metadata
CommonPrefixes All of the keys rolled up in a common prefix count as a single return
when calculating the number of returns. See MaxKeys.
• A response can contain CommonPrefixes only if you specify a

delimiter.
• CommonPrefixes contains all (if there are any) keys between
Prefix and the next occurrence of the string specified by the
delimiter.
• CommonPrefixes lists keys that act like subdirectories in the
directory specified by Prefix.
For example, if the prefix is notes/ and the delimiter is a slash (/) as in
notes/summer/july, the common prefix is notes/summer/. All of
the keys that roll up into a common prefix count as a single return when
calculating the number of returns. See MaxKeys.
Type: String
Delimiter Causes keys that contain the same string between the prefix and the
first occurrence of the delimiter to be rolled up into a single result
element in the CommonPrefixes collection. These rolled-up keys are
not returned elsewhere in the response. Each rolled-up result counts as
only one return against the MaxKeys value.
Type: String

Important
Reference.
Type: String
XML response.

139
Name Description
If you specify the encoding-type request parameter, Amazon S3
includes this element in the response, and returns encoded key name
values in the following response elements:
Delimiter, Marker, Prefix, NextMarker, Key
Type: String
ETag The entity tag is an MD5 hash of the object. The ETag reflects only
changes to the contents of an object, not its metadata.
Type: String
Type: String
IsTruncated Specifies whether (true) or not (false) all of the results were returned.
If the number of results exceeds that specified by MaxKeys, all of the
results might not be returned.
Type: Boolean
Type: String
Type: Date
Marker Indicates where in the bucket listing begins. Marker is included in the
response if it was sent with the request.
Type: String
Type: String

140
Name Description
Type: String
NextMarker When the response is truncated (that is, the IsTruncated element
value in the response is true), you can use the key name in this field as
a marker in the subsequent request to get next set of objects. Amazon
S3 lists objects in UTF-8 character encoding in lexicographical order.
Note
This element is returned only if you specify a delimiter
request parameter. If the response does not include the
NextMarker and it is truncated, you can use the value of the
last Key in the response as the marker in the subsequent
request to get the next set of object keys.
Type: String
Owner Bucket owner.
Type: String
Ancestor: ListBucketResult.Contents | CommonPrefixes
Type: String
Type: String
StorageClass The storage class used to store the object.
Type: String

DEEP_ARCHIVE
Special Errors

141
Examples
Sample Request
This request returns the objects in BucketName.
GET / HTTP/1.1
Date: Wed, 12 Oct 2009 17:50:00 GMT
Sample Response

<Name>bucket</Name>
<Prefix/>
<Marker/>
<Contents>
<Size>434234</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>mtd@amazon.com</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>my-third-image.jpg</Key>
<ETag>"1b2cf535f27731c974343645a3985328"</ETag>
<Size>64994</Size>
<StorageClass>STANDARD_IA</StorageClass>
<Owner>
</Owner>
</Contents>
</ListBucketResult>
Sample Request Using Request Parameters

This example lists up to 40 keys in the quotes bucket that start with N and occur lexicographically after
Ned.
GET /?prefix=N&marker=Ned&max-keys=40 HTTP/1.1

Date: Wed, 01 Mar 2006 12:00:00 GMT
Sample Response
HTTP/1.1 200 OK

142
Date: Wed, 01 Mar 2006 12:00:00 GMT
Content-Length: 302
Connection: close
Server: AmazonS3

<Name>quotes</Name>
<Prefix>N</Prefix>
<Marker>Ned</Marker>
<Contents>
<Key>Nelson</Key>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>5</Size>
<Owner>
<ID>bcaf161ca5fb16fd081034f</ID>
</Owner>
</Contents>
<Contents>
<Key>Neo</Key>
<Size>4</Size>
<Owner>
<ID>bcaf1ffd86a5fb16fd081034f</ID>
</Owner>
</Contents>
</ListBucketResult>
Sample Request Using a Prefix and Delimiter

For this example, we assume that you have the following keys in your bucket:
sample.jpg
The following GET request specifies the delimiter parameter with value /.
GET /?delimiter=/ HTTP/1.1

Date: Wed, 01 Mar 2006 12:00:00 GMT
The key sample.jpg does not contain the delimiter character, and Amazon S3 returns it in the
Contents element in the response. However, all other keys contain the delimiter character. Amazon S3
groups these keys and returns 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.

143
<Prefix></Prefix>
<Marker></Marker>
<Contents>
<ETag>"bf1d737a4d46a19f3bced6905cc8b902"</ETag>
<Size>142863</Size>
<Owner>
<ID>canonical-user-id</ID>
<DisplayName>display-name</DisplayName>
</Owner>
</Contents>
<CommonPrefixes>
</CommonPrefixes>
</ListBucketResult>
The following GET request specifies the delimiter parameter with the value /, and the prefix
parameter with the value photos/2006/.
GET /?prefix=photos/2006/&delimiter=/ HTTP/1.1

Date: Wed, 01 Mar 2006 12:00:00 GMT
In response, Amazon S3 returns only the keys that start with the specified prefix. It uses the
delimiter character to group keys that contain the same substring until the first occurrence of the
delimiter character after the specified prefix. For each such key group, Amazon S3 returns one
<CommonPrefixes> element in the response. The keys grouped under this CommonPrefixes element
are not returned elsewhere in the response. The value returned in the CommonPrefixes element is
a substring that starts at the beginning of the key and ends at the first occurrence of the specified
delimiter after the prefix.
<Marker></Marker>
<CommonPrefixes>
</CommonPrefixes>
<CommonPrefixes>
</CommonPrefixes>
</ListBucketResult>
Related Resources

144

145
GET Bucket accelerate
GET Bucket accelerate

Description
This implementation of the GET operation uses the accelerate subresource to return the Transfer
Acceleration state of a bucket, which is either Enabled or Suspended. Amazon S3 Transfer Acceleration
is a bucket-level feature that enables you to perform faster data transfers to and from Amazon S3.
To use this operation, you must have permission to perform the s3:GetAccelerateConfiguration
You set the Transfer Acceleration state of an existing bucket to Enabled or Suspended by using the PUT
Bucket accelerate (p. 257) operation.
A GET accelerate request does not return a state value for a bucket that has no transfer acceleration
state. A bucket has no Transfer Acceleration state, if a state has never been set on the bucket.
This implementation of the GET operation returns the following responses:
• If the transfer acceleration state is set to Enabled on a bucket, the response is:
<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</AccelerateConfiguration>
• If the transfer acceleration state is set to Suspended on a bucket, the response is:
<Status>Suspended</Status>
• If the transfer acceleration state on a bucket has never been set to Enabled or Suspended, the
response is:
<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"/>
For more information on transfer acceleration, see Transfer Acceleration in the Amazon Simple Storage
Requests
Syntax
GET /?accelerate HTTP/1.1
Date: date
4))

146
Responses
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
This implementation of GET returns the following response elements.
Name Description
AccelerateConfiguration Container for the Status response element.
Type: Container
Ancestor: None
Status The transfer acceleration state of the bucket.
Type: Enum
Valid Values: Suspended | Enabled
Ancestor: AccelerateConfiguration
Special Errors
Examples
Example 1: Retrieve the transfer acceleration configuration for a
bucket
The following example shows a GET /?accelerate request to retrieve the transfer acceleration state
of the bucket named examplebucket.

147
Related Resources
GET /?accelerate HTTP/1.1

Date: Mon, 11 Apr 2016 12:00:00 GMT
The following is a sample of the response body (only) that shows bucket transfer acceleration is enabled.
Related Resources
• PUT Bucket accelerate (p. 257)

148
GET Bucket acl
GET Bucket acl

Description
This implementation of the GET operation uses the acl subresource to return the access control list
(ACL) of a bucket. To use GET to return the ACL of the bucket, you must have READ_ACP access to the
bucket. If READ_ACP permission is granted to the anonymous user, you can return the ACL of the bucket
without using an authorization header.
Requests
Syntax
GET /?acl HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
AccessControlList Container for ACL information.
Type: Container
Ancestry: AccessControlPolicy
AccessControlPolicy Container for the response.

149
Responses
Name Description
Type: Container
Ancestry: None
DisplayName Bucket owner's display name. This is returned only if the owner's e-mail
address (or the forum name, if configured) can be determined from the
ID.
Important
This value is only included in the response in the US East
(N. Virginia), US West (N. California), US West (Oregon), Asia
Pacific (Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo),
EU (Ireland), and South America (São Paulo) regions.
Reference.
Type: String
Ancestry: AccessControlPolicy.Owner
Grant Container for Grantee and Permission.
Type: Container
Ancestry: AccessControlPolicy.AccessControlList
Grantee Container for DisplayName and ID of the person being granted

permissions.
Type: Container
Ancestry: AccessControlPolicy.AccessControlList.Grant
ID Bucket owner's ID.
Type: String
Ancestry: AccessControlPolicy.Owner
Owner Container for bucket owner information.
Type: Container
Ancestry: AccessControlPolicy
Permission Permission given to the Grantee for bucket.
Type: String
Valid Values: FULL_CONTROL | WRITE | WRITE_ACP | READ | READ_ACP
Ancestry: AccessControlPolicy.AccessControlList.Grant
Special Errors

150
Examples
Examples
Sample Request
The following request returns the ACL of the specified bucket.
GET ?acl HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
Content-Length: 124
Connection: close
Server: AmazonS3
<Owner>
<DisplayName>CustomersName@amazon.com</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
Related Resources
• GET Bucket Objects (p. 137)

151
GET Bucket analytics
GET Bucket analytics

Description
This implementation of the GET operation returns an analytics configuration (identified by the analytics
configuration ID) from the bucket.
To use this operation, you must have permissions to perform the s3:GetAnalyticsConfiguration
Requests
Syntax
GET /?analytics&id=analytics-configuration-ID HTTP/1.1
Date: date
4))
Request Parameters
This implementation of GET uses the parameter in the following table.
id The ID that identifies the analytics configuration. Limited to Yes

64 characters.
Type: String
Default: None
Request Headers
Request Elements

152
Responses
Responses
Response Headers
Response Elements
The Examples section shows an example of an analytics configuration XML. The following table describes
the XML elements in the analytics configuration returned by the GET request.
Name Description
AnalyticsConfiguration Contains the configuration and any analyses for the analytics filter.
Type: Container
Children: Id, Filter, StorageClassAnalysis
Ancestor: None
And A conjunction (logical AND) of predicates, which is used in evaluating an

analytics filter. The operator must have at least two predicates.
Type: String
Children: Prefix, Tag
Ancestor: Filter
Bucket The Amazon Resource Name (ARN) of the bucket where analytics results
are published.
Type: String
Ancestor: S3BucketDestination
BucketAccountId The ID of the account that owns the destination bucket where the
analytics results are published.
Type: String
DataExport A container used to describe how data related to the storage class
analysis should be exported.
Type: Container
Children: OutputSchemaVersion, Destination
Ancestor: StorageClassAnalysis
Destination Contains information about where to publish the analytics results.
Type: Container
Children: S3BucketDestination

153
Responses
Name Description
Ancestor: DataExport
Filter Specifies an analytics filter. The analytics only includes objects that meet
the filter's criteria.
Type: Container
Children: And
Ancestor: AnalyticsConfiguration
Format Specifies the output format of the analytics results. Currently, Amazon
S3 supports the comma-separated value (CSV) format.
Type: String
Valid values: CSV
Id The ID that identifies the analytics configuration.
Type: String
Key The key for a tag.
Type: String
Ancestor: Tag
OutputSchemaVersion The version of the output schema to use when exporting data. Must be
V_1.
Type: String
Valid values: V_1
Prefix The prefix that an object must have to be included in the analytics
results.
Type: String
Ancestor: And
Prefix The prefix that is prepended to all analytics results.
Type: String

154
Examples
Name Description
StorageClassAnalysis If present, it indicates that data related to access patterns is collected

and made available to analyze the tradeoffs between different storage
classes.
Type: Container
Children: DataExport
S3BucketDestination Contains the bucket ARN, file format, bucket owner (optional), and prefix
(optional) where analytics results are published.
Type: Container
Children: Format, BucketAccountId, Bucket, Prefix
Ancestor: Destination.
Tag The tag to use when evaluating an analytics filter.
Type: Container
Children: Key, Value
Ancestor: And
Value The value for a tag.
Type: String
Ancestor: Tag
Special Errors
Examples
Example: Configure an Analytics Report
The following GET request for the bucket examplebucket returns the inventory configuration with the
ID list1.
GET /?analytics&id=list1 HTTP/1.1

Date: Mon, 31 Oct 2016 12:00:00 GMT
The following is a sample response.
HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A02

155
Related Resources
Date: Mon, 31 Oct 2016 12:00:00 GMT

Server: AmazonS3

<AnalyticsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>list1</Id>
<Filter>
<And>
<Prefix>images/</Prefix>
<Tag>
<Key>dog</Key>
<Value>corgi</Value>
</Tag>
</And>
</Filter>
<StorageClassAnalysis>
<DataExport>
<OutputSchemaVersion>V_1</OutputSchemaVersion>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<BucketAccountId>123456789012</BucketAccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>destination-prefix</Prefix>
</S3BucketDestination>
</Destination>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>
Related Resources

156
GET Bucket cors
GET Bucket cors

Description
Returns the cors configuration information set for the bucket.
To use this operation, you must have permission to perform the s3:GetBucketCORS action. By default,
the bucket owner has this permission and can grant it to others.
To learn more cors, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple Storage Service
Developer Guide.
Requests
Syntax
GET /?cors HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
CORSConfiguration Container for up to 100 CORSRules elements.
Type: Container
Children: CORSRules

157
Responses
Name Description
Ancestor: None
CORSRule A set of origins and methods (cross-origin access that you want to
allow). You can add up to 100 rules to the configuration.
Type: Container
Children: AllowedOrigin, AllowedMethod, MaxAgeSeconds,

ExposeHeader, ID.
Ancestor: CORSConfiguration
AllowedHeader Specifies which headers are allowed in a pre-flight OPTIONS request

through the Access-Control-Request-Headers header. Each
header name specified in the Access-Control-Request-Headers
must have a corresponding entry in the rule. Only the headers that
were requested will be sent back. This element can contain at most
one * wildcard character.
A CORSRule can have at most one MaxAgeSeconds element.
Type: Integer (seconds)
Ancestor: CORSRule
AllowedMethod Identifies an HTTP method that the domain/origin specified in the

rule is allowed to execute.
Each CORSRule must contain at least one AllowedMethod and one

AllowedOrigin element.
Type: Enum (GET, PUT, HEAD, POST, DELETE)
Ancestor: CORSRule
AllowedOrigin One or more response headers that you want customers to be able
to access from their applications (for example, from a JavaScript
XMLHttpRequest object).
Each CORSRule must have at least one AllowedOrigin element.

The string value can include at most one '*' wildcard character, for
example, http://*.example.com". You can also specify only "*" to
allow cross-origin access for all domains/origins.
Type: String
Ancestor: CORSRule
ExposeHeader One or more headers in the response that you want customers to be
able to access from their applications (for example, from a JavaScript
You add one ExposeHeader in the rule for each header.
Type: String
Ancestor: CORSRule

158
Special Errors
Name Description
ID An optional unique identifier for the rule. The ID value can be

up to 255 characters long. The IDs help you find a rule in the
configuration.
Type: String
Ancestor: CORSRule
MaxAgeSeconds The time in seconds that your browser is to cache the preflight
response for the specified resource.
Ancestor: CORSRule
Special Errors
Examples
Example 1: Retrieve cors subresource
The following example gets the cors subresource of a bucket.
Sample Request
GET /?cors HTTP/1.1

Date: Tue, 13 Dec 2011 19:14:42 GMT
Sample Response
HTTP/1.1 200 OK
Date: Tue, 13 Dec 2011 19:14:42 GMT
Server: AmazonS3
Content-Length: 280
<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
<MaxAgeSeconds>3000</MaxAgeSec>
<ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
</CORSRule>
</CORSConfiguration>

159
Related Resources
Related Resources

160
GET Bucket encryption
GET Bucket encryption

Description
This implementation of the GET operation uses the encryption subresource to return the default
encryption configuration for an Amazon S3 bucket. For information about the Amazon S3 default
encryption feature, see Amazon S3 Default Bucket Encryption in the Amazon Simple Storage Service
Developer Guide.
To use this operation, you must have permission to perform the s3:GetEncryptionConfiguration
Requests
Syntax
GET /?encryption HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
ApplyServerSideEncryptionByDefault Container for

setting server-

161
Responses
Name Description
side encryption by
default.
Type: Container
Children:
SSEAlgorithm,
KMSMasterKeyID
Ancestor: Rule
KMSMasterKeyID The AWS KMS

master key ID used
for the SSE-KMS
encryption.
Type: String
Ancestor:
ApplyServerSideEncryptionByDefault
Constraint: Can
only be used when
you set the value
of SSEAlgorithm
as aws:kms. The
default aws/s3 AWS
KMS master key is
used if this element
is absent while the
SSEAlgorithm is
aws:kms.
Rule Container for server-

side encryption
by default
configuration.
Type: Container
Children:
Ancestor:
ServerSideEncryptionConfiguration
ServerSideEncryptionConfiguration Container for

the server-side
encryption by
default configuration
rule.
Type: Container
Children: Rule
Ancestor: None

162
Examples
Name Description
SSEAlgorithm The server-side

encryption algorithm
to use.
Type: String
Valid Values:
AES256, aws:kms
Ancestor:
Constraint: Can
only be used
when you use
ApplyServerSideEncryptionByDefault.
Special Errors
Examples
Example 1: Retrieve the Encryption Configuration for an S3
Bucket
The following example shows a GET /?encryption request.
GET /?encryption HTTP/1.1

Date: Wed, 06 Sep 2017 12:00:00 GMT
The following is a sample of the response.
HTTP/1.1 200 OK
x-amz-id-2: kDmqsuw5FDmgLmxQaUkd9A4NJ/PIiE0c1rAU/ue2Yp60toXs4I5k5fqlwZsA6fV+wJQCzRRwygQ=
x-amz-request-id: 5D8706FCB2673B7D
Date: Wed, 06 Sep 2017 12:00:00 GMT
Transfer-Encoding: chunked
Server: AmazonS3
<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<SSEAlgorithm>aws:kms</SSEAlgorithm>
<KMSMasterKeyID>arn:aws:kms:us-east-1:1234/5678example</KMSMasterKeyID>
</ApplyServerSideEncryptionByDefault>
</Rule>
</ServerSideEncryptionConfiguration>

163
Related Resources
Related Resources

164
GET Bucket Inventory
GET Bucket Inventory

Description
This implementation of the GET operation returns an inventory configuration (identified by the inventory
configuration ID) from the bucket.
To use this operation, you must have permissions to perform the s3:GetInventoryConfiguration
action. The bucket owner has this permission by default and can grant this permission to others. For
more information about permissions, see Permissions Related to Bucket Subresource Operations and
Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple Storage Service
Developer Guide.
Requests
Syntax
GET /?inventory&id=inventory-configuration-ID HTTP/1.1
Date: date
4))
Request Parameters
This implementation of GET uses the parameter in the following table.
id The ID that identifies the inventory configuration. Yes
Type: String
Default: None
Request Headers
Request Elements

165
Responses
Responses
Response Headers
Response Elements
The Examples section shows an example of an inventory configuration XML. The following table
describes the XML elements in the inventory configuration returned by the GET request.
Name Description
AccountId The ID of the account that owns the destination bucket where the
inventory is published.
Although optional, we recommend that the value be set to prevent

problems if the destination bucket ownership changes.
Type: String
Bucket The Amazon Resource Name (ARN) of the bucket where inventory results
are published.
Type: String
Destination Contains information about where to publish the inventory results.
Type: Container
Ancestor: InventoryConfiguration
Encryption Contains the type of server-side encryption used to encrypt the

inventory results.
Type: Container
Children: SSE-KMS, SSE-S3
Field Contains the optional fields that are included in the inventory results.
Multiple Field elements can be contained in OptionalFields.
Type: String
Ancestor: OptionalFields
Valid values: Size, LastModifiedDate, StorageClass, ETag,

IsMultipartUploaded, ReplicationStatus, EncryptionStatus,
ObjectLockRetainUntilDate, ObjectLockMode,
ObjectLockLegalHoldStatus

166
Responses
Name Description
Filter Specifies an inventory filter. The inventory only includes objects that
meet the filter's criteria.
Type: Container
Children: Prefix
Format Specifies the output format of the inventory results. Currently, Amazon
S3 supports the comma-separated values (CSV) format, the Apache
optimized row columnar (ORC) format, and the Apache Parquet
(Parquet) format.
Type: String
Valid values: CSV, ORC, or Parquet
Frequency Specifies how frequently inventory results are produced.
Type: String
Ancestor: Schedule
Valid values: Daily, or Weekly
Id The ID that identifies the inventory configuration.
Type: String
IncludedObjectVersions Object versions to include in the inventory list. If set to All, the list
includes all the object versions, which adds the version-related fields
VersionId, IsLatest, and DeleteMarker to the list. If set to
Current, the list does not contain these version-related fields.
Type: String
Valid values: Current or All
InventoryConfiguration Contains the inventory configuration.
Type: Container
Children: Id, IsEnabled, Filter, Destination, Schedule,

IncludedObjectVersions, and OptionalFields elements.
Ancestor: None

167
Responses
Name Description
IsEnabled Specifies whether the inventory is enabled or disabled. If set to True, an

inventory list is generated. If set to False, no inventory list is generated.
Type: String
Valid values: True or False
KeyId The AWS KMS customer master key (CMK) used to encrypt the inventory
file.
Type: String
Ancestor: SSE-KMS
Valid values: ARN of the CMK
OptionalFields Contains the optional fields.
Type: Container
Children: Field
Prefix The prefix that an object must have to be included in the inventory
results.
Type: String
Ancestor:Filter
Prefix The prefix that is prepended to all inventory results.
Type: String
Schedule Contains the frequency of inventory results generation.
Type: Container
Children: Frequency
SSE-KMS Specifies to use server-side encryption with AWS KMS-managed keys

(SSE-KMS) and contains the key that is used to encrypt the inventory file.
Type: Container
Children: KeyId
Ancestor: Encryption

168
Examples
Name Description
SSE-S3 Specifies to use server-side encryption with Amazon S3-managed keys

(SSE-S3) to encrypt the inventory file.
Type: Container
Valid values: empty
S3BucketDestination Contains the bucket ARN, file format, bucket owner (optional), prefix
where inventory results are published (optional), and the type of server-
side encryption that is used to encrypt the file (optional).
Type: Container
Children: Format, AccountId, Bucket, Prefix, Encryption
Special Errors
Examples
Example: Configure an Inventory Report
The following GET request for the bucket examplebucket returns the inventory configuration with the
ID list1.
GET /?inventory&id=list1 HTTP/1.1

Date: Mon, 31 Oct 2016 12:00:00 GMT
HTTP/1.1 200 OK
Date: Mon, 31 Oct 2016 12:00:00 GMT
Server: AmazonS3

<InventoryConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>report1</Id>
<IsEnabled>true</IsEnabled>
<Destination>
<AccountId>123456789012</AccountId>
<Prefix>prefix1</Prefix>
<SSE-S3/>

169
Related Resources
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<Prefix>myprefix/</Prefix>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
<Field>ObjectLockRetainUntilDate</Field>
<Field>ObjectLockMode</Field>
<Field>ObjectLockLegalHoldStatus</Field>
</OptionalFields>
</InventoryConfiguration>
Related Resources

170
GET Bucket lifecycle
GET Bucket lifecycle

Description
Note
Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name
prefix, one or more object tags, or a combination of both. Accordingly, this section describes
the latest API. The response describes the new filter element that you can use to specify a filter
to select a subset of objects to which the rule applies. If you are still using previous version
of the lifecycle configuration, it works. For related API description, see GET Bucket lifecycle
(Deprecated) (p. 603).
Returns the lifecycle configuration information set on the bucket. For information about lifecycle
configuration, go to Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.
To use this operation, you must have permission to perform the s3:GetLifecycleConfiguration
action. The bucket owner has this permission, by default. The bucket owner can grant this permission to
others. For more information about permissions, see Managing Access Permissions to Your Amazon S3
Resources in the Amazon Simple Storage Service Developer Guide.
Requests
Syntax
GET /?lifecycle HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements

171
Responses
Name Description
And Container for specifying Prefix and Tag based filters.
Child: Prefix and Tag
Type: Container
Ancestor: Filter
AbortIncompleteMultipartUpload Container for specifying when an incomplete multipart

upload becomes eligible for an abort operation.
Child: DaysAfterInitiation
Type: Container
Ancestor: Rule
Date Date when you want Amazon S3 to take the action. For
more information, see Lifecycle Rules: Based on a Specific
Date in the Amazon Simple Storage Service Developer
Guide.
Type: String
Ancestor: Expiration or Transition
Days Specifies the number of days after object creation when

the specific rule action takes effect. The object's eligibility
time is calculated as creation time + the number of days,
and rounding the resulting time to the next day midnight
UTC.
Type: Non-negative Integer when used with Transition,

Positive Integer when used with Expiration
Ancestor: Transition or Expiration
DaysAfterInitiation Specifies the number of days after initiating a multipart

upload when the multipart upload must be completed. If
it does not complete by the specified number of days, it
becomes eligible for an abort operation and Amazon S3
aborts the incomplete multipart upload.
Type: Positive Integer
Ancestor: AbortIncompleteMultipartUpload
Expiration This action specifies a period in the object's lifetime when

Amazon S3 should take the appropriate expiration action.
The expiration action occurs only on objects that are
eligible according to the period specified in the child Date
or Days element. The action Amazon S3 takes depends on
whether the bucket is versioning enabled.
• If versioning has never been enabled on the bucket,

Amazon S3 deletes the only copy of the object
permanently.

172
Responses
Name Description
• Otherwise, if your bucket is versioning-enabled (or
versioning is suspended), the action applies only to the
current version of the object. Buckets with versioning-
enabled or versioning-suspended can have many
versions of the same object, one current version, and
zero or more noncurrent versions.
Instead of deleting the current version, Amazon S3

makes it a noncurrent version by adding a delete marker
as the new current version.
Important
If the state of your bucket is versioning-
suspended, Amazon S3 creates a delete marker
with version ID null. If you have a version with
version ID null, Amazon S3 overwrites that
version.
Note
To set the expiration for noncurrent
objects, you must use the
NoncurrentVersionExpiration action.
Type: Container
Children: Days or Date
Ancestor: Rule
Filter Container element describing one or more filters used

to identify a subset of objects to which the lifecycle rule
applies.
Child: Prefix, Tag, or And (if both prefix and tag are
specified)
Type: String
Ancestor: Rule
ID Unique identifier for the rule. The value cannot be longer

than 255 characters.
Type: String
Ancestor: Rule
Key Tag key.
Type: String
Ancestor: Tag

173
Responses
Name Description
LifecycleConfiguration Container for lifecycle rules. You can add as many as 1000
rules.
Type: Container
Children: Rule
Ancestor: None
ExpiredObjectDeleteMarker On a versioned bucket (a versioning-enabled or

versioning-suspended bucket), this element indicates
whether Amazon S3 will delete any expired object delete
markers in the bucket. For an example, go to Example
8: Specify Expiration Action to Remove Expired Object
Delete Markers in the Amazon Simple Storage Service
Developer Guide.
Type: String
Valid values: true | false (the value false is allowed, but

it is no-op, which means that Amazon S3 does not take
action if the value is false)
Ancestor: Expiration
NoncurrentDays Specifies the number of days that an object is noncurrent

before Amazon S3 can perform the associated action.
For information about calculating noncurrent days, see
Lifecycle Rules Based on the Number of Days in the
Type: Nonnegative Integer when used with

NoncurrentVersionTransition, Positive Integer when
used with NoncurrentVersionExpiration
Ancestor: NoncurrentVersionExpiration or
NoncurrentVersionTransition
NoncurrentVersionExpiration Specifies when noncurrent object versions expire.

Upon expiration, Amazon S3 permanently deletes the
noncurrent object versions.
Set this lifecycle configuration action on a bucket that has

versioning enabled (or suspended) to request that Amazon
S3 delete noncurrent object versions at a specific period in
the object's lifetime.
Type: Container
Children: NoncurrentDays
Ancestor: Rule

174
Responses
Name Description
NoncurrentVersionTransition Container for the transition rule that describes when

noncurrent objects transition to the STANDARD_IA,
ONEZONE_IA, INTELLIGENT_TIERING, GLACIER, or
DEEP_ARCHIVE storage class.
If your bucket is versioning-enabled (or versioning is

suspended), you can set this action to request that
Amazon S3 transition noncurrent object versions at a
specific period in the object's lifetime.
Type: Container
Children: NoncurrentDays and StorageClass
Ancestor: Rule
Prefix Object key prefix identifying one or more objects to which

the rule applies.
Type: String
Ancestor: Filter or And (if you specify Prefix and Tag

child elements in the Filter)
Rule Container for a lifecycle rule.
Type: Container
Ancestor: LifecycleConfiguration
Status If enabled, Amazon S3 executes the rule as scheduled. If it

is disabled, Amazon S3 ignores the rule.
Type: String
Ancestor: Rule
Valid values: Enabled or Disabled
StorageClass Specifies the Amazon S3 storage class to which you want

to transition the object.
Type: String
Ancestor: Transition and NoncurrentVersionTransition
Valid values: GLACIER | STANDARD_IA | ONEZONE_IA |

Tag Container listing the tag key and value used to filter
objects to which the rule applies.
Type: String
Ancestor: Filter

175
Special Errors
Name Description
Transition This action specifies a period in the objects' lifetime when

Amazon S3 should transition them to the STANDARD_IA,
ONEZONE_IA, INTELLIGENT_TIERING, GLACIER,
DEEP_ARCHIVE storage class. When this action is in
effect, what Amazon S3 does depends on whether the
bucket is versioning-enabled.
• If versioning has never been enabled on the bucket,

Amazon S3 transitions the only copy of the object to
the specified storage class.
• If your bucket is versioning-enabled (or versioning is
suspended), Amazon S3 transitions only the current
versions of objects identified in the rule.
Note
A versioning-enabled or versioning-suspended
bucket can contain many versions of
an object. This action has no effect on
noncurrent object versions. To transition
noncurrent objects, you must use the
NoncurrentVersionTransition action.
Type: Container
Children: Days or Date, and StorageClass
Ancestor: Rule
Value Tag key value.
Type: String
Ancestor: Tag
Special Errors
Error Code Description HTTP Status SOAP Fault

Code Code Prefix
The lifecycle configuration does not

NoSuchLifecycleConfiguration 404 Not Client
exist. Found
For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 6).
Examples
Example 1: Retrieve the Lifecycle Subresource
This example is a GET request to retrieve the lifecycle subresource from the specified bucket. The
example response returns the lifecycle configuration.

176
Related Resources
Sample Request

Sample Response
HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4RyTmXa3rPi4hklTXouTf0hccUjo0iCPjz6FnfIutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991C342C575321
Date: Thu, 15 Nov 2012 00:17:23 GMT
Server: AmazonS3
Content-Length: 358

<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ID>Archive and then delete rule</ID>
<Filter>
<Prefix>projectdocs/</Prefix>
</Filter>
<Transition>
<Days>30</Days>
</Transition>
<Transition>
<Days>365</Days>
<StorageClass>GLACIER</StorageClass>
</Transition>
<Expiration>
<Days>3650</Days>
</Expiration>
</Rule>
</LifecycleConfiguration>
Related Resources

177
GET Bucket location
GET Bucket location

Description
This implementation of the GET operation uses the location subresource to return a bucket's region.
You set the bucket's region using the LocationConstraint request parameter in a PUT Bucket
request. For more information, see PUT Bucket (p. 252).
To use this operation in an AWS Identity and Access Management (IAM) policy, you must have
permissions to perform the s3:ListBucket action. The bucket owner has this permission by default
and can grant this permission to others. For more information about permissions, see Permissions
Related to Bucket Operations and Managing Access Permissions to Your Amazon S3 Resources in the
Requests
Syntax
GET /?location HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
LocationConstraint Specifies the region where the bucket resides.
Type: String

178
Name Description
Valid Values: For a list of all the Amazon S3 supported location constraints
by region, see Regions and Endpoints in the AWS General Reference.
Ancestry: None
When the bucket's region is US East (N. Virginia), Amazon S3 returns an empty string for the bucket's
region:
<LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/"/>
Special Errors
Examples
Sample Request
The following request returns the region of the specified bucket.
GET /?location HTTP/1.1

Host: myBucket.s3.amazonaws.com
Date: Tue, 09 Oct 2007 20:26:04 +0000
Sample Response

<LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">EU</LocationConstraint>
Related Resources
Description
This operation retrieves the PublicAccessBlock configuration for an Amazon S3 bucket. In order
to use this operation, you must have the s3:GetBucketPublicAccessBlock permission. For more
information about Amazon S3 permissions, see Specifying Permissions in a Policy in the Amazon Simple
Important
the object) and the bucket owner's account. If the PublicAccessBlock settings are different
between the bucket and the account, Amazon S3 uses the most restrictive combination of the
bucket-level and account-level settings.

179
Requests
Requests
Syntax
GET /<bucket-name>?publicAccessBlock HTTP/1.1
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
PublicAccessBlockConfiguration
Type: Container
Children: BlockPublicAcls, IgnorePublicAcls, BlockPublicPolicy,

Ancestor: None
BlockPublicAcls Specifies whether Amazon S3 will block public access control lists (ACLs) for this
bucket and objects in this bucket.
Type: Boolean

180
Examples
Name Description
IgnorePublicAcls Specifies whether Amazon S3 will ignore public ACLs for this bucket and objects
in this bucket.
Type: Boolean
BlockPublicPolicy Specifies whether Amazon S3 will block public bucket policies for this bucket.
Type: Boolean
Specifies whether Amazon S3 will restrict public bucket policies for this bucket.
Type: Boolean
Special Errors
Examples
Sample Request
The following request gets a bucket PublicAccessBlock configuration.
GET /<bucket-name>?publicAccessBlock HTTP/1.1

Sample Response
HTTP/1.1 200 OK
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

181
Related Resources
Related Resources

182
GET Bucket logging
GET Bucket logging

Note
Logging functionality is currently in beta.
Description
This implementation of the GET operation uses the logging subresource to return the logging status
of a bucket and the permissions users have to view and modify that status. To use GET, you must be the
bucket owner.
Requests
Syntax
GET /?logging HTTP/1.1
Date: date
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
BucketLoggingStatus Container for the response.
Type: Container
Ancestry: None
EmailAddress E-mail address of the person whose logging permissions are displayed.

183
Responses
Name Description
Type: String
Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant.Grantee
Grant Container for Grantee and Permission.
Type: Container
Ancestry: BucketLoggingStatus.LoggingEnabled.TargetGrants
Grantee Container for EmailAddress of the person whose logging permissions

are displayed.
Type: Container
Ancestry: BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant
LoggingEnabled Container for logging information. This element and its children are
present when logging is enabled, otherwise, this element and its children
are absent.
Type: Container
Ancestry: BucketLoggingStatus
Permission Logging permissions assigned to the Grantee for the bucket.
Type: String
Valid Values: FULL_CONTROL | READ | WRITE
Ancestry: BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant
TargetBucket Specifies the bucket whose logging status is being returned. This
element specifies the bucket where server access logs will be delivered.
Type: String
Ancestry: BucketLoggingStatus.LoggingEnabled
TargetGrants Container for granting information.
Type: Container
TargetPrefix Specifies the prefix for the keys that the log files are being stored under.
Type: String
Special Errors

184
Examples
Examples
Sample Request
The following request returns the logging status for mybucket.
GET ?logging HTTP/1.1

Host: mybucket.s3.amazonaws.com
Date: Wed, 25 Nov 2009 12:00:00 GMT
Sample Response Showing an Enabled Logging Status

HTTP/1.1 200 OK
Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<LoggingEnabled>
<TargetBucket>mybucketlogs</TargetBucket>
<TargetPrefix>mybucket-access_log-/</TargetPrefix>
<TargetGrants>
<Grant>
xsi:type="AmazonCustomerByEmail">
<EmailAddress>user@company.com</EmailAddress>
</Grantee>
<Permission>READ</Permission>
</Grant>
</TargetGrants>
</LoggingEnabled>
</BucketLoggingStatus>
Sample Response Showing a Disabled Logging Status

HTTP/1.1 200 OK
Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />
Related Resources
• PUT Bucket logging (p. 306)

185
GET Bucket metrics
GET Bucket metrics

Description
Gets a metrics configuration for the CloudWatch request metrics (specified by the metrics configuration
ID) from the bucket. Note that this doesn't include the daily storage metrics.
To use this operation, you must have permissions to perform the s3:GetMetricsConfiguration
Requests
Syntax
GET /?metrics&id=id HTTP/1.1
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
The Examples section shows an example of a metrics configuration XML. The following table describes
the XML elements in the metrics configuration returned by the GET request.

186
Responses
Name Description
And A conjunction (logical AND) of predicates, which is used in evaluating a

metrics filter. The operator must have at least two predicates, and an
object must match all of the predicates in order for the filter to apply.
Type: Container
Ancestor: Filter
Filter Specifies a metrics configuration filter. The metrics configuration only

includes objects that meet the filter's criteria. A filter must be a prefix, a
tag, or a conjunction (MetricsAndOperator).
Type: Container
Children: And
Ancestor: MetricsConfiguration
Id The ID used to identify the metrics configuration.
Type: String
Key The name of the tag.
Type: String
Ancestor: Tag
MetricsConfiguration An existing metrics configuration for CloudWatch request metrics on

this bucket.
Type: Container
Children: Filter, Id
Ancestor: None
Prefix A string of text used at the beginning of an object key name.
Type: String
Ancestor: And
Tag A key value name pair, used to organize objects by association.
Type: Container
Ancestor: And
Value The value of the tag.
Type: String

187
Examples
Name Description
Ancestor: Tag
Special Errors
Examples
Retrieve a metrics configuration that filters metrics based on a specified prefix.
GET /?metrics&id=Documents HTTP/1.1


Retrieve a metrics configuration that filters metrics based on a specified prefix.
HTTP/1.1 200 OK
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 180

<MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>Documents</Id>
<Filter>
<Prefix>documents/</Prefix>
</Filter>
</MetricsConfiguration>

Retrieve a metrics configuration that enables metrics for objects that start with a particular prefix and
also have specific tags applied.
GET /?metrics&id=ImportantBlueDocuments HTTP/1.1


Retrieve a metrics configuration that enables metrics for objects that start with a particular prefix and
also have specific tags applied.
HTTP/1.1 200 OK

188
Related Resources
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 480

<Id>ImportantBlueDocuments</Id>
<Filter>
<And>
<Tag>
<Key>priority</Key>
<Value>high</Value>
</Tag>
<Tag>
<Key>class</Key>
<Value>blue</Value>
</Tag>
</And>
</Filter>
Related Resources

189
GET Bucket notification
GET Bucket notification

Description
This implementation of the GET operation uses the notification subresource to return the
notification configuration of a bucket.
If notifications are not enabled on the bucket, the operation returns an empty
NotificationConfiguration element.
By default, you must be the bucket owner to read the notification configuration of a bucket. However,
the bucket owner can use a bucket policy to grant permission to other users to read this configuration
with the s3:GetBucketNotification permission.
For more information about setting and reading the notification configuration on a bucket, see Setting
Up Notification of Bucket Events. For more information about bucket policies, see Using Bucket Policies.
Requests
Syntax
GET /?notification HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
CloudFunction Lambda cloud function ARN that Amazon S3 can

invoke when it detects events of the specified type.

190
Responses
Name Description
Type: String
Ancestry: CloudFunctionConfiguration
CloudFunctionConfiguration Container for specifying the AWS Lambda

notification configuration.
Type: Container
Children: An Id, CloudFunction, and one, or more

Event.
Ancestry: NotificationConfiguration
Event Bucket event for which to send notifications.

Note
You can add multiple instance
of QueueConfiguration,
TopicConfiguration, or
CloudFunctionConfiguration to the
Type: String
Valid Values: For a list of supported event types, go

to Configuring Event Notifications in the Amazon
Ancestry: TopicConfiguration and

QueueConfiguration
Filter Container for S3Key, which contains object key

name filtering rules. For information about key name
filtering, go to Configuring Event Notifications in the
Type: Container
Children: S3Key
Ancestor: TopicConfiguration,
QueueConfiguration, or
CloudFunctionConfiguration.
FilterRule Container for key value pair that defines the criteria
for the filter rule.
Container S3Key
Type: Container
Children: Name and Value
Ancestor: S3Key

191
Responses
Name Description
Id Optional unique identifier for

each of the configurations in the
NotificationConfiguration. If you don't
provide, Amazon S3 will assign an ID.
Type: String
Ancestry: TopicConfiguration and

QueueConfiguration
Name Object key name prefix or suffix identifying

one or more objects to which the filtering rule
applies. Maximum prefix length can be up to 1,024
characters. Overlapping prefixes and suffixes are not
supported. For more information, go to Configuring
Event Notifications in the Amazon Simple Storage
Type: String
Ancestor: FilterRule
Valid values: prefix or suffix
NotificationConfiguration Container for specifying the notification

configuration of the bucket. If this element is empty,
notifications are turned off on the bucket.
Type: Container
Children: one or more TopicConfiguration,

QueueConfiguration, and
CloudFunctionConfiguration elements.
Ancestry: None
Queue Amazon SQS queue ARN to which Amazon S3

will publish a message when it detects events of
specified type.
Type: String
Ancestry: TopicConfiguration
QueueConfiguration Container for specifying a configuration when you

want Amazon S3 to publish events to an Amazon
Simple Queue Service (Amazon SQS) queue.
Type: Container
Children: An Id, Topic, and one, or more Event.

192
Examples
Name Description
S3Key Container for object key name prefix and suffix

filtering rules.
Type: Container
Children: One or more FilterRule
Ancestor: Filter
Topic Amazon SNS topic ARN to which Amazon S3

will publish a message when it detects events of
specified type.
Type: String
Ancestry: TopicConfiguration
TopicConfiguration Container for specifying the configuration when you

want Amazon S3 to publish events to an Amazon
Simple Notification Service (Amazon SNS) topic.
Type: Container
Children: An Id, Topic, and one, or more Event.
Value Specifies the object key name prefix or suffix to filter

on.
Type: String
Special Errors
Examples
Sample Request
This request returns the notification configuration on the bucket quotes.s3.amazonaws.com.
GET ?notification HTTP/1.1

Date: Wed, 15 Oct 2014 16:59:03 GMT
Sample Response
This response returns that the notification configuration for the specified bucket.
HTTP/1.1 200 OK

193
Related Resources
Date: Wed, 15 Oct 2014 16:59:04 GMT
Server: AmazonS3
<NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<TopicConfiguration>
<Id>YjVkM2Y0YmUtNGI3NC00ZjQyLWEwNGItNDIyYWUxY2I0N2M4</Id>
<Topic>arn:aws:sns:us-east-1:account-id:s3notificationtopic2</Topic>
<Event>s3:ReducedRedundancyLostObject</Event>
<Event>s3:ObjectCreated:*</Event>
</TopicConfiguration>
</NotificationConfiguration>
Related Resources
• PUT Bucket notification (p. 315)

194
GET Bucket object lock configuration
GET Bucket object lock configuration

Service: Amazon Simple Storage Service
Gets the Object Lock configuration for a bucket. The rule specified in the Object Lock configuration will
be applied by default to every new object placed in the specified bucket.
Request Syntax
GET /?object-lock HTTP/1.1
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization-string> (see Authenticating Requests (AWS Signature Version
4))

The request does not use any URI parameters.
Request Body
Response Syntax
<ObjectLockConfiguration>
<ObjectLockEnabled>string</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Mode>string</Mode>
<Years>integer</Years>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>
Response Elements
For more information about the response elements that this operation returns, see
ObjectLockConfiguration (p. 544).
Related Resources
Locking Objects in the Amazon Simple Storage Service Developer Guide.
GET BucketPolicyStatus
Description
This operation retrieves the policy status for an Amazon S3 bucket, indicating whether the bucket is
public. In order to use this operation, you must have the s3:GetBucketPolicyStatus permission. For

195
Requests
For more information about when Amazon S3 considers a bucket public, see The Meaning of "Public" in
Requests
Syntax
GET /<bucket-name>?policyStatus HTTP/1.1
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
PolicyStatus Container element for bucket policy status.
Type: Container
Children: IsPublic
IsPublic Indicates whether this bucket currently has a public access policy.
Type: Boolean
Ancestor: PolicyStatus

196
Examples
Special Errors
Examples
Sample Request
The following request gets a bucket policy status.
GET /<bucket-name>?policyStatus HTTP/1.1

Sample Response
HTTP/1.1 200 OK
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0
<PolicyStatus>
<IsPublic>TRUE</IsPublic>
</PolicyStatus>
Related Resources

197
GET Bucket Object versions
GET Bucket Object versions

Description
You can use the versions subresource to list metadata about all of the versions of objects in a bucket.
You can also use request parameters as selection criteria to return metadata about a subset of all the
object versions. For more information, see Request Parameters (p. 198).
Note
A 200 OK response can contain valid or invalid XML. Make sure to design your application to
parse the contents of the response and handle it appropriately.
To use this operation, you must have READ access to the bucket.
Requests
Syntax
GET /?versions HTTP/1.1
Date: date
4))
Request Parameters
in a bucket.
delimiter A delimiter is a character that you specify to group keys. All keys No
that contain the same string between the prefix and the first
occurrence of the delimiter are grouped under a single result
element in CommonPrefixes. These groups are counted as
one result against the max-keys limitation. These keys are not
returned elsewhere in the response. Also, see prefix.
Type: String
Default: None
encoding-type Requests Amazon S3 to encode the response and specifies the No

encoding method to use.
An object key can contain any Unicode character; however, XML

1.0 parser cannot parse some characters, such as characters with
an ASCII value from 0 to 10. For characters that are not supported
in XML 1.0, you can add this parameter to request that Amazon S3
encode the keys in the response.
Type: String
Default: None

198
Responses

Valid value: url
key-marker Specifies the key in the bucket that you want to start listing from. No
Also, see version-id-marker.
Type: String
Default: None
max-keys Sets the maximum number of keys returned in the response body. No
The response might contain fewer keys, but will never contain
more. If additional keys satisfy the search criteria, but were not
returned because max-keys was exceeded, the response contains
<isTruncated>true</isTruncated>. To return the additional
keys, see key-marker and version-id-marker.
Type: String
Default: 1000
prefix Use this parameter to select only those keys that begin with the No
specified prefix. You can use prefixes to separate a bucket into
different groupings of keys. (You can think of using prefix to
make groups in the same way you'd use a folder in a file system.)
You can use prefix with delimiter to roll up numerous
objects into a single result under CommonPrefixes. Also, see
delimiter.
Type: String
Default: None
version-id- Specifies the object version you want to start listing from. Also, No
marker see key-marker.
Type: String
Default: None
Valid Values: Valid version ID | Default
Constraint: May not be an empty string
Request Headers
Responses
Response Headers

199
Responses
Response Elements
Name Description
DeleteMarker Container for an object that is a delete marker.
Type: Container
Children: Key, VersionId, IsLatest, LastModified, Owner
Ancestor: ListVersionsResult

Important
Reference.
Type: String
Ancestor: ListVersionsResult.Version.Owner |
ListVersionsResult.DeleteMarker.Owner
XML response.

the following response elements:
KeyMarker, NextKeyMarker, Prefix, Key, and Delimiter.
Type: String
ETag The entity tag is an MD5 hash of the object. The ETag only reflects
changes to the contents of an object, not its metadata.
Type: String
Ancestor: ListVersionsResult.Version
Type: String
Ancestor: ListVersionsResult.Version.Owner |
ListVersionsResult.DeleteMarker.Owner
IsLatest Specifies whether the object is (true) or is not (false) the current
version of an object.
Type: Boolean

200
Responses
Name Description
Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker
IsTruncated A flag that indicates whether (true) or not (false) Amazon S3 returned
all of the results that satisfied the search criteria. If your results were
truncated, you can make a follow-up paginated request using the
NextKeyMarker and NextVersionIdMarker response parameters as
a starting place in another request to return the rest of the results.
Type: Boolean
Type: String
KeyMarker Marks the last Key returned in a truncated response.
Type: String
Type: Date
ListVersionsResult Container for the result.
Type: Container
Children: All elements in the response
MaxKeys Specifies the maximum number of objects to return.
Type: String
Default: 1000
Valid Values: Integers from 1 to 1000, inclusive
Name Bucket owner's name.
Type: String

201
Responses
Name Description
NextKeyMarker When the number of responses exceeds the value of MaxKeys,

NextKeyMarker specifies the first key not returned that satisfies the
search criteria. Use this value for the key-marker request parameter in
a subsequent request.
Type: String
NextVersionIdMarker When the number of responses exceeds the value of MaxKeys,

NextVersionIdMarker specifies the first object version not returned
that satisfies the search criteria. Use this value for the version-id-
marker request parameter in a subsequent request.
Type: String
Owner Bucket owner.
Type: String
Prefix Selects objects that start with the value supplied by this parameter.
Type: String
Type: String
StorageClass Always STANDARD.
Type: String
Version Container for version information.
Type: Container
VersionId Version ID of an object
Type: String

202
Examples
Name Description
VersionIdMarker Marks the last version of the Key returned in a truncated response.
Type: String
Special Errors
Examples
Sample Request
The following request returns all of the versions of all of the objects in the specified bucket.
GET /?versions HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 +0000
4))
Sample Response to GET Versions

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Name>bucket</Name>
<Prefix>my</Prefix>
<KeyMarker/>
<VersionIdMarker/>
<Version>
<VersionId>3/L4kqtJl40Nr8X8gdRQBpUMLUo</VersionId>
<IsLatest>true</IsLatest>
<Size>434234</Size>
<Owner>
</Owner>
</Version>
<DeleteMarker>
<Key>my-second-image.jpg</Key>
<VersionId>03jpff543dhffds434rfdsFDN943fdsFkdmqnh892</VersionId>
<Owner>

203
Examples
</Owner>
</DeleteMarker>
<Version>
<Key>my-second-image.jpg</Key>
<VersionId>QUpfdndhfd8438MNFDN93jdnJFkdmqnh893</VersionId>
<IsLatest>false</IsLatest>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
<Size>166434</Size>
<Owner>
</Owner>
</Version>
<DeleteMarker>
<VersionId>03jpff543dhffds434rfdsFDN943fdsFkdmqnh892</VersionId>
<Owner>
</Owner>
</DeleteMarker>
<Version>
<VersionId>UIORUnfndfhnw89493jJFJ</VersionId>
<ETag>"772cf535f27731c974343645a3985328"</ETag>
<Size>64</Size>
<Owner>
</Owner>
</Version>
</ListVersionsResult>
Sample Request
The following request returns objects in the order they were stored, returning the most recently stored
object first starting with the value for key-marker.
GET /?versions&key-marker=key2 HTTP/1.1

Pragma: no-cache
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
Date: Thu, 10 Dec 2009 22:46:32 +0000
Sample Response
<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>mtp-versioning-fresh</Name>
<Prefix/>
<KeyMarker>key2</KeyMarker>
<VersionIdMarker/>

204
Examples
<Version>
<Key>key3</Key>
<VersionId>I5VhmK6CDDdQ5Pwfe1gcHZWmHDpcv7gfmfc29UBxsKU.</VersionId>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
</Owner>
</Version>
<DeleteMarker>
<Key>sourcekey</Key>
<VersionId>qDhprLU80sAlCFLu2DWgXAEDgKzWarn-HS_JU0TvYqs.</VersionId>
<Owner>
</Owner>
</DeleteMarker>
<Version>
<VersionId>wxxQ7ezLaL5JN2Sislq66Syxxo0k7uHTUpb9qiiMxNg.</VersionId>
<Size>217</Size>
<Owner>
</Owner>
</Version>
Sample Request Using prefix

This example returns objects whose keys begin with source.
GET /?versions&prefix=source HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 +0000
Sample Response
<Prefix>source</Prefix>
<KeyMarker/>
<VersionIdMarker/>
<DeleteMarker>
<Owner>

205
Examples
</Owner>
</DeleteMarker>
<Version>
<Size>217</Size>
<Owner>
</Owner>
</Version>
Sample Request Using key-marker and version-id-marker

Parameters
The following example returns objects starting at the specified key (key-marker) and version ID
(version-id-marker).
GET /?versions&key-marker=key3&version-id-marker=t46ZenlYTZBnj HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 +0000
Sample Response
<Prefix/>
<VersionIdMarker>t46ZenlYTZBnj</VersionIdMarker>
<DeleteMarker>
<Owner>
</Owner>
</DeleteMarker>
<Version>
<Size>217</Size>
<Owner>
</Owner>
</Version>

206
Examples
Sample Request Using key-marker, version-id-marker and max-

keys
The following request returns up to three (the value of max-keys) objects starting with the key specified
by key-marker and the version ID specified by version-id-marker.
GET /?versions&key-marker=key3&version-id-marker=t46Z0menlYTZBnj&max-keys=3
Date: Wed, 28 Oct 2009 22:32:00 +0000
Sample Response
<Prefix/>
<VersionIdMarker>null</VersionIdMarker>
<NextKeyMarker>key3</NextKeyMarker>
<NextVersionIdMarker>d-d309mfjFrUmoQ0DBsVqmcMV15OI.</NextVersionIdMarker>
<Version>
<Key>key3</Key>
<VersionId>8XECiENpj8pydEDJdd-_VRrvaGKAHOaGMNW7tg6UViI.</VersionId>
<Size>217</Size>
<Owner>
</Owner>
</Version>
<Version>
<Key>key3</Key>
<VersionId>d-d309mfjFri40QYukDozqBt3UmoQ0DBsVqmcMV15OI.</VersionId>
<Size>217</Size>
<Owner>
</Owner>
</Version>
Sample Request Using the Delimiter and the Prefix Parameters

Assume you have the following keys in your bucket, example-bucket.
photos/2006/February/sample.jpg
photos/2006/March/sample.jpg

207
Examples
videos/2006/March/sample.wmv
sample.jpg
The following GET versions request specifies the delimiter parameter with value "/".
GET /?versions&delimiter=/ HTTP/1.1

Date: Wed, 02 Feb 2011 20:34:56 GMT
The list of keys from the specified bucket are shown in the following response.
The response returns the sample.jpg key in a <Version> element. However, because all the other keys
contain the specified delimiter, a distinct substring, from the beginning of the key to the first occurrence
of the delimiter, from each of these keys is returned in a <CommonPrefixes> element. The key substrings,
photos/ and videos/, in the <CommonPrefixes> element indicate that there are one or more keys with
these key prefixes.
This is a useful scenario if you use key prefixes for your objects to create a logical folder like structure. In
this case you can interpret the result as the folders photos/ and videos/ have one or more objects.
<Name>mvbucketwithversionon1</Name>
<Prefix></Prefix>
<KeyMarker></KeyMarker>
<VersionIdMarker></VersionIdMarker>
<Version>
<Key>Sample.jpg</Key>
<VersionId>toxMzQlBsGyGCz1YuMWMp90cdXLzqOCH</VersionId>
<ETag>"3305f2cfc46c0f04559748bb039d69ae"</ETag>
<Size>3191</Size>
<Owner>
<ID>852b113e7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc</ID>
</Owner>
</Version>
<CommonPrefixes>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>videos/</Prefix>
</CommonPrefixes>
In addition to the delimiter parameter you can filter results by adding a prefix parameter as shown in
the following request.
GET /?versions&prefix=photos/2006/&delimiter=/ HTTP/1.1

Date: Wed, 02 Feb 2011 19:34:02 GMT

208
Related Resources
In this case the response will include only objects keys that start with the specified prefix. The value
returned in the <CommonPrefixes> element is a substring from the beginning of the key to the first
occurrence of the specified delimiter after the prefix.

<VersionIdMarker></VersionIdMarker>
<Version>
<Key>photos/2006/</Key>
<VersionId>3U275dAA4gz8ZOqOPHtJCUOi60krpCdy</VersionId>
<ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
<Size>0</Size>
<Owner>
</Owner>
</Version>
<CommonPrefixes>
</CommonPrefixes>
<CommonPrefixes>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/March/</Prefix>
</CommonPrefixes>
Related Resources

209
GET Bucket policy
GET Bucket policy

Description
This implementation of the GET operation uses the policy subresource to return the policy of a
bucket, the calling identity must have the GetBucketPolicy permissions on the specified bucket and
belong to the bucket owner's account in order to use this operation.
If you don't have GetBucketPolicy permissions, Amazon S3 returns a 403 Access Denied error. If
you have the correct permissions, but you're not using an identity that belongs to the bucket owner's
Important
Requests
Syntax
GET /?policy HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
The response contains the (JSON) policy of the specified bucket.

210
Examples
Special Errors
Examples
Sample Request
The following request returns the policy of the specified bucket.
GET ?policy HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: Uuag1LuByru9pO4SAMPLEAtRPfTaOFg==
Date: Tue, 04 Apr 2010 20:34:56 GMT
Server: AmazonS3
{
"Version":"2008-10-17",
"Id":"aaaa-bbbb-cccc-dddd",
"Statement" : [
{
"Effect":"Deny",
"Sid":"1",
"Principal" : {
"AWS":["111122223333","444455556666"]
},
"Action":["s3:*"],
"Resource":"arn:aws:s3:::bucket/*"
}
]
}
Related Resources

211
GET Bucket replication
GET Bucket replication

Description
Returns a bucket's replication configuration.
Note
It can take a while for PUT Bucket replication and DELETE Bucket replication
requests to fully propagate. If you submit a GET Bucket replication request soon after
submitting either of those requests, might not return the latest replication configuration.
For information about replication configuration, see Cross-Region Replication (CRR) in the Amazon
This operation requires permissions for the s3:GetReplicationConfiguration action. For more
information about permissions, see Using Bucket Policies and User Policies in the Amazon Simple Storage
Requests
Syntax
GET /?replication HTTP/1.1
Date: date
For more information about authorization, see Authenticating Requests (AWS Signature Version
4) (p. 14).
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements

212
Responses
Element Description
ReplicationConfiguration The container for replication rules.
Type: Container
Children: Rule
Ancestor: None
Rule The container for information about a particular

replication rule.
Type: Container
Ancestor: ReplicationConfiguration
Role The Amazon Resource Name (ARN) of an AWS Identity and

Access Management (IAM) role that Amazon S3 assumes
when replicating objects.
Type: String
Ancestor: Rule
ID The unique identifier for the rule.
Type: String
Ancestor: Rule
Status Whether a rule is enabled. If Status is not set to

Enabled, Amazon S3 ignores the rule
Type: String
Ancestor: Rule
Valid values: Enabled, Disabled.
Prefix The object key name prefix that identifies the objects that
the rule applies to.
Note
If the replication configuration uses the Filter
element instead of Prefix, Amazon S3 returns
the Filter element. For more information about
the Filter element, see the next table.
Type: String
Ancestor: Rule
Destination A container for information about the destination.
Type: Container
Ancestor: Rule
Account The account ID of the owner of the destination bucket. In

a cross-account scenario, if you tell Amazon S3 to change

213
Responses
Element Description
replica ownership to the AWS account that owns the
destination bucket, this is the account ID of the owner of
the destination bucket. For more information, see Cross-
Region Replication Additional Configuration: Change
Replica Owner in the Amazon Simple Storage Service
Developer Guide.
If the owner override option is not set in a replication

configuration, the response does include this element.
Type: String
Ancestor: Destination
Bucket The name of the bucket where Amazon S3 stores replicas

of objects identified by the rule.
Type: String
StorageClass The storage class for replicated objects. This field is

returned only if you set the storage class when you
configured cross-region replication (with PUT Bucket
replication (p. 327)).
Type: String
Valid values: STANDARD | REDUCED_REDUNDANCY

| GLACIER | STANDARD_IA | ONEZONE_IA |
AccessControlTranslation If you set the owner override option in the replication

configuration, Amazon S3 returns this element. It
identifies the owner of the replicas.
If this element isn't present, replicas are owned by the

same AWS account that owns the source object.
Type: String
Owner Identifies the owner of the replicas. Amazon S3 returns

this element only if you configured owner override option,
in a cross-account scenario.
Type: String
Ancestor: AccessControlTranslation
Rule Filter Response Elements

A replication configuration rule can specify a filter to identify a subset of source objects to apply the rule
to. The response can return the following additional elements, which are related to filtering.

214
Responses
Element Description
Filter The container that describes the filters used to identify

the source objects that you want to replicate.
Ancestor: Rule
And The container for the Prefix and one or more Tag
elements. If the And element is present, it includes at
least one child element.
Ancestor: Filter
Prefix The object key prefix that identifies one or more objects
that the rule applies to.
Note
The earlier version of replication configuration
(V1) supported only the key prefix as a rule
filter. In V1, the response returns the Prefix
element as a child of the Rule element.
Amazon S3 supports this behavior for backward
compatibility. For more information, see
Backward Compatibility in the Amazon S3
Developer Guide.
Type: String
Ancestor: Filter, or And (if present), or Rule (if you are

using the earlier version of replication configuration).
Tag A container that provides a tag key and value.
Ancestor: Filter or And (if present)
Key A tag key.
Type: String
Ancestor: Tag
Value A tag value.
Type: String
Ancestor: Tag
If you include the Filter element in a replication configuration, you must also include the
DeleteMarkerReplication and Priority elements. The response also returns those elements.
Element Description
DeleteMarkerReplication A container that describes whether Amazon S3 replicates

the delete markers.
Ancestor: Rule
Status Indicates whether to replicate delete markers.

215
Responses
Element Description
Type: String
Ancestor: DeleteMarkerReplication
Priority If you specify multiple rules with overlapping filters,

identifies the rule priority. For example, if two rules
apply to the same object based on the Filter specified,
then the rule with higher priority supersedes. The
higher the numerical value of this element, the higher
the rule priority. For more information, see Backward
Compatibility in the Amazon S3 Developer Guide.
Type: Integer
Ancestor: Rule
Encryption Response Elements

If a replication configuration specifies replicating objects created with server-side encryption using an
AWS KMS-managed key, the response returns the following additional elements. For more information,
see CRR: Replicating Objects Created with SSE Using AWS KMS-Managed Encryption Keys in the Amazon
Element Description
SourceSelectionCriteria A container that describes additional filters that identify

Type: String
Ancestor: Rule
SseKmsEncryptedObjects A container for the Status element.
Type: String
Ancestor: SourceSelectionCriteria
Status A flag that tells Amazon S3 whether to replicate objects

created with server-side encryption using an AWS KMS-
managed key.
Type: String
Ancestor: SseKmsEncryptedObjects
EncryptionConfiguration A container that provides information about encryption.
Type: String
ReplicaKmsKeyID The AWS KMS Key ID—the Key Amazon Resource Name
(ARN) or Alias ARN—of the destination bucket. Amazon
S3 uses this key to encrypt replicas.
Type: String

216
Special Errors
Element Description
Ancestor: EncryptionConfiguration
Special Errors
Code Code Prefix
There is no replication configuration

NoSuchReplicationConfiguration 404 Not Client
with that name. Found
Examples
Example 1: Retrieve Replication Configuration Information
The following GET request retrieves information about the replication configuration set for the
examplebucket bucket:
GET /?replication HTTP/1.1

Date: Tue, 10 Feb 2015 00:17:21 GMT
The following response shows that replication is enabled on the bucket. The empty prefix indicates that
Amazon S3 will replicate all objects that are created in the examplebucket bucket. The Destination
element identifies the target bucket where Amazon S3 creates the object replicas, and the storage class
(STANDARD_IA) that Amazon S3 uses when creating replicas.
Amazon S3 assumes the specified IAM role to replicate objects on behalf of the bucket owner, which is
the AWS account that created the bucket.
HTTP/1.1 200 OK
x-amz-request-id: 51991C342example
Date: Tue, 10 Feb 2015 00:17:23 GMT
Server: AmazonS3
Content-Length: contentlength

<ReplicationConfiguration>
<Role>arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3</Role>
<Rule>
<ID>rule1</ID>
<Priority>1</Priority>
<DeleteMarkerReplication>
<Status>Disabled</Status>
</DeleteMarkerReplication>
<Filter>
<And>
<Prefix>TaxDocs</Prefix>
<Tag>

217
Related Resources
<Key>key1</Key>
<Value>value1</Value>
</Tag>
<Tag>
<Key>key1</Key>
</Tag>
</And>
</Filter>
<Destination>
<Bucket>arn:aws:s3:::exampletargetbucket</Bucket>
</Destination>
</Rule>
</ReplicationConfiguration>
Related Resources

218
GET Bucket requestPayment
GET Bucket requestPayment

Description
This implementation of the GET operation uses the requestPayment subresource to return the request
payment configuration of a bucket. To use this version of the operation, you must be the bucket owner.
For more information, see Requester Pays Buckets.
Requests
Syntax
GET ?requestPayment HTTP/1.1
Date: Date
Request Parameters
Request Headers
Responses
Response Headers
Response Elements
Name Description
Payer Specifies who pays for the download and request fees.
Type: Enum
Valid Values: Requester | BucketOwner
Ancestor: RequestPaymentConfiguration
RequestPaymentConfiguration Container for Payer.
Type: Container
Special Errors

219
Examples
Examples
Sample Request
The following request returns the payer for the bucket, colorpictures.
GET ?requestPayment HTTP/1.1

Host: colorpictures.s3.amazonaws.com
Date: Wed, 01 Mar 2009 12:00:00 GMT
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
Date: Wed, 01 Mar 2009 12:00:00 GMT
Content-Type: [type]
Content-Length: 0
Connection: close
Server: AmazonS3

<RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Payer>Requester</Payer>
</RequestPaymentConfiguration>
This response shows that the bucket is a Requester Pays bucket, meaning the person requesting a
download from this bucket pays the transfer fees.
Related Resources

220
GET Bucket tagging
GET Bucket tagging

Description
This implementation of the GET operation uses the tagging subresource to return the tag set
associated with the bucket.
To use this operation, you must have permission to perform the s3:GetBucketTagging action. By
Requests
Syntax
GET /?tagging HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
Tagging Contains the TagSet and Tag elements.
Type: Container
Ancestry: None

221
Examples
Name Description
TagSet Contains the tag set.
Type: Container
Ancestry: Tagging
Tag Contains the tag information.
Type: Container
Ancestry: TagSet
Key Name of the tag
Type: String
Ancestry: Tag
Value Value of the tag
Type: String
Ancestry: Tag
Special Errors
• NoSuchTagSetError - There is no tag set associated with the bucket.
Examples
Sample Request
The following request returns the tag set of the specified bucket.
GET ?tagging HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
Sample Response
HTTP/1.1 200 OK
Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3
<Tagging>
<TagSet>
<Tag>
<Key>Project</Key>
<Value>Project One</Value>
</Tag>
<Tag>
<Key>User</Key>

222
Related Resources
<Value>jsmith</Value>
</Tag>
</TagSet>
</Tagging>
Related Resources

223
GET Bucket versioning
GET Bucket versioning

Description
This implementation of the GET operation uses the versioning subresource to return the versioning
state of a bucket. To retrieve the versioning state of a bucket, you must be the bucket owner.
This implementation also returns the MFA Delete status of the versioning state, i.e., if the MFA Delete
status is enabled, the bucket owner must use an authentication device to change the versioning state of
the bucket.
There are three versioning states:
• If you enabled versioning on a bucket, the response is:
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
</VersioningConfiguration>
• If you suspended versioning on a bucket, the response is:
• If you never enabled (or suspended) versioning on a bucket, the response is:
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"/>
Requests
Syntax
GET /?versioning HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements

224
Responses
Responses
Response Headers
Response Elements
Name Description
MfaDelete Specifies whether MFA delete is enabled in the bucket versioning

configuration. This element is only returned if the bucket has
been configured with MfaDelete. If the bucket has never been so
configured, this element is not returned.
Type: Enum
Valid Values: Disabled | Enabled
Ancestor: VersioningConfiguration
Status The versioning state of the bucket.
Type: Enum
VersioningConfiguration Container for the Status response element.
Type: Container
Ancestor: None
Special Errors
Examples
Sample Request
This example returns the versioning state of myBucket.
GET /?versioning HTTP/1.1

Date: Wed, 12 Oct 2009 17:50:00 GMT

225
Related Resources
Sample Response
The following is a sample of the response body (only) that shows bucket versioning is enabled.
Related Resources

226
GET Bucket website
GET Bucket website

Description
This implementation of the GET operation returns the website configuration associated with a bucket.
To host website on Amazon S3, you can configure a bucket as website by adding a website configuration.
For more information about hosting websites, go to Hosting Websites on Amazon S3 in the Amazon
Simple Storage Service Developer Guide .
This GET operation requires the S3:GetBucketWebsite permission. By default, only the bucket owner
can read the bucket website configuration. However, bucket owners can allow other users to read
the website configuration by writing a bucket policy granting them the S3:GetBucketWebsite
permission.
Requests
Syntax
GET /?website HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
The response XML includes same elements that were uploaded when you configured the bucket as
website. For more information, see PUT Bucket website (p. 345).

227
Examples
Examples
Sample Request
This request retrieves website configuration on the specified bucket.
GET ?website HTTP/1.1

Date: Thu, 27 Jan 2011 00:49:20 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:n0Nhek72Ufg/u7Sm5C1dqRLs8XX=
Sample Response
HTTP/1.1 200 OK
x-amz-request-id: 3848CD259D811111
Date: Thu, 27 Jan 2011 00:49:26 GMT
Content-Length: 240
Server: AmazonS3

<WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<IndexDocument>
<Suffix>index.html</Suffix>
</IndexDocument>
<ErrorDocument>
<Key>404.html</Key>
</ErrorDocument>
</WebsiteConfiguration>
Related Resources

228
HEAD Bucket
HEAD Bucket
Description
This operation is useful to determine if a bucket exists and you have permission to access it. The
operation returns a 200 OK if the bucket exists and you have permission to access it. Otherwise, the
operation might return responses such as 404 Not Found and 403 Forbidden.
To use this operation, you must have permissions to perform the s3:ListBucket action. The bucket
owner has this permission by default and can grant this permission to others. For more information
about permissions, see Permissions Related to Bucket Operations and Managing Access Permissions to
Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.
Requests
Syntax
HEAD / HTTP/1.1
Date: date
4))
Request Parameters
Request Elements
Request Headers
Responses
Response Headers
Response Elements
Special Errors

229
Examples
Examples
Sample Request
HEAD / HTTP/1.1
Date: Fri, 10 Feb 2012 21:34:55 GMT
Host: myawsbucket.s3.amazonaws.com
Connection: Keep-Alive
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: JuKZqmXuiwFeDQxhD7M8KtsKobSzWA1QEjLbTMTagkKdBX2z7Il/jGhDeJ3j6s80
x-amz-request-id: 32FE2CEB32F5EE25
Date: Fri, 10 2012 21:34:56 GMT
Server: AmazonS3

230
List Bucket Analytics Configurations
List Bucket Analytics Configurations

Description
This implementation of the GET operation returns a list of analytics configurations for the bucket. You
can have up to 1,000 analytics configurations per bucket.
This operation supports list pagination and does not return more than 100 configurations at a time. You
should always check the IsTruncated element in the response. If there are no more configurations to
list, IsTruncated is set to false. If there are more configurations to list, IsTruncated is set to true,
and there will be a value in NextContinuationToken. You use the NextContinuationToken value to
continue the pagination of the list by passing the value in continuation-token in the request to GET
the next page.
To use this operation, you must have permissions to perform the s3:GetAnalyticsConfiguration
Requests
Syntax
GET /?analytics HTTP/1.1
Date: date
4))
Request Parameters
continuation- When the Amazon S3 response to this API call is truncated (that is, No
token when the IsTruncated response element value is true), the response
also includes the NextContinuationToken element, the value of
which you can use in the next request as the continuation-token
to list the next page. The continuation token is an opaque value that
Amazon S3 understands.
Type: String
Default: None
Request Elements

231
Responses
Request Headers
Responses
Response Headers
Response Elements
Name Description
ContinuationToken The marker that is used as a starting point for this analytics
configuration list response. This value is present if it was sent
in the request.
Type: String
Ancestor: ListBucketAnalyticsConfigurationsResult
IsTruncated Indicates whether the returned list of analytics configurations

is complete. A value of true indicates that the list is not
complete and the NextContinuationToken is provided for
Type: Boolean
Ancestor: ListAnalyticsConfigurationsResult
AnalyticsConfiguration Contains the analytics configuration. For the XML structure,

see GET Bucket analytics (p. 152).
Type: Container
Ancestor: ListAnalyticsConfigurationsResult
The list of analytics configurations for a bucket.

ListAnalyticsConfigurationsResult
Type: Container
NextContinuationToken The marker used to continue an analytics configuration listing

that has been truncated. Use the NextContinuationToken
from a previously truncated list response to continue the
listing. The continuation token is an opaque value that
Type: String
Ancestor: ListBucketAnalyticsConfigurationsResult

232
Examples
Special Errors
Examples
Example 1: Listing Analytics Configurations
The following request returns the analytics configurations in example-bucket.
Sample Request
GET /?analytics HTTP/1.1

x-amz-date: 20160430T233541Z
Sample Response
HTTP/1.1 200 OK
Date: Sat, 30 Apr 2016 23:29:37 GMT
Server: AmazonS3
<ListBucketAnalyticsConfigurationResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<AnalyticsConfiguration>
<Id>list1</Id>
<Filter>
<And>
<Tag>
<Key>dog</Key>
</Tag>
</And>
</Filter>
<DataExport>
<Destination>
</Destination>
</DataExport>
<AnalyticsConfiguration>
<Id>report1</Id>
<Filter>
<And>

233
Related Resources
<Tag>
<Key>dog</Key>
<Value>bulldog</Value>
</Tag>
</And>
</Filter>
<DataExport>
<Destination>
</Destination>
</DataExport>
...

<ContinuationToken>...</ContinuationToken>

<NextContinuationToken>...</NextContinuationToken>
</ListBucketAnalyticsConfigurationResult>
For an example of using the ContinuationToken with a list, see Example 4: Using a Continuation
Token (p. 135).
Related Resources

234
List Bucket Inventory Configurations
List Bucket Inventory Configurations

Description
This implementation of the GET operation returns a list of inventory configurations for the bucket. You
can have up to 1,000 analytics configurations per bucket.
This operation supports list pagination and does not return more than 100 configurations at a time.
Always check the IsTruncated element in the response. If there are no more configurations to list,
IsTruncated is set to false. If there are more configurations to list, IsTruncated is set to true, and
there is a value in NextContinuationToken. You use the NextContinuationToken value to continue
the pagination of the list by passing the value in continuation-token in the request to GET the next
page.
To use this operation, you must have permissions to perform the s3:GetInventoryConfiguration
Requests
Syntax
GET /?inventory HTTP/1.1
Date: date
4))
Request Parameters
continuation- When the Amazon S3 response to this API call is No

token truncated (that is, when the IsTruncated response
element value is true), the response also includes the
NextContinuationToken element. You can use
the value of this element in the next request as the
continuation-token to list the next page. The
continuation token is an opaque value that Amazon S3
understands.
Type: String
Default: None
Request Elements

235
Responses
Request Headers
Responses
Response Headers
Response Elements
Name Description
ContinuationToken The marker that is used as a starting point for this inventory
in the request.
Type: String
Ancestor: ListInventoryConfigurationsResult
IsTruncated Tells whether the returned list of inventory configurations

complete and the NextContinuationToken is provided for
Type: Boolean
InventoryConfiguration Contains the inventory configuration. For the XML structure,

see GET Bucket Inventory (p. 165).
Type: Container
The list of inventory configurations for a bucket.

ListInventoryConfigurationsResult
Type: Container
NextContinuationToken The marker that is used to continue an inventory

configuration listing that has been truncated. Use the
NextContinuationToken from a previously truncated list
response to continue the listing. The continuation token is an
opaque value that Amazon S3 understands.
Type: String

236
Examples
Special Errors
Examples
Example 1: Listing Inventory Configurations
The following request returns the inventory configurations in example-bucket.
Sample Request
GET /?inventory HTTP/1.1

x-amz-date: 20160430T233541Z
Sample Response
HTTP/1.1 200 OK
Date: Sat, 30 Apr 2016 23:29:37 GMT
Connection: close
Server: AmazonS3

<ListInventoryConfigurationsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<InventoryConfiguration>
<Id>report1</Id>
<Destination>
</Destination>
<Schedule>
</Schedule>
<Filter>
<Prefix>prefix/One</Prefix>
</Filter>
<OptionalFields>
<Field>Size</Field>
<Field>ETag</Field>
</OptionalFields>
<Id>report2</Id>

237
Examples
<Destination>
<Bucket>arn:aws:s3:::bucket2</Bucket>
</Destination>
<Schedule>
</Schedule>
<Filter>
<Prefix>prefix/Two</Prefix>
</Filter>
<OptionalFields>
<Field>Size</Field>
<Field>ETag</Field>
</OptionalFields>
<Id>report3</Id>
<Destination>
<Bucket>arn:aws:s3:::bucket3</Bucket>
</Destination>
<Schedule>
</Schedule>
<Filter>
<Prefix>prefix/Three</Prefix>
</Filter>
<OptionalFields>
<Field>Size</Field>
<Field>ETag</Field>
</OptionalFields>
...

<ContinuationToken>...</ContinuationToken>

<NextContinuationToken>...</NextContinuationToken>
</ListBucketAnalyticsConfigurationResult>
</ListInventoryConfigurationsResult>

238
Related Resources
For an example of using the ContinuationToken with a list, see Example 4: Using a Continuation
Token (p. 135).
Related Resources

239
List Bucket Metrics Configurations
List Bucket Metrics Configurations

Description
This implementation of the GET operation returns a list of Amazon CloudWatch metrics configurations
for the bucket. The metrics configurations are only for the request metrics of the bucket and do not
provide information on daily storage metrics. You can have up to 1,000 configurations per bucket.
This operation supports list pagination and does not return more than 100 configurations at a time.
Always check the IsTruncated element in the response. If there are no more configurations to list,
IsTruncated is set to false. If there are more configurations to list, IsTruncated is set to true, and
there is a value in NextContinuationToken. You use the NextContinuationToken value to continue
the pagination of the list by passing the value in continuation-token in the request to GET the next
page.
To use this operation, you must have permissions to perform the s3:GetMetricsConfiguration
For more information about metrics configurations and CloudWatch request metrics, see Monitoring
Metrics with Amazon CloudWatch in the Amazon Simple Storage Service Developer Guide.
Requests
Syntax
GET /?metrics HTTP/1.1
Date: date
4))
Request Parameters
continuation- When the Amazon S3 response to this API call is truncated (that is, No
token when the IsTruncated response element value is true), the response
also includes the NextContinuationToken element. You can use
the value of that element in the next request as the continuation-
token to list the next page. The continuation token is an opaque
value that Amazon S3 understands.
Type: String
Default: None
Request Headers

240
Responses
Request Elements
Responses
Response Headers
Response Elements
Name Description
IsTruncated Tells whether the returned list of metrics configurations

complete, and the NextContinuationToken is provided for
Type: Boolean
Ancestor: ListMetricsConfigurationResult
ContinuationToken The marker that is used as a starting point for this metrics
in the request.
Type: String
NextContinuationToken The marker used to continue a metrics configuration listing

that has been truncated. Use the NextContinuationToken
from a previously truncated list response to continue the
listing. The continuation token is an opaque value that
Type: String
ListMetricsConfigurationsResultThe list of metrics configurations for a bucket.
Type: Container
Examples
Sample Request
GET /?metrics HTTP/1.1

241
Related Resources
Sample Response
HTTP/1.1 200 OK
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 758

<ListMetricsConfigurationsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<MetricsConfiguration>
<Id>EntireBucket</Id>
<Id>Documents</Id>
<Filter>
</Filter>
<Id>BlueDocuments</Id>
<Filter>
<And>
<Tag>
<Key>class</Key>
<Value>blue</Value>
</Tag>
</And>
</Filter>
</ListMetricsConfigurationsResult>
Related Resources

242
List Multipart Uploads
List Multipart Uploads

Description
This operation lists in-progress multipart uploads. An in-progress multipart upload is a multipart upload
that has been initiated using the Initiate Multipart Upload request, but has not yet been completed or
aborted.
This operation returns at most 1,000 multipart uploads in the response. 1,000 multipart uploads is the
maximum number of uploads a response can include, which is also the default value. You can further
limit the number of uploads in a response by specifying the max-uploads parameter in the response. If
additional multipart uploads satisfy the list criteria, the response will contain an IsTruncated element
with the value true. To list the additional multipart uploads, use the key-marker and upload-id-
marker request parameters.
In the response, the uploads are sorted by key. If your application has initiated more than one multipart
upload using the same object key, then uploads in the response are first sorted by key. Additionally,
uploads are sorted in ascending order within each key by the upload initiation time.
For more information on multipart uploads, see Uploading Objects Using Multipart Upload in the
For information on permissions required to use the multipart upload API, see Multipart Upload API and
Permissions in the Amazon Simple Storage Service Developer Guide.
Requests
Syntax
GET /?uploads HTTP/1.1
Date: Date
Request Parameters
delimiter Character you use to group keys. No
All keys that contain the same string between the prefix, if
specified, and the first occurrence of the delimiter after the prefix
are grouped under a single result element, CommonPrefixes.
If you don't specify the prefix parameter, then the substring
starts at the beginning of the key. The keys that are grouped under
CommonPrefixes result element are not returned elsewhere in the
response.
Type: String

An object key can contain any Unicode character; however, XML 1.0
parser cannot parse some characters, such as characters with an ASCII

243
Requests

value from 0 to 10. For characters that are not supported in XML 1.0,
you can add this parameter to request that Amazon S3 encode the
keys in the response.
Type: String
Default: None
Valid value: url
max-uploads Sets the maximum number of multipart uploads, from 1 to 1,000, No

to return in the response body. 1,000 is the maximum number of
uploads that can be returned in a response.
Type: Integer
Default: 1,000
key-marker Together with upload-id-marker, this parameter specifies the No

multipart upload after which listing should begin.
If upload-id-marker is not specified, only the keys

lexicographically greater than the specified key-marker will be
included in the list.
If upload-id-marker is specified, any multipart uploads for a key

equal to the key-marker might also be included, provided those
multipart uploads have upload IDs lexicographically greater than the
specified upload-id-marker.
Type: String
prefix Lists in-progress uploads only for those keys that begin with the No
specified prefix. You can use prefixes to separate a bucket into
different grouping of keys. (You can think of using prefix to make
groups in the same way you'd use a folder in a file system.)
Type: String
upload-id- Together with key-marker, specifies the multipart upload after No

marker which listing should begin. If key-marker is not specified, the
upload-id-marker parameter is ignored. Otherwise, any multipart
uploads for a key equal to the key-marker might be included in the
list only if they have an upload ID lexicographically greater than the
specified upload-id-marker.
Type: String
Request Headers
Request Elements

244
Responses
Responses
Response Headers
This operation uses only response headers that are common to most responses. For more information,
see Common Response Headers (p. 4).
Response Elements
Name Description
ListMultipartUploadsResult Container for the response.
Children: Bucket, KeyMarker, UploadIdMarker,

NextKeyMarker, NextUploadIdMarker, MaxUploads,
Delimiter, Prefix, CommonPrefixes, IsTruncated
Type: Container
Ancestor: None
Bucket Name of the bucket to which the multipart upload was

initiated.
Type: String
Ancestor: ListMultipartUploadsResult
KeyMarker The key at or after which the listing began.
Type: String
UploadIdMarker Upload ID after which listing began.
Type: String
NextKeyMarker When a list is truncated, this element specifies the value that
should be used for the key-marker request parameter in a
subsequent request.
Type: String
NextUploadIdMarker When a list is truncated, this element specifies the value

that should be used for the upload-id-marker request
parameter in a subsequent request.
Type: String
Encoding-Type Encoding type used by Amazon S3 to encode object key

names in the XML response.

245
Responses
Name Description
If you specify encoding-type request parameter, Amazon
S3 includes this element in the response, and returns encoded
key name values in the following response elements:
Delimiter, KeyMarker, Prefix, NextKeyMarker, Key.
Type: String
MaxUploads Maximum number of multipart uploads that could have been

included in the response.
Type: Integer
IsTruncated Indicates whether the returned list of multipart uploads

is truncated. A value of true indicates that the list was
truncated. The list can be truncated if the number of
multipart uploads exceeds the limit allowed or specified by
MaxUploads.
Type: Boolean
Upload Container for elements related to a particular multipart

upload. A response can contain zero or more Upload
elements.
Type: Container
Children: Key, UploadId, InitiatorOwner,

StorageClass, Initiated
Key Key of the object for which the multipart upload was
initiated.
Type: Integer
Ancestor: Upload
UploadId Upload ID that identifies the multipart upload.
Type: Integer
Ancestor: Upload

246
Responses
Name Description
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, then this element provides the user
ARN and display name.
Children: ID, DisplayName
Type: Container
Ancestor: Upload
ID If the principal is an AWS account, it provides the Canonical

User ID. If the principal is an IAM User, it provides a user ARN
value.
Type: String
Ancestor: Initiator, Owner
DisplayName Principal's name.
Type: String
Ancestor: Initiator , Owner
Owner Container element that identifies the object owner, after

the object is created. If multipart upload is initiated by an
IAM user, this element provides a the parent account ID and
display name.
Type: Container
Ancestor: Upload
StorageClass The class of storage (STANDARD or REDUCED_REDUDANCY)

that will be used to store the object when the multipart
upload is complete.
Type: String
Ancestor: Upload
Initiated Date and time at which the multipart upload was initiated.
Type: Date
Ancestor: Upload
When a prefix is provided in the request, this field contains

ListMultipartUploadsResult.Prefix
the specified prefix. The result contains only keys starting
with the specified prefix.
Type: String

247
Examples
Name Description
Delimiter Contains the delimiter you specified in the request. If you

don't specify a delimiter in your request, this element is
absent from the response.
Type: String
CommonPrefixes If you specify a delimiter in the request, then the result

returns each distinct key prefix containing the delimiter in
a CommonPrefixes element. The distinct key prefixes are
returned in the Prefix child element.
Type: Container
CommonPrefixes.Prefix If the request does not include the Prefix parameter,

then this element shows only the substring of the key that
precedes the first occurrence of the delimiter character. These
keys are not returned anywhere else in the response.
If the request includes the Prefix parameter, then this

element shows the substring of the key from the beginning to
the first occurrence of the delimiter after the prefix.
Type: String
Ancestor: CommonPrefixes
Examples
Sample Request
The following request lists three multipart uploads. The request specifies the max-uploads request
parameter to set the maximum number of multipart uploads to return in the response body.
GET /?uploads&max-uploads=3 HTTP/1.1

Date: Mon, 1 Nov 2010 20:34:56 GMT
Sample Response
The following sample response indicates that the multipart upload list was truncated and provides
the NextKeyMarker and the NextUploadIdMarker elements. You specify these values in
your subsequent requests to read the next set of multipart uploads. That is, send a subsequent
request specifying key-marker=my-movie2.m2ts (value of the NextKeyMarker element) and
upload-id-marker=YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ (value of the
NextUploadIdMarker).
The sample response also shows a case of two multipart uploads in progress with the same key (my-
movie.m2ts). That is, the response shows two uploads with the same key. This response shows the
uploads sorted by key, and within each key the uploads are sorted in ascending order by the time the
multipart upload was initiated.

248
Examples
HTTP/1.1 200 OK
x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
Date: Mon, 1 Nov 2010 20:34:56 GMT
Server: AmazonS3

<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Bucket>bucket</Bucket>
<UploadIdMarker></UploadIdMarker>
<NextKeyMarker>my-movie.m2ts</NextKeyMarker>
<NextUploadIdMarker>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</NextUploadIdMarker>
<MaxUploads>3</MaxUploads>
<Upload>
<Key>my-divisor</Key>
<UploadId>XMgbGlrZSBlbHZpbmcncyBub3QgaGF2aW5nIG11Y2ggbHVjaw</UploadId>
<Initiator>
<ID>arn:aws:iam::111122223333:user/user1-11111a31-17b5-4fb7-9df5-b111111f13de</ID>
<DisplayName>user1-11111a31-17b5-4fb7-9df5-b111111f13de</DisplayName>
</Initiator>
<Owner>
<DisplayName>OwnerDisplayName</DisplayName>
</Owner>
<Initiated>2010-11-10T20:48:33.000Z</Initiated>
</Upload>
<Upload>
<Key>my-movie.m2ts</Key>
<UploadId>VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</UploadId>
<Initiator>
<ID>b1d16700c70b0b05597d7acd6a3f92be</ID>
<DisplayName>InitiatorDisplayName</DisplayName>
</Initiator>
<Owner>
</Owner>
</Upload>
<Upload>
<Key>my-movie.m2ts</Key>
<UploadId>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</UploadId>
<Initiator>
<ID>arn:aws:iam::444455556666:user/user1-22222a31-17b5-4fb7-9df5-b222222f13de</ID>
<DisplayName>user1-22222a31-17b5-4fb7-9df5-b222222f13de</DisplayName>
</Initiator>
<Owner>
</Owner>
</Upload>
</ListMultipartUploadsResult>

249
Examples
Sample Request Using the Delimiter and the Prefix Parameters

Assume you have a multipart upload in progress for the following keys in your bucket, example-
bucket.
photos/2006/February/sample.jpg
photos/2006/March/sample.jpg
videos/2006/March/sample.wmv
sample.jpg
The following list multipart upload request specifies the delimiter parameter with value "/".
GET /?uploads&delimiter=/ HTTP/1.1

Date: Mon, 1 Nov 2010 20:34:56 GMT
The following sample response lists multipart uploads on the specified bucket, example-bucket.
The response returns multipart upload for the sample.jpg key in an <Upload> element.
However, because all the other keys contain the specified delimiter, a distinct substring, from the
beginning of the key to the first occurrence of the delimiter, from each of these keys is returned in a
<CommonPrefixes> element. The key substrings, photos/ and videos/, in the <CommonPrefixes>
element indicate that there are one or more in-progress multipart uploads with these key prefixes.
This is a useful scenario if you use key prefixes for your objects to create a logical folder like structure. In
this case you can interpret the result as the folders photos/ and videos/ have one or more multipart
uploads in progress.
<Bucket>example-bucket</Bucket>
<KeyMarker/>
<UploadIdMarker/>
<NextKeyMarker>sample.jpg</NextKeyMarker>
<NextUploadIdMarker>Xgw4MJT6ZPAVxpY0SAuGN7q4uWJJM22ZYg1W99trdp4tpO88.PT6.MhO0w2E17eutfAvQfQWoajgE_W2gp
</NextUploadIdMarker>
<Prefix/>
<Upload>
<UploadId>Agw4MJT6ZPAVxpY0SAuGN7q4uWJJM22ZYg1N99trdp4tpO88.PT6.MhO0w2E17eutfAvQfQWoajgE_W2gpcxQw--
</UploadId>
<Initiator>
<ID>314133b66967d86f031c7249d1d9a80249109428335cd0ef1cdc487b4566cb1b</ID>
<DisplayName>s3-nickname</DisplayName>
</Initiator>
<Owner>
<ID>314133b66967d86f031c7249d1d9a80249109428335cd0ef1cdc487b4566cb1b</ID>
<DisplayName>s3-nickname</DisplayName>
</Owner>

250
Related Actions
</Upload>
<CommonPrefixes>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>videos/</Prefix>
</CommonPrefixes>
In addition to the delimiter parameter you can filter results by adding a prefix parameter as shown in
the following request.
GET /?uploads&delimiter=/&prefix=photos/2006/ HTTP/1.1

Date: Mon, 1 Nov 2010 20:34:56 GMT
In this case the response will include only multipart uploads for keys that start with the specified prefix.
The value returned in the <CommonPrefixes> element is a substring from the beginning of the key to the
first occurrence of the specified delimiter after the prefix.

<KeyMarker/>
<UploadIdMarker/>
<NextKeyMarker/>
<NextUploadIdMarker/>
<CommonPrefixes>
</CommonPrefixes>
<CommonPrefixes>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/March/</Prefix>
</CommonPrefixes>
Related Actions
• Initiate Multipart Upload (p. 512)
• Upload Part (p. 528)
• Complete Multipart Upload (p. 506)
• Abort Multipart Upload (p. 504)
• List Parts (p. 522)

251
PUT Bucket
PUT Bucket
Description
This implementation of the PUT operation creates a new bucket. To create a bucket, you must register
with Amazon S3 and have a valid AWS Access Key ID to authenticate requests. Anonymous requests are
never allowed to create buckets. By creating the bucket, you become the bucket owner.
Not every string is an acceptable bucket name. For information on bucket naming restrictions, see
Working with Amazon S3 Buckets.
By default, the bucket is created in the US East (N. Virginia) region. You can optionally specify a region in
the request body. You might choose a region to optimize latency, minimize costs, or address regulatory
requirements. For example, if you reside in Europe, you will probably find it advantageous to create
buckets in the EU (Ireland) region. For more information, see How to Select a Region for Your Buckets.
Note
If you create a bucket in a region other than US East (N. Virginia) region, your application
must be able to handle 307 redirect. For more information, go to Virtual Hosting of Buckets in
When creating a bucket using this operation, you can optionally specify the accounts or groups that
should be granted specific permissions on the bucket. There are two ways to grant the appropriate
permissions using the request headers.
• Specify a canned ACL using the x-amz-acl request header. For more information, see Canned ACL in
• Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-write, x-amz-
grant-read-acp, x-amz-grant-write-acp, x-amz-grant-full-control headers. These
headers map to the set of permissions Amazon S3 supports in an ACL. For more information, go to
Access Control List (ACL) Overview in the Amazon Simple Storage Service Developer Guide.
Note
You can use either a canned ACL or specify access permissions explicitly. You cannot do both.
Requests
Syntax
PUT / HTTP/1.1
Date: date
4))
<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<LocationConstraint>BucketRegion</LocationConstraint>
</CreateBucketConfiguration>
Note
The syntax shows some of the request headers. For a complete list, see the Request Headers
section.
Note
If you send your create bucket request to the s3.amazonaws.com endpoint, the request go
to the us-east-1 region. Accordingly, the signature calculations in Signature Version 4 must

252
Requests
use us-east-1 as region, even if the location constraint in the request specifies another region
where the bucket is to be created.
Request Parameters
Request Headers
This implementation of the operation can use the following request headers in addition to the request
headers common to all operations. Request headers are limited to 8 KB in size. For more information, see
Common Request Headers (p. 2).
When creating a bucket, you can grant permissions to individual AWS accounts or predefined groups
defined by Amazon S3. This results in creation of the Access Control List (ACL) on the bucket. For more
information, see Using ACLs. You have the following two ways to grant these permissions:
• Specify a canned ACL — Amazon S3 supports a set of predefined ACLs, known as canned ACLs. Each
canned ACL has a predefined set of grantees and permissions. For more information, go to Canned
ACL.
x-amz-acl The canned ACL to apply to the bucket you are creating. For more No
information, go to Canned ACL in the Amazon Simple Storage
Type: String
Valid Values: private | public-read | public-read-

write | aws-exec-read | authenticated-read |
bucket-owner-read | bucket-owner-full-control
• Specify access permissions explicitly — If you want to explicitly grant access permissions to specific
AWS accounts or groups, you use the following headers. Each of these headers maps to specific
permissions Amazon S3 supports in an ACL. For more information, go to Access Control List (ACL)
Overview. In the header value, you specify a list of grantees who get the specific permission
x-amz-grant- Allows grantee to list the objects in the bucket. No

read
Type: String
Default: None
Constraints: None
x-amz-grant- Allows grantee to create, overwrite, and delete any object in the No
write bucket.
Type: String
Default: None
Constraints: None

253
Requests
x-amz-grant- Allows grantee to read the bucket ACL. No

read-acp
Type: String
Default: None
Constraints: None
x-amz-grant- Allows grantee to write the ACL for the applicable bucket. No
write-acp
Type: String
Default: None
Constraints: None
x-amz-grant- Allows grantee the READ, WRITE, READ_ACP, and WRITE_ACP No

full-control permissions on the bucket.
Type: String
Default: None
Constraints: None
You specify each grantee as a type=value pair, where the type can be one of the following::
• emailAddress — if value specified is the email address of an AWS account

• id — if value specified is the canonical user ID of an AWS account
• uri — if granting permission to a predefined group.
For example, the following x-amz-grant-read header grants list objects permission to the AWS
accounts identified by their email addresses.
x-amz-grant-read: emailAddress="xyz@amazon.com", emailAddress="abc@amazon.com"
For more information see, ACL Overview.
Request Elements
CreateBucketConfiguration Container for bucket configuration settings. No
Type: Container
Ancestor: None
LocationConstraint Specifies the region where the bucket will be No

created. If you are creating a bucket on the US East
(N. Virginia) region (us-east-1), you do not need to
specify the location constraint.
Type: Enum

254
Examples

Valid Values: For a list of all the Amazon S3
supported location constraints by region, see
Regions and Endpoints in the AWS General
Reference.
Default: US East (N. Virginia) region
Ancestor: CreateBucketConfiguration
Response Elements
Special Errors
Examples
Sample Request
This request creates a bucket named colorpictures.
PUT / HTTP/1.1
Content-Length: 0
Date: Wed, 01 Mar 2006 12:00:00 GMT
Sample Response
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2006 12:00:00 GMT
Location: /colorpictures
Content-Length: 0
Connection: close
Server: AmazonS3
Sample Request: Setting the region of a bucket

The following request sets the region the bucket to EU.
PUT / HTTP/1.1
Host: bucketName.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 124

255
Related Resources
<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<LocationConstraint>EU</LocationConstraint>
</CreateBucketConfiguration >
Sample Response
Sample Request: Creating a bucket and configuring access
permission using a canned ACL
This request creates a bucket named "colorpictures" and sets the ACL to private.
PUT / HTTP/1.1
Content-Length: 0
x-amz-acl: private
Date: Wed, 01 Mar 2006 12:00:00 GMT
Sample Response
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2006 12:00:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3
Sample Request: Creating a bucket and configuring access

permissions explicitly
This request creates a bucket named colorpictures and grants WRITE permission to the AWS account
identified by an email address.
PUT HTTP/1.1
x-amz-date: Sat, 07 Apr 2012 00:54:40 GMT
x-amz-grant-write: emailAddress="xyz@amazon.com", emailAddress="abc@amazon.com"
Sample Response
HTTP/1.1 200 OK
Related Resources

256
PUT Bucket accelerate
PUT Bucket accelerate

Description
This implementation of the PUT operation uses the accelerate subresource to set the Transfer
Acceleration state of an existing bucket. Amazon S3 Transfer Acceleration is a bucket-level feature that
enables you to perform faster data transfers to Amazon S3.
To use this operation, you must have permission to perform the s3:PutAccelerateConfiguration
The Transfer Acceleration state of a bucket can be set to one of the following two values:
• Enabled – Enables accelerated data transfers to the bucket.

• Suspended – Disables accelerated data transfers to the bucket.
The GET Bucket accelerate (p. 146) operation returns the transfer acceleration state of a bucket.
After setting the Transfer Acceleration state of a bucket to Enabled, it might take up to thirty minutes
before the data transfer rates to the bucket increase.
The name of the bucket used for Transfer Acceleration must be DNS-compliant and must not contain
periods (".").
For more information about transfer acceleration, see Transfer Acceleration in the Amazon Simple
Requests
Syntax
PUT /?accelerate HTTP/1.1
Date: date
4))
Transfer acceleration configuration in the request body
Request Parameters
Request Headers

257
Responses
Request Body
In the request, you specify the acceleration configuration in the request body. The acceleration
configuration is specified as XML. The following is an example of an acceleration configuration used in a
request. The Status indicates whether to set the transfer acceleration state to Enabled or Suspended.
<Status>transfer acceleration state</Status>
The following table describes the XML elements in the acceleration configuration:
AccelerateConfiguration Container for setting the transfer acceleration state. Yes
Type: Container
Children: Status
Ancestor: None
Status Sets the transfer acceleration state of the bucket. Yes
Type: Enum
Valid Values: Enabled | Suspended
Ancestor: AccelerateConfiguration
Responses
Response Headers
Response Elements
Special Errors
Examples
Example 1: Add Transfer Acceleration Configuration to Set
Acceleration Status
The following is an example of a PUT /?accelerate request that enables transfer acceleration for the
bucket named examplebucket.

258
Related Resources
PUT /?accelerate HTTP/1.1

Date: Mon, 11 Apr 2016 12:00:00 GMT
The following is an example response:
HTTP/1.1 200 OK
Date: Mon, 11 Apr 2016 12:00:00 GMT
Content-Length: 0
Server: AmazonS3
Related Resources
• GET Bucket accelerate (p. 146)

259
PUT Bucket acl
PUT Bucket acl

Description
This implementation of the PUT operation uses the acl subresource to set the permissions on an existing
bucket using access control lists (ACL). For more information, go to Using ACLs. To set the ACL of a
bucket, you must have WRITE_ACP permission.
You can use one of the following two ways to set a bucket's permissions:
• Specify the ACL in the request body

• Specify permissions using request headers
Note
You cannot specify access permission using both the body and the request headers.
Depending on your application needs, you may choose to set the ACL on a bucket using either the
request body or the headers. For example, if you have an existing application that updates a bucket ACL
using the request body, then you can continue to use that approach.
Requests
Syntax
The following request shows the syntax for sending the ACL in the request body. If you want to use
headers to specify the permissions for the bucket, you cannot send the ACL in the request body. Instead,
see Request Headers section for a list of headers you can use.
PUT /?acl HTTP/1.1

Date: date
4))
<Owner>
<ID>ID</ID>
<DisplayName>EmailAddress</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<ID>ID</ID>
</Grantee>
<Permission>Permission</Permission>
</Grant>
...
Request Parameters

260
Requests
Request Headers
You can use the following request headers in addition to the Common Request Headers (p. 2).
These headers enable you to set access permissions using one of the following methods:
• Specify a canned ACL, or

• Specify the permission for each grantee explicitly
Amazon S3 supports a set of predefined ACLs, known as canned ACLs. Each canned ACL has a predefined
set of grantees and permissions. For more information, see Canned ACL. To grant access permissions by
specifying canned ACLs, you use the following header and specify the canned ACL name as its value. If
you use this header, you cannot use other access control specific headers in your request.
x-amz-acl Sets the ACL of the bucket using the specified canned ACL. For No
more information, go to Canned ACL in the Amazon Simple Storage
Type: String
Valid Values: private | public-read | public-read-write |

authenticated-read
Default: private
If you need to grant individualized access permissions on a bucket, you can use the following "x-amz-
grant-permission" headers. When using these headers you specify explicit access permissions and
grantees (AWS accounts or a Amazon S3 groups) who will receive the permission. If you use these ACL
specific headers, you cannot use x-amz-acl header to set a canned ACL.
Note
Each of the following request headers maps to specific permissions Amazon S3 supports in an
ACL. For more information go to Access Control List (ACL) Overview.
x-amz-grant- Allows the specified grantee(s) to list the objects in the bucket. No
read
Type: String
Default: None
Constraints: None
x-amz-grant- Allows the specified grantee(s) to create, overwrite, and delete any No
write object in the bucket.
Type: String
Default: None
Constraints: None
x-amz-grant- Allows the specified grantee(s) to read the bucket ACL. No

read-acp

261
Requests

Type: String
Default: None
Constraints: None
x-amz-grant- Allows the specified grantee(s) to write the ACL for the applicable No
write-acp bucket.
Type: String
Default: None
Constraints: None
x-amz-grant- Allows the specified grantee(s) the READ, WRITE, READ_ACP, and No
full-control WRITE_ACP permissions on the bucket.
Type: String
Default: None
Constraints: None
For each of these headers, the value is a comma-separated list of one or more grantees. You specify each
grantee as a type=value pair, where the type can be one of the following:

• id — if value specified is the canonical User ID of an AWS account
• uri — if granting permission to a predefined Amazon S3 group.
For example, the following x-amz-grant-write header grants create, overwrite, and delete objects
permission to LogDelivery group predefined by Amazon S3 and two AWS accounts identified by their
email addresses.
x-amz-grant-write: uri="http://acs.amazonaws.com/groups/s3/LogDelivery",
emailAddress="xyz@amazon.com", emailAddress="abc@amazon.com"
For more information, go to Access Control List (ACL) Overview. For more information about bucket
logging, go to Server Access Logging.
Request Elements
If you decide to use the request body to specify an ACL, you must use the following elements.
Note
If you request the request body, you cannot use the request headers to set an ACL.
AccessControlList Container for Grant, Grantee, and Permission No
Type: Container
Ancestors: AccessControlPolicy

262
Requests
AccessControlPolicy Contains the elements that set the ACL permissions for an No
object per grantee.
Type: String
Ancestors: None
DisplayName Screen name of the bucket owner. No
Type: String
Ancestors: AccessControlPolicy.Owner
Grant Container for the grantee and his or her permissions. No
Type: Container
Ancestors: AccessControlPolicy.AccessControlList
Grantee The subject whose permissions are being set. For more No
information, see Grantee Values (p. 263).
Type: String
Ancestors:
AccessControlPolicy.AccessControlList.Grant
ID ID of the bucket owner, or the ID of the grantee. No
Type: String
Ancestors: AccessControlPolicy.Owner |
Owner Container for the bucket owner's display name and ID. Yes
Type: Container
Permission Specifies the permission given to the grantee. No
Type: String
Valid Values: FULL_CONTROL | WRITE | WRITE_ACP | READ |

READ_ACP
Ancestors:
Grantee Values
You can specify the person (grantee) to whom you're assigning access rights (using request elements) in
the following ways:
• By the person's ID:

263
Responses
xsi:type="CanonicalUser"><ID><replaceable>ID</replaceable></
ID><DisplayName><replaceable>GranteesEmail</replaceable></DisplayName>
</Grantee>
DisplayName is optional and ignored in the request.

• By Email address:
xsi:type="AmazonCustomerByEmail"><EmailAddress><replaceable>Grantees@email.com</
replaceable></EmailAddress>lt;/Grantee>
The grantee is resolved to the CanonicalUser and, in a response to a GET Object acl request,
appears as the CanonicalUser.
• By URI:
xsi:type="Group"><URI><replaceable>http://acs.amazonaws.com/groups/global/
AuthenticatedUsers</replaceable></URI></Grantee>
Responses
Response Headers
Response Elements
Special Errors
This operation does not return special errors. For general information about Amazon S3 errors and a list
of error codes, see Error Responses (p. 6).
Examples
Sample Request: Access permissions specified in the body
The following request grants access permission to the existing examplebucket bucket. The request
specifies the ACL in the body. In addition to granting full control to the bucket owner, the XML specifies
the following grants.
• Grant AllUsers group READ permission on the bucket.

• Grant the LogDelivery group WRITE permission on the bucket.
• Grant an AWS account, identified by email address, WRITE_ACP permission.
• Grant an AWS account, identified by canonical user ID, READ_ACP permission.
PUT ?acl HTTP/1.1


264
Examples
x-amz-date: Thu, 12 Apr 2012 20:04:21 GMT
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Owner>
<ID>852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID</ID>
</Owner>
<AccessControlList>
<Grant>
<ID>852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID</ID>
</Grantee>
</Grant>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
<URI xmlns="">http://acs.amazonaws.com/groups/global/AllUsers</URI>
</Grantee>
<Permission xmlns="">READ</Permission>
</Grant>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
<URI xmlns="">http://acs.amazonaws.com/groups/s3/LogDelivery</URI>
</Grantee>
<Permission xmlns="">WRITE</Permission>
</Grant>
<Grant>
<EmailAddress xmlns="">xyz@amazon.com</EmailAddress>
</Grantee>
<Permission xmlns="">WRITE_ACP</Permission>
</Grant>
<Grant>
<ID xmlns="">f30716ab7115dcb44a5ef76e9d74b8e20567f63TestAccountCanonicalUserID</ID>
</Grantee>
<Permission xmlns="">READ_ACP</Permission>
</Grant>
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: NxqO3PNiMHXXGwjgv15LLgUoAmPVmG0xtZw2sxePXLhpIvcyouXDrcQUaWWXcOK0
x-amz-request-id: C651BC9B4E1BD401
Date: Thu, 12 Apr 2012 20:04:28 GMT
Content-Length: 0
Server: AmazonS3
Sample Request: Access permissions specified using headers

The following request uses ACL-specific request headers to grant the following permissions:
• Write permission to the Amazon S3 LogDelivery group and an AWS account identified by the email
xyz@amazon.com.

265
Related Resources
• Read permission to the Amazon S3 AllUsers group
PUT ?acl HTTP/1.1

x-amz-date: Sun, 29 Apr 2012 22:00:57 GMT
x-amz-grant-write: uri="http://acs.amazonaws.com/groups/s3/LogDelivery",
emailAddress="xyz@amazon.com"
x-amz-grant-read: uri="http://acs.amazonaws.com/groups/global/AllUsers"
Accept: */*
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: 0w9iImt23VF9s6QofOTDzelF7mrryz7d04Mw23FQCi4O205Zw28Zn+d340/RytoQ
x-amz-request-id: A6A8F01A38EC7138
Date: Sun, 29 Apr 2012 22:01:10 GMT
Content-Length: 0
Server: AmazonS3
Related Resources
• GET Object ACL (p. 383)

266
PUT Bucket analytics
PUT Bucket analytics

Description
This implementation of the PUT operation adds an analytics configuration (identified by the analytics ID)
to the bucket. You can have up to 1,000 analytics configurations per bucket.
You can choose to have storage class analysis export analysis reports to a comma-separated values
(CSV) flat file, see the DataExport request element. Reports are updated daily and are based on the
object filters you configure. When selecting data export you specify a destination bucket and optional
destination prefix where the file is written. You can export the data to a destination bucket in a different
account. However, the destination bucket must be in the same region as the bucket that you are making
the PUT analytics configuration to. For more information, see Amazon S3 Analytics – Storage Class
Analysis in the Amazon Simple Storage Service Developer Guide.
Important
You must create a bucket policy on the destination bucket where the exported file is written
to grant permissions to Amazon S3 to write objects to the bucket. For an example policy, see
Granting Permissions for Amazon S3 Inventory and Storage Class Analysis.
To use this operation, you must have permissions to perform the s3:PutAnalyticsConfiguration
Requests
Syntax
PUT /?analytics&id=configuration-ID HTTP/1.1
Date: date
4))
Analytics configuration in the request body
Request Parameters
This implementation of PUT uses the parameter in the following table.
id The ID identifying the analytics configuration. This ID must Yes

match the request element id. Limited to 64 characters.
Type: String
Default: None

267
Requests
Request Headers
Request Elements
In the request, you must specify the analytics configuration in the request body, which is specified as
XML. The Examples section shows an example of an analytics configuration.
The following table describes the XML elements in the analytics configuration:
Contains the configuration and any analyses for the

AnalyticsConfiguration Yes
analytics filter.
Type: Container
Children: Id, Filter, StorageClassAnalysis
Ancestor: None
And A conjunction (logical AND) of predicates, which is No

used in evaluating an analytics filter. The operator
must have at least two predicates.
Type: String
Ancestor: Filter
Bucket The Amazon Resource Name (ARN) of the bucket Yes

where analytics results are published. This destination
bucket must be in the same region as the bucket used
for the analytics configuration PUT.
Type: String
BucketAccountId The ID of the account that owns the destination No

bucket where the analytics is published.
Although optional, we recommend that the value

be set to prevent problems if the destination bucket
ownership changes.
Type: String
DataExport A container used to describe how data related to the No

storage class analysis should be exported.
Type: Container
Children: OutputSchemaVersion, Destination

268
Requests

Ancestor: StorageClassAnalysis
Destination Contains information about where to publish the Yes

analytics results.
Type: Container
Filter Specifies an analytics filter. The analytics only includes No

objects that meet the filter's criteria. If no filter
is specified, all of the contents of the bucket are
included in the analysis.
Type: Container
Children: And
Format Specifies the output format of the analytics results. Yes

Currently, Amazon S3 supports the comma-separated
value (CSV) format.
Type: String
Valid values: CSV
Id The ID that identifies the analytics configuration. This Yes

ID must match the request parameter id.
Type: String
Key The key for a tag. Yes
Type: String
Ancestor: Tag
OutputSchemaVersionThe version of the output schema to use when Yes

exporting data. Must be V_1.
Type: String
Valid values: V_1

269
Responses
Prefix The prefix that an object must have to be included in No

the analytics results.
Type: String
Ancestor: And
Prefix The prefix that is prepended to all analytics results. No
Type: String
Indicates that data related to access patterns will be

StorageClassAnalysis Yes
collected and made available to analyze the tradeoffs
between different storage classes.
Type: Container
Children: DataExport
S3BucketDestinationContains the bucket ARN, file format, bucket owner Yes

(optional), and prefix (optional) where analytics results
are published.
Type: Container
Children: Format, BucketAccountId, Bucket,

Prefix
Tag The tag to use when evaluating an analytics filter. No
Type: Container
Ancestor: And
Value The value for a tag. Yes
Type: String
Ancestor: Tag
Responses
Response Headers

270
Examples
Response Elements
Special Errors
Amazon S3 checks the validity of the proposed AnalyticsConfiguration element and verifies
whether the proposed configuration is valid when you call the PUT operation. The following table lists
the errors and possible causes.
HTTP Error Code Cause
HTTP 400 Bad InvalidArgument Invalid argument.

Request
HTTP 400 Bad TooManyConfigurations

You are attempting to create a new configuration but have
Request already reached the 1,000-configuration limit.
HTTP 403 AccessDenied You are not the owner of the specified bucket, or you do
Forbidden not have the s3:PutAnalyticsConfiguration bucket
permission to set the configuration on the bucket.
Examples
Example 1: Creating an Analytics Configuration
The following PUT request for the bucket examplebucket creates a new or replaces an existing
analytics configuration with the ID report1. The configuration is defined in the request body.
PUT /?analytics&id=report1 HTTP/1.1

Date: Mon, 31 Oct 2016 12:00:00 GMT

<AnalyticsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>report1</Id>
<Filter>
<And>
<Tag>
<Key>dog</Key>
</Tag>
</And>
</Filter>
<DataExport>
<Destination>

271
Related Resources
</Destination>
</DataExport>
HTTP/1.1 200 OK
Date: Mon, 31 Oct 2016 12:00:00 GMT
Content-Length: 0
Server: AmazonS3
Related Resources

272
PUT Bucket cors
PUT Bucket cors

Description
Sets the cors configuration for your bucket. If the configuration exists, Amazon S3 replaces it.
To use this operation, you must be allowed to perform the s3:PutBucketCORS action. By default, the
bucket owner has this permission and can grant it to others.
You set this configuration on a bucket so that the bucket can service cross-origin requests. For example,
you might want to enable a request whose origin is http://www.example.com to access your Amazon
S3 bucket at my.example.bucket.com by using the browser's XMLHttpRequest capability.
To enable cross-origin resource sharing (CORS) on a bucket, you add the cors subresource to the bucket.
The cors subresource is an XML document in which you configure rules that identify origins and the
HTTP methods that can be executed on your bucket. The document is limited to 64 KB in size. For
example, the following cors configuration on a bucket has two rules:
• The first CORSRule allows cross-origin PUT, POST and DELETE requests whose origin is http://
www.example.com origins. The rule also allows all headers in a pre-flight OPTIONS request through
the Access-Control-Request-Headers header. Therefore, in response to any pre-flight OPTIONS
request, Amazon S3 will return any requested headers.
• The second rule allows cross-origin GET requests from all the origins. The '*' wildcard character refers
to all origins.
<CORSConfiguration>
<CORSRule>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedMethod>DELETE</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
</CORSRule>
<CORSRule>
<AllowedOrigin>*</AllowedOrigin>
</CORSRule>
The cors configuration also allows additional optional configuration parameters as shown in the
following cors configuration on a bucket. For example, this cors configuration allows cross-origin PUT
and POST requests from http://www.example.com.
<CORSConfiguration>
<CORSRule>
<MaxAgeSeconds>3000</MaxAgeSeconds>
</CORSRule>

273
Requests
In the preceding configuration, CORSRule includes the following additional optional parameters:
• MaxAgeSeconds—Specifies the time in seconds that the browser will cache an Amazon S3 response
to a pre-flight OPTIONS request for the specified resource. In this example, this parameter is 3000
seconds. Caching enables the browsers to avoid sending pre-flight OPTIONS request to Amazon S3 for
repeated requests.
• ExposeHeader—Identifies the response header (in this case x-amz-server-side-encryption)
that you want customers to be able to access from their applications (for example, from a JavaScript
When Amazon S3 receives a cross-origin request (or a pre-flight OPTIONS request) against a bucket,
it evaluates the cors configuration on the bucket and uses the first CORSRule rule that matches the
incoming browser request to enable a cross-origin request. For a rule to match, the following conditions
must be met:
• The request's Origin header must match AllowedOrigin elements.

• The request method (for example, GET, PUT, HEAD and so on) or the Access-Control-Request-
Method header in case of a pre-flight OPTIONS request must be one of the AllowedMethod elements.
• Every header specified in the Access-Control-Request-Headers request header of a pre-flight
request must match an AllowedHeader element.
For more information about CORS, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple
Requests
Syntax
PUT /?cors HTTP/1.1
Date: date
4))
Content-MD5: MD5
<CORSConfiguration>
<CORSRule>
<AllowedOrigin>Origin you want to allow cross-domain requests from</AllowedOrigin>
<AllowedOrigin>...</AllowedOrigin>
...
<AllowedMethod>HTTP method</AllowedMethod>
<AllowedMethod>...</AllowedMethod>
...
<MaxAgeSeconds>Time in seconds your browser to cache the pre-flight OPTIONS response
for a resource</MaxAgeSeconds>
<AllowedHeader>Headers that you want the browser to be allowed to send</AllowedHeader>
<AllowedHeader>...</AllowedHeader>
...
<ExposeHeader>Headers in the response that you want accessible from client
application</ExposeHeader>
<ExposeHeader>...</ExposeHeader>
...
</CORSRule>
<CORSRule>
...
</CORSRule>
...

274
Requests
Request Parameters
Request Headers
Content-MD5 The base64-encoded 128-bit MD5 digest of the data. This header Yes
must be used as a message integrity check to verify that the request
body was not corrupted in transit. For more information, go to RFC
1864.
Type: String
Default: None
Request Elements
CORSConfiguration Container for up to 100 CORSRules elements. Yes
Type: Container
Children: CORSRules
Ancestor: None
CORSRule A set of origins and methods (cross-origin access that Yes

you want to allow). You can add up to 100 rules to the
configuration.
Type: Container
Children: AllowedOrigin, AllowedMethod,

MaxAgeSeconds, ExposeHeader, ID.
Ancestor: CORSConfiguration
ID A unique identifier for the rule. The ID value can be up to No

255 characters long. The IDs help you find a rule in the
configuration.
Type: String
Ancestor: CORSRule
AllowedMethod An HTTP method that you want to allow the origin to Yes
execute.
Each CORSRule must identify at least one origin and one

method.
Type: Enum (GET, PUT, HEAD, POST, DELETE)

275
Responses

Ancestor: CORSRule
AllowedOrigin An origin that you want to allow cross-domain requests from. Yes
This can contain at most one * wild character.
Each CORSRule must identify at least one origin and one

method.
The origin value can include at most one '*' wild character. For
example, "http://*.example.com". You can also specify only *
as the origin value allowing all origins cross-domain access.
Type: String
Ancestor: CORSRule
AllowedHeader Specifies which headers are allowed in a pre-flight OPTIONS No

request via the Access-Control-Request-Headers
header. Each header name specified in the Access-
Control-Request-Headers header must have a
corresponding entry in the rule. Amazon S3 will send only the
allowed headers in a response that were requested.
This can contain at most one * wild character.
Type: String
Ancestor: CORSRule
MaxAgeSeconds The time in seconds that your browser is to cache the No

preflight response for the specified resource.
Ancestor: CORSRule
ExposeHeader One or more headers in the response that you want No

customers to be able to access from their applications (for
example, from a JavaScript XMLHttpRequest object).
You add one ExposeHeader element in the rule for each

header.
Type: String
Ancestor: CORSRule
Responses
Response Headers

276
Examples
Response Elements
Special Errors
Examples
The following examples add the cors subresource to a bucket.
Example : Configure cors

Sample Request
The following PUT request adds the cors subresource to a bucket (examplebucket).
PUT /?cors HTTP/1.1

x-amz-date: Tue, 21 Aug 2012 17:54:50 GMT
Content-MD5: 8dYiLewFWZyGgV2Q5FNI4W==
Content-Length: 216
<CORSConfiguration>
<CORSRule>
<MaxAgeSeconds>3000</MaxAgeSec>
</CORSRule>
<CORSRule>
<AllowedOrigin>*</AllowedOrigin>
<MaxAgeSeconds>3000</MaxAgeSeconds>
</CORSRule>
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: CCshOvbOPfxzhwOADyC4qHj/Ck3F9Q0viXKw3rivZ+GcBoZSOOahvEJfPisZB7B
x-amz-request-id: BDC4B83DF5096BBE
Date: Tue, 21 Aug 2012 17:54:50 GMT
Server: AmazonS3
Related Resources

277
Related Resources

278
PUT Bucket encryption
PUT Bucket encryption

Description
This implementation of the PUT operation uses the encryption subresource to set the default
encryption state of an existing bucket.
This implementation of the PUT operation sets default encryption for a buckets using server-side
encryption with Amazon S3-managed keys SSE-S3 or AWS KMS-managed Keys (SSE-KMS) bucket. For
information about the Amazon S3 default encryption feature, see Amazon S3 Default Bucket Encryption
Important
This operation requires AWS Signature Version 4. For more information, see Authenticating
Requests (AWS Signature Version 4) (p. 14).
To use this operation, you must have permissions to perform the s3:PutEncryptionConfiguration
Requests
Syntax
PUT /?encryption HTTP/1.1
Date: date
4))
default encryption configuration in the request body
Request Parameters
Request Headers
Request Body
In the request, you specify the encryption configuration in the request body. The encryption
configuration is specified as XML, as shown in the following examples that show setting encryption using
SSE-S3 or SSE-KMS.
The following is an example of the request body for setting SSE-S3.
<Rule>
<SSEAlgorithm>AES256</SSEAlgorithm>

279
Requests
</Rule>
The following is an example of the request body for setting SSE-KMS.
<Rule>
</Rule>
The following table describes the XML elements in the encryption configuration:
Container for setting server-side encryption by

ApplyServerSideEncryptionByDefault No
default.
Type: Container
Children: SSEAlgorithm, KMSMasterKeyID
Ancestor: Rule
KMSMasterKeyID The AWS KMS master key ID used for the SSE-KMS No
encryption.
Type: String
Ancestor:
Constraint: Can only be used when you set the value

of SSEAlgorithm as aws:kms. The default aws/
s3 AWS KMS master key is used if this element is
absent while the SSEAlgorithm is aws:kms.
Rule Container for server-side encryption by default Yes

configuration.
Type: Container
Children:
Ancestor:
ServerSideEncryptionConfiguration
Container for the server-side encryption by default

ServerSideEncryptionConfiguration Yes
configuration rule.
Type: Container
Children: Rule
Ancestor: None

280
Responses
SSEAlgorithm The server-side encryption algorithm to use. Yes
Type: String
Valid Values: AES256, aws:kms
Ancestor:
Constraint: Can only be used when you use

ApplyServerSideEncryptionByDefault.
Responses
Response Headers
Response Elements
Special Errors
Examples
Example 1: Set the Default Encryption Configuration for an S3
Bucket
The following is an example of a PUT /?encryption request that specifies to use AWS KMS encryption.
PUT /?encryption HTTP/1.1

Date: Wed, 06 Sep 2017 12:00:00 GMT
<Rule>
</Rule>
The following is an example response:
HTTP/1.1 100 Continue

281
Related Resources
HTTP/1.1 200 OK
x-amz-id-2: B3Z1w/R0GaUCDHStDVuoz+4NSndjUDYuE3jvJ5kvrDroucdFCygEQYEwpC0Lj0Cv
x-amz-request-id: E0DE682C2FDDBCF8
Date: Wed, 06 Sep 2017 12:00:00 GMT
Content-Length: 0
Server: AmazonS3
Related Resources

282
PUT Bucket inventory
PUT Bucket inventory

Description
This implementation of the PUT operation adds an inventory configuration (identified by the inventory
ID) to the bucket. You can have up to 1,000 inventory configurations per bucket.
Amazon S3 inventory generates inventories of the objects in the bucket on a daily or weekly basis, and
the results are published to a flat file. The bucket that is inventoried is called the source bucket, and the
bucket where the inventory flat file is stored is called the destination bucket. The destination bucket must
be in the same AWS Region as the source bucket.
When you configure an inventory for a source bucket, you specify the destination bucket where you
want the inventory to be stored, and whether to generate the inventory daily or weekly. You can also
configure what object metadata to include and whether to inventory all object versions or only current
versions. For more information, see Amazon S3 Inventory in the Amazon Simple Storage Service Developer
Guide.
Important
You must create a bucket policy on the destination bucket to grant permissions to Amazon
S3 to write objects to the bucket in the defined location. For an example policy, see Granting
Permissions for Amazon S3 Inventory and Storage Class Analysis.
To use this operation, you must have permissions to perform the s3:PutInventoryConfiguration
action. The bucket owner has this permission by default and can grant this permission to others. For
more information about permissions, see Permissions Related to Bucket Subresource Operations and
Developer Guide.
Requests
Syntax
PUT /?inventory&id=configuration-ID HTTP/1.1
Date: date
4))
Inventory configuration in the request body
Request Parameters
id The ID identifying the inventory configuration. This ID must Yes

match the request element id. Limited to 64 characters.
Type: String
Default: None

283
Requests
Request Headers
Request Elements
In the request, you must specify the inventory configuration in the request body, which is specified as
XML. The Examples section shows an example of an inventory configuration.
The following table describes the XML elements in the inventory configuration:
AccountId The ID of the account that owns the destination No

bucket.
Although optional, we recommend that the value

be set to prevent problems if the destination bucket
ownership changes.
Type: String

where inventory results are published. This destination
bucket must be in the same AWS Region as the source
bucket.
Type: String
Destination Contains information about where to publish the Yes

inventory results.
Type: Container
Encryption Contains the type of server-side encryption to use to No

encrypt the inventory.
Type: Container
Children: SSE-KMS, SSE-S3
Field Contains the optional fields that are included in the No

inventory results. Multiple Field elements can be
contained in OptionalFields.
Type: String
Ancestor: OptionalFields

284
Requests

Valid values: Size, LastModifiedDate,
StorageClass, ETag, IsMultipartUploaded,
ReplicationStatus, EncryptionStatus,
ObjectLockRetainUntilDate, ObjectLockMode,
Filter Specifies an inventory filter. The inventory only No

includes objects that meet the filter's criteria. If no
filter is specified, all of the contents of the bucket are
inventoried.
Type: Container
Children: Prefix
Format Specifies the output format of the inventory results. Yes

Currently, Amazon S3 supports the comma-separated
values (CSV) format, the Apache optimized row
columnar (ORC) format, and the Apache Parquet
(Parquet) format.
Type: String
Valid values: CSV, ORC, or Parquet
Frequency Specifies how frequently inventory results are Yes

produced.
Type: String
Ancestor: Schedule
Valid values: Daily, or Weekly
Id The ID identifying the inventory configuration. This ID Yes

must match the request parameter id.
Type: String
Ancestor:InventoryConfiguration
Specifies which object versions to include in the

IncludedObjectVersions Yes
inventory results. If set to All, the list includes all of
the object versions, which adds the version-related
fields VersionId, IsLatest, and DeleteMarker
to the list. If set to Current, the list does not contain
these version-related fields.
Type: String
Valid values: Current or All

285
Requests
Contains the inventory configuration.

InventoryConfiguration Yes
Type: Container
Children: Id, IsEnabled, Filter, Destination,

Schedule, IncludedObjectVersions, and
OptionalFields elements.
Ancestor: None
IsEnabled Specifies whether the inventory is enabled or disabled. Yes
If set to True, inventory results are generated. If set to

False, no inventory is generated.
Type: String
Valid values: True or False
KeyId The AWS KMS customer master key (CMK) used to No

encrypt the inventory file.
Type: String
Ancestor: SSE-KMS
Valid values: ARN of the CMK
OptionalFields Contains the optional fields that are included in the No

inventory results.
Type: Container
Children: Field

the inventory results.
Type: String
Ancestor: Filter
Prefix The prefix that is prepended to all inventory results. No
Type: String

286
Responses
Schedule Contains the frequency for generating inventory Yes

results.
Type: Container
Children: Frequency
SSE-KMS Specifies to use server-side encryption with AWS KMS- No

managed keys (SSE-KMS) and contains the key that is
used to encrypt the inventory file.
Type: Container
Children: KeyId
SSE-S3 Specifies to use server-side encryption with Amazon No

S3-managed keys (SSE-S3) to encrypt the inventory
file.
Type: Container
Valid values: empty
S3BucketDestinationContains the bucket ARN, file format, bucket owner Yes

(optional), prefix where inventory results are published
(optional), and the type of server-side encryption that
is used to encrypt the file (optional).
Type: Container
Children: Format, AccountId, Bucket, Prefix,

Encryption
Responses
Response Headers
Response Elements

287
Examples
Special Errors
Amazon S3 checks the validity of the proposed InventoryConfiguration element and verifies
HTTP 400 Bad InvalidArgument Invalid argument.

Request

HTTP 403 AccessDenied You are not the owner of the specified bucket, or you do
Forbidden not have the s3:PutInventoryConfiguration bucket
permission to set the configuration on the bucket.
Examples
Example 1: Creating an Inventory Configuration
The following PUT request for the bucket examplebucket creates a new or replaces an existing
inventory configuration with the ID report1. The configuration is defined in the request body.
PUT /?inventory&id=report1 HTTP/1.1

Date: Mon, 31 Oct 2016 12:00:00 GMT

<InventoryConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>report1</Id>
<Filter>
<Prefix>filterPrefix/</Prefix>
</Filter>
<Destination>
<Encryption>
<SSE-KMS>
<KeyId>arn:aws:kms:us-
west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab</KeyId>
</SSE-KMS>
</Encryption>
</Destination>
<Schedule>
</Schedule>

288
Related Resources
<OptionalFields>
<Field>Size</Field>
<Field>ETag</Field>
<Field>EncryptionStatus</Field>
</OptionalFields>
HTTP/1.1 200 OK
Date: Mon, 31 Oct 2016 12:00:00 GMT
Content-Length: 0
Server: AmazonS3
Related Resources

289
PUT Bucket lifecycle
PUT Bucket lifecycle

Description
Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration. For
information about lifecycle configuration, go to Object Lifecycle Management in the Amazon Simple
Note
Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name
prefix, one or more object tags, or a combination of both. Accordingly, this section describes the
latest API. The previous version of the API supported filtering based only on an object key name
prefix, which is supported for backward compatibility. For the related API description, see PUT
Bucket lifecycle (Deprecated) (p. 593).
Permissions
By default, all Amazon S3 resources are private, including buckets, objects, and related subresources
(for example, lifecycle configuration and website configuration). Only the resource owner (that is,
the AWS account that created it) can access the resource. The resource owner can optionally grant
access permissions to others by writing an access policy. For this operation, a user must get the
s3:PutLifecycleConfiguration permission.
You can also explicitly deny permissions. Explicit deny also supersedes any other permissions. If you want
to block users or accounts from removing or deleting objects from your bucket, you must deny them
permissions for the following actions:
• s3:DeleteObject
• s3:DeleteObjectVersion
• s3:PutLifecycleConfiguration
For more information about permissions, see Managing Access Permissions to Your Amazon S3 Resources
Requests
Syntax
PUT /?lifecycle HTTP/1.1
Date: date
Content-MD5: MD5
Lifecycle configuration in the request body
For details about authorization string, see Authenticating Requests (AWS Signature Version
4) (p. 14).
Request Parameters

290
Requests
Request Headers
Content-MD5 The base64-encoded 128-bit MD5 digest of the Yes

data. This header must be used as a message
integrity check to verify that the request body was
not corrupted in transit. For more information, see
RFC 1864.
Type: String
Default: None
Request Body
You specify the lifecycle configuration in your request body. The lifecycle configuration is specified as
XML consisting of one or more rules.
<LifecycleConfiguration>
<Rule>
...
</Rule>
<Rule>
...
</Rule>
…
Each rule consists of the following:
• Filter identifying a subset of objects to which the rule applies. The filter can be based on a key name
prefix, object tags, or a combination of both.
• Status whether the rule is in effect.
• One or more lifecycle transition and expiration actions that you want Amazon S3 to perform on
the objects identified by the filter. If the state of your bucket is versioning-enabled or versioning-
suspended, you can have many versions of the same object (one current version and zero or more
noncurrent versions). Amazon S3 provides predefined actions that you can specify for current and
noncurrent object versions.
For example,
<Rule>
<Filter>
<Prefix>key-prefix</Prefix>
</Filter>
<Status>rule-status</Status>
One or more Transition/Expiration lifecycle actions.
</Rule>
For more information, see Object Lifecycle Management in the Amazon Simple Storage Service Developer
Guide.

291
Requests
For more information, see Lifecycle Configuration Elements in the Amazon Simple Storage Service
Developer Guide.
The following table describes the XML elements in the lifecycle configuration:
Container for specifying when an incomplete

AbortIncompleteMultipartUpload Yes, if no
multipart upload becomes eligible for an abort other action
operation. is specified
for the rule.
When you specify this lifecycle action, the rule
cannot specify a tag-based filter.
For more information, see Lifecycle Configuration

Elements in the Amazon Simple Storage Service
Developer Guide.
Type: Container
Ancestor: Rule.
And Container for specify rule filters. These filters Yes, if you
determine the subset of objects to which the rule specify
applies. more than
one filter
Type: String condition
(for
Ancestor: Rule example,
one prefix
and one or
more tags).
Date Date when you want Amazon S3 to take the Yes, if

action. For more information, see Lifecycle Rules: Days and
Based on a Specific Date in the Amazon Simple ExpiredObjectDeleteMa
Storage Service Developer Guide. are absent.
The date value must conform to the ISO 8601

format. The time is always midnight UTC.
Type: String
Days Specifies the number of days after object creation Yes, if

when the specific rule action takes effect. Date and
ExpiredObjectDeleteMa
Type: Nonnegative Integer when used with are absent.
Transition, Positive Integer when used with
Expiration.
Ancestor: Expiration, Transition.
DaysAfterInitiation Specifies the number of days after initiating a Yes, if

multipart upload when the multipart upload ancestor is
must be completed. If it does not complete by specified.
the specified number of days, it becomes eligible

292
Requests

for an abort operation and Amazon S3 aborts the
incomplete multipart upload.
Type: Positive Integer.
Ancestor:
AbortIncompleteMultipartUpload.
Expiration This action specifies a period in an object's Yes, if no

lifetime when Amazon S3 should take the other action
appropriate expiration action. The action Amazon is present in
S3 takes depends on whether the bucket is the Rule.
versioning-enabled.
• If versioning has never been enabled on the

bucket, Amazon S3 deletes the only copy of the
object permanently.
• Otherwise, if your bucket is versioning-enabled
(or versioning is suspended), the action applies
only to the current version of the object. A
versioning-enabled bucket can have many
versions of the same object, one current
version, and zero or more noncurrent versions.
Instead of deleting the current version, Amazon

S3 makes it a noncurrent version by adding a
delete marker as the new current version.
Important
If your bucket state is versioning-
suspended, Amazon S3 creates a
delete marker with version ID null.
If you have a version with version ID
null, then Amazon S3 overwrites that
version.
Note
To set expiration for noncurrent
NoncurrentVersionExpiration
action.
Type: Container
Ancestor: Rule

293
Requests
Filter Container for elements that describe the filter Yes

identifying a subset of objects to which the
lifecycle rule applies. If you specify an empty
filter (<Filter></Filter>), the rule applies to
all objects in the bucket.
Type: String
Children: Prefix, Tag
Ancestor: Rule
ID Unique identifier for the rule. The value cannot No

be longer than 255 characters.
Type: String
Ancestor: Rule
Key Specifies the key of a tag. A tag key can be up to Yes, if <Tag>
128 Unicode characters in length. parent is
specified.
Tag keys that you specify in a lifecycle rule filter
must be unique.
For more information, see Object Tagging in the

Type: String
Ancestor: Tag
LifecycleConfiguration Container for lifecycle rules. You can add as many Yes
as 1,000 rules.
Type: Container
Children: Rule
Ancestor: None

294
Requests
ExpiredObjectDeleteMarker On a versioned bucket (versioning-enabled or Yes, if Date

versioning-suspended bucket), you can add and Days
this element in the lifecycle configuration to are absent.
direct Amazon S3 to delete expired object
delete markers. For an example, see Example 7:
Removing Expired Object Delete Markers in the
On a nonversioned bucket, adding this element
in a policy is meaningless because you cannot
have delete markers and the element doesn't do
anything.
For more information, see Lifecycle Configuration

Elements in the Amazon Simple Storage Service
Developer Guide.
When you specify this lifecycle action, the rule

cannot specify a tag-based filter.
Type: String
Valid values: true | false (the value false is

allowed, but it is no-op and Amazon S3 does not
take action if the value is false)
Ancestor: Expiration.
NoncurrentDays Specifies the number of days an object is Yes

noncurrent before Amazon S3 can perform
the associated action. For information about
the noncurrent days calculations, see How
Amazon S3 Calculates When an Object Became
Noncurrent in the Amazon Simple Storage Service
Developer Guide.
Type: Nonnegative Integer when used

with NoncurrentVersionTransition,
Positive Integer when used with
NoncurrentVersionExpiration.

295
Requests
NoncurrentVersionExpiration Specifies when noncurrent object versions expire. Yes, if no

Upon expiration, Amazon S3 permanently deletes other action
the noncurrent object versions. is present in
the Rule.
You set this lifecycle configuration action
on a bucket that has versioning enabled (or
suspended) to request that Amazon S3 delete
noncurrent object versions at a specific period in
the object's lifetime.
Type: Container
Ancestor: Rule
NoncurrentVersionTransition Container for the transition rule that Yes, if no

describes when noncurrent objects transition other action
to the STANDARD_IA, ONEZONE_IA, is present in
INTELLIGENT_TIERING, GLACIER or the Rule.
If your bucket is versioning-enabled (or versioning

is suspended), you can set this action to request
that Amazon S3 transition noncurrent object
versions at a specific period in the object's
lifetime.
Type: Container
Ancestor: Rule
Prefix Object key prefix identifying one or more No

objects to which the rule applies. Empty prefix
(<Prefix></Prefix>) indicates there is no filter
based on key prefix.
There can be at most one Prefix in a lifecycle

rule Filter.
Type: String
Ancestor: Filter or And (if you specify multiple

filters such as a prefix and one or more tags).
Rule Container for a lifecycle rule. A lifecycle Yes

configuration can contain as many as 1,000 rules.
Type: Container
Ancestor: LifecycleConfiguration

296
Requests
Status If Enabled, Amazon S3 executes the rule as Yes

scheduled. If Disabled, Amazon S3 ignores the
rule.
Type: String
Ancestor: Rule
Valid values: Enabled, Disabled.
StorageClass Specifies the Amazon S3 storage class to which Yes

you want the object to transition.
This element
Type: String is required
only if you
Ancestor: Transition and specify one
NoncurrentVersionTransition or both its
ancestors.
Valid values: GLACIER | STANDARD_IA |
ONEZONE_IA | INTELLIGENT_TIERING |
DEEP_ARCHIVE
Tag Container for specifying a tag key and value. Each No

tag has a key and a value.
Type: Container
Children: Key and Value
Ancestor: Filter or And (if you specify multiple

filters such as a prefix and one or more tags).

297
Responses
Transition This action specifies a period in the objects' Yes, if no

lifetime when Amazon S3 should transition other action
them to the STANDARD_IA, ONEZONE_IA, is present in
INTELLIGENT_TIERING, GLACIER, or the the Rule.
DEEP_ARCHIVE storage class. When this action
is in effect, what Amazon S3 does depends on
whether the bucket is versioning-enabled.

bucket, Amazon S3 transitions the only copy of
the object to the specified storage class.
• Otherwise, when your bucket is versioning-
enabled (or versioning is suspended), Amazon
S3 transitions only the current versions of
objects identified in the rule.
Note
A versioning-enabled bucket can have
many versions of an object. This action
has no impact on the noncurrent
object versions. To transition
action.
Type: Container
Ancestor: Rule
Value Specifies the value for a tag key. Each object tag Yes, if <Tag>
is a key-value pair. parent is
specified.
Tag value can be up to 256 Unicode characters in
length.
Type: String
Ancestor: Tag
Responses
Response Headers
Response Elements

298
Examples
Special Errors
Examples
Example 1: Add lifecycle configuration - bucket not versioning-
enabled
The following lifecycle configuration specifies two rules, each with one action.
• The Transition action requests Amazon S3 to transition objects with the "documents/" prefix to the
GLACIER storage class 30 days after creation.
• The Expiration action requests Amazon S3 to delete objects with the "logs/" prefix 365 days after
creation.
<Rule>
<ID>id1</ID>
<Filter>
</Filter>
<Transition>
<Days>30</Days>
</Transition>
</Rule>
<Rule>
<ID>id2</ID>
<Filter>
<Prefix>logs/</Prefix>
</Filter>
<Expiration>
<Days>365</Days>
</Expiration>
</Rule>
The following is a sample PUT /?lifecycle request that adds the preceding lifecycle configuration to
the examplebucket bucket.

x-amz-date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Content-Length: 415
<Rule>
<ID>id1</ID>
<Filter>

299
Examples
</Filter>
<Transition>
<Days>30</Days>
</Transition>
</Rule>
<Rule>
<ID>id2</ID>
<Filter>
</Filter>
<Expiration>
<Days>365</Days>
</Expiration>
</Rule>
HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E
Date: Wed, 14 May 2014 02:11:22 GMT
Content-Length: 0
Server: AmazonS3
Example 2: Add lifecycle configuration - bucket is versioning-

enabled
The following lifecycle configuration specifies two rules, each with one action for Amazon S3 to perform.
You specify these actions when your bucket is versioning-enabled or versioning is suspended:
• The NoncurrentVersionExpiration action requests Amazon S3 to expire noncurrent versions of

objects with the "logs/" prefix 100 days after the objects become noncurrent.
• The NoncurrentVersionTransition action requests Amazon S3 to transition noncurrent versions
of objects with the "documents/" prefix to the GLACIER storage class 30 days after they become
noncurrent.
<LifeCycleConfiguration>
<Rule>
<ID>DeleteAfterBecomingNonCurrent</ID>
<Filter>
</Filter>
<NoncurrentVersionExpiration>
<NoncurrentDays>100</NoncurrentDays>
</NoncurrentVersionExpiration>
</Rule>
<Rule>
<ID>TransitionAfterBecomingNonCurrent</ID>
<Filter>
</Filter>
<NoncurrentVersionTransition>

300
Related Resources
</NoncurrentVersionTransition>
</Rule>
</LifeCycleConfiguration>

Content-MD5: 96rxH9mDqVNKkaZDddgnw==
Content-Length: 598
<Rule>
<Filter>
</Filter>
</Rule>
<Rule>
<ID>TransitionSoonAfterBecomingNonCurrent</ID>
<Filter>
</Filter>
</Rule>
HTTP/1.1 200 OK
x-amz-id-2: aXQ+KbIrmMmoO//3bMdDTw/CnjArwje+J49Hf+j44yRb/VmbIkgIO5A+PT98Cp/6k07hf+LD2mY=
x-amz-request-id: 02D7EC4C10381EB1
Date: Wed, 14 May 2014 02:21:50 GMT
Content-Length: 0
Server: AmazonS3
Additional Examples
Lifecycle configuration topic in the developer guide provides additional examples. For more information,
go to Examples of Lifecycle Configuration.
Related Resources

301
Description
This operation creates or modifies the PublicAccessBlock configuration for an Amazon S3 bucket.
In order to use this operation, you must have the s3:PutBucketPublicAccessBlock permission. For
Important
the object) and the bucket owner's account. If the PublicAccessBlock configurations are
different between the bucket and the account, Amazon S3 uses the most restrictive combination
of the bucket-level and account-level settings.
Requests
Syntax
PUT /<bucket-name>?publicAccessBlock HTTP/1.1
4))
Request Parameters
Request Headers
Request Elements
This operation uses the following request elements. You can enable BlockPublicAcls,
IgnorePublicAcls, BlockPublicPolicy, and RestrictPublicBuckets in any combination.
PublicAccessBlockConfiguration Yes
Type: Container
Children: BlockPublicAcls, IgnorePublicAcls,

BlockPublicPolicy, RestrictPublicBuckets
BlockPublicAcls Specifies whether Amazon S3 should block public access control No

lists (ACLs) for this bucket. Setting this element to TRUE causes the
following behavior:

302
Requests

• PUT Bucket acl (p. 260) and PUT Object acl (p. 467) calls fail if the
specified ACL is public.
• PUT Object (p. 434) calls fail if the request includes a public ACL.
Important
Type: Boolean
IgnorePublicAclsSpecifies whether Amazon S3 should ignore public ACLs for this No

bucket. Setting this element to TRUE causes Amazon S3 to ignore all
public ACLs on this bucket and any objects that it contains.
Important
Enabling this setting doesn't affect the persistence of any
existing ACLs and doesn't prevent new public ACLs from
being set.
Type: Boolean
Specifies whether Amazon S3 should block public bucket policies for

BlockPublicPolicy No
this bucket. Setting this element to TRUE causes Amazon S3 to reject
calls to PUT Bucket policy (p. 325) if the specified policy allows
public access.
Important
Type: Boolean
Specifies whether Amazon S3 should restrict public bucket policies for

RestrictPublicBuckets No
this bucket. If this element is set to TRUE, then only AWS services and
authorized users within the bucket owner's account can access this
bucket if it has a public bucket policy.
Important
Enabling this setting doesn't affect previously stored bucket
policies, except that public and cross-account access within
any public bucket policy, including non-public delegation to
specific accounts, is blocked.
Type: Boolean

303
Responses
Responses
Response Headers
Response Elements
Special Errors
Examples
The following request puts a bucket PublicAccessBlock configuration that rejects public ACLs.



HTTP/1.1 200 OK
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

The following request puts a bucket PublicAccessBlock configuration that ignores public ACLs and
restricts access to public buckets.


304
Related Resources
<BlockPublicAcls>FALSE</BlockPublicAcls>
<IgnorePublicAcls>TRUE</IgnorePublicAcls>
<RestrictPublicBuckets>TRUE</RestrictPublicBuckets>

HTTP/1.1 200 OK
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0
Related Resources

305
PUT Bucket logging
PUT Bucket logging

Description
This implementation of the PUT operation uses the logging subresource to set the logging parameters
for a bucket and to specify permissions for who can view and modify the logging parameters. All logs are
saved to buckets in the same AWS Region as the source bucket. To set the logging status of a bucket, you
must be the bucket owner.
The bucket owner is automatically granted FULL_CONTROL to all logs. You use the Grantee request
element to grant access to other people. The Permissions request element specifies the kind of access
the grantee has to the logs.
To enable logging, you use LoggingEnabled and its children request elements. To disable logging, you
use an empty BucketLoggingStatus request element:
For more information about server access logging, see Server Access Logging in the Amazon Simple
For more information about creating a bucket, see PUT Bucket (p. 252). For more information about
returning the logging status of a bucket, see GET Bucket logging (p. 183).
Requests
Syntax
PUT /?logging HTTP/1.1
Date: date
4))
Request elements vary depending on what you're setting.
Request Parameters
Request Headers
Request Elements
BucketLoggingStatus Container for logging status information. Yes
Type: Container
Children: LoggingEnabled

306
Requests

Ancestry: None
EmailAddress Email address of the person being granted logging No

permissions.
Type: String
Children: None
Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant.Grantee
Grant Container for the grantee and his/her logging permissions. No
Type: Container
Children: Grantee, Permission
Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants
Grantee Container for EmailAddress of the person being granted No

logging permissions. For more information, see Grantee
Values (p. 308).
Type: Container
Children: EmailAddress
Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant
LoggingEnabled Container for logging information. This element is present No

when you are enabling logging (and not present when you are
disabling logging).
Type: Container
Children: Grant, TargetBucket, TargetPrefix
Ancestry: BucketLoggingStatus
Permission Logging permissions given to the Grantee for the bucket. The No
bucket owner is automatically granted FULL_CONTROL to all
logs delivered to the bucket. This optional element enables
you to grant access to others.
Type: String
Children: None
Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant

307
Requests
TargetBucket Specifies the bucket where you want Amazon S3 to store No

server access logs, which is the target bucket. The bucket
that's being logged is the source bucket. The target bucket
can be any bucket that you own that is in the same Region
as the source bucket, including the source bucket itself. You
can also configure multiple buckets to deliver their logs to the
same target bucket. In this case, you should choose a different
TargetPrefix for each source bucket so that the delivered
log files can be distinguished by key.
Type: String
Children: None
TargetGrants Container for granting information. No
Type: Container
Children: Grant, Permission
TargetPrefix This element lets you specify a prefix for the keys that the log Yes,
files will be stored under. if the
TargetBucket
Type: String element
is
Children: None specified.
Grantee Values
the following ways:
</Grantee>

• By URI:

308
Responses
Responses
Response Headers
Response Elements
Special Errors
Examples
Sample Request
This request enables logging and gives the grantee of the bucket READ access to the logs.
PUT ?logging HTTP/1.1

Content-Length: 214
Date: Wed, 25 Nov 2009 12:00:00 GMT

<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<LoggingEnabled>
<TargetBucket>mybucketlogs</TargetBucket>
<TargetPrefix>mybucket-access_log-/</TargetPrefix>
<TargetGrants>
<Grant>
<EmailAddress>user@company.com</EmailAddress>
</Grantee>
</Grant>
</TargetGrants>
</LoggingEnabled>
Sample Response
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2006 12:00:00 GMT

309
Related Resources
Sample Request Disabling Logging

This request disables logging on the bucket, quotes.
PUT ?logging HTTP/1.1

Content-Length: 214
Date: Wed, 25 Nov 2009 12:00:00 GMT

Sample Response
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2006 12:00:00 GMT
Related Resources
• GET Bucket logging (p. 183)
PUT Bucket metrics

Description
Sets or updates a metrics configuration for the CloudWatch request metrics (specified by the metrics
configuration ID) from the bucket. You can have up to 1,000 metrics configurations per bucket. If you're
updating an existing metrics configuration, note that this is a full replacement of the existing metrics
configuration. If you don't include the elements you want to keep, they are erased.
To use this operation, you must have permissions to perform the s3:PutMetricsConfiguration
Requests
Syntax
PUT /?metrics&id=id HTTP/1.1
Date: date

310
Requests

4))
Metrics configuration in the request body.
Request Parameters
Request Headers
Request Elements
In the request, you must specify the metrics configuration in the request body, which is specified as XML.
The Examples section shows an example of a metrics configuration.
The following table describes the XML elements in the metrics configuration:
And A conjunction (logical AND) of predicates, which is No

used in evaluating a metrics filter. The operator must
have at least two predicates in any combination, and
an object must match all of the predicates for the
filter to apply.
Type: Container
Ancestor: Filter
Filter Specifies a metrics configuration filter. The metrics No

configuration includes only objects that meet the
filter's criteria. A filter must be a prefix, a tag, or a
conjunction (And). There's a limit of 11 predicates for
each filter, of which there can be one prefix and up to
ten tags in a single filter.
Type: Container
Children: And
Id The ID used to identify the metrics configuration. Yes
Type: String
Key The name of the tag. No

311
Responses

Type: String
Ancestor: Tag
Specifies the metrics configuration for CloudWatch

MetricsConfiguration Yes
request metrics on this bucket.
Type: Container
Ancestor: None

the metrics results.
Type: String
Ancestor: And
Tag A key-value name pair, used to organize objects by No

association.
Type: Container
Children: Key, Value,
Ancestor: And
Value The value of the tag. No
Type: String
Ancestor: Tag
Responses
Response Headers
Response Elements
Special Errors
Amazon S3 checks the validity of the proposed MetricsConfiguration element and verifies whether
the proposed configuration is valid when you call the PUT operation. The following table lists the errors
and possible causes.


312
Examples
Examples
Put a metric configuration that enables metrics for an entire bucket.
PUT /?metrics&id=EntireBucket HTTP/1.1

Content-Length: 159

<Id>EntireBucket</Id>

Put a metric configuration that enables metrics for an entire bucket.

Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3

Put a metrics configuration that enables metrics for objects that start with a particular prefix and also
have specific tags applied.
PUT /?metrics&id=ImportantBlueDocuments HTTP/1.1

Content-Length: 480

<Id>ImportantBlueDocuments</Id>
<Filter>
<And>
<Tag>
<Key>priority</Key>
<Value>high</Value>
</Tag>
<Tag>
<Key>class</Key>
<Value>blue</Value>
</Tag>
</And>
</Filter>

313
Related Resources

Put a metrics configuration that enables metrics for objects that start with a particular prefix and also
have specific tags applied.

Date: Thu, 15 Nov 2016 00:17:29 GMT
Server: AmazonS3
Related Resources

314
PUT Bucket notification
PUT Bucket notification

Description
The Amazon S3 notification feature enables you to receive notifications when certain events happen in
your bucket. For more information about event notifications, go to Configuring Event Notifications in the
Using this API, you can replace an existing notification configuration. The configuration is an XML file
that defines the event types that you want Amazon S3 to publish and the destination where you want
Amazon S3 to publish an event notification when it detects an event of the specified type.
By default, your bucket has no event notifications configured. That is, the notification configuration will
be an empty NotificationConfiguration.
<NotificationConfiguration>
This operation replaces the existing notification configuration with the configuration you include in the
request body.
After Amazon S3 receives this request, it first verifies that any Amazon Simple Notification Service
(Amazon SNS) or Amazon Simple Queue Service (Amazon SQS) destination exists, and that the bucket
owner has permission to publish to it by sending a test notification. In the case of AWS Lambda
destinations, Amazon S3 verifies that the Lambda function permissions grant Amazon S3 permission to
invoke the function from the Amazon S3 bucket. For more information, go to Configuring Notifications
for Amazon S3 Events in the Amazon Simple Storage Service Developer Guide.
You can disable notifications by adding the empty NotificationConfiguration element.
By default, only the bucket owner can configure notifications on a bucket. However, bucket
owners can use a bucket policy to grant permission to other users to set this configuration with
s3:PutBucketNotification permission.
Note
The PUT notification is an atomic operation. For example, suppose your notification
configuration includes SNS topic, SQS queue, and Lambda function configurations. When
you send a PUT request with this configuration, Amazon S3 sends test messages to your SNS
topic. If the message fails, the entire PUT operation will fail, and Amazon S3 will not add the
configuration to your bucket.
Requests
Syntax
PUT /?notification HTTP/1.1
Date: date
4))
<Id>ConfigurationId</Id>
<Filter>
<S3Key>
<FilterRule>

315
Requests
<Name>prefix</Name>
<Value>prefix-value</Value>
</FilterRule>
<FilterRule>
<Name>suffix</Name>
<Value>suffix-value</Value>
</FilterRule>
</S3Key>
</Filter>
<Topic>TopicARN</Topic>
<Event>event-type</Event>
...
<QueueConfiguration>
<Filter>
...
</Filter>
<Queue>QueueARN</Queue>
...
</QueueConfiguration>
...
<CloudFunctionConfiguration>
<Filter>
...
</Filter>
<CloudFunction>cloud-function-arn</CloudFunction>
...
</CloudFunctionConfiguration>
...
Request Parameters
Request Headers
Request Elements
CloudFunction Lambda cloud function ARN that Amazon S3 can invoke Required if
when it detects events of the specified type. CloudFunctionConfigurat
is added.
Type: String
Ancestor: CloudFunctionConfiguration
Container for specifying the AWS Lambda notification

CloudFunctionConfiguration No
configuration.
Type: Container

316
Requests

Children: An Id,Filter, CloudFunction, and one, or more
Event.
Ancestor: NotificationConfiguration
Event Bucket event for which to send notifications. Required if

TopicConfiguration,
Note
QueueConfiguration
You can add multiple instance of
or
QueueConfiguration, TopicConfiguration,
CloudFunctionConfigurat
or CloudFunctionConfiguration to the
is added.
Type: String
Valid Values: For a list of supported event types, go to

Configuring Event Notifications in the Amazon Simple
Ancestor: TopicConfiguration, QueueConfiguration,

and CloudFunctionConfiguration.
Filter Container for S3Key, which contains object key name No

filtering rules. For information about key name filtering, go
to Configuring Event Notifications in the Amazon Simple
Type: Container
Children: S3Key
Ancestor: TopicConfiguration, QueueConfiguration,

or CloudFunctionConfiguration.
FilterRule Container for key value pair that defines the criteria for the No
filter rule.
Container S3Key
Type: Container
Children: Name and Value
Ancestor: S3Key
Id Optional unique identifier for each of the configurations in No

the NotificationConfiguration. If you don't provide,
Amazon S3 will assign an ID.
Type: String
Ancestor: TopicConfiguration and

QueueConfiguration

317
Requests
Name Object key name prefix or suffix identifying one or more No

objects to which the filtering rule applies. Maximum prefix
length can be up to 1,024 characters. Overlapping prefixes
and suffixes are not supported. For more information, go
to Configuring Event Notifications in the Amazon Simple
Type: String
Valid values: prefix or suffix
Container for specifying the notification configuration of the

NotificationConfiguration Yes
bucket. If this element is empty, notifications are turned off
on the bucket.
Type: Container
Children: one or more TopicConfiguration,

QueueConfiguration, and
CloudFunctionConfiguration elements.
Ancestor: None
Queue Amazon SQS queue ARN to which Amazon S3 will publish a Required if
message when it detects events of specified type. QueueConfiguration
is added.
Type: String
Ancestor: TopicConfiguration
QueueConfiguration Container for specifying the SQS queue configuration for No

the notification. You can add one or more of these queue
configurations, each identifying one or more event types.
Type: Container
Children: An Id, Filter, Topic, and one, or more Event.
S3Key Container for object key name prefix and suffix filtering No
rules.
Type: Container
Children: One or more FilterRule
Ancestor: Filter
Topic Amazon SNS topic ARN to which Amazon S3 will publish a Required if
message when it detects events of specified type. TopicConfiguration
is added.
Type: String
Ancestor: TopicConfiguration

318
Responses
TopicConfiguration Container for specifying an SNS topic configuration for the No

notification.
Type: Container
Children: An Id, Filter, Topic, and one, or more Event.
Value Specifies the object key name prefix or suffix to filter on. No
Type: String
Responses
Response Headers
In addition to the common response headers (see Common Response Headers (p. 4)), if the
configuration in the request body includes only one TopicConfiguration specifying only the
s3:ReducedRedundancyLostObject event type, the response will also include the x-amz-sns-test-message-
id header containing the message ID of the test notification sent to topic.
Response Elements
Special Errors
Amazon S3 checks the validity of the proposed NotificationConfiguration element and verifies
HTTP 400 Bad InvalidArgument The following conditions can cause this error:
Request
• A specified event is not supported for notifications.
• A specified destination ARN does not exist or is not well-
formed. Verify the destination ARN.
• A specified destination is in a different region than the
bucket. You must use a destination that resides in the
same region as the bucket.
• The bucket owner does not have appropriate
permissions on the specified destination.
• An object key name filtering rule defined with
overlapping prefixes, overlapping suffixes, or
overlapping combinations of prefixes and suffixes for
the same event types.

319
Examples
HTTP 403 AccessDenied You are not the owner of the specified bucket, or you
Forbidden do not have the s3:PutBucketNotification bucket
permission to set the notification configuration on the
bucket.
Examples
Example 1: Configure Notification to Invoke a cloud function in
Lambda
The following notification configuration includes CloudFunctionConfiguration, which identifies
the event type for which Amazon S3 can invoke a cloud function and the name of the cloud function to
invoke.
<CloudFunctionConfiguration>
<Id>ObjectCreatedEvents</Id>
<CloudFunction>arn:aws:lambda:us-west-2:35667example:function:CreateThumbnail</
CloudFunction>
</CloudFunctionConfiguration>
The following PUT uploads the notification configuration. The operation replaces the existing
PUT http://s3.amazonaws.com/examplebucket?notification= HTTP/1.1

User-Agent: s3curl 2.0
Pragma: no-cache
Accept: */*
Proxy-Connection: Keep-Alive
Date: Mon, 13 Oct 2014 23:14:52 +0000
[request body]
HTTP/1.1 200 OK
x-amz-id-2: 8+FlwagBSoT2qpMaGlfCUkRkFR5W3OeS7UhhoBb17j+kqvpS2cSFlgJ5coLd53d2
x-amz-request-id: E5BA4600A3937335
Date: Fri, 31 Oct 2014 01:49:50 GMT
Content-Length: 0
Server: AmazonS3
Example 2: Configure a Notification with Multiple Destinations

The following notification configuration includes the topic and queue configurations:

320
Examples
• A topic configuration identifying an SNS topic for Amazon S3 to publish events of the
s3:ReducedRedundancyLostObject type.
• A queue configuration identifying an SQS queue for Amazon S3 to publish events of the
s3:ObjectCreated:* type.
<Topic>arn:aws:sns:us-east-1:356671443308:s3notificationtopic2</Topic>
<Event>s3:ReducedRedundancyLostObject</Event>
<Queue>arn:aws:sqs:us-east-1:356671443308:s3notificationqueue</Queue>
The following PUT request against the notification subresource of the examplebucket bucket sends the
preceding notification configuration in the request body. The operation replaces the existing notification
configuration on the bucket.

Pragma: no-cache
Accept: */*
Date: Mon, 13 Oct 2014 22:58:43 +0000
Content-Length: 391
Expect: 100-continue
HTTP/1.1 200 OK
x-amz-id-2: SlvJLkfunoAGILZK3KqHSSUq4kwbudkrROmESoHOpDacULy+cxRoR1Svrfoyvg2A
x-amz-request-id: BB1BA8E12D6A80B7
Date: Mon, 13 Oct 2014 22:58:44 GMT
Content-Length: 0
Server: AmazonS3
Example 3: Configure a Notification with Object Key Name

Filtering
The following notification configuration contains a queue configuration identifying an Amazon SQS
queue for Amazon S3 to publish events to of the s3:ObjectCreated:Put type. The events will be
published whenever an object that has a prefix of images/ and a .jpg suffix is PUT to a bucket. For
more examples of notification configurations that use filtering, go to Configuring Event Notifications in
<Id>1</Id>
<Filter>
<S3Key>
<FilterRule>
<Name>prefix</Name>
<Value>images/</Value>

321
Related Resources
</FilterRule>
<FilterRule>
<Name>suffix</Name>
<Value>.jpg</Value>
</FilterRule>
</S3Key>
</Filter>
<Queue>arn:aws:sqs:us-west-2:444455556666:s3notificationqueue</Queue>
<Event>s3:ObjectCreated:Put</Event>
The following PUT request against the notification subresource of the examplebucket bucket sends the
preceding notification configuration in the request body. The operation replaces the existing notification
configuration on the bucket.

Pragma: no-cache
Accept: */*
Date: Mon, 13 Oct 2014 22:58:43 +0000
HTTP/1.1 200 OK
x-amz-id-2: SlvJLkfunoAGILZK3KqHSSUq4kwbudkrROmESoHOpDacULy+cxRoR1Svrfoyvg2A
x-amz-request-id: BB1BA8E12D6A80B7
Date: Mon, 13 Oct 2014 22:58:44 GMT
Content-Length: 0
Server: AmazonS3
Related Resources
• GET Bucket notification (p. 190)

322
PUT Bucket object lock configuration
PUT Bucket object lock configuration

Places an Object Lock configuration on the specified bucket. The rule specified in the Object Lock
configuration will be applied by default to every new object placed in the specified bucket.
Request Syntax
PUT /?object-lock HTTP/1.1
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
4))
<ObjectLockEnabled><value></ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Mode><value></Mode>
<Days><value></Days>
<Years><value></Years>
</DefaultRetention>
</Rule>
Note
DefaultRetention requires either Days or Years. You can't specify both at the same time.

The request does not use any URI parameters.
Request Body
For more information about the request elements that this operation uses, see
ObjectLockConfiguration (p. 544).
Example Request Body:
<ObjectLockEnabled>Enabled</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Mode>GOVERNANCE</Mode>
<Days>30</Days>
</DefaultRetention>
</Rule>
Response Syntax
HTTP/1.1 200
Response Elements

323
Related Resources
Related Resources

324
PUT Bucket policy
PUT Bucket policy

Description
This implementation of the PUT operation uses the policy subresource to return the policy of a
bucket, the calling identity must have the PutBucketPolicy permissions on the specified bucket and
belong to the bucket owner's account in order to use this operation.
If you don't have PutBucketPolicy permissions, Amazon S3 returns a 403 Access Denied error. If
you have the correct permissions, but you're not using an identity that belongs to the bucket owner's
Important
Requests
Syntax
PUT /?policy HTTP/1.1
Date: date
4))
Policy written in JSON
Request Parameters
Request Headers
Request Elements
The body is a JSON string containing the policy contents containing the policy statements.
Responses
Response Headers
Response Elements
PUT response elements return whether the operation succeeded or not.

325
Examples
Special Errors
Examples
Sample Request
The following request shows the PUT individual policy request for the bucket.
PUT /?policy HTTP/1.1

Date: Tue, 04 Apr 2010 20:34:56 GMT
{
"Version":"2008-10-17",
"Id":"aaaa-bbbb-cccc-dddd",
"Statement" : [
{
"Effect":"Allow",
"Sid":"1",
"Principal" : {
"AWS":["111122223333","444455556666"]
},
"Action":["s3:*"],
"Resource":"arn:aws:s3:::bucket/*"
}
]
}
Sample Response
x-amz-id-2: Uuag1LuByR5Onimru9SAMPLEAtRPfTaOFg==
Date: Tue, 04 Apr 2010 20:34:56 GMT
Server: AmazonS3
Related Resources

326
PUT Bucket replication
PUT Bucket replication

Description
Creates a replication configuration or replaces one. For more information, see Cross-Region Replication
(CRR) in the Amazon S3 Developer Guide.
Requests
Syntax
PUT /?replication HTTP/1.1
Date: date
Content-MD5: MD5
Replication configuration XML in the body
For more information, see the following topics:
• For an overview of replication configuration XML and examples, see Replication Configuration
Overview in the Amazon S3 Developer Guide.
Important
This topic describes all of the XML elements that are supported in the latest version of the
replication configuration XML. For backward compatibility, Amazon S3 also continues to
support earlier versions. For more information, see Backward Compatibility in the Amazon S3
Developer Guide.
• For authorization, see Authenticating Requests (AWS Signature Version 4) (p. 14).
Request Parameters
Request Headers

data. You must use this header as a message
RFC 1864.
Type: String
Default: None
x-amz-bucket-object-lock- Use to allow Amazon S3 object lock to be enabled No

token for an existing bucket.
Type: String

327
Requests

Default: None
Request Body
Specify the replication configuration in the request body. In the replication configuration, you provide
the name of the destination bucket where you want Amazon S3 to replicate objects, the IAM role that
Amazon S3 can assume to replicate objects on your behalf, and other relevant information.
A replication configuration must include at least one rule, and can contain a maximum of 1,000. Each
rule identifies a subset of objects to replicate by filtering the objects in the source bucket. To choose
additional subsets of objects to replicate, add a rule for each subset. All rules must specify the same
destination bucket.
You can add other configuration options to rules. For more information, see Replication Configuration
Overview in the Amazon S3 Developer Guide.
The following table describes the XML elements in a replication configuration.
Account The account ID of the destination bucket owner. Yes, if you

In a cross-account scenario, if you tell Amazon S3 specify the
to change replica ownership to the AWS account AccessControlTranslat
that owns the destination bucket by adding element
the AccessControlTranslation element,
this is the account ID of the destination bucket
owner. For more information, see Cross-Region
Replication Additional Configuration: Change
Replica Owner in the Amazon Simple Storage
Type: String
Container for replication rules. You can add a

maximum of 1,000 rules. The maximum size of a
replication configuration size is 2 MB.
Type: Container
Children: Rule
Ancestor: None
ReplicationConfiguration A container for replication rules. You can add a Yes

maximum of 1,000 rules. The maximum size of a
replication configuration size is 2 MB.
Type: Container
Children: Rule
Ancestor: None

328
Requests
Role The Amazon Resource Name (ARN) of an Yes

IAM role that Amazon S3 can assume when
replicating the objects.
Type: String
Ancestor: Rule
Rule A container for information about a particular Yes

replication rule. A replication configuration must
include at least one rule, and can contain up to
1,000 rules.
Type: Container
Ancestor:ReplicationConfiguration
ID A unique identifier for the rule. The value is No

limited to 255 characters.
Type: String
Ancestor: Rule
Status If you don't set the Status to Enabled, the rule Yes
is ignored.
Type: String
Ancestor: Rule
Valid values: Enabled, Disabled
Destination A container for destination information. Yes
Type: Container
Ancestor: Rule

where you want Amazon S3 to store replicas of
the objects identified by the rule.
If you have multiple rules, all rules must specify

the same bucket as the destination. A replication
configuration can replicate objects to only one
destination bucket.
Type: String

329
Requests
StorageClass An optional destination storage class override to No

use when replicating objects. If you don't specify
a storage class, Amazon S3 uses the storage class
of the source object for object replicas.
Type: String
Default: Storage class of the source object

Constraints: If you specify the STANDARD_IA

or ONEZONE_IA storage class for object
replicas, there are pricing considerations if the
object replicas are less than 128 KB. For more
information, see https://aws.amazon.com/s3/
pricing/.
AccessControlTranslation Use only in a cross-account scenario, where No

different AWS accounts own source and
destination buckets, to change replica ownership
to the AWS account that owns the destination
bucket.
If you don't add this element to the replication

configuration, replicas are owned by same AWS
account that owns the source object.
Type: String
Owner Identifies the replica owner. Yes, if

AccessControlTranslat
Type: String is specified
Ancestor: AccessControlTranslation
Default: Storage class of the source object
Valid values: Destination
Specifying a Filter
To specify a subset of the objects in the source bucket to apply a replication rule to, add the Filter
element as a child of the Rule element. You can filter objects based on an object key prefix, one or more
object tags, or both. The following table describes the elements for filtering in a Rule.
Filter A container that describes the filters that identify Yes.


330
Requests

You can optionally specify one of these child
elements: Prefix, Tag, or And.
Use the And child element to specify an object

filter that combines an object key Prefix and
one or more Tags.
An empty Filter element indicates that the rule

applies to all objects.
Ancestor: Rule
And A container element for a Prefix and one or Yes, if you want to specify
more Tag elements. At least one child element is more than one filtering criteria.
required. For example, one object key
prefix and one or more object
Ancestor: Filter tags.
Prefix An object key prefix that identifies one or more No

objects to which the rule applies. The maximum
length of a Prefix is 1,024 characters. If prefixes
in multiple rules overlap (if multiple rules apply to
the same object), rule priority determines which
rule applies to the object.
Note
In previous versions of replication
configuration, only the object key prefix
could be used as a rule filter (where you
add the Prefix element as a child of
the Rule element). Amazon S3 supports
this for backward compatibility. But in
the lastest configuration, Amazon S3
allows you to specify either the Filter
or Prefix as child of the Rule. For more
information, see Backward Compatibility
in the Amazon S3 Developer Guide.
Type: String
Ancestor: Filter
Tag A container that provides a tag key and value. No
Ancestor: Filter
Key Provides an object tag key. The Tag Key and No

Value are case sensitive. A Tag Key can have
1-128 characters.
Type: String

331
Requests
Value Provides the object Tag Value. The Tag Key and No
Value are case sensitive. The Tag Value can have
0-256 characters.
Type: String
When you add the Filter element in the configuration, you must also add the elements described in
this table.
A container that describes whether Amazon

DeleteMarkerReplication Yes, if Filter is specified
S3 replicates the delete markers. If you specify
a Filter, you must specify this element.
However, in the latest version of replication
configuration (when Filter is specified), Amazon
S3 doesn't replicate delete markers. Therefore,
the DeleteMarkerReplication element can
contain only <Status>Disabled</Status>.
For an example configuration, see The Basic Rule
Configuration in the Amazon S3 Developer Guide.
Note
If you don't specify the Filter element,
Amazon S3 assumes the replication
configuration is the earlier version, V1. In
the earlier version, Amazon S3 handled
replication of delete markers differently.
For more information, see Backward
Compatibility in the Amazon S3 Developer
Guide.
Ancestor: Rule
Status Indicates whether to replicate delete markers. Yes, if

DeleteMarkerReplication
Type: String is specified
Ancestor: DeleteMarkerReplication
Valid values: Disabled
Priority If you specify multiple rules with overlapping Yes, if Filter is specified
filters, identifies the rule priority. For example,
if two rules apply to the same object based on
the Filter specified, then the rule with higher
priority supersedes. The higher the numerical
value of this element, the higher the rule priority.
For more information, see Backward Compatibility
in the Amazon S3 Developer Guide.
Type: Integer
Ancestor: Rule

332
Requests

Valid values: 0 - INT-MAX.
Handling Replication of Encrypted Objects

By default, Amazon S3 doesn't replicate objects that are stored at rest using server-side encryption
with AWS KMS-managed keys, . To replicate AWS MKS-encrypted objects, add the following optional
configuration. For information about replication configuration, see CRR: Replicating Objects Created with
SSE Using AWS KMS-Managed Encryption Keys in the Amazon Simple Storage Service Developer Guide.
SourceSelectionCriteria A container that describes additional filters that Yes, if

identify the source objects that you want to you want
replicate. Amazon S3
to replicate
Currently, Amazon S3 supports only the filter for objects
objects created with server-side encryption using created with
an AWS KMS-managed key. You can choose to server-side
enable or disable replication of these objects. encryption
using
Ancestor: Rule AWS KMS-
managed
keys
SseKmsEncryptedObjects A container element for Status. Yes, if

SourceSelectionCriter
Ancestor: SourceSelectionCriteria is specified
Status A flag that tells Amazon S3 whether to replicate Yes, if

objects created with server-side encryption using SseKmsEncryptedObject
an AWS KMS-managed key. is specified
Type: String
Ancestor: SseKmsEncryptedObjects
Valid Values: Enabled, Disabled
EncryptionConfiguration A container that provides encryption-related Yes, if

information. SourceSelectionCriter
is specified
ReplicaKmsKeyID Provides the AWS KMS Key ID (Key ARN or Alias Yes, if
ARN) of the destination bucket. Amazon S3 uses EncryptionConfigurati
this key to encrypt replicas. is specified
Type: String

333
Responses
Responses
Response Headers
Response Elements
Special Errors
When you call the PUT operation, Amazon S3 checks the validity of the proposed
AnalyticsConfiguration element and verifies that the proposed configuration is valid. The following
table lists errors and possible causes.
HTTP 400 InvalidRequest If the <Owner> in <AccessControlTranslation> has a

value, the <Account> element must be specified.
HTTP 400 InvalidArgument The <Account> element is empty. It must contain a valid
account ID.
HTTP 400 InvalidArgument The AWS account specified in the <Account> element
must match the destination bucket owner.
Examples
The following example shows how to add a replication configuration.
Example 1: Add a Replication Configuration

The following is a sample PUT request that creates a replication subresource on the specified bucket
and saves the replication configuration in it. The replication configuration specifies a rule to replicate
objects to the exampletargetbucket bucket. The rule includes a filter to replicate only the objects
created with the key name prefix TaxDocs and that have two specific tags.
After you add a replication configuration to your bucket, Amazon S3 assumes the AWS Identity and
Access Management (IAM) role specified in the configuration to replicate objects on behalf of the bucket
owner. The bucket owner is the AWS account that created the bucket.
PUT /?replication HTTP/1.1

Date: Wed, 11 Feb 2015 02:11:21 GMT
<ReplicationConfiguration>
<Role>arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3</Role>
<Rule>

334
Related Resources
<ID>rule1</ID>
<Priority>1</Priority>
<DeleteMarkerReplication>
<Status>Disabled</Status>
</DeleteMarkerReplication>
<Filter>
<And>
<Prefix>TaxDocs</Prefix>
<Tag>
<Key>key1</Key>
</Tag>
<Tag>
<Key>key1</Key>
</Tag>
</And>
</Filter>
<Destination>
<Bucket>arn:aws:s3:::exampletargetbucket</Bucket>
</Destination>
</Rule>
</ReplicationConfiguration>
The following is a sample response:
HTTP/1.1 200 OK
Date: Wed, 11 Feb 2015 02:11:22 GMT
Content-Length: 0
Server: AmazonS3
Filtering using the <Filter> element is supported in the latest XML configuration. If you are using
an earlier version of the XML configuration, you can filter only on key prefix. In that case, you add the
<Prefix> element as a child of the <Rule>.
For more examples of replication configuration, see Replication Configuration Overview in the Amazon
S3 Developer Guide.
Related Resources
• GET Bucket replication (p. 212).
• DELETE Bucket replication (p. 121).
• For information about enabling versioning on a bucket, see Using Versioning in the Amazon Simple
• By default, a resource owner, in this case the AWS account that created the bucket, can perform this
operation. The resource owner can also grant others permissions to perform the operation. For more
information, see the following topics in the Amazon Simple Storage Service Developer Guide:
• Specifying Permissions in a Policy
• Managing Access Permissions to Your Amazon S3 Resources

335
PUT Bucket requestPayment
PUT Bucket requestPayment

Description
This implementation of the PUT operation uses the requestPayment subresource to set the request
payment configuration of a bucket. By default, the bucket owner pays for downloads from the bucket.
This configuration parameter enables the bucket owner (only) to specify that the person requesting the
download will be charged for the download. For more information, see Requester Pays Buckets.
Requests
Syntax
PUT ?requestPayment HTTP/1.1
Date: date
Authorization:signatureValue
<Payer>payer</Payer>
Request Parameters
Request Headers
Request Elements
Name Description
Payer Specifies who pays for the download and request fees.
Type: Enum
Ancestor: RequestPaymentConfiguration
RequestPaymentConfiguration Container for Payer.
Type: Container

336
Responses
Responses
Response Headers
Response Elements
Special Errors
Examples
Sample Request
This request creates a Requester Pays bucket named "colorpictures."
PUT ?requestPayment HTTP/1.1

Content-Length: 173
Date: Wed, 01 Mar 2006 12:00:00 GMT
<Payer>Requester</Payer>
Sample Response
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2006 12:00:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3
Related Resources
• GET Bucket requestPayment (p. 219)

337
PUT Bucket tagging
PUT Bucket tagging

Description
This implementation of the PUT operation uses the tagging subresource to add a set of tags to an
existing bucket.
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.
Note
Within a bucket, if you add a tag that has the same key as an existing tag, the new value
overwrites the old value. For more information, see Using Cost Allocation in Amazon S3 Bucket
Tags in AWS Billing and Cost Management.
To use this operation, you must have permissions to perform the s3:PutBucketTagging action.
The bucket owner has this permission by default and can grant this permission to others. For more
information about permissions, see Permissions Related to Bucket Subresource Operations and
Developer Guide.
Requests
Syntax
The following request shows the syntax for sending tagging information in the request body.
PUT /?tagging HTTP/1.1

Date: date
4))
<Tagging>
<TagSet>
<Tag>
<Key>Tag Name</Key>
<Value>Tag Value</Value>
</Tag>
</TagSet>
</Tagging>
Request Parameters
Request Headers
Content-MD5 will be a required header for this operation.

338
Responses
Request Elements
Tagging Container for the TagSet and Tag elements. Yes
Type: String
Ancestors: None
TagSet Container for a set of tags Yes
Type: Container
Ancestors: Tagging
Tag Container for tag information. Yes
Type: Container
Ancestors: TagSet
Key Name of the tag. Yes
Type: String
Ancestors: Tag
Value Value of the tag. Yes
Type: String
Ancestors: Tag
Responses
Response Headers
Response Elements
Special Errors
• InvalidTagError - The tag provided was not a valid tag. This error can occur if the tag did not pass
input validation. For information about tag restrictions, see User-Defined Tag Restrictions and AWS-
Generated Cost Allocation Tag Restrictions in the AWS Billing and Cost Management User Guide.
• MalformedXMLError - The XML provided does not match the schema.
• OperationAbortedError - A conflicting conditional operation is currently in progress against this
resource. Please try again.
• InternalError - The service was unable to apply the provided tag to the bucket.

339
Examples
Examples
Sample Request: Add tag set to a bucket
The following request adds a tag set to the existing examplebucket bucket.
PUT ?tagging HTTP/1.1

x-amz-date: Thu, 12 Apr 2012 20:04:21 GMT
<Tagging>
<TagSet>
<Tag>
<Key>Project</Key>
<Value>Project One</Value>
</Tag>
<Tag>
<Key>User</Key>
<Value>jsmith</Value>
</Tag>
</TagSet>
</Tagging>
Sample Response
Date: Wed, 01 Oct 2012 12:00:00 GMT
Related Resources

340
PUT Bucket versioning
PUT Bucket versioning

Description
This implementation of the PUT operation uses the versioning subresource to set the versioning state
of an existing bucket. To set the versioning state, you must be the bucket owner.
You can set the versioning state with one of the following values:
• Enabled—Enables versioning for the objects in the bucket
All objects added to the bucket receive a unique version ID.

• Suspended—Disables versioning for the objects in the bucket
All objects added to the bucket receive the version ID null.
If the versioning state has never been set on a bucket, it has no versioning state; a GET versioning
request does not return a versioning state value.
If the bucket owner enables MFA Delete in the bucket versioning configuration, the bucket owner must
include the x-amz-mfa request header and the Status and the MfaDelete request elements in a
request to set the versioning state of the bucket.
Important
If you have an object expiration lifecycle policy in your non-versioned 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 version-enabled bucket. (A version-enabled bucket
maintains one current and zero or more noncurrent object versions.) For more information, see
Lifecycle and Versioning in the Amazon Simple Storage Service Developer Guide.
For more information about creating a bucket, see PUT Bucket (p. 252). For more information about
returning the versioning state of a bucket, see GET Bucket Versioning Status (p. 224).
Requests
Syntax
PUT /?versioning HTTP/1.1
Date: date
4))
x-amz-mfa: [SerialNumber] [TokenCode]
<Status>VersioningState</Status>
<MfaDelete>MfaDeleteState</MfaDelete>
Note the space between [SerialNumber] and [TokenCode].
Request Parameters

341
Requests
Request Headers
x-amz-mfa The value is the concatenation of the authentication device's serial Conditional
number, a space, and the value displayed on your authentication
device.
Type: String
Default: None
Condition: Required to configure the versioning state if versioning is

configured with MFA Delete enabled.
Request Elements
Status Sets the versioning state of the bucket. No
Type: Enum
MfaDelete Specifies whether MFA Delete is enabled in the No

bucket versioning configuration. When enabled, the
bucket owner must include the x-amz-mfa request
header in requests to change the versioning state
of a bucket and to permanently delete a versioned
object.
Type: Enum
Valid Values: Disabled | Enabled
Constraint: Can only be used when you use Status.
VersioningConfiguration Container for setting the versioning state. Yes
Type: Container
Children: Status
Ancestor: None

342
Responses
Responses
Response Headers
Response Elements
Special Errors
Examples
Sample Request
The following request enables versioning for the specified bucket.

Date: Wed, 01 Mar 2006 12:00:00 GMT
Content-Length: 124
Sample Response
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2006 12:00:00 GMT
Sample Request
The following request suspends versioning for the specified bucket.

Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 124

343
Related Resources
Sample Response
HTTP/1.1 200 OK
Date: Wed, 01 Mar 2006 12:00:00 GMT
Sample Request
The following request enables versioning and MFA Delete on a bucket.

Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-mfa:[SerialNumber] [TokenCode]
Content-Length: 124
<MfaDelete>Enabled</MfaDelete>
Note the space between [SerialNumber] and [TokenCode] and that you must include Status
whenever you use MfaDelete.
Sample Response
HTTPS/1.1 200 OK
Date: Wed, 01 Mar 2006 12:00:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3
Related Resources

344
PUT Bucket website
PUT Bucket website

Description
Sets the configuration of the website that is specified in the website subresource. To configure a bucket
as a website, you can add this subresource on the bucket with website configuration information such
as the file name of the index document and any redirect rules. For more information, go to Hosting
Websites on Amazon S3 in the Amazon Simple Storage Service Developer Guide.
This PUT operation requires the S3:PutBucketWebsite permission. By default, only the bucket owner
can configure the website attached to a bucket; however, bucket owners can allow other users to set
the website configuration by writing a bucket policy that grants them the S3:PutBucketWebsite
permission.
Requests
Syntax
PUT /?website HTTP/1.1
Date: date
Content-Length: ContentLength
4))
<WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">

Request Parameters
Request Headers
Request Elements
You can use a website configuration to redirect all requests to the website endpoint of a bucket, or you
can add routing rules that redirect only specific requests.
• To redirect all website requests sent to the bucket's website endpoint, you add a website configuration
with the following elements. Because all requests are sent to another website, you don't need to
provide index document name for the bucket.
WebsiteConfiguration The root element for the website configuration Yes
Type: Container

345
Requests

Ancestors: None
RedirectAllRequestsToDescribes the redirect behavior for every request to this Yes

bucket's website endpoint. If this element is present, no
other siblings are allowed.
Type: Container
Ancestors: WebsiteConfiguration
HostName Name of the host where requests will be redirected. Yes
Type: String
Ancestors: RedirectAllRequestsTo
Protocol Protocol to use (http, https) when redirecting requests. No

The default is the protocol that is used in the original
request.
Type: String
Ancestors: RedirectAllRequestsTo
• If you want granular control over redirects, you can use the following elements to add routing rules
that describe conditions for redirecting requests and information about the redirect destination. In
this case, the website configuration must provide an index document for the bucket, because some
requests might not be redirected.
WebsiteConfiguration Container for the request Yes
Type: Container
Ancestors: None
IndexDocument Container for the Suffix element. Yes
Type: Container
Suffix A suffix that is appended to a request that is for a Yes

directory on the website endpoint (e.g., if the suffix is
index.html and you make a request to samplebucket/
images/, the data that is returned will be for the object
with the key name images/index.html)
The suffix must not be empty and must not include a

slash character.
Type: String
Ancestors: WebsiteConfiguration.IndexDocument
ErrorDocument Container for the Key element No

346
Requests

Type: Container
Key The object key name to use when a 4XX class error Conditional
occurs. This key identifies the page that is returned when
such an error occurs.
Type: String
Ancestors: WebsiteConfiguration.ErrorDocument
Condition: Required when ErrorDocument is specified.
RoutingRules Container for a collection of RoutingRule elements. No
Type: Container
RoutingRule Container for one routing rule that identifies a condition Yes
and a redirect that applies when the condition is met.
Type: String
Ancestors: WebsiteConfiguration.RoutingRules
Condition: In a RoutingRules container, there must be

at least one of RoutingRule element.
Condition A container for describing a condition that must be met No

for the specified redirect to apply. For example:
• If request is for pages in the /docs folder, redirect to
the /documents folder.
• If request results in HTTP error 4xx, redirect request to
another host where you might process the error.
Type: Container
Ancestors:
WebsiteConfiguration.RoutingRules.RoutingRule

347
Requests
KeyPrefixEquals The object key name prefix when the redirect Conditional
is applied. For example, to redirect requests
for ExamplePage.html, the key prefix will be
ExamplePage.html. To redirect request for all pages
with the prefix docs/, the key prefix will be /docs,
which identifies all objects in the docs/ folder.
Type: String
Ancestors:
WebsiteConfiguration.RoutingRules.RoutingRule.Condition
Condition: Required when the parent

element Condition is specified and sibling
HttpErrorCodeReturnedEquals is not specified. If
both conditions are specified, both must be true for the
redirect to be applied.
The HTTP error code when the redirect is applied. In the

HttpErrorCodeReturnedEquals Conditional
event of an error, if the error code equals this value, then
the specified redirect is applied.
Type: String
Ancestors:
WebsiteConfiguration.RoutingRules.RoutingRule.Condition
Condition: Required when parent element Condition is

specified and sibling KeyPrefixEquals is not specified.
If both are specified, then both must be true for the
redirect to be applied.
Redirect Container for redirect information. You can redirect Yes

requests to another host, to another page, or with
another protocol. In the event of an error, you can
specify a different error code to return.
Type: String
Ancestors:
WebsiteConfiguration.RoutingRules.RoutingRule
Protocol The protocol to use in the redirect request. No
Type: String
Ancestors:
WebsiteConfiguration.RoutingRules.RoutingRule.Redirect
Valid Values: http, https
Condition: Not required if one of the siblings is present

348
Responses
HostName The host name to use in the redirect request. No
Type: String
Ancestors:
Condition: Not required if one of the siblings is present
ReplaceKeyPrefixWith The object key prefix to use in the redirect request. No

For example, to redirect requests for all pages
with prefix docs/ (objects in the docs/ folder) to
documents/, you can set a condition block with
KeyPrefixEquals set to docs/ and in the Redirect
set ReplaceKeyPrefixWith to /documents.
Type: String
Ancestors:
Condition: Not required if one of the siblings is present.

Can be present only if ReplaceKeyWith is not provided.
ReplaceKeyWith The specific object key to use in the redirect request. For No
example, redirect request to error.html.
Type: String
Ancestors:
Condition: Not required if one of the sibling is present.

Can be present only if ReplaceKeyPrefixWith is not
provided.
HttpRedirectCode The HTTP redirect code to use on the response. No
Type: String
Ancestors:
Condition: Not required if one of the siblings is present.
Responses
Response Headers
Response Elements

349
Examples
Examples
Example 1: Configure bucket as a website (add website
configuration)
The following request configures a bucket example.com as a website. The configuration in the
request specifies index.html as the index document. It also specifies the optional error document,
SomeErrorDocument.html.
PUT ?website HTTP/1.1

Host: example.com.s3.amazonaws.com
Content-Length: 256
Date: Thu, 27 Jan 2011 12:00:00 GMT
<WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'>
<IndexDocument>
</IndexDocument>
<ErrorDocument>
<Key>SomeErrorDocument.html</Key>
</ErrorDocument>
Amazon S3 returns the following sample response.
HTTP/1.1 200 OK
x-amz-request-id: 80CD4368BD211111
Date: Thu, 27 Jan 2011 00:00:00 GMT
Content-Length: 0
Server: AmazonS3
Example 2: Configure bucket as a website but redirect all

requests
The following request configures a bucket www.example.com as a website; however, the configuration
specifies that all GET requests for the www.example.com bucket's website endpoint will be redirected to
host example.com.

Host: www.example.com.s3.amazonaws.com
Content-Length: length-value
Date: Thu, 27 Jan 2011 12:00:00 GMT
<RedirectAllRequestsTo>
<HostName>example.com</HostName>
</RedirectAllRequestsTo>
This redirect can be useful when you want to serve requests for both http://www.example.com and
http://example.com, but you want to maintain the website content in only one bucket, in this case
example.com. For more information, go to Hosting Websites on Amazon S3 in the Amazon Simple

350
Examples
Example 3: Configure bucket as a website and also specify

optional redirection rules
Example 1 is the simplest website configuration. It configures a bucket as a website by providing only an
index document and an error document. You can further customize the website configuration by adding
routing rules that redirect requests for one or more objects. For example, suppose your bucket contained
the following objects:
index.html
docs/article1.html
docs/article2.html
If you decided to rename the folder from docs/ to documents/, you would need to redirect requests
for prefix /docs to documents/. For example, a request for docs/article1.html will need to be
redirected to documents/article1.html.
In this case, you update the website configuration and add a routing rule as shown in the following
request:

Content-Length: length-value
Date: Thu, 27 Jan 2011 12:00:00 GMT
<IndexDocument>
</IndexDocument>
<ErrorDocument>
<Key>Error.html</Key>
</ErrorDocument>
<RoutingRules>
<RoutingRule>
<Condition>
<KeyPrefixEquals>docs/</KeyPrefixEquals>
</Condition>
<Redirect>
<ReplaceKeyPrefixWith>documents/</ReplaceKeyPrefixWith>
</Redirect>
</RoutingRule>
</RoutingRules>
Example 4: Configure bucket as a website and redirect errors

You can use a routing rule to specify a condition that checks for a specific HTTP error code. When a page
request results in this error, you can optionally reroute requests. For example, you might route requests
to another host and optionally process the error. The routing rule in the following requests redirects
requests to an EC2 instance in the event of an HTTP error 404. For illustration, the redirect also inserts a
object key prefix report-404/ in the redirect. For example, if you request a page ExamplePage.html
and it results in a HTTP 404 error, the request is routed to a page report-404/testPage.html on
the specified EC2 instance. If there is no routing rule and the HTTP error 404 occurred, then Error.html
would be returned.

351
Examples
Content-Length: 580
Date: Thu, 27 Jan 2011 12:00:00 GMT
<IndexDocument>
</IndexDocument>
<ErrorDocument>
</ErrorDocument>
<RoutingRules>
<RoutingRule>
<Condition>
<HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals >
</Condition>
<Redirect>
<HostName>ec2-11-22-333-44.compute-1.amazonaws.com</HostName>
<ReplaceKeyPrefixWith>report-404/</ReplaceKeyPrefixWith>
</Redirect>
</RoutingRule>
</RoutingRules>
Example 5: Configure a bucket as a website and redirect folder

requests to a page
Suppose you have the following pages in your bucket:
images/photo1.jpg
images/photo2.jpg
images/photo3.jpg
Now you want to route requests for all pages with the images/ prefix to go to a single page,
errorpage.html. You can add a website configuration to your bucket with the routing rule shown in
the following request:

Content-Length: 481
Date: Thu, 27 Jan 2011 12:00:00 GMT
<IndexDocument>
</IndexDocument>
<ErrorDocument>
</ErrorDocument>
<RoutingRules>
<RoutingRule>
<Condition>
<KeyPrefixEquals>images/</KeyPrefixEquals>
</Condition>
<Redirect>
<ReplaceKeyWith>errorpage.html</ReplaceKeyWith>

352
Examples
</Redirect>
</RoutingRule>
</RoutingRules>

353
Delete Multiple Objects
Operations on Objects
This section describes operations you can perform on Amazon S3 objects.
Topics
• Delete Multiple Objects (p. 354)
• DELETE Object tagging (p. 368)
• GET Object legal hold (p. 387)
• GET Object retention (p. 388)
• GET Object tagging (p. 389)
• GET Object torrent (p. 392)
• HEAD Object (p. 394)
• POST Object (p. 407)
• POST Object restore (p. 419)
• PUT Object legal hold (p. 449)
• PUT Object retention (p. 450)
• PUT Object - Copy (p. 451)
• PUT Object acl (p. 467)
• PUT Object tagging (p. 474)
• SELECT Object Content (p. 477)
• Upload Part - Copy (p. 534)
Delete Multiple Objects

Description
The Multi-Object Delete operation enables you to delete multiple objects from a bucket using a single
HTTP request. If you know the object keys that you want to delete, then this operation provides a
suitable alternative to sending individual delete requests (see DELETE Object (p. 364)), reducing per-
request overhead.
The Multi-Object Delete request contains a list of up to 1000 keys that you want to delete. In the XML,
you provide the object key names, and optionally, version IDs if you want to delete a specific version of
the object from a versioning-enabled bucket. For each key, Amazon S3 performs a delete operation and
returns the result of that delete, success, or failure, in the response. Note that, if the object specified in
the request is not found, Amazon S3 returns the result as deleted.

354
Requests
The Multi-Object Delete operation supports two modes for the response; verbose and quiet. By default,
the operation uses verbose mode in which the response includes the result of deletion of each key in
your request. In quiet mode the response includes only keys where the delete operation encountered an
error. For a successful deletion, the operation does not return any information about the delete in the
response body.
When performing a Multi-Object Delete operation on an MFA Delete enabled bucket, that attempts
to delete any versioned objects, you must include an MFA token. If you do not provide one, the entire
request will fail, even if there are non versioned objects you are attempting to delete. If you provide
an invalid token, whether there are versioned keys in the request or not, the entire Multi-Object Delete
request will fail. For information about MFA Delete, see MFA Delete.
Finally, the Content-MD5 header is required for all Multi-Object Delete requests. Amazon S3 uses the
header value to ensure that your request body has not been altered in transit.
Requests
Syntax
POST /?delete HTTP/1.1
Content-Length: Size
Content-MD5: MD5

<Delete>
<Quiet>true</Quiet>
<Object>
<Key>Key</Key>
<VersionId>VersionId</VersionId>
</Object>
<Object>
<Key>Key</Key>
</Object>
...
</Delete>
Request Parameters
The Multi-Object Delete operation requires a single query string parameter called "delete" to distinguish
it from other bucket POST operations.
Request Headers
This operation uses the following Request Headers in addition to the request headers common to most
requests. For more information, see Common Request Headers (p. 2).
Content-MD5 The base64-encoded 128-bit MD5 digest of the data. This header Yes
must be used as a message integrity check to verify that the request
body was not corrupted in transit. For more information, go to RFC
1864.
Type: String
Default: None

355
Requests
Content- Length of the body according to RFC 2616. Yes

Length
Type: String
Default: None
x-amz-mfa The value is the concatenation of the authentication device's Conditional

serial number, a space, and the value that is displayed on your
authentication device.
Type: String
Default: None
Condition: Required to permanently delete a versioned object if

versioning is configured with MFA Delete enabled.
Request Elements
Delete Container for the request. Yes
Ancestor: None
Type: Container
Children: One or more Object elements and an optional

Quiet element.
Quiet Element to enable quiet mode for the request. When you No
add this element, you must set its value to true.
Ancestor: Delete
Type: Boolean
Default: false
Object Container element that describes the delete request for an Yes
object.
Ancestor: Delete
Type: Container
Children: Key element and an optional VersionId element.
Key Key name of the object to delete. Yes
Ancestor: Object
Type: String
VersionId VersionId for the specific version of the object to delete. No
Ancestor: Object

356
Responses

Type: String
Responses
Response Headers
Response Elements
Name Description
DeleteResult Container for the response.
Children: Deleted, Error
Type: Container
Ancestor: None
Deleted Container element for a successful delete. It identifies the

object that was successfully deleted.
Children: Key, VersionId
Type: Container
Ancestor: DeleteResult
Key Key name for the object that Amazon S3 attempted to

delete.
Type: String
Ancestor: Deleted, or Error
VersionId VersionId for the versioned object in the case of a versioned

delete.
Type: String
Ancestor: Deleted
DeleteMarker DeleteMarker element with a true value indicates that the

request accessed a delete marker.
If a specific delete request either creates or deletes a delete

marker, Amazon S3 returns this element in the response with
a value of true. This is only the case when your Multi-Object
Delete request is on a bucket that has versioning enabled or
suspended. For more information about delete markers, go
to Object Versioning.
Type: Boolean

357
Responses
Name Description
Ancestor: Deleted
DeleteMarkerVersionId Version ID of the delete marker accessed (deleted or created)

by the request.
If the specific delete request in the Multi-Object Delete either

creates or deletes a delete marker, Amazon S3 returns this
element in response with the version ID of the delete marker.
When deleting an object in a bucket with versioning enabled,
this value is present for the following two reasons:
• You send a non-versioned delete request, that is, you

specify only object key and not the version ID. In this case,
Amazon S3 creates a delete marker and returns its version
ID in the response.
• You send a versioned delete request, that is, you specify an
object key and a version ID in your request; however, the
version ID identifies a delete marker. In this case, Amazon
S3 deletes the delete marker and returns the specific
version ID in response. For information about versioning,
go to Object Versioning.
Type: String
Ancestor: Deleted
Error Container for a failed delete operation that describes the

object that Amazon S3 attempted to delete and the error it
encountered.
Children: Key, VersionId, Code, Message.
Type: String
Ancestor: DeleteResult
Key Key for the object Amazon S3 attempted to delete.
Type: String
Ancestor: Error
VersionId Version ID of the versioned object Amazon S3 attempted to

delete. Amazon S3 includes this element only in case of a
versioned-delete request.
Type: String
Ancestor: Deleted, Error
Code Status code for the result of the failed delete. .
Type: String
Values: AccessDenied, InternalError
Ancestor: Error

358
Examples
Name Description
Message Error description.
Type: String
Ancestor: Error
Examples
Example 1: Multi-Object Delete resulting in mixed success/error
response
This example illustrates a Multi-Object Delete request to delete objects that result in mixed success and
errors response.
Sample Request
The following Multi-Object Delete request deletes two objects from a bucket (bucketname). In this
example, the requester does not have permission to delete the sample2.txt object.

Accept: */*
x-amz-date: Wed, 30 Nov 2011 03:39:05 GMT
Content-MD5: p5/WA/oEr30qrEEl21PAqw==
Authorization: AWS AKIAIOSFODNN7EXAMPLE:W0qPYCLe6JwkZAD1ei6hp9XZIee=
Content-Length: 125
<Delete>
<Object>
<Key>sample1.txt</Key>
</Object>
<Object>
</Object>
</Delete>
Sample Response
The response includes a DeleteResult element that includes a Deleted element for the item that
Amazon S3 successfully deleted and an Error element that Amazon S3 did not delete because you
didn't have permission to delete the object.
HTTP/1.1 200 OK
x-amz-id-2: 5h4FxSNCUS7wP5z92eGCWDshNpMnRuXvETa4HH3LvvH6VAIr0jU7tH9kM7X+njXx
x-amz-request-id: A437B3B641629AEE
Date: Fri, 02 Dec 2011 01:53:42 GMT
Server: AmazonS3
Content-Length: 251

<DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Deleted>
</Deleted>

359
Examples
<Error>
<Code>AccessDenied</Code>
<Message>Access Denied</Message>
</Error>
</DeleteResult>
Example 2: Deleting Object from a Versioned Bucket

If you delete an item from a versioning enabled bucket, all versions of that object remain in the bucket;
however, Amazon S3 inserts a delete marker. For more information, go to Object Versioning.
The following scenarios describe the behavior of a Multi-Object Delete request when versioning is
enabled for your bucket.
Case 1 - Simple Delete

The following sample the Multi-Object Delete request specifies only one key.

Accept: */*
Content-Length: 79
<Delete>
<Object>
<Key>SampleDocument.txt</Key>
</Object>
</Delete>
Because versioning is enabled on the bucket, Amazon S3 does not delete the object. Instead, it
adds a delete marker for this object. The response indicates that a delete marker was added (the
DeleteMarker element in the response as a value of true) and the version number of the delete marker
it added.
HTTP/1.1 200 OK
x-amz-id-2: P3xqrhuhYxlrefdw3rEzmJh8z5KDtGzb+/FB7oiQaScI9Yaxd8olYXc7d1111ab+
x-amz-request-id: 264A17BF16E9E80A
Date: Wed, 30 Nov 2011 03:39:32 GMT
Server: AmazonS3
Content-Length: 276

<Deleted>
<DeleteMarker>true</DeleteMarker>
<DeleteMarkerVersionId>NeQt5xeFTfgPJD8B4CGWnkSLtluMr11s</DeleteMarkerVersionId>
</Deleted>
</DeleteResult>
Case 2 - Versioned Delete

The following Multi-Object Delete attempts to delete a specific version of an object

360
Examples
Accept: */*
Authorization: AWS AKIAIOSFODNN7EXAMPLE:W0qPYCLe6JwkZAD1ei6hp9XZIxx=
Content-Length: 140
<Delete>
<Object>
<VersionId>OYcLXagmS.WaD..oyH4KRguB95_YhLs7</VersionId>
</Object>
</Delete>
In this case, Amazon S3 deletes the specific object version from the bucket and returns the following
response. In the response, Amazon S3 returns the key and version ID of the object deleted.
HTTP/1.1 200 OK
x-amz-id-2: P3xqrhuhYxlrefdw3rEzmJh8z5KDtGzb+/FB7oiQaScI9Yaxd8olYXc7d1111xx+
Date: Wed, 30 Nov 2011 03:39:32 GMT
Server: AmazonS3
Content-Length: 219

<Deleted>
<VersionId>OYcLXagmS.WaD..oyH4KRguB95_YhLs7</VersionId>
</Deleted>
</DeleteResult>
Case 3 - Versioned Delete of a Delete Marker

In the preceding example, the request refers to a delete marker (instead of an object), then Amazon S3
deletes the delete marker. The effect of this operation is to make your object reappear in your bucket.
Amazon S3 returns a response that indicates the delete marker it deleted (DeleteMarker element with
value true) and the version ID of the delete marker.
HTTP/1.1 200 OK
x-amz-id-2: IIPUZrtolxDEmWsKOae9JlSZe6yWfTye3HQ3T2iAe0ZE4XHa6NKvAJcPp51zZaBr
x-amz-request-id: D6B284CEC9B05E4E
Date: Wed, 30 Nov 2011 03:43:25 GMT
Server: AmazonS3
Content-Length: 331

<Deleted>
<VersionId>NeQt5xeFTfgPJD8B4CGWnkSLtluMr11s</VersionId>
</Deleted>
</DeleteResult>
In general, when a Multi-Object Delete request results in Amazon S3 either adding a delete marker or
removing a delete marker, the response returns the following elements.

361
Related Actions
Example
Example 3: Malformed XML in the Request

This example shows how Amazon S3 responds to a request that includes a malformed XML document.
Sample Request
The following requests sends a malformed XML document (missing the Delete end element).

Accept: */*
Content-Length: 104
<Delete>
<Object>
<Key>404.txt</Key>
</Object>
<Object>
<Key>a.txt</Key>
</Object>
Sample Response
The response returns the Error messages that describe the error.
HTTP/1.1 200 OK
x-amz-id-2: P3xqrhuhYxlrefdw3rEzmJh8z5KDtGzb+/FB7oiQaScI9Yaxd8olYXc7d1111ab+
Date: Wed, 30 Nov 2011 03:39:32 GMT
Server: AmazonS3
Content-Length: 207

<Error>
<Code>MalformedXML</Code>
<Message>The XML you provided was not well-formed or did not
validate against our published schema</Message>
<RequestId>264A17BF16E9E80A</RequestId>
<HostId>P3xqrhuhYxlrefdw3rEzmJh8z5KDtGzb+/FB7oiQaScI9Yaxd8olYXc7d1111ab+</HostId>
</Error>
Related Actions

362
Related Actions

363
DELETE Object
DELETE Object
Description
The DELETE operation removes the null version (if there is one) of an object and inserts a delete marker,
which becomes the current version of the object. If there isn't a null version, Amazon S3 does not remove
any objects.
Versioning
To remove a specific version, you must be the bucket owner and you must use the versionId
subresource. Using this subresource permanently deletes the version. If the object deleted is a delete
marker, Amazon S3 sets the response header, x-amz-delete-marker, to true.
If the object you want to delete is in a bucket where the bucket versioning configuration is MFA Delete
enabled, you must include the x-amz-mfa request header in the DELETE versionId request. Requests
that include x-amz-mfa must use HTTPS.
For more information about MFA Delete, go to Using MFA Delete. To see sample requests that use
versioning, see Sample Request (p. 366).
You can delete objects by explicitly calling the DELETE Object API or configure its lifecycle (see PUT
Bucket lifecycle (p. 290)) to enable Amazon S3 to remove them for you. If you want to block users or
accounts from removing or deleting objects from your bucket you must deny them s3:DeleteObject,
s3:DeleteObjectVersion and s3:PutLifeCycleConfiguration actions.
Requests
Syntax
DELETE /ObjectName HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
x-amz-mfa The value is the concatenation of the authentication device's serial Conditional
number, a space, and the value displayed on your authentication
device.
Type: String
Default: None
Condition: Required to permanently delete a versioned object if

versioning is configured with MFA Delete enabled.

364
Responses
Request Elements
Responses
Response Headers
Header Description
x-amz-delete- Specifies whether the versioned object that was permanently deleted was
marker (true) or was not (false) a delete marker. In a simple DELETE, this header
indicates whether (true) or not (false) a delete marker was created.
Type: Boolean
Default: false
x-amz-version- Returns the version ID of the delete marker created as a result of the DELETE
id operation. If you delete a specific object version, the value returned by this
header is the version ID of the object version deleted.
Type: String
Default: None
Response Elements
Special Errors
Examples
Sample Request
The following request deletes the object, my-second-image.jpg.
DELETE /my-second-image.jpg HTTP/1.1

Date: Wed, 12 Oct 2009 17:50:00 GMT
Sample Response
HTTP/1.1 204 NoContent

365
Examples
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3
Sample Request Deleting a Specified Version of an Object

The following request deletes the specified version of the object, my-third-image.jpg.
DELETE /my-third-image.jpg?versionId=UIORUnfndfiufdisojhr398493jfdkjFJjkndnqUifhnw89493jJFJ
HTTP/1.1
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Sample Response
x-amz-version-id: UIORUnfndfiufdisojhr398493jfdkjFJjkndnqUifhnw89493jJFJ
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3
Sample Response if the Object Deleted is a Delete Marker

x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-delete-marker: true
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3
Sample Request Deleting a Specified Version of an Object in an

MFA-Enabled Bucket
The following request deletes the specified version of the object, my-third-image.jpg, which is stored
in an MFA-enabled bucket.
DELETE /my-third-image.jpg?versionId=UIORUnfndfiuf HTTP/1.1

Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-mfa:[SerialNumber] [AuthenticationCode]
Content-Length: 0

366
Related Resources
Sample Response
x-amz-version-id: UIORUnfndfiuf
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3
Related Resources

367
DELETE Object tagging
DELETE Object tagging

Description
This implementation of the DELETE operation uses the tagging subresource to remove the entire tag
set from the specified object. For more information about managing object tags, see Object Tagging in
To use this operation, you must have permission to perform the s3:DeleteObjectTagging action.
To delete tags of a specific object version, add the versionId query parameter in the request. You will
need permission for the s3:DeleteObjectVersionTagging action.
Requests
Syntax
DELETE /ObjectKey?tagging HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Examples
Sample Request
The following DELETE request deletes the tag set from the specified object.
DELETE /exampleobject?tagging HTTP/1.1


368
Related Resources
Date: Wed, 25 Nov 2016 12:00:00 GMT

Sample Response
The following successful response shows Amazon S3 returning a 204 No Content response. The tag set
for the object has been removed.

Date: Wed, 25 Nov 2016 12:00:00 GMT
Connection: close
Server: AmazonS3
Related Resources

369
GET Object
GET Object
Description
This implementation of the GET operation retrieves objects from Amazon S3. To use GET, you must have
READ access to the object. If you grant READ access to the anonymous user, you can return the object
without using an authorization header.
An Amazon S3 bucket has no directory hierarchy such as you would find in a typical computer file
system. You can, however, create a logical hierarchy by using object key names that imply a folder
structure. For example, instead of naming an object sample.jpg, you can name it photos/2006/
February/sample.jpg.
To get an object from such a logical hierarchy, specify the full key name for the object in the GET
operation. For a virtual hosted-style request example, if you have the object photos/2006/February/
sample.jpg, specify the resource as /photos/2006/February/sample.jpg. For a path-style
request example, if you have the object photos/2006/February/sample.jpg in the bucket named
examplebucket, specify the resource as /examplebucket/photos/2006/February/sample.jpg.
For more information about request types, see HTTP Host Header Bucket Specification in the Amazon
To distribute large files to many people, you can save bandwidth costs by using BitTorrent. For more
information, see Amazon S3 Torrent in the Amazon Simple Storage Service Developer Guide. For more
information about returning the ACL of an object, see GET Object ACL (p. 383).
If the object you are retrieving is stored in the GLACIER or DEEP_ARCHIVE storage classes, before you can
retrieve the object you must first restore a copy using the POST Object restore (p. 419) API. Otherwise,
this operation returns an InvalidObjectStateError error. For information about restoring archived
objects, see Restoring Archived Objects in the Amazon Simple Storage Service Developer Guide.
If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-
C) when you store the object in Amazon S3, then when you GET the object, you must use the headers
documented in the section Specific Request Headers for Server-Side Encryption with Customer-Provided
Encryption Keys (p. 374). For more information about SSE-C, go to Server-Side Encryption (Using
Customer-Provided Encryption Keys) in the Amazon Simple Storage Service Developer Guide.
Assuming you have permission to read object tags (permission for the s3:GetObjectVersionTagging
action), the response also returns the x-amz-tagging-count header that provides the count of
number of tags associated with the object. You can use the "GET Object tagging" API (see GET Object
tagging (p. 389)) to retrieve the tag set associated with an object.
Permissions
You need the s3:GetObject permission for this operation. For more information, go to Specifying
Permissions in a Policy in the Amazon Simple Storage Service Developer Guide. If the object you request
does not exist, the error Amazon S3 returns depends on whether you also have the s3:ListBucket
permission.
• If you have the s3:ListBucket permission on the bucket, Amazon S3 will return an HTTP status code
404 ("no such key") error.
• if you don’t have the s3:ListBucket permission, Amazon S3 will return an HTTP status code 403
("access denied") error.

370
Versioning
Versioning
By default, the GET operation returns the current version of an object. To return a different version, use
the versionId subresource.
Note
If the current version of the object is a delete marker, Amazon S3 behaves as if the object was
deleted and includes x-amz-delete-marker: true in the response.
For more information about versioning, see PUT Bucket versioning (p. 341) To see sample requests that
use versioning, see Sample Request Getting a Specified Version of an Object (p. 380) .
Requests
Syntax
GET /ObjectName HTTP/1.1
Date: date
4))
Range:bytes=byte_range
Request Parameters
partNumber Part number of the object part being read. This is a No

positive integer between 1 and the maximum number of
parts supported.
Only objects uploaded using the multipart upload API

have part numbers. For information about multipart
uploads, see Multipart Upload Overview in the Amazon
Effectively performs a 'ranged' GET request for the part

specified. Useful for downloading just a part of an object.
Type: Integer
Default: None
versionId Version ID used to reference a specific version of the No

object.
Type: String
Default: None
There are times when you want to override certain response header values in a GET response. For
example, you might override the Content-Disposition response header value in your GET request.
You can override values for a set of response headers using the query parameters listed in the following
table. These response header values are sent only on a successful request, that is, when status code 200
OK is returned. The set of headers you can override using these parameters is a subset of the headers

371
Requests
that Amazon S3 accepts when you create an object. The response headers that you can override for
the GET response are Content-Type, Content-Language, Expires, Cache-Control, Content-
Disposition, and Content-Encoding. To override these header values in the GET response, you use
the request parameters described in the following table.
Note
You must sign the request, either using an Authorization header or a presigned URL, when
using these parameters. They cannot be used with an unsigned (anonymous) request.
response-content-type Sets the Content-Type header of the response. No
Type: String
Default: None
response-content- Sets the Content-Language header of the response. No

language
Type: String
Default: None
response-expires Sets the Expires header of the response. No
Type: String
Default: None
response-cache-control Sets the Cache-Control header of the response. No
Type: String
Default: None
response-content- Sets the Content-Disposition header of the response. No

disposition
Type: String
Default: None
response-content- Sets the Content-Encoding header of the response. No

encoding
Type: String
Default: None
Request Headers
Range Downloads the specified range bytes of an object. For more No

information about the HTTP Range header, go to http://
www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.

372
Requests

Type: String
Default: None
Constraints: None
If-Modified- Return the object only if it has been modified since the specified No
Since time, otherwise return a 304 (not modified).
See Consideration 2 after the table.
Type: String
Default: None
Constraints: None
If-Unmodified- Return the object only if it has not been modified since the No
Since specified time, otherwise return a 412 (precondition failed).
Type: String
Default: None
Constraints: None
If-Match Return the object only if its entity tag (ETag) is the same as the No
one specified; otherwise, return a 412 (precondition failed).
Type: String
Default: None
Constraints: None
If-None-Match Return the object only if its entity tag (ETag) is different from the No
one specified; otherwise, return a 304 (not modified).
Type: String
Default: None
Constraints: None
Note
Encryption request headers, like x-amz-server-side-encryption, should not be sent for
GET requests if your object uses server-side encryption with AWS KMS–managed encryption
keys (SSE-KMS) or server-side encryption with Amazon S3–managed encryption keys (SSE-S3). If
your object does use these types of keys, you’ll get an HTTP 400 BadRequest error.
Note the following additional considerations about the preceding request headers:

373
Requests
• Consideration 1 – If both of the If-Match and If-Unmodified-Since headers are present in the
request as follows:
If-Match condition evaluates to true, and;
If-Unmodified-Since condition evaluates to false;
then, S3 returns 200 OK and the data requested. For more information about conditional requests, see
RFC 7232.

• Consideration 2 – If both of the If-None-Match and If-Modified-Since headers are present in
the request as follows:
If-None-Match condition evaluates to false, and;
If-Modified-Since condition evaluates to true;
then, S3 returns 304 Not Modified response code. For more information about conditional
requests, see RFC 7232.
Specific Request Headers for Server-Side Encryption with Customer-Provided

Encryption Keys
When you retrieve an object from Amazon S3 that was encrypted by using server-side encryption with
customer-provided encryption keys (SSE-C), you must use the following request headers. For more
information about SSE-C, go to Server-Side Encryption (Using Customer-Provided Encryption Keys) in
x-amz-server- Specifies the algorithm to use to when decrypting the requested Yes
side-encryption object.
-customer-
algorithm Type: String
Default: None
Valid Values: AES256
Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-key and x-amz-server-side-
encryption-customer-key-MD5 headers.
x-amz-server- Specifies the customer-provided base64-encoded encryption Yes

side-encryption key to use to decrypt the requested object. This value is used to
-customer-key perform the decryption and then it is discarded; Amazon does
not store the key. The key must be appropriate for use with the
algorithm specified in the x-amz-server-side-encryption-
customer-algorithm header.
Type: String
Default: None
Constraints: Must be accompanied by valid x-amz-server-side-

encryption-customer-algorithm and x-amz-server-
side-encryption-customer-key-MD5 headers.

374
Responses
x-amz-server- Specifies the base64-encoded 128-bit MD5 digest of the No

side-encryption customer-provided encryption key according to RFC 1321. If
-customer-key- this header is included in your request, Amazon S3 uses it for a
MD5 message integrity check to ensure that the encryption key was
transmitted without error.
Type: String
Default: None

side-encryption-customer-key headers.
Request Elements
Responses
Response Headers
Header Description
x-amz-delete- Specifies whether the object retrieved was (true) or was not (false) a delete
marker marker. If false, this response header does not appear in the response.
Type: Boolean
Default: false
x-amz- Amazon S3 returns this header if an Expiration action is configured for the
expiration object as part of the bucket's lifecycle configuration. The header value includes
an "expiry-date" component and a URL-encoded "rule-id" component. Note that
for versioning-enabled buckets, this header applies only to current versions;
Amazon S3 does not provide a header to infer when a noncurrent version will
be eligible for permanent deletion. For more information, see PUT Bucket
lifecycle (p. 290).
Type: String
x-amz-meta-* Headers starting with this prefix are user-defined metadata. Each one is stored
and returned as a set of key-value pairs. Amazon S3 doesn't validate or interpret
user-defined metadata.
Type: String
x-amz- Amazon S3 can return this header if your request involves a bucket that is either
replication- a source or destination in a cross-region replication.
status
In cross-region replication you have a source bucket on which you configure
replication and destination bucket where Amazon S3 stores object replicas.

375
Responses
Header Description
When you request an object (GET Object) or object metadata (HEAD Object)
from these buckets, Amazon S3 will return the x-amz-replication-status
header in the response as follow:
• If requesting object from the source bucket — Amazon S3 will return the x-
amz-replication-status header if object in your request is eligible for
replication.
For example, suppose in your replication configuration you specify object

prefix "TaxDocs" requesting Amazon S3 to replicate objects with key prefix
"TaxDocs". Then any objects you upload with this key name prefix, for example
"TaxDocs/document1.pdf", is eligible for replication. For any object request
with this key name prefix Amazon S3 will return the x-amz-replication-
status header with value PENDING, COMPLETED or FAILED indicating object
replication status.
• If requesting object from the destination bucket — Amazon S3 will return the
x-amz-replication-status header with value REPLICA if object in your
request is a replica that Amazon S3 created.
For more information, go to Cross-Region Replication in the Amazon Simple

Valid Values: PENDING, COMPLETED, FAILED, REPLICA
Type: String
x-amz-server- If the object is stored using server-side encryption either with an AWS KMS or an
side-encryption Amazon S3-managed encryption key, the response includes this header with the
value of the encryption algorithm used.
Type: String
x-amz- If the x-amz-server-side-encryption is present and has the value of

server-side- aws:kms, this header specifies the ID of the AWS Key Management Service
encryption-aws- (KMS) master encryption key that was used for the object.
kms-key-id
Type: String
x-amz-server- If server-side encryption with customer-provided encryption keys decryption

side-encryption was requested, the response will include this header confirming the decryption
-customer- algorithm used.
algorithm
Type: String
x-amz-server- If server-side encryption with customer-provided encryption keys decryption

side-encryption was requested, the response includes this header to provide roundtrip message
-customer-key- integrity verification of the customer-provided encryption key.
MD5
Type: String

376
Responses
Header Description
x-amz-storage- Provides storage class information of the object. Amazon S3 returns this header
class for all objects except for Standard storage class objects.
For more information, go to Storage Classes in Amazon Simple Storage Service

Developer Guide.
Type: String
Default: None
x-amz-restore Provides information about the object restoration operation and expiration time
of the restored object copy.
For more information about archiving objects and restoring them, go to

Transitioning Objects: General Considerations in the Amazon Simple Storage
Type: String
Default: None
x-amz-tagging- Returns the count of the tags associated with the object. This header is returned
count only if the count is greater than zero.
Type: String
Default: None
x-amz-version- Returns the version ID of the retrieved object if it has a unique version ID.
id
Type: String
Default: None
x-amz-website When a bucket is configured as a website, you can set this metadata on the
-redirect- object so the website endpoint will evaluate the request for the object as a 301
location redirect to another object in the same bucket or an external URL.
Type: String
Default: None
x-amz-object- The Object Lock mode, if any, that's in effect for this object. This header is only
lock-mode returned if the requester has the s3:GetObjectRetention permission. For
more information about S3 Object Lock, see Object Lock in the Amazon Simple
Type: String
Valid values: GOVERNANCE | COMPLIANCE
x-amz-object- The date and time when the Object Lock retention period expires. This header is
lock-retain- only returned if the requester has the s3:GetObjectRetention permission.
until-date
Type: Timestamp
Format: 2020-01-05T00:00:00.000Z

377
Examples
Header Description
x-amz-object- Specifies whether a legal hold is in effect for this object. This header is only
lock-legal-hold returned if the requester has the s3:GetObjectLegalHold permission. This
header is not returned if the specified version of this object has never had a legal
hold applied. For more information about legal holds, see Object Lock in the
Type: String
Valid values: ON | OFF
Response Elements
Special Errors
Examples
Sample Request
The following request returns the object, my-image.jpg.
GET /my-image.jpg HTTP/1.1

Date: Mon, 3 Oct 2016 22:32:00 GMT
Sample Response
HTTP/1.1 200 OK
Date: Mon, 3 Oct 2016 22:32:00 GMT
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
[434234 bytes of object data]
If the object had tags associated with it, Amazon S3 returns the x-amz-tagging-count header with
tag count.
HTTP/1.1 200 OK
Date: Mon, 3 Oct 2016 22:32:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
x-amz-tagging-count: 2

378
Examples
If the object had expiration set using lifecycle configuration, you get the following response with the x-
amz-expiration header.
HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-expiration: expiry-date="Fri, 23 Dec 2012 00:00:00 GMT", rule-id="picture-deletion-
rule"
ETag: "fba9dede5f27731c9771645a39863328"
Sample Response if an Object Is Archived in Glacier

An object archived in Glacier must first be restored before you can access it. If you attempt to access an
Glacier object without restoring it, Amazon S3 returns the following error.
HTTP/1.1 403 Forbidden

x-amz-request-id: CD4BD8A1310A11B3
x-amz-id-2: m9RDbQU0+RRBTjOUN1ChQ1eqMUnr9dv8b+KP6I2gHfRJZSTSrMCoRP8RtPRzX9mb
Date: Mon, 12 Nov 2012 23:53:21 GMT
Server: AmazonS3
Content-Length: 231
<Error>
<Code>InvalidObjectState</Code>
<Message>The operation is not valid for the object's storage class</Message>
<RequestId>9FEFFF118E15B86F</RequestId>
<HostId>WVQ5kzhiT+oiUfDCOiOYv8W4Tk9eNcxWi/MK+hTS/av34Xy4rBU3zsavf0aaaaa</HostId>
</Error>
Sample Response if the Latest Object Is a Delete Marker

HTTP/1.1 404 Not Found
x-amz-id-2: eftixk72aD6Ap51Tnqzj7UDNEHGran
x-amz-version-id: 3GL4kqtJlcpXroDTDm3vjVBH40Nr8X8g
x-amz-delete-marker: true
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3
Notice that the delete marker returns a 404 Not Found error.
Sample Request for Getting an Object Part

The following request returns the specified part of the object test.txt.
GET /test.txt?partNumber=1 HTTP/1.1

379
Examples
Date: Mon, 3 Oct 2016 22:32:00 GMT
Sample Response to an Object Part Request

HTTP/1.1 206 Partial Content
x-amz-id-2: 4lJovnctP+tyF27MwR7pAg0Y9Jgf0AVAL+pOhyJlWM4yCxwdbnilC/BlSVFxbmzIvjtgTPqLDrU=
x-amz-request-id: 8AC212BBF9DF3D33
Date: Thu, 28 Jun 2018 20:11:04 GMT
Last-Modified: Thu, 28 Jun 2018 19:16:25 GMT
ETag: "497db513b7b597ec93459bd2f3c9a452"
x-amz--mp-parts-count: 6
Accept-Ranges: bytes
Content-Range: bytes 0-121443838/876536789
Content-Type: binary/octet-stream
Sample Request Getting a Specified Version of an Object

The following request returns the specified version of an object.
GET /myObject?versionId=3/L4kqtJlcpXroDTDmpUMLUo HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
Sample Response to a Versioned Object GET Request

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap54OpIszj7UDNEHGran
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3QBpUMLUo
ETag: "fba9dede5f27731c9771645a39863328"
Connection: close
Server: AmazonS3
Sample Request with Parameters Altering Response Header

Values
The following request specifies all the query string parameters in a GET request overriding the response
header values.
GET /Junk3.txt?response-cache-control=No-cache&response-content-disposition=attachment%3B
%20filename%3Dtesting.txt&response-content-encoding=x-gzip&response-content-language=mi%2C
%20en&response-expires=Thu%2C%2001%20Dec%201994%2016:00:00%20GMT HTTP/1.1
x-amz-date: Sun, 19 Dec 2010 01:53:44 GMT
Accept: */*
Authorization: AWS AKIAIOSFODNN7EXAMPLE:aaStE6nKnw8ihhiIdReoXYlMamW=

380
Examples
Sample Response with Overridden Response Header Values

In the following sample response note, the header values are set to the values specified in the true
request.
HTTP/1.1 200 OK
x-amz-id-2: SIidWAK3hK+Il3/Qqiu1ZKEuegzLAAspwsgwnwygb9GgFseeFHL5CII8NXSrfWW2
x-amz-request-id: 881B1CBD9DF17WA1
Date: Sun, 19 Dec 2010 01:54:01 GMT
x-amz-meta-param1: value 1
x-amz-meta-param2: value 2
Cache-Control: No-cache
Content-Language: mi, en
Expires: Thu, 01 Dec 1994 16:00:00 GMT
Content-Disposition: attachment; filename=testing.txt
Content-Encoding: x-gzip
Last-Modified: Fri, 17 Dec 2010 18:10:41 GMT
ETag: "0332bee1a7bf845f176c5c0d1ae7cf07"
Content-Length: 22
Server: AmazonS3
[object data not shown]
Sample Request with a Range Header

The following request specifies the HTTP Range header to retrieve the first 10 bytes of an object. For
more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-
sec14.html.
GET /example-object HTTP/1.1

x-amz-date: Fri, 28 Jan 2011 21:32:02 GMT
Range: bytes=0-9
Authorization: AWS AKIAIOSFODNN7EXAMPLE:Yxg83MZaEgh3OZ3l0rLo5RTX11o=
Sample Response with Specified Range of the Object Bytes
Note
Amazon S3 doesn't support retrieving multiple ranges of data per GET request.
Sample Response
In the following sample response, note that the header values are set to the values specified in the true
request.

x-amz-id-2: MzRISOwyjmnupCzjI1WC06l5TTAzm7/JypPGXLh0OVFGcJaaO3KW/hRAqKOpIEEp
x-amz-request-id: 47622117804B3E11
Date: Fri, 28 Jan 2011 21:32:09 GMT
x-amz-meta-title: the title
Last-Modified: Fri, 28 Jan 2011 20:10:32 GMT
ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f"
Content-Length: 10
Server: AmazonS3

381
Related Resources
Sample: Get an Object Stored Using Server-Side Encryption

with Customer-Provided Encryption Keys
If an object is stored in Amazon S3 using server-side encryption with customer-provided encryption
keys, Amazon S3 needs encryption information so that it can decrypt the object before sending it to
you in response to a GET request. You provide the encryption information in your GET request using
the relevant headers (see Specific Request Headers for Server-Side Encryption with Customer-Provided
Encryption Keys (p. 374)), as shown in the following example request.
GET /example-object HTTP/1.1

Accept: */*
Authorization:authorization string
Date: Wed, 28 May 2014 19:24:44 +0000
x-amz-server-side-encryption-customer-key:g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEKEXAMPLE
x-amz-server-side-encryption-customer-key-MD5:ZjQrne1X/iTcskbY2m3example
x-amz-server-side-encryption-customer-algorithm:AES256
The following sample response shows some of the response headers Amazon S3 returns. Note that it
includes the encryption information in the response.
HTTP/1.1 200 OK
x-amz-id-2: ka5jRm8X3N12ZiY29Z989zg2tNSJPMcK+to7jNjxImXBbyChqc6tLAv+sau7Vjzh
x-amz-request-id: 195157E3E073D3F9
Date: Wed, 28 May 2014 19:24:45 GMT
Last-Modified: Wed, 28 May 2014 19:21:01 GMT
ETag: "c12022c9a3c6d3a28d29d90933a2b096"
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2m3example
Related Resources
• GET Service (p. 65)

382
GET Object ACL
GET Object ACL

Description
This implementation of the GET operation uses the acl subresource to return the access control list
(ACL) of an object. To use this operation, you must have READ_ACP access to the object.
Versioning
By default, GET returns ACL information about the current version of an object. To return ACL
information about a different version, use the versionId subresource.
To see sample requests that use Versioning, see Sample Request Getting the ACL of the Specific Version
of an Object (p. 385).
Requests
Syntax
GET /ObjectName?acl HTTP/1.1
Date: date
4))
Range:bytes=byte_range
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
AccessControlList Container for Grant, Grantee, and Permission.

383
Responses
Name Description
Type: Container
AccessControlPolicy Contains the elements that set the ACL permissions for an object per
Grantee.
Type: Container
Ancestors: None
DisplayName Screen name of the bucket owner.

Important
(Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo), EU (Ireland),
and South America (São Paulo) regions.
For a list of all the Amazon S3 supported regions and endpoints,
see Regions and Endpoints in the AWS General Reference.
Type: String
Grant Container for the grantee and his or her permissions.
Type: Container
Grantee The subject whose permissions are being set.
Type: String
Ancestors: AccessControlPolicy.AccessControlList.Grant
ID ID of the bucket owner, or the ID of the grantee.
Type: String
Ancestors: AccessControlPolicy.Owner or
Owner Container for the bucket owner's display name and ID.
Type: Container
Permission Specifies the permission (FULL_CONTROL, WRITE, READ_ACP) given to the

grantee.
Type: String

384
Examples
Special Errors
Examples
Sample Request
The following request returns information, including the ACL, of the object, my-image.jpg.
GET /my-image.jpg?acl HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
Sample Response
HTTP/1.1 200 OK
x-amz-version-id: 4HL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nrjfkd
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 124
Connection: close
Server: AmazonS3
<Owner>
</Owner>
<AccessControlList>
<Grant>
</Grantee>
</Grant>
Sample Request Getting the ACL of the Specific Version of an

Object
The following request returns information, including the ACL, of the specified version of the object, my-
image.jpg.
GET /my-image.jpg?versionId=3/L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo&acl HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT

385
Related Resources
Sample Response Showing the ACL of the Specific Version

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Content-Length: 124
Connection: close
Server: AmazonS3
<Owner>
<DisplayName>mdtd@amazon.com</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<DisplayName>mdtd@amazon.com</DisplayName>
</Grantee>
</Grant>
Related Resources

386
GET Object legal hold
GET Object legal hold

Gets an object's current Legal Hold status.
Request Syntax
GET /<object-key>?legal-hold&versionId=<version-id> HTTP/1.1
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
4))

versionId
The version ID for the object version whose retention settings you want to retrieve.
Request Body
Response Syntax
HTTP/1.1 200
<LegalHold>
</LegalHold>
Response Elements
For more information about the response elements that this operation returns, see
ObjectLockLegalHold (p. 545).
Related Resources

387
GET Object retention
GET Object retention

Retrieves an object's retention settings.
Request Syntax
GET /<object-key>?retention&versionId=<version-id> HTTP/1.1
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
4))

versionId
The version ID for the object version whose retention settings you want to retrieve.
Request Body
Response Syntax
<Retention>
<Mode><value></Mode>
<RetainUntilDate><value></RetainUntilDate>
</Retention>
Response Elements
For more information about the response elements this operation returns, see
ObjectLockRetention (p. 546).
Related Resources

388
GET Object tagging
GET Object tagging

Description
This implementation of the GET operation returns the tags associated with an object. You send the GET
request against the tagging subresource associated with the object.
To use this operation, you must have permission to perform the s3:GetObjectTagging action.
By default, the GET operation returns information about current version of an object. For a
versioned bucket, you can have multiple versions of an object in your bucket. To retrieve tags
of any other version, use the versionId query parameter. You also need permission for the
s3:GetObjectVersionTagging action.
By default, the bucket owner has this permission and can grant this permission to others.
For information about the Amazon S3 object tagging feature, see Object Tagging in the Amazon Simple
Requests
Syntax
GET /ObjectName?tagging HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
Tagging Container for the TagSet element.

389
Examples
Name Description
Type: Container
Ancestors: None
TagSet Contains the tag set.
Type: Container
Ancestors: Tagging
Tag Contains the tag information.
Type: Container
Ancestors: TagSet
Key Name of the tag
Type: String
Ancestors: Tag
Value Value of the tag
Type: String
Ancestors: Tag
Examples
Sample Request
The following request returns the tag set of the specified object.
GET /example-object?tagging HTTP/1.1

Date: Thu, 22 Sep 2016 21:33:08 GMT
Sample Response
HTTP/1.1 200 OK
Date: Thu, 22 Sep 2016 21:33:08 GMT
Connection: close
Server: AmazonS3
<Tagging xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<TagSet>
<Tag>
<Key>tag1</Key>
<Value>val1</Value>
</Tag>
<Tag>
<Key>tag2</Key>
<Value>val2</Value>
</Tag>
</TagSet>

390
Related Resources
</Tagging>
Related Resources

391
GET Object torrent
GET Object torrent

Description
This implementation of the GET operation uses the torrent subresource to return torrent files from
a bucket. BitTorrent can save you bandwidth when you're distributing large files. For more information
about BitTorrent, see Amazon S3 Torrent.
Note
You can get torrent only for objects that are less than 5 GB in size and that are not encrypted
using server-side encryption with customer-provided encryption key.
To use GET, you must have READ access to the object.
Requests
Syntax
GET /ObjectName?torrent HTTP/1.1
Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Special Errors

392
Examples
Examples
Getting Torrent Files in a Bucket
This example retrieves the Torrent file for the "Nelson" object in the "quotes" bucket.
GET /quotes/Nelson?torrent HTTP/1.0

Date: Wed, 28 Oct 2009 22:32:00 GMT
Sample Response
HTTP/1.1 200 OK
x-amz-request-id: 7CD745EBB7AB5ED9
Date: Wed, 25 Nov 2009 12:00:00 GMT
Content-Disposition: attachment; filename=Nelson.torrent;
Content-Type: application/x-bittorrent
Content-Length: 537
Server: AmazonS3
<body: a Bencoded dictionary as defined by the BitTorrent specification>
Related Resources

393
HEAD Object
HEAD Object
Description
The HEAD operation retrieves metadata from an object without returning the object itself. This operation
is useful if you are interested only in an object's metadata. To use HEAD, you must have READ access to
the object.
A HEAD request has the same options as a GET operation on an object. The response is identical to the
GET response except that there is no response body.
If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-
C) when you store the object in Amazon S3, then when you retrieve the metadata from the object, you
must use the headers documented in the section Specific Request Headers for Server-Side Encryption
with Customer-Provided Encryption Keys (p. 397). For more information about SSE-C, go to Server-
Side Encryption (Using Customer-Provided Encryption Keys) in the Amazon Simple Storage Service
Developer Guide.
Permissions
You need the s3:GetObject permission for this operation. For more information, go to Specifying
Permissions in a Policy in the Amazon Simple Storage Service Developer Guide. If the object you request
does not exist, the error Amazon S3 returns depends on whether you also have the s3:ListBucket
permission.
• If you have the s3:ListBucket permission on the bucket, Amazon S3 will return a HTTP status code
404 ("no such key") error.
• If you don’t have the s3:ListBucket permission, Amazon S3 will return a HTTP status code 403
("access denied") error.
Versioning
By default, the HEAD operation retrieves metadata from the current version of an object. If the current
version is a delete marker, Amazon S3 behaves as if the object was deleted. To retrieve metadata from
a different version, use the versionId subresource. For more information, see Versions in the Amazon
To see sample requests that use versioning, see Sample Request Getting Metadata from a Specified
Version of an Object (p. 402).
Requests
Syntax
HEAD /ObjectName HTTP/1.1
4))
Date: date

394
Requests
Request Parameters
partNumber Part number of the object part being read. This is a No

positive integer between 1 and the maximum number of
parts supported.
Only objects uploaded using the multipart upload API

have part numbers. For information about multipart
uploads, see Multipart Upload Overview in the Amazon
Effectively performs a 'ranged' HEAD request for the part

specified. Useful for downloading just a part of an object.
Type: Integer
Default: None
versionId Version ID used to reference a specific version of the No

object.
Type: String
Default: None
Request Headers
Range Downloads the specified range bytes of an object. For more No

information about the HTTP Range header, go to http://
Type: String
Default: None
Constraints: None
If-Modified- Return the object only if it has been modified since the specified No
Since time, otherwise return a 304 (not modified).
Type: String
Default: None
Constraints: None

395
Requests
If-Unmodified- Return the object only if it has not been modified since the No
Since specified time, otherwise return a 412 (precondition failed).
Type: String
Default: None
Constraints: None
If-Match Return the object only if its entity tag (ETag) is the same as the No
one specified; otherwise, return a 412 (precondition failed).
Type: String
Default: None
Constraints: None
If-None-Match Return the object only if its entity tag (ETag) is different from the No
one specified; otherwise, return a 304 (not modified).
Type: String
Default: None
Constraints: None
Note
Encryption request headers, like x-amz-server-side-encryption, should not be sent for
GET requests if your object uses server-side encryption with AWS KMS–managed encryption
keys (SSE-KMS) or server-side encryption with Amazon S3–managed encryption keys (SSE-S3). If
your object does use these types of keys, you’ll get an HTTP 400 BadRequest error.
• Consideration 1 – If both of the If-Match and If-Unmodified-Since headers are present in the
request as follows:
If-Match condition evaluates to true, and;
If-Unmodified-Since condition evaluates to false;
then, Amazon S3 returns 200 OK and the data requested. For more information about conditional
requests, see RFC 7232.

• Consideration 2 – If both of the If-None-Match and If-Modified-Since headers are present in
the request as follows:
If-None-Match condition evaluates to false, and;

396
Requests
If-Modified-Since condition evaluates to true;
then, Amazon S3 returns the 304 Not Modified response code. For more information about
conditional requests, see RFC 7232.
Specific Request Headers for Server-Side Encryption with Customer-Provided

Encryption Keys
When you retrieve metadata from an object stored in Amazon S3 that was encrypted by using server-
side encryption with customer-provided encryption keys (SSE-C), you must use the following request
headers. For more information about SSE-C, go to Server-Side Encryption (Using Customer-Provided
Encryption Keys) in the Amazon Simple Storage Service Developer Guide.
x-amz-server- Specifies the algorithm to use to when decrypting the requested Yes
side-encryption object.
-customer-
Default: None

side-encryption-customer-key and x-amz-server-side-

side-encryption key to use to decrypt the requested object. This value is used to
-customer-key perform the decryption and then it is discarded; Amazon does
not store the key. The key must be appropriate for use with the
algorithm specified in the x-amz-server-side-encryption-
customer-algorithm header.
Type: String
Default: None

x-amz-server- Specifies the base64-encoded 128-bit MD5 digest of the No

side-encryption customer-provided encryption key according to RFC 1321. If
-customer-key- this header is included in your request, Amazon S3 uses it for a
MD5 message integrity check to ensure that the encryption key was
transmitted without error.
Type: String
Default: None

side-encryption-customer-key headers.

397
Responses
Request Elements
Responses
Response Headers
This implementation of the operation can include the following response headers in addition to the
response headers common to all responses. For more information, see Common Response Headers (p. 4).
Name Description
x-amz-expiration Amazon S3 returns this header if an Expiration action is configured

for the object as part of the bucket's lifecycle configuration. The header
value includes an "expiry-date" component and a URL-encoded "rule-id"
component. Note that for versioning-enabled buckets, this header applies
only to current versions; Amazon S3 does not provide a header to infer
when a noncurrent version is eligible for permanent deletion. For more
information, see PUT Bucket lifecycle (p. 290).
Type: String
x-amz-meta-* Headers starting with this prefix are user-defined metadata. Each one is
stored and returned as a set of key-value pairs. Amazon S3 doesn't validate
or interpret user-defined metadata.
Type: String
x-amz-missing-meta This header is set to the number of metadata entries that were not
returned in x-amz-meta headers. This can happen if you create metadata
using an API like SOAP that supports more flexible metadata than the REST
API. For example, with SOAP, you can create metadata with values that are
not valid HTTP headers.
Type: String
x-amz-replication- Amazon S3 can return this header if your request involves a bucket that is
status either a source or destination in a cross-region replication.
In cross-region replication, you have a source bucket on which you

configure replication and destination bucket where Amazon S3 stores
object replicas. When you request an object (GET Object) or object
metadata (HEAD Object) from these buckets, Amazon S3 returns the x-
amz-replication-status header in the response as follows:
• If requesting object from the source bucket — Amazon S3 returns the x-

amz-replication-status header if object in your request is eligible
for replication.
For example, suppose that in your replication configuration you specify

object prefix "TaxDocs" requesting Amazon S3 to replicate objects
with key prefix "TaxDocs". Then any objects you upload with this key
name prefix, for example "TaxDocs/document1.pdf", is eligible for
replication. For any object request with this key name prefix, Amazon S3
returns the x-amz-replication-status header with value PENDING,
COMPLETED, or FAILED indicating object replication status.

398
Responses
Name Description
• If requesting object from the destination bucket — Amazon S3 returns
the x-amz-replication-status header with value REPLICA if object
in your request is a replica that Amazon S3 created.
For more information, see Cross-Region Replication in the Amazon Simple

Valid Values: PENDING, COMPLETED, FAILED, REPLICA
Type: String
x-amz-restore If the object is an archived object (an object whose storage class is
GLACIER), the response includes this header if either the archive
restoration is in progress (see POST Object restore (p. 419)) or an archive
copy is already restored.
If an archive copy is already restored, the header value indicates when

Amazon S3 is scheduled to delete the object copy. For example,
x-amz-restore: ongoing-request="false", expiry-date="Fri,

23 Dec 2012 00:00:00 GMT"
If the object restoration is in progress, the header returns the value

ongoing-request="true".
For more information about archiving objects, see Transitioning Objects:

General Considerations in the Amazon Simple Storage Service Developer
Guide
Type: String
Default: None
x-amz-server-side- If the object is stored using server-side encryption either with an AWS
encryption KMS or an Amazon S3-managed encryption key, the response includes this
header with the value of the encryption algorithm used.
Type: String
x-amz-server-side- If the x-amz-server-side-encryption is present and has the value of

encryption-aws-kms- aws:kms, this header specifies the ID of the AWS KMS master encryption
key-id key that was used for the object.
Type: String
x-amz-server- If server-side encryption with customer-provided encryption keys(SSE-C)

side-encryption- decryption was requested, the response includes this header confirming the
customer-algorithm decryption algorithm used.
Type: String

399
Responses
Name Description
x-amz-server- If SSE-C decryption was requested, the response includes this header to
side-encryption- provide roundtrip message integrity verification of the customer-provided
customer-key-MD5 encryption key.
Type: String
x-amz-storage-class Provides storage class information of the object. Amazon S3 returns this
header for all objects except for Standard storage class objects.
For more information, see Storage Classes in the Amazon Simple Storage
Type: String
Default: None
x-amz-version-id The version ID of the object returned.
Type: String
x-amz-object-lock- The Object Lock mode, if any, that's in effect for this object. This header
mode is only returned if the requester has the s3:GetObjectRetention
permission. For more information about S3 Object Lock, see Object Lock in
Type: String
x-amz-object-lock- The date and time when the Object Lock retention period expires. This
retain-until-date header is only returned if the requester has the s3:GetObjectRetention
permission.
Type: Timestamp
Format: 2020-01-05T00:00:00.000Z
x-amz-object-lock- Specifies whether a legal hold is in effect for this object. This header is only
legal-hold returned if the requester has the s3:GetObjectLegalHold permission.
This header is not returned if the specified version of this object has never
had a legal hold applied. For more information about legal holds, see
Object Lock in the Amazon Simple Storage Service Developer Guide.
Type: String
Response Elements
Response Elements

400
Examples
Special Errors
Examples
Sample Request
The following request returns the metadata of an object.
HEAD /my-image.jpg HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0RonhpaBX5sCYVf1bNRuU=
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: ef8yU9AS1ed4OpIszj7UDNEHGran
x-amz-version-id: 3HL4kqtJlcpXroDTDmjVBH40Nrjfkd
Date: Wed, 28 Oct 2009 22:32:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Connection: close
Server: AmazonS3
If the object is scheduled to expire according to a lifecycle configuration set on the bucket, the response
returns the x-amz-expiration tag with information about when Amazon S3 will delete the object.
For more information, see Transitioning Objects: General Considerations in the Amazon Simple Storage
HTTP/1.1 200 OK
x-amz-id-2: azQRZtQJ2m1P8R+TIsG9h0VuC/DmiSJmjXUMq7snk+LKSJeurtmfzSlGhR46GzSJ
x-amz-request-id: 0EFF61CCE3F24A26
Date: Mon, 17 Dec 2012 02:26:39 GMT
Last-Modified: Mon, 17 Dec 2012 02:14:10 GMT
x-amz-expiration: expiry-date="Fri, 21 Dec 2012 00:00:00 GMT", rule-id="Rule for
testfile.txt"
ETag: "54b0c58c7ce9f2a8b551351102ee0938"
Content-Length: 14
Server: AmazonS3
Sample Request for Getting Metadata from an Object Part

The following request returns the meteadata for the specified part of the object test.txt.
HEAD /test.txt?partNumber=1 HTTP/1.1

Date: Wed, 12 Jun 2019 16:52:50 GMT

401
Sample Request for an Glacier Object
Sample Response to an Object Part HEAD Request

x-amz-id-2: oMGCGCG2SFoQ//zIZ/7zCrGI1bIa+STIEhXLeFVbYnoVszvgXHepSQuJ3U/kFBNiLFhZbqlhevQ=
x-amz-request-id: 82291A7EE7DD9E30
Date: Wed, 12 Jun 2019 16:52:53 GMT
Last-Modified: Mon, 06 Mar 2017 21:21:28 GMT
ETag: "46ea6cc5c77a33c569e5700f0ca465d8-2"
x-amz-mp-parts-count: 2
x-amz-version-id: null
Server: AmazonS3
Sample Request Getting Metadata from a Specified Version of

an Object
The following request returns the metadata of the specified version of an object.
HEAD /my-image.jpg?versionId=3HL4kqCxf3vjVBH40Nrjfkd HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0WpaBX5sCYVf1bNRuU=
Sample Response to a Versioned HEAD Request

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8epIszj7UDNEHGran
x-amz-version-id: 3HL4kqtJlcpXrof3vjVBH40Nrjfkd
Date: Wed, 28 Oct 2009 22:32:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Connection: close
Server: AmazonS3
Sample Request for an Glacier Object

For an archived object, the x-amz-restore header provides the date when the restored copy expires,
as shown in the following response. Even if the object is stored in Glacier, all object metadata is still
available.
HEAD /my-image.jpg HTTP/1.1

Date: 13 Nov 2012 00:28:38 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0RonhpaBX5sCYVf1bNRuU=
Sample Response - Glacier Object

If the object is already restored, the x-amz-restore header provides the date when the restored copy
will expire, as shown in the following response.

402
Related Resources
HTTP/1.1 200 OK
x-amz-id-2: FSVaTMjrmBp3Izs1NnwBZeu7M19iI8UbxMbi0A8AirHANJBo+hEftBuiESACOMJp
x-amz-request-id: E5CEFCB143EB505A
Date: Tue, 13 Nov 2012 00:28:38 GMT
Last-Modified: Mon, 15 Oct 2012 21:58:07 GMT
x-amz-restore: ongoing-request="false", expiry-date="Wed, 07 Nov 2012 00:00:00 GMT"
ETag: "1accb31fcf202eba0c0f41fa2f09b4d7"
Content-Length: 300
Server: AmazonS3
If the restoration is in progress, then the x-amz-restore header returns a message accordingly.
HTTP/1.1 200 OK
x-amz-id-2: b+V2mDiMHTdy1myoUBpctvmJl95H9U/OSUm/jRtHxjh0+pCk5SvByL4xu2TDv4GM
x-amz-request-id: E2E7B6AEE4E9BD2B
Date: Tue, 13 Nov 2012 00:43:32 GMT
Last-Modified: Sat, 20 Oct 2012 21:28:27 GMT
x-amz-restore: ongoing-request="true"
ETag: "1accb31fcf202eba0c0f41fa2f09b4d7"
Content-Length: 300
Server: AmazonS3
Related Resources

403
OPTIONS object
OPTIONS object
Description
A browser can send this preflight request to Amazon S3 to determine if it can send an actual request
with the specific origin, HTTP method, and headers.
Amazon S3 supports cross-origin resource sharing (CORS) by enabling you to add a cors subresource on
a bucket. When a browser sends this preflight request, Amazon S3 responds by evaluating the rules that
are defined in the cors configuration.
If cors is not enabled on the bucket, then Amazon S3 returns a 403 Forbidden response.
For more information about CORS, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple
Requests
Syntax
OPTIONS /ObjectName HTTP/1.1
Origin: Origin
Access-Control-Request-Method: HTTPMethod
Access-Control-Request-Headers: RequestHeader
Request Parameters
This operation does not introduce any specific request parameters, but it may contain any request
parameters that are required by the actual request.
Request Headers
Origin Identifies the origin of the cross-origin request to Amazon S3. Yes
For example, http://www.example.com.
Type: String
Default: None
Access-Control- Identifies what HTTP method will be used in the actual request. Yes
Request-Method
Type: String
Default: None
Access-Control- A comma-delimited list of HTTP headers that will be sent in the No

Request-Headers actual request.
For example, to put an object with server-side encryption, this

preflight request will determine if it can include the x-amz-
server-side-encryption header with the request.

404
Responses

Type: String
Default: None
Request Elements
Responses
Response Headers
Header Description
Access-Control-Allow- The origin you sent in your request. If the origin in your request is not
Origin allowed, Amazon S3 will not include this header in the response.
Type: String
Access-Control-Max-Age How long, in seconds, the results of the preflight request can be
cached.
Type: String
Access-Control-Allow- The HTTP method that was sent in the original request. If the
Methods method in the request is not allowed, Amazon S3 will not include this
header in the response.
Type: String
Access-Control-Allow- A comma-delimited list of HTTP headers that the browser can send
Headers in the actual request. If any of the requested headers is not allowed,
Amazon S3 will not include that header in the response, nor will the
response contain any of the headers with the Access-Control
prefix.
Type: String
Access-Control-Expose- A comma-delimited list of HTTP headers. This header provides the

Headers JavaScript client with access to these headers in the response to the
actual request.
Type: String
Response Elements

405
Examples
Examples
Example : Send a preflight OPTIONS request to a cors enabled
bucket
A browser can send this preflight request to Amazon S3 to determine if it can send the actual PUT
request from http://www.example.com origin to the Amazon S3 bucket named examplebucket.
Sample Request
OPTIONS /exampleobject HTTP/1.1

Origin: http://www.example.com
Access-Control-Request-Method: PUT
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: 6SvaESv3VULYPLik5LLl7lSPPtSnBvDdGmnklX1HfUl7uS2m1DF6td6KWKNjYMXZ
x-amz-request-id: BDC4B83DF5096BBE
Date: Wed, 21 Aug 2012 23:09:55 GMT
Etag: "1f1a1af1f1111111111111c11aed1da1"
Access-Control-Allow-Origin: http://www.example.com
Access-Control-Allow-Methods: PUT
Access-Control-Expose-Headers: x-amz-request-id
Content-Length: 0
Server: AmazonS3
Related Resources

406
POST Object
POST Object
Description
The POST operation adds an object to a specified bucket using HTML forms. POST is an alternate form
of PUT that enables browser-based uploads as a way of putting objects in buckets. Parameters that are
passed to PUT via HTTP Headers are instead passed as form fields to POST in the multipart/form-data
encoded message body. You must have WRITE access on a bucket to add an object to it. Amazon S3
never stores partial objects: if you receive a successful response, you can be confident the entire object
was stored.
Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests for the same object
simultaneously, all but the last object written is overwritten.
To ensure that data is not corrupted traversing the network, use the Content-MD5 form field. When you
use this form field, Amazon S3 checks the object against the provided MD5 value. If they do not match,
Amazon S3 returns an error. Additionally, you can calculate the MD5 value while posting an object to
Amazon S3 and compare the returned ETag to the calculated MD5 value. The ETag only reflects changes
Note
To configure your application to send the Request Headers before sending the request body,
use the 100-continue HTTP status code. For POST operations, this helps you avoid sending the
message body if the message is rejected based on the headers (for example, authentication
failure or redirect). For more information on the 100-continue HTTP status code, go to Section
8.2.3 of http://www.ietf.org/rfc/rfc2616.txt.
You can optionally request server-side encryption where Amazon S3 encrypts your data as it writes it
to disks in its data centers and decrypts it for you when you access it. You have the option of providing
your own encryption key or you can use the AWS-managed encryption keys. For more information, go to
Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide.
Versioning
If you enable versioning for a bucket, POST automatically generates a unique version ID for the object
being added. Amazon S3 returns this ID in the response using the x-amz-version-id response header.
If you suspend versioning for a bucket, Amazon S3 always uses null as the version ID of the object
stored in a bucket.
For more information about returning the versioning state of a bucket, see GET Bucket (Versioning
Status) (p. 224).
Amazon S3 is a distributed system. If you enable versioning for a bucket and Amazon S3 receives
multiple write requests for the same object simultaneously, all of the objects are stored.
To see sample requests that use versioning, see Sample Request (p. 417).
Requests
Syntax
POST / HTTP/1.1
Host: destinationBucket.s3.amazonaws.com
User-Agent: browser_data

407
Requests
Accept: file_types
Accept-Language: Regions
Accept-Encoding: encoding
Accept-Charset: character_set
Keep-Alive: 300
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
acl
--9431149156168
Content-Disposition: form-data; name="tagging"
<Tagging><TagSet><Tag><Key>Tag Name</Key><Value>Tag Value</Value></Tag></TagSet></Tagging>

--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Type"
content_type
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-uuid"
uuid
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="AWSAccessKeyId"
access-key-id
--9431149156168
Content-Disposition: form-data; name="Policy"
encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"
signature=
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg
file_content
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to Amazon S3
--9431149156168--
Request Parameters
Form Fields
This operation can use the following form fields.

408
Requests
AWSAccessKeyId The AWS access key ID of the owner of the bucket who Conditional
grants an Anonymous user access for a request that
satisfies the set of constraints in the policy.
Type: String
Default: None
Constraints: Required if a policy document is included

with the request.
acl Specifies an Amazon S3 access control list. If an invalid No

access control list is specified, an error is generated.
For more information on ACLs, go to Access Control
List (ACL) Overview in the Amazon Simple Storage
Type: String
Default: private
Valid Values: private | public-read |

public-read-write | aws-exec-read |
authenticated-read | bucket-owner-read |
bucket-owner-full-control
Cache-Control, Content- REST-specific headers. For more information, see PUT No

Type, Content- Object (p. 434).
Disposition, Content-
Encoding, Expires Type: String
Default: None
file File or text content. Yes
The file or text content must be the last field in the

form.
You cannot upload more than one file at a time.
Type: File or text content
Default: None
key The name of the uploaded key. Yes
To use the file name provided by the user, use the

${filename} variable. For example, if the user Betty
uploads the file lolcatz.jpg and you specify /
user/betty/${filename}, the key name is /user/
betty/lolcatz.jpg.
For more information, go to Object Key and Metadata

Type: String
Default: None

409
Requests
policy Security Policy describing what is permitted in the Conditional

request. Requests without a security policy are
considered anonymous and work only on publicly
writable buckets. For more information, go to HTML
Forms and Upload Examples.
Type: String
Default: None
Constraints: Policy is required if the bucket is not

publicly writable.
success_action_redirect, The URL to which the client is redirected upon No

redirect successful upload.
If success_action_redirect is not specified,

Amazon S3 returns the empty document type specified
in the success_action_status field.
If Amazon S3 cannot interpret the URL, it acts as if the

field is not present.
If the upload fails, Amazon S3 displays an error and

does not redirect the user to a URL.
Type: String
Default: None
Note
The redirect field name is deprecated, and
support for the redirect field name is removed
in the future.

410
Requests
success_action_status If you don't specify success_action_redirect, the No

status code is returned to the client when the upload
succeeds.
Accepts the values 200, 201, or 204 (the default).
If the value is set to 200 or 204, Amazon S3 returns an

empty document with a 200 or 204 status code.
If the value is set to 201, Amazon S3 returns an XML

document with a 201 status code.
If the value is not set or if it is set to an invalid value,

Amazon S3 returns an empty document with a 204
status code.
Type: String
Default: None
Note
Some versions of the Adobe Flash player
do not properly handle HTTP responses
with an empty body. To support uploads
through Adobe Flash, we recommend setting
success_action_status to 201.
tagging Specifies set of tags to add to the object using the No

following encoding scheme.
<Tagging>
<TagSet>
<Tag>
<Key>Tag Name</Key>
</Tag>
...
</TagSet>
</Tagging>
For more information, see Object Tagging in the

Type: String
Default: None

411
Requests
x-amz-storage-class Storage class to use for storing the object. If you don't No
specify a class, Amazon S3 uses the default storage
class, STANDARD. Amazon S3 supports other storage
classes. For more information, see Storage Classes in
Type: String
Default: STANDARD

x-amz-meta-* Headers starting with this prefix are user-defined No

metadata. Each one is stored and returned as a
set of key-value pairs. Amazon S3 doesn't validate
or interpret user-defined metadata. For more
information, see PUT Object (p. 434).
Type: String
Default: None
x-amz-security-token Amazon DevPay security token. No
Each request that uses Amazon DevPay requires two

x-amz-security-token form fields: one for the
product token and one for the user token.
Type: String
Default: None

412
Requests
x-amz-website-redirect- If the bucket is configured as a website, redirects No

location requests for this object to another object in the same
bucket or to an external URL. Amazon S3 stores
the value of this header in the object metadata. For
information about object metadata, see Object Key
and Metadata.
In the following example, the request header sets the

redirect to an object (anotherPage.html) in the
same bucket:
x-amz-website-redirect-location: /
anotherPage.html
In the following example, the request header sets the

object redirect to another website:
x-amz-website-redirect-location: http://
www.example.com/
For more information about website hosting in

Amazon S3, see Hosting Websites on Amazon S3
and How to Configure Website Page Redirects in the
Type: String
Default: None
Constraints: The value must be prefixed by, "/",

"http://" or "https://". The length of the value is
limited to 2 K.
Server-Side Encryption Specific Request Form Fields

You can optionally request Amazon S3 to encrypt data at rest using server-side encryption. Server-side
encryption is data encryption at rest. Amazon S3 encrypts your data as it writes it to disks in its data
centers and decrypts it when you access it.
For more information, see Protecting Data Using Server-Side Encryption in the Amazon Simple Storage
Depending on whether you want to use AWS-managed encryption keys or provide your own encryption
keys, the following form fields:
• Use AWS-managed encryption keys — If you want Amazon S3 to manage keys used to encrypt data,
specify the following form fields in the request.
x-amz-server- Specifies a server-side encryption algorithm to use when Yes

side-encryption Amazon S3 creates an object.
Type: String

413
Requests

Valid Value: aws:kms, AES256
x-amz-server- If the x-amz-server-side-encryption is present and has Yes, if the

side-encryption- the value of aws:kms, this header specifies the ID of the AWS value of
aws-kms-key-id Key Management Service (AWS KMS) master encryption key x-amz-
that was used for the object. server-
side-
Type: String encryption
is
aws:kms
x-amz-server- If x-amz-server-side-encryption is present, and if its No

side-encryption- value is aws:kms, this header specifies the encryption context
context for the object. The value of this header is a base64-encoded
UTF-8 string holding JSON with the key-value pairs for the
encryption context.
Type: String
Note
If you specify x-amz-server-side-encryption:aws:kms, but do not provide x-amz-
server-side- encryption-aws-kms-key-id, Amazon S3 uses the default AWS KMS key
to protect the data.
• Use customer-provided encryption keys — If you want to manage your own encryption keys, you must
provide all the following form fields in the request.
Note
If you use this feature, the ETag value that Amazon S3 returns in the response is not the MD5
of the object.
x-amz-server- Specifies the algorithm to use to when encrypting the object. Yes
side-encryption-
customer- Type: String
algorithm
Default: None
Valid Value: AES256

side-encryption-customer-key and x-amz-server-
side-encryption-customer-key-MD5 fields.

side-encryption- key for Amazon S3 to use in encrypting data. This value is used
customer-key to store the object and then it is discarded. Amazon does not
store the encryption key. The key must be appropriate for use
with the algorithm specified in the x-amz-server-side-
encryption-customer-algorithm header.
Type: String
Default: None

414
Requests

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key-MD5 fields.
x-amz-server- Specifies the base64-encoded 128-bit MD5 digest of the Yes

side-encryption- encryption key according to RFC 1321. Amazon S3 uses this
customer-key-MD5 header for a message integrity check to ensure that the
encryption key was transmitted without error.
Type: String
Default: None

server-side-encryption-customer-key fields.
Responses
Response Headers
Name Description
x-amz-expiration If an Expiration action is configured for the object

as part of the bucket's lifecycle configuration, Amazon
S3 returns this header. The header value includes an
"expiry-date" component and a URL-encoded "rule-id"
component. For version-enabled buckets, this header
applies only to current versions. Amazon S3 does not
provide a header to infer when a noncurrent version is
eligible for permanent deletion. For more information,
see PUT Bucket lifecycle (p. 290).
Type: String
success_action_redirect, The URL to which the client is redirected on successful

redirect upload.
Type: String
Ancestor: PostResponse
x-amz-server-side-encryption If you specified server-side encryption either with AWS

KMS encryption or AWS-managed encryption in your
POST request, the response includes this header. It
confirms the encryption algorithm that Amazon S3 used
to encrypt the object.
Type: String
x-amz-server-side-encryption- If the x-amz-server-side-encryption header is

aws-kms-key-id present and has the value of aws:kms, this header

415
Requests
Name Description
specifies the ID of the AWS KMS master encryption key
that was used for the object.
Type: String
x-amz-server-side-encryption- If server-side encryption with customer-provided

customer-algorithm encryption keys (SSE-C) encryption was requested,
the response includes this header that confirms the
encryption algorithm that was used.
Type: String
x-amz-server-side-encryption- If SSE-C encryption was requested, the response includes

customer-key-MD5 this header to verify roundtrip message integrity of the
customer-provided encryption key.
Type: String
x-amz-version-id Version of the object.
Type: String
Response Elements
Name Description
Bucket Name of the bucket the object was stored in.
Type: String
ETag The entity tag is an MD5 hash of the object that you can use to
do conditional GET operations using the If-Modified request
tag with the GET request operation. ETag reflects changes only
Type: String
Key The object key name.
Type: String
Location URI of the object.
Type: String

416
Examples
Special Errors
Examples
Sample Request
POST /Neo HTTP/1.1
Content-Length: 4
Date: Wed, 01 Mar 2006 12:00:00 GMT
Expect: the 100-continue HTTP status code
ObjectContent
Sample Response with Versioning Suspended

The following is a sample response when bucket versioning is suspended:

HTTP/1.1 200 OK
x-amz-version-id: default
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server: AmazonS3
In this response, the version ID is null.
Sample Response with Versioning Enabled

The following is a sample response when bucket versioning is enabled.

HTTP/1.1 200 OK
x-amz-version-id: 43jfkodU8493jnFJD9fjj3HHNVfdsQUIFDNsidf038jfdsjGFDSIRp
Date: Wed, 01 Mar 2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Length: 0
Connection: close
Server: AmazonS3
Related Resources

417
Related Resources

418
POST Object restore
POST Object restore

Description
This operation performs the following types of requests:
• select – Perform a select query on an archived object

• restore an archive – Restore an archived object
To use this operation, you must have permissions to perform the s3:RestoreObject and
s3:GetObject actions. The bucket owner has this permission by default and can grant this permission
Querying Archives with Select Requests

You use a select type of request to perform SQL queries on archived objects. The archived objects that
are being queried by the select request must be formatted as uncompressed comma-separated values
(CSV) files. You can run queries and custom analytics on your archived data without having to restore
your data to a hotter Amazon S3 tier. For an overview about select requests, see Querying Archived
Objects in the Amazon Simple Storage Service Developer Guide.
When making a select request, do the following:
• Define an output location for the select query's output. This must be an Amazon S3 bucket in the same
AWS Region as the bucket that contains the archive object that is being queried. The AWS account that
initiates the job must have permissions to write to the S3 bucket. You can specify the storage class
and encryption for the output objects stored in the bucket. For more information about output, see
Querying Archived Objects in the Amazon Simple Storage Service Developer Guide.
For more information about the S3 structure in the request body, see the following:
• Managing Access with ACLs in the Amazon Simple Storage Service Developer Guide
• Protecting Data Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide
• Define the SQL expression for the SELECT type of restoration for your query in the request body's
SelectParameters structure. You can use expressions like the following examples.
• The following expression returns all records from the specified object.
SELECT * FROM Object
• Assuming that you are not using any headers for data stored in the object, you can specify columns
with positional headers.
SELECT s._1, s._2 FROM Object s WHERE s._3 > 100
• If you have headers and you set the fileHeaderInfo in the CSV structure in the request body to
USE, you can specify headers in the query. (If you set the fileHeaderInfo field to IGNORE, the
first row is skipped for the query.) You cannot mix ordinal positions with header column names.
SELECT s.Id, s.FirstName, s.SSN FROM S3Object s

419
Restoring Archives
For more information about using SQL with Glacier Select restore, see SQL Reference for Amazon S3
Select and Glacier Select in the Amazon Simple Storage Service Developer Guide.
When making a select request, you can also do the following:
• To expedite your queries, specify the Expedited tier. For more information about tiers, see "Restoring
Archives," later in this topic.
• Specify details about the data serialization format of both the input object that is being queried and
the serialization of the CSV-encoded query results.
The following are additional important facts about the select feature:
• The output results are new Amazon S3 objects. Unlike archive retrievals, they are stored until explicitly
deleted—manually or through a lifecycle policy.
• You can issue more than one select request on the same Amazon S3 object. Amazon S3 doesn't
deduplicate requests, so avoid issuing duplicate requests.
• Amazon S3 accepts a select request even if the object has already been restored. A select request
doesn’t return error response 409.
Restoring Archives
Objects in the GLACIER and DEEP_ARCHIVE storage classes are archived. To access an archived object,
you must first initiate a restore request. This restores a temporary copy of the archived object. In a
restore request, you specify the number of days that you want the restored copy to exist. After the
specified period, Amazon S3 deletes the temporary copy but the object remains archived in the GLACIER
or DEEP_ARCHIVE storage class that object was restored from.
To restore a specific object version, you can provide a version ID. If you don't provide a version ID,
Amazon S3 restores the current version.
The time it takes restore jobs to finish depends on which storage class the object is being restored from
and which data access tier you specify.
When restoring an archived object (or using a select request), you can specify one of the following data
access tier options in the Tier element of the request body:
• Expedited - Expedited retrievals allow you to quickly access your data stored in the GLACIER storage
class when occasional urgent requests for a subset of archives are required. For all but the largest
archived objects (250 MB+), data accessed using Expedited retrievals are typically made available
within 1–5 minutes. Provisioned capacity ensures that retrieval capacity for Expedited retrievals is
available when you need it. Expedited retrievals and provisioned capacity are not available for the
• Standard - Standard retrievals allow you to access any of your archived objects within several hours.
This is the default option for the GLACIER and DEEP_ARCHIVE retrieval requests that do not specify
the retrieval option. Standard retrievals typically complete within 3-5 hours from the GLACIER storage
class and typically complete within 12 hours from the DEEP_ARCHIVE storage class.
• Bulk - Bulk retrievals are Amazon S3 Glacier’s lowest-cost retrieval option, enabling you to retrieve
large amounts, even petabytes, of data inexpensively in a day. Bulk retrievals typically complete
within 5-12 hours from the GLACIER storage class and typically complete within 48 hours from the
For more information about archive retrieval options and provisioned capacity for Expedited data
access, see Restoring Archived Objects in the Amazon Simple Storage Service Developer Guide.

420
Requests
You can use Amazon S3 restore speed upgrade to change the restore speed to a faster speed while it is
in progress. You upgrade the speed of an in-progress restoration by issuing another restore request to
the same object, setting a new Tier request element. When issuing a request to upgrade the restore
tier, you must choose a tier that is faster than the tier that the in-progress restore is using. You must not
change any other parameters, such as the Days request element. For more information, see Upgrading
the Speed of an In-Progress Restore in the Amazon Simple Storage Service Developer Guide.
To get the status of object restoration, you can send a HEAD request. Operations return the x-amz-
restore header, which provides information about the restoration status, in the response. You can
use Amazon S3 event notifications to notify you when a restore is initiated or completed. For more
information, see Configuring Amazon S3 Event Notifications in the Amazon Simple Storage Service
Developer Guide.
After restoring an archived object, you can update the restoration period by reissuing the request with a
new period. Amazon S3 updates the restoration period relative to the current time and charges only for
the request—there are no data transfer charges. You cannot update the restoration period when Amazon
S3 is actively processing your current restore request for the object.
If your bucket has a lifecycle configuration with a rule that includes an expiration action, the object
expiration overrides the life span that you specify in a restore request. For example, if you restore an
object copy for 10 days, but the object is scheduled to expire in 3 days, Amazon S3 deletes the object in
3 days. For more information about lifecycle configuration, see PUT Bucket lifecycle (p. 290) and Object
Lifecycle Management in Amazon Simple Storage Service Developer Guide.
Requests
Syntax
POST /ObjectName?restore&versionId=VersionID HTTP/1.1
Date: date
4))
Content-MD5: MD5
request body
Note
The syntax shows some of the request headers. For a complete list, see "Request Headers," later
in this topic.
Request Parameters
Request Headers
Content-MD5 The base64-encoded 128-bit MD5 digest of the data. You must use Yes
this header as a message integrity check to verify that the request
body was not corrupted in transit. For more information, see RFC
1864.
Type: String

421
Requests

Default: None
Request Elements
The following is an XML example of a request body for restoring an archive.
<RestoreRequest>
<Days>2</Days>
<GlacierJobParameters>
<Tier>Bulk</Tier>
</GlacierJobParameters>
</RestoreRequest>
The following table explains the XML for archive restoration in the request body.
RestoreRequest Container for restore information. Yes
Type: Container
Days Lifetime of the restored (active) copy. The minimum number of Yes, if restoring
days that you can restore an object from Glacier is 1. After the an archive
object copy reaches the specified lifetime, Amazon S3 removes
it from the bucket. If you are restoring an archive, this element is
required.
Do not use this element with a SELECT type of request.
Type: Positive integer
Ancestors: RestoreRequest
Container for Glacier job parameters.

GlacierJobParameters No
Do not use this element with a SELECT type of request.
Type: Container
Tier The data access tier to use when restoring the archive. No
Standard is the default.
Type: Enum
Valid values: Expedited | Standard | Bulk
Ancestors: GlacierJobParameters
The following XML is the request body for a select query on an archived object:
<RestoreRequest>
<Type>SELECT</Type>

422
Requests
<Tier>Expedited</Tier>
<Description>Job description</Description>
<SelectParameters>
<Expression>Select * from Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CSV>
<FileHeaderInfo>IGNORE</FileHeaderInfo>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
<Comments>#</Comments>
</CSV>
</InputSerialization>
<OutputSerialization>
<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
</CSV>
</OutputSerialization>
</SelectParameters>
<OutputLocation>
<S3>
<BucketName>Name of bucket</BucketName>
<Prefix>Key prefix</Prefix>
<CannedACL>Canned ACL string</CannedACL>
<AccessControlList>
<Grantee>
<Type>Grantee Type</Type>
<ID>Grantee identifier</ID>
<URI>Grantee URI</URI>
<Permission>Granted permission</Permission>
<DisplayNmae>Display Name</DisplayName>
<EmailAddress>email</EmailAddress>
</Grantee>
<Encryption>
<EncryptionType>Encryption type</EncryptionType>
<KMSKeyId>KMS Key ID</KMSKeyId>
<KMSContext>Base64-encoded JSON<KMSContext>
</Encryption>
<UserMetadata>
<MetadataEntry>
<Name>Key</Name>
<Value>Value</Value>
</MetadataEntry>
</UserMetadata>
<Tagging>
<TagSet>
<Tag>
<Key>Tag name</Key>
<Value>Tag value</Value>
</Tag>
</TagSet>
</Tagging>
<StorageClass>Storage class</StorageClass>
</S3>
</OutputLocation>
</RestoreRequest>
The following tables explain the XML for a SELECT type of restoration in the request body.

423
Requests
RestoreRequest Container for restore information. Yes
Type: Container
Tier The data access tier to use when restoring the archive. No
Standard is the default.
Type: Enum
Valid values: Expedited | Standard | Bulk
Description The optional description for the request. No
Type: String
Describes the parameters for the select job request.

SelectParameters Yes, if request
type is SELECT
Type: Container
OutputLocation Describes the location that receives the results of the select Yes, if request
restore request. type is SELECT
Type: Container for Amazon S3
The SelectParameters container element contains the following elements.
Expression The SQL expression. For example: Yes
• The following SQL expression retrieves the first column of the

data from the object stored in CSV format:
SELECT s._1 FROM Object s

• The following SQL expression returns everything from the
object:
SELECT * FROM Object
Type: String
Ancestors: SelectParameters
ExpressionType Identifies the expression type. Yes
Type: String
Valid values: SQL

424
Requests

Describes the serialization format of the object.

InputSerialization Yes
Type: Container for CSV
Describes how the results of the select job are serialized.

OutputSerialization Yes
Type: Container for CSV
The CSV container element in the InputSerialization element contains the following
elements.
RecordDelimiterA single character used to separate individual records in the No

input. Instead of the default value, you can specify an arbitrary
delimiter.
Type: String
Default: \n
Ancestors: CSV
FieldDelimiter A single character used to separate individual fields in a record. No

You can specify an arbitrary delimiter.
Type: String
Default: ,
Ancestors: CSV
QuoteCharacter A single character used for escaping when the field delimiter is No
part of the value.
Consider this example in a CSV file:
"a, b"
Wrapping the value in quotation marks makes this value a single

field. If you don't use the quotation marks, the comma is a field
delimiter (which makes it two separate field values, a and b).
Type: String
Default: "
Ancestors: CSV
A single character used for escaping the quotation mark

QuoteEscapeCharacter No
character inside an already escaped value. For example, the
value """ a , b """ is parsed as " a , b ".

425
Requests

Type: String
Default: "
Ancestors: CSV
FileHeaderInfo Describes the first line in the input data. It is one of the ENUM No
values.
• NONE: First line is not a header.

• IGNORE: First line is a header, but you can't use the header
values to indicate the column in an expression. You can use
column position (such as _1, _2, …) to indicate the column
(SELECT s._1 FROM OBJECT s).
• Use: First line is a header, and you can use the header value
to identify a column in an expression (SELECT "name" FROM
OBJECT).
Type: Enum
Valid values: NONE | USE | IGNORE
Ancestors: CSV
Comments A single character used to indicate that a row should be ignored No

when the character is present at the start of that row. You can
specify any character to indicate a comment line.
Type: String
Ancestors: CSV
The CSV container element (in the OutputSerialization elements) contains the following
elements.
QuoteFields Indicates whether to use quotation marks around output fields. No
• ALWAYS: Always use quotation marks for output fields.

• ASNEEDED: Use quotation marks for output fields when
needed.
Type: Enum
Valid values: ALWAYS | ASNEEDED
Default: AsNeeded
Ancestors: CSV
RecordDelimiterA single character used to separate individual records in the No

output. Instead of the default value, you can specify an arbitrary
delimiter.

426
Requests

Type: String
Default: \n
Ancestors: CSV
FieldDelimiter A single character used to separate individual fields in a record. No

You can specify an arbitrary delimiter.
Type: String
Default: ,
Ancestors: CSV
QuoteCharacter A single character used for escaping when the field delimiter is No
part of the value. For example, if the value is a, b, Amazon S3
wraps this field value in quotation marks, as follows: " a , b
".
Type: String
Default: "
Ancestors: CSV
A single character used for escaping the quotation mark

character inside an already escaped value. For example, if the
value is " a , b ", Amazon S3 wraps the value in quotation
marks, as follows: """ a , b """.
Type: String
Ancestors: CSV
The S3 container element (in the OutputLocation element) contains the following
elements.
A list of grants that control access to the staged results.

AccessControlList No
Type: Container for Grant
Ancestors: S3
BucketName The name of the S3 bucket where the select restore results Yes
are stored. The bucket must be in the same AWS Region as the
bucket that contains the input archive object.
Type: String
Ancestors: S3
CannedACL The canned access control list (ACL) to apply to the select No
restore results.
Type: String

427
Requests

Valid values: private | public-read | public-read-
Ancestors: S3
Encryption Contains encryption information for the stored results. No
Type: Container for Encryption
Ancestors: S3
Prefix The prefix that is prepended to the select restore results. The Yes
maximum length for the prefix is 512 bytes.
Type: String
Ancestors: S3
StorageClass The class of storage used to store the select request results. No
Type: String
Valid values: STANDARD | REDUCED_REDUNDANCY |

STANDARD_IA | ONEZONE_IA
Ancestors: S3
Tagging Container for tag information. No
Type: Tag structure
Ancestors: S3
UserMetadata Contains a list of metadata to store with the select restore No

results.
Type: MetadataEntry structure
Ancestors: S3
The Grantee container element (in the AccessControlList element) contains the following
elements.
DisplayName The screen name of the grantee. No
Type: String
Ancestors: Grantee
EmailAddress The email address of the grantee. No
Type: String
Ancestors: Grantee
ID The canonical user ID of the grantee. No

428
Requests

Type: String
Ancestors: Grantee
Type The type of the grantee. No
Type: String
Ancestors: Grantee
URI The URI of the grantee group. No
Type: String
Ancestors: Grantee
Permission Granted permission. No
Type: String
Ancestors: Grantee
The Encryption container element (in S3) contains the following elements.
EncryptionType The server-side encryption algorithm used when storing job No

results. The default is no encryption.
Type: String
Valid Values aws:kms | AES256
Ancestors: Encryption
KMSContext Optional. If the encryption type is aws:kms, you can use this No
value to specify the encryption context for the select restore
results.
Type: String
KMSKeyId The AWS Key Management Service (AWS KMS) key ID to use for No
object encryption.
Type: String
The TagSet container element (in the Tagging element) contains the following element.
Tag Contains tags. No
Type: Container

429
Responses

Ancestors: TagSet
The Tag container element (in the TagSet element) contains the following elements.
Key Name of the tag. No
Type: String
Ancestors: Tag
Value Value of the tag. No
Type: String
Ancestors: Tag
The MetadataEntry container element (in the UserMetadata element) contains the
following key-value pair elements to store with an object.
MetadataKey The metadata key. No
Type: String
Ancestors:
MetadataEntry The metadata value. No
Type: String
Ancestors:
Responses
A successful operation returns either the 200 OK or 202 Accepted status code.
• If the object copy is not previously restored, then Amazon S3 returns 202 Accepted in the response.
• If the object copy is previously restored, Amazon S3 returns 200 OK in the response.
Response Headers
Response Elements

430
Examples
Special Errors

Code Code Prefix
RestoreAlreadyInProgress Object restore is already in progress. 409 Conflict Client

(This error does not apply to SELECT
type requests.)
Glacier expedited retrievals

GlacierExpeditedRetrievalNotAvailable 503 N/A
are currently not available. Try
again later. (Returned if there is
insufficient capacity to process the
Expedited request. This error
applies only to Expedited retrievals
and not to Standard or Bulk
retrievals.)
Examples
Restore an Object for Two Days Using the Expedited Retrieval
Option
The following restore request restores a copy of the photo1.jpg object from Glacier for a period of two
days using the expedited retrieval option.
POST /photo1.jpg?restore HTTP/1.1

Date: Mon, 22 Oct 2012 01:49:52 GMT
Content-Length: content length
<RestoreRequest>
<Days>2</Days>
<GlacierJobParameters>
</GlacierJobParameters>
</RestoreRequest>
If the examplebucket does not have a restored copy of the object, Amazon S3 returns the following
202 Accepted response.
HTTP/1.1 202 Accepted

x-amz-id-2: GFihv3y6+kE7KG11GEkQhU7/2/cHR3Yb2fCb2S04nxI423Dqwg2XiQ0B/UZlzYQvPiBlZNRcovw=
x-amz-request-id: 9F341CD3C4BA79E0
Date: Sat, 20 Oct 2012 23:54:05 GMT
Content-Length: 0
Server: AmazonS3
If a copy of the object is already restored, Amazon S3 returns a 200 OK response, and updates only the
restored copy's expiry time.
Query an Archive with a SELECT Request

The following is an example select restore request.

431
Examples
POST /object-one.csv?restore HTTP/1.1

Date: Date: Sat, 20 Oct 2012 23:54:05 GMT
<RestoreRequest xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Type>SELECT</Type>
<Description>this is a description</Description>
<SelectParameters>
<CSV>
</CSV>
<Expression>select * from object</Expression>
<CSV>
<QuoteFields>ALWAYS</QuoteFields>
<FieldDelimiter>\t</FieldDelimiter>
<QuoteCharacter>\'</QuoteCharacter>
</CSV>
</SelectParameters>
<OutputLocation>
<S3>
<BucketName>example-output-bucket</BucketName>
<Prefix>test-s3</Prefix>
<AccessControlList>
<Grant>
<EmailAddress>jane-doe@example.com</EmailAddress>
</Grantee>
</Grant>
<UserMetadata>
<MetadataEntry>
<Name>test</Name>
<Value>test-value</Value>
</MetadataEntry>
<MetadataEntry>
<Name>other</Name>
<Value>something else</Value>
</MetadataEntry>
</UserMetadata>
</S3>
</OutputLocation>
</RestoreRequest>
Amazon S3 returns the following 202 Accepted response.
HTTP/1.1 202 Accepted

432
More Info
x-amz-restore-output-path: js-test-s3/qE8nk5M0XIj-LuZE2HXNw6empQm3znLkHlMWInRYPS-
Orl2W0uj6LyYm-neTvm1-btz3wbBxfMhPykd3jkl-lvZE7w42/
Date: Sat, 20 Oct 2012 23:54:05 GMT
Content-Length: 0
Server: AmazonS3
More Info
• SQL Reference for Amazon S3 Select and Glacier Select in the Amazon Simple Storage Service
Developer Guide

433
PUT Object
PUT Object
Description
This implementation of the PUT operation adds an object to a bucket. You must have WRITE permissions
on a bucket to add an object to it.
Amazon S3 never adds partial objects; if you receive a success response, Amazon S3 added the entire
object to the bucket.
Amazon S3 is a distributed system. If it receives multiple write requests for the same object
simultaneously, it overwrites all but the last object written. Amazon S3 does not provide object locking;
if you need this, make sure to build it into your application layer or use versioning instead.
To ensure that data is not corrupted traversing the network, use the Content-MD5 header. When you
use this header, Amazon S3 checks the object against the provided MD5 value and, if they do not match,
returns an error. Additionally, you can calculate the MD5 while putting an object to Amazon S3 and
compare the returned ETag to the calculated MD5 value.
Note
To configure your application to send the request headers before sending the request body,
use the 100-continue HTTP status code. For PUT operations, this helps you avoid sending
the message body if the message is rejected based on the headers (for example, because
authentication fails or a redirect occurs). For more information on the 100-continue HTTP
status code, go to Section 8.2.3 of http://www.ietf.org/rfc/rfc2616.txt.
You can optionally request server-side encryption. With server-side encryption, Amazon S3 encrypts
your data as it writes it to disks in its data centers and decrypts the data when you access it. You have the
option to provide your own encryption key or use AWS-managed encryption keys. For more information,
see Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide.
Versioning
If you enable versioning for a bucket, Amazon S3 automatically generates a unique version ID for
the object being stored. Amazon S3 returns this ID in the response using the x-amz-version-id
response header. If versioning is suspended, Amazon S3 always uses null as the version ID for the
object stored. For more information about returning the versioning state of a bucket, see GET Bucket
versioning (p. 224).
If you enable versioning for a bucket, when Amazon S3 receives multiple write requests for the same
object simultaneously, it stores all of the objects.
To see sample requests that use versioning, see Sample Request (p. 446).
Storage Class Options

By default, Amazon S3 uses the Standard storage class to store newly created objects. The Standard
storage class provides high durability and high availability. You can specify other storage classes
depending on the performance needs. For more information, see Storage Classes in the Amazon Simple
Access Permissions
When uploading an object, you can optionally specify the accounts or groups that should be granted
specific permissions on your object. There are two ways to grant the appropriate permissions using the
request headers:

434
Requests
• Specify a canned (predefined) ACL using the x-amz-acl request header. For more information, see
Canned ACL in the Amazon Simple Storage Service Developer Guide.
• Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-read-acp, and
x-amz-grant-write-acp, x-amz-grant-full-control headers. These headers map to the set
of permissions Amazon S3 supports in an ACL. For more information, go to Access Control List (ACL)
Overview in the Amazon Simple Storage Service Developer Guide.
Note
You can either use a canned ACL or specify access permissions explicitly. You cannot do both.
To change an object's ACLs from the default, the requester must have s3:PutObjectAcl included
in the list of permitted actions in their AWS Identity and Access Management (IAM) policy. For more
information about permissions, see Permissions for Object Operations and Managing Access Permissions
to Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.
Requests
Syntax
PUT /ObjectName HTTP/1.1
Date: date
4))
Note
The syntax shows some of the request headers. For a complete list, see the Request Headers
section.
Request Parameters
Request Headers
Cache-Control Can be used to specify caching behavior along the request/ No

reply chain. For more information, go to http://www.w3.org/
Protocols/rfc2616/rfc2616-sec14.html#sec14.9.
Type: String
Default: None
Constraints: None
Content- Specifies presentational information for the object. For more No

Disposition information, go to http://www.w3.org/Protocols/rfc2616/
rfc2616-sec19.html#sec19.5.1.
Type: String

435
Requests

Default: None
Constraints: None
Content-Encoding Specifies what content encodings have been applied to the No

object and thus what decoding mechanisms must be applied
to obtain the media-type referenced by the Content-Type
header field. For more information, go to http://www.w3.org/
Type: String
Default: None
Constraints: None
Content-Length The size of the object, in bytes. For more information, Yes
go to http://www.w3.org/Protocols/rfc2616/rfc2616-
sec14.html#sec14.13.
Type: String
Default: None
Constraints: None
Content-MD5 The base64-encoded 128-bit MD5 digest of the message Required

(without the headers) according to RFC 1864. This header can be if Object
used as a message integrity check to verify that the data is the Lock
same data that was originally sent. Although it is optional, we parameters
recommend using the Content-MD5 mechanism as an end-to- are
end integrity check. For more information about REST request specified
authentication, see REST Authentication in the Amazon Simple
Type: String
Default: None
Constraints: None
Content-Type A standard MIME type describing the format of the contents. For No
more information, go to http://www.w3.org/Protocols/rfc2616/
rfc2616-sec14.html#sec14.17.
Type: String
Default: binary/octet-stream
Valid Values: MIME types
Constraints: None

436
Requests
Expect When your application uses 100-continue, it does not send No

the request body until it receives an acknowledgment. If the
message is rejected based on the headers, the body of the
message is not sent.
Type: String
Default: None
Constraints: None
Expires The date and time at which the object is no longer able to No
be cached. For more information, go to http://www.w3.org/
Type: String
Default: None
Constraints: None
x-amz-meta- Headers starting with this prefix are user-defined metadata. No

Within the PUT request header, the user-defined metadata is
limited to 2 KB in size. User-defined metadata is a set of key-
value pairs. The size of user-defined metadata is the sum of the
number of bytes in the UTF-8 encoding of each key and value.
Amazon S3 doesn't validate or interpret user-defined metadata.
Type: String
Default: None
Constraints: None
x-amz-storage- If you don't specify, Standard is the default storage class. No

class Amazon S3 supports other storage classes. For more
information, see Storage Classes in the Amazon Simple Storage
Type: Enum
Default: STANDARD

DEEP_ARCHIVE

437
Requests
x-amz-tagging Specifies a set of one or more tags to associate with the object. No
These tags are stored in the tagging subresource that is
associated with the object.
To specify tags on an object, the requester must have

s3:PutObjectTagging included in the list of permitted
actions in their IAM policy.
For more information about adding tags to an object, see Object

Tagging Management in the Amazon Simple Storage Service
Developer Guide.
Type: String
Default: None
Constraints: The encoding for tags is URL query parameter

encoding. The maximum size of this header is 2 KB.
x-amz-website- If the bucket is configured as a website, redirects requests No

redirect-location for this object to another object in the same bucket or to an
external URL. Amazon S3 stores the value of this header in the
object metadata. For information about object metadata, see
Object Key and Metadata.
In the following example, the request header sets the redirect to

an object (anotherPage.html) in the same bucket:
anotherPage.html
In the following example, the request header sets the object

redirect to another website:
www.example.com/
For more information about website hosting in Amazon S3, see

Hosting Websites on Amazon S3 and How to Configure Website
Page Redirects in the Amazon Simple Storage Service Developer
Guide.
Type: String
Default: None
Constraints: The value must be prefixed by, "/", "http://" or

"https://". The length of the value is limited to 2 KB.

438
Requests
x-amz-object- The Object Lock mode, if any, that should be applied to this No
lock-mode object. For more information about S3 Object Lock, see Object
Lock in the Amazon Simple Storage Service Developer Guide.
Type: String
Default: None
x-amz-object- The date and time when the Object Lock retention period will Required
lock-retain- expire. if x-amz-
until-date object-
Type: Timestamp lock-
mode is
Default: None specified
Format: 2020-01-05T00:00:00.000Z
x-amz-object- Specifies whether a legal hold will be applied to this object. No

lock-legal-hold For more information about legal holds, see Object Lock in the
Type: String
Default: None
Access-Control-List-(ACL)-Specific Request Headers

Additionally, you can use the following access control–related headers with this operation. By default,
all objects are private: only the owner has full control. When adding a new object, you can grant
permissions to individual AWS accounts or predefined Amazon S3 groups. These permissions are then
used to create the Access Control List (ACL) on the object. For more information, see Using ACLs.
To grant these permissions, you can use one of the following methods:
canned ACL has a predefined set of grantees and permissions. For more information, go to Canned
ACL.
x-amz-acl The canned ACL to apply to the object. For more information, No
see Canned ACL in the Amazon Simple Storage Service Developer
Guide.
Type: String
Default: private


439
Requests

Constraints: None
• Specify access permissions explicitly — To explicitly grant access permissions to specific AWS
accounts or a group, use the following headers. Each maps to specific permissions that Amazon S3
supports in an ACL. For more information, see Access Control List (ACL) Overview. In the header value,
you specify a list of grantees who get the specific permission.
x-amz-grant- Grants permission to read the object data and its metadata. No
read
Type: String
Default: None
Constraints: None
x-amz-grant- Not applicable. This header applies only when granting No

write permission on a bucket.
Type: String
Default: None
Constraints: None
x-amz-grant- Grants permission to read the object ACL. No

read-acp
Type: String
Default: None
Constraints: None
x-amz-grant- Grants permission to write the ACL for the applicable object. No
write-acp
Type: String
Default: None
Constraints: None
x-amz-grant- Grants READ, READ_ACP, and WRITE_ACP permissions on the No

full-control object.
Type: String
Default: None
Constraints: None
You specify each grantee as a type=value pair, where the type can be one of the following:
• emailAddress – if the specified value is the email address of an AWS account

440
Requests
Important
Using email addresses to specify a grantee is only supported in the following AWS Regions:
• US East (N. Virginia)
• US West (N. California)
• US West (Oregon)
• Asia Pacific (Singapore)
• Asia Pacific (Sydney)
• Asia Pacific (Tokyo)
• EU (Ireland)
• South America (São Paulo)
For a list of all the Amazon S3 supported regions and endpoints, see Regions and Endpoints in
the AWS General Reference.
• id – if the specified value is the canonical user ID of an AWS account
• uri – if you are granting permission to a predefined group
For example, the following x-amz-grant-read header grants permission to read object data and its
metadata to the AWS accounts identified by their email addresses.
Server-Side-Encryption-Specific Request Headers

You can optionally request Amazon S3 to encrypt data at rest using server-side encryption. Server-side
encryption is for data encryption at rest. Amazon S3 encrypts your data as it writes it to disks in its data
centers and decrypts the date when you access it. The header you use depend on whether you want to
use AWS-managed encryption keys or provide your own encryption keys.
• Use AWS-managed encryption keys — If you want Amazon S3 to manage the keys used to encrypt
data, specify the following headers in the request.
x-amz-server-side Specifies the server-side encryption algorithm to use when Yes

-encryption Amazon S3 creates an object.
Type: String
x-amz-server- If the x-amz-server-side-encryption is present and has No. If the

aws-kms-key-id Key Management Service (AWS KMS) master encryption key x-amz-
that was used for the object. server-
side-
is
aws:kms,
this
header
specifies
the ID
of the
AWS Key

441
Requests

Management
Service
(AWS
KMS)
master
encryption
key that
will be
used for
the object.
If you
specify
x-amz-
server-
side-
encryption:aws:kms,
but do not
provide
x-amz-
server-
side-
encryption-
aws-kms-
key-id,
Amazon
S3 uses
the
default
AWS KMS
key to
protect
the data.
x-amz-server- If the x-amz-server-side-encryption header is No

side-encryption- present, and if its value is aws:kms, this header specifies the
context encryption context for the object. The value of this header
is a base64-encoded UTF-8 string holding JSON with the
encryption context key-value pairs.
Type: String
Note
Important
All GET and PUT requests for an object protected by AWS KMS fail if you don't make them
with SSL or by using SigV4.
For more information on Server-Side Encryption with Amazon KMS-Managed Keys (SSE-KMS), see
Protecting Data Using Server-Side Encryption with AWS KMS-Managed Keys in the Amazon Simple
• Use customer-provided encryption keys— If you want to manage your own encryption keys, provide all
the following headers in the request.

442
Requests
Note
If you use this feature, the ETag value that Amazon S3 returns in the response is not the MD5
of the object.
side-encryption
-customer- Type: String
algorithm
Default: None
Valid Value: AES256


side-encryption- key that Amazon S3 should use to encrypt data. Amazon
customer-key S3 uses this value to store the object and then discards it.
Amazon does not store the encryption key. The key must be
appropriate for use with the algorithm specified in the x-amz-
server-side-encryption-customer-algorithm header.
Type: String
Default: None

server-side-encryption-customer-key-MD5 headers.

Type: String
Default: None

server-side-encryption-customer-key headers.
For more information on Server-Side Encryption with Customer-Provided Encryption Keys (SSE-C), see
Protecting Data Using Server-Side Encryption with Customer-Provided Encryption Keys (SSE-C) in the

443
Responses
Responses
Response Headers
Name Description
x-amz- If the expiration is configured for the object (see PUT Bucket lifecycle (p. 290)),
expiration the response includes this header. It includes the expiry-date and rule-id
key-value pairs that provide information about object expiration. The value of the
rule-id is URL encoded.
Type: String
x-amz- If you specified server-side encryption either with an AWS KMS-managed or

server-side- Amazon S3-managed encryption key in your PUT request, the response includes
encryption this header. It confirms the encryption algorithm that Amazon S3 used to encrypt
the object.
Type: String

server-side- aws:kms, this header specifies the ID of the AWS KMS master encryption key that
encryption- was used for the object.
aws-kms-key-
id Type: String
x-amz- If server-side encryption with customer-provided encryption keys encryption

server-side was requested, the response includes this header that confirms the encryption
-encryption algorithm that was used.
-customer-
x-amz- If server-side encryption using customer-provided encryption keys was requested,

server-side the response returns this header to verify the roundtrip message integrity of the
-encryption- customer-provided encryption key.
customer-key-
MD5 Type: String
x-amz- Version of the object.

version-id
Type: String
Response Elements
Special Errors

444
Examples
Examples
Example 1: Upload an Object
Sample Request
The following request stores the my-image.jpg image in the myBucket bucket.
PUT /my-image.jpg HTTP/1.1

Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-meta-author: Janet
Sample Response with Versioning Suspended
HTTP/1.1 200 OK
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server: AmazonS3
If an expiration rule that was created on the bucket using lifecycle configuration applies to the object,
you get a response with an x-amz-expiration header as shown in the following response. For more
information, see Transitioning Objects: General Considerations in the Amazon Simple Storage Service
Developer Guide.
HTTP/1.1 200 OK
Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-expiration: expiry-date="Fri, 23 Dec 2012 00:00:00 GMT", rule-id="1"
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server: AmazonS3
Sample Response with Versioning Enabled

If the bucket has versioning enabled, the response includes the x-amz-version-id header.
HTTP/1.1 200 OK
x-amz-version-id: 43jfkodU8493jnFJD9fjj3HHNVfdsQUIFDNsidf038jfdsjGFDSIRp

445
Examples
Date: Wed, 12 Oct 2009 17:50:00 GMT

ETag: "fbacf535f27731c9771645a39863328"
Content-Length: 0
Connection: close
Server: AmazonS3
Example 2: Upload an Object (Specify Storage Class)

Sample Request: Specifying the Reduced Redundancy Storage Class
The following request stores the image, my-image.jpg, in the myBucket bucket. The request
specifies the x-amz-storage-class header to request that the object is stored using the
REDUCED_REDUNDANCY storage class.
PUT /my-image.jpg HTTP/1.1

Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Type: image/jpeg
Sample Response
HTTP/1.1 200 OK
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server: AmazonS3
Example 3:Upload an Object (Specify Access Permission

Explicitly)
Sample Request: Uploading an Object and Specifying Access Permissions
Explicitly
The following request stores the TestObject.txt file in the myBucket bucket. The request specifies
various ACL headers to grant permission to AWS accounts that are specified with a canonical user ID and
an email address.
PUT TestObject.txt HTTP/1.1

x-amz-date: Fri, 13 Apr 2012 05:40:14 GMT
x-amz-grant-write-acp: id=8a6925ce4adf588a4532142d3f74dd8c71fa124ExampleCanonicalUserID
x-amz-grant-full-control: emailAddress="ExampleUser@amazon.com"
x-amz-grant-write: emailAddress="ExampleUser1@amazon.com",
emailAddress="ExampleUser2@amazon.com"
Content-Length: 300

446
Examples
...Object data in the body...
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: RUxG2sZJUfS+ezeAS2i0Xj6w/ST6xqF/8pFNHjTjTrECW56SCAUWGg+7QLVoj1GH
x-amz-request-id: 8D017A90827290BA
Date: Fri, 13 Apr 2012 05:40:25 GMT
ETag: "dd038b344cf9553547f8b395a814b274"
Content-Length: 0
Server: AmazonS3
Example 4: Upload an Object (Specify Access Permission Using

Canned ACL)
Sample Request: Using a Canned ACL to Set Access Permissions
The following request stores the TestObject.txt file in the myBucket bucket. The request uses an x-
amz-acl header to specify a canned ACL that grants READ permission to the public.

PUT TestObject.txt HTTP/1.1
x-amz-date: Fri, 13 Apr 2012 05:54:57 GMT
x-amz-acl: public-read
Content-Length: 300
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: Yd6PSJxJFQeTYJ/3dDO7miqJfVMXXW0S2Hijo3WFs4bz6oe2QCVXasxXLZdMfASd
x-amz-request-id: 80DF413BB3D28A25
Date: Fri, 13 Apr 2012 05:54:59 GMT
ETag: "dd038b344cf9553547f8b395a814b274"
Content-Length: 0
Server: AmazonS3
Example 5: Upload an Object (Request Server-Side Encryption

Using a Customer-Provided Encryption Key)
This example of an upload object requests server-side encryption and provides an encryption key.
PUT /example-object HTTP/1.1

Accept: */*
Date: Wed, 28 May 2014 19:31:11 +0000
x-amz-server-side-encryption-customer-key:g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEEXAMPLE
x-amz-server-side-encryption-customer-key-MD5:ZjQrne1X/iTcskbY2example
x-amz-server-side-encryption-customer-algorithm:AES256

447
Related Resources
In the response, Amazon S3 returns the encryption algorithm and MD5 of the encryption key that you
specified when uploading the object. The ETag that is returned is not the MD5 of the object.
HTTP/1.1 200 OK
x-amz-id-2: 7qoYGN7uMuFuYS6m7a4lszH6in+hccE+4DXPmDZ7C9KqucjnZC1gI5mshai6fbMG
x-amz-request-id: 06437EDD40C407C7
Date: Wed, 28 May 2014 19:31:12 GMT
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2example
ETag: "ae89237c20e759c5f479ece02c642f59"
Example 6: Upload an Object and Specify Tags

This example of an upload object request specifies the optional x-amz-tagging header to add tags to
the object.
PUT /example-object HTTP/1.1

Accept: */*
Date: Thu, 22 Sep 2016 21:58:13 GMT
x-amz-tagging: tag1=value1&tag2=value2
[... bytes of object data]
After the object is created, Amazon S3 stores the specified object tags in the tagging subresource that
is associated with the object.
HTTP/1.1 200 OK
x-amz-id-2: 7qoYGN7uMuFuYS6m7a4lszH6in+hccE+4DXPmDZ7C9KqucjnZC1gI5mshai6fbMG
x-amz-request-id: 06437EDD40C407C7
Date: Thu, 22 Sep 2016 21:58:17 GMT
Related Resources

448
PUT Object legal hold
PUT Object legal hold

Applies a Legal Hold configuration to the specified object.
Request Syntax
PUT /<object-key>?legal-hold&versionId=<version-id> HTTP/1.1
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
4))

versionId
The version ID of the object version that you want to put a retention period on.
Request Body
ObjectLockLegalHold (p. 545).
<LegalHold>
<Status>ON</Status>
</LegalHold>
Response Syntax
HTTP/1.1 200
Response Elements
Related Resources

449
PUT Object retention
PUT Object retention

Places an Object Retention configuration on an object.
Request Syntax
PUT /<object-key>?retention&versionId=<version-id> HTTP/1.1
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
4))

versionId
The version ID of the object version that you want to put a retention period on.
Request Body
ObjectLockRetention (p. 546).
<Retention>
<Mode>GOVERNANCE</Mode>
<RetainUntilDate>2020-01-05T00:00:00.000Z</RetainUntilDate>
</Retention>
Response Syntax
HTTP/1.1 200
Response Elements
Related Resources

450
PUT Object - Copy
PUT Object - Copy

Description
This implementation of the PUT operation creates a copy of an object that is already stored in Amazon
S3. A PUT copy operation is the same as performing a GET and then a PUT. Adding the request header,
x-amz-copy-source, makes the PUT operation copy the source object into the destination bucket.
Note
You can store individual objects of up to 5 TB in Amazon S3. You create a copy of your object
up to 5 GB in size in a single atomic operation using this API. However, for copying an object
greater than 5 GB, you must use the multipart upload Upload Part - Copy (p. 534) API. For
conceptual information, see Copy Object Using the REST Multipart Upload API in the Amazon
When copying an object, you can preserve most of the metadata (default) or specify new metadata.
However, the ACL is not preserved and is set to private for the user making the request.
Important
Amazon S3 Transfer Acceleration does not support cross-region copies. If you request a cross-
region copy using a Transfer Acceleration endpoint, you get a 400 Bad Request error. For
more information about transfer acceleration, see Transfer Acceleration in the Amazon Simple
All copy requests must be authenticated and cannot contain a message body. Additionally, you
must have READ access to the source object and WRITE access to the destination bucket. For more
information, see REST Authentication. Both the Region that you want to copy the object from and the
Region that you want to copy the object to must be enabled for your account.
To copy an object only under certain conditions, such as whether the ETag matches or whether the
object was modified before or after a specified date, use the request headers x-amz-copy-source-if-
match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-unmodified-since, or
x-amz-copy-source-if-modified-since.
Note
All headers with the x-amz- prefix, including x-amz-copy-source, must be signed.
You can use this operation to change the storage class of an object that is already stored in Amazon S3
using the x-amz-storage-class request header. For more information, see Storage Classes in the
The source object that you are copying can be encrypted or unencrypted. If the source object is
encrypted, it can be encrypted by server-side encryption using AWS-managed encryption keys or by
using a customer-provided encryption key. When copying an object, you can request that Amazon S3
encrypt the target object by using either the AWS-managed encryption keys or by using your own
encryption key. You can do this regardless of the form of server-side encryption that was used to encrypt
the source, or even if the source object was not encrypted. For more information about server-side
encryption, see Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide.
A copy request might return an error when Amazon S3 receives the copy request or while Amazon S3 is
copying the files. If the error occurs before the copy operation starts, you receive a standard Amazon
S3 error. If the error occurs during the copy operation, the error response is embedded in the 200 OK
response. This means that a 200 OK response can contain either a success or an error. Design your
application to parse the contents of the response and handle it appropriately.
If the copy is successful, you receive a response with information about the copied object.
Note
If the request is an HTTP 1.1 request, the response is chunk encoded. If it were not, it would not
contain the content-length, and you would need to read the entire body.

451
Versioning
The copy request charge is based on the storage class and Region you specify for the destination object.
For pricing information, see Amazon S3 Pricing.
Versioning
By default, x-amz-copy-source identifies the current version of an object to copy. (If the current
version is a delete marker, Amazon S3 behaves as if the object was deleted.) To copy a different version,
use the versionId subresource.
If you enable versioning on the target bucket, Amazon S3 generates a unique version ID for the object
being copied. This version ID is different from the version ID of the source object. Amazon S3 returns the
version ID of the copied object in the x-amz-version-id response header in the response.
If you do not enable versioning or suspend it on the target bucket, the version ID that Amazon S3
generates is always null.
If the source object's storage class is GLACIER, then you must restore a copy of this object before you can
use it as a source object for the copy operation. For more information, see POST Object restore (p. 419).
To see sample requests that use versioning, see Sample Request: Copying a specified version of an
object (p. 464).
Access Permissions
When copying an object, you can optionally specify the accounts or groups that should be granted
specific permissions on the new object. There are two ways to grant the permissions using the request
headers:
• Specify a canned ACL with the x-amz-acl request header. For more information, see Canned ACL in
• Specify access permissions explicitly with the x-amz-grant-read, x-amz-grant-read-acp, x-
amz-grant-write-acp, and x-amz-grant-full-control headers. These headers map to the set
of permissions that Amazon S3 supports in an ACL. For more information, go to Access Control List
(ACL) Overview in the Amazon Simple Storage Service Developer Guide.
Note
You can use either a canned ACL or specify access permissions explicitly. You cannot do both.
Requests
Syntax
PUT /destinationObject HTTP/1.1
Host: destinationBucket.s3.amazonaws.com
x-amz-copy-source: /source_bucket/sourceObject
x-amz-metadata-directive: metadata_directive
x-amz-copy-source-if-match: etag
x-amz-copy-source-if-none-match: etag
x-amz-copy-source-if-unmodified-since: time_stamp
x-amz-copy-source-if-modified-since: time_stamp
<request metadata>
4))
Date: date

452
Requests
Note
The syntax shows only some of the request headers. For a complete list, see the Request
Headers section.
Request Parameters
Request Headers
x-amz-copy-source The name of the source bucket and key name of Yes
the source object, separated by a slash (/).
Type: String
Default: None
Constraints:
This string must be URL-encoded. Additionally,

the source bucket must be valid and you must
have READ access to the valid source object.
If the source object is archived in the GLACIER

or DEEP_ARCHIVE storage class, you must first
restore a temporary copy using the POST Object
restore (p. 419). Otherwise, Amazon S3 returns
the 403 ObjectNotInActiveTierError
error response.
x-amz-metadata-directive Specifies whether the metadata is copied from No

the source object or is replaced with metadata
provided in the request.
• If the metadata is copied, all of the metadata

except for the version ID remains unchanged.
In addition, the server-side-encryption,
storage-class and website-redirect-
location metadata from the source is not
copied. If you specify this metadata explicitly
in the copy request, Amazon S3 adds this
metadata to the resulting object. If you specify
headers in the request that specifies user-
defined metadata, Amazon S3 ignores these
headers.
• If the metadata is replaced, all of the original
metadata is replaced by the metadata that you
specify.
Type: String

453
Requests

Default: COPY
Constraints: Values other than COPY or REPLACE

result in an immediate 400-based error
response. You can't copy an object to itself
unless you specify the MetadataDirective
header and set its value to REPLACE.
For information on supported metadata, see

Common Request Headers (p. 2)
x-amz-copy-source-if-match Copies the object if its entity tag (ETag) matches No

the specified tag. Otherwise, the request
returns a 412 HTTP status code error (failed
precondition).
For more information, see Consideration 1 after

this table.
Type: String
Default: None
Constraints: This header can be used with x-

amz-copy-source-if-unmodified-since,
but it cannot be used with other conditional
copy headers.
x-amz-copy-source-if-none- Copies the object if its entity tag (ETag) is No

match different than the specified ETag. Otherwise,
the request returns a 412 HTTP status code error
(failed precondition).

this table.
Type: String
Default: None
Constraints: This header can be used with x-

amz-copy-source-if-modified-since, but
it cannot be used with other conditional copy
headers.

454
Requests
x-amz-copy-source-if- Copies the object if it hasn't been modified No

unmodified-since since the specified time. Otherwise, the request
precondition).

this table.
Type: String
Default: None
Constraints: This must be a valid HTTP date.

This header can be used with x-amz-copy-
source-if-match, but cannot be used with
other conditional copy headers.
x-amz-copy-source-if-modified- Copies the object if it has been modified since No

since the specified time; otherwise, the request
condition).

this table.
Type: String
Default: None
Constraints: This must be a valid HTTP date. This

header can be used with x-amz-copy-source-
if-none-match, but cannot be used with other
conditional copy headers.
x-amz-storage-class If you don't specify this header, Amazon S3 uses No

STANDARD, the default, for the storage class.
Amazon S3 supports other storage classes. For
more information, see Storage Classes in the
Type: Enum
Default: STANDARD
Valid values: STANDARD |

REDUCED_REDUNDANCY | GLACIER
| STANDARD_IA | ONEZONE_IA |

455
Requests
x-amz-tagging-directive Specifies whether the object tags are copied No

from the source object or replaced with tags
provided in the request.
• If the tags are copied, the tagset remains

unchanged.
• If the tags are replaced, all of the original
tagset is replaced by the tags you specify.
If you don't specify a tagging directive, Amazon

S3 copies tags by default.
If the tagging directive is REPLACE, you specify

any tags in url format in the x-amz-tagging
header, similar to using a PUT object with tags.
If the tagging directive is REPLACE, but you don't

specify the x-amz-tagging in the request, the
destination object won't have tags.
Type: String
Default: COPY
Constraints: Values other than COPY or REPLACE

result in an immediate 400-based error
response.

456
Requests
x-amz-website-redirect- If the bucket is configured as a website, redirects No

location requests for this object to another object
in the same bucket or to an external URL.
Amazon S3 stores the value of this header in the
object metadata. For information about object
metadata, see Object Key and Metadata.
In the following example, the request header

sets the redirect to an object (anotherPage.html)
in the same bucket:
anotherPage.html
In the following example, the request header

sets the object redirect to another website:
x-amz-website-redirect-location:
http://www.example.com/
For more information about website hosting in

Amazon S3, see Hosting Websites on Amazon S3
and How to Configure Website Page Redirects
in the Amazon Simple Storage Service Developer
Guide.
Type: String
Default: None
Constraints: The value must be prefixed by, "/",

"http://" or "https://". The length of the value is
limited to 2 K.
Consider the following when using request headers:
• Consideration 1 – If both the x-amz-copy-source-if-match and x-amz-copy-source-if-

unmodified-since headers are present in the request and evaluate as follows, Amazon S3 returns
200 OK and copies the data:
x-amz-copy-source-if-match condition evaluates to true
x-amz-copy-source-if-unmodified-since condition evaluates to false

• Consideration 2 – If both of the x-amz-copy-source-if-none-match and x-amz-copy-source-
if-modified-since headers are present in the request and evaluate as follows, Amazon S3 returns
the 412 Precondition Failed response code:
x-amz-copy-source-if-none-match condition evaluates to false
x-amz-copy-source-if-modified-since condition evaluates to true

457
Requests
Server-Side- Encryption-Specific Request Headers

To encrypt the target object, you must provide the appropriate encryption-related request headers. The
one you use depends on whether you want to use AWS-managed encryption keys or provide your own
encryption key:
• To encrypt the target object using server-side encryption with an AWS-managed encryption key,
provide the following request headers, as appropriate.
x-amz-server-side Specifies a server-side encryption algorithm to use when Yes

Type: String
x-amz-server- If the x-amz-server-side-encryption header is present Yes, if the

side-encryption- and has the value of aws:kms, this header specifies the ID value of
aws-kms-key-id of the AWS Key Management Service (AWS KMS) master x-amz-
encryption key that was used for the object. server-
side-
is
aws:kms
x-amz-server- If x-amz-server-side-encryption is present and its value No

side-encryption- is aws:kms, this header specifies the encryption context for
context the object. The value of this header is a base64-encoded UTF-8
string holding JSON with the encryption context key-value
pairs.
Type: String
Note
If you specify x-amz-server-side-encryption:aws:kms, but don't provide x-amz-
Important
All GET and PUT requests for an object protected by AWS KMS fail if you don't make them
with SSL or by using SigV4.
• To encrypt the target object using server-side encryption with an encryption key that you provide, use
the following headers.
side-encryption
algorithm
458
Requests

Default: None
Valid Value: AES256


side-encryption- key for Amazon S3 to use to encrypt data. Amazon S3 uses this
customer-key value to store the object and then discards it. Amazon does
not store the encryption key. The key must be appropriate for
use with the algorithm specified in the x-amz-server-side-
Type: String
Default: None


side-encryption- encryption key according to RFC 1321. Amazon S3 uses
customer-key-MD5 this header as a message integrity check to ensure that the
Type: String
Default: None

• If the source object is encrypted using server-side encryption with customer-provided encryption keys,
you must use the following headers.
x-amz-copy- Specifies the algorithm to use when decrypting the source Yes
source-server- object.
side-encryption
algorithm
Default: None
Valid Value: AES256
Constraints: Must be accompanied by valid x-amz-copy-

source-server-side-encryption-customer-key
and x-amz-copy-source-server-side-encryption-
customer-key-MD5 headers.
x-amz-copy-source Specifies the customer-provided base64-encoded encryption Yes

-server-side key for Amazon S3 to use to decrypt the source object.
After the copy operation, Amazon S3 discards this key. The

459
Requests

-encryption- encryption key provided in this header must be one that was
customer-key used when the source object was created.
Type: String
Default: None

source-server-side-encryption-customer-
algorithm and x-amz-copy-source-server-side-
x-amz-copy- Specifies the base64-encoded 128-bit MD5 digest of the Yes

source-server- encryption key according to RFC 1321. Amazon S3 uses this
side-encryption- header for a message integrity check to ensure that the
customer-key-MD5 encryption key was transmitted without error.
Type: String
Default: None

source-server-side-encryption-customer-
algorithm and x-amz-copy-source-server-side-
encryption-customer-key headers.
Access-Control-List-ACL)-Specific Request Headers

You also can use the following access control–related headers with this operation. By default, all objects
are private. Only the owner has full access control. When adding a new object, you can grant permissions
to individual AWS accounts or to predefined groups defined by Amazon S3. These permissions are then
added to the Access Control List (ACL) on the object. For more information, see Using ACLs. With this
operation, you can grant access permissions using one of the following two methods:
canned ACL has a predefined set of grantees and permissions. For more information, see Canned ACL.
x-amz-acl The canned ACL to apply to the object. No
Type: String
Default: private

Constraints: None

460
Requests
• Specify access permissions explicitly — To explicitly grant access permissions to specific AWS
accounts or groups, use the following headers. Each header maps to specific permissions that Amazon
S3 supports in an ACL. For more information, see Access Control List (ACL) Overview. In the header,
you specify a list of grantees who get the specific permission.
x-amz-grant- Gives the grantee permissions to read the object data and its No
read metadata.
Type: String
Default: None
Constraints: None
x-amz-grant- Not applicable. This header applies only when granting access No
write permissions on a bucket.
Type: String
Default: None
Constraints: None
x-amz-grant- Gives the grantee permissions to read the object ACL. No

read-acp
Type: String
Default: None
Constraints: None
x-amz-grant- Gives the grantee permissions to write the ACL for the applicable No
write-acp object.
Type: String
Default: None
Constraints: None
x-amz-grant- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions No

full-control on the object.
Type: String
Default: None
Constraints: None
You specify each grantee as a type=value pair, where the type is one of the following:
• emailAddress – if the value specified is the email address of an AWS account

• id – if the value specified is the canonical user ID of an AWS account
• uri – if you are granting permissions to a predefined group.

461
Responses
For example, the following x-amz-grant-read header grants the AWS accounts identified by email
addresses permissions to read object data and its metadata:
Request Elements
Responses
Response Headers
Name Description
x-amz-expiration If an Expiration action is configured for the object as part

of the bucket's lifecycle configuration, Amazon S3 returns this
header. The header value includes an "expiry-date" component
and a URL-encoded "rule-id" component. For version-enabled
buckets, this header applies only to current versions. Amazon S3
does not provide a header to infer when a noncurrent version is
eligible for permanent deletion. For more information, see PUT
Bucket lifecycle (p. 290).
Type: String
x-amz-copy-source-version- Version of the source object that was copied.

id
Type: String
x-amz-server-side- If you specified server-side encryption either with an encryption

encryption key managed by AWS KMS or Amazon S3 in your copy request,
the response includes this header. It confirms the encryption
algorithm that Amazon S3 used to encrypt the object.
Type: String
x-amz-server-side- If the x-amz-server-side-encryption header is present

encryption-aws-kms-key-id and has the value of aws:kms, this header specifies the ID of
the AWS KMS master encryption key that was used for the
object.
Type: String
x-amz-server-side- If server-side encryption with customer-provided encryption

encryption-customer- keys (SSE-C) encryption was requested, the response includes
algorithm this header, which confirms the encryption algorithm used for
the destination object.
Type: String
Valid values: AES256

462
Responses
Name Description
x-amz-server-side- If SSE-C encryption was requested, the response includes this

encryption-customer-key-MD5 header to verify the integrity of the roundtrip message of the
customer-provided encryption key that was used to encrypt the
destination object.
Type: String
x-amz-storage-class Provides information about the object's storage class. Amazon

S3 returns this header for all objects except Standard storage
class objects.
For more information, see Storage Classes in Amazon Simple

Type: String
Default: None
x-amz-version-id Version of the copied object in the destination bucket.
Type: String
Response Elements
Name Description
CopyObjectResult Container for all response elements.
Type: Container
Ancestor: None
ETag Returns the ETag of the new object. The ETag reflects only changes
to the contents of an object, not its metadata. The source and
destination ETag is identical for a successfully copied object.
Type: String
Ancestor: CopyObjectResult
LastModified Returns the date that the object was last modified.
Type: String
Special Errors

463
Examples
Examples
Sample Request
This example copies my-image.jpg into the bucket bucket, with the key name my-second-
image.jpg.
PUT /my-second-image.jpg HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-copy-source: /bucket/my-image.jpg
Sample Response
HTTP/1.1 200 OK
x-amz-copy-source-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-version-id: QUpfdndhfd8438MNFDN93jdnJFkdmqnh893
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3
<CopyObjectResult>
<LastModified>2009-10-28T22:32:00</LastModified>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>
x-amz-version-id returns the version ID of the object in the destination bucket. x-amz-copy-
source-version-id returns the version ID of the source object.
Sample Request: Copying a Specified Version of an Object

The following request copies the my-image.jpg key with the specified version ID, copies it into the
bucket bucket, and gives it the my-second-image.jpg key.
PUT /my-second-image.jpg HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-copy-source: /bucket/my-image.jpg?versionId=3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
Success Response: Copying a Versioned Object into a Version-

enabled Bucket
The following response shows that an object was copied into a target bucket where versioning is
enabled.
HTTP/1.1 200 OK

464
Examples
x-amz-version-id: QUpfdndhfd8438MNFDN93jdnJFkdmqnh893
x-amz-copy-source-version-id: 09df8234529fjs0dfi0w52935029wefdj
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

<CopyObjectResult>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>
Success Response: Copying a Versioned Object into a Version-

suspended Bucket
The following response shows that an object was copied into a target bucket where versioning is
suspended. The parameter <VersionId> does not appear.
HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

<CopyObjectResult>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>
Sample: Copy from Unencrypted Object to an Object Encrypted

with Server-side Encryption with Customer-provided Encryption
Keys
The following example specifies the HTTP PUT header to copy an unencrypted object to an object
encrypted with server-side encryption with customer-provided encryption keys (SSE-C).
PUT /exampleDestinationObject HTTP/1.1

Host: example-destination-bucket.s3.amazonaws.com
x-amz-server-side-encryption-customer-key: Base64(YourKey)
x-amz-server-side-encryption-customer-key-MD5 : Base64(MD5(YourKey))
x-amz-copy-source: /example_source_bucket/exampleSourceObject
<request metadata>
4))
Date: date

465
Related Resources
Sample: Copy from an Object Encrypted with SSE-C to an

Object Encrypted with SSE-C
The following example specifies the HTTP PUT header to copy an object encrypted with server-side
encryption with customer-provided encryption keys to an object encrypted with server-side encryption
with customer-provided encryption keys for key rotation.
PUT /exampleDestinationObject HTTP/1.1

Host: example-destination-bucket.s3.amazonaws.com
x-amz-server-side-encryption-customer-key: Base64(NewKey)
x-amz-server-side-encryption-customer-key-MD5: Base64(MD5(NewKey))
x-amz-copy-source-server-side-encryption-customer-algorithm: AES256
x-amz-copy-source-server-side-encryption-customer-key: Base64(OldKey)
x-amz-copy-source-server-side-encryption-customer-key-MD5: Base64(MD5(OldKey))
<request metadata>
4))
Date: date
Related Resources
• Copying Objects

466
PUT Object acl
PUT Object acl

Description
This implementation of the PUT operation uses the acl subresource to set the access control list (ACL)
permissions for an object that already exists in a bucket. You must have WRITE_ACP permission to set the
ACL of an object.
You can use one of the following two ways to set an object's permissions:
• Specify the ACL in the request body, or

• Specify permissions using request headers
Depending on your application needs, you may choose to set the ACL on an object using either the
request body or the headers. For example, if you have an existing application that updates an object ACL
using the request body, then you can continue to use that approach.
Versioning
The ACL of an object is set at the object version level. By default, PUT sets the ACL of the current version
of an object. To set the ACL of a different version, use the versionId subresource.
To see sample requests that use versioning, see Sample Request: Setting the ACL of a specified object
version (p. 472).
Requests
Syntax
The following request shows the syntax for sending the ACL in the request body. If you want to use
headers to specify the permissions for the object, you cannot send the ACL in the request body. Instead,
see the Request Headers section for a list of headers you can use.
PUT /ObjectName?acl HTTP/1.1

Date: date
4))
<Owner>
<ID>ID</ID>
</Owner>
<AccessControlList>
<Grant>
<ID>ID</ID>
</Grantee>
<Permission>Permission</Permission>
</Grant>
...

467
Requests
Note
The syntax shows some of the request headers. For a complete list see the Request Headers
section.
Request Parameters
Request Headers
You can use the following request headers in addition to the Common Request Headers (p. 2).
Access Control List (ACL) Specific Request Headers

These headers enable you to set access permissions using one of the following methods:
• Specify canned ACL, or

• Specify the permission for each grantee explicitly
Amazon S3 supports a set of predefined ACLs, known as canned ACLs. Each canned ACL has a predefined
a set of grantees and permissions. For more information, see Canned ACL. To grant access permissions by
specifying canned ACLs, you use the following header and specify the canned ACL name as its value. If
you use this header, you cannot use other access control-specific headers in your request.
x-amz-acl Sets the ACL of the object using the specified canned ACL. For No
more information, go to Canned ACL in the Amazon Simple Storage
Type: String
Valid Values: private | public-read | public-read-write

| aws-exec-read | authenticated-read | bucket-
owner-read | bucket-owner-full-control
Default: private
If you need to grant individualized access permissions on an object, you can use the following x-amz-
grant-permission headers. When using these headers you specify explicit access permissions and
grantees (AWS accounts or Amazon S3 groups) who will receive the permission. If you use these ACL
specific headers, you cannot use x-amz-acl header to set a canned ACL.
Note
Each of the following request headers maps to specific permissions Amazon S3 supports in an
ACL. For more information, go to Access Control List (ACL) Overview.
x-amz-grant- Allows the specified grantee to list the objects in the bucket. No
read
Type: String
Default: None
Constraints: None

468
Requests
x-amz-grant- Not applicable when granting access permissions on objects. You No

write can use this when granting access permissions on buckets.
Type: String
Default: None
Constraints: None
x-amz-grant- Allows the specified grantee to read the bucket ACL. No

read-acp
Type: String
Default: None
Constraints: None
x-amz-grant- Allows the specified grantee to write the ACL for the applicable No
write-acp bucket.
Type: String
Default: None
Constraints: None
x-amz-grant- Allows the specified grantee the READ, WRITE, READ_ACP, and No
full-control WRITE_ACP permissions on the bucket.
Type: String
Default: None
Constraints: None
For each of these headers, the value is a comma-separated list of one or more grantees. You specify each
grantee as a type=value pair, where the type can be one of the following:

• id — if value specified is the canonical user ID of an AWS account
• uri — if granting permission to a predefined group.
For example, the following x-amz-grant-read header grants list objects permission to the two AWS
accounts identified by their email addresses.
For more information, go to Access Control List (ACL) Overview.
Request Elements
If you decide to use the request body to specify an ACL, you must use the following elements.
Note
If you use the request body, you cannot use the request headers to set an ACL.

469
Requests
AccessControlList Container for ACL information No
Type: Container
AccessControlPolicy Contains the elements that set the ACL permissions for an No
object per grantee
Type: Container
Ancestors: None
DisplayName Screen name of the bucket owner No
Type: String
Grant Container for the grantee and his or her permissions No
Type: Container
Grantee The subject whose permissions are being set. No
Type: String
Valid Values: DisplayName | EmailAddress |

AuthenticatedUser. For more information, see Grantee
Values (p. 471).
ID ID of the bucket owner, or the ID of the grantee No
Type: String
Ancestors: AccessControlPolicy.Owner or
Owner Container for the bucket owner's display name and ID Yes
Type: Container
Permission Specifies the permission given to the grantee No
Type: String
Valid Values: FULL_CONTROL | WRITE | WRITE_ACP | READ |

READ_ACP
Ancestors:

470
Responses
Grantee Values
the following ways:
</Grantee>

• By URI:
Responses
Response Headers
Name Description
x-amz- Version of the object whose ACL is being set.

version-id
Type: String
Default: None
Response Elements
Special Errors
This operation does not return special errors. For general information about Amazon S3 errors and a list
of error codes, see Error Responses (p. 6).

471
Examples
Examples
Sample Request
The following request grants access permission to an existing object. The request specifies the ACL in the
body. In addition to granting full control to the object owner, the XML specifies full control to an AWS
account identified by its canonical user ID.
PUT /my-image.jpg?acl HTTP/1.1

Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 124
<Owner>
</Owner>
<AccessControlList>
<Grant>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeeExampleCanonicalUserID</ID>
<DisplayName>CustomerName@amazon.com</DisplayName>
</Grantee>
</Grant>
Sample Response
The following shows a sample response when versioning on the bucket is enabled.
HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51T9AS1ed4OpIszj7UDNEHGran
x-amz-version-id: 3/L4kqtJlcpXrof3vjVBH40Nr8X8gdRQBpUMLUo
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3
Sample Request: Setting the ACL of a specified object version

The following request sets the ACL on the specified version of the object.
PUT /my-image.jpg?acl&versionId=3HL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nrjfkd
HTTP/1.1
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 124
<Owner>

472
Related Resources
</Owner>
<AccessControlList>
<Grant>
</Grantee>
</Grant>
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51u8yU9AS1ed4OpIszj7UDNEHGran
x-amz-version-id: 3/L4kqtJlcpXro3vjVBH40Nr8X8gdRQBpUMLUo
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3
Sample Request: Access permissions specified using headers

The following request uses ACL-specific request headers, x-amz-acl, and specifies a canned ACL
(public_read) to grant object read access to everyone.
PUT ExampleObject.txt?acl HTTP/1.1

x-amz-acl: public-read
Accept: */*
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: w5YegkbG6ZDsje4WK56RWPxNQHIQ0CjrjyRVFZhEJI9E3kbabXnBO9w5G7Dmxsgk
x-amz-request-id: C13B2827BD8455B1
Date: Sun, 29 Apr 2012 23:24:12 GMT
Content-Length: 0
Server: AmazonS3
Related Resources

473
PUT Object tagging
PUT Object tagging

Description
This implementation of the PUT operation uses the tagging subresource to add a set of tags to an
existing object.
A tag is a key-value pair. You can associate tags with an object by sending a PUT request against the
tagging subresource that is associated with the object. You can retrieve tags by sending a GET request.
For more information, see GET Object tagging (p. 389).
For tagging-related restrictions related to characters and encodings, see Tag Restrictions in the AWS
Billing and Cost Management User Guide. Note that Amazon S3 limits the maximum number of tags to 10
tags per object.
To use this operation, you must have permission to perform the s3:PutObjectTagging action. By
To put tags of any other version, use the versionId query parameter. You also need permission for
the s3:PutObjectVersionTagging action.
For information about the Amazon S3 object tagging feature, see Object Tagging in the Amazon Simple
Requests
Syntax
The following request shows the syntax for sending tagging information in the request body.
PUT /ObjectName?tagging HTTP/1.1

Date: date
4))
<Tagging>
<TagSet>
<Tag>
<Key>Tag Name</Key>
</Tag>
</TagSet>
</Tagging>
Request Parameters
Request Headers
Content-MD5 is a required header for this operation.
Request Elements
Tagging Container for the TagSet and Tag elements. Yes

474
Responses

Type: String
Ancestors: None
TagSet Container for a set of tags Yes
Type: Container
Ancestors: Tagging
Tag Container for tag information. No
Type: Container
Ancestors: TagSet
Key Name of the tag. Yes, if Tag is

specified.
Type: String
Ancestors: Tag
Value Value of the tag. Yes, if Tag is

specified.
Type: String
Ancestors: Tag
Responses
Response Headers
Response Elements
Special Errors
• InvalidTagError - The tag provided was not a valid tag. This error can occur if the tag did not pass input
validation. For more information, see Object Tagging in the Amazon Simple Storage Service Developer
Guide.
• MalformedXMLError - The XML provided does not match the schema.
• OperationAbortedError - A conflicting conditional operation is currently in progress against this
resource. Please try again.
• InternalError - The service was unable to apply the provided tag to the object.

475
Examples
Examples
Sample Request: Add tag set to an object
The following request adds a tag set to the existing object object-key in the examplebucket bucket.
PUT object-key?tagging HTTP/1.1

Content-MD5: pUNXr/BjKK5G2UKExample==
x-amz-date: 20160923T001956Z
<Tagging>
<TagSet>
<Tag>
<Key>tag1</Key>
<Value>val1</Value>
</Tag>
<Tag>
<Key>tag2</Key>
<Value>val2</Value>
</Tag>
</TagSet>
</Tagging>
Sample Response
HTTP/1.1 200 OK
Date: Fri, 23 Sep 2016 00:20:19 GMT
Related Resources

476
SELECT Object Content
SELECT Object Content

Description
This operation filters the contents of an Amazon S3 object based on a simple structured query language
(SQL) statement. In the request, along with the SQL expression, you must also specify a data serialization
format (JSON, CSV, or Apache Parquet) of the object. Amazon S3 uses this format to parse object data
into records, and returns only records that match the specified SQL expression. You must also specify the
data serialization format for the response.
For more information about Amazon S3 Select, see Selecting Content from Objects in the Amazon
For more information about using SQL with Amazon S3 Select, see SQL Reference for Amazon S3 Select
and Glacier Select in the Amazon Simple Storage Service Developer Guide.
Permissions
You must have s3:GetObject permission for this operation. Amazon S3 Select does not support
anonymous access. For more information about permissions, see Specifying Permissions in a Policy in the
Object Data Formats

You can use Amazon S3 Select to query objects that have the following format properties:
• CSV, JSON, and Parquet – Objects must be in CSV, JSON, or Parquet format.
• UTF-8 – UTF-8 is the only encoding type Amazon S3 Select supports.
• GZIP or BZIP2 – CSV and JSON files can be compressed using GZIP or BZIP2. GZIP and BZIP2 are the
only compression formats that Amazon S3 Select supports for CSV and JSON files. Amazon S3 Select
supports columnar compression for Parquet using GZIP or Snappy. Amazon S3 Select does not support
whole-object compression for Parquet objects.
• Server-side encryption – Amazon S3 Select supports querying objects that are protected with server-
side encryption.
For objects that are encrypted with customer-provided encryption keys (SSE-C), you must use HTTPS,
and you must use the headers that are documented in the Specific Request Headers for Server-Side
Encryption with Customer-Provided Encryption Keys (p. 374) section in the Amazon S3 GET Object
REST API. For more information about SSE-C, see Server-Side Encryption (Using Customer-Provided
Encryption Keys) in the Amazon Simple Storage Service Developer Guide.
For objects that are encrypted with Amazon S3 managed encryption keys (SSE-S3) and AWS KMS
managed encryption keys (SSE-KMS), server-side encryption is handled transparently, so you don't
need to specify anything. For more information about server-side encryption, including SSE-S3 and
SSE-KMS, see Protecting Data Using Server-Side Encryption in the Amazon Simple Storage Service
Developer Guide.
Requests
Syntax
POST /ObjectName?select&select-type=2 HTTP/1.1

477
Requests
Date: date
Authorization: authorization string (See Authenticating Requests (AWS Signature Version
4))
Request body goes here
Note
The syntax shows some of the request headers. For a complete list, see the "Request Headers"
section of this topic.
Query parameters select and select-type=2 are both required for all requests. select-
type=2 is present in order to enable extensions for future capabilities.
Request Parameters
Request Headers
Request Body
The following XML shows the request body for an object in CSV format with results in CSV format:

<SelectRequest>
<Expression>Select * from S3Object</Expression>
<CompressionType>GZIP</CompressionType>
<CSV>
<AllowQuotedRecordDelimiter>FALSE</AllowQuotedRecordDelimiter>
</CSV>
<CSV>
</CSV>
<RequestProgress>
<Enabled>FALSE</Enabled>
</RequestProgress>
</SelectRequest>
The following XML shows the request body for an object in JSON format with results in JSON format:

<SelectRequest>

478
Requests

<JSON>
<Type>DOCUMENT</Type>
</JSON>
<JSON>
</JSON>
<RequestProgress>
</RequestProgress>
</SelectRequest>
The following XML shows the request body for an object in Parquet format with results in CSV format:

<SelectRequest>
<CompressionType>NONE</CompressionType>
<Parquet>
</Parquet>
<CSV>
</CSV>
<RequestProgress>
</RequestProgress>
</SelectRequest>
Note
In the XML:
• The InputSerialization element describes the format of the data in the object that is
being queried. It must specify CSV, JSON, or Parquet.
• The OutputSerialization element describes the format of the data that you want
Amazon S3 to return in response to the query. It must specify either CSV or JSON. Amazon S3
Select doesn't support outputting data in Parquet format.
• The format of the InputSerialization doesn't need to match the format
of the OutputSerialization. So, for example, you can specify JSON in the
InputSerialization and CSV in the OutputSerialization.
The following tables explain each of the XML elements in the request body.
Expression The SQL expression. For example: Yes

479
Requests

• The following SQL expression retrieves the first column of the
data from the object stored in CSV format.
SELECT s._1 FROM S3Object s

• The following SQL expression returns everything from the
object.
SELECT * FROM S3Object
Type: String
Ancestor: SelectRequest
ExpressionType Identifies the expression type. Yes
Type: String
Valid values: SQL
Describes the format of the data in the object that is being

InputSerialization Yes
queried.
Type: Container
Describes the format of the data that you want Amazon S3 to

OutputSerialization Yes
return in response.
Type: Container
RequestProgressDescribes optional, periodic QueryProgress messages that can No

be sent.
Type: Container
InputSerialization container element
CompressionTypeIdentifies whether the Amazon S3 object that is being queried No

is compressed. GZIP and BZIP2 are the only supported
compression types, and are supported only for CSV and JSON
objects. If InputSerialization specifies the Parquet format,
then CompressionType must be NONE, even if the Parquet
object uses columnar compression.
Type: String
Valid values: NONE | GZIP | BZIP2

480
Requests

Default: NONE
Ancestor: InputSerialization
CSV | JSON | Specifies the format and certain properties of the Amazon S3 Exactly one
Parquet object that is being queried. of CSV, JSON,
or Parquet is
Type: Container required.
Ancestor: InputSerialization
CSV container element (inside InputSerialization)
RecordDelimiterThe value used to separate individual records in the input. No

Instead of the default value, you can specify an arbitrary
delimiter, including an octal character. For example, \\036 is
parsed as the "record separator" (non-printing) character.
You can specify up to two characters for a record delimiter. You

can specify two characters, one character and one octal, or two
octals. For example, \r\n is a valid record delimiter.
Type: String
Default: \n
Ancestor: CSV
FieldDelimiter The value used to separate individual fields in a record. Instead No

of the default value, you can specify an arbitrary delimiter,
including an octal character. For example, \\036 is parsed as
the "record separator" (non-printing) character.
Type: String
Default: ,
Ancestor: CSV
QuoteCharacter The value to use for escaping when the field delimiter is part of No
the value.
Consider this example in a CSV file:
"a, b"
The use of quotation marks makes this value a single field

because you are wrapping the value in quotation marks. If
you don't specify the quotation marks, the comma is a field
delimiter (which makes it two separate field values, a and b).
Type: String
Default: "

481
Requests

Ancestor: CSV
The value to use for escaping the quotation mark character

inside an already escaped value. For example, the value """
a , b """ is parsed as " a , b ".
Type: String
Default: "
Ancestor: CSV
FileHeaderInfo Describes the first line in the input data. It is one of the ENUM No
values.
• NONE: The first line is not a column header.

• USE: The first line is a column header, and you can use the
header value to identify a column in an expression (for
example, SELECT "name" FROM S3Object).
• IGNORE: The first line is a column header, but you can't use
the header values to identify the column in an expression. You
can use column position (such as _1, _2, …) to identify the
column (for example, SELECT s._1 FROM S3Object s).
Type: Enum
Valid values: NONE | USE | IGNORE
Ancestor: CSV
Comments If the first character of a line of text matches the comment No

character, the row is considered a comment and is discarded
from the input. You can specify any character to indicate a
comment line.
Type: String
Default: #
Ancestor: CSV
Specifies that CSV input records might contain record delimiters

AllowQuotedRecordDelimiter No
within quote characters. Setting this option to TRUE could result
in slower performance.
Type: Boolean
Default: FALSE
Ancestor: CSV

482
Requests
JSON container element (inside InputSerialization)
Type The type of JSON content. LINES means that each line in the Yes
input data contains a single JSON object. DOCUMENT means that
a single JSON object can span multiple lines in the input. Using
DOCUMENT might result in slower performance in some cases.
Type: Enum
Valid values: DOCUMENT | LINES
Ancestor: JSON
OutputSerialization container element
CSV | JSON Specifies the format and certain properties of the data that is Exactly one of
returned in response. CSV or JSON is
required.
Type: Container
Ancestor: OutputSerialization
CSV container element (inside OutputSerialization)
QuoteFields Indicates whether to use quotation marks around output fields. No
• ALWAYS: Always use quotation marks for output fields.

• ASNEEDED: Use quotation marks for output fields when
needed.
Type: String
Valid values: ALWAYS | ASNEEDED
Default: ASNEEDED
Ancestor: CSV
RecordDelimiterThe value used to separate individual records in the output. No


Type: String
Default: \n

483
Requests

Ancestor: CSV
FieldDelimiter The value you want Amazon S3 to use to separate individual No

fields in a record. Instead of the default value, you can specify
an arbitrary delimiter, including an octal character. For example,
\\036 is parsed as the "record separator" (non-printing)
character.
Type: String
Default: ,
Ancestor: CSV
QuoteCharacter The value to use for escaping when the field delimiter is part No
of the value. For example, if the value is a, b, then Amazon S3
wraps this field value in quotation marks as follows: " a , b
".
Type: String
Default: "
Ancestor: CSV
The value to use for escaping the quotation mark character

inside an already escaped value. For example, if the value is "
a , b ", then Amazon S3 wraps the value in quotation marks
as follows: """ a , b """.
Type: String
Default: "
Ancestor: CSV
JSON container element (inside OutputSerialization)
RecordDelimiterThe value used to separate individual records in the output. No


Type: String
Default: \n
Ancestor: JSON

484
Responses
RequestProgress container element
Enabled Specifies whether periodic QueryProgress messages should be No

sent.
Type: Boolean
Default: FALSE
Ancestor: RequestProgress
Responses
A successful operation returns 200 OK status code.
Response Headers
Response Body
Because the response size is unknown, Amazon S3 streams the response as a series of messages and
includes a Transfer-Encoding header with chunked as its value in the response. The following
example shows the response format at the top level:
<Message 1>
<Message 2>
<Message 3>
......
<Message n>
Each message consists of two sections: the prelude and the data. The prelude section consists of 1) the
total byte-length of the message, and 2) the combined byte-length of all the headers. The data section
consists of 1) the headers, and 2) a payload.
Each section ends with a 4-byte big-endian integer checksum (CRC). Amazon S3 Select uses CRC32
(often referred to as GZIP CRC32) to calculate both CRCs. For more information about CRC32, see GZIP
file format specification version 4.3.
Total message overhead including the prelude and both checksums is 16 bytes.
Note
All integer values within messages are in network byte order, or big-endian order.
The following diagram shows the components that make up a message and a header. Note that there are
multiple headers per message.

485
Responses
Note
For Amazon S3 Select, the header value type is always 7 (type=String). For this type, the header
value consists of two components, a 2-byte big-endian integer length, and a UTF-8 string that
is of that byte-length. The following diagram shows the components that make up Amazon S3
Select headers.
Payload byte-length calculations (these two calculations are equivalent):
• payload_length = total_length - header_length - sizeOf(total_length) - sizeOf(header_length) -

sizeOf(prelude_crc) - sizeOf(message_crc)
• payload_length = total_length - header_length - 16
Each message contains the following components:
• Prelude: Always fixed size of 8 bytes (two fields of 4 bytes each):

486
Responses
• First four bytes: Total byte-length: Big-endian integer byte-length of the entire message (including
the 4-byte total length field itself).
• Second four bytes: Headers byte-length: Big-endian integer byte-length of the headers portion of
the message (excluding the headers length field itself).
• Prelude CRC: 4-byte big-endian integer checksum (CRC) for the prelude portion of the message
(excluding the CRC itself). The prelude has a separate CRC from the message CRC (see below),
to ensure that corrupted byte-length information can be detected immediately, without causing
pathological buffering behavior.
• Headers: A set of metadata annotating the message, such as the message type, payload format, and
so on. Messages can have multiple headers, so this portion of the message can have different byte-
lengths depending on the message type. Headers are key-value pairs, where both the key and value
are UTF-8 strings. Headers can appear in any order within the headers portion of the message, and any
given header type can only appear once.
For Amazon S3 Select, following is a list of header names and the set of valid values depending on the
message type.
• MessageType Header:
• HeaderName => ":message-type"
• Valid HeaderValues => "error", "event"
• EventType Header:
• HeaderName => ":event-type"
• Valid HeaderValues => "Records", "Cont", "Progress", "Stats", "End"
• ErrorCode Header:
• HeaderName => ":error-code"
• Valid HeaderValues => Error Code from the table in the Special Errors (p. 494) section.
• ErrorMessage Header:
• HeaderName => ":error-message"
• Valid HeaderValues => Error message returned by the service, to help diagnose request-level
errors.
• Payload: Can be anything.
• Message CRC: 4-byte big-endian integer checksum (CRC) from the start of the message to the start of
the checksum (that is, everything in the message excluding the message CRC itself).
Each header contains the following components. There can be multiple headers per message.
• Header Name Byte-Length: Byte-length of the header name.

• Header Name: Name of the header, indicating the header type. Valid values: ":message-type" ":event-
type" ":error-code" ":error-message"
• Header Value Type: Enum indicating the header value type. For Amazon S3 Select, this is always 7.
• Value String Byte-Length: (For Amazon S3 Select) Byte-length of the header value string.
• Header Value String: (For Amazon S3 Select) Value of the header string. Valid values for this field
vary based on the type of the header. See the sections below for valid values for each header type and
message type.
For Amazon S3 Select, responses can be messages of the following types:
• Records message: Can contain a single record, partial records, or multiple records. Depending on the
size of the result, a response can contain one or more of these messages.

487
Responses
• Continuation message: Amazon S3 periodically sends this message to keep the TCP connection open.
These messages appear in responses at random. The client must detect the message type and process
accordingly.
• Progress message: Amazon S3 periodically sends this message, if requested. It contains information
about the progress of a query that has started but has not yet completed.
• Stats message: Amazon S3 sends this message at the end of the request. It contains statistics about
the query.
• End message: Indicates that the request is complete, and no more messages will be sent. You should
not assume that the request is complete until the client receives an End message.
• RequestLevelError message: Amazon S3 sends this message if the request failed for any reason. It
contains the error code and error message for the failure. If Amazon S3 sends a RequestLevelError
message, it doesn't send an End message.
The following sections explain the structure of each message type in more detail.
For sample code and unit tests that use this protocol, see AWS C Event Stream on the GitHub website.
Records Message
Header specification
Records messages contain three headers, as follows:

488
Responses
Payload specification
Records message payloads can contain a single record, partial records, or multiple records.
Continuation Message
Continuation messages contain two headers, as follows:

489
Responses
Continuation messages have no payload.
Progress Message
Progress messages contain three headers, as follows:

490
Responses
Progress message payload is an XML document containing information about the progress of a request.
• BytesScanned => Number of bytes that have been processed before being uncompressed (if the file is
compressed).
• BytesProcessed => Number of bytes that have been processed after being uncompressed (if the file is
compressed).
• BytesReturned => Current number of bytes of records payload data returned by Amazon S3.
For uncompressed files, BytesScanned and BytesProcessed are equal.
Example:

<Progress>
<BytesScanned>512</BytesScanned>
<BytesProcessed>1024</BytesProcessed>
<BytesReturned>1024</BytesReturned>
</Progress>

491
Responses
Stats Message
Stats messages contain three headers, as follows:
Stats message payload is an XML document containing information about a request's stats when
processing is complete.
• BytesScanned => Number of bytes that have been processed before being uncompressed (if the file is
compressed).
• BytesProcessed => Number of bytes that have been processed after being uncompressed (if the file is
compressed).
• BytesReturned => Total number of bytes of records payload data returned by Amazon S3.
For uncompressed files, BytesScanned and BytesProcessed are equal.
Example:

492
Responses
<Stats>
<BytesScanned>512</BytesScanned>
<BytesProcessed>1024</BytesProcessed>
<BytesReturned>1024</BytesReturned>
</Stats>
End Message
End messages contain two headers, as follows:
End messages have no payload.
Request Level Error Message

Request-level error messages contain three headers, as follows:

493
Responses
For a list of possible error codes and error messages, see the table in the Special Errors (p. 494) section.
Request-level error messages have no payload.
Special Errors
The following table contains special errors that SELECT Object Content might return.

Code Code Prefix
Busy The service is unavailable. Please 503 Client

retry.
UnauthorizedAccess You are not authorized to perform 401 Client

this operation
EmptyRequestBody Request body cannot be empty. 400 Client

494
Responses

Code Code Prefix
ExpressionTooLong The SQL expression is too long: The 400 Client

maximum byte-length for the SQL
expression is 256 KB.
IllegalSqlFunctionArgumentIllegal argument was used in the 400 Client

SQL function.
InternalError Encountered an internal error. 500 Client
InvalidColumnIndex Column index in the SQL expression 400 Client

is invalid.
InvalidKeyPath Key path in the SQL expression is 400 Client

invalid.
ColumnTooLong The length of a column in the result 400 Client

is greater than maxCharsPerColumn
of 1 MB.
OverMaxColumn The number of columns in the 400 Client

result is greater than the maximum
allowable number of columns.
OverMaxRecordSize The length of a record in the 400 Client

input or result is greater than
maxCharsPerRecord of 1 MB.
MissingHeaders Some headers in the query are 400 Client

missing from the file. Check the file
and try again.
InvalidCompressionFormat The file is not in a supported 400 Client

compression format. Only GZIP and
BZIP2 are supported.
TruncatedInput Object decompression failed. 400 Client

Check that the object is properly
compressed using the format
specified in the request.
InvalidExpressionType The ExpressionType is invalid. Only 400 Client

SQL expressions are supported.
InvalidFileHeaderInfo The FileHeaderInfo is invalid. 400 Client

Only NONE, USE, and IGNORE are
supported.
InvalidJsonType The JsonType is invalid. Only 400 Client

DOCUMENT and LINES are
supported.
InvalidQuoteFields The QuoteFields is invalid. Only 400 Client

ALWAYS and ASNEEDED are
supported.

495
Responses

Code Code Prefix
InvalidRequestParameter The value of a parameter 400 Client

in SelectRequest element is
invalid. Check the service API
documentation and try again.
CSVParsingError Encountered an error parsing the 400 Client

CSV file. Check the file and try again.
JSONParsingError Encountered an error parsing the 400 Client

JSON file. Check the file and try
again.
ExternalEvalException The query cannot be evaluated. 400 Client

Check the file and try again.
InvalidDataType The SQL expression contains an 400 Client

invalid data type.
Encountered an invalid record type.

UnrecognizedFormatException 400 Client
InvalidTextEncoding Invalid encoding type. Only UTF-8 400 Client

encoding is supported.
InvalidDataSource Invalid data source type. Only CSV, 400 Client

JSON, and Parquet are supported.
InvalidTableAlias The SQL expression contains an 400 Client

invalid table alias.
MalformedXML The XML provided was not well- 400 Client

formed or did not validate against
our published schema. Check the
service documentation and try
again.
Multiple data sources are not

MultipleDataSourcesUnsupported 400 Client
supported.
MissingRequiredParameter The SelectRequest entity is missing 400 Client

a required parameter. Check the
service documentation and try
again.
InputSerialization specifies more

ObjectSerializationConflict 400 Client
than one format (CSV, JSON, or
Parquet), or OutputSerialization
specifies more than one format (CSV
or JSON). InputSerialization and
OutputSerialization can only specify
one format each.
UnsupportedFunction Encountered an unsupported SQL 400 Client

function.
UnsupportedSqlOperation Encountered an unsupported SQL 400 Client

operation.

496
Responses

Code Code Prefix
UnsupportedSqlStructure Encountered an unsupported SQL 400 Client

structure. Check the SQL Reference.
UnsupportedStorageClass Encountered an invalid storage class. 400 Client

Only STANDARD, STANDARD_IA, and
ONEZONE_IA storage classes are
supported.
UnsupportedSyntax Encountered invalid syntax. 400 Client
UnsupportedRangeHeader Range header is not supported for 400 Client

this operation.
LexerInvalidChar The SQL expression contains an 400 Client

invalid character.
LexerInvalidOperator The SQL expression contains an 400 Client

invalid literal.
LexerInvalidLiteral The SQL expression contains an 400 Client

invalid operator.
LexerInvalidIONLiteral The SQL expression contains an 400 Client

invalid operator.
ParseExpectedDatePart Did not find the expected date part 400 Client
in the SQL expression.
ParseExpectedKeyword Did not find the expected keyword in 400 Client

the SQL expression.
ParseExpectedTokenType Did not find the expected token in 400 Client

the SQL expression.
ParseExpected2TokenTypes Did not find the expected token in 400 Client

the SQL expression.
ParseExpectedNumber Did not find the expected number in 400 Client

the SQL expression.
Did not find the expected right

ParseExpectedRightParenBuiltinFunctionCall 400 Client
parenthesis character in the SQL
expression.
ParseExpectedTypeName Did not find the expected type name 400 Client
in the SQL expression.
ParseExpectedWhenClause Did not find the expected WHEN 400 Client

clause in the SQL expression. CASE is
not supported.
ParseUnsupportedToken The SQL expression contains an 400 Client

unsupported token.
The SQL expression contains an

ParseUnsupportedLiteralsGroupBy 400 Client
unsupported use of GROUP BY.

497
Responses

Code Code Prefix
ParseExpectedMember The SQL expression contains an 400 Client

unsupported use of MEMBER.
ParseUnsupportedSelect The SQL expression contains an 400 Client

unsupported use of SELECT.
ParseUnsupportedCase The SQL expression contains an 400 Client

unsupported use of CASE.
ParseUnsupportedCaseClauseThe SQL expression contains an 400 Client

unsupported use of CASE.
ParseUnsupportedAlias The SQL expression contains an 400 Client

unsupported use of ALIAS.
ParseUnsupportedSyntax The SQL expression contains 400 Client

unsupported syntax.
ParseUnknownOperator The SQL expression contains an 400 Client

invalid operator.
ParseInvalidPathComponent The SQL expression contains an 400 Client

invalid path component.
ParseMissingIdentAfterAt Did not find the expected identifier 400 Client

after the @ symbol in the SQL
expression.
ParseUnexpectedOperator The SQL expression contains an 400 Client

unexpected operator.
ParseUnexpectedTerm The SQL expression contains an 400 Client

unexpected term.
ParseUnexpectedToken The SQL expression contains an 400 Client

unexpected token.
ParseUnExpectedKeyword The SQL expression contains an 400 Client

unexpected keyword.
ParseExpectedExpression Did not find the expected SQL 400 Client

expression.
Did not find the expected left

ParseExpectedLeftParenAfterCast 400 Client
parenthesis after CAST in the SQL
expression.
Did not find expected the left

ParseExpectedLeftParenValueConstructor 400 Client
parenthesis in the SQL expression.
Did not find the expected left

ParseExpectedLeftParenBuiltinFunctionCall 400 Client
parenthesis in the SQL expression.
Did not find the expected argument

ParseExpectedArgumentDelimiter 400 Client
delimiter in the SQL expression.

498
Responses

Code Code Prefix
ParseCastArity The SQL expression CAST has 400 Client

incorrect arity.
ParseInvalidTypeParam The SQL expression contains an 400 Client

invalid parameter value.
ParseEmptySelect The SQL expression contains an 400 Client

empty SELECT.
ParseSelectMissingFrom The SQL expression contains a 400 Client

missing FROM after SELECT list.
GROUP is not supported in the SQL

ParseExpectedIdentForGroupName 400 Client
expression.
ParseExpectedIdentForAliasDid not find the expected identifier 400 Client

for the alias in the SQL expression.
Only COUNT with (*) as a parameter

ParseUnsupportedCallWithStar 400 Client
is supported in the SQL expression.
Only one argument is supported

ParseNonUnaryAgregateFunctionCall 400 Client
for aggregate functions in the SQL
expression.
ParseMalformedJoin JOIN is not supported in the SQL 400 Client

expression.
ParseExpectedIdentForAt Did not find the expected identifier 400 Client

for AT name in the SQL expression.
Other expressions are not allowed

ParseAsteriskIsNotAloneInSelectList 400 Client
in the SELECT list when '*' is used
without dot notation in the SQL
expression.
Cannot mix [] and * in the same

ParseCannotMixSqbAndWildcardInSelectList 400 Client
expression in a SELECT list in SQL
expression.
Invalid use of * in SELECT list in the

ParseInvalidContextForWildcardInSelectList 400 Client
SQL expression.
A column name or a path provided

EvaluatorBindingDoesNotExist 400 Client
does not exist in the SQL expression.
ValueParseFailure Time stamp parse failure in the SQL 400 Client

expression.
Incorrect type of arguments in

IncorrectSqlFunctionArgumentType 400 Client
function call in the SQL expression.
AmbiguousFieldName Field name matches to multiple 400 Client

fields in the file. Check the SQL
expression and the file, and try
again.

499
Responses

Code Code Prefix
EvaluatorInvalidArguments Incorrect number of arguments 400 Client

in the function call in the SQL
expression.
Invalid time stamp format string in

EvaluatorInvalidTimestampFormatPattern 400 Client
the SQL expression.
ValueParseFailure Time stamp parse failure in the SQL 400 Client

expression.
IntegerOverflow Integer overflow or underflow in the 400 Client

SQL expression.
LikeInvalidInputs Invalid argument given to the LIKE 400 Client

clause in the SQL expression.
CastFailed Attempt to convert from one data 400 Client

type to another using CAST failed in
the SQL expression.
InvalidCast Attempt to convert from one data 400 Client

type to another using CAST failed in
the SQL expression.
Time stamp format pattern

EvaluatorInvalidTimestampFormatPattern 400 Client
requires additional fields in the SQL
expression.
Time stamp format pattern contains 400

EvaluatorInvalidTimestampFormatPatternSymbolForParsing Client
a valid format symbol that cannot
be applied to time stamp parsing in
the SQL expression.

EvaluatorTimestampFormatPatternDuplicateFields 400 Client
contains multiple format specifiers
representing the time stamp field in
the SQL expression.
Time stamp format pattern contains

EvaluatorTimestampFormatPatternHourClockAmPmMismatch 400 Client
a 12-hour hour of day format
symbol but doesn't also contain an
AM/PM field, or it contains a 24-
hour hour of day format specifier
and contains an AM/PM field in the
SQL expression.

EvaluatorUnterminatedTimestampFormatPatternToken 400 Client
unterminated token in the SQL
expression.

EvaluatorInvalidTimestampFormatPatternToken 400 Client
contains an invalid token in the SQL
expression.

500
Examples

Code Code Prefix

EvaluatorInvalidTimestampFormatPatternSymbol 400 Client
an invalid symbol in the SQL
expression.
ParquetParsingError Error parsing Parquet file. Please 400 Client

check the file and try again.
Examples
Example 1: CSV Object
The following select request retrieves all records from an object with data stored in CSV format. The
OutputSerialization element directs Amazon S3 to return results in CSV.
POST /exampleobject.csv?select&select-type=2 HTTP/1.1

Date: Tue, 17 Oct 2017 01:49:52 GMT

<SelectRequest>
<CSV>
</CSV>
<CSV>
</CSV>
</SelectRequest>
You can try different queries in the Expression element:
• Assuming that you are not using column headers, you can identify columns using positional headers:
SELECT s._1, s._2 FROM S3Object s WHERE s._3 > 100
• If you have column headers and you set the FileHeaderInfo to Use, you can identify columns by
name in the expression:

501
Examples
SELECT s.Id, s.FirstName, s.SSN FROM S3Object s
• You can specify functions in the SQL expression:
SELECT count(*) FROM S3Object s WHERE s._1 < 1
HTTP/1.1 200 OK
Date: Tue, 17 Oct 2017 23:54:05 GMT
A series of messages
Example 2: JSON Object

The following select request retrieves all records from an object with data stored in JSON format. The
OutputSerialization directs Amazon S3 to return results in CSV.
POST /exampleobject.json?select&select-type=2 HTTP/1.1

Date: Tue, 17 Oct 2017 01:49:52 GMT

<SelectRequest>
<JSON>
<Type>DOCUMENT</Type>
</JSON>
<CSV>
</CSV>
</SelectRequest>
You can try different queries in the Expression element:
• You can filter by string comparison using record keys:
SELECT s.country, s.city from S3Object s where s.city = 'Seattle'
• You can specify functions in the SQL expression:
SELECT count(*) FROM S3Object s

502
Notes
Example 3: Parquet Object

The following select request retrieves all records from an object with data stored in Parquet format. The
OutputSerialization directs Amazon S3 to return results in CSV.
POST /exampleobject.parquet?select&select-type=2 HTTP/1.1

Date: Tue, 17 Oct 2017 01:49:52 GMT

<SelectRequest>
<CompressionType>NONE</CompressionType>
<Parquet>
</Parquet>
<CSV>
</CSV>
</SelectRequest>
Notes
The SELECT Object Content operation does not support the following GET Object functionality.
For more information, see GET Object (p. 370).
• Range: You cannot specify the range of bytes of an object to return.

• GLACIER, DEEP_ARCHIVE and REDUCED_REDUNDANCY storage classes: You cannot specify the
GLACIER, DEEP_ARCHIVE, or REDUCED_REDUNDANCY storage classes. For more information, about
storage classes see Storage Classes in the Amazon Simple Storage Service Developer Guide.
Related Resources

503
Abort Multipart Upload
Abort Multipart Upload

Description
This operation aborts a multipart upload. After a multipart upload is aborted, no additional parts can be
uploaded using that upload ID. The storage consumed by any previously uploaded parts will be freed.
However, if any part uploads are currently in progress, those part uploads might or might not succeed.
As a result, it might be necessary to abort a given multipart upload multiple times in order to completely
free all storage consumed by all parts. To verify that all parts have been removed, so you don't get
charged for the part storage, you should call the List Parts (p. 522) operation and ensure the parts list
is empty.
For information on permissions required to use the multipart upload API, go to Multipart Upload API and
Requests
Syntax
DELETE /ObjectName?uploadId=UploadId HTTP/1.1
Date: Date
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements
This operation does not use response elements.

504
Examples
Special Errors
Error Code Description HTTP Status SOAP

Code Fault Code
Prefix
NoSuchUpload The specified multipart upload does not exist. 404 Not Found Client
The upload ID might be invalid, or the multipart
upload might have been aborted or completed.
Examples
Sample Request
The following request aborts a multipart upload identified by its upload ID.
DELETE /example-object?uploadId=VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZ
HTTP/1.1
Date: Mon, 1 Nov 2010 20:34:56 GMT
Sample Response
HTTP/1.1 204 OK
x-amz-id-2: Weag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 0
Server: AmazonS3
Related Actions

505
Complete Multipart Upload
Complete Multipart Upload

Description
This operation completes a multipart upload by assembling previously uploaded parts.
You first initiate the multipart upload and then upload all parts using the Upload Parts operation
(see Upload Part (p. 528)). After successfully uploading all relevant parts of an upload, you call this
operation to complete the upload. Upon receiving this request, Amazon S3 concatenates all the parts in
ascending order by part number to create a new object. In the Complete Multipart Upload request, you
must provide the parts list. You must ensure the parts list is complete, this operation concatenates the
parts you provide in the list. For each part in the list, you must provide the part number and the ETag
header value, returned after that part was uploaded.
Processing of a Complete Multipart Upload request could take several minutes to complete. After
Amazon S3 begins processing the request, it sends an HTTP response header that specifies a 200 OK
response. While processing is in progress, Amazon S3 periodically sends whitespace characters to keep
the connection from timing out. Because a request could fail after the initial 200 OK response has been
sent, it is important that you check the response body to determine whether the request succeeded.
Note that if Complete Multipart Upload fails, applications should be prepared to retry the failed
requests. For more information, go to Amazon S3 Error Best Practices section of the Amazon Simple
For more information on multipart uploads, go to Uploading Objects Using Multipart Upload in the
For information on permissions required to use the multipart upload API, go to Multipart Upload API and
Requests
Syntax
POST /ObjectName?uploadId=UploadId HTTP/1.1
Date: Date
<CompleteMultipartUpload>
<Part>
<PartNumber>PartNumber</PartNumber>
<ETag>ETag</ETag>
</Part>
...
</CompleteMultipartUpload>
Request Parameters
Request Headers
Request Headers (p. 2)

506
Responses
Request Elements
CompleteMultipartUpload Container for the request. Yes
Ancestor: None
Type: Container
Children: One or more Part elements
Part Container for elements related to a particular previously Yes

uploaded part.
Ancestor: CompleteMultipartUpload
Type: Container
Children: PartNumber, ETag
PartNumber Part number that identifies the part. Yes
Ancestor: Part
Type: Integer
ETag Entity tag returned when the part was uploaded. Yes
Ancestor: Part
Type: String
Responses
Response Headers
The operation uses the following response header, in addition to the response headers common to most
requests. For more information, see Common Response Headers (p. 4).
Header Description
x-amz- Amazon S3 returns this header if an Expiration action is configured for the
expiration object as part of the bucket's lifecycle configuration. The header value includes
an "expiry-date" component and a URL-encoded "rule-id" component. Note that
for versioning-enabled buckets, this header applies only to current versions;
Amazon S3 does not provide a header to infer when a noncurrent version will
be eligible for permanent deletion. For more information, see PUT Bucket
lifecycle (p. 290).
Type: String
x-amz-server- If you specified server-side encryption either with an AWS KMS or Amazon S3-
side-encryption managed encryption key in your initiate multipart upload request, the response
includes this header. It confirms the encryption algorithm that Amazon S3 used
to encrypt the object.

507
Responses
Header Description
Type: String

server-side- aws:kms, this header specifies the ID of the AWS Key Management Service
encryption-aws- (KMS) master encryption key that was used for the object.
kms-key-id
Type: String
x-amz-server- If encryption by using server-side encryption with customer-provided encryption

side-encryption keys was requested, the response will include this header confirming the
-customer- encryption algorithm used.
algorithm
Type: String
Valid Value: AES256
x-amz-version- Version ID of the newly created object, in case the bucket has versioning turned
id on.
Type: String
Response Elements
Name Description
CompleteMultipartUploadResult Container for the response
Type: Container
Children: Location, Bucket, Key, ETag
Ancestors: None
Location The URI that identifies the newly created object.
Type: URI
Ancestors: CompleteMultipartUploadResult
Bucket The name of the bucket that contains the newly created
object.
Type: String
Key The object key of the newly created object.
Type: String
ETag Entity tag that identifies the newly created object's data.
Objects with different object data will have different entity
tags. The entity tag is an opaque string. The entity tag
may or may not be an MD5 digest of the object data. If the
entity tag is not an MD5 digest of the object data, it will

508
Examples
Name Description
contain one or more nonhexadecimal characters and/or will
consist of less than 32 or more than 32 hexadecimal digits.
Type: String
Special Errors
Error Code Description HTTP Status

Code
EntityTooSmall Your proposed upload is smaller than the minimum 400 Bad Request
allowed object size. Each part must be at least 5 MB in
size, except the last part.
InvalidPart One or more of the specified parts could not be found. 400 Bad Request
The part might not have been uploaded, or the specified
entity tag might not have matched the part's entity tag.
InvalidPartOrder The list of parts was not in ascending order. The parts list 400 Bad Request
must be specified in order by part number.
NoSuchUpload The specified multipart upload does not exist. The upload 404 Not Found
ID might be invalid, or the multipart upload might have
been aborted or completed.
Examples
Sample Request
The following Complete Multipart Upload request specifies three parts in the
CompleteMultipartUpload element.
POST /example-object?uploadId=AAAsb2FkIElEIGZvciBlbHZpbmcncyWeeS1tb3ZpZS5tMnRzIRRwbG9hZA
HTTP/1.1
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 391
<CompleteMultipartUpload>
<Part>
<PartNumber>1</PartNumber>
<ETag>"a54357aff0632cce46d942af68356b38"</ETag>
</Part>
<Part>
<ETag>"0c78aef83f66abc1fa1e8477f296d394"</ETag>
</Part>
<Part>

509
Examples
<ETag>"acbd18db4cc2f85cedef654fccc4a4d8"</ETag>
</Part>
</CompleteMultipartUpload>
Sample Response
The following response indicates that an object was successfully assembled.
HTTP/1.1 200 OK
Date: Mon, 1 Nov 2010 20:34:56 GMT
Connection: close
Server: AmazonS3

<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Location>http://Example-Bucket.s3.amazonaws.com/Example-Object</Location>
<Bucket>Example-Bucket</Bucket>
<Key>Example-Object</Key>
<ETag>"3858f62230ac3c915f300c664312c11f-9"</ETag>
</CompleteMultipartUploadResult>
Sample Response with Error Specified in Header

The following response indicates that an error occurred before the HTTP response header was sent.
HTTP/1.1 403 Forbidden

Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 237
Server: AmazonS3

<Error>
<Code>AccessDenied</Code>
<Message>Access Denied</Message>
<RequestId>656c76696e6727732072657175657374</RequestId>
<HostId>Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==</HostId>
</Error>
Sample Response with Error Specified in Body

The following response indicates that an error occurred after the HTTP response header was sent.
Note that while the HTTP status code is 200 OK, the request actually failed as described in the Error
element.
HTTP/1.1 200 OK
Date: Mon, 1 Nov 2010 20:34:56 GMT
Connection: close
Server: AmazonS3
<Error>
<Code>InternalError</Code>

510
Related Actions
<Message>We encountered an internal error. Please try again.</Message>

<RequestId>656c76696e6727732072657175657374</RequestId>
<HostId>Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==</HostId>
</Error>
Related Actions

511
Initiate Multipart Upload
Initiate Multipart Upload

Description
This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate
all of the parts in the specific multipart upload. You specify this upload ID in each of your subsequent
upload part requests (see Upload Part (p. 528)). You also include this upload ID in the final request to
either complete or abort the multipart upload request.
For more information about multipart uploads, see Multipart Upload Overview in the Amazon Simple
If you have configured a lifecycle rule to abort incomplete multipart uploads, the upload must complete
within the number of days specified in the bucket lifecycle configuration. Otherwise, the incomplete
multipart upload becomes eligible for an abort operation and Amazon S3 aborts the multipart upload.
For more information, see Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle Policy in the
For information about the permissions required to use the multipart upload API, see Multipart Upload
API and Permissions in the Amazon Simple Storage Service Developer Guide.
For request signing, multipart upload is just a series of regular requests. You initiate a multipart upload,
send one or more requests to upload parts, and then complete the multipart upload process. You sign
each request individually. There is nothing special about signing multipart upload requests. For more
information about signing, see Authenticating Requests (AWS Signature Version 4) (p. 14).
Note
After you initiate a multipart upload and upload one or more parts, to stop being charged for
storing the uploaded parts, you must either complete or abort the multipart upload. Amazon S3
frees up the space used to store the parts and stop charging you for storing them only after you
either complete or abort a multipart upload.
You can optionally request server-side encryption. For server-side encryption, Amazon S3 encrypts your
data as it writes it to disks in its data centers and decrypts it when you access it. You can provide your
own encryption key, or use AWS Key Management Service (AWS KMS) encryption keys or Amazon S3-
managed encryption keys. If you choose to provide your own encryption key, the request headers you
provide in Upload Part (p. 528) and Upload Part - Copy (p. 534) requests must match the headers
you used in the request to initiate the upload by using Initiate Multipart Upload (p. 512). For more
information, see Protecting Data Using Server-Side Encryption in the Amazon Simple Storage Service
Developer Guide.
Requests
Syntax
POST /ObjectName?uploads HTTP/1.1
Date: date
4))
Request Parameters

512
Requests
Request Headers
Cache-Control Can be used to specify caching behavior along the request/reply No

chain. For more information, see http://www.w3.org/Protocols/
rfc2616/rfc2616-sec14.html#sec14.9.
Type: String
Default: None
Content- Specifies presentational information for the object. For more No

Disposition information, see http://www.w3.org/Protocols/rfc2616/rfc2616-
sec19.html#sec19.5.1.
Type: String
Default: None
Content-Encoding Specifies the content encodings that have been applied to the No
object and which decoding mechanisms must be applied to
obtain the media-type referenced by the Content-Type header
field. For more information, see http://www.w3.org/Protocols/
Type: String
Default: None
Content-Type A standard MIME type that describes the format of the object No
data. For more information, see http://www.w3.org/Protocols/
Type: String
Default: binary/octet-stream
Constraints: MIME types only
Expires The date and time at which the object should no longer be No
cached. For more information, see http://www.w3.org/Protocols/
Type: String
Default: None
x-amz-meta- Headers starting with this prefix are user-defined metadata. Each No
one is stored and returned as a set of key-value pairs. Amazon
S3 doesn't validate or interpret user-defined metadata. For more
information, see PUT Object (p. 434).
Type: String
Default: None
x-amz-storage- The type of storage to use for the object that is created after a No
class successful multipart upload. If you don't specify a class, Amazon
S3 uses the default storage class, Standard. Amazon S3 supports

513
Requests

other storage classes. For more information, see Storage Classes
Type: Enum
Default: STANDARD

DEEP_ARCHIVE
x-amz-tagging Specifies a set of one or more tags you want associated with No
the object. These tags are stored in the tagging subresource
associated with the object.
For more information about adding tags to an object, see Object

Tagging Management in the Amazon Simple Storage Service
Developer Guide.
Type: String
Default: None
Constraints: The encoding for tags will be URL query parameter

encoding. The maximum size of this header is limited to 2 K.
x-amz-website If the bucket is configured as a website, redirects requests for No

-redirect- this object to another object in the same bucket or to an external
location URL. Amazon S3 stores the value of this header in the object
metadata. For information about object metadata, see Object Key
and Metadata.
In the following example, the request header sets the redirect to

an object (anotherPage.html) in the same bucket:
anotherPage.html
In the following example, the request header sets the object

redirect to another website:
www.example.com/
For more information about website hosting in Amazon S3, see

Hosting Websites on Amazon S3 and How to Configure Website
Page Redirects in the Amazon Simple Storage Service Developer
Guide.
Type: String
Default: None
Constraints: The value must be prefixed by, "/", "http://" or

"https://". The length of the value is limited to 2 K.

514
Requests
Access Control List (ACL) Specific Request Headers

Additionally, you can use the following access control-related headers with this operation. By default, all
objects are private and only the owner has full access control. When adding a new object, you can grant
permissions to individual AWS accounts or predefined groups defined by Amazon S3. These permissions
are then added to the Access Control List (ACL) on the object. For more information, see Access Control
List (ACL) Overview in the Amazon Simple Storage Service Developer Guide. This operation enables you to
grant access permissions using one of the following methods:
• Specify canned ACL – Amazon S3 supports a set of predefined ACLs, known as canned ACLs. Each
canned ACL has a predefined set of grantees and permissions. For more information, see Canned ACL.
x-amz-acl The canned ACL to apply to the object. No
Type: String
Default: private

Constraints: None
• Specify access permissions explicitly – If you want to explicitly grant access permissions to
specific AWS accounts or groups, use the following headers. Each of these headers maps to specific
permissions that Amazon S3 supports in an access control list (ACL). For more information, see
Access Control List (ACL) Overview. In the header, you specify a list of grantees who get the specific
permission.
x-amz-grant-read Allows the grantee to read the object data and its No
metadata.
Type: String
Default: None
Constraints: None
x-amz-grant-write Not applicable. No
Type: String
Default: None
Constraints: None
x-amz-grant-read- Allows the grantee to read the object ACL. No

acp
Type: String
Default: None

515
Requests

Constraints: None
x-amz-grant-write- Allows the grantee to write the ACL for the applicable No
acp object.
Type: String
Default: None
Constraints: None
x-amz-grant-full- Grants the grantee the READ, READ_ACP, and WRITE_ACP No

control permissions on the object.
Type: String
Default: None
Constraints: None
You specify each grantee as a type=value pair, where the type can be one of the following:
• emailAddress – If the specified value is the email address of an AWS account.

• id – If the specified value is the canonical user ID of an AWS account.
• uri – If you are granting permission to a predefined group.
For example, the following x-amz-grant-read header grants read object data and its metadata
permissions to the AWS accounts identified by their email addresses:
Server-Side Encryption–Specific Request Headers

You can optionally tell Amazon S3 to encrypt data at rest using server-side encryption. Server-side
encryption is for data encryption at rest. Amazon S3 encrypts your data as it writes it to disks in its
data centers and decrypts it when you access it. Depending on whether you want to use AWS-managed
encryption keys or provide your own encryption keys, you use the following headers:
• Use encryption keys managed by AWS KMS or Amazon S3 – If you want AWS to manage the keys used
to encrypt data, specify the following headers in the request.
x-amz-server-side Specifies a server-side encryption algorithm to use when Yes

Type: String
x-amz-server- If the x-amz-server-side-encryption is present and has Yes, if the

aws-kms-key-id x-amz-

516
Requests

Key Management Service (AWS KMS) master encryption key server-
that was used for the object. side-
encryption
Type: String is
aws:kms
x-amz-server- If x-amz-server-side-encryption is present, and if its No

side-encryption- value is aws:kms, this header specifies the encryption context
context for the object. The value of this header is a base64-encoded
UTF-8 string holding JSON with the encryption context key-
value pairs.
Type: String
Note
• Use customer-provided encryption keys – If you want to manage your own encryption keys, provide all
the following headers in the request.
side-encryption
algorithm
Default: None
Valid Value: AES256

side-encryption-customer-key-MD5 headers

side-encryption- key that Amazon S3 uses in encrypting data. This value stores
customer-key the object and then is discarded. Amazon does not store
the encryption key. The key must be appropriate for use
Type: String
Default: None

server-side-encryption-customer-key-MD5 headers

517
Responses

Type: String
Default: None

server-side-encryption-customer-key headers
Request Elements
Responses
Response Headers
Name Description
x-amz-abort- If the bucket has a lifecycle rule configured with an action to abort incomplete
date multipart uploads and the prefix in the lifecycle rule matches the object name
in the request, the response includes this header. The header indicates when the
initiated multipart upload becomes eligible for an abort operation. For more
information, see Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle
Policy in the Amazon Simple Storage Service Developer Guide.
The response also includes the x-amz-abort-rule-id header that provides the
ID of the lifecycle configuration rule that defines this action.
Type: String
x-amz-abort- This header is returned along with the x-amz-abort-date header. It identifies
rule-id the applicable lifecycle configuration rule that defines the action to abort
incomplete multipart uploads.
Type: String
x-amz- If you specified server-side encryption either with an AWS KMS key or an Amazon
server-side- S3-managed encryption key in your initiate multipart upload request, the
encryption response includes this header. It confirms the encryption algorithm that Amazon
S3 used to encrypt the part that you uploaded.

518
Responses
Name Description
Type: String
x-amz- If x-amz-server-side-encryption is present and has the value of aws:kms,

server-side- this header specifies the ID of the AWS KMS master encryption key that was used
encryption- for the object.
aws-kms-key-
id Type: String
x-amz- If server-side encryption with customer-provided encryption keys was requested,

server-side the response includes this header to confirm which encryption algorithm was
-encryption used.
-customer-
x-amz- If server-side encryption using a customer-provided encryption key was requested,

server-side the response returns this header to verify the integrity of the roundtrip message
-encryption- of the customer-provided encryption key.
customer-key-
MD5 Type: String
Response Elements
Name Description
InitiateMultipartUploadResult Container for the response.
Type: Container
Children: Bucket, Key, UploadId
Ancestors: None
Bucket Name of the bucket to which the multipart upload was

initiated.
Type: String
Ancestors: InitiateMultipartUploadResult
Key Object key for which the multipart upload was initiated.
Type: String
UploadId ID for the initiated multipart upload.
Type: String

519
Examples
Special Errors
Examples
Sample Request
This operation initiates a multipart upload for the example-object object.
POST /example-object?uploads HTTP/1.1

Date: Mon, 1 Nov 2010 20:34:56 GMT
Sample Response
HTTP/1.1 200 OK
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 197
Server: AmazonS3

<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Key>example-object</Key>
<UploadId>VXBsb2FkIElEIGZvciA2aWWpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</UploadId>
</InitiateMultipartUploadResult>
Sample: Initiate a Multipart Upload Using Server-side

Encryption with Customer-provided Encryption Keys
This example, which initiates a multipart upload request, specifies server-side encryption with customer-
provided encryption keys by adding relevant headers.
POST /example-object?uploads HTTP/1.1

Date: Wed, 28 May 2014 19:34:57 +0000
x-amz-server-side-encryption-customer-key: g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEEXAMPLE
In the response, Amazon S3 returns an UploadId. In addition, Amazon S3 returns the encryption
algorithm and the MD5 digest of the encryption key that you provided in the request.
HTTP/1.1 200 OK
x-amz-id-2: 36HRCaIGp57F1FvWvVRrvd3hNn9WoBGfEaCVHTCt8QWf00qxdHazQUgfoXAbhFWD
x-amz-request-id: 50FA1D691B62CA43
Date: Wed, 28 May 2014 19:34:58 GMT
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2m3tFg==

520
Related Actions

<InitiateMultipartUploadResult
xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<UploadId>EXAMPLEJZ6e0YupT2h66iePQCc9IEbYbDUy4RTpMeoSMLPRp8Z5o1u8feSRonpvnWsKKG35tI2LB9VDPiCgTy.Gq2VxQ
</UploadId>
</InitiateMultipartUploadResult>
Related Actions

521
List Parts
List Parts
Description
This operation lists the parts that have been uploaded for a specific multipart upload.
This operation must include the upload ID, which you obtain by sending the initiate multipart upload
request (see Initiate Multipart Upload (p. 512)). This request returns a maximum of 1,000 uploaded
parts. The default number of parts returned is 1,000 parts. You can restrict the number of parts
returned by specifying the max-parts request parameter. If your multipart upload consists of
more than 1,000 parts, the response returns an IsTruncated field with the value of true, and a
NextPartNumberMarker element. In subsequent List Parts requests you can include the part-
number-marker query string parameter and set its value to the NextPartNumberMarker field value
from the previous response.
For more information on multipart uploads, see Uploading Objects Using Multipart Upload in the
For information on permissions required to use the multipart upload API, see Multipart Upload API and
Requests
Syntax
GET /ObjectName?uploadId=UploadId HTTP/1.1
Date: Date
Request Parameters
in a bucket.

An object key can contain any Unicode character; however, XML 1.0
parser cannot parse some characters, such as characters with an ASCII
value from 0 to 10. For characters that are not supported in XML 1.0,
you can add this parameter to request that Amazon S3 encode the
keys in the response.
Type: String
Default: None
Valid value: url
uploadId Upload ID identifying the multipart upload whose parts are being Yes
listed.
Type: String

522
Responses

Default: None
max-parts Sets the maximum number of parts to return in the response body. No
Type: String
Default: 1,000
part-number- Specifies the part after which listing should begin. Only parts with No
marker higher part numbers will be listed.
Type: String
Default: None
Request Headers
Request Elements
Responses
Response Headers
Response Elements
Name Description
x-amz-abort-date If the bucket has a lifecycle rule configured with an action to abort
incomplete multipart uploads and the prefix in the lifecycle rule
matches the object name in the request, then the response includes
this header indicating when the initiated multipart upload will become
eligible for abort operation. For more information, see Aborting
Incomplete Multipart Uploads Using a Bucket Lifecycle Policy in the
The response will also include the x-amz-abort-rule-id header

that will provide the ID of the lifecycle configuration rule that defines
this action.
Type: String
x-amz-abort-rule-id This header is returned along with the x-amz-abort-date header. It

identifies applicable lifecycle configuration rule that defines the action
to abort incomplete multipart uploads.
Type: String

523
Responses
Name Description
ListPartsResult Container for the response.
Children: Bucket, Key, UploadId, Initiator, Owner,

StorageClass, PartNumberMarker, NextPartNumberMarker,
MaxParts, IsTruncated, Part
Type: Container
Bucket Name of the bucket to which the multipart upload was initiated.
Type: String
Ancestor: ListPartsResult
XML response.

the Key element.
Type: String
Key Object key for which the multipart upload was initiated.
Type: String
UploadId Upload ID identifying the multipart upload whose parts are being
listed.
Type: String
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, then
this element provides the user ARN and display name.
Type: Container
ID If the principal is an AWS account, it provides the Canonical User ID. If

the principal is an IAM User, it provides a user ARN value.
Type: String
Ancestor: Initiator

524
Responses
Name Description
DisplayName Principal's name.
Type: String
Ancestor: Initiator
Owner Container element that identifies the object owner, after the object is
created. If multipart upload is initiated by an IAM user, this element
provides the parent account ID and display name.
Type: Container
StorageClass Class of storage (STANDARD or REDUCED_REDUNDANCY) used to store

the uploaded object.
Type: String
PartNumberMarker Part number after which listing begins.
Type: Integer
NextPartNumberMarker When a list is truncated, this element specifies the last part in the list,
as well as the value to use for the part-number-marker request
parameter in a subsequent request.
Type: Integer
MaxParts Maximum number of parts that were allowed in the response.
Type: Integer
IsTruncated Indicates whether the returned list of parts is truncated. A true value
indicates that the list was truncated. A list can be truncated if the
number of parts exceeds the limit returned in the MaxParts element.
Type: Boolean
Part Container for elements related to a particular part. A response can

contain zero or more Part elements.
Children: PartNumber, LastModified, ETag, Size
Type: String

525
Examples
Name Description
PartNumber Part number identifying the part.
Type: Integer
Ancestor: Part
LastModified Date and time at which the part was uploaded.
Type: Date
Ancestor: Part
ETag Entity tag returned when the part was uploaded.
Type: String
Ancestor: Part
Size Size in bytes of the uploaded part data.
Type: Integer
Ancestor: Part
Examples
Sample Request
Assume you have uploaded parts with sequential part numbers starting with 1. The following List Parts
request specifies max-parts and part-number-marker query parameters. The request lists the first
two parts that follow part number 1, that is, you will get parts 2 and 3 in the response. If more parts
exist , the result is a truncated result and therefore the response will return an IsTruncated element
with the value true. The response will also return the NextPartNumberMarker element with the value
3, which should be used for the value of the part-number-marker request query string parameter in
the next List Parts request.
GET /example-object?
uploadId=XXBsb2FkIElEIGZvciBlbHZpbmcncyVcdS1tb3ZpZS5tMnRzEEEwbG9hZA&max-parts=2&part-
number-marker=1 HTTP/1.1
Date: Mon, 1 Nov 2010 20:34:56 GMT
Sample Response
HTTP/1.1 200 OK
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 985
Server: AmazonS3

526
Related Actions

<ListPartsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<UploadId>XXBsb2FkIElEIGZvciBlbHZpbmcncyVcdS1tb3ZpZS5tMnRzEEEwbG9hZA</UploadId>
<Initiator>
<ID>arn:aws:iam::111122223333:user/some-user-11116a31-17b5-4fb7-9df5-b288870f11xx</
ID>
<DisplayName>umat-user-11116a31-17b5-4fb7-9df5-b288870f11xx</DisplayName>
</Initiator>
<Owner>
<DisplayName>someName</DisplayName>
</Owner>
<PartNumberMarker>1</PartNumberMarker>
<NextPartNumberMarker>3</NextPartNumberMarker>
<MaxParts>2</MaxParts>
<Part>
<ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
<Size>10485760</Size>
</Part>
<Part>
<ETag>"aaaa18db4cc2f85cedef654fccc4a4x8"</ETag>
<Size>10485760</Size>
</Part>
</ListPartsResult>
Related Actions

527
Upload Part
Upload Part
Description
This operation uploads a part in a multipart upload.
Note
In this operation, you provide part data in your request. However, you have an option to specify
your existing Amazon S3 object as a data source for the part you are uploading. To upload a part
from an existing object, you use the Upload Part (Copy) operation. For more information, see
Upload Part - Copy (p. 534).
You must initiate a multipart upload (see Initiate Multipart Upload (p. 512)) before you can upload any
part. In response to your initiate request, Amazon S3 returns an upload ID, a unique identifier, that you
must include in your upload part request.
Part numbers can be any number from 1 to 10,000, inclusive. A part number uniquely identifies a part
and also defines its position within the object being created. If you upload a new part using the same
part number that was used with a previous part, the previously uploaded part is overwritten. Each part
must be at least 5 MB in size, except the last part. There is no size limit on the last part of your multipart
upload.
To ensure that data is not corrupted when traversing the network, specify the Content-MD5 header in
the upload part request. Amazon S3 checks the part data against the provided MD5 value. If they do not
match, Amazon S3 returns an error.
Note
After you initiate multipart upload and upload one or more parts, you must either complete or
abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only
after you either complete or abort the multipart upload, Amazon S3 frees up the parts storage
and stops charging you for it.
For more information on multipart uploads, go to Multipart Upload Overview in the Amazon Simple
Storage Service Developer Guide .
For information on the permissions required to use the multipart upload API, go to Multipart Upload API
and Permissions in the Amazon Simple Storage Service Developer Guide.
You can optionally request server-side encryption where Amazon S3 encrypts your data as it writes it to
disks in its data centers and decrypts it for you when you access it. You have the option of providing your
own encryption key, or you can use the AWS-managed encryption keys. If you choose to provide your
own encryption key, the request headers you provide in the request must match the headers you used in
the request to initiate the upload by using Initiate Multipart Upload (p. 512). For more information, go to
Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide.
Requests
Syntax
PUT /ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Date: date

528
Requests
Request Parameters
Request Headers
Content-Length The size of the part, in bytes. For more information, go to http:// Yes
Type: Integer
Default: None
Content-MD5 The base64-encoded 128-bit MD5 digest of the part data. This No
header can be used as a message integrity check to verify that the
part data is the same data that was originally sent. Although it is
optional, we recommend using the Content-MD5 mechanism as an
end-to-end integrity check. For more information, see RFC 1864.
Type: String
Default: None
Expect When your application uses 100-continue, it does not send the No
request body until it receives an acknowledgment. If the message
is rejected based on the headers, the body of the message is not
sent. For more information, go to RFC 2616.
Type: String
Default: None
Server-Side Encryption Specific Request Headers

Server-side encryption is supported by the S3 Multipart Upload actions. Unless you are using a
customer-provided encryption key, you don't need to specify the encryption parameters in each
UploadPart request. Instead, you only need to specify the server side encryption parameters in the initial
Initiate Multipart request. For more information, see Initiate Multipart Upload (p. 512).
If you requested server-side encryption using a customer-provided encryption key in your initiate
multipart upload request, you must provide identical encryption information in each part upload using
side-encryption

529
Responses

algorithm
Default: None
Valid Value: AES256


side-encryption- key for Amazon S3 to use in encrypting data. This value is used
customer-key to store the object and then is discarded; Amazon does not
store the encryption key. The key must be appropriate for use
Type: String
Default: None


customer-key-MD5 header for a message integrity check to ensure the encryption
key was transmitted without error.
Type: String
Default: None

Request Elements
Responses
Response Headers
Name Description
x-amz- If you specified server-side encryption either with an AWS KMS or Amazon S3-
server-side- managed encryption key in your initiate multipart upload request, the response
encryption includes this header. It confirms the encryption algorithm that Amazon S3 used to
encrypt the object.

530
Examples
Name Description
Type: String

server-side- aws:kms, this header specifies the ID of the AWS Key Management Service (KMS)
encryption- master encryption key that was used for the object.
aws-kms-key-
id Type: String
x-amz- If server-side encryption with customer-provided encryption keys(SSE-C)

server-side encryption was requested, the response will include this header confirming the
-encryption encryption algorithm used.
-customer-
x-amz- If SSE-C encryption was requested, the response includes this header to provide
server-side roundtrip message integrity verification of the customer-provided encryption key.
-encryption-
customer-key- Type: String
MD5
x-amz- Provides storage class information of the object. Amazon S3 returns this header
storage-class for all objects except for Standard storage class objects.
For more information, go to Storage Classes in Amazon Simple Storage Service

Developer Guide.
Type: String
Default: None
Response Elements
This operation does not use response elements.
Special Errors

Code Code Prefix
NoSuchUpload The specified multipart upload does not exist. 404 Not Client
The upload ID might be invalid, or the multipart Found
upload might have been aborted or completed.
Examples
Sample Request
The following PUT request uploads a part (part number 1) in a multipart upload. The request includes
the upload ID that you get in response to your Initiate Multipart Upload request.

531
Related Actions
PUT /my-movie.m2ts?
partNumber=1&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-MD5: pUNXr/BjKK5G2UKvaRRrOA==
***part data omitted***
Sample Response
The response includes the ETag header. You need to retain this value for use when you send the
Complete Multipart Upload request.
HTTP/1.1 200 OK
x-amz-id-2: Vvag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
Date: Mon, 1 Nov 2010 20:34:56 GMT
ETag: "b54357faf0632cce46e942fa68356b38"
Content-Length: 0
Server: AmazonS3
Sample: Upload a part with an encryption key in the request for

server-side encryption
If you initiated a multipart upload, see Sample: Initiate a Multipart Upload Using Server-side Encryption
with Customer-provided Encryption Keys (p. 520), with a request to save an object using server-side
encryption with a customer-provided encryption key, each part upload must also include the same set of
encryption-specific headers as shown in the following example request.
PUT /example-object?
partNumber=1&uploadId=EXAMPLEJZ6e0YupT2h66iePQCc9IEbYbDUy4RTpMeoSMLPRp8Z5o1u8feSRonpvnWsKKG35tI2LB9VDPi
HTTP/1.1
Date: Wed, 28 May 2014 19:40:11 +0000
x-amz-server-side-encryption-customer-key: g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEEXAMPLE
In the response, Amazon S3 returns encryption-specific headers providing the encryption algorithm used
and MD5 digest of the encryption key you provided in the request.
HTTP/1.1 100 Continue HTTP/1.1 200 OK

x-amz-id-2: Zn8bf8aEFQ+kBnGPBc/JaAf9SoWM68QDPS9+SyFwkIZOHUG2BiRLZi5oXw4cOCEt
x-amz-request-id: 5A37448A37622243
Date: Wed, 28 May 2014 19:40:12 GMT
ETag: "7e10e7d25dc4581d89b9285be5f384fd"
Related Actions

532
Related Actions


533
Upload Part - Copy
Upload Part - Copy

Description
Uploads a part by copying data from an existing object as data source. You specify the data source by
adding the request header x-amz-copy-source in your request and a byte range by adding the request
header x-amz-copy-source-range in your request.
The minimum allowable part size for a multipart upload is 5 MB. For more information about multipart
upload limits, go to Quick Facts in the Amazon Simple Storage Service Developer Guide.
Note
Instead of using an existing object as part data, you might use the Upload Part operation and
provide data in your request. For more information, see Upload Part (p. 528).
You must initiate a multipart upload before you can upload any part. In response to your initiate request.
Amazon S3 returns a unique identifier, the upload ID, that you must include in your upload part request.
For more information on using the upload part - copy operation, see the following topics:
• For conceptual information on multipart uploads, go to Uploading Objects Using Multipart Upload in
• For information on permissions required to use the multipart upload API, go to Multipart Upload API
and Permissions in the Amazon Simple Storage Service Developer Guide.
• For information about copying objects using a single atomic operation vs. the multipart upload, go to
Operations on Objects in the Amazon Simple Storage Service Developer Guide.
• For information about using server-side encryption with customer-provided encryption keys with the
upload part - copy operation, see PUT Object - Copy (p. 451) and Upload Part (p. 528).
Requests
Syntax
PUT /ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
x-amz-copy-source-range:bytes=first-last
Date: date
Request Parameters
Request Headers

534
Requests
x-amz-copy-source The name of the source bucket and the source object key Yes
name separated by a slash ('/').
Type: String
Default: None
x-amz-copy-source- The range of bytes to copy from the source object. The No
range range value must use the form bytes=first-last,
where the first and last are the zero-based byte offsets to
copy. For example, bytes=0-9 indicates that you want to
copy the first ten bytes of the source.
This request header is not required when copying an

entire source object.
Type: Integer
Default: None
The following conditional headers are based on the object that the x-amz-copy-source header
specifies.
x-amz-copy-source-if-match Perform a copy if the source object entity tag No

(ETag) matches the specified value. If the value
does not match, Amazon S3 returns an HTTP status
code 412 precondition failed error.
Type: String
Default: None
x-amz-copy-source-if-none- Perform a copy if the source object entity tag No

match (ETag) is different than the value specified using
this header. If the values match, Amazon S3 returns
an HTTP status code 412 precondition failed error.
Type: String
Default: None
x-amz-copy-source-if- Perform a copy if the source object is not modified No

unmodified-since after the time specified using this header. If the
source object is modified, Amazon S3 returns an
HTTP status code 412 precondition failed error.
Type: String

535
Requests

Default: None
x-amz-copy-source-if- Perform a copy if the source object is modified No

modified-since after the time specified using this header. If the
source object is not modified, Amazon S3 returns
an HTTP status code 412 precondition failed error.
Type: String
Default: None
• Consideration 1 – If both of the x-amz-copy-source-if-match and x-amz-copy-source-if-

unmodified-since headers are present in the request as follows:
x-amz-copy-source-if-match condition evaluates to true, and;
x-amz-copy-source-if-unmodified-since condition evaluates to false;
then, S3 returns 200 OK and copies the data.

• Consideration 2 – If both of the x-amz-copy-source-if-none-match and x-amz-copy-source-
if-modified-since headers are present in the request as follows:
x-amz-copy-source-if-none-match condition evaluates to false, and;
x-amz-copy-source-if-modified-since condition evaluates to true;
then, S3 returns 412 Precondition Failed response code.
Server-Side Encryption Specific Request Headers

If you requested server-side encryption using a customer-provided encryption key in your initiate
multipart upload request, you must provide identical encryption information in each part upload using
side-encryption
algorithm
Default: None
Valid Value: AES256
Constraints: Must be accompanied by a valid x-amz-server-


536
Requests
x-amz-server- Specifies the customer provided base64-encoded encryption key Yes

side-encryption- for Amazon S3 to use in encrypting data. This must be the same
customer-key encryption key specified in the initiate multipart upload request.
Type: String
Default: None


customer-key-MD5 header as a message integrity check to ensure the encryption
key was transmitted without error.
Type: String
Default: None

If the source object is encrypted using server-side encryption with a customer-provided encryption key,
you must use the following headers providing encryption information so that Amazon S3 can decrypt
the object for copying.
x-amz-copy- Specifies algorithm to use when decrypting the source object. Yes
source-server-
side-encryption Type: String
-customer-
algorithm Default: None
Valid Value: AES256
Constraints: Must be accompanied by a valid x-amz-copy-

source-server-side-encryption-customer-key and x-
amz-copy-source-server-side-encryption-customer-
key-MD5 headers.
x-amz-copy-source Specifies the customer provided base-64 encoded encryption Yes

-server-side key for Amazon S3 to use to decrypt the source object. The
-encryption- encryption key provided in this header must be one that was
customer-key used when the source object was created.
Type: String
Default: None

source-server-side-encryption-customer-algorithm

537
Versioning

customer-key-MD5 headers.
x-amz-copy- Specifies the base64-encoded 128-bit MD5 digest of the Yes

source-server- encryption key according to RFC 1321. Amazon S3 uses this
side-encryption- header for a message integrity check to ensure the encryption
customer-key-MD5 key was transmitted without error.
Type: String
Default: None

source-server-side-encryption-customer-algorithm
customer-key headers.
Request Elements
Versioning
If your bucket has versioning enabled, you could have multiple versions of the same object. By default,
x-amz-copy-source identifies the current version of the object to copy. If the current version is a
delete marker and you don't specify a versionId in the x-amz-copy-source, Amazon S3 returns a 404
error, because the object does not exist. If you specify versionId in the x-amz-copy-source and the
versionId is a delete marker, Amazon S3 returns an HTTP 400 error, because you are not allowed to
specify a delete marker as a version for the x-amz-copy-source.
You can optionally specify a specific version of the source object to copy by adding the versionId
subresource as shown in the following example:
x-amz-copy-source: /bucket/object?versionId=version id
Responses
Response Headers
This implementation of the operation can include the following headers in addition to the response
headers common to all responses. For more information, see Common Response Headers (p. 4).
Name Description
x-amz-copy-source- The version of the source object that was copied, if you have
version-id enabled versioning on the source bucket.
Type: String
x-amz-server-side- If you specified server-side encryption either with an AWS KMS

encryption or Amazon S3-managed encryption key in your initiate multipart

538
Responses
Name Description
upload request, the response includes this header. It confirms the
encryption algorithm that Amazon S3 used to encrypt the object.
Type: String
x-amz-server-side- If the x-amz-server-side-encryption is present and has the

encryption-aws-kms-key-id value of aws:kms, this header specifies the ID of the AWS Key
Management Service (KMS) master encryption key that was used
for the object.
Type: String
x-amz-server-side- If server-side encryption with customer-provided encryption keys

encryption-customer- encryption was requested, the response will include this header
algorithm confirming the encryption algorithm used.
Type: String
x-amz-server-side- If server-side encryption with customer-provided encryption keys

encryption-customer-key- encryption was requested, the response includes this header to
MD5 provide roundtrip message integrity verification of the customer-
provided encryption key.
Type: String
Response Elements
Name Description
CopyPartResult Container for all response elements.
Type: Container
Ancestor: None
ETag Returns the ETag of the new part.
Type: String
Ancestor: CopyPartResult
LastModified Returns the date the part was last modified.
Type: String
Ancestor: CopyPartResult
Important
Part boundaries are factored into ETag calculations, so if the part boundary on the source is
different than on the destination, then the ETag data will not match between the two. However,
data integrity checks are performed with each copy to ensure that the data written to the
destination matches the data at the source.

539
Examples
Special Errors
Error Code Description HTTP Status

Code
NoSuchUpload The specified multipart upload does not exist. The upload 404 Not Found
ID might be invalid, or the multipart upload might have
been aborted or completed.
InvalidRequest The specified copy source is not supported as a byte- 400 Bad Request
range copy source.
Examples
As the following examples illustrate, when a request succeeds, Amazon S3 returns <CopyPartResult>
in the body. If you included versionId in the request, Amazon S3 returns the version ID in the x-amz-
copy-source-version-id response header.
Sample Request
The following PUT request uploads a part (part number 2) in a multipart upload. The request specifies a
byte range from an existing object as the source of this upload. The request includes the upload ID that
you get in response to your Initiate Multipart Upload request.
PUT /newobject?
Host: target-bucket.s3.amazonaws.com
Date: Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject
x-amz-copy-source-range:bytes=500-6291456
Sample Response
The response includes the ETag value. You need to retain this value to use when you send the Complete
Multipart Upload request.
HTTP/1.1 200 OK
Date: Mon, 11 Apr 2011 20:34:56 GMT
Server: AmazonS3
<CopyPartResult>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyPartResult>
Sample Request
The following PUT request uploads a part (part number 2) in a multipart upload. The request does not
specify the optional byte range header, but requests the entire source object copy as part 2. The request
includes the upload ID that you got in response to your Initiate Multipart Upload request.

540
Related Actions
PUT /newobject?
Date: Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject
Sample Response
The response structure is similar to the one specified in the preceding example.
Sample Request
The following PUT request uploads a part (part number 2) in a multipart upload. The request specifies
a specific version of the source object to copy by adding the versionId subresource. The byte range
requests 6 MB of data, starting with byte 500, as the part to be uploaded.
PUT /newobject?
Date: Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject?versionId=3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
x-amz-copy-source-range:bytes=500-6291456
Sample Response
The response includes the ETag value. You need to retain this value to use when you send the Complete
Multipart Upload request.
HTTP/1.1 200 OK
Date: Mon, 11 Apr 2011 20:34:56 GMT
Server: AmazonS3
<CopyPartResult>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyPartResult>
Related Actions

541
Data Types

542
DefaultRetention
DefaultRetention
The container element for specifying the default Object Lock retention settings for new objects placed in
Contents
Mode
The default Object Lock retention mode you want to apply to new objects placed in the specified
bucket.
Type: String
Valid Values: GOVERNANCE | COMPLIANCE
Required: Yes
Days
The number of days that you want to specify for the default retention period.
Type: Integer
Required: No
Years
The number of years that you want to specify for the default retention period.
Type: Integer
Required: No
Note
Either Days or Years must be specified, but not both.

543
ObjectLockConfiguration
The container element for Object Lock configuration parameters.
Contents
ObjectLockEnabled
Indicates whether this bucket has an Object Lock configuration enabled.
Type: String
Valid Values: Enabled
Required: Yes
Rule
The Object Lock rule in place for the specified bucket.
Type: ObjectLockRule (p. 547) object
Required: No

544
ObjectLockLegalHold
ObjectLockLegalHold
A Legal Hold configuration for an object.
Contents
Status
Indicates whether the specified object has a Legal Hold in place.
Type: String
Valid Values: ON | OFF
Required: Yes

545
ObjectLockRetention
ObjectLockRetention
A Retention configuration for an object.
Contents
Mode
Indicates the Retention mode for the specified object.
Type: String
Required: Yes
RetainUntilDate
Type: Timestamp
Format: 2020-01-05T00:00:00.000Z
Required: Yes

546
ObjectLockRule
ObjectLockRule
The container element for an Object Lock rule.
Contents
DefaultRetention
The default retention period that you want to apply to new objects placed in the specified bucket.
Type: DefaultRetention (p. 543) object
Required: No

547
Amazon S3 Resources
Following is a table that lists related resources that you'll find useful as you work with this service.
Resource Description
Amazon Simple Storage Service The getting started guide provides a quick tutorial of the
Getting Started Guide service based on a simple use case.
Amazon Simple Storage Service The developer guide describes how to accomplish tasks using
Developer Guide Amazon S3 operations.
Amazon S3 Technical FAQ The FAQ covers the top 20 questions developers have asked
about this product.
Amazon S3 Release Notes The Release Notes give a high-level overview of the current
release. They specifically note any new features, corrections,
and known issues.
Tools for Amazon Web Services A central starting point to find documentation, code
samples, release notes, and other information to help you
build innovative applications with AWS SDKs and tools.
AWS Management Console The console allows you to perform most of the functions of
Amazon S3 without programming.
Discussion Forums A community-based forum for developers to discuss

technical questions related to Amazon Web Services.
AWS Support Center The home page for AWS Technical Support, including access
to our Developer Forums, Technical FAQs, Service Status
page, and Premium Support.
AWS Premium Support The primary web page for information about AWS Premium
Support, a one-on-one, fast-response support channel to
help you build and run applications on AWS Infrastructure
Services.
Amazon S3 product information The primary web page for information about Amazon S3.
Contact Us A central contact point for inquiries concerning AWS billing,

account, events, abuse, etc.
Conditions of Use Detailed information about the copyright and trademark

usage at Amazon.com and other topics.

548
Document History
The following table describes the important changes to the documentation since the last release of the
Amazon Simple Storage Service API Reference.
• API version: 2006-03-01

• Latest documentation update: March 27, 2019
Change Description Release

Date
New archive storage Amazon S3 now offers a new archive storage class, March 27,
class DEEP_ARCHIVE, for storing rarely accessed objects. For 2019
more information, see Storage Classes in the Amazon Simple
Support for Parquet- Amazon S3 now supports the Apache Parquet (Parquet) December
formatted Amazon S3 format in addition to the Apache optimized row columnar 04, 2018
inventory files (ORC) and comma-separated values (CSV) file formats for
inventory output files. For more information, see Amazon
S3 Inventory in the Amazon Simple Storage Service Developer
Guide.
The following APIs were updated accordingly:

PUT directly to the The Amazon S3 PUT and related operations now support November
GLACIER storage class specifying GLACIER as the storage class when creating 26, 2018
objects. Previously, you had to transition to the GLACIER
storage class from another Amazon S3 storage class. For more
information about the GLACIER storage class, see Storage
Classes in the Amazon Simple Storage Service Developer Guide.

Object Lock Amazon S3 now supports locking objects using a Write Once November
Read Many (WORM) model. You can lock objects for a definite 26, 2018
period of time using a retention period or indefinitely using
a legal hold. For more information about Amazon S3 Object
Lock, see Locking Objects in the Amazon Simple Storage
The following APIs were updated for S3 Object Lock:


549

Date
• HEAD Bucket (p. 229)
The following new APIs were added for S3 Object Lock:
• GET Bucket object lock configuration (p. 195)

• PUT Bucket object lock configuration (p. 323)
• GET Object retention (p. 388)
• PUT Object retention (p. 450)
• GET Object legal hold (p. 387)
• PUT Object legal hold (p. 449)
New storage class Amazon S3 now offers a new storage class named November
INTELLIGENT_TIERING that is for storing data that has 26, 2018
changing or unknown access patterns. For more information,
see Storage Classes in the Amazon Simple Storage Service
Developer Guide.

Block Public Access Amazon S3 now includes the ability to block public access to November
buckets and objects on a per-bucket or account-wide basis. 15, 2018
For more information, see Using Amazon S3 Block Public
Access in the Amazon Simple Storage Service Developer Guide.
The following new APIs have been added:

• PUT PublicAccessBlock (p. 302) (Bucket)
• GET PublicAccessBlock (p. 179) (Bucket)
• DELETE PublicAccessBlock (p. 115) (Bucket)
• PUT PublicAccessBlock (p. 72) (Account)
• GET PublicAccessBlock (p. 69) (Account)
• DELETE PublicAccessBlock (p. 68) (Account)

550

Date
Filtering enhancements In a CRR rule configuration, you can specify an object filter September
in cross-region to choose a subset of objects to apply the rule to. Previously, 19, 2018
replication (CRR) rules you could filter only on an object key prefix. In this release,
you can filter on an object key prefix, one or more object tags,
or both. For more information, see Replication Configuration
Overview in the Amazon Simple Storage Service Developer
Guide.
The following APIs are updated accordingly:

New storage class Amazon S3 now offers a new storage class, ONEZONE_IA April 4,
(IA, for infrequent access) for storing objects. For more 2018
information, see Storage Classes in the Amazon Simple
Amazon S3 Select Amazon S3 Select is now generally available. This feature April 4,
retrieves object content based on an SQL expression. For 2018
more information, see Selecting Content from Objects in the
The following API has been updated:
Asia Pacific (Osaka- Amazon S3 is now available in the Asia Pacific (Osaka-Local) February
Local) Region Region. For more information about Amazon S3 Regions and 12, 2018
Reference.
Important
You can use the Asia Pacific (Osaka-Local) Region
only in conjunction with the Asia Pacific (Tokyo)
Region. To request access to Asia Pacific (Osaka-
Local) Region, contact your sales representative.
EU (Paris) Region Amazon S3 is now available in the EU (Paris) Region. For more December
information about Amazon S3 regions and endpoints, see 18, 2017
Regions and Endpoints in the AWS General Reference.
China (Ningxia) Region Amazon S3 is now available in the China (Ningxia) Region. For December
more information about Amazon S3 regions and endpoints, 11, 2017
Querying archives with Amazon S3 now supports querying Glacier data archives with November
SQL SQL. For more information, see Querying Archived Objects in 29, 2017
The following API changed:

551

Date
SELECT Object Content Amazon S3 now supports the SELECT Object Content November
(Preview) functionality as part of a Preview program. This feature 29, 2017
retrieves object content based on an SQL expression.
The following API has been added:
Support for ORC- Amazon S3 now supports the Apache optimized row November
formatted Amazon S3 columnar (ORC) format in addition to comma-separated 17, 2017
inventory files values (CSV) file format for inventory output files. For more
information, see Amazon S3 Inventory in the Amazon Simple

Default encryption for Amazon S3 default encryption provides a way to set the November
S3 buckets default encryption behavior for an S3 bucket. You can 06, 2017
set default encryption on a bucket so that all objects are
encrypted when they are stored in the bucket. The objects are
encrypted using server-side encryption with either Amazon
S3-managed keys (SSE-S3) or AWS KMS-managed keys
(SSE-KMS). For more information, see Amazon S3 Default
Encryption for S3 Buckets in the Amazon Simple Storage

Encryption status in Amazon S3 now supports including encryption status in November

Amazon S3 inventory Amazon S3 inventory so you can see how your objects are 06, 2017
encrypted at rest for compliance auditing or other purposes.
You can also configure to encrypt Amazon S3 inventory with
server-side encryption (SSE) or SSE-KMS so that all inventory
files are encrypted accordingly. For more information, see
Amazon S3 Inventory in the Amazon Simple Storage Service
Developer Guide.


552

Date
Cross-region replication Cross-region replication (CRR) now supports the following: November
(CRR) enhancements 06, 2017
• In a cross-account scenario, you can add a CRR
configuration to change replica ownership to the AWS
account that owns the destination bucket. For more
information, see CRR: Change Replica Owner in the Amazon
• By default, Amazon S3 does not replicate objects in your
source bucket that are created using server-side encryption
using AWS KMS-managed keys. In your CRR configuration,
you can now direct Amazon S3 to replicate these objects.
For more information, see CRR: Replicating Objects Created
with SEE Using AWS KMS-Managed Encryption Keys in the

EU (London) Region Amazon S3 is now available in the EU (London) Region. For December
more information about Amazon S3 regions and endpoints, 13, 2016
Canada (Central) Region Amazon S3 is now available in the Canada (Central) Region. December
For more information about Amazon S3 regions and 8, 2016
Reference.
Object tagging support Amazon S3 now supports object tagging. The following new November
API operations support object tagging: 29, 2016

• DELETE Object tagging (p. 368)
In addition, other API operations are updated to support

object tagging. For more information, see Object Tagging in
S3 lifecycle now Amazon S3 now supports tag-based filtering in lifecycle November

supports object tag configuration. You can now specify a lifecycle rule, in which 29, 2016
based filter you can specify a key prefix, one or more object tags, or a
combination of both, to select a subset of objects to which
the lifecycle rule applies. For more information, see Object
Lifecycle Managementin the Amazon Simple Storage Service
Developer Guide.
Amazon S3 now supports Expedited and Bulk data retrievals

in addition to Standard retrievals when restoring objects
archived to Glacier.

553

Date
CloudWatch request Amazon S3 now supports CloudWatch metrics for requests November
metrics for buckets made on buckets. The following new API operations support 29, 2016
configuring request metrics:

For more information, see Monitoring Metrics with Amazon

CloudWatch in the Amazon Simple Storage Service Developer
Guide.
Amazon S3 Inventory Amazon S3 now supports storage inventory. Amazon S3 November

inventory provides a flat-file output of your objects and their 29, 2016
corresponding metadata on a daily or weekly basis for an S3
bucket or a shared prefix (that is, objects that have names
that begin with a common string).
The following new API operations are for storage inventory:

For more information, see Amazon S3 Storage Inventory in


554

Date
Amazon S3 Analytics – The new Amazon S3 analytics – storage class analysis feature November
Storage Class Analysis observes data access patterns to help you determine when 29, 2016
to transition less frequently accessed STANDARD storage to
the STANDARD_IA (IA, for infrequent access) storage class.
After storage class analysis observes the infrequent access
patterns of a filtered set of data over a period of time, you
can use the analysis results to help you improve your lifecycle
policies. This feature also includes a detailed daily analysis of
your storage usage at the specified bucket, prefix, or tag level
that you can export to a S3 bucket.
The following new API operations are for storage class

analysis:

For more information, see Amazon S3 Analytics – Storage

Class Analysis in the Amazon Simple Storage Service Developer
Guide.
Added Glacier retrieval Amazon S3 now supports Expedited and Bulk data retrievals November
options to POST Object in addition to Standard retrievals when restoring objects 21, 2016
restore (p. 419) archived to Glacier. For more information, see Restoring
Archived Objects in the Amazon Simple Storage Service
Developer Guide.
US East (Ohio) Region Amazon S3 is now available in the US East (Ohio) Region. For October 17,
more information about Amazon S3 regions and endpoints, 2016
Asia Pacific (Mumbai) Amazon S3 is now available in the Asia Pacific (Mumbai) June 27,
region region. For more information about Amazon S3 regions and 2016
Reference.
GET Bucket (List The GET Bucket (List Objects) API has been revised. We May 4,
Objects) API revised recommend that you use the new version, GET Bucket (List 2016
Objects) version 2. For more information, see GET Bucket (List
Objects) Version 2 (p. 127).

555

Date
Amazon S3 Transfer Amazon S3 Transfer Acceleration enables fast, easy, and April 19,
Acceleration secure transfers of files over long distances between 2016
your client and an S3 bucket. Transfer Acceleration takes
advantage of Amazon CloudFront’s globally distributed edge
locations.
For more information, see Transfer Acceleration in the

The following new API operations support Transfer

Acceleration: GET Bucket accelerate (p. 146) and PUT Bucket
accelerate (p. 257).
Lifecycle support to Lifecycle configuration expiration action now allows you to March 16,
remove expired object direct Amazon S3 to remove expired object delete markers 2016
delete marker in versioned bucket. For more information, see Elements
to Describe Lifecycle Actions in the Amazon Simple Storage
Bucket lifecycle Bucket lifecycle configuration now supports the March 16,
configuration now AbortIncompleteMultipartUpload action that you can 2016
supports the action use to direct Amazon S3 to abort multipart uploads that
to abort incomplete don't complete within a specified number of days after being
multipart uploads initiated. When a multipart upload becomes eligible for an
abort operation, Amazon S3 deletes any uploaded parts and
aborts the multipart upload.
The following API operations have been updated to support

the new action:
• PUT Bucket lifecycle (p. 290) – The XML

configuration now allows you to specify the
AbortIncompleteMultipartUpload action in a lifecycle
configuration rule.
• List Parts (p. 522) and Initiate Multipart Upload (p. 512)
– Both of these API operations now return two additional
response headers (x-amz-abort-date, and x-amz-
abort-rule-id) if the bucket has a lifecycle rule that
specifies the AbortIncompleteMultipartUpload
action. These headers in the response indicate when the
initiated multipart upload will become eligible for an abort
operation and which lifecycle rule is applicable.
For conceptual information, see the following topics in the

Amazon Simple Storage Service Developer Guide:
• Aborting Incomplete Multipart Uploads Using a Bucket

Lifecycle Policy
• Elements to Describe Lifecycle Actions

556

Date
Amazon S3 Signature Amazon S3 Signature Version 4 now supports unsigned January 15,
Version 4 now supports payloads when authenticating requests using the 2016
unsigned payloads Authorization header. Because you don't sign the payload,
it does not provide the same security that comes with payload
signing, but it provides similar performance characteristics
as signature version 2. For more information, see Signature
Calculations for the Authorization Header: Transferring
Payload in a Single Chunk (AWS Signature Version 4) (p. 18).
Asia Pacific (Seoul) Amazon S3 is now available in the Asia Pacific (Seoul) January 6,
region region. For more information about Amazon S3 regions and 2016
Reference.
Renamed the US Changed the region name string from US Standard to US East December
Standard region (N. Virginia). This is only a region name update, there is no 11, 2015
change in the functionality.
New storage class Amazon S3 now offers a new storage class, STANDARD_IA (IA, September
for infrequent access) for storing objects. This storage class 16, 2015
is optimized for long-lived and less frequently accessed data.
For more information, see Storage Classes in the Amazon
Lifecycle configuration feature updates now allow you to

transition objects to the STANDARD_IA storage class. For
more information, see Object Lifecycle Management in the
Previously, the cross-region replication feature used the

storage class of the source object for object replicas. Now,
when you configure cross-region replication you can specify a
storage class for the object replica created in the destination
bucket. For more information, see Cross-Region Replication in
Event notifications Amazon S3 event notifications have been updated to add July 28,
notifications when objects are deleted and to add filtering on 2015
object names with prefix and suffix matching. For the relevant
API operations, see PUT Bucket notification (p. 315), and
GET Bucket notification (p. 190). For more information, see
Configuring Amazon S3 Event Notifications in the Amazon
Cross-region replication Amazon S3 now supports cross-region replication. Cross- March 24,
region replication is the automatic, asynchronous copying 2015
of objects across buckets in different AWS regions. For the
relevant API operations, see PUT Bucket replication (p. 327),
GET Bucket replication (p. 212) and DELETE Bucket
replication (p. 121). For more information, see Enabling Cross-
Region Replication in the Amazon Simple Storage Service
Developer Guide.

557

Date
Event notifications Amazon S3 now supports new event types and November
destinations in a bucket notification configuration. 13, 2014
Prior to this release, Amazon S3 supported only the
s3:ReducedRedundancyLostObject event type and an
Amazon SNS topic as the destination. For more information
about the new event types, go to Setting Up Notification of
Bucket Events in the Amazon Simple Storage Service Developer
Guide. For the relevant API operations, see PUT Bucket
notification (p. 315) and GET Bucket notification (p. 190).
Server-side encryption Amazon S3 now supports server-side encryption using AWS November
with AWS Key Key Management Service (KMS). With server-side encryption 12, 2014
Management Service with KMS, you manage the envelope key through KMS, and
(KMS) Amazon S3 calls KMS to access the envelope key within the
permissions you set.
For more information about server-side encryption with

KMS, see Protecting Data Using Server-Side Encryption with
AWS Key Management Service in the Amazon Simple Storage
The following Amazon S3 REST API operations support

headers related to KMS.

EU (Frankfurt) region Amazon S3 is now available in the EU (Frankfurt) region. October 23,
2014

558

Date
Server-side encryption Amazon S3 now supports server-side encryption using June 12,
with customer-provided customer-provided encryption keys (SSE-C). Server-side 2014
encryption keys encryption enables you to request Amazon S3 to encrypt your
data at rest. When using SSE-C, Amazon S3 encrypts your
objects with the custom encryption keys that you provide.
Since Amazon S3 performs the encryption for you, you get
the benefits of using your own encryption keys without the
cost of writing or executing your own encryption code.
For more information about SSE-C, go to Server-Side

Encryption (Using Customer-Provided Encryption Keys) in the
The following Amazon S3 REST API operations support

headers related to SSE-C.

• Upload Part - Copy (p. 534)
Lifecycle support for Prior to this release lifecycle configuration was supported May 20,
versioning only on nonversioned buckets. Now you can configure 2014
lifecycle on both the nonversioned and versioning-enabled
buckets.
For more information, go to Object Lifecycle Management in

The related API operations, see PUT Bucket lifecycle (p. 290),
GET Bucket lifecycle (p. 171), and DELETE Bucket
lifecycle (p. 114).
Amazon S3 now Amazon S3 now supports Signature Version 4 (SigV4) in January 30,
supports Signature all regions, the latest specification for how to sign and 2014
Version 4 authenticate AWS requests.
For more information, see Authenticating Requests (AWS


559

Date
Amazon S3 list The following Amazon S3 list actions now support November
actions now support encoding-type optional request parameter. 1, 2013
encoding-type
request parameter GET Bucket (List Objects) Version 1 (p. 137)
GET Bucket Object versions (p. 198)
List Multipart Uploads (p. 243)
List Parts (p. 522)
An object key can contain any Unicode character; however,

the XML 1.0 parser cannot parse some characters, such as
characters with an ASCII value from 0 to 10. For characters
that are not supported in XML 1.0, you can add this
parameter to request that Amazon S3 encode the keys in the
response.
SOAP Support Over SOAP support over HTTP is deprecated, but it is still available September
HTTP Deprecated over HTTPS. New Amazon S3 features will not be supported 19, 2013
for SOAP. We recommend that you use either the REST API or
the AWS SDKs.
Root domain support Amazon S3 now supports hosting static websites at the root December
for website hosting domain. Visitors to your website can access your site from 27, 2012
their browser without specifying "www" in the web address
(e.g., "example.com"). Many customers already host static
websites on Amazon S3 that are accessible from a "www"
subdomain (e.g., "www.example.com"). Previously, to support
root domain access, you needed to run your own web server
to proxy root domain requests from browsers to your website
on Amazon S3. Running a web server to proxy requests
introduces additional costs, operational burden, and another
potential point of failure. Now, you can take advantage of the
high availability and durability of Amazon S3 for both "www"
and root domain addresses.
For an example walkthrough, go to Example: Setting Up a

Static Website Using a Custom Domain in the Amazon Simple
Storage Service Developer Guide. For conceptual information,
go to Hosting Static Websites on Amazon S3 in the Amazon

560

Date
Support for Archiving Amazon S3 now supports a storage option that enables November
Data to Amazon Glacier you to utilize Amazon Glacier's low-cost storage service 13, 2012
for data archival. To archive objects, you define archival
rules identifying objects and a timeline when you want
Amazon S3 to archive these objects to Glacier. You can easily
set the rules on a bucket using the Amazon S3 console or
programmatically using the Amazon S3 API or AWS SDKs.
To support data archival rules, Amazon S3 lifecycle

management API has been updated. For more information,
see PUT Bucket lifecycle (p. 290).
After you archive objects, you must first restore a copy before
you can access the data. Amazon S3 offers a new API for you
to initiate a restore. For more information, see POST Object
restore (p. 419).
For conceptual information, go to Object Lifecycle

Management in the Amazon Simple Storage Service Developer
Guide.
Support for Website For a bucket that is configured as a website, Amazon S3 now October 4,
Page Redirects supports redirecting a request for an object to another object 2012
in the same bucket or to an external URL. You can configure
redirect by adding the x-amz-website-redirect-
location metadata to the object.
The object upload API operations PUT Object (p. 434), Initiate
Multipart Upload (p. 512), and POST Object (p. 407) allow
you to configure the x-amz-website-redirect-location
object metadata.
For conceptual information, go to How to Configure Website

Page Redirects in the Amazon Simple Storage Service
Developer Guide.
Cross-Origin Resource Amazon S3 now supports Cross-Origin Resource Sharing August 31,
Sharing (CORS) support (CORS). CORS defines a way in which client web applications 2012
that are loaded in one domain can interact with or access
resources in a different domain. With CORS support in
Amazon S3, you can build rich client-side web applications
on top of Amazon S3 and selectively allow cross-domain
access to your Amazon S3 resources. For more information,
see Enabling Cross-Origin Resource Sharing in the Amazon
Cost Allocation Tagging Amazon S3 now supports cost allocation tagging, which August 21,
support allows you to label S3 buckets so you can more easily 2012
track their cost against projects or other criteria. For more
information, see Cost Allocation Tagging in the Amazon

561

Date
Object Expiration You can use Object Expiration to schedule automatic December
support removal of data after a configured time period. You set 27, 2011
object expiration by adding lifecycle configuration to a
bucket. For more information, see Transitioning Objects:
General Considerations in the Amazon Simple Storage Service
Developer Guide.
New Region supported Amazon S3 now supports the South America (São Paulo) December
region. For more information, see Buckets and Regions in the 14, 2011
Multi-Object Delete Amazon S3 now supports Multi-Object Delete API that December
enables you to delete multiple objects in a single request. 7, 2011
With this feature, you can remove large numbers of objects
from Amazon S3 more quickly than using multiple individual
DELETE requests.
For more information about the API see, see Delete Multiple
Objects (p. 354).
For conceptual information about the delete operation,

see Deleting Objects in the Amazon Simple Storage Service
Developer Guide.
New region supported Amazon S3 now supports the US West (Oregon) region. For November
more information, see Buckets and Regions in the Amazon 8, 2011
Server-side encryption Amazon S3 now supports server-side encryption. It enables October 17,
support you to request Amazon S3 to encrypt your data at rest, that 2011
is, encrypt your object data when Amazon S3 writes your data
to disks in its data centers. To request server-side encryption,
you must add the x-amz-server-side-encryption
header to your request. To learn more about data encryption,
go to Using Data Encryption in the Amazon Simple Storage
Multipart Upload API Prior to this release, Amazon S3 API supported copying June 21,
extended to enable objects (see PUT Object - Copy (p. 451)) of up to 5 GB in 2011
copying objects up to 5 size. To enable copying objects larger than 5 GB, Amazon
TB S3 extends the multipart upload API with a new operation,
Upload Part (Copy). You can use this multipart upload
operation to copy objects up to 5 TB in size. For conceptual
information about multipart upload, go to Uploading Objects
Using Multipart Upload in the Amazon Simple Storage Service
Developer Guide. To learn more about the new API, see Upload
Part - Copy (p. 534).
SOAP API calls over To increase security, SOAP API calls over HTTP are disabled. June 6,
HTTP disabled Authenticated and anonymous SOAP requests must be sent to 2011
Amazon S3 using SSL.

562

Date
Support for hosting Amazon S3 introduces enhanced support for hosting static February
static websites in websites. This includes support for index documents and 17, 2011
Amazon S3 custom error documents. When using these features, requests
to the root of your bucket or a subfolder (e.g., http://
mywebsite.com/subfolder) returns your index document
instead of the list of objects in your bucket. If an error is
encountered, Amazon S3 returns your custom error message
instead of an Amazon S3 error message. For API information
to configure your bucket as a website, see the following
sections:

For conceptual overview, go to Hosting Websites on Amazon

S3 in the Amazon Simple Storage Service Developer Guide.
Response Header API The GET Object REST API now allows you to change the January 14,
Support response headers of the REST GET Object request for 2011
each request. That is, you can alter object metadata in
the response, without altering the object itself. For more
information, see GET Object (p. 370).
Large Object Support Amazon S3 has increased the maximum size of an object December
you can store in an S3 bucket from 5 GB to 5 TB. If you are 9, 2010
using the REST API you can upload objects of up to 5 GB
size in a single PUT operation. For larger objects, you must
use the Multipart Upload REST API to upload objects in
parts. For conceptual information, go to Uploading Objects
Developer Guide. For multipart upload API information, see
Initiate Multipart Upload (p. 512), Upload Part (p. 528),
Complete Multipart Upload (p. 506), List Parts (p. 522), and
Multipart upload Multipart upload enables faster, more flexible uploads into November
Amazon S3. It allows you to upload a single object as a set of 10, 2010
parts. For conceptual information, go to Uploading Objects
Developer Guide. For multipart upload API information, see
Initiate Multipart Upload (p. 512), Upload Part (p. 528),
Complete Multipart Upload (p. 506), List Parts (p. 522), and
Notifications The Amazon S3 notifications feature enables you to configure July 14,
a bucket so that Amazon S3 publishes a message to an 2010
Amazon Simple Notification Service (SNS) topic when
Amazon S3 detects a key event on a bucket. For more
information, see GET Bucket notification (p. 190) and PUT
Bucket notification (p. 190).

563

Date
Bucket policies Bucket policies is an access management system you use to July 6, 2010
set access permissions on buckets, objects, and sets of objects.
This functionality supplements and in many cases replaces
access control lists.
Reduced Redundancy Amazon S3 now enables you to reduce your storage costs by May 12,
storing objects in Amazon S3 with reduced redundancy. For 2010
more information, see PUT Object (p. 434).
New region supported Amazon S3 now supports the Asia Pacific (Singapore) region April 28,
and therefore new location constraints. For more information, 2010
see GET Bucket location (p. 178) and PUT Bucket (p. 252).
Object Versioning This release introduces object Versioning. All objects now February 8,
have a key and a version. If you enable versioning for a 2010
bucket, Amazon S3 gives all objects added to a bucket
a unique version ID. This feature enables you to recover
from unintended overwrites and deletions. For more
information, see GET Object (p. 370), DELETE Object (p. 364),
PUT Object (p. 434), PUT Object Copy (p. 451), or POST
Object (p. 407). The SOAP API does not support versioned
objects.
New region supported Amazon S3 now supports the US-West (Northern December
California) region. The new endpoint is s3-us- 2, 2009
west-1.amazonaws.com. For more information, see How
to Select a Region for Your Buckets in the Amazon Simple
C# Library Support AWS now provides Amazon S3 C# libraries, sample code, November
tutorials, and other resources for software developers who 11, 2009
prefer to build applications using language-specific API
operations instead of REST or SOAP. These libraries provide
basic functions (not included in the REST or SOAP APIs), such
as request authentication, request retries, and error handling
so that it's easier to get started.
Technical documents The API reference has been split out of the Amazon S3 September
reorganized Developer Guide. Now, on the documentation landing page, 16, 2009
Amazon Simple Storage Service Documentation, you can
select the document you want to view. When viewing the
documents online, the links in one document will take you,
when appropriate, to one of the other guides.

564
Appendix: SOAP API
Appendix
Topics
• Appendix: SOAP API (p. 565)
• Appendix: Lifecycle Configuration APIs (Deprecated) (p. 592)
Appendix: SOAP API

Note
AWS SDKs.
This section describes the SOAP API with respect to service, bucket, and object operations. Note that
SOAP requests, both authenticated and anonymous, must be sent to Amazon S3 using SSL. Amazon S3
returns an error when you send a SOAP request over HTTP.
The latest Amazon S3 WSDL is available at http://doc.s3.amazonaws.com/2006-03-01/AmazonS3.wsdl.
Topics
• Operations on the Service (SOAP API) (p. 565)
• Operations on Buckets (SOAP API) (p. 566)
• Operations on Objects (SOAP API) (p. 575)
• SOAP Error Responses (p. 590)
Operations on the Service (SOAP API)

Note
AWS SDKs.
This section describes operations you can perform on the Amazon S3 service.
Topics
• ListAllMyBuckets (SOAP API) (p. 565)
ListAllMyBuckets (SOAP API)

Note
AWS SDKs.
The ListAllMyBuckets operation returns a list of all buckets owned by the sender of the request.
Example
Sample Request

565
Operations on Buckets (SOAP API)
<ListAllMyBuckets xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</ListAllMyBuckets>
Sample Response
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Owner>
</Owner>
<Buckets>
<Bucket>
<Name>quotes;/Name>
</Bucket>
<Bucket>
<Name>samples</Name>
</Bucket>
</Buckets>
</ListAllMyBucketsResult>
Response Body
• Owner:
This provides information that Amazon S3 uses to represent your identity for purposes of
authentication and access control. ID is a unique and permanent identifier for the developer who
made the request. DisplayName is a human-readable name representing the developer who made
the request. It is not unique, and might change over time.We recommend that you match your
DisplayName to your Forum name.
• Name:
The name of a bucket. Note that if one of your buckets was recently deleted, the name of the deleted
bucket might still be present in this list for a period of time.
• CreationDate:
The time that the bucket was created.
Access Control
You must authenticate with a valid AWS Access Key ID. Anonymous requests are never allowed to list
buckets, and you can only list buckets for which you are the owner.

Note
AWS SDKs.
This section describes operations you can perform on Amazon S3 buckets.
Topics

566
• CreateBucket (SOAP API) (p. 567)

• DeleteBucket (SOAP API) (p. 568)
• ListBucket (SOAP API) (p. 568)
• GetBucketAccessControlPolicy (SOAP API) (p. 571)
• SetBucketAccessControlPolicy (SOAP API) (p. 572)
• GetBucketLoggingStatus (SOAP API) (p. 573)
• SetBucketLoggingStatus (SOAP API) (p. 574)
CreateBucket (SOAP API)

Note
AWS SDKs.
The CreateBucket operation creates a bucket. Not every string is an acceptable bucket name. For
information on bucket naming restrictions, see Working with Amazon S3 Buckets .
Note
To determine whether a bucket name exists, use ListBucket and set MaxKeys to 0. A
NoSuchBucket response indicates that the bucket is available, an AccessDenied response
indicates that someone else owns the bucket, and a Success response indicates that you own the
bucket or have permission to access it.
Example Create a bucket named "quotes"
Sample Request
<CreateBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
</CreateBucket>
Sample Response
<CreateBucketResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<CreateBucketResponse>
</CreateBucketResponse>
</CreateBucketResponse>
Elements
• Bucket: The name of the bucket you are trying to create.
• AccessControlList: The access control list for the new bucket. This element is optional. If not
provided, the bucket is created with an access policy that give the requester FULL_CONTROL access.
Access Control
You must authenticate with a valid AWS Access Key ID. Anonymous requests are never allowed to create
buckets.

567
Related Resources
• ListBucket (SOAP API) (p. 568)
DeleteBucket (SOAP API)

Note
AWS SDKs.
The DeleteBucket operation deletes a bucket. All objects in the bucket must be deleted before the
bucket itself can be deleted.
Example
This example deletes the "quotes" bucket.
Sample Request
<DeleteBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<AWSAccessKeyId> AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
</DeleteBucket>
Sample Response
<DeleteBucketResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<DeleteBucketResponse>
<Code>204</Code>
<Description>No Content</Description>
</DeleteBucketResponse>
</DeleteBucketResponse>
Elements
• Bucket: The name of the bucket you want to delete.
Access Control
Only the owner of a bucket is allowed to delete it, regardless the access control policy on the bucket.
ListBucket (SOAP API)

Note
AWS SDKs.
The ListBucket operation returns information about some of the items in the bucket.
For a general introduction to the list operation, see the Listing Object Keys.
Requests
This example lists up to 1000 keys in the "quotes" bucket that have the prefix "notes."

568
Syntax
<ListBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Prefix>notes/</Prefix>
</ListBucket>
Parameters
prefix Limits the response to keys which begin with the indicated prefix. No
You can use prefixes to separate a bucket into different sets of keys
in a way similar to how a file system uses folders.
Type: String
Default: None
marker Indicates where in the bucket to begin listing. The list will only No
include keys that occur lexicographically after marker. This is
convenient for pagination: To get the next page of results use the
last key of the current page as the marker.
Type: String
Default: None
max-keys The maximum number of keys you'd like to see in the response No
body. The server might return fewer than this many keys, but will
not return more.
Type: String
Default: None
delimiter Causes keys that contain the same string between the prefix and No
the first occurrence of the delimiter to be rolled up into a single
result element in the CommonPrefixes collection. These rolled-up
keys are not returned elsewhere in the response.
Type: String
Default: None
Success Response
This response assumes the bucket contains the following keys:
notes/todos.txt
notes/2005-05-23/customer_mtg_notes.txt

569
notes/2005-05-23/phone_notes.txt
notes/2005-05-28/sales_notes.txt
Syntax

<Name>backups</Name>
<Prefix>notes/</Prefix>
<Contents>
<Key>notes/todos.txt</Key>
<Size>5126</Size>
<Owner>
</Owner>
</Contents>
<CommonPrefixes>
<Prefix>notes/2005-05-23/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>notes/2005-05-28/</Prefix>
</CommonPrefixes>
</ListBucketResult>
As you can see, many of the fields in the response echo the request parameters. IsTruncated,
Contents, and CommonPrefixes are the only response elements that can contain new information.
Response Elements
Name Description
Type: XML metadata
CommonPrefixes A response can contain CommonPrefixes only if you specify a delimiter.

When you do, CommonPrefixes contains all (if there are any) keys between
Prefix and the next occurrence of the string specified by delimiter. In effect,
CommonPrefixes lists keys that act like subdirectories in the directory specified
by Prefix. For example, if prefix is notes/ and delimiter is a slash (/), in
notes/summer/july, the common prefix is notes/summer/.
Type: String
Delimiter Causes keys that contain the same string between the prefix and the first
occurrence of the delimiter to be rolled up into a single result element in the
CommonPrefixes collection. These rolled-up keys are not returned elsewhere in
the response.

570
Name Description
Type: String
IsTruncated Specifies whether (true) or not (false) all of the results were returned. All of the
results may not be returned if the number of results exceeds that specified by
MaxKeys.
Type: String
Ancestor: boolean
Marker Indicates where in the bucket to begin listing.
Type: String
Type: String
Type: String
Type: String
Response Body
For information about the list response, see Listing Keys Response.
Access Control
To list the keys of a bucket you need to have been granted READ access on the bucket.
GetBucketAccessControlPolicy (SOAP API)

Note
AWS SDKs.
The GetBucketAccessControlPolicy operation fetches the access control policy for a bucket.
Example
This example retrieves the access control policy for the "quotes" bucket.
Sample Request

571
<GetBucketAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">
</GetBucketAccessControlPolicy>
Sample Response
<Owner>
<ID>a9a7b886d6fd2441bf9b1c61be666e9</ID>
<DisplayName>chriscustomer</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xsi:type="CanonicalUser">
<ID>a9a7b886d6f41bf9b1c61be666e9</ID>
</Grantee>
</Grant>
<Grant>
<Grantee xsi:type="Group">
<URI>http://acs.amazonaws.com/groups/global/AllUsers<URI>
</Grantee>
</Grant>
Response Body
The response contains the access control policy for the bucket. For an explanation of this response, see
SOAP Access Policy .
Access Control
You must have READ_ACP rights to the bucket in order to retrieve the access control policy for a bucket.
SetBucketAccessControlPolicy (SOAP API)

Note
AWS SDKs.
The SetBucketAccessControlPolicy operation sets the Access Control Policy for an existing bucket.
If successful, the previous Access Control Policy for the bucket is entirely replaced with the specified
Access Control Policy.
Example
Give the specified user (usually the owner) FULL_CONTROL access to the "quotes" bucket.
Sample Request
<SetBucketAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">

572
<AccessControlList>
<Grant>
<ID>a9a7b8863000e241bf9b1c61be666e9</ID>
</Grantee>
</Grant>
</SetBucketAccessControlPolicy >
Sample Response
<GetBucketAccessControlPolicyResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<GetBucketAccessControlPolicyResponse>
<Code>200</Code>
<Description>OK</Description>
</GetBucketAccessControlPolicyResponse>
</GetBucketAccessControlPolicyResponse>
Access Control
You must have WRITE_ACP rights to the bucket in order to set the access control policy for a bucket.
GetBucketLoggingStatus (SOAP API)

Note
AWS SDKs.
The GetBucketLoggingStatus retrieves the logging status for an existing bucket.
For a general introduction to this feature, see Server Logs.
Example
Sample Request
<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/
XMLSchema">
<soap:Body>
<GetBucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>mybucket</Bucket>
<AWSAccessKeyId>YOUR_AWS_ACCESS_KEY_ID</AWSAccessKeyId>
<Signature>YOUR_SIGNATURE_HERE</Signature>
</GetBucketLoggingStatus>
</soap:Body>
</soap:Envelope>
Sample Response

573
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" >
<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<GetBucketLoggingStatusResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<GetBucketLoggingStatusResponse>
<LoggingEnabled>
<TargetBucket>mylogs</TargetBucket>
<TargetPrefix>mybucket-access_log-</TargetPrefix>
</LoggingEnabled>
</GetBucketLoggingStatusResponse>
</GetBucketLoggingStatusResponse>
</soapenv:Body>
</soapenv:Envelope>
Access Control
Only the owner of a bucket is permitted to invoke this operation.
SetBucketLoggingStatus (SOAP API)

Note
AWS SDKs.
The SetBucketLoggingStatus operation updates the logging status for an existing bucket.
For a general introduction to this feature, see Server Logs.
Example
This sample request enables server access logging for the 'mybucket' bucket, and configures the logs to
be delivered to 'mylogs' under prefix 'access_log-'
Sample Request

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/
XMLSchema">
<soap:Body>
<SetBucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>myBucket</Bucket>
<AWSAccessKeyId>YOUR_AWS_ACCESS_KEY_ID</AWSAccessKeyId>
<Signature>YOUR_SIGNATURE_HERE</Signature>
<BucketLoggingStatus>
<LoggingEnabled>
<TargetBucket>mylogs</TargetBucket>
<TargetPrefix>mybucket-access_log-</TargetPrefix>
</LoggingEnabled>
</SetBucketLoggingStatus>
</soap:Body>
:</soap:Envelope>
Sample Response

574
Operations on Objects (SOAP API)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" >
<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<SetBucketLoggingStatusResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01"/>
</soapenv:Body>
</soapenv:Envelope>
Access Control
Only the owner of a bucket is permitted to invoke this operation.

Note
AWS SDKs.
This section describes operations you can perform on Amazon S3 objects.
Topics
• PutObjectInline (SOAP API) (p. 575)
• PutObject (SOAP API) (p. 577)
• CopyObject (SOAP API) (p. 579)
• GetObject (SOAP API) (p. 583)
• GetObjectExtended (SOAP API) (p. 587)
• DeleteObject (SOAP API) (p. 588)
• GetObjectAccessControlPolicy (SOAP API) (p. 589)
• SetObjectAccessControlPolicy (SOAP API) (p. 590)
PutObjectInline (SOAP API)

Note
AWS SDKs.
The PutObjectInline operation adds an object to a bucket. The data for the object is provided in the
body of the SOAP message.
If an object already exists in a bucket, the new object will overwrite it because Amazon S3 stores the last
write request. However, Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests
for the same object nearly simultaneously, all of the objects might be stored, even though only one wins
in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your
application layer.
To ensure an object is not corrupted over the network, you can calculate the MD5 of an object, PUT it to
Amazon S3, and compare the returned Etag to the calculated MD5 value.

575
PutObjectInline is not suitable for use with large objects. The system limits this operation to working
with objects 1MB or smaller. PutObjectInline will fail with the InlineDataTooLargeError status code
if the Data parameter encodes an object larger than 1MB. To upload large objects, consider using the
non-inline PutObject API, or the REST API instead.
Example
This example writes some text and metadata into the "Nelson" object in the "quotes" bucket, give a user
(usually the owner) FULL_CONTROL access to the object, and make the object readable by anonymous
parties.
Sample Request
<PutObjectInline xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Key>Nelson</Key>
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>Muntz</Value>
</Metadata>
<Data>aGEtaGE=</Data>
<ContentLength>5</ContentLength>
<AccessControlList>
<Grant>
<ID>a9a7b886d6fde241bf9b1c61be666e9</ID>
</Grantee>
</Grant>
<Grant>
<URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
</Grantee>
</Grant>
</PutObjectInline>
Sample Response
<PutObjectInlineResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<PutObjectInlineResponse>
<ETag>&quot828ef3fdfa96f00ad9f27c383fc9ac7f&quot</ETag>
<LastModified>2006-01-01T12:00:00.000Z</lastModified>
</PutObjectInlineResponse>
</PutObjectInlineResponse>
Elements
• Bucket: The bucket in which to add the object.
• Key: The key to assign to the object.
• Metadata: You can provide name-value metadata pairs in the metadata element. These will be stored
with the object.

576
• Data: The base 64 encoded form of the data.

• ContentLength: The length of the data in bytes.
• AccessControlList: An Access Control List for the resource. This element is optional. If omitted,
the requester is given FULL_CONTROL access to the object. If the object already exists, the preexisting
access control policy is replaced.
Responses
• ETag: The entity tag is an MD5 hash of the object that you can use to do conditional fetches of the
object using GetObjectExtended. The ETag only reflects changes to the contents of an object, not
its metadata.
• LastModified: The Amazon S3 timestamp for the saved object.
Access Control
You must have WRITE access to the bucket in order to put objects into the bucket.
Related Resources
PutObject (SOAP API)

Note
AWS SDKs.
The PutObject operation adds an object to a bucket. The data for the object is attached as a DIME
attachment.
To ensure an object is not corrupted over the network, you can calculate the MD5 of an object, PUT it to
Amazon S3, and compare the returned Etag to the calculated MD5 value.
If an object already exists in a bucket, the new object will overwrite it because Amazon S3 stores the last
write request. However, Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests
for the same object nearly simultaneously, all of the objects might be stored, even though only one wins
in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your
application layer.
Example
This example puts some data and metadata in the "Nelson" object of the "quotes" bucket, give a user
(usually the owner) FULL_CONTROL access to the object, and make the object readable by anonymous
parties. In this sample, the actual attachment is not shown.
Sample Request
<PutObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Key>Nelson</Key>
<Metadata>

577
</Metadata>
<Metadata>
<Name>family</Name>
</Metadata>
<ContentLength>5</ContentLength>
<AccessControlList>
<Grant>
<ID>a9a7b886d6241bf9b1c61be666e9</ID>
</Grantee>
</Grant>
<Grant>
</Grantee>
</Grant>
</PutObject>
Sample Response
<PutObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<PutObjectResponse>
</PutObjectResponse>
</PutObjectResponse>
Elements
• Bucket: The bucket in which to add the object.
• Key: The key to assign to the object.
• Metadata: You can provide name-value metadata pairs in the metadata element. These will be stored
with the object.
• ContentLength: The length of the data in bytes.
• AccessControlList: An Access Control List for the resource. This element is optional. If omitted,
the requester is given FULL_CONTROL access to the object. If the object already exists, the preexisting
Access Control Policy is replaced.
Responses
• ETag: The entity tag is an MD5 hash of the object that you can use to do conditional fetches of the
object using GetObjectExtended. The ETag only reflects changes to the contents of an object, not
its metadata.
• LastModified: The Amazon S3 timestamp for the saved object.
Access Control
To put objects into a bucket, you must have WRITE access to the bucket.

578
Related Resources
CopyObject (SOAP API)

Note
AWS SDKs.
Description
The CopyObject operation creates a copy of an object when you specify the key and bucket of a source
object and the key and bucket of a target destination.
When copying an object, you can preserve all metadata (default) or specify new metadata. However, the
ACL is not preserved and is set to private for the user making the request. To override the default ACL
setting, specify a new ACL when generating a copy request. For more information, see Using ACLs.
All copy requests must be authenticated. Additionally, you must have read access to the source object
and write access to the destination bucket. For more information, see Using Auth Access.
To only copy an object under certain conditions, such as whether the Etag matches or
whether the object was modified before or after a specified date, use the request parameters
CopySourceIfUnmodifiedSince, CopyIfUnmodifiedSince, CopySourceIfMatch, or
CopySourceIfNoneMatch.
Note
You might need to configure the SOAP stack socket timeout for copying large objects.
Request Syntax
<CopyObject xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
<SourceBucket>source_bucket</SourceBucket>
<SourceObject>source_object</SourceObject>
<DestinationBucket>destination_bucket</DestinationBucket>
<DestinationObject>destination_object</DestinationObject>
<MetadataDirective>{REPLACE | COPY}</MetadataDirective>
<Metadata>
<Name>metadata_name</Name>
<Value>metadata_value</Value>
</Metadata>
...
<AccessControlList>
<Grant>
<Grantee xsi:type="user_type">
<ID>user_id</ID>
<DisplayName>display_name</DisplayName>
</Grantee>
<Permission>permission</Permission>
</Grant>
...
<CopySourceIfMatch>etag</CopySourceIfMatch>
<CopySourceIfNoneMatch>etag</CopySourceIfNoneMatch>
<CopySourceIfModifiedSince>date_time</CopySourceIfModifiedSince>
<CopySourceIfUnmodifiedSince>date_time</CopySourceIfUnmodifiedSince>
<AWSAccessKeyId>AWSAccessKeyId</AWSAccessKeyId>
<Timestamp>TimeStamp</Timestamp>
<Signature>Signature</Signature>

579
</CopyObject>
Request Parameters
SourceBucket The name of the source bucket. Yes
Type: String
Default: None
Constraints: A valid source bucket.
SourceKey The key name of the source object. Yes
Type: String
Default: None
Constraints: The key for a valid source object

to which you have READ access.
DestinationBucket The name of the destination bucket. Yes
Type: String
Default: None
Constraints: You must have WRITE access to

the destination bucket.
DestinationKey The key of the destination object. Yes
Type: String
Default: None
Constraints: You must have WRITE access to

the destination bucket.
MetadataDirective Specifies whether the metadata is copied No

from the source object or replaced with
metadata provided in the request.
Type: String
Default: COPY
Constraints: Values other than COPY or

REPLACE will result in an immediate error.
You cannot copy an object to itself unless
the MetadataDirective header is specified
and its value set to REPLACE.
Metadata Specifies metadata name-value pairs to set No

for the object.If MetadataDirective is set to
COPY, all metadata is ignored.

580

Type: String
Default: None
Constraints: None.
AccessControlList Grants access to users by e-mail addresses or No

canonical user ID.
Type: String
Default: None
Constraints: None
CopySourceIfMatch Copies the object if its entity tag (ETag) No

matches the specified tag; otherwise return a
PreconditionFailed.
Type: String
Default: None
Constraints: None. If the Etag does not

match, the object is not copied.
CopySourceIfNoneMatch Copies the object if its entity tag (ETag) is No

different than the specified Etag; otherwise
returns an error.
Type: String
Default: None
Constraints: None.
CopySourceIfUnmodifiedSince Copies the object if it hasn't been modified No

since the specified time; otherwise returns a
PreconditionFailed.
Type: dateTime
Default: None
CopySourceIfModifiedSince Copies the object if it has been modified No

since the specified time; otherwise returns an
error.
Type: dateTime
Default: None
Response Syntax
<CopyObjectResponse xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
<CopyObjectResponse>
<ETag>"etag"</ETag>
<LastModified>timestamp</LastModified>

581
</CopyObjectResponse>
Response Elements
Following is a list of response elements.
Note
The SOAP API does not return extra whitespace. Extra whitespace is only returned by the REST
API.
Name Description
Etag Returns the etag of the new object. The ETag only
reflects changes to the contents of an object, not its
metadata.
Type: String
LastModified Returns the date the object was last modified.
Type: String
For information about general response elements, see Using REST Error Response Headers.
Special Errors
There are no special errors for this operation. For information about general Amazon S3 errors, see List
of Error Codes (p. 7).
Examples
This example copies the flotsam object from the pacific bucket to the jetsam object of the
atlantic bucket, preserving its metadata.
Sample Request
<CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<SourceBucket>pacific</SourceBucket>
<SourceObject>flotsam</SourceObject>
<DestinationBucket>atlantic</DestinationBucket>
<DestinationObject>jetsam</DestinationObject>
<Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
</CopyObject>
Sample Response
<CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01">

582
This example copies the "tweedledee" object from the wonderland bucket to the "tweedledum" object of
the wonderland bucket, replacing its metadata.
Sample Request
<CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<SourceBucket>wonderland</SourceBucket>
<SourceObject>tweedledee</SourceObject>
<DestinationBucket>wonderland</DestinationBucket>
<DestinationObject>tweedledum</DestinationObject>
<MetadataDirective >REPLACE</MetadataDirective >
<Metadata>
</Metadata>
<Metadata>
<Name>relationship</Name>
<Value>twins</Value>
</Metadata>
<Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
</CopyObject>
Sample Response
<CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01">
Related Resources
• PutObjectInline (SOAP API) (p. 575)
GetObject (SOAP API)

Note
AWS SDKs.
The GetObject operation returns the current version of an object. If you try to GetObject an object
that has a delete marker as its current version, S3 returns a 404 error. You cannot use the SOAP API
to retrieve a specified version of an object. To do that, use the REST API. For more information, see
Versioning. For more options, use the GetObjectExtended (SOAP API) (p. 587) operation.
Example
This example gets the "Nelson" object from the "quotes" bucket.
Sample Request
<GetObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">

583
<Key>Nelson</Key>
<GetMetadata>true</GetMetadata>
<GetData>true</GetData>
<InlineData>true</InlineData>
</GetObject>
Sample Response
<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<GetObjectResponse>
<Status>
<Code>200</Code>
</Status>
<Metadata>
</Metadata>
<Metadata>
<Name>family</Name>
</Metadata>
</GetObjectResponse>
Elements
• Bucket: The bucket from which to retrieve the object.
• Key: The key that identifies the object.
• GetMetadata: The metadata is returned with the object if this is true.
• GetData: The object data is returned if this is true.
• InlineData: If this is true, then the data is returned, base 64-encoded, as part of the SOAP body of
the response. If false, then the data is returned as a SOAP attachment. The InlineData option is not
suitable for use with large objects. The system limits this operation to working with 1MB of data or
less. A GetObject request with the InlineData flag set will fail with the InlineDataTooLargeError
status code if the resulting Data parameter would have encoded more than 1MB. To download large
objects, consider calling GetObject without setting the InlineData flag, or use the REST API instead.
Returned Elements
• Metadata: The name-value paired metadata stored with the object.
• Data: If InlineData was true in the request, this contains the base 64 encoded object data.
• LastModified: The time that the object was stored in Amazon S3.
• ETag: The object's entity tag. This is a hash of the object that can be used to do conditional gets. The
ETag only reflects changes to the contents of an object, not its metadata.
Access Control
You can read an object only if you have been granted READ access to the object.

584
SOAP Chunked and Resumable Downloads

To provide GET flexibility, Amazon S3 supports chunked and resumable downloads.
Select from the following:
• For large object downloads, you might want to break them into smaller chunks. For more information,
see Range GETs (p. 585)
• For GET operations that fail, you can design your application to download the remainder instead of the
entire file. For more information, see REST GET Error Recovery (p. 587)
Range GETs
For some clients, you might want to break large downloads into smaller downloads. To break a GET into
smaller units, use Range.
Before you can break a GET into smaller units, you must determine its size. For example, the following
request gets the size of the bigfile object.
<ListBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>bigbucket</Bucket>
<Prefix>bigfile</Prefix>
</ListBucket>
Amazon S3 returns the following response.
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Name>quotes</Name>
<Prefix>N</Prefix>
<Contents>
<Key>bigfile</Key>
<Size>2023276</Size>
<Owner>
<DisplayName>bigfile</DisplayName>
</Owner>
</Contents>
</ListBucketResult>
Following is a request that downloads the first megabyte from the bigfile object.
<Key>bigfile</Key>
<ByteRangeStart>0</ByteRangeStart>
<ByteRangeEnd>1048576</ByteRangeEnd>

585
</GetObject>
Amazon S3 returns the first megabyte of the file and the Etag of the file.
<GetObjectResponse>
<Status>
<Code>200</Code>
</Status>
<Metadata>
</Metadata>
<Metadata>
<Name>family</Name>
</Metadata>
<Data>--first megabyte of bigfile--</Data>
To ensure the file did not change since the previous portion was downloaded, specify the IfMatch
element. Although the IfMatch element is not required, it is recommended for content that is likely to
change.
The following is a request that gets the remainder of the file, using the IfMatch request header.
<Key>bigfile</Key>
<ByteRangeStart>10485761</ByteRangeStart>
<ByteRangeEnd>2023276</ByteRangeEnd>
<IfMatch>"828ef3fdfa96f00ad9f27c383fc9ac7f"</IfMatch>
</GetObject>
Amazon S3 returns the following response and the remainder of the file.
<GetObjectResponse>
<Status>
<Code>200</Code>
</Status>
<Metadata>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>>Muntz</Value>
</Metadata>
<Data>--remainder of bigfile--</Data>

586
Versioned GetObject
The following request returns the specified version of the object in the bucket.
<Key>Nelson</Key>
</GetObject>
Sample Response
<GetObjectResponse>
<Status>
<Code>200</Code>
</Status>
<Metadata>
</Metadata>
<Metadata>
<Name>family</Name>
</Metadata>
REST GET Error Recovery

If an object GET fails, you can get the rest of the file by specifying the range to download. To do so, you
must get the size of the object using ListBucket and perform a range GET on the remainder of the file.
For more information, see GetObjectExtended (SOAP API) (p. 587).
Related Resources
Operations on Objects (SOAP API) (p. 575)
GetObjectExtended (SOAP API)

Note
AWS SDKs.
GetObjectExtended is exactly like GetObject (SOAP API) (p. 583), except that it supports the
following additional elements that can be used to accomplish much of the same functionality provided
by HTTP GET headers (go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).

587
GetObjectExtended supports the following elements in addition to those supported by GetObject:
• ByteRangeStart, ByteRangeEnd: These elements specify that only a portion of the object data
should be retrieved. They follow the behavior of the HTTP byte ranges (go to http://www.w3.org/
Protocols/rfc2616/rfc2616-sec14.html#sec14.35).
• IfModifiedSince: Return the object only if the object's timestamp is later than the specified
timestamp. (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25)
• IfUnmodifiedSince: Return the object only if the object's timestamp is earlier than or equal to the
specified timestamp. (go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.28)
• IfMatch: Return the object only if its ETag matches the supplied tag(s). (go to http://www.w3.org/
Protocols/rfc2616/rfc2616-sec14.html#sec14.24)
• IfNoneMatch: Return the object only if its ETag does not match the supplied tag(s). (go to http://
www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26)
• ReturnCompleteObjectOnConditionFailure:ReturnCompleteObjectOnConditionFailure: If
true, then if the request includes a range element and one or both of IfUnmodifiedSince/IfMatch
elements, and the condition fails, return the entire object rather than a fault. This enables the If-Range
functionality (go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.27).
DeleteObject (SOAP API)

Note
AWS SDKs.
The DeleteObject operation removes the specified object from Amazon S3. Once deleted, there is no
method to restore or undelete an object.
Note
If you delete an object that does not exist, Amazon S3 will return a success (not an error
message).
Example
This example deletes the "Nelson" object from the "quotes" bucket.
Sample Request
<DeleteObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Key>Nelson</Key>
<AWSAccessKeyId> AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
</DeleteObject>
Sample Response
<DeleteObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<DeleteObjectResponse>
<Code>200</Code>
</DeleteObjectResponse>
</DeleteObjectResponse>
Elements
• Bucket: The bucket that holds the object.

588
• Key: The key that identifies the object.
Access Control
You can delete an object only if you have WRITE access to the bucket, regardless of who owns the object
or what rights are granted to it.
GetObjectAccessControlPolicy (SOAP API)

Note
AWS SDKs.
The GetObjectAccessControlPolicy operation fetches the access control policy for an object.
Example
This example retrieves the access control policy for the "Nelson" object from the "quotes" bucket.
Sample Request
<GetObjectAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Key>Nelson</Key>
</GetObjectAccessControlPolicy>
Sample Response
<Owner>
<ID>a9a7b886d6fd24a541bf9b1c61be666e9</ID>
</Owner>
<AccessControlList>
<Grant>
<ID>a9a7b841bf9b1c61be666e9</ID>
</Grantee>
</Grant>
<Grant>
</Grantee>
</Grant>
Response Body
The response contains the access control policy for the bucket. For an explanation of this response, SOAP
Access Policy .

589
SOAP Error Responses
Access Control
You must have READ_ACP rights to the object in order to retrieve the access control policy for an object.
SetObjectAccessControlPolicy (SOAP API)

Note
AWS SDKs.
The SetObjectAccessControlPolicy operation sets the access control policy for an existing object.
If successful, the previous access control policy for the object is entirely replaced with the specified
access control policy.
Example
This example gives the specified user (usually the owner) FULL_CONTROL access to the "Nelson" object
from the "quotes" bucket.
Sample Request
<SetObjectAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Key>Nelson</Key>
<AccessControlList>
<Grant>
<ID>a9a7b886d6fd24a52fe8ca5bef65f89a64e0193f23000e241bf9b1c61be666e9</ID>
</Grantee>
</Grant>
</SetObjectAccessControlPolicy>
Sample Response
<SetObjectAccessControlPolicyResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<SetObjectAccessControlPolicyResponse>
<Code>200</Code>
</SetObjectAccessControlPolicyResponse>
</SetObjectAccessControlPolicyResponse>
Access Control
You must have WRITE_ACP rights to the object in order to set the access control policy for a bucket.

Note
AWS SDKs.
In SOAP, an error result is returned to the client as a SOAP fault, with the HTTP response code 500. If
you do not receive a SOAP fault, then your request was successful. The Amazon S3 SOAP fault code is

590
comprised of a standard SOAP 1.1 fault code (either "Server" or "Client") concatenated with the Amazon
S3-specific error code. For example: "Server.InternalError" or "Client.NoSuchBucket". The SOAP fault
string element contains a generic, human readable error message in English. Finally, the SOAP fault
detail element contains miscellaneous information relevant to the error.
For example, if you attempt to delete the object "Fred", which does not exist, the body of the SOAP
response contains a "NoSuchKey" SOAP fault.
The following example shows a sample SOAP error response.
<soapenv:Body>
<soapenv:Fault>
<Faultcode>soapenv:Client.NoSuchKey</Faultcode>
<Faultstring>The specified key does not exist.</Faultstring>
<Detail>
<Key>Fred</Key>
</Detail>
</soapenv:Fault>
</soapenv:Body>
The following table explains the SOAP error response elements
Name Description
Detail Container for the key involved in the error
Type: Container
Ancestor: Body.Fault
Fault Container for error information.
Type: Container
Ancestor: Body
Faultcode The fault code is a string that uniquely identifies an error condition. It is meant to be
read and understood by programs that detect and handle errors by type. For more
information, see List of Error Codes (p. 7).
Type: String
Faultstring The fault string contains a generic description of the error condition in English. It is
intended for a human audience. Simple programs display the message directly to
the end user if they encounter an error condition they don't know how or don't care
to handle. Sophisticated programs with more exhaustive error handling and proper
internationalization are more likely to ignore the fault string.
Type: String
Key Identifies the key involved in the error
Type: String

591
Appendix: Lifecycle Configuration APIs (Deprecated)
Appendix: Lifecycle Configuration APIs

(Deprecated)
Bucket lifecycle configuration is updated to support filters based on object tags. That is, you can now
specify a rule that specifies key name prefix, one or more object tags, or both to select a subset of
objects to which the rule applies. The APIs have been updated accordingly. The following topics describes
the prior version of the PUT and GET bucket lifecycle operations for backward compatibility.
Topics
• PUT Bucket lifecycle (Deprecated) (p. 593)
• GET Bucket lifecycle (Deprecated) (p. 603)

592
PUT Bucket lifecycle (Deprecated)

Description
Important
For an updated version of this API, see PUT Bucket lifecycle (p. 290). This version has been
deprecated. Existing lifecycle configurations will work. For new lifecycle configurations, use the
updated API.
Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration. For
information about lifecycle configuration, see Object Lifecycle Management in the Amazon Simple
Permissions
By default, all Amazon S3 resources, including buckets, objects, and related subresources (for
example, lifecycle configuration and website configuration) are private. Only the resource owner,
the AWS account that created the resource, can access it. The resource owner can optionally grant
access permissions to others by writing an access policy. For this operation, users must get the
s3:PutLifecycleConfiguration permission.
You can also explicitly deny permissions. Explicit denial also supersedes any other permissions. If you
want to prevent users or accounts from removing or deleting objects from your bucket, you must deny
them permissions for the following actions:
• s3:DeleteObject
• s3:DeleteObjectVersion
• s3:PutLifecycleConfiguration
For more information about permissions, see Managing Access Permissions to Your Amazon S3 Resources
Requests
Syntax
Date: date
Content-MD5: MD5
Lifecycle configuration in the request body
For details about authorization strings, see Authenticating Requests (AWS Signature Version 4) (p. 14).
Request Parameters
Request Headers

data. You must use this header as a message

593

RFC 1864.
Type: String
Default: None
Request Body
In the request, you specify the lifecycle configuration in the request body. The lifecycle configuration
is specified as XML. The following is an example of a basic lifecycle configuration. It specifies one rule.
The Prefix in the rule identifies objects to which the rule applies. The rule also specifies two actions
(Transitionand Expiration). Each action specifies a timeline when Amazon S3 should perform the
action. The Status indicates whether the rule is enabled or disabled.
<Rule>
<ID>sample-rule</ID>
<Transition>
<Date>value</Date>
<StorageClass>storage class</StorageClass>
</Transition>
<Expiration>
<Days>value</Days>
</Expiration>
</Rule>
If the state of your bucket is versioning-enabled or versioning-suspended, you can have many
versions of the same object: one current version and zero or more noncurrent versions. The
following lifecycle configuration specifies the actions (NoncurrentVersionTransition,
NoncurrentVersionExpiration) that are specific to noncurrent object versions.
<Rule>
<NoncurrentDays>value</NoncurrentDays>
<StorageClass>storage class</StorageClass>
<NoncurrentDays>value</NoncurrentDays>
</Rule>
You can use the multipart upload API to upload large objects in parts. For more information about
multipart uploads, see Multipart Upload Overview in the Amazon Simple Storage Service Developer Guide.
With lifecycle configuration, you can tell Amazon S3 to abort incomplete multipart uploads, which are
identified by the key name prefix specified in the rule, if they don't complete within a specified number
of days. When Amazon S3 aborts a multipart upload, it deletes all parts associated with the upload. This
ensures that you don't have incomplete multipart uploads that have left parts stored in Amazon S3, so

594
you don't have to pay storage costs for them. The following is an example lifecycle configuration that
specifies a rule with the AbortIncompleteMultipartUpload action. This action tells Amazon S3 to
abort incomplete multipart uploads seven days after initiation.
<Rule>
<Prefix>SomeKeyPrefix/</Prefix>
<AbortIncompleteMultipartUpload>
<DaysAfterInitiation>7</DaysAfterInitiation>
</AbortIncompleteMultipartUpload>
</Rule>
The following table describes the XML elements in the lifecycle configuration.

for the rule
Type: Container
Ancestor: Rule

Storage Service Developer Guide. are absent
The date value must conform to ISO 8601

Type: String

when the specific rule action takes effect. Date and
ExpiredObjectDeleteMa
Type: Nonnegative Integer when used with are absent
Expiration
Ancestor: Expiration, Transition
DaysAfterInitiation Specifies the number of days after initiating a Yes, if a

multipart upload when the multipart upload parent tag is
must be completed. If it does not complete by specified

595
Expiration This action specifies a period in an object's Yes, if no

lifetime when Amazon S3 should take the other action
appropriate expiration action. The action Amazon is present in
S3 takes depends on whether the bucket is the Rule.
versioning-enabled.

object permanently.
• If the bucket is versioning-enabled (or
versioning is suspended), the action applies
only to the current version of the object. A
versioning-enabled bucket can have many
versions of the same object: one current version
and zero or more noncurrent versions.

Important
If a bucket's state is versioning-
null, Amazon S3 overwrites that
version.
Note
To set the expiration for
noncurrent objects, use the
action.
Type: Container
Ancestor: Rule

Type: String
Ancestor: Rule
as 1000 rules.
Type: Container
Children: Rule
Ancestor: None

596
ExpiredObjectDeleteMarker On a versioned bucket (a versioning-enabled Yes, if Date

or versioning-suspended bucket), you can add and Days
this element in the lifecycle configuration are absent
to tell Amazon S3 to delete expired object
delete markers. For an example, see Example
8: Removing Expired Object Delete Markers in
the Amazon Simple Storage Service Developer
Guide. Don't add it to a non-versioned bucket,
because that type of bucket cannot include delete
markers.
Type: String

allowed, but it is no-op, which means that
Amazon S3 will not take action)
NoncurrentDays Specifies the number of days an object is Yes

noncurrent before Amazon S3 can perform
the associated action. For information about
the noncurrent days calculations, see How
Amazon S3 Calculates When an Object Became
Noncurrent in the Amazon Simple Storage Service
Developer Guide.


the Rule
Set this lifecycle configuration action on a bucket
that has versioning enabled (or suspended) to tell
Amazon S3 to delete noncurrent object versions
at a specific period in the object's lifetime.
Type: Container
Ancestor: Rule

597
NoncurrentVersionTransition Container for the transition rule that describes Yes, if no

when noncurrent objects transition to the other action
STANDARD_IA, ONEZONE_IA, or GLACIER storage is present in
class. the Rule
If your bucket is versioning-enabled (or if

versioning is suspended), you can set this action
to tell Amazon S3 to transition noncurrent
object versions at a specific period in the object's
lifetime.
Type: Container
Ancestor: Rule
Prefix Object key prefix that identifies one or more Yes

objects to which the rule applies.
Type: String
Ancestor: Rule
Rule Container for a lifecycle rule. A lifecycle Yes

configuration can contain as many as 1000 rules.
Type: Container
Ancestor:LifecycleConfiguration
Status If enabled, Amazon S3 executes the rule as Yes

scheduled. If it is disabled, Amazon S3 ignores the
rule.
Type: String
Ancestor: Rule
Valid values: Enabled, Disabled

you want the object to transition.
This element
Type: String is required
only if you
Ancestor: Transition and specify one
NoncurrentVersionTransition or both its
ancestors.
Valid values: STANDARD_IA | ONEZONE_IA |
GLACIER

598

lifetime when Amazon S3 should transition them other action
to the STANDARD_IA, ONEZONE_IA, or GLACIER is present in
storage class. When this action is in effect, what the Rule
Amazon S3 does depends on whether the bucket
is versioning-enabled.

• If your bucket is versioning-enabled (or
versioning is suspended), Amazon S3
transitions only the current versions of objects
identified in the rule.
Note
A versioning-enabled bucket can
have many versions of an object. This
action has no effect on noncurrent
action.
Type: Container
Ancestor: Rule
Responses
Response Headers
Response Elements
Special Errors
Examples
Example 1: Add Lifecycle Configuration to a Bucket That Is Not Versioning-
enabled
The following lifecycle configuration specifies two rules, each with one action.

599
• The Transition action tells Amazon S3 to transition objects with the "documents/" prefix to the
GLACIER storage class 30 days after creation.
• The Expiration action tells Amazon S3 to delete objects with the "logs/" prefix 365 days after creation.
<Rule>
<ID>id1</ID>
<Transition>
<Days>30</Days>
</Transition>
</Rule>
<Rule>
<ID>id2</ID>
<Expiration>
<Days>365</Days>
</Expiration>
</Rule>

Content-Length: 415
<Rule>
<ID>id1</ID>
<Transition>
<Days>30</Days>
</Transition>
</Rule>
<Rule>
<ID>id2</ID>
<Expiration>
<Days>365</Days>
</Expiration>
</Rule>
HTTP/1.1 200 OK
Date: Wed, 14 May 2014 02:11:22 GMT

600
Content-Length: 0
Server: AmazonS3
Example 2: Add Lifecycle Configuration to a Versioning-enabled Bucket

The following lifecycle configuration specifies two rules, each with one action for Amazon S3 to perform.
You specify these actions when your bucket is versioning-enabled or versioning is suspended:
• The NoncurrentVersionExpiration action tells Amazon S3 to expire noncurrent versions of

objects with the "logs/" prefix 100 days after the objects become noncurrent.
• The NoncurrentVersionTransition action tells Amazon S3 to transition noncurrent versions
of objects with the "documents/" prefix to the GLACIER storage class 30 days after they become
noncurrent.
<Rule>
</Rule>
<Rule>
<ID>TransitionAfterBecomingNonCurrent</ID>
</Rule>

Content-MD5: 96rxH9mDqVNKkaZDddgnw==
Content-Length: 598
<Rule>
</Rule>
<Rule>
<ID>TransitionSoonAfterBecomingNonCurrent</ID>

601
</Rule>
HTTP/1.1 200 OK
x-amz-id-2: aXQ+KbIrmMmoO//3bMdDTw/CnjArwje+J49Hf+j44yRb/VmbIkgIO5A+PT98Cp/6k07hf+LD2mY=
x-amz-request-id: 02D7EC4C10381EB1
Date: Wed, 14 May 2014 02:21:50 GMT
Content-Length: 0
Server: AmazonS3
Additional Examples
For more examples of transitioning objects to storage classes such as STANDARD_IA or ONEZONE_IA, see
Examples of Lifecycle Configuration.
Related Resources
• By default, a resource owner—in this case, a bucket owner, which is the AWS account that created the
bucket—can perform any of the operations. A resource owner can also grant others permission to
perform the operation. For more information, see the following topics in the Amazon Simple Storage
Service Developer Guide:
• Specifying Permissions in a Policy
• Managing Access Permissions to Your Amazon S3 Resources

602
GET Bucket lifecycle (Deprecated)

Description
Important
For an updated version of this API, see GET Bucket lifecycle (p. 171). If you configured a bucket
lifecycle using the <filter> element, you should see an updated version of this topic. This topic is
provided for backward compatibility.
Returns the lifecycle configuration information set on the bucket. For information about lifecycle
configuration, go to Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.
To use this operation, you must have permission to perform the s3:GetLifecycleConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Managing Access Permissions to Your Amazon S3
Resources in the Amazon Simple Storage Service Developer Guide.
Requests
Syntax

Date: date
4))
Request Parameters
Request Headers
Request Elements
Responses
Response Headers
Response Elements

for the rule

603

Type: Container
Ancestor: Rule

Storage Service Developer Guide. are absent
The date value must conform to the ISO 8601

Type: String

when the specific rule action takes effect. The Date and
object's eligibility time is calculated as creation ExpiredObjectDeleteMa
time + the number of days with the resulting time are absent
rounded to midnight UTC of the next day.
Type: Non-negative Integer when used with

Expiration.
Ancestor: Transition or Expiration
DaysAfterInitiation Specifies the number of days after initiating a Yes, if Date

multipart upload when the multipart upload is absent
must be completed. If it does not complete by

604
Expiration This action specifies a period in the object's Yes, if the

lifetime when Amazon S3 should take the parent tag is
appropriate expiration action. The expiration specified
action occurs only on objects that are eligible
according to the period specified in the child
Date or Days element. The action Amazon
S3 takes depends on whether the bucket is
versioning enabled.

object permanently.
• Otherwise, if your bucket is versioning-
enabled (or versioning is suspended), the
action applies only to the current version of the
object. Buckets that are versioning-enabled or
versioning-suspended can have many versions
of the same object: one current version, and
zero or more noncurrent versions.

Important
If the state of a bucket is versioning-
null, then Amazon S3 overwrites that
version.
Note
To set the expiration for noncurrent
action.
Type: Container
Ancestor: Rule

Type: String
Ancestor: Rule

605
as 1000 rules.
Type: Container
Children: Rule
Ancestor: None
ExpiredObjectDeleteMarker On a versioned bucket (versioning-enabled or Yes, if Date

versioning-suspended bucket), this element and Days
indicates whether Amazon S3 will delete any are absent
expired object delete markers in the bucket. For
an example, go to Example 8: Specify Expiration
Action to Remove Expired Object Delete Markers
in the Amazon Simple Storage Service Developer
Guide.
Type: String

allowed but it is no-op, Amazon S3 doesn't take
action if the value is false)
NoncurrentDays Specifies the number of days that an object Yes, only if

is noncurrent before Amazon S3 can perform the ancestor
the associated action. For information about is present
calculating noncurrent days, see Lifecycle Rules
Based on the Number of Days in the Amazon


the Rule
Set this lifecycle configuration action on a bucket
that has versioning enabled (or suspended)
to request that Amazon S3 delete noncurrent
object versions at a specific period in the object's
lifetime.
Type: Container
Ancestor: Rule

606
NoncurrentVersionTransition Container for the transition rule that describes Yes, if no

when noncurrent objects transition to the other action
STANDARD_IA, ONEZONE_IA, or the GLACIER is present in
storage class. the Rule
If your bucket is versioning-enabled (or

versioning is suspended), you can set this action
to request Amazon S3 to transition noncurrent
object versions to the GLACIER storage class at a
specific period in the object's lifetime.
Type: Container
Ancestor: Rule
Prefix Object key prefix identifying one or more objects Yes

to which the rule applies.
Type: String
Ancestor: Rule
Rule Container for a lifecycle rule. Yes
Type: Container
Ancestor: LifecycleConfiguration
Status If Enabled, Amazon S3 executes the rule as Yes

scheduled. If Disabled, Amazon S3 ignores the
rule.
Type: String
Ancestor: Rule
Valid values: Enabled or Disabled

you want to transition the object.
Type: String
Ancestor: Transition and

Valid values: STANDARD_IA | ONEZONE_IA |

GLACIER

607

lifetime when Amazon S3 should transition them other action
to the STANDARD_IA, ONEZONE_IA, or GLACIER is present in
storage class. When this action is in effect, what the Rule
Amazon S3 does depends on whether the bucket
is versioning-enabled.

• When your bucket is versioning-enabled
(or versioning is suspended), Amazon S3
transitions only the current versions of the
objects identified in the rule.
Note
A versioning-enabled or versioning-
suspended bucket can contain many
versions of an object. This action
has no effect on the noncurrent
action.
Type: Container
Ancestor: Rule
Special Errors

Code Code Prefix
The lifecycle configuration does not

NoSuchLifecycleConfiguration 404 Not Client
exist. Found
Examples
Example 1: Retrieve a Lifecycle Subresource
This example is a GET request to retrieve the lifecycle subresource from the specified bucket, and an
example response with the returned lifecycle configuration.
Sample Request


608

Sample Response
HTTP/1.1 200 OK
x-amz-request-id: 51991C342C575321
Date: Thu, 15 Nov 2012 00:17:23 GMT
Server: AmazonS3
Content-Length: 358

<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ID>Archive and then delete rule</ID>
<Prefix>projectdocs/</Prefix>
<Transition>
<Days>30</Days>
</Transition>
<Transition>
<Days>365</Days>
</Transition>
<Expiration>
<Days>3650</Days>
</Expiration>
</Rule>
Related Resources

609
Glossary
100-continue A method that enables a client to see if a server can accept a request before
actually sending it. For large PUTs, this can save both time and bandwidth
charges.
account AWS account associated with a particular developer.
authentication The process of proving your identity to the system.
bucket A container for objects stored in Amazon S3. Every object is contained within
a bucket. For example, if the object named photos/puppy.jpg is stored
in the johnsmith bucket, then it is addressable using the URL http://
johnsmith.s3.amazonaws.com/photos/puppy.jpg
canned access policy A standard access control policy that you can apply to a bucket or object. Valid
Values: private | public-read | public-read-write | aws-exec-
read | authenticated-read | bucket-owner-read | bucket-owner-
full-control
canonicalization The process of converting data into a standard format that will be recognized by a
service such as Amazon S3.
consistency model The method through which Amazon S3 achieves high availability, which involves
replicating data across multiple servers within Amazon's data centers. After a
"success" is returned, your data is safely stored. However, information about the
changes might not immediately replicate across Amazon S3.
key The unique identifier for an object within a bucket. Every object in a bucket has
exactly one key. Since a bucket and key together uniquely identify each object,
Amazon S3 can be thought of as a basic data map between "bucket + key" and
the object itself. Every object in Amazon S3 can be uniquely addressed through
the combination of the web service endpoint, bucket name, and key, as in http://
doc.s3.amazonaws.com/2006-03-01/AmazonS3.wsdl, where "doc" is the name of
the bucket, and "2006-03-01/AmazonS3.wsdl" is the key.
metadata The metadata is a set of name-value pairs that describe the object. These include
default metadata such as the date last modified and standard HTTP metadata
such as Content-Type. The developer can also specify custom metadata at the
time the Object is stored.
object The fundamental entities stored in Amazon S3. Objects consist of object data and
metadata. The data portion is opaque to Amazon S3.

610
part The fundamental entities stored in Amazon S3. Objects consist of object data and
metadata. The data portion is opaque to Amazon S3.
service endpoint The host and port with which you are trying to communicate
within the destination URL. For virtual hosted-style requests, this
is mybucket.s3.amazonaws.com. For path-style requests, this is
s3.amazonaws.com

611
Data Types
API Reference
This section contains the API Reference documentation.
Data Types
The following data types are supported by Amazon Simple Storage Service:
• AbortIncompleteMultipartUpload (p. 619)

• AccelerateConfiguration (p. 620)
• AccessControlPolicy (p. 621)
• AccessControlTranslation (p. 622)
• AnalyticsAndOperator (p. 623)
• AnalyticsConfiguration (p. 624)
• AnalyticsExportDestination (p. 625)
• AnalyticsFilter (p. 626)
• AnalyticsS3BucketDestination (p. 627)
• Bucket (p. 628)
• BucketLifecycleConfiguration (p. 629)
• BucketLoggingStatus (p. 630)
• CloudFunctionConfiguration (p. 631)
• CommonPrefix (p. 633)
• CompletedMultipartUpload (p. 634)
• CompletedPart (p. 635)
• Condition (p. 636)
• ContinuationEvent (p. 637)
• CopyObjectResult (p. 638)
• CopyPartResult (p. 639)
• CORSConfiguration (p. 640)
• CORSRule (p. 641)
• CreateBucketConfiguration (p. 643)
• CSVInput (p. 644)
• CSVOutput (p. 646)
• DefaultRetention (p. 647)
• Delete (p. 648)
• DeletedObject (p. 649)
• DeleteMarkerEntry (p. 650)
• DeleteMarkerReplication (p. 651)
• Destination (p. 652)
• Encryption (p. 654)
• EncryptionConfiguration (p. 655)
• EndEvent (p. 656)
• Error (p. 657)

612
Data Types
• ErrorDocument (p. 658)

• FilterRule (p. 659)
• GlacierJobParameters (p. 660)
• Grant (p. 661)
• Grantee (p. 662)
• IndexDocument (p. 663)
• Initiator (p. 664)
• InputSerialization (p. 665)
• InventoryConfiguration (p. 666)
• InventoryDestination (p. 668)
• InventoryEncryption (p. 669)
• InventoryFilter (p. 670)
• InventoryS3BucketDestination (p. 671)
• InventorySchedule (p. 672)
• JSONInput (p. 673)
• JSONOutput (p. 674)
• LambdaFunctionConfiguration (p. 675)
• LifecycleConfiguration (p. 676)
• LifecycleExpiration (p. 677)
• LifecycleRule (p. 678)
• LifecycleRuleAndOperator (p. 680)
• LifecycleRuleFilter (p. 681)
• LoggingEnabled (p. 682)
• MetadataEntry (p. 683)
• MetricsAndOperator (p. 684)
• MetricsConfiguration (p. 685)
• MetricsFilter (p. 686)
• MultipartUpload (p. 687)
• NoncurrentVersionExpiration (p. 689)
• NoncurrentVersionTransition (p. 690)
• NotificationConfiguration (p. 691)
• NotificationConfigurationDeprecated (p. 692)
• NotificationConfigurationFilter (p. 693)
• Object (p. 694)
• ObjectIdentifier (p. 695)
• ObjectLockConfiguration (p. 696)
• ObjectLockLegalHold (p. 697)
• ObjectLockRetention (p. 698)
• ObjectLockRule (p. 699)
• ObjectVersion (p. 700)
• OutputLocation (p. 702)
• OutputSerialization (p. 703)
• Owner (p. 704)
• ParquetInput (p. 705)
• Part (p. 706)
• PolicyStatus (p. 707)

613
Data Types
• Progress (p. 708)

• ProgressEvent (p. 709)
• PublicAccessBlockConfiguration (p. 710)
• QueueConfiguration (p. 712)
• QueueConfigurationDeprecated (p. 713)
• RecordsEvent (p. 714)
• Redirect (p. 715)
• RedirectAllRequestsTo (p. 717)
• ReplicationConfiguration (p. 718)
• ReplicationRule (p. 719)
• ReplicationRuleAndOperator (p. 721)
• ReplicationRuleFilter (p. 722)
• RequestPaymentConfiguration (p. 723)
• RequestProgress (p. 724)
• RestoreRequest (p. 725)
• RoutingRule (p. 727)
• Rule (p. 728)
• S3KeyFilter (p. 730)
• S3Location (p. 731)
• SelectObjectContentEventStream (p. 733)
• SelectParameters (p. 734)
• ServerSideEncryptionByDefault (p. 735)
• ServerSideEncryptionConfiguration (p. 736)
• ServerSideEncryptionRule (p. 737)
• SourceSelectionCriteria (p. 738)
• SSEKMS (p. 739)
• SseKmsEncryptedObjects (p. 740)
• SSES3 (p. 741)
• Stats (p. 742)
• StatsEvent (p. 743)
• StorageClassAnalysis (p. 744)
• StorageClassAnalysisDataExport (p. 745)
• Tag (p. 746)
• Tagging (p. 747)
• TargetGrant (p. 748)
• TopicConfiguration (p. 749)
• TopicConfigurationDeprecated (p. 750)
• Transition (p. 752)
• VersioningConfiguration (p. 753)
• WebsiteConfiguration (p. 754)
The following data types are supported by AWS S3 Control:
• JobDescriptor (p. 756)

• JobFailure (p. 759)
• JobListDescriptor (p. 760)

614
• JobManifest (p. 762)

• JobManifestLocation (p. 763)
• JobManifestSpec (p. 764)
• JobOperation (p. 765)
• JobProgressSummary (p. 766)
• JobReport (p. 767)
• LambdaInvokeOperation (p. 769)
• S3AccessControlList (p. 772)
• S3AccessControlPolicy (p. 773)
• S3CopyObjectOperation (p. 774)
• S3Grant (p. 777)
• S3Grantee (p. 778)
• S3InitiateRestoreObjectOperation (p. 779)
• S3ObjectMetadata (p. 780)
• S3ObjectOwner (p. 782)
• S3SetObjectAclOperation (p. 783)
• S3SetObjectTaggingOperation (p. 784)
• S3Tag (p. 785)

The following data types are supported by Amazon Simple Storage Service:
• AbortIncompleteMultipartUpload (p. 619)

• AccelerateConfiguration (p. 620)
• AccessControlPolicy (p. 621)
• AccessControlTranslation (p. 622)
• AnalyticsAndOperator (p. 623)
• AnalyticsConfiguration (p. 624)
• AnalyticsExportDestination (p. 625)
• AnalyticsFilter (p. 626)
• AnalyticsS3BucketDestination (p. 627)
• Bucket (p. 628)
• BucketLifecycleConfiguration (p. 629)
• BucketLoggingStatus (p. 630)
• CloudFunctionConfiguration (p. 631)
• CommonPrefix (p. 633)
• CompletedMultipartUpload (p. 634)
• CompletedPart (p. 635)
• Condition (p. 636)
• ContinuationEvent (p. 637)
• CopyObjectResult (p. 638)
• CopyPartResult (p. 639)
• CORSConfiguration (p. 640)
• CORSRule (p. 641)

615
• CreateBucketConfiguration (p. 643)

• CSVInput (p. 644)
• CSVOutput (p. 646)
• DefaultRetention (p. 647)
• Delete (p. 648)
• DeletedObject (p. 649)
• DeleteMarkerEntry (p. 650)
• DeleteMarkerReplication (p. 651)
• Destination (p. 652)
• Encryption (p. 654)
• EncryptionConfiguration (p. 655)
• EndEvent (p. 656)
• Error (p. 657)
• ErrorDocument (p. 658)
• FilterRule (p. 659)
• GlacierJobParameters (p. 660)
• Grant (p. 661)
• Grantee (p. 662)
• IndexDocument (p. 663)
• Initiator (p. 664)
• InputSerialization (p. 665)
• InventoryConfiguration (p. 666)
• InventoryDestination (p. 668)
• InventoryEncryption (p. 669)
• InventoryFilter (p. 670)
• InventoryS3BucketDestination (p. 671)
• InventorySchedule (p. 672)
• JSONInput (p. 673)
• JSONOutput (p. 674)
• LambdaFunctionConfiguration (p. 675)
• LifecycleConfiguration (p. 676)
• LifecycleExpiration (p. 677)
• LifecycleRule (p. 678)
• LifecycleRuleAndOperator (p. 680)
• LifecycleRuleFilter (p. 681)
• LoggingEnabled (p. 682)
• MetadataEntry (p. 683)
• MetricsAndOperator (p. 684)
• MetricsConfiguration (p. 685)
• MetricsFilter (p. 686)
• MultipartUpload (p. 687)
• NoncurrentVersionExpiration (p. 689)
• NoncurrentVersionTransition (p. 690)
• NotificationConfiguration (p. 691)
• NotificationConfigurationDeprecated (p. 692)
• NotificationConfigurationFilter (p. 693)

616
• Object (p. 694)

• ObjectIdentifier (p. 695)
• ObjectLockConfiguration (p. 696)
• ObjectLockLegalHold (p. 697)
• ObjectLockRetention (p. 698)
• ObjectLockRule (p. 699)
• ObjectVersion (p. 700)
• OutputLocation (p. 702)
• OutputSerialization (p. 703)
• Owner (p. 704)
• ParquetInput (p. 705)
• Part (p. 706)
• PolicyStatus (p. 707)
• Progress (p. 708)
• ProgressEvent (p. 709)
• QueueConfiguration (p. 712)
• QueueConfigurationDeprecated (p. 713)
• RecordsEvent (p. 714)
• Redirect (p. 715)
• RedirectAllRequestsTo (p. 717)
• ReplicationConfiguration (p. 718)
• ReplicationRule (p. 719)
• ReplicationRuleAndOperator (p. 721)
• ReplicationRuleFilter (p. 722)
• RequestPaymentConfiguration (p. 723)
• RequestProgress (p. 724)
• RestoreRequest (p. 725)
• RoutingRule (p. 727)
• Rule (p. 728)
• S3KeyFilter (p. 730)
• S3Location (p. 731)
• SelectObjectContentEventStream (p. 733)
• SelectParameters (p. 734)
• ServerSideEncryptionByDefault (p. 735)
• ServerSideEncryptionConfiguration (p. 736)
• ServerSideEncryptionRule (p. 737)
• SourceSelectionCriteria (p. 738)
• SSEKMS (p. 739)
• SseKmsEncryptedObjects (p. 740)
• SSES3 (p. 741)
• Stats (p. 742)
• StatsEvent (p. 743)
• StorageClassAnalysis (p. 744)
• StorageClassAnalysisDataExport (p. 745)
• Tag (p. 746)

617
• Tagging (p. 747)

• TargetGrant (p. 748)
• TopicConfiguration (p. 749)
• TopicConfigurationDeprecated (p. 750)
• Transition (p. 752)
• VersioningConfiguration (p. 753)
• WebsiteConfiguration (p. 754)

618
AbortIncompleteMultipartUpload
Specifies the days since the initiation of an incomplete multipart upload that Amazon S3 will wait before
permanently removing all parts of the upload. For more information, see Aborting Incomplete Multipart
Uploads Using a Bucket Lifecycle Policy in the Amazon Simple Storage Service Developer Guide.
Contents
DaysAfterInitiation
Specifies the number of days after which Amazon S3 aborts an incomplete multipart upload.
Type: Integer
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Go - Pilot

619
AccelerateConfiguration
Configures the transfer acceleration state for an Amazon S3 bucket. For more information, see Amazon
S3 Transfer Acceleration in the Amazon Simple Storage Service Developer Guide.
Contents
Status
Specifies the transfer acceleration status of the bucket.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

620
AccessControlPolicy
Contains the elements that set the ACL permissions for an object per grantee.
Contents
Grants
A list of grants.
Type: Array of Grant (p. 661) data types
Required: No
Owner
Container for the bucket owner's display name and ID.
Type: Owner (p. 704) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

621
AccessControlTranslation
A container for information about access control for replicas.
Contents
Owner
Specifies the replica ownership. For default and valid values, see PUT bucket replication in the
Type: String
Valid Values: Destination
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

622
AnalyticsAndOperator
A conjunction (logical AND) of predicates, which is used in evaluating a metrics filter. The operator must
have at least two predicates in any combination, and an object must match all of the predicates for the
filter to apply.
Contents
Prefix
The prefix to use when evaluating an AND predicate: The prefix that an object must have to be
included in the metrics results.
Type: String
Required: No
Tags
The list of tags to use when evaluating an AND predicate.
Type: Array of Tag (p. 746) data types
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

623
AnalyticsConfiguration
Specifies the configuration and any analyses for the analytics filter of an Amazon S3 bucket.
For more information, see GET Bucket analytics in the Amazon Simple Storage Service API Reference.
Contents
Filter
The filter used to describe a set of objects for analyses. A filter must have exactly one prefix, one tag,
or one conjunction (AnalyticsAndOperator). If no filter is provided, all objects will be considered in
any analysis.
Type: AnalyticsFilter (p. 626) data type
Required: No
Id
The ID that identifies the analytics configuration.
Type: String
Required: Yes
StorageClassAnalysis
Contains data related to access patterns to be collected and made available to analyze the tradeoffs
between different storage classes.
Type: StorageClassAnalysis (p. 744) data type
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

624
AnalyticsExportDestination
Where to publish the analytics results.
Contents
S3BucketDestination
A destination signifying output to an S3 bucket.
Type: AnalyticsS3BucketDestination (p. 627) data type
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

625
AnalyticsFilter
Contents
And
A conjunction (logical AND) of predicates, which is used in evaluating an analytics filter. The operator
must have at least two predicates.
Type: AnalyticsAndOperator (p. 623) data type
Required: No
Prefix
The prefix to use when evaluating an analytics filter.
Type: String
Required: No
Tag
The tag to use when evaluating an analytics filter.
Type: Tag (p. 746) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

626
AnalyticsS3BucketDestination
Contents
Bucket
The Amazon Resource Name (ARN) of the bucket to which data is exported.
Type: String
Required: Yes
BucketAccountId
The account ID that owns the destination bucket. If no account ID is provided, the owner will not be
validated prior to exporting data.
Type: String
Required: No
Format
Specifies the file format used when exporting data to Amazon S3.
Type: String
Valid Values: CSV
Required: Yes
Prefix
The prefix to use when exporting data. The prefix is prepended to all results.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

627
Bucket
Contents
CreationDate
Date the bucket was created.
Type: Timestamp
Required: No
Name
The name of the bucket.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

628
BucketLifecycleConfiguration
Specifies the lifecycle configuration for objects in an Amazon S3 bucket. For more information, see
Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.
Contents
Rules
A lifecycle rule for individual objects in an Amazon S3 bucket.
Type: Array of LifecycleRule (p. 678) data types
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

629
BucketLoggingStatus
Contents
LoggingEnabled
Type: LoggingEnabled (p. 682) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

630
CloudFunctionConfiguration
Contents
CloudFunction
Type: String
Required: No
Event
This member has been deprecated.
The bucket event for which to send notifications.
Type: String
Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy
| s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* |
s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated |
s3:ObjectRestore:Post | s3:ObjectRestore:Completed
Required: No
Events
Type: Array of strings

Required: No
Id
An optional unique identifier for configurations in a notification configuration. If you don't provide
one, Amazon S3 will assign an ID.
Type: String
Required: No
InvocationRole
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

631


632
CommonPrefix
Contents
Prefix
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

633
CompletedMultipartUpload
Contents
Parts
Type: Array of CompletedPart (p. 635) data types
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

634
CompletedPart
Contents
ETag
Entity tag returned when the part was uploaded.
Type: String
Required: No
PartNumber
Part number that identifies the part. This is a positive integer between 1 and 10,000.
Type: Integer
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

635
Condition
Specifies a condition that must be met for a redirect to apply.
Contents
HttpErrorCodeReturnedEquals
The HTTP error code when the redirect is applied. In the event of an error, if the error code equals
this value, then the specified redirect is applied. Required when parent element Condition is
specified and sibling KeyPrefixEquals is not specified. If both are specified, then both must be
true for the redirect to be applied.
Type: String
Required: No
KeyPrefixEquals
The object key name prefix when the redirect is applied. For example, to redirect requests
for ExamplePage.html, the key prefix will be ExamplePage.html. To redirect request
for all pages with the prefix docs/, the key prefix will be /docs, which identifies all objects
in the docs/ folder. Required when the parent element Condition is specified and sibling
HttpErrorCodeReturnedEquals is not specified. If both conditions are specified, both must be
true for the redirect to be applied.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

636
ContinuationEvent
Contents
The members of this structure are context-dependent.
See Also
• AWS SDK for C++

• AWS SDK for Go

637
CopyObjectResult
Contents
ETag
Type: String
Required: No
LastModified
Type: Timestamp
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

638
CopyPartResult
Contents
ETag
Entity tag of the object.
Type: String
Required: No
LastModified
Date and time at which the object was uploaded.
Type: Timestamp
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

639
CORSConfiguration
Describes the cross-origin access configuration for objects in an Amazon S3 bucket. For more
information, see Enabling Cross-Origin Resource Sharing in the Amazon Simple Storage Service Developer
Guide.
Contents
CORSRules
A set of allowed origins and methods.
Type: Array of CORSRule (p. 641) data types
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

640
CORSRule
Specifies a cross-origin access rule for an Amazon S3 bucket.
Contents
AllowedHeaders
Headers that are specified in the Access-Control-Request-Headers header. These headers are
allowed in a preflight OPTIONS request. In response to any preflight OPTIONS request, Amazon S3
returns any requested headers that are allowed.
Required: No
AllowedMethods
An HTTP method that you allow the origin to execute. Valid values are GET, PUT, HEAD, POST, and
DELETE.
Required: Yes
AllowedOrigins
One or more origins you want customers to be able to access the bucket from.
Required: Yes
ExposeHeaders
One or more headers in the response that you want customers to be able to access from their
applications (for example, from a JavaScript XMLHttpRequest object).
Required: No
MaxAgeSeconds
The time in seconds that your browser is to cache the preflight response for the specified resource.
Type: Integer
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

641

642
CreateBucketConfiguration
Contents
LocationConstraint
Specifies the region where the bucket will be created. If you don't specify a region, the bucket is
created in US East (N. Virginia) Region (us-east-1).
Type: String
Valid Values: EU | eu-west-1 | us-west-1 | us-west-2 | ap-south-1 | ap-

southeast-1 | ap-southeast-2 | ap-northeast-1 | sa-east-1 | cn-north-1 | eu-
central-1
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

643
CSVInput
Describes how a CSV-formatted input object is formatted.
Contents
AllowQuotedRecordDelimiter
Specifies that CSV field values may contain quoted record delimiters and such records should be
allowed. Default value is FALSE. Setting this value to TRUE may lower performance.
Type: Boolean
Required: No
Comments
The single character used to indicate a row should be ignored when present at the start of a row.
Type: String
Required: No
FieldDelimiter
The value used to separate individual fields in a record.
Type: String
Required: No
FileHeaderInfo
Describes the first line of input. Valid values: None, Ignore, Use.
Type: String
Valid Values: USE | IGNORE | NONE
Required: No
QuoteCharacter
Value used for escaping where the field delimiter is part of the value.
Type: String
Required: No
QuoteEscapeCharacter
The single character used for escaping the quote character inside an already escaped value.
Type: String
Required: No
RecordDelimiter
The value used to separate individual records.
Type: String
Required: No

644
See Also
• AWS SDK for C++

• AWS SDK for Go

645
CSVOutput
Describes how CSV-formatted results are formatted.
Contents
FieldDelimiter
The value used to separate individual fields in a record.
Type: String
Required: No
QuoteCharacter
The value used for escaping where the field delimiter is part of the value.
Type: String
Required: No
QuoteEscapeCharacter
Th single character used for escaping the quote character inside an already escaped value.
Type: String
Required: No
QuoteFields
Indicates whether or not all output fields should be quoted.
Type: String
Valid Values: ALWAYS | ASNEEDED
Required: No
RecordDelimiter
The value used to separate individual records.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

646
DefaultRetention
The container element for specifying the default object lock retention settings for new objects placed in
Contents
Days
The number of days that you want to specify for the default retention period.
Type: Integer
Required: No
Mode
The default object lock retention mode you want to apply to new objects placed in the specified
bucket.
Type: String
Required: No
Years
The number of years that you want to specify for the default retention period.
Type: Integer
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

647
Delete
Contents
Objects
Type: Array of ObjectIdentifier (p. 695) data types
Required: Yes
Quiet
Element to enable quiet mode for the request. When you add this element, you must set its value to
true.
Type: Boolean
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

648
DeletedObject
Contents
DeleteMarker
Type: Boolean
Required: No
DeleteMarkerVersionId
Type: String
Required: No
Key
Type: String
Length Constraints: Minimum length of 1.
Required: No
VersionId
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

649
DeleteMarkerEntry
Contents
IsLatest
Specifies whether the object is (true) or is not (false) the latest version of an object.
Type: Boolean
Required: No
Key
The object key.
Type: String
Required: No
LastModified
Date and time the object was last modified.
Type: Timestamp
Required: No
Owner
Required: No
VersionId
Version ID of an object.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

650
Specifies whether Amazon S3 should replicate delete makers.
Contents
Status
The status of the delete marker replication.

Note
In the current implementation, Amazon S3 doesn't replicate the delete markers. The status
must be Disabled.
Type: String
Valid Values: Enabled | Disabled
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

651
Destination
Specifies information about where to publish analysis or configuration results for an Amazon S3 bucket.
Contents
AccessControlTranslation
Specify this only in a cross-account scenario (where source and destination bucket owners are not
the same), and you want to change replica ownership to the AWS account that owns the destination
bucket. If this is not specified in the replication configuration, the replicas are owned by same AWS
account that owns the source object.
Type: AccessControlTranslation (p. 622) data type
Required: No
Account
Destination bucket owner account ID. In a cross-account scenario, if you direct Amazon S3 to
change replica ownership to the AWS account that owns the destination bucket by specifying the
AccessControlTranslation property, this is the account ID of the destination bucket owner. For
more information, see Cross-Region Replication Additional Configuration: Change Replica Owner in
Type: String
Required: No
Bucket
The Amazon Resource Name (ARN) of the bucket where you want Amazon S3 to store replicas of the
object identified by the rule.
A replication configuration can replicate objects to only one destination bucket. If there are multiple
rules in your replication configuration, all rules must specify the same destination bucket.
Type: String
Required: Yes
EncryptionConfiguration
A container that provides information about encryption. If SourceSelectionCriteria is

specified, you must specify this element.
Type: EncryptionConfiguration (p. 655) data type
Required: No
StorageClass
The storage class to use when replicating objects, such as standard or reduced redundancy. By
default, Amazon S3 uses the storage class of the source object to create the object replica.
For valid values, see the StorageClass element of the PUT Bucket replication action in the Amazon
Simple Storage Service API Reference.
Type: String
Valid Values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA |

INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE

652
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

653
Encryption
Describes the server-side encryption that will be applied to the restore results.
Contents
EncryptionType
The server-side encryption algorithm used when storing job results in Amazon S3 (e.g., AES256,
aws:kms).
Type: String
Valid Values: AES256 | aws:kms
Required: Yes
KMSContext
If the encryption type is aws:kms, this optional value can be used to specify the encryption context
for the restore results.
Type: String
Required: No
KMSKeyId
If the encryption type is aws:kms, this optional value specifies the AWS KMS key ID to use for
encryption of job results.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

654
EncryptionConfiguration
Specifies encryption-related information for an Amazon S3 bucket that is a destination for replicated
objects.
Contents
ReplicaKmsKeyID
Specifies the AWS KMS Key ID (Key ARN or Alias ARN) for the destination bucket. Amazon S3 uses
this key to encrypt replica objects.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

655
EndEvent
Contents
See Also
• AWS SDK for C++

• AWS SDK for Go

656
Error
Contents
Code
Type: String
Required: No
Key
Type: String
Required: No
Message
Type: String
Required: No
VersionId
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

657
ErrorDocument
Contents
Key
The object key name to use when a 4XX class error occurs.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

658
FilterRule
Specifies the Amazon S3 object key name to filter on and whether to filter on the suffix or prefix of the
key name.
Contents
Name
The object key name prefix or suffix identifying one or more objects to which the filtering rule
applies. The maximum length is 1,024 characters. Overlapping prefixes and suffixes are not
supported. For more information, see Configuring Event Notifications in the Amazon Simple Storage
Type: String
Valid Values: prefix | suffix
Required: No
Value
The value that the filter searches for in object key names.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

659
GlacierJobParameters
Contents
Tier
Glacier retrieval tier at which the restore will be processed.
Type: String
Valid Values: Standard | Bulk | Expedited
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

660
Grant
Contents
Grantee
Type: Grantee (p. 662) data type
Required: No
Permission
Specifies the permission given to the grantee.
Type: String
Valid Values: FULL_CONTROL | WRITE | WRITE_ACP | READ | READ_ACP
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

661
Grantee
Contents
DisplayName
Screen name of the grantee.
Type: String
Required: No
EmailAddress
Email address of the grantee.
Type: String
Required: No
ID
The canonical user ID of the grantee.
Type: String
Required: No
Type
Type of grantee
Type: String
Valid Values: CanonicalUser | AmazonCustomerByEmail | Group
Required: Yes
URI
URI of the grantee group.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

662
IndexDocument
Contents
Suffix
A suffix that is appended to a request that is for a directory on the website endpoint (e.g. if the suffix
is index.html and you make a request to samplebucket/images/ the data that is returned will be
for the object with the key name images/index.html) The suffix must not be empty and must not
include a slash character.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

663
Initiator
Contents
DisplayName
Name of the Principal.
Type: String
Required: No
ID
If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it
provides a user ARN value.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

664
InputSerialization
Contents
CompressionType
Specifies object's compression format. Valid values: NONE, GZIP, BZIP2. Default Value: NONE.
Type: String
Valid Values: NONE | GZIP | BZIP2
Required: No
CSV
Describes the serialization of a CSV-encoded object.
Type: CSVInput (p. 644) data type
Required: No
JSON
Specifies JSON as object's input serialization format.
Type: JSONInput (p. 673) data type
Required: No
Parquet
Specifies Parquet as object's input serialization format.
Type: ParquetInput (p. 705) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

665
InventoryConfiguration
Specifies the inventory configuration for an Amazon S3 bucket. For more information, see GET Bucket
inventory in the Amazon Simple Storage Service API Reference.
Contents
Destination
Contains information about where to publish the inventory results.
Type: InventoryDestination (p. 668) data type
Required: Yes
Filter
Specifies an inventory filter. The inventory only includes objects that meet the filter's criteria.
Type: InventoryFilter (p. 670) data type
Required: No
Id
The ID used to identify the inventory configuration.
Type: String
Required: Yes
IncludedObjectVersions
Object versions to include in the inventory list. If set to All, the list includes all the object versions,
which adds the version-related fields VersionId, IsLatest, and DeleteMarker to the list. If set
to Current, the list does not contain these version-related fields.
Type: String
Valid Values: All | Current
Required: Yes
IsEnabled
Specifies whether the inventory is enabled or disabled. If set to True, an inventory list is generated.
If set to False, no inventory list is generated.
Type: Boolean
Required: Yes
OptionalFields
Contains the optional fields that are included in the inventory results.
Valid Values: Size | LastModifiedDate | StorageClass | ETag |

IsMultipartUploaded | ReplicationStatus | EncryptionStatus |
ObjectLockRetainUntilDate | ObjectLockMode | ObjectLockLegalHoldStatus
Required: No

666
Schedule
Specifies the schedule for generating inventory results.
Type: InventorySchedule (p. 672) data type
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

667
InventoryDestination
Contents
S3BucketDestination
Contains the bucket name, file format, bucket owner (optional), and prefix (optional) where
inventory results are published.
Type: InventoryS3BucketDestination (p. 671) data type
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

668
InventoryEncryption
Contains the type of server-side encryption used to encrypt the inventory results.
Contents
SSEKMS
Specifies the use of SSE-KMS to encrypt delivered Inventory reports.
Type: SSEKMS (p. 739) data type
Required: No
SSES3
Specifies the use of SSE-S3 to encrypt delivered Inventory reports.
Type: SSES3 (p. 741) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

669
InventoryFilter
Contents
Prefix
The prefix that an object must have to be included in the inventory results.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

670
InventoryS3BucketDestination
Contents
AccountId
The ID of the account that owns the destination bucket.
Type: String
Required: No
Bucket
The Amazon resource name (ARN) of the bucket where inventory results will be published.
Type: String
Required: Yes
Encryption
Contains the type of server-side encryption used to encrypt the inventory results.
Type: InventoryEncryption (p. 669) data type
Required: No
Format
Specifies the output format of the inventory results.
Type: String
Valid Values: CSV | ORC | Parquet
Required: Yes
Prefix
The prefix that is prepended to all inventory results.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

671
InventorySchedule
Contents
Frequency
Specifies how frequently inventory results are produced.
Type: String
Valid Values: Daily | Weekly
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

672
JSONInput
Contents
Type
The type of JSON. Valid values: Document, Lines.
Type: String
Valid Values: DOCUMENT | LINES
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

673
JSONOutput
Contents
RecordDelimiter
The value used to separate individual records in the output.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

674
LambdaFunctionConfiguration
A container for specifying the configuration for AWS Lambda notifications.
Contents
Events
The Amazon S3 bucket event for which to invoke the AWS Lambda function. For more information,
see Supported Event Types in the Amazon Simple Storage Service Developer Guide.

Required: Yes
Filter
Type: NotificationConfigurationFilter (p. 693) data type
Required: No
Id
Type: String
Required: No
LambdaFunctionArn
The Amazon Resource Name (ARN) of the AWS Lambda function that Amazon S3 invokes when the
specified event type occurs.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

675
LifecycleConfiguration
Contents
Rules
Type: Array of Rule (p. 728) data types
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

676
LifecycleExpiration
Contents
Date
Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
Type: Timestamp
Required: No
Days
Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-
zero positive integer.
Type: Integer
Required: No
ExpiredObjectDeleteMarker
Indicates whether Amazon S3 will remove a delete marker with no noncurrent versions. If set to true,
the delete marker will be expired; if set to false the policy takes no action. This cannot be specified
with Days or Date in a Lifecycle Expiration Policy.
Type: Boolean
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

677
LifecycleRule
Contents
Type: AbortIncompleteMultipartUpload (p. 619) data type
Required: No
Expiration
Type: LifecycleExpiration (p. 677) data type
Required: No
Filter
Type: LifecycleRuleFilter (p. 681) data type
Required: No
ID
Unique identifier for the rule. The value cannot be longer than 255 characters.
Type: String
Required: No
Type: NoncurrentVersionExpiration (p. 689) data type
Required: No
NoncurrentVersionTransitions
Type: Array of NoncurrentVersionTransition (p. 690) data types
Required: No
Prefix
Prefix identifying one or more objects to which the rule applies. This is No longer used; use Filter
instead.
Type: String
Required: No
Status
If 'Enabled', the rule is currently being applied. If 'Disabled', the rule is not currently being applied.
Type: String
Required: Yes
Transitions
Type: Array of Transition (p. 752) data types

678
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

679
LifecycleRuleAndOperator
This is used in a Lifecycle Rule Filter to apply a logical AND to two or more predicates. The Lifecycle Rule
will apply to any object matching all of the predicates configured inside the And operator.
Contents
Prefix
Type: String
Required: No
Tags
All of these tags must exist in the object's tag set in order for the rule to apply.
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

680
LifecycleRuleFilter
The Filter is used to identify objects that a Lifecycle Rule applies to. A Filter must have exactly one of
Prefix, Tag, or And specified.
Contents
And
Type: LifecycleRuleAndOperator (p. 680) data type
Required: No
Prefix
Prefix identifying one or more objects to which the rule applies.
Type: String
Required: No
Tag
This tag must exist in the object's tag set in order for the rule to apply.
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

681
LoggingEnabled
Describes where logs are stored and the prefix that Amazon S3 assigns to all log object keys for a bucket.
For more information, see PUT Bucket logging in the Amazon Simple Storage Service API Reference.
Contents
TargetBucket
Specifies the bucket where you want Amazon S3 to store server access logs. You can have your
logs delivered to any bucket that you own, including the same bucket that is being logged. You
can also configure multiple buckets to deliver their logs to the same target bucket. In this case you
should choose a different TargetPrefix for each source bucket so that the delivered log files can be
distinguished by key.
Type: String
Required: Yes
TargetGrants
Type: Array of TargetGrant (p. 748) data types
Required: No
TargetPrefix
A prefix for all log object keys. If you store log files from multiple Amazon S3 buckets in a single
bucket, you can use a prefix to distinguish which log files came from which bucket.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

682
MetadataEntry
A metadata key-value pair to store with an object.
Contents
Name
Type: String
Required: No
Value
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

683
MetricsAndOperator
Contents
Prefix
The prefix used when evaluating an AND predicate.
Type: String
Required: No
Tags
The list of tags used when evaluating an AND predicate.
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

684
MetricsConfiguration
Specifies a metrics configuration for the CloudWatch request metrics (specified by the metrics
configuration ID) from an Amazon S3 bucket. If you're updating an existing metrics configuration, note
that this is a full replacement of the existing metrics configuration. If you don't include the elements
you want to keep, they are erased. For more information, see PUT Bucket metrics in the Amazon Simple
Storage Service API Reference.
Contents
Filter
Specifies a metrics configuration filter. The metrics configuration will only include objects that meet
the filter's criteria. A filter must be a prefix, a tag, or a conjunction (MetricsAndOperator).
Type: MetricsFilter (p. 686) data type
Required: No
Id
The ID used to identify the metrics configuration.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

685
MetricsFilter
Contents
And
A conjunction (logical AND) of predicates, which is used in evaluating a metrics filter. The operator
must have at least two predicates, and an object must match all of the predicates in order for the
filter to apply.
Type: MetricsAndOperator (p. 684) data type
Required: No
Prefix
The prefix used when evaluating a metrics filter.
Type: String
Required: No
Tag
The tag used when evaluating a metrics filter.
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

686
MultipartUpload
Contents
Initiated
Date and time at which the multipart upload was initiated.
Type: Timestamp
Required: No
Initiator
Identifies who initiated the multipart upload.
Type: Initiator (p. 664) data type
Required: No
Key
Key of the object for which the multipart upload was initiated.
Type: String
Required: No
Owner
Required: No
StorageClass
The class of storage used to store the object.
Type: String

Required: No
UploadId
Upload ID that identifies the multipart upload.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

687


688
Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the
noncurrent object versions. You set this lifecycle configuration action on a bucket that has versioning
enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period
in the object's lifetime.
Contents
NoncurrentDays
Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated
action. For information about the noncurrent days calculations, see How Amazon S3 Calculates
When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
Type: Integer
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

689
Container for the transition rule that describes when noncurrent objects transition to the STANDARD_IA,
ONEZONE_IA, INTELLIGENT_TIERING, GLACIER, or DEEP_ARCHIVE storage class. If your bucket is
versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3
transition noncurrent object versions to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING,
GLACIER, or DEEP_ARCHIVE storage class at a specific period in the object's lifetime.
Contents
NoncurrentDays
Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated
action. For information about the noncurrent days calculations, see How Amazon S3 Calculates
When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
Type: Integer
Required: No
StorageClass
Type: String
Valid Values: GLACIER | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING |

DEEP_ARCHIVE
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

690
NotificationConfiguration
A container for specifying the notification configuration of the bucket. If this element is empty,
notifications are turned off for the bucket.
Contents
LambdaFunctionConfigurations
Describes the AWS Lambda functions to invoke and the events for which to invoke them.
Type: Array of LambdaFunctionConfiguration (p. 675) data types
Required: No
QueueConfigurations
The Amazon Simple Queue Service queues to publish messages to and the events for which to
publish messages.
Type: Array of QueueConfiguration (p. 712) data types
Required: No
TopicConfigurations
The topic to which notifications are sent and the events for which notifications are generated.
Type: Array of TopicConfiguration (p. 749) data types
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

691
NotificationConfigurationDeprecated
Contents
CloudFunctionConfiguration
Type: CloudFunctionConfiguration (p. 631) data type
Required: No
QueueConfiguration
Type: QueueConfigurationDeprecated (p. 713) data type
Required: No
TopicConfiguration
Type: TopicConfigurationDeprecated (p. 750) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

692
NotificationConfigurationFilter
Specifies object key name filtering rules. For information about key name filtering, see Configuring Event
Notifications in the Amazon Simple Storage Service Developer Guide.
Contents
Key
Type: S3KeyFilter (p. 730) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

693
Object
Contents
ETag
Type: String
Required: No
Key
Type: String
Required: No
LastModified
Type: Timestamp
Required: No
Owner
Required: No
Size
Type: Integer
Required: No
StorageClass
Type: String
Valid Values: STANDARD | REDUCED_REDUNDANCY | GLACIER | STANDARD_IA |

ONEZONE_IA | INTELLIGENT_TIERING | DEEP_ARCHIVE
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

694
ObjectIdentifier
Contents
Key
Key name of the object to delete.
Type: String
Required: Yes
VersionId
VersionId for the specific version of the object to delete.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

695
The container element for object lock configuration parameters.
Contents
ObjectLockEnabled
Indicates whether this bucket has an object lock configuration enabled.
Type: String
Valid Values: Enabled
Required: No
Rule
The object lock rule in place for the specified object.
Type: ObjectLockRule (p. 699) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

696
ObjectLockLegalHold
A Legal Hold configuration for an object.
Contents
Status
Indicates whether the specified object has a Legal Hold in place.
Type: String
Valid Values: ON | OFF
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

697
ObjectLockRetention
A Retention configuration for an object.
Contents
Mode
Indicates the Retention mode for the specified object.
Type: String
Required: No
RetainUntilDate
The date on which this object lock retention expires.
Type: Timestamp
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

698
ObjectLockRule
The container element for an object lock rule.
Contents
DefaultRetention
The default retention period that you want to apply to new objects placed in the specified bucket.
Type: DefaultRetention (p. 647) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

699
ObjectVersion
Contents
ETag
Type: String
Required: No
IsLatest
Specifies whether the object is (true) or is not (false) the latest version of an object.
Type: Boolean
Required: No
Key
The object key.
Type: String
Required: No
LastModified
Date and time the object was last modified.
Type: Timestamp
Required: No
Owner
Required: No
Size
Size in bytes of the object.
Type: Integer
Required: No
StorageClass
Type: String
Valid Values: STANDARD
Required: No
VersionId
Version ID of an object.
Type: String

700
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

701
OutputLocation
Describes the location where the restore job's output is stored.
Contents
S3
Describes an S3 location that will receive the results of the restore request.
Type: S3Location (p. 731) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

702
OutputSerialization
Describes how results of the Select job are serialized.
Contents
CSV
Describes the serialization of CSV-encoded Select results.
Type: CSVOutput (p. 646) data type
Required: No
JSON
Specifies JSON as request's output serialization format.
Type: JSONOutput (p. 674) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

703
Owner
Contents
DisplayName
Type: String
Required: No
ID
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

704
ParquetInput
Contents
See Also
• AWS SDK for C++

• AWS SDK for Go

705
Part
Contents
ETag
Entity tag returned when the part was uploaded.
Type: String
Required: No
LastModified
Date and time at which the part was uploaded.
Type: Timestamp
Required: No
PartNumber
Part number identifying the part. This is a positive integer between 1 and 10,000.
Type: Integer
Required: No
Size
Size in bytes of the uploaded part data.
Type: Integer
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

706
PolicyStatus
The container element for a bucket's policy status.
Contents
IsPublic
The policy status for this bucket. TRUE indicates that this bucket is public. FALSE indicates that the
bucket is not public.
Type: Boolean
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

707
Progress
Contents
BytesProcessed
The current number of uncompressed object bytes processed.
Type: Long
Required: No
BytesReturned
The current number of bytes of records payload data returned.
Type: Long
Required: No
BytesScanned
The current number of object bytes scanned.
Type: Long
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

708
ProgressEvent
Contents
Details
The Progress event details.
Type: Progress (p. 708) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

709
PublicAccessBlockConfiguration
Specifies the Block Public Access configuration for an Amazon S3 bucket.
Contents
BlockPublicAcls
Specifies whether Amazon S3 should block public access control lists (ACLs) for this bucket and
objects in this bucket. Setting this element to TRUE causes the following behavior:
• PUT Bucket acl and PUT Object acl calls fail if the specified ACL is public.
• PUT Object calls fail if the request includes a public ACL.
Type: Boolean
Required: No
BlockPublicPolicy
Specifies whether Amazon S3 should block public bucket policies for this bucket. Setting this
element to TRUE causes Amazon S3 to reject calls to PUT Bucket policy if the specified bucket policy
allows public access.
Type: Boolean
Required: No
IgnorePublicAcls
Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket.
Setting this element to TRUE causes Amazon S3 to ignore all public ACLs on this bucket and objects
in this bucket.
Enabling this setting doesn't affect the persistence of any existing ACLs and doesn't prevent new
public ACLs from being set.
Type: Boolean
Required: No
Specifies whether Amazon S3 should restrict public bucket policies for this bucket. Setting this
element to TRUE restricts access to this bucket to only AWS services and authorized users within this
account if the bucket has a public policy.
Enabling this setting doesn't affect previously stored bucket policies, except that public and cross-
account access within any public bucket policy, including non-public delegation to specific accounts,
is blocked.
Type: Boolean
Required: No
See Also

710
• AWS SDK for C++

• AWS SDK for Go

711
QueueConfiguration
Specifies the configuration for publishing messages to an Amazon Simple Queue Service (Amazon SQS)
queue when Amazon S3 detects specified events.
Contents
Events

Required: Yes
Filter
Required: No
Id
Type: String
Required: No
QueueArn
The Amazon Resource Name (ARN) of the Amazon SQS queue to which Amazon S3 publishes a
message when it detects events of the specified type.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

712
QueueConfigurationDeprecated
Contents
Event
The bucket event for which to send notifications.
Type: String

Required: No
Events

Required: No
Id
Type: String
Required: No
Queue
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

713
RecordsEvent
Contents
Payload
The byte array of partial, one or more result records.
Type: Base64-encoded binary data object
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

714
Redirect
Specifies how requests are redirected. In the event of an error, you can specify a different error code to
return.
Contents
HostName
The host name to use in the redirect request.
Type: String
Required: No
HttpRedirectCode
The HTTP redirect code to use on the response. Not required if one of the siblings is present.
Type: String
Required: No
Protocol
Protocol to use when redirecting requests. The default is the protocol that is used in the original
request.
Type: String
Valid Values: http | https
Required: No
ReplaceKeyPrefixWith
The object key prefix to use in the redirect request. For example, to redirect requests for all pages
with prefix docs/ (objects in the docs/ folder) to documents/, you can set a condition block
with KeyPrefixEquals set to docs/ and in the Redirect set ReplaceKeyPrefixWith to /
documents. Not required if one of the siblings is present. Can be present only if ReplaceKeyWith
is not provided.
Type: String
Required: No
ReplaceKeyWith
The specific object key to use in the redirect request. For example, redirect request to error.html.
Not required if one of the siblings is present. Can be present only if ReplaceKeyPrefixWith is not
provided.
Type: String
Required: No
See Also
• AWS SDK for C++

715
• AWS SDK for Go


716
RedirectAllRequestsTo
Specifies the redirect behavior of all requests to a website endpoint of an Amazon S3 bucket.
Contents
HostName
Name of the host where requests are redirected.
Type: String
Required: Yes
Protocol
Protocol to use when redirecting requests. The default is the protocol that is used in the original
request.
Type: String
Valid Values: http | https
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

717
ReplicationConfiguration
A container for replication rules. You can add up to 1,000 rules. The maximum size of a replication
configuration is 2 MB.
Contents
Role
The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that
Amazon S3 assumes when replicating objects. For more information, see How to Set Up Cross-
Region Replication in the Amazon Simple Storage Service Developer Guide.
Type: String
Required: Yes
Rules
A container for one or more replication rules. A replication configuration must have at least one rule
and can contain a maximum of 1,000 rules.
Type: Array of ReplicationRule (p. 719) data types
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

718
ReplicationRule
Specifies which Amazon S3 objects to replicate and where to store the replicas.
Contents
Type: DeleteMarkerReplication (p. 651) data type
Required: No
Destination
A container for information about the replication destination.
Type: Destination (p. 652) data type
Required: Yes
Filter
Type: ReplicationRuleFilter (p. 722) data type
Required: No
ID
A unique identifier for the rule. The maximum value is 255 characters.
Type: String
Required: No
Prefix
An object keyname prefix that identifies the object or objects to which the rule applies. The
maximum prefix length is 1,024 characters. To include all objects in a bucket, specify an empty
string.
Type: String
Required: No
Priority
The priority associated with the rule. If you specify multiple rules in a replication configuration,
Amazon S3 prioritizes the rules to prevent conflicts when filtering. If two or more rules identify the
same object based on a specified filter, the rule with higher priority takes precedence. For example:
• Same object quality prefix based filter criteria If prefixes you specified in multiple rules overlap
• Same object qualify tag based filter criteria specified in multiple rules
For more information, see Cross-Region Replication (CRR) in the Amazon S3 Developer Guide.
Type: Integer
Required: No
SourceSelectionCriteria
A container that describes additional filters for identifying the source objects that you want to
replicate. You can choose to enable or disable the replication of these objects. Currently, Amazon S3

719
supports only the filter that you can specify for objects created with server-side encryption using an
AWS KMS-Managed Key (SSE-KMS).
Type: SourceSelectionCriteria (p. 738) data type
Required: No
Status
Specifies whether the rule is enabled.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

720
ReplicationRuleAndOperator
Contents
Prefix
Type: String
Required: No
Tags
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

721
ReplicationRuleFilter
A filter that identifies the subset of objects to which the replication rule applies. A Filter must specify
exactly one Prefix, Tag, or an And child element.
Contents
And
A container for specifying rule filters. The filters determine the subset of objects to which the rule
applies. This element is required only if you specify more than one filter. For example:
• If you specify both a Prefix and a Tag filter, wrap these filters in an And tag.
• If you specify a filter based on multiple tags, wrap the Tag elements in an And tag.
Type: ReplicationRuleAndOperator (p. 721) data type
Required: No
Prefix
An object keyname prefix that identifies the subset of objects to which the rule applies.
Type: String
Required: No
Tag
A container for specifying a tag key and value.
The rule applies only to objects that have the tag in their tag set.
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

722
RequestPaymentConfiguration
Contents
Payer
Specifies who pays for the download and request fees.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

723
RequestProgress
Contents
Enabled
Specifies whether periodic QueryProgress frames should be sent. Valid values: TRUE, FALSE. Default
value: FALSE.
Type: Boolean
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

724
RestoreRequest
Container for restore job parameters.
Contents
Days
Lifetime of the active copy in days. Do not use with restores that specify OutputLocation.
Type: Integer
Required: No
Description
The optional description for the job.
Type: String
Required: No
GlacierJobParameters
Glacier related parameters pertaining to this job. Do not use with restores that specify
OutputLocation.
Type: GlacierJobParameters (p. 660) data type
Required: No
OutputLocation
Describes the location where the restore job's output is stored.
Type: OutputLocation (p. 702) data type
Required: No
SelectParameters
Describes the parameters for Select job types.
Type: SelectParameters (p. 734) data type
Required: No
Tier
Glacier retrieval tier at which the restore will be processed.
Type: String
Valid Values: Standard | Bulk | Expedited
Required: No
Type
Type of restore request.
Type: String
Valid Values: SELECT

725
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

726
RoutingRule
Specifies the redirect behavior and when a redirect is applied.
Contents
Condition
A container for describing a condition that must be met for the specified redirect to apply. For
example, 1. If request is for pages in the /docs folder, redirect to the /documents folder. 2. If
request results in HTTP error 4xx, redirect request to another host where you might process the
error.
Type: Condition (p. 636) data type
Required: No
Redirect
Container for redirect information. You can redirect requests to another host, to another page, or
with another protocol. In the event of an error, you can specify a different error code to return.
Type: Redirect (p. 715) data type
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

727
Rule
Specifies lifecycle rules for an Amazon S3 bucket. For more information, see PUT Bucket lifecycle in the
Contents
Type: AbortIncompleteMultipartUpload (p. 619) data type
Required: No
Expiration
Type: LifecycleExpiration (p. 677) data type
Required: No
ID
Unique identifier for the rule. The value can't be longer than 255 characters.
Type: String
Required: No
Type: NoncurrentVersionExpiration (p. 689) data type
Required: No
Type: NoncurrentVersionTransition (p. 690) data type
Required: No
Prefix
Object key prefix that identifies one or more objects to which this rule applies.
Type: String
Required: Yes
Status
If Enabled, the rule is currently being applied. If Disabled, the rule is not currently being applied.
Type: String
Required: Yes
Transition
Type: Transition (p. 752) data type
Required: No

728
See Also
• AWS SDK for C++

• AWS SDK for Go

729
S3KeyFilter
A container for object key name prefix and suffix filtering rules.
Contents
FilterRules
Type: Array of FilterRule (p. 659) data types
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

730
S3Location
Describes an S3 location that will receive the results of the restore request.
Contents
AccessControlList
A list of grants that control access to the staged results.
Type: Array of Grant (p. 661) data types
Required: No
BucketName
The name of the bucket where the restore results will be placed.
Type: String
Required: Yes
CannedACL
The canned ACL to apply to the restore results.
Type: String
Valid Values: private | public-read | public-read-write | authenticated-read |

aws-exec-read | bucket-owner-read | bucket-owner-full-control
Required: No
Encryption
Type: Encryption (p. 654) data type
Required: No
Prefix
The prefix that is prepended to the restore results for this request.
Type: String
Required: Yes
StorageClass
The class of storage used to store the restore results.
Type: String

Required: No
Tagging
The tag-set that is applied to the restore results.
Type: Tagging (p. 747) data type

731
Required: No
UserMetadata
A list of metadata to store with the restore results in S3.
Type: Array of MetadataEntry (p. 683) data types
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

732
SelectObjectContentEventStream
Contents
Cont
The Continuation Event.
Type: ContinuationEvent (p. 637) data type
Required: No
End
The End Event.
Type: EndEvent (p. 656) data type
Required: No
Progress
The Progress Event.
Type: ProgressEvent (p. 709) data type
Required: No
Records
The Records Event.
Type: RecordsEvent (p. 714) data type
Required: No
Stats
The Stats Event.
Type: StatsEvent (p. 743) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

733
SelectParameters
Describes the parameters for Select job types.
Contents
Expression
The expression that is used to query the object.
Type: String
Required: Yes
ExpressionType
The type of the provided expression (e.g., SQL).
Type: String
Valid Values: SQL
Required: Yes
InputSerialization
Type: InputSerialization (p. 665) data type
Required: Yes
OutputSerialization
Describes how the results of the Select job are serialized.
Type: OutputSerialization (p. 703) data type
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

734
ServerSideEncryptionByDefault
Describes the default server-side encryption to apply to new objects in the bucket. If a PUT Object
request doesn't specify any server-side encryption, this default encryption will be applied. For more
information, see PUT Bucket encryption in the Amazon Simple Storage Service API Reference.
Contents
KMSMasterKeyID
KMS master key ID to use for the default encryption. This parameter is allowed if and only if
SSEAlgorithm is set to aws:kms.
Type: String
Required: No
SSEAlgorithm
Server-side encryption algorithm to use for the default encryption.
Type: String
Valid Values: AES256 | aws:kms
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

735
ServerSideEncryptionConfiguration
Specifies the default server-side-encryption configuration.
Contents
Rules
Container for information about a particular server-side encryption configuration rule.
Type: Array of ServerSideEncryptionRule (p. 737) data types
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

736
ServerSideEncryptionRule
Specifies the default server-side encryption configuration.
Contents
Specifies the default server-side encryption to apply to new objects in the bucket. If a PUT Object
request doesn't specify any server-side encryption, this default encryption will be applied.
Type: ServerSideEncryptionByDefault (p. 735) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

737
SourceSelectionCriteria
A container that describes additional filters for identifying the source objects that you want to replicate.
You can choose to enable or disable the replication of these objects. Currently, Amazon S3 supports
only the filter that you can specify for objects created with server-side encryption using an AWS KMS-
Managed Key (SSE-KMS).
Contents
SseKmsEncryptedObjects
A container for filter information for the selection of Amazon S3 objects encrypted with AWS KMS. If
you include SourceSelectionCriteria in the replication configuration, this element is required.
Type: SseKmsEncryptedObjects (p. 740) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

738
SSEKMS
Specifies the use of SSE-KMS to encrypt delivered Inventory reports.
Contents
KeyId
Specifies the ID of the AWS Key Management Service (KMS) master encryption key to use for
encrypting Inventory reports.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

739
SseKmsEncryptedObjects
A container for filter information for the selection of S3 objects encrypted with AWS KMS.
Contents
Status
Specifies whether Amazon S3 replicates objects created with server-side encryption using an AWS
KMS-managed key.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

740
SSES3
Specifies the use of SSE-S3 to encrypt delivered Inventory reports.
Contents
See Also
• AWS SDK for C++

• AWS SDK for Go

741
Stats
Contents
BytesProcessed
The total number of uncompressed object bytes processed.
Type: Long
Required: No
BytesReturned
The total number of bytes of records payload data returned.
Type: Long
Required: No
BytesScanned
The total number of object bytes scanned.
Type: Long
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

742
StatsEvent
Contents
Details
The Stats event details.
Type: Stats (p. 742) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

743
StorageClassAnalysis
Specifies data related to access patterns to be collected and made available to analyze the tradeoffs
between different storage classes for an Amazon S3 bucket.
Contents
DataExport
Specifies how data related to the storage class analysis for an Amazon S3 bucket should be
exported.
Type: StorageClassAnalysisDataExport (p. 745) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

744
StorageClassAnalysisDataExport
Contents
Destination
The place to store the data for an analysis.
Type: AnalyticsExportDestination (p. 625) data type
Required: Yes
OutputSchemaVersion
The version of the output schema to use when exporting data. Must be V_1.
Type: String
Valid Values: V_1
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

745
Tag
Contents
Key
Name of the tag.
Type: String
Required: Yes
Value
Value of the tag.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

746
Tagging
Contents
TagSet
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

747
TargetGrant
Contents
Grantee
Type: Grantee (p. 662) data type
Required: No
Permission
Logging permissions assigned to the Grantee for the bucket.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

748
TopicConfiguration
A container for specifying the configuration for publication of messages to an Amazon Simple
Notification Service (Amazon SNS) topic when Amazon S3 detects specified events.
Contents
Events
The Amazon S3 bucket event about which to send notifications. For more information, see
Supported Event Types in the Amazon Simple Storage Service Developer Guide.

Required: Yes
Filter
Required: No
Id
Type: String
Required: No
TopicArn
The Amazon Resource Name (ARN) of the Amazon SNS topic to which Amazon S3 publishes a
message when it detects events of the specified type.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

749
TopicConfigurationDeprecated
Contents
Event
Bucket event for which to send notifications.
Type: String

Required: No
Events

Required: No
Id
Type: String
Required: No
Topic
Amazon SNS topic to which Amazon S3 will publish a message to report the specified events for the
bucket.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

750

751
Transition
Specifies when an object transitions to a specified storage class.
Contents
Date
Indicates when objects are transitioned to the specified storage class. The date value must be in ISO
8601 format. The time is always midnight UTC.
Type: Timestamp
Required: No
Days
Indicates the number of days after creation when objects are transitioned to the specified storage
class. The value must be a positive integer.
Type: Integer
Required: No
StorageClass
The storage class to which you want the object to transition.
Type: String
Valid Values: GLACIER | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING |

DEEP_ARCHIVE
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

752
VersioningConfiguration
Describes the versioning state of an Amazon S3 bucket. For more information, see PUT Bucket versioning
in the Amazon Simple Storage Service API Reference.
Contents
MFADelete
Specifies whether MFA delete is enabled in the bucket versioning configuration. This element is
only returned if the bucket has been configured with MFA delete. If the bucket has never been so
configured, this element is not returned.
Type: String
Required: No
Status
The versioning state of the bucket.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

753
AWS S3 Control
WebsiteConfiguration
Specifies website configuration parameters for an Amazon S3 bucket.
Contents
ErrorDocument
The name of the error document for the website.
Type: ErrorDocument (p. 658) data type
Required: No
IndexDocument
The name of the index document for the website.
Type: IndexDocument (p. 663) data type
Required: No
RedirectAllRequestsTo
The redirect behavior for every request to this bucket's website endpoint.
Important
If you specify this property, you can't specify any other property.
Type: RedirectAllRequestsTo (p. 717) data type
Required: No
RoutingRules
Rules that define when a redirect is applied and the redirect behavior.
Type: Array of RoutingRule (p. 727) data types
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go
AWS S3 Control
The following data types are supported by AWS S3 Control:
• JobDescriptor (p. 756)

• JobFailure (p. 759)

754
AWS S3 Control
• JobListDescriptor (p. 760)

• JobManifest (p. 762)
• JobManifestLocation (p. 763)
• JobManifestSpec (p. 764)
• JobOperation (p. 765)
• JobProgressSummary (p. 766)
• JobReport (p. 767)
• LambdaInvokeOperation (p. 769)
• S3AccessControlList (p. 772)
• S3AccessControlPolicy (p. 773)
• S3CopyObjectOperation (p. 774)
• S3Grant (p. 777)
• S3Grantee (p. 778)
• S3InitiateRestoreObjectOperation (p. 779)
• S3ObjectMetadata (p. 780)
• S3ObjectOwner (p. 782)
• S3SetObjectAclOperation (p. 783)
• S3SetObjectTaggingOperation (p. 784)
• S3Tag (p. 785)

755
AWS S3 Control
JobDescriptor
A container element for the job configuration and status information returned by a Describe Job
request.
Contents
ConfirmationRequired
Indicates whether confirmation is required before Amazon S3 begins running the specified job.
Confirmation is required only for jobs created through the Amazon S3 console.
Type: Boolean
Required: No
CreationTime
A timestamp indicating when this job was created.
Type: Timestamp
Required: No
Description
The description for this job, if one was provided in this job's Create Job request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Required: No
FailureReasons
If the specified job failed, this field contains information describing the failure.
Type: Array of JobFailure (p. 759) data types
Required: No
JobArn
The Amazon Resource Name (ARN) for this job.
Type: String
Required: No
JobId
The ID for the specified job.
Type: String
Required: No
Manifest
The configuration information for the specified job's manifest object.

756
AWS S3 Control
Type: JobManifest (p. 762) data type
Required: No
Operation
The operation that the specified job is configured to execute on the objects listed in the manifest.
Type: JobOperation (p. 765) data type
Required: No
Priority
The priority of the specified job.
Type: Integer
Valid Range: Minimum value of 0. Maximum value of 2147483647.
Required: No
ProgressSummary
Describes the total number of tasks that the specified job has executed, the number of tasks that
succeeded, and the number of tasks that failed.
Type: JobProgressSummary (p. 766) data type
Required: No
Report
Contains the configuration information for the job-completion report if you requested one in the
Create Job request.
Type: JobReport (p. 767) data type
Required: No
RoleArn
The Amazon Resource Name (ARN) for the Identity and Access Management (IAM) Role assigned to
execute the tasks for this job.
Type: String
Required: No
Status
The current status of the specified job.
Type: String

Required: No
StatusUpdateReason
Type: String

757
AWS S3 Control
Required: No
SuspendedCause
The reason why the specified job was suspended. A job is only suspended if you create it through the
Amazon S3 console. When you create the job, it enters the Suspended state to await confirmation
before running. After you confirm the job, it automatically exits the Suspended state.
Type: String
Required: No
SuspendedDate
The timestamp when this job was suspended, if it has been suspended.
Type: Timestamp
Required: No
TerminationDate
A timestamp indicating when this job terminated. A job's termination date is the date and time when
it succeeded, failed, or was canceled.
Type: Timestamp
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

758
AWS S3 Control
JobFailure
If this job failed, this element indicates why the job failed.
Contents
FailureCode
The failure code, if any, for the specified job.
Type: String
Required: No
FailureReason
The failure reason, if any, for the specified job.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

759
AWS S3 Control
JobListDescriptor
Contains the configuration and status information for a single job retrieved as part of a job list.
Contents
CreationTime
A timestamp indicating when the specified job was created.
Type: Timestamp
Required: No
Description
The user-specified description that was included in the specified job's Create Job request.
Type: String
Required: No
JobId
The ID for the specified job.
Type: String
Required: No
Operation
The operation that the specified job is configured to run on each object listed in the manifest.
Type: String
Valid Values: LambdaInvoke | S3PutObjectCopy | S3PutObjectAcl |

S3PutObjectTagging | S3InitiateRestoreObject
Required: No
Priority
The current priority for the specified job.
Type: Integer
Valid Range: Minimum value of 0. Maximum value of 2147483647.
Required: No
ProgressSummary
Type: JobProgressSummary (p. 766) data type
Required: No

760
AWS S3 Control
Status
The specified job's current status.
Type: String

Required: No
TerminationDate
A timestamp indicating when the specified job terminated. A job's termination date is the date and
time when it succeeded, failed, or was canceled.
Type: Timestamp
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

761
AWS S3 Control
JobManifest
Contains the configuration information for a job's manifest.
Contents
Location
Contains the information required to locate the specified job's manifest.
Type: JobManifestLocation (p. 763) data type
Required: Yes
Spec
Describes the format of the specified job's manifest. If the manifest is in CSV format, also describes
the columns contained within the manifest.
Type: JobManifestSpec (p. 764) data type
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

762
AWS S3 Control
JobManifestLocation
Contains the information required to locate a manifest object.
Contents
ETag
The ETag for the specified manifest object.
Type: String
Required: Yes
ObjectArn
The Amazon Resource Name (ARN) for a manifest object.
Type: String
Required: Yes
ObjectVersionId
The optional version ID to identify a specific version of the manifest object.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

763
AWS S3 Control
JobManifestSpec
Describes the format of a manifest. If the manifest is in CSV format, also describes the columns
contained within the manifest.
Contents
Fields
If the specified manifest object is in the S3BatchOperations_CSV_20180820 format, this element

describes which columns contain the required data.
Valid Values: Ignore | Bucket | Key | VersionId
Required: No
Format
Indicates which of the available formats the specified manifest uses.
Type: String
Valid Values: S3BatchOperations_CSV_20180820 | S3InventoryReport_CSV_20161130
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

764
AWS S3 Control
JobOperation
The operation that you want this job to perform on each object listed in the manifest. For more
information about the available operations, see Available Operations in the Amazon Simple Storage
Contents
LambdaInvoke
Directs the specified job to invoke an AWS Lambda function on each object in the manifest.
Type: LambdaInvokeOperation (p. 769) data type
Required: No
Directs the specified job to execute an Initiate Glacier Restore call on each object in the manifest.
Type: S3InitiateRestoreObjectOperation (p. 779) data type
Required: No
S3PutObjectAcl
Directs the specified job to execute a PUT Object acl call on each object in the manifest.
Type: S3SetObjectAclOperation (p. 783) data type
Required: No
S3PutObjectCopy
Directs the specified job to execute a PUT Copy object call on each object in the manifest.
Type: S3CopyObjectOperation (p. 774) data type
Required: No
S3PutObjectTagging
Directs the specified job to execute a PUT Object tagging call on each object in the manifest.
Type: S3SetObjectTaggingOperation (p. 784) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

765
AWS S3 Control
JobProgressSummary
Contents
NumberOfTasksFailed
Type: Long
Valid Range: Minimum value of 0.
Required: No
NumberOfTasksSucceeded
Type: Long
Required: No
TotalNumberOfTasks
Type: Long
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

766
AWS S3 Control
JobReport
Contains the configuration parameters for a job-completion report.
Contents
Bucket
The bucket where specified job-completion report will be stored.
Type: String
Required: No
Enabled
Indicates whether the specified job will generate a job-completion report.
Type: Boolean
Required: Yes
Format
The format of the specified job-completion report.
Type: String
Valid Values: Report_CSV_20180820
Required: No
Prefix
An optional prefix to describe where in the specified bucket the job-completion report will be stored.
Amazon S3 will store the job-completion report at <prefix>/job-<job-id>/report.json.
Type: String
Required: No
ReportScope
Indicates whether the job-completion report will include details of all tasks or only failed tasks.
Type: String
Valid Values: AllTasks | FailedTasksOnly
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

767
AWS S3 Control


768
AWS S3 Control
LambdaInvokeOperation
Contains the configuration parameters for a Lambda Invoke operation.
Contents
FunctionArn
The Amazon Resource Name (ARN) for the AWS Lambda function that the specified job will invoke
for each object in the manifest.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

769
AWS S3 Control
PublicAccessBlockConfiguration
The PublicAccessBlock configuration that you want to apply to this Amazon S3 bucket. You can
enable the configuration options in any combination. For more information about when Amazon S3
considers a bucket or object public, see The Meaning of "Public" in the Amazon Simple Storage Service
Developer Guide.
Contents
BlockPublicAcls
Specifies whether Amazon S3 should block public access control lists (ACLs) for buckets in this
account. Setting this element to TRUE causes the following behavior:
• PUT Bucket acl and PUT Object acl calls fail if the specified ACL is public.
• PUT Object calls fail if the request includes a public ACL.
• PUT Bucket calls fail if the request includes a public ACL.
Type: Boolean
Required: No
BlockPublicPolicy
Specifies whether Amazon S3 should block public bucket policies for buckets in this account. Setting
this element to TRUE causes Amazon S3 to reject calls to PUT Bucket policy if the specified bucket
policy allows public access.
Type: Boolean
Required: No
IgnorePublicAcls
Specifies whether Amazon S3 should ignore public ACLs for buckets in this account. Setting this
element to TRUE causes Amazon S3 to ignore all public ACLs on buckets in this account and any
objects that they contain.
Enabling this setting doesn't affect the persistence of any existing ACLs and doesn't prevent new
public ACLs from being set.
Type: Boolean
Required: No
Specifies whether Amazon S3 should restrict public bucket policies for buckets in this account.
Setting this element to TRUE restricts access to buckets with public policies to only AWS services and
authorized users within this account.
Enabling this setting doesn't affect previously stored bucket policies, except that public and cross-
account access within any public bucket policy, including non-public delegation to specific accounts,
is blocked.
Type: Boolean

770
AWS S3 Control
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

771
AWS S3 Control
S3AccessControlList
Contents
Grants
Type: Array of S3Grant (p. 777) data types
Required: No
Owner
Type: S3ObjectOwner (p. 782) data type
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

772
AWS S3 Control
S3AccessControlPolicy
Contents
AccessControlList
Type: S3AccessControlList (p. 772) data type
Required: No
Type: String
Valid Values: private | public-read | public-read-write | aws-exec-read |

authenticated-read | bucket-owner-read | bucket-owner-full-control
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

773
AWS S3 Control
S3CopyObjectOperation
Contains the configuration parameters for a PUT Copy object operation. Amazon S3 batch operations
passes each value through to the underlying PUT Copy object API. For more information about the
parameters for this operation, see PUT Object - Copy.
Contents
AccessControlGrants
Type: Array of S3Grant (p. 777) data types
Required: No
Type: String
Valid Values: private | public-read | public-read-write | aws-exec-read |

authenticated-read | bucket-owner-read | bucket-owner-full-control
Required: No
MetadataDirective
Type: String
Valid Values: COPY | REPLACE
Required: No
ModifiedSinceConstraint
Type: Timestamp
Required: No
NewObjectMetadata
Type: S3ObjectMetadata (p. 780) data type
Required: No
NewObjectTagging
Type: Array of S3Tag (p. 785) data types
Required: No
Type: String
Valid Values: OFF | ON
Required: No
ObjectLockMode
Type: String
Valid Values: COMPLIANCE | GOVERNANCE
Required: No

774
AWS S3 Control
ObjectLockRetainUntilDate
Type: Timestamp
Required: No
RedirectLocation
Type: String
Required: No
RequesterPays
Type: Boolean
Required: No
SSEAwsKmsKeyId
Type: String
Required: No
StorageClass
Type: String
Valid Values: STANDARD | STANDARD_IA | ONEZONE_IA | GLACIER |

Required: No
TargetKeyPrefix
Type: String
Required: No
TargetResource
Type: String
Required: No
UnModifiedSinceConstraint
Type: Timestamp
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

775
AWS S3 Control


776
AWS S3 Control
S3Grant
Contents
Grantee
Type: S3Grantee (p. 778) data type
Required: No
Permission
Type: String
Valid Values: FULL_CONTROL | READ | WRITE | READ_ACP | WRITE_ACP
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

777
AWS S3 Control
S3Grantee
Contents
DisplayName
Type: String
Required: No
Identifier
Type: String
Required: No
TypeIdentifier
Type: String
Valid Values: id | emailAddress | uri
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

778
AWS S3 Control
S3InitiateRestoreObjectOperation
Contains the configuration parameters for an Initiate Glacier Restore job. Amazon S3 batch operations
passes each value through to the underlying POST Object restore API. For more information about the
parameters for this operation, see Restoring Archives.
Contents
ExpirationInDays
Type: Integer
Required: No
GlacierJobTier
Type: String
Valid Values: BULK | STANDARD
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

779
AWS S3 Control
S3ObjectMetadata
Contents
CacheControl
Type: String
Required: No
ContentDisposition
Type: String
Required: No
ContentEncoding
Type: String
Required: No
ContentLanguage
Type: String
Required: No
ContentLength
Type: Long
Required: No
ContentMD5
Type: String
Required: No
ContentType
Type: String
Required: No
HttpExpiresDate
Type: Timestamp
Required: No

780
AWS S3 Control
RequesterCharged
Type: Boolean
Required: No
SSEAlgorithm
Type: String
Valid Values: AES256 | KMS
Required: No
UserMetadata
Type: String to string map
Key Length Constraints: Minimum length of 1. Maximum length of 1024.
Value Length Constraints: Maximum length of 1024.
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

781
AWS S3 Control
S3ObjectOwner
Contents
DisplayName
Type: String
Required: No
ID
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

782
AWS S3 Control
S3SetObjectAclOperation
Contains the configuration parameters for a Set Object ACL operation. Amazon S3 batch operations
passes each value through to the underlying PUT Object acl API. For more information about the
parameters for this operation, see PUT Object acl.
Contents
AccessControlPolicy
Type: S3AccessControlPolicy (p. 773) data type
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

783
AWS S3 Control
S3SetObjectTaggingOperation
Contains the configuration parameters for a Set Object Tagging operation. Amazon S3 batch operations
passes each value through to the underlying PUT Object tagging API. For more information about the
parameters for this operation, see PUT Object tagging.
Contents
TagSet
Type: Array of S3Tag (p. 785) data types
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

784
AWS S3 Control
S3Tag
Contents
Key
Type: String
Required: Yes
Value
Type: String
Length Constraints: Maximum length of 1024.
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

785

s3 Api

Uploaded by

Copyright:

Available Formats

s3 Api

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

s3 Api

Uploaded by

Copyright:

Available Formats

Amazon Simple Storage Service

Amazon Simple Storage Service: API Reference

API Version 2006-03-01

API Version 2006-03-01

DELETE Bucket replication ....................................................................................................... 121

API Version 2006-03-01

Description .................................................................................................................... 165

API Version 2006-03-01

Related Resources ........................................................................................................... 209

API Version 2006-03-01

Requests ........................................................................................................................ 240

API Version 2006-03-01

PUT PublicAccessBlock ............................................................................................................ 302

API Version 2006-03-01

Requests ........................................................................................................................ 341

API Version 2006-03-01

Description .................................................................................................................... 389

API Version 2006-03-01

Request Syntax .............................................................................................................. 450

API Version 2006-03-01

Related Actions .............................................................................................................. 527

API Version 2006-03-01

Amazon S3 REST API Introduction

Amazon S3 supports the REST API.

Requests to Amazon S3 can be authenticated or anonymous. Authenticated access requires credentials

API Version 2006-03-01

Common Request Headers

Header Name Description

Authorization The information required for request authentication. For more

Content-Length Length of the message (without the headers) according to RFC

Valid Values: 100-continue

Host For path-style requests, the value is s3.amazonaws.com.

x-amz-content-sha256 When using signature version 4 to authenticate request, this

API Version 2006-03-01

Header Name Description

x-amz-security-token This header can be used in the following scenarios:

• Provide security tokens for Amazon DevPay operations -

API Version 2006-03-01

Common Response Headers

Content-Length The length in bytes of the body in the response.

Connection speciﬁes whether the connection to the server is open or closed.

Valid Values: open | close

• Objects created by the PUT Object, POST Object, or Copy operation, or

Server The name of the server that created the response.

API Version 2006-03-01

Valid Values: true | false

Valid Values: null | any URL-ready, UTF-8 encoded string

API Version 2006-03-01

REST Error Responses

<?xml version="1.0" encoding="UTF-8"?>

The following table explains the REST error response elements.

Error Container for all error elements.

API Version 2006-03-01

RequestId ID of the request associated with the error.

Resource The bucket or object that is involved in the error.

For information about general response elements, go to Error Responses.

List of Error Codes

Error Code Description HTTP SOAP

AccessDenied Access Denied 403 Client