To change the ACLs on an object you make a PUT
request that is scoped to the bucket and object and you use the
acl
query string parameter. You must also include an XML document
in the request body that contains the ACL settings you want to apply.
You can also specify ACLs when you upload an object. To do this you can use the
x-goog-acl
request header. When you use the x-goog-acl
request header you can apply one of the predefined ACLs. If you
don't use the x-goog-acl
request header when you upload an object,
the default ACL (private) is applied to the object.
Keep in mind, a bucket's ACLs determines whether a user has permission to
upload objects into the bucket. If a bucket grants WRITE
permission to anonymous users, then users can upload objects without
authenticating. Otherwise, all upload requests must be authenticated and only
those users with WRITE
permission can upload objects into a
bucket.
You must have FULL_CONTROL
permission to apply ACLs to an existing
object.
Query string parameters
Parameter | Description | Required |
---|---|---|
acl |
Scopes the request to ACL changes only. You can use this only if you are using the PUT Object method to change ACLs on an existing object. You must specify the ACLs in an XML document in the request body. | No |
generation |
Specifies the generation to update ACLs for. You can use this only if you are using the PUT Object method to change ACLs on an existing object. You must specify the ACLs in an XML document in the request body. | No |
See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.
Request headers
Request body elements
The following request body elements are applicable only if you use the
acl
query string parameter to apply ACLs to an existing object.
Element | Description |
---|---|
Owner |
Container for object owner information. |
ID |
The Cloud Storage ID of the object owner or the Cloud Storage ID of the user or group for whom the ACLs are being applied. |
Name |
Comment field for GroupByEmail , GroupById , UserByEmail , and UserById . If you do not specify anything in Name when you apply an ACL, the Cloud Storage system populates this field with the email address you specified in EmailAddress . |
AccessControlList |
Container for the ACLs you are applying. |
Entries |
Container for the ACL entries you are applying. |
Entry |
The ACL entry you are applying. |
Scope |
The scope to which the ACLs apply. |
Permission |
The permission you are granting. Can be any of the Cloud Storage permissions, including READ , WRITE , or FULL_CONTROL |
EmailAddress |
A user account email address or a Google group email address. |
Domain |
A Google Workspace or Cloud Identity domain. |
Request syntax
The following syntax applies to PUT Object requests that use the
acl
query string parameter.
PUT /OBJECT_NAME?acl HTTP/1.1 Host: BUCKET_NAME.storage.googleapis.com Date: DATE Content-Length: REQUEST_BODY_LENGTH Content-Type: MIME_TYPE Authorization: AUTHENTICATION_STRING XML_DOCUMENT_DEFINING_ACLS
The following syntax applies to conditional PUT Object requests that use the
acl
query string parameter as well as generation
and
metageneration
.
PUT /object?acl HTTP/1.1 Host: bucket.storage.googleapis.com Date: DATE Content-Length: REQUEST_BODY_LENGTH Content-Type: MIME_TYPE Authorization: AUTHENTICATION_STRING x-goog-if-generation: GENERATION_NUMBER x-goog-if-metageneration: META_GENERATION_NUMBER XML_DOCUMENT_DEFINING_ACLS
The following syntax applies to conditional PUT Object for a history object
that use the acl
query string parameter as well as
generation
and metageneration
.
PUT /object?acl&generation=136088769710500 HTTP/1.1 Host: bucket.storage.googleapis.com Date: DATE Content-Length: REQUEST_BODY_LENGTH Content-Type: MIME_TYPE Authorization: AUTHENTICATION_STRING x-goog-if-metageneration: META_GENERATION_NUMBER XML_DOCUMENT_DEFINING_ACLS
Response headers
The request can return a variety of response headers depending on the request headers you use.
Response body elements
The response does not include an XML document in the response body.
Example
The following sample applies ACLs to the london.jpg
object, which is stored in
the travel-maps
bucket. The ACLs grant jane@example.com FULL_CONTROL
permission, which lets Jane download london.jpg
and change the ACLs on
london.jpg
. The ACLs also grant members of the
Cloud Storage group READ
permission to london.jpg
, which lets
each member of the group download london.jpg
.
Request
PUT /london.jpg?acl HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Sat, 20 Feb 2010 17:08:44 GMT Content-Length: 682 Content-Type=application/xml; charset=UTF-8 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg <?xml version="1.0" encoding="UTF-8"?> <AccessControlList> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <Name></Name> </Owner> <Entries> <Entry> <Scope type="UserById"> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <Name></Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="UserByEmail"> <EmailAddress>jane@example.com</EmailAddress> <Name></Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="GroupByEmail"> <EmailAddress>gs-discussion@googlegroups.com</EmailAddress> </Scope> <Permission>READ</Permission> </Entry> </Entries> </AccessControlList>
Response
HTTP/1.1 200 OK Date: Sat, 20 Feb 2010 17:08:45 GMT Content-Length: 0 Content-Type: text/html