Interface Description

This command allows you to set the permission of access to an object. At present, you can set the ACL for BOS in two ways. The first method is to use the Canned ACL. The object access control is set through "x-bce-acl" or "x-bce-grant-permission" in the header field during PutObjectAcl. At present, the settable access control includes private and public-read. Two types of headers cannot appear in a request at the same time. The second method is to upload an ACL file. For the file format, see ACL File Format. At present, the ACL file only supports accessControlList, grantee, id, and permission fields.

At present, you cannot set Canned ACL and upload the ACL file in the same request.

Request

• ACL file request syntax

  PUT /<ObjectKey>?acl HTTP/1.1
  Host: <BucketName>.bj.bcebos.com
  x-bce-date: <Date>
  Authorization: <AuthorizationString>
  Content-Type: application/json; charset=utf-8
  Content-Length: <ContentLength>

• Canned ACL file request syntax (Set x-bce-acl)

   PUT /<ObjectKey>?acl HTTP/1.1
   Host: <BucketName>.bj.bcebos.com
   x-bce-date: <Date>
   Authorization: <AuthorizationString>
   x-bce-acl: <ObjectAcl>
   Content-Length: <ContentLength>
   Content-Type: application/json; charset=utf-8

• Canned ACL file request syntax (set x-bce-grant-permission)

  PUT /<ObjectKey>?acl HTTP/1.1
  Host: <BucketName>.bj.bcebos.com
  x-bce-date: <Date>
  Authorization: <AuthorizationString>
  x-bce-grant-read: <ObjectGrantRead>
  Content-Length: <ContentLength>
  Content-Type: application/json; charset=utf-8

• Request header field

  Name	Type	Description	Required?
  x-bce-acl	String	ACL set for the object, which can be private and public-read.	No
  x-bce-grant-read	String	Object ID authorized to read, which supports multiple IDs separated by commas.	No
  x-bce-grant-full-control	String	Object ID with the control permission granted, which supports multiple IDs separated by commas.	No

  Considerations

  • Only the bucket owner and the user with the FULL_CONTROL permission can set the object ACL.
  • The object ACL is empty by default during the object upload. If failed to set the object ACL, that is, when the object ACL is empty, the bucket ACL should prevail by default.
  • When the object ACL is not consistent with the bucket ACL, the object ACL should prevail.
  • The object ACL cannot be setted (set) when the archive storage object is not restored or the archive file is just uploaded. For the duration, see the retrieval duration.

• Request parameters

  No special parameters.

Response

• Response header field

  No special parameters.

• Response parameters

  None

Example

• ACL file request example

   PUT /ObjectName?acl HTTP/1.1
   Host: BucketName.bj.bcebos.com
   x-bce-date: 2017-05-01T12:23:49Z
   Authorization: AuthorizationString
   Content-Type: application/json; charset=utf-8
   Content-Length: 315
  
   {
       "accessControlList":[
       {
           "grantee":[{
               "id":"e13b12d0131b4c8bae959df4969387b8"
           }],
           "permission":["READ"]
       }
       ]
   }

• Canned ACL request example (Set x-bce-acl)

  PUT /ObjectName?acl HTTP/1.1
  Host: BucketName.bj.bcebos.com
  x-bce-date: 2017-05-01T12:23:49Z
  Authorization: AuthorizationString
  x-bce-acl: public-read
  Content-Length: 0
  Content-Type: application/json; charset=utf-8

• Canned ACL request example (Set x-bce-grant-permission)

  PUT /ObjectName?acl HTTP/1.1
  Host: BucketName.bj.bcebos.com
  x-bce-date: 2017-05-01T12:23:49Z
  Authorization: AuthorizationString
  x-bce-grant-read:id="e13b12d0131b4c8bae959df4969387b8",id="8c47a952db4444c5a097b41be3f24c94"
  Content-Length: 0
  Content-Type: application/json; charset=utf-8

• Response example

  HTTP/1.1 200 OK
  Date: Wed, 01 Mar 2017 12:25:00 GMT
  Content-Length: 0
  Server: BceBos
  x-bce-request-id:413e34fd-118d-4049-b992-1b1f3a68b1f5