Access Control List (ACL)

cos.putBucketAcl({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   ACL: 'public-read'
}, function(err, data) {
   console.log(err || data);
});

Grant a user full permission for a bucket:

cos.putBucketAcl({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   GrantFullControl: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000011:uin/100000000011"' // 100000000001 is uin.
}, function(err, data) {
   console.log(err || data);
});

Modify bucket permission with AccessControlPolicy:

cos.putBucketAcl({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   AccessControlPolicy: {
       "Owner": { // `Owner` is required in `AccessControlPolicy`.
           "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the UIN of the bucket owner
       },
       "Grants": [{
           "Grantee": {
               "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is UIN
           },
           "Permission": "WRITE"
       }]
   }
}, function(err, data) {
   console.log(err || data);
});

Parameter description

Parameter	Description	Type	Required
Bucket	Bucket name in the format: `BucketName-APPID`	String	Yes
Region	Bucket region. For the enumerated values, please see Regions and Access Endpoints.	String	Yes
ACL	Defines the access control list (ACL) attribute of the bucket. For the enumerated values, such as `private` (default) and `public-read`, please see the Preset ACL section in ACL Overview.	String	No
GrantRead	Grants a user read access in the format: id="[OwnerUin]". Use a comma (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<owneruin>:uin/<subuin>"`. To authorize a root account, use `id="qcs::cam::uin/<owneruin>:uin/<owneruin>"`. Examples: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
GrantWrite	Grants a user write access in the format: id="[OwnerUin]". Use a comma (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<owneruin>:uin/<subuin>"`. To authorize a root account, use `id="qcs::cam::uin/<owneruin>:uin/<owneruin>"`. Examples: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
GrantReadAcp	Grants a user read permission for bucket ACL and policies in the format: `id="[OwnerUin]"`. You can use commas (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<owneruin>:uin/<subuin>"`. To authorize a root account, use `id="qcs::cam::uin/<owneruin>:uin/<owneruin>"`. Example: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
GrantWriteAcp	Grants a user write permission for bucket ACL and policies in the format: `id="[OwnerUin]"`. You can use commas (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<owneruin>:uin/<subuin>"`. To authorize a root account, use `id="qcs::cam::uin/<owneruin>:uin/<owneruin>"`. Example: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
GrantFullControl	Grants full permission in the format: `id="[OwnerUin]"`. You can use commas (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<owneruin>:uin/<subuin>"`. To authorize a root account, use `id="qcs::cam::uin/<owneruin>:uin/<owneruin>"`. Example: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
AccessControlPolicy	A list of all the information about the CORS configuration	Object	No
- Owner	Object representing the bucket owner	Object	No
- - ID	Complete ID of the bucket owner in the format: `qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]`, such as `qcs::cam::uin/100000000001:uin/100000000001’, where 100000000001 is uin	String	No
- Grants	List of information on the authorized user and granted permissions	ObjectArray	No
- - Permission	Permission granted. Valid values: `READ`, `WRITE`, `READ_ACP`, `WRITE_ACP`, `FULL_CONTROL`. For the enumerated values, please see the Action permissions section in ACL Overview.	String	No
- - Grantee	Authorized user information	Object	No
- - - ID	Complete ID of the grantee in the format of `qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]` Example: `qcs::cam::uin/100000000001:uin/100000000001` where 100000000001 is the uin	String	No
- - - DisplayName	String representing the username, which is usually the same as the string you enter for `ID`	String	No
- - - URI	Preset user groups. For more information, see the `Identity (Grantee)` section in ACL Overview, such as `http://cam.qcloud.com/groups/global/AllUsers` or `http://cam.qcloud.com/groups/global/AuthenticatedUsers`	String	No

Callback function description

function(err, data) { ... }

Parameter Name	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object

Querying a bucket ACL

Feature description

This API (GET Bucket acl) is used to query the ACL of a bucket. To call this API, you need to have permission to read the ACL of the bucket.

Use case

cos.getBucketAcl({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
}, function(err, data) {
   console.log(err || data);
});

Sample response

{
  "GrantFullControl": "",
  "GrantWrite": "",
  "GrantRead": "",
  "GrantReadAcp": "id=\"qcs::cam::uin/100000000011:uin/100000000011\"",
  "GrantWriteAcp": "id=\"qcs::cam::uin/100000000011:uin/100000000011\"",
  "ACL": "private",
  "Owner": {
      "ID": "qcs::cam::uin/100000000001:uin/100000000001",
      "DisplayName": "qcs::cam::uin/100000000001:uin/100000000001"
  },
  "Grants": [{
      "Grantee": {
          "ID": "qcs::cam::uin/100000000011:uin/100000000011",
          "DisplayName": "qcs::cam::uin/100000000011:uin/100000000011"
      },
      "Permission": "READ"
  }],
  "statusCode": 200,
  "headers": {}
}

Parameter description

Parameter Name	Description	Type	Required
Bucket	Bucket name in the format: `BucketName-APPID`	String	Yes
Region	Bucket region. For the enumerated values, please see Regions and Access Endpoints.	String	Yes

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Returns headers	Object
data	Returns data when the request is successful. If the request fails, this is empty.	Object
- statusCode	Returns an HTTP status code, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
x-cos-acl	Defines the access control list (ACL) attribute of the bucket. For the enumerated values such as `private` and `public-read`, see the `Preset ACLs for buckets` section in ACL Overview. Default value: `private`	Enum
- GrantRead	ID information of the user granted read access	String
- GrantWrite	ID information of the user granted write access	String
- GrantReadAcp	ID information of the user granted read access to the ACL and Policies	String
- GrantWriteAcp	ID information of the user granted write access to the ACL and Policies	String
- GrantFullControl	ID information of the user granted full access	String
- Owner	Bucket owner information	Object
- - DisplayName	Bucket owner username	String
- - ID	Bucket owner ID in the format: `qcs::cam::uin/<owneruin>:uin/<subuin>`. For root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.	String
- Grants	List of information on the authorized user and granted permissions	ObjectArray
- - Permission	Specifies the permission granted to the user. Enumerated values: `READ`, `WRITE`, `READ_ACP`, `WRITE_ACP`, `FULL_CONTROL`	String
- - Grantee	Authorized user information	Object
- - - DisplayName	Authorized user’s username	String
- - - ID	User ID of the authorized user For root accounts, the format is `qcs::cam::uin/<owneruin>:uin/<owneruin>` or `qcs::cam::anyone:anyone` representing all users. For sub-accounts, the format is `qcs::cam::uin/<owneruin>:uin/<subuin>`	String
- - - URI	Preset user groups. For more information see the `Identity (Grantee)` section in ACL Overview, such as `http://cam.qcloud.com/groups/global/AllUsers` or `http://cam.qcloud.com/groups/global/AuthenticatedUsers`	String

Object ACLs

Setting object ACL

Feature description

This API (PUT Object acl) is used to set the ACL of an object in a bucket.

Note：

The total number of policies associated with bucket ACL, Policy, and CAM under a single root account (i.e., under the same APPID) cannot exceed 1,000. There is no upper limit on the number of object ACL rules. If you do not need access control for an object, do not make any configuration, and the object will inherit the permissions of its bucket.

Use case

cos.putObjectAcl({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   Key: 'exampleobject',              /* Required */
   ACL: 'public-read', /*Optional*/
}, function(err, data) {
   console.log(err || data);
});

Grant a user all permissions for an object:

cos.putObjectAcl({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   Key: 'exampleobject',              /* Required */
   GrantFullControl: 'id="100000000001"' // 100000000001 is the uin of the root account.
}, function(err, data) {
   console.log(err || data);
});

Grant the user permission to write the object via AccessControlPolicy:

cos.putObjectAcl({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   Key: 'exampleobject',              /* Required */
   AccessControlPolicy: {
       "Owner": { // `Owner` is required in `AccessControlPolicy`.
           "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the UIN of the bucket owner
       },
       "Grants": [{
           "Grantee": {
               "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is the UIN of the sub-account of the bucket owner
           },
           "Permission": "WRITE"
       }]
   }
}, function(err, data) {
   console.log(err || data);
});

Parameter description

Parameter	Description	Type	Required
Bucket	Bucket name, formatted as `BucketName-APPID`	String	Yes
Region	Bucket region. For the enumerated values, please see Regions and Access Endpoints.	String	Yes
Key	Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview	String	Yes
ACL	Defines the ACL attribute of the object. For the enumerated values, such as `default`, `private`, and `public-read`, please see the Preset ACL section in ACL Overview. Default value: `default` Note: If you do not need access control for the object, set `default` for this parameter or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.	String	No
GrantRead	Grants a user read permission for an object in the format: `id="[OwnerUin]"`. You can use commas (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/:uin/"`. To authorize a root account, use `id="qcs::cam::uin/:uin/"`. Example: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
GrantFullControl	Grants a user full access in the format: `id="[OwnerUin]"`. You can use commas (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/:uin/"`. To authorize a root account, use `id="qcs::cam::uin/:uin/"`. Example: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
AccessControlPolicy	Sets the object's ACL attributes.	Object	No
- Owner	Information about the object owner	Object	No
- - ID	ID of the object owner in the format: `qcs::cam::uin/<owneruin>:uin/<subuin>` For root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.	String	No
- - DisplayName	Name of the object owner	String	No
- Grants	A list of information about the grantee and granted permissions	ObjectArray	No
- - Permission	Permission granted. Enumerated values: `READ`, `WRITE`, `READ_ACP`, `WRITE_ACP`, `FULL_CONTROL`	String	No
- - Grantee	Information about the grantee	Object	No
- - - DisplayName	Name of the grantee	String	No
- - - ID	ID of the authorized user in the format: `qcs::cam::uin/<owneruin>:uin/<subuin>` For root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 204, 403, and 404	Number
- headers	Headers returned by the request	Object

Querying object ACL

Feature description

The API is used to query the ACL of an object. Only the owner of the bucket has the permission to use this API.

Use case

cos.getObjectAcl({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   Key: 'exampleobject',              /* Required */
}, function(err, data) {
   console.log(err || data);
});

Parameter description

Parameter	Description	Type	Required
Bucket	Bucket name, formatted as `BucketName-APPID`	String	Yes
Region	Bucket region. For the enumerated values, please see Regions and Access Endpoints.	String	Yes
Key	Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview.	String	Yes

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
- ACL	Defines the ACL attribute of the object. For the enumerated values, such as `default`, `private`, and `public-read`, please see the Preset ACL section in ACL Overview. Default value: `default` Note: If you do not need access control for the object, set `default` for this parameter or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.	String
- Owner	Owner of the resource	Object
- - ID	Object owner ID in the format of `qcs::cam::uin/<owneruin>:uin/<subuin>` For root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.	String
- - DisplayName	Object owner name	String
- Grants	List of information on the grantee and permissions	ObjectArray
- - Permission	Permission granted. Enumerated values: `READ`, `READ_ACP`, `WRITE_ACP`, `FULL_CONTROL`	String
- - Grantee	Grantee information	Object
- - - DisplayName	Name of the user	String
- - - ID	User ID in the format: `qcs::cam::uin/<owneruin>:uin/<subuin>` For root accounts, and have the same value.	String

Hubungi Kami

Hubungi tim penjualan atau penasihat bisnis kami untuk membantu bisnis Anda.

Dukungan Teknis

Buka tiket jika Anda mencari bantuan lebih lanjut. Tiket kami tersedia 7x24.

Dukungan Telepon 7x24

tencent cloud

Recent Pages