All Products
Search
Document Center

Object Storage Service:PutObjectACL

Last Updated:Apr 28, 2024

You can call this operation to modify the access control list (ACL) of an object. Only the bucket owner that has permissions to read and write objects in the bucket can call this operation to modify object ACLs.

Versioning

By default, the PutObjectACL operation is called to configure the ACL of the current version of an object. You can specify a version ID in the request to configure the ACL of the specified version of an object.

  • If you specify a version ID in the request and the version of the associated object is a delete marker, OSS returns the 405 MethodNotAllowed error.

  • If you do not specify a version ID in the request and the latest version of the associated object is a delete marker, OSS returns the 404 NoSuchKey error.

ACL overview

When you call the PutObjectACL operation, you can set the x-oss-object-acl header in the request to configure the ACL of an object. The following table describes the ACLs that you can configure for an object.

ACL

Description

private

The object is a private resource. Only the owner of the object has permissions to read and write the object. Other users cannot access the object.

public-read

The object is a public-read resource. Only the owner of the object has permissions to read and write this object. Other users can only read the object.

public-read-write

The object is a public-read-write resource. All users have permissions to read and write the object.

default

The ACL of the object is the same as that of the bucket in which the object is stored.

Note
  • The ACL of an object takes precedence over the ACL of the bucket in which the object is stored. For example, if an object whose ACL is public-read-write is stored in a bucket whose ACL is private, all users can read and write the object. By default, if you do not configure the ACL of an object, the ACL of the object is the same as the ACL of the bucket in which the object is stored.

  • Operations that read objects include GetObject, HeadObject, CopyObject, and UploadPartCopy, in which CopyObject and UploadPartCopy read the source object. Operations that write objects include PutObject, PostObject, AppendObject, DeleteObject, DeleteMultipleObjects, CompleteMultipartUpload, and CopyObject, in which CopyObject writes the destination object.

  • When you call operations to write an object, you can also include the x-oss-object-acl header in the request to configure the ACL of the object. For example, you can include the x-oss-object-acl header in a PutObject request to configure the ACL of the object to upload.

Request structure

PUT /ObjectName?acl HTTP/1.1
x-oss-object-acl: Permission
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

Header

Type

Required

Example

Description

x-oss-object-acl

String

Yes

public-read

The access control list (ACL) of the object.

Valid values:

  • default (default): The ACL of the object is the same as that of the bucket in which the object is stored.

  • private: The ACL of the object is private. Only the owner of the object and authorized users have the read and write permissions on the object.

  • public-read: The ACL of the object is public-read. Only the owner of the object and authorized users have the read and write permissions on the object. Other users have only the read permissions on the object. Exercise caution when you use this ACL.

  • public-read-write: The ACL of the object is public-read-write. All users have the read and write permissions on the object. Exercise caution when you use this ACL.

For more information, see Object ACLs.

For more information about the common request headers in a PutObjectACL request, such as Host and Date, see Common request headers.

Response headers

This request contains only common response headers. For more information, see Common HTTP headers.

Examples

  • Modify the ACL of an object in an unversioned bucket

    Sample request

    PUT /test-object?acl HTTP/1.1
    x-oss-object-acl: public-read
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Wed, 29 Apr 2015 05:21:12 GMT
    Authorization: OSS qn6q**************:77Dv****************

    Sample response

    HTTP/1.1 200 OK
    x-oss-request-id: 559CC9BDC755F95A64485981
    Date: Wed, 29 Apr 2015 05:21:12 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: AliyunOSS
  • Modify the ACL of an object in a versioned bucket

    Sample request

    PUT /example?acl&versionId=CAEQMhiBgIC3rpSD0BYiIDBjYTk5MmIzN2JlNjQxZTFiNGIzM2E3OTliODA0**** HTTP/1.1
    x-oss-object-acl: public-read
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 06:30:11 GMT
    Authorization: OSS qn6q**************:77Dv****************

    Sample response

    HTTP/1.1 200 OK
    x-oss-version-id: CAEQMhiBgIC3rpSD0BYiIDBjYTk5MmIzN2JlNjQxZTFiNGIzM2E3OTliODA0****
    x-oss-request-id: 5CAC3BF3B7AEADE017000624
    Date: Tue, 09 Apr 2019 06:30:11 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: AliyunOSS

SDK

You can use OSS SDKs for the following programming languages to call the PutObjectACLoperation:

Error codes

Error code

HTTP status code

Description

AccessDenied

403

You are not the bucket owner or do not have permissions to read and write the object whose ACL you want to modify.

InvalidArgument

400

The specified x-oss-object-acl value is invalid.

FileAlreadyExists

409

The object whose ACL you want to modify is a directory in a bucket for which the hierarchical namespace feature is enabled.