Amazon Simple Storage Service API Reference

357 Pages·2014·2.36 MB·English

Amazon Simple Storage Service
API Reference
API Version 2006-03-01
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service: API Reference
Copyright © 2014 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
The following are trademarks of Amazon Web Services, Inc.: Amazon, Amazon Web Services Design, AWS, Amazon CloudFront,
Cloudfront, Amazon DevPay, DynamoDB, ElastiCache, Amazon EC2, Amazon Elastic Compute Cloud, Amazon Glacier, Kindle, Kindle
Fire, AWS Marketplace Design, Mechanical Turk, Amazon Redshift, Amazon Route 53, Amazon S3, Amazon VPC. In addition,
Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in
the U.S. and/or other countries. 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.
Amazon Simple Storage Service API Reference
Table of Contents
Welcome to Amazon S3 ................................................................................................................. 1
How Do I...? ......................................................................................................................... 1
Introduction .................................................................................................................................. 2
Error Responses ........................................................................................................................... 3
List of Error Codes................................................................................................................. 3
REST Error Responses.......................................................................................................... 9
REST API .................................................................................................................................. 11
Common Request Headers ................................................................................................... 12
Common Response Headers................................................................................................. 14
Authenticating Requests (AWS Signature Version 4).................................................................. 15
Authentication Methods ................................................................................................ 16
Introduction to Signing Requests.................................................................................... 16
Using an Authorization Header....................................................................................... 17
Using Query Parameters............................................................................................... 38
Examples: Signature Calculations................................................................................... 43
Authenticating HTTP POST Requests............................................................................. 45
Amazon S3 Signature Version 4 Authentication Specific Policy Keys..................................... 47
Browser-Based Uploads Using POST ..................................................................................... 51
Calculating a Signature ................................................................................................ 52
Creating HTML Forms ................................................................................................. 52
Creating a POST Policy................................................................................................ 56
Upload Examples ........................................................................................................ 61
Additional Considerations.............................................................................................. 64
Operations on the Service..................................................................................................... 65
GET Service............................................................................................................... 65
Operations on Buckets.......................................................................................................... 68
DELETE Bucket .......................................................................................................... 69
DELETE Bucket cors.................................................................................................... 71
DELETE Bucket lifecycle............................................................................................... 73
DELETE Bucket policy.................................................................................................. 75
DELETE Bucket tagging ............................................................................................... 77
DELETE Bucket website ............................................................................................... 79
GET Bucket (List Objects)............................................................................................. 81
GET Bucket acl ........................................................................................................... 89
GET Bucket cors ......................................................................................................... 92
GET Bucket lifecycle .................................................................................................... 95
GET Bucket policy...................................................................................................... 101
GET Bucket location................................................................................................... 103
GET Bucket logging.................................................................................................... 105
GET Bucket notification............................................................................................... 108
GET Bucket tagging ................................................................................................... 111
GET Bucket Object versions ........................................................................................ 114
GET Bucket requestPayment ....................................................................................... 126
GET Bucket versioning................................................................................................ 128
GET Bucket website................................................................................................... 131
HEAD Bucket ............................................................................................................ 133
List Multipart Uploads................................................................................................. 135
PUT Bucket .............................................................................................................. 144
PUT Bucket acl.......................................................................................................... 150
PUT Bucket cors........................................................................................................ 157
PUT Bucket lifecycle................................................................................................... 162
PUT Bucket policy...................................................................................................... 171
PUT Bucket logging.................................................................................................... 173
PUT Bucket notification............................................................................................... 178
PUT Bucket tagging.................................................................................................... 182
API Version 2006-03-01
iii
Amazon Simple Storage Service API Reference
PUT Bucket requestPayment ....................................................................................... 185
PUT Bucket versioning................................................................................................ 187
PUT Bucket website ................................................................................................... 191
Operations on Objects ........................................................................................................ 198
DELETE Object ......................................................................................................... 200
Delete Multiple Objects ............................................................................................... 203
GET Object............................................................................................................... 212
GET Object ACL........................................................................................................ 222
GET Object torrent..................................................................................................... 226
HEAD Object ............................................................................................................ 228
OPTIONS object........................................................................................................ 235
POST Object............................................................................................................. 238
POST Object restore .................................................................................................. 247
PUT Object............................................................................................................... 250
PUT Object acl.......................................................................................................... 262
PUT Object - Copy..................................................................................................... 269
Initiate Multipart Upload .............................................................................................. 282
Upload Part .............................................................................................................. 290
Upload Part - Copy..................................................................................................... 295
Complete Multipart Upload .......................................................................................... 302
Abort Multipart Upload................................................................................................ 308
List Parts.................................................................................................................. 310
Resources ................................................................................................................................ 315
Document History ...................................................................................................................... 317
Appendix .................................................................................................................................. 323
Operations on the Service................................................................................................... 323
ListAllMyBuckets........................................................................................................ 323
Operations on Buckets........................................................................................................ 325
CreateBucket ............................................................................................................ 325
DeleteBucket............................................................................................................. 326
ListBucket................................................................................................................. 327
GetBucketAccessControlPolicy..................................................................................... 330
SetBucketAccessControlPolicy ..................................................................................... 331
GetBucketLoggingStatus ............................................................................................. 332
SetBucketLoggingStatus ............................................................................................. 333
Operations on Objects ........................................................................................................ 334
PutObjectInline .......................................................................................................... 334
PutObject ................................................................................................................. 336
CopyObject............................................................................................................... 338
GetObject ................................................................................................................. 342
GetObjectExtended .................................................................................................... 347
DeleteObject ............................................................................................................. 348
GetObjectAccessControlPolicy ..................................................................................... 348
SetObjectAccessControlPolicy ..................................................................................... 349
SOAP Error Responses ...................................................................................................... 350
Glossary .................................................................................................................................. 352
API Version 2006-03-01
iv
Amazon Simple Storage Service API Reference
How Do I...?
Welcome to Amazon S3
This is the Amazon Simple Storage Service API Reference. It explains the Amazon Simple Storage Service
(Amazon S3) application programming interface. It describes various API operations, related request and
response structures, and error codes.
Amazon S3 is a web service that enables you to store data in the cloud.You can then download the data
or use the data with other AWS services, such as Amazon Elastic Compute Cloud (Amazon EC2). For
information about Amazon EC2, see Amazon EC2).
How Do I...?
Information Relevant Sections
General product overview and pricing Amazon Simple Storage Service (Amazon S3)
List of REST operations REST API (p.11)
List of SOAP operations Appendix: SOAP API (p.323)
Amazon S3 error codes and descriptions List of Error Codes (p.3)
API Version 2006-03-01
1
Amazon Simple Storage Service API Reference
Amazon S3 API Reference
Introduction
This application programming interface reference explains Amazon S3 operations, their parameters, re-
sponses, and errors.There are separate sections for the REST and SOAP APIs, which include example
requests and responses.
The location of the latest Amazon S3 WSDL is http://doc.s3.amazonaws.com/2006-03-01/AmazonS3.wsdl.
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
API Version 2006-03-01
2
Amazon Simple Storage Service API Reference
List of Error Codes
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
• List of Error Codes (p.3)
• REST Error Responses (p.9)
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
use Contact Us.
AmbiguousGrantByEmailAddress The email address you provided is 400 Bad Client
associated with more than one Request
account.
BadDigest The Content-MD5 you specified did 400 Bad Client
not match what we received. Request
API Version 2006-03-01
3
Amazon Simple Storage Service API Reference
List of Error Codes
Error Code Description HTTP SOAP
Status Fault
Code Code
Prefix
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 Your previous request to create the 409 Client
named bucket succeeded and you Conflict (in
already own it.You get this error in all all regions
AWS regions except US Standard, except US
us-east-1. In us-east-1 region, you will Standard).
get 200 OK, but it is no-op (if bucket
exists it Amazon S3 will not do
anything).
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
IllegalVersioningConfigurationException Indicates that the versioning 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
IncorrectNumberOfFilesInPostRequest POST requires exactly one file upload 400 Bad Client
per request. Request
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
API Version 2006-03-01
4
Amazon Simple Storage Service API Reference
List of Error Codes
Error Code Description HTTP SOAP
Status Fault
Code Code
Prefix
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 not 400 Bad Client
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 not Request
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 specified in order Request
by part number.
InvalidPayer All access to this object has been 403 Client
disabled. Forbidden
InvalidPolicyDocument The content of the form does not meet 400 Bad Client
the conditions specified in the policy Request
document.
InvalidRange The requested range cannot be 416 Client
satisfied. Requested
Range Not
Satisfiable
InvalidRequest SOAP requests must be made over 400 Bad Client
an HTTPS connection. Request
InvalidSecurity The provided security credentials are 403 Client
not valid. Forbidden
API Version 2006-03-01
5
Amazon Simple Storage Service API Reference
List of Error Codes
Error Code Description HTTP SOAP
Status Fault
Code Code
Prefix
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 not 400 Bad Client
exist, is not owned by you, or does not Request
have the appropriate grants for the
log-delivery group.
InvalidToken The provided token is malformed or 400 Bad Client
otherwise invalid. Request
InvalidURI Couldn't parse the specified URI. 400 Bad Client
Request
KeyTooLong Your key is too long. 400 Bad Client
Request
MalformedACLError The XML you provided was not 400 Bad Client
well-formed or did not validate against Request
our 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
MaxPostPreDataLengthExceededError Your 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
API Version 2006-03-01
6