All Documents
Current Document

Content is empty

If you don't find the content you expect, please try another search term

Documentation

PUT Object ACL

Last updated:2021-09-14 16:18:12

Description

This PUT operation uses a subset of acl to set access control permissions (ACL) for existing and object in bucket.

Only the bucket owner can call the interface.

You can set permissions on objects in two ways.

  • Specify ACL in the request body.
  • Use the request header to set access rights.

Attention The above two methods cannot be used at the same time.

Request

Syntax

The following shows how to set by specifying ACL in the request body.

PUT /{ObjectKey}?acl HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}

<AccessControlPolicy>
<Owner>
<ID>{Base64EncodeUserId}</ID>
<DisplayName>{Base64EncodeUserId}</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
<ID>{Base64EncodeUserId}</ID>
<DisplayName>{Base64EncodeUserId}</DisplayName>
</Grantee>
<Permission>{Permission}</Permission>
</Grant>
...
</AccessControlList>
</AccessControlPolicy>

Attention:

Request Parameters

The interface does not use request parameters.

Request Headers

This interface can use all common request headers. For more information, please click Public Request Headers. The user can set the default ACL for the Object through the following header

Name Description Required
x-kss-acl Predefined permissions for the object.
Type:String
Default:private
Valid Value:private public-read
Constraints:None
No

If the user expects to set the detailed ACL for the Object, the following header settings can be used

Name Description Required
x-kss-grant-read Grant READ permission to several users.
Type:String
Default:None
Constraints:None
No
x-kss-grant-full-control Grant FULL_CONTROL permission to several users.
Type:String
Default:None
Constraints:None
No

The value of the above header value is a comma "," separated authorization list. The format of each authorization information is type = value. The current type supports ID:

  • ID: user ID of the authorized person

For example, to grant READ permission to two users with ID 1234578 and 3344211: x-kss-grant- read: id="1234578",id="3344211"

Request Elements

If the user decides to use the request body to specify the access list, the following table element is required.

Attention If you use the request body to set ACL, you can no longer set ACL through the request header

Name Description
AccessControlList Container containing Grant,Grantee,Permission
Type:Container
Ancestors:AccessControlPolicy
AccessControlPolicy Contains the ACL permission setting information of each Grantee for an object
Type:Container
Ancestors:None
Grant Contains information about authorized persons and their permissions.Refer to the way of granting authority
Type:String
Ancestors:AccessControlPolicy.AccessControlList
Grantee Authorized person
Type:String
Ancestors:AccessControlPolicy.AccessControlList.Grant
DisplayName Bucket owner's name
Type:String
Ancestors:AccessControlPolicy.Owner
ID The user ID of the bucket owner or the ID of the authorized person
Type:String
Ancestors:AccessControlPolicy.Owner or AccessControlPolicy.AccessControlList.Grant
Owner Container containing bucket owner information (DisplayName,ID)
Type:Container
Ancestors:AccessControlPolicy
Permission Indicates the permission information granted to the authorized person(FULL_CONTROL,READ,WRITE
Type:String
Ancestors:AccessControlPolicy.AccessControlList.Grant

How to Grant Permission

Users can grant a user permission to the user space in the following ways.

Specific user rights are granted based on user ID

{Base64EncodeUserId}{Base64EncodeUserId}

Response

Response Headers

This interface can use all common response headers. For more information, please click Public Response Headers.

Response Elements

The interface does not return the corresponding content.

Special Errors

The interface does not return any special errors.

Examples

Sample Request

PUT /my-image.jpg ?acl HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Content-Length: 1660
Date: Fri, 26 Dec 2014 06:34:32 GMT
Authorization: authorization string

<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Owner>
<ID>73410125</ID>
<DisplayName>ks3@kingsoft.com</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
<ID>73404060</ID>
<DisplayName>ks3_dt@kingsoft.com</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
<ID>73406240</ID>
<DisplayName>ks3_op@kingsoft.com</DisplayName>
</Grantee>
<Permission xmlns="">READ</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

Sample Response

HTTP/1.1 200 OK
Date: Fri, 26 Dec 2014 06:34:32 GMT
x-kss-request-id: dbea4ce4ec23415b9e454ecfa25ec4d9
Content-Length: 0
Server: Tengine

Interface Detail Analysis

  • Refer to the permission meaning of object for details ACL
  • When ACL is set in the header and body at the same time, only those in the header will take effect. When both x-kss-acl and x-kss-grant - \ * are set in the header, the latter takes effect.
  • For most users, using x-kss-acl to set the preset ACL in the header can meet most requirements.
On this page
Pure ModeNormal Mode

Pure Mode

Click to preview the document content in full screen
Feedback