Setting a Bucket ACL (SDK for Java)
Function
Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over resources when a bucket or object is created. That is, the bucket creator has full control over the bucket, and the object uploader has full control over the object. Other accounts do not have the permissions to access resources. If resource owners want to grant other accounts the read and write permissions on resources, they can use ACLs. ACLs grant permissions to accounts. After an account is granted permissions, both the account and its IAM users can access the resources.
For more information, see ACLs.
You can configure a bucket ACL by referring to Method.
Restrictions
- A bucket can have up to 100 ACL rules.
- To configure an ACL for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketAcl in IAM or PutBucketAcl in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Creating a Custom Bucket Policy.
Method
- Method 1: Set a pre-defined ACL when creating a bucket.
obsBucket.setBucketName(exampleBucket); // Set the bucket ACL to private read and write. obsBucket.setAcl(AccessControlList.REST_CANNED_PRIVATE); // Create a bucket. obsClient.createBucket(obsBucket);
- Method 2: After the bucket is created, set a pre-defined ACL.
// Set the bucket ACL to private read and write. obsClient.setBucketAcl(String exampleBucket, AccessControlList.REST_CANNED_PRIVATE);
- Method 3: After the bucket is created, set a user-defined ACL.
// Set a user-defined ACL for the bucket. obsClient.setBucketAcl(String bucketName,AccessControlList acl);
Request Parameters
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
bucketName |
String |
Yes |
Explanation: Bucket name. Restrictions:
Default value: None |
acl |
Yes |
Explanation: An ACL that can be specified at bucket creation. You can use either a pre-defined or a user-defined ACL. For more information about ACLs, see ACLs. Value range:
Default value: AccessControlList.REST_CANNED_PRIVATE |
Parameter |
Type |
Mandatory (Yes/No) |
Type |
---|---|---|---|
owner |
Yes |
Explanation: Bucket owner information. For details, see Table 4. |
|
delivered |
boolean |
No |
Explanation: Whether the bucket ACL is applied to all objects in the bucket. Value range: true: The bucket ACL is applied to all objects in the bucket. false: The bucket ACL is not applied to any objects in the bucket. Default value: false |
grants |
Set<GrantAndPermission> |
No |
Explanation: Grantee information. For details, see Table 5. |
Constant |
Description |
---|---|
AccessControlList.REST_CANNED_PRIVATE |
Private read/write. A bucket or object can only be accessed by its owner. |
AccessControlList.REST_CANNED_PUBLIC_READ |
Public read. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, bucket metadata, and object versions in the bucket. If this permission is granted on an object, anyone can read the content and metadata of the object. |
AccessControlList.REST_CANNED_PUBLIC_READ_WRITE |
Public read/write. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart uploads, upload parts, assemble parts, copy parts, and abort multipart upload tasks. If this permission is granted on an object, anyone can read the content and metadata of the object. |
AccessControlList.REST_CANNED_PUBLIC_READ_DELIVERED |
Public read on a bucket as well as objects in the bucket. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket. This permission cannot be granted on objects. |
AccessControlList.REST_CANNED_PUBLIC_READ_WRITE_DELIVERED |
Public read/write on a bucket as well as objects in the bucket. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket. This permission cannot be granted on objects. |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
id |
String |
Yes |
Explanation: Account (domain) ID of the bucket owner. Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? Default value: None |
displayName |
String |
No |
Explanation: Account name of the owner. Value range: To obtain the account name, see How Do I Get My Account ID and User ID? Default value: None |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
grantee |
Yes |
Explanation: Grantees (users or user groups). For details, see Table 6. |
|
permission |
Yes |
Explanation: Permissions to grant. Value range: See Table 9. Default value: None |
|
delivered |
boolean |
No |
Explanation: Whether the bucket ACL is applied to all objects in the bucket. Value range: true: The bucket ACL is applied to all objects in the bucket. false: The bucket ACL is not applied to any objects in the bucket. Default value: false |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
Yes |
Explanation: Grantee (user) information. For details, see Table 7. |
||
Yes |
Explanation: Grantee (user group) information. Value range: See Table 8. Default value: None |
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
grantId |
String |
Yes if Type is set to GranteeUser |
Explanation: Account (domain) ID of the grantee. Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? Default value: None |
displayName |
String |
No |
Explanation: Account name of the grantee. Value range: To obtain the account name, see How Do I Get My Account ID and User ID? Default value: None |
Constant |
Description |
---|---|
ALL_USERS |
All users. |
AUTHENTICATED_USERS |
Authorized users. This constant is deprecated. |
LOG_DELIVERY |
Log delivery group. This constant is deprecated. |
Constant |
Default Value |
Description |
---|---|---|
PERMISSION_READ |
READ |
Read permission. A grantee with this permission for a bucket can obtain the list of objects, multipart uploads, bucket metadata, and object versions in the bucket. A grantee with this permission for an object can obtain the object content and metadata. |
PERMISSION_WRITE |
WRITE |
Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object or part in the bucket. This permission is not available for objects. |
PERMISSION_READ_ACP |
READ_ACP |
Permission to read an ACL. A grantee with this permission can obtain the ACL of a bucket or object. A bucket or object owner has this permission for their bucket or object by default. |
PERMISSION_WRITE_ACP |
WRITE_ACP |
Permission to modify an ACL. A grantee with this permission can update the ACL of a bucket or object. A bucket or object owner has this permission for their bucket or object by default. This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object. |
PERMISSION_FULL_CONTROL |
FULL_CONTROL |
Full control access, including read and write permissions for a bucket and its ACL, or for an object and its ACL. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket. A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object. |
Responses
Parameter |
Type |
Description |
---|---|---|
statusCode |
int |
Explanation: HTTP status code. Value range: A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response. For more information, see Status Code. Default value: None |
responseHeaders |
Map<String, Object> |
Explanation: HTTP response header list, composed of tuples. In a tuple, the String key indicates the name of the header, and the Object value indicates the value of the header. Default value: None |
Code Example: Setting a Pre-defined ACL When Creating a Bucket
This example configures a pre-defined ACL during the creation of bucket exampleBucket.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.AccessControlList;
import com.obs.services.model.ObsBucket;
public class SetBucketAcl001 {
public static void main(String[] args) {
// Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
// Obtain an AK/SK pair on the management console.
String ak = System.getenv("ACCESS_KEY_ID");
String sk = System.getenv("SECRET_ACCESS_KEY_ID");
// (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
// Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
// String securityToken = System.getenv("SECURITY_TOKEN");
// Enter the endpoint corresponding to the bucket. EU-Dublin is used here as an example. Replace it with the one in your actual situation.
String endPoint = "https://obs.eu-west-101.myhuaweicloud.eu";
// Obtain an endpoint using environment variables or import it in other ways.
//String endPoint = System.getenv("ENDPOINT");
// Create an ObsClient instance.
// Use the permanent AK/SK pair to initialize the client.
ObsClient obsClient = new ObsClient(ak, sk,endPoint);
// Use the temporary AK/SK pair and security token to initialize the client.
// ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);
try {
ObsBucket obsBucket = new ObsBucket();
// Example bucket name
String exampleBucket = "examplebucket";
obsBucket.setBucketName(exampleBucket);
// Set the bucket ACL to private read and write.
obsBucket.setAcl(AccessControlList.REST_CANNED_PRIVATE);
// Create a bucket.
obsClient.createBucket(obsBucket);
System.out.println("SetBucketAcl successfully");
} catch (ObsException e) {
System.out.println("SetBucketAcl failed");
// Request failed. Print the HTTP status code.
System.out.println("HTTP Code:" + e.getResponseCode());
// Request failed. Print the server-side error code.
System.out.println("Error Code:" + e.getErrorCode());
// Request failed. Print the error details.
System.out.println("Error Message:" + e.getErrorMessage());
// Request failed. Print the request ID.
System.out.println("Request ID:" + e.getErrorRequestId());
System.out.println("Host ID:" + e.getErrorHostId());
e.printStackTrace();
} catch (Exception e) {
System.out.println("SetBucketAcl failed");
// Print other error information.
e.printStackTrace();
}
}
}
|
Code Example: Setting a Pre-defined ACL for an Existing Bucket
This example configures a pre-defined ACL for bucket exampleBucket.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 |
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.AccessControlList;
public class SetBucketAcl002 {
public static void main(String[] args) {
// Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
// Obtain an AK/SK pair on the management console.
String ak = System.getenv("ACCESS_KEY_ID");
String sk = System.getenv("SECRET_ACCESS_KEY_ID");
// (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
// Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
// String securityToken = System.getenv("SECURITY_TOKEN");
// Enter the endpoint corresponding to the bucket. EU-Dublin is used here as an example. Replace it with the one in your actual situation.
String endPoint = "https://obs.eu-west-101.myhuaweicloud.eu";
// Obtain an endpoint using environment variables or import it in other ways.
//String endPoint = System.getenv("ENDPOINT");
// Create an ObsClient instance.
// Use the permanent AK/SK pair to initialize the client.
ObsClient obsClient = new ObsClient(ak, sk,endPoint);
// Use the temporary AK/SK pair and security token to initialize the client.
// ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);
try {
// Example bucket name
String exampleBucket = "examplebucket";
// Set the bucket ACL to private read and write.
obsClient.setBucketAcl(exampleBucket, AccessControlList.REST_CANNED_PRIVATE);
System.out.println("SetBucketAcl successfully");
} catch (ObsException e) {
System.out.println("SetBucketAcl failed");
// Request failed. Print the HTTP status code.
System.out.println("HTTP Code:" + e.getResponseCode());
// Request failed. Print the server-side error code.
System.out.println("Error Code:" + e.getErrorCode());
// Request failed. Print the error details.
System.out.println("Error Message:" + e.getErrorMessage());
// Request failed. Print the request ID.
System.out.println("Request ID:" + e.getErrorRequestId());
System.out.println("Host ID:" + e.getErrorHostId());
e.printStackTrace();
} catch (Exception e) {
System.out.println("SetBucketAcl failed");
// Print other error information.
e.printStackTrace();
}
}
}
|
Code Example: Setting a User-defined ACL for an Existing Bucket
This example defines an ACL for the exampleBucket bucket.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.AccessControlList;
import com.obs.services.model.CanonicalGrantee;
import com.obs.services.model.GroupGrantee;
import com.obs.services.model.Owner;
import com.obs.services.model.Permission;
public class SetBucketAcl003 {
public static void main(String[] args) {
// Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
// Obtain an AK/SK pair on the management console.
String ak = System.getenv("ACCESS_KEY_ID");
String sk = System.getenv("SECRET_ACCESS_KEY_ID");
// (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
// Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
// String securityToken = System.getenv("SECURITY_TOKEN");
// Enter the endpoint corresponding to the bucket. EU-Dublin is used here as an example. Replace it with the one in your actual situation.
String endPoint = "https://obs.eu-west-101.myhuaweicloud.eu";
// Obtain an endpoint using environment variables or import it in other ways.
//String endPoint = System.getenv("ENDPOINT");
// Create an ObsClient instance.
// Use the permanent AK/SK pair to initialize the client.
ObsClient obsClient = new ObsClient(ak, sk,endPoint);
// Use the temporary AK/SK pair and security token to initialize the client.
// ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);
try {
// Example bucket name
String exampleBucket = "examplebucket";
// Example user ID
String exampleUserid = "userid";
// Example user ID
String exampleOwnerId = "ownerid";
AccessControlList acl = new AccessControlList();
Owner owner = new Owner();
owner.setId(exampleOwnerId);
acl.setOwner(owner);
// Grant the full control permission to a specified user.
acl.grantPermission(new CanonicalGrantee(exampleUserid), Permission.PERMISSION_FULL_CONTROL);
// Grant the read permission to all users.
acl.grantPermission(GroupGrantee.ALL_USERS, Permission.PERMISSION_READ);
// Set the bucket ACL.
obsClient.setBucketAcl(exampleBucket, acl);
System.out.println("SetBucketAcl successfully");
} catch (ObsException e) {
System.out.println("SetBucketAcl failed");
// Request failed. Print the HTTP status code.
System.out.println("HTTP Code:" + e.getResponseCode());
// Request failed. Print the server-side error code.
System.out.println("Error Code:" + e.getErrorCode());
// Request failed. Print the error details.
System.out.println("Error Message:" + e.getErrorMessage());
// Request failed. Print the request ID.
System.out.println("Request ID:" + e.getErrorRequestId());
System.out.println("Host ID:" + e.getErrorHostId());
e.printStackTrace();
} catch (Exception e) {
System.out.println("SetBucketAcl failed");
// Print other error information.
e.printStackTrace();
}
}
}
|
This example directly configures an ACL for bucket exampleBucket and applies this ACL to the objects in the bucket.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.AccessControlList;
import com.obs.services.model.CanonicalGrantee;
import com.obs.services.model.GroupGrantee;
import com.obs.services.model.Owner;
import com.obs.services.model.Permission;
public class SetBucketAcl004 {
public static void main(String[] args) {
// Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
// Obtain an AK/SK pair on the management console.
String ak = System.getenv("ACCESS_KEY_ID");
String sk = System.getenv("SECRET_ACCESS_KEY_ID");
// (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
// Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
// String securityToken = System.getenv("SECURITY_TOKEN");
// Enter the endpoint corresponding to the bucket. EU-Dublin is used here as an example. Replace it with the one currently in use.
String endPoint = "https://obs.eu-west-101.myhuaweicloud.eu";
// Obtain an endpoint using environment variables or import it in other ways.
//String endPoint = System.getenv("ENDPOINT");
// Create an instance of ObsClient.
// Use a permanent AK/SK pair to initialize the client.
ObsClient obsClient = new ObsClient(ak, sk,endPoint);
// Use a temporary AK/SK pair and security token to initialize the client.
// ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);
try {
//Example bucket name
String exampleBucket = "examplebucket";
//Example user ID
String exampleUserid = "userid";
//Example owner ID
String exampleOwnerId = "ownerid";
AccessControlList acl = new AccessControlList();
Owner owner = new Owner();
owner.setId(exampleOwnerId);
acl.setOwner(owner);
// Grant the full control permission to a specific user. The bucket ACL also applies to the objects in the bucket.
acl.grantPermission(new CanonicalGrantee(exampleUserid), Permission.PERMISSION_FULL_CONTROL,true);
// Grant the read permission to all users. The bucket ACL also applies to the objects in the bucket.
acl.grantPermission(GroupGrantee.ALL_USERS, Permission.PERMISSION_READ,true);
// Set the bucket ACL.
obsClient.setBucketAcl(exampleBucket, acl);
System.out.println("SetBucketAcl successfully");
} catch (ObsException e) {
System.out.println("SetBucketAcl failed");
// Request failed. Print the HTTP status code.
System.out.println("HTTP Code:" + e.getResponseCode());
// Request failed. Print the server-side error code.
System.out.println("Error Code:" + e.getErrorCode());
// Request failed. Print the error details.
System.out.println("Error Message:" + e.getErrorMessage());
// Request failed. Print the request ID.
System.out.println("Request ID:" + e.getErrorRequestId());
System.out.println("Host ID:" + e.getErrorHostId());
e.printStackTrace();
} catch (Exception e) {
System.out.println("SetBucketAcl failed");
// Print other error details.
e.printStackTrace();
}
}
}
|
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.