Buckets service
Introduction​
The S3 Bucket service is used when we want to make changes to buckets.
We can do multiple things with this service like:
- create buckets
- list buckets
- delete buckets
- tag buckets, etc.
Basic usage​
The pre-requisites to use this service are to have the main module initialized in our app, so we can access all the services it exports. Later, when we need a service we can simply:
import { Injectable } from '@nestjs/common';
import { BucketsService } from '@lab08/nestjs-s3';
@Injectable()
export class MyService {
public constructor(private readonly bucketService: BucketService) {}
}
then we can simply call start using the service freely.
Listing buckets​
One of the things we can do is list buckets. In other to do that we can use the list
method of the service
const buckets = await this.bucketService.list();
which will return a Promise
containing
interface ListBucketsCommandOutput {
/**
* The list of buckets owned by the requestor.
*/
Buckets?: Bucket[];
/**
* The owner of the buckets listed.
*/
Owner?: Owner;
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}
Creating buckets​
When we need to create a new bucket we can just simply call
const bucket = await this.bucketService.create('test-bucket');
or
const bucket = await this.bucketService.create('test-bucket', options);
where options can be
export interface CreateBucketRequest {
/**
* The canned ACL to apply to the bucket.
*/
ACL?: BucketCannedACL | string;
/**
* The configuration information for the bucket.
*/
CreateBucketConfiguration?: CreateBucketConfiguration;
/**
* Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
*/
GrantFullControl?: string;
/**
* Allows grantee to list the objects in the bucket.
*/
GrantRead?: string;
/**
* Allows grantee to read the bucket ACL.
*/
GrantReadACP?: string;
/**
* Allows grantee to create new objects in the bucket.
* For the bucket and object owners of existing objects, it also allows deletions and overwrites.
*/
GrantWrite?: string;
/**
* Allows grantee to write the ACL for the applicable bucket.
*/
GrantWriteACP?: string;
/**
* Specifies whether you want S3 Object Lock for the new bucket.
*/
ObjectLockEnabledForBucket?: boolean;
}
which will return a Promise
containing
interface CreateBucketCommandOutput {
/**
* Specifies the Region where the bucket will be created. If you are creating a bucket on
* the US East (N. Virginia) Region (us-east-1), you do not need to specify the
* location.
*/
Location?: string;
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}
Deleting buckets​
After we already have a bucket, we can easily remove it. This can be done by calling the delete
method.
const result = await this.bucketService.delete('test-bucket');
which will return a Promise
with the delete operation output
interface DeleteBucketCommandOutput {
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}
Listing buckets​
We can call the list
method if we want to get all our existing buckets.
const result = await this.bucketService.list();
which will return a list of all the buckets, that we have access to. It returns a Promise
with the following:
export interface ListBucketsCommandOutput {
/**
* <p>The list of buckets owned by the requestor.</p>
*/
Buckets?: Bucket[];
/**
* <p>The owner of the buckets listed.</p>
*/
Owner?: Owner;
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}
Searching for a bucket by name​
If we want to see if we have a bucket with a specific name, we can use the find
method and pass the name of the bucket we want.
const result = await this.bucketService.find('test');
If found this method will return a Promise
with a Bucket
object, or if it cannot find a bucket - undefined
.
Upading a bucket​
Tagging​
We can do other things with a bucket like updating tags
const result = await this.bucketService.tagging('test');
which will return a Promise
with the following:
export interface GetBucketTaggingCommandOutput {
/**
* <p>Contains the tag set.</p>
*/
TagSet: Tag[] | undefined;
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}
Updating CORS​
We can update the exsisting cors
const result = await this.bucketService.updateCors('test', options);
which can receive the following options
export interface CORSConfiguration {
/**
* <p>A set of origins and methods (cross-origin access you want to allow). You can add
* up to 100 rules to the configuration.</p>
*/
CORSRules: CORSRule[] | undefined;
}
which will return a Promise
with
export interface PutBucketCorsCommandOutput {
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}
Updating ACL​
const result = await this.bucketService.updateAcl('test', options);
which can receive the following options
export interface CORSConfiguration {
/**
* <p>The canned ACL to apply to the bucket.</p>
*/
ACL?: BucketCannedACL | string;
/**
* <p>Contains the elements that set the ACL permissions for an object per grantee.</p>
*/
AccessControlPolicy?: AccessControlPolicy;
/**
* <p>The base64-encoded 128-bit MD5 digest of the data. This header must be used as a message
* integrity check to verify that the request body was not corrupted in transit. For more
* information, go to <a href="http://www.ietf.org/rfc/rfc1864.txt">RFC
* 1864.</a>
* </p>
* <p>For requests made using the Amazon Web Services Command Line Interface (CLI) or Amazon Web Services SDKs, this field is calculated automatically.</p>
*/
ContentMD5?: string;
/**
* <p>Allows grantee the read, write, read ACP, and write ACP permissions on the
* bucket.</p>
*/
GrantFullControl?: string;
/**
* <p>Allows grantee to list the objects in the bucket.</p>
*/
GrantRead?: string;
/**
* <p>Allows grantee to read the bucket ACL.</p>
*/
GrantReadACP?: string;
/**
* <p>Allows grantee to create new objects in the bucket.</p>
* <p>For the bucket and object owners of existing objects, also allows deletions and overwrites of those objects.</p>
*/
GrantWrite?: string;
/**
* <p>Allows grantee to write the ACL for the applicable bucket.</p>
*/
GrantWriteACP?: string;
/**
* <p>The account ID of the expected bucket owner. If different account owns the bucket, the request will fail with an HTTP <code>403 (Access Denied)</code> error.</p>
*/
ExpectedBucketOwner?: string;
}
which will return a Promise
with
export interface PutBucketAclCommandOutput {
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}
Updating Logging​
const result = await this.bucketService.updateLogging('test', options);
which can receive the following options
export interface PutBucketLoggingCommandInput {
/**
* <p>Container for logging status information.</p>
*/
BucketLoggingStatus: BucketLoggingStatus | undefined;
/**
* <p>The MD5 hash of the <code>PutBucketLogging</code> request body.</p>
* <p>For requests made using the Amazon Web Services Command Line Interface (CLI) or Amazon Web Services SDKs, this field is calculated automatically.</p>
*/
ContentMD5?: string;
/**
* <p>The account ID of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP <code>403 (Access Denied)</code> error.</p>
*/
ExpectedBucketOwner?: string;
}
which will return a Promise
with
export interface PutBucketLoggingCommandOutput {
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}
Updating encryption​
const result = await this.bucketService.updateEncryption('test', options);
which can receive the following options
export interface PutBucketEncryptionCommandInput {
/**
* <p>The base64-encoded 128-bit MD5 digest of the server-side encryption configuration.</p>
* <p>For requests made using the Amazon Web Services Command Line Interface (CLI) or Amazon Web Services SDKs, this field is calculated automatically.</p>
*/
ContentMD5?: string;
/**
* <p>Specifies the default server-side-encryption configuration.</p>
*/
ServerSideEncryptionConfiguration: ServerSideEncryptionConfiguration | undefined;
/**
* <p>The account ID of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP <code>403 (Access Denied)</code> error.</p>
*/
ExpectedBucketOwner?: string;
}
which will return a Promise
with
export interface PutBucketEncryptionCommandOutput {
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}
Updating accelerate configuration​
const result = await this.bucketService.updateAccelerateConfiguration('test', options);
which can receive the following options
export interface AccelerateConfiguration {
/**
* <p>Specifies the transfer acceleration status of the bucket.</p>
*/
Status?: BucketAccelerateStatus | string;
}
which will return a Promise
with
export interface PutBucketAccelerateConfigurationCommandOutput {
/**
* Metadata pertaining to this request.
*/
$metadata: ResponseMetadata;
}