Class BucketService
Amazon S3 Bucket management service.
Implements
Inherited Members
Namespace: Glitch9.AIDevKit.AmazonAws.S3.Services
Assembly: Glitch9.AIDevKit.Provider.AmazonAws.dll
Syntax
public sealed class BucketService : CrudServiceBase<AwsClient>, ICrudServiceRemarks
Required IAM Permissions:
- s3:CreateBucket -Allows creating new S3 buckets.
- s3:DeleteBucket -Allows deleting existing buckets.
- s3:ListAllMyBuckets -Allows listing all buckets in the AWS account.
These three actions are the minimum permissions required to programmatically create, delete, and retrieve the list of buckets.
Important: AWS does not provide a built-in managed policy that grants only these bucket-management permissions. You must create a customer-managed policy with the actions listed above.
You may use AmazonS3FullAccess instead, which includes all S3 actions, but this grants far more permissions than necessary and is generally not recommended for production environments due to security risks.
Note for beginners:
Creating a bucket does not automatically grant permission to upload,
read, or delete objects inside it. Those actions require separate S3 object
permissions such as s3:PutObject, s3:GetObject, or
s3:DeleteObject. Bucket management and object management are
handled by different IAM permissions.
Constructors
| Edit this page View SourceBucketService(AwsClient)
Declaration
public BucketService(AwsClient client)Parameters
| Type | Name | Description |
|---|---|---|
| AwsClient | client |
Methods
| Edit this page View SourceCreateAsync(CreateBucketRequest, RequestOptions)
Creates a new S3 bucket. To create a bucket, you must set up Amazon S3 and have a valid AWS Access Key ID to authenticate requests.
Declaration
public UniTask<S3Bucket> CreateAsync(CreateBucketRequest request, RequestOptions options = null)Parameters
| Type | Name | Description |
|---|---|---|
| CreateBucketRequest | request | The bucket creation request parameters. |
| RequestOptions | options | Optional REST request options. |
Returns
| Type | Description |
|---|---|
| UniTask<S3Bucket> | The created S3 bucket. |
Remarks
Bucket Types: There are two types of buckets: general purpose buckets and directory buckets.
General Purpose Buckets:
- If you send your CreateBucket request to the s3.amazonaws.com global endpoint, the request goes to the us-east-1 Region.
- Signature calculations in Signature Version 4 must use us-east-1 as the Region, even if the location constraint specifies another Region.
- If you create a bucket in a Region other than US East (N. Virginia), your application must be able to handle 307 redirect.
Directory Buckets:
- You must make requests for this API operation to the Regional endpoint.
- These endpoints support path-style requests in the format: https://s3express-control.region-code.amazonaws.com/bucket-name
- Virtual-hosted-style requests aren't supported.
- HTTP Host header syntax: s3express-control.region-code.amazonaws.com
General Purpose Bucket Permissions:
- s3:CreateBucket permission is required.
- ACLs: If you specify an ACL (public-read, public-read-write, authenticated-read, or custom), both s3:CreateBucket and s3:PutBucketAcl permissions are required.
- Object Lock: If you set x-amz-bucket-object-lock-enabled to true, s3:PutBucketObjectLockConfiguration and s3:PutBucketVersioning permissions are required.
- S3 Object Ownership: If you include the x-amz-object-ownership header, s3:PutBucketOwnershipControls permission is required.
- Block Public Access: To disable Block Public Access, you must have the s3:PutBucketPublicAccessBlock permission.
Important - ACLs and Public Access:
To set an ACL on a bucket as part of a CreateBucket request, you must explicitly set S3 Object Ownership to a different value than the default (BucketOwnerEnforced). If your desired bucket ACL grants public access, you must first create the bucket without the ACL, then explicitly disable Block Public Access, and finally use PutBucketAcl to set the ACL. For modern use cases, we recommend keeping all Block Public Access settings enabled and ACLs disabled.
Directory Bucket Permissions:
- You must have the s3express:CreateBucket permission in an IAM identity-based policy.
- Cross-account access is not supported.
- ACLs, Object Lock, S3 Object Ownership, and S3 Block Public Access are not supported for directory buckets.
- All Block Public Access settings are enabled at the bucket level and S3 Object Ownership is set to Bucket owner enforced (ACLs disabled).
DeleteAsync(DeleteBucketRequest, RequestOptions)
Deletes the S3 bucket. All objects (including all object versions and delete markers) in the bucket must be deleted before the bucket itself can be deleted.
Declaration
public UniTask<bool> DeleteAsync(DeleteBucketRequest request, RequestOptions options = null)Parameters
| Type | Name | Description |
|---|---|---|
| DeleteBucketRequest | request | The bucket deletion request parameters. |
| RequestOptions | options | Optional REST request options. |
Returns
| Type | Description |
|---|---|
| UniTask<bool> | True if the bucket was successfully deleted, false otherwise. |
Remarks
Important: All objects (including all object versions and delete markers) in the bucket must be deleted before the bucket itself can be deleted.
Directory Buckets - Multipart Uploads:
If multipart uploads in a directory bucket are in progress, you can't delete the bucket until all the in-progress multipart uploads are aborted or completed.
Directory Buckets - Regional Endpoint:
- For directory buckets, you must make requests for this API operation to the Regional endpoint.
- These endpoints support path-style requests in the format: https://s3express-control.region-code.amazonaws.com/bucket-name
- Virtual-hosted-style requests aren't supported.
- HTTP Host header syntax: s3express-control.region-code.amazonaws.com
Permissions:
- General purpose bucket: You must have the s3:DeleteBucket permission on the specified bucket in a policy.
- Directory bucket: You must have the s3express:DeleteBucket permission in an IAM identity-based policy instead of a bucket policy.
- Cross-account access to this API operation isn't supported for directory buckets.
- This operation can only be performed by the AWS account that owns the resource.
DeleteAsync(string, string, RequestOptions)
Declaration
public UniTask<bool> DeleteAsync(string bucketName, string region = null, RequestOptions options = null)Parameters
| Type | Name | Description |
|---|---|---|
| string | bucketName | |
| string | region | |
| RequestOptions | options |
Returns
| Type | Description |
|---|---|
| UniTask<bool> |
ListAsync(ListBucketsRequest, RequestOptions)
Lists all buckets owned by the authenticated sender.
Declaration
public UniTask<S3BucketList> ListAsync(ListBucketsRequest request, RequestOptions options = null)Parameters
| Type | Name | Description |
|---|---|---|
| ListBucketsRequest | request | Optional request parameters for filtering and pagination. |
| RequestOptions | options | Optional REST request options. |
Returns
| Type | Description |
|---|---|
| UniTask<S3BucketList> | A list of S3 buckets. |
Remarks
Important: We strongly recommend using only paginated ListBuckets requests.
Unpaginated ListBuckets requests are only supported for AWS accounts set to the default general purpose bucket quota of 10,000. If you have an approved general purpose bucket quota above 10,000, you must send paginated ListBuckets requests to list your account's buckets.
All unpaginated ListBuckets requests will be rejected for AWS accounts with a general purpose bucket quota greater than 10,000.
Note: You must URL encode any signed header values that contain spaces. For example, if your header value is "my file.txt", you must URL encode this value to "my%20%20file.txt".
ListAsync(int, RequestOptions)
Declaration
public UniTask<S3BucketList> ListAsync(int maxBuckets, RequestOptions options = null)Parameters
| Type | Name | Description |
|---|---|---|
| int | maxBuckets | |
| RequestOptions | options |
Returns
| Type | Description |
|---|---|
| UniTask<S3BucketList> |