PUT Object acl
Description
This implementation of the PUT
operation uses the acl
sub-resource to set the access control list (ACL) permissions for
an object that already exists in a bucket. (To set the ACL of an object when you put it
into a bucket, use the x-amz-acl
request header.) You must have
WRITE_ACP permission to set the ACL of an object.
Versioning
The ACL of an object is set at the object version level. By default, PUT
sets the ACL of the latest version of an object. To set the ACL of a
different version, use the versionId
sub-resource.
To see sample requests that use versioning, see
Requests
Syntax
PUT /ObjectName
?acl HTTP/1.1 Host:BucketName
.s3.amazonaws.com Date:date
Authorization:signatureValue
<AccessControlPolicy> <Owner> <ID>ID
</ID> <DisplayName>EmailAddress
</DisplayName> </Owner> <AccessControlList> <Grant> <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"> <ID>ID
</ID> <DisplayName>EmailAddress
</DisplayName> </Grantee> <Permission>Permission
</Permission> </Grant> </AccessControlList> </AccessControlPolicy>
Request Parameters
This implementation of the operation does not use 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. For more information, see Common Request Headers.
Name | Description | Required |
---|---|---|
Cache-Control
|
Can be used to specify caching behavior along the request/reply chain. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9. Type: String Default: None Constraints: None |
No |
Content-Disposition
|
Specifies presentational information for the object. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1. Type: String Default: None Constraints: None |
No |
Content-Encoding
|
Specifies what content encodings have been applied to the
object and thus what decoding mechanisms must be applied to obtain
the media-type referenced by the Type: String Default: None Constraints: None |
No |
Content-Length
|
The size of the object, in bytes. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13. Type: String Default: None Constraints: None |
Yes |
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 . Type: String Default: None Constraints: None |
No |
Content-Type
|
A standard MIME type describing the format of the contents. For 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 |
No |
Expect
|
When your application uses 100-continue, it does not send the request body until it receives an acknowledgement. If the message is rejected based on the headers, the body of the message is not sent. Type: String Default: None Valid Values: 100-continue Constraints: None |
No |
Expires
|
Number of milliseconds before expiration Type: Int Default: None Constraints: None |
No |
x-amz-acl
|
The canned ACL to apply to the object. For more information, go to REST Access Policy in the Amazon Simple Storage Service Developer Guide . Type: String Default: private Valid Values: private | public-read | public-read-write | authenticated-read | bucket-owner-read | bucket-owner-full-control Constraints: None |
No |
x-amz-meta-
|
Any header starting with this prefix is considered user metadata. It will be stored with the object and returned when you retrieve the object. The total size of the HTTP request, not including the body, must be less than 8 KB. Type: String Default: None Constraints: None |
No |
Request Elements
You use the following parameters in the body of a GET
request
to set ACL permissions for a grantee.
Name | Description |
---|---|
AccessControlList |
Container for ACL information Type: Container Ancestors: AcessControlPolicy |
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 Type: String Ancestors: AcessControlPolicy.Owner |
Grant |
Container for the grantee and his or her permissions Type: Container Ancestors: AcessControlPolicy.AccessControlList |
Grantee |
The subject whose permissions are being set. Type: String Valid Values: DisplayName | EmailAddress | AuthenticatedUser. For more information, see Grantee Values. Ancestors: AcessControlPolicy.AccessControlList.Grant |
ID |
ID of the bucket owner, or the ID of the grantee Type: String Ancestors: AcessControlPolicy.Owner or AcessControlPolicy.AccessControlList.Grant |
Owner |
Container for the bucket owner's display name and ID Type: Container Ancestors: AcessControlPolicy |
Permission |
Specifies the permission given to the grantee Type: String Valid Values: FULL_CONTROL | WRITE | WRITE_ACP | READ | READ_ACP Ancestors: AcessControlPolicy.AccessControlList.Grant |
Grantee Values
You can specify the person (grantee) that you're assigning access rights to (using request elements) in the following ways:
-
By the person's ID:
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"> <ID>
ID
</ID> <DisplayName>GranteesEmail
</DisplayName> </Grantee>DisplayName
is optional and ignored in the request. -
By E-mail address:
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail"> <EmailAddress>
[email protected]
</EmailAddress> </Grantee>The grantee is resolved to the
CanonicalUser
and in a response to aGET Object acl
request appears as theCanonicalUser
. -
By URI:
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"> <URI>
http://acs.amazonaws.com/groups/global/AuthenticatedUsers
<URI> </Grantee>
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.
Name | Description |
---|---|
x-amz-version-id |
Version of the object whose ACL is being set. Type: String Default: None |
Response Elements
This implementation of the operation does not return response elements.
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.
Examples
Sample Request
The following request sets the ACL on the specified object.
PUT /my-image.jpg?acl HTTP/1.1 Host: bucket.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 GMT Authorization: AWS 02236Q3V0WHVSRW0EXG2:0RQf4/cRonhpaBX5sCYVf1bNRuU= Content-Length: 124 <AccessControlPolicy> <Owner> <ID>8a6925ce4adf588e97f21c32aa379004fef</ID> <DisplayName>[email protected]</DisplayName> </Owner> <AccessControlList> <Grant> <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"> <ID>8a6925ce4adf588a45379004fef</ID> <DisplayName>[email protected]</DisplayName> </Grantee> <Permission>FULL_CONTROL</Permission> </Grant> </AccessControlList> </AccessControlPolicy>
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-request-id: 318BC8BC148832E5 x-amz-version-id: 3/L4kqtJlcpXrof3vjVBH40Nr8X8gdRQBpUMLUo Date: Wed, 28 Oct 2009 22:32:00 GMT Last-Modified: Sun, 1 Jan 2006 12:00: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 Host: bucket.s3.amazonaws.com Date: Wed, 28 Oct 2009 22:32:00 GMT Authorization: AWS 02236Q3V0WHVSRW0EXG2:0RQf4/cRonhpaBX5sCYVf1bNRuU= Content-Length: 124 <AccessControlPolicy> <Owner> <ID>8a6925ce4adf5f21c32aa379004fef</ID> <DisplayName>[email protected]</DisplayName> </Owner> <AccessControlList> <Grant> <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"> <ID>8a6925ce4adf588a4532142d3f74dd8c71fa124b1ddee97f21c32aa379004fef</ID> <DisplayName>[email protected]</DisplayName> </Grantee> <Permission>FULL_CONTROL</Permission> </Grant> </AccessControlList> </AccessControlPolicy>
Sample Response
HTTP/1.1 200 OK x-amz-id-2: eftixk72aD6Ap51u8yU9AS1ed4OpIszj7UDNEHGran x-amz-request-id: 318BC8BC148832E5 x-amz-version-id: 3/L4kqtJlcpXro3vjVBH40Nr8X8gdRQBpUMLUo Date: Wed, 28 Oct 2009 22:32:00 GMT Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT Content-Length: 0 Connection: close Server: AmazonS3