Class Bucket (7.16.0)

Create a Bucket object to interact with a Cloud Storage bucket.

Inheritance

ServiceObject<Bucket, BucketMetadata> > Bucket

Package

@google-cloud/storage

Example


const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('albums');

Constructors

(constructor)(storage, name, options)

constructor(storage: Storage, name: string, options?: BucketOptions);

Constructs a new instance of the Bucket class

Parameters
Name Description
storage Storage_2
name string
options BucketOptions

Properties

acl

acl: Acl;

cloudStorageURI

get cloudStorageURI(): URL;

The bucket's Cloud Storage URI (gs://)

Example 
ts
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('my-bucket');

// `gs://my-bucket`
const href = bucket.cloudStorageURI.href;

crc32cGenerator

crc32cGenerator: CRC32CValidatorGenerator;

iam

iam: Iam;

instancePreconditionOpts

instancePreconditionOpts?: PreconditionOptions;

name

name: string;

signer

signer?: URLSigner;

storage

storage: Storage;

A reference to the associated with this Bucket instance. Bucket#storage {Storage}

userProject

userProject?: string;

A user project to apply to each request from this bucket. Bucket#userProject {string}

Methods

addLifecycleRule(rule, options)

addLifecycleRule(rule: LifecycleRule | LifecycleRule[], options?: AddLifecycleRuleOptions): Promise<SetBucketMetadataResponse>;
Parameters
Name Description
rule LifecycleRule | LifecycleRule[]
options AddLifecycleRuleOptions
Returns
Type Description
Promise<SetBucketMetadataResponse>

addLifecycleRule(rule, options, callback)

addLifecycleRule(rule: LifecycleRule | LifecycleRule[], options: AddLifecycleRuleOptions, callback: SetBucketMetadataCallback): void;
Parameters
Name Description
rule LifecycleRule | LifecycleRule[]
options AddLifecycleRuleOptions
callback SetBucketMetadataCallback
Returns
Type Description
void

addLifecycleRule(rule, callback)

addLifecycleRule(rule: LifecycleRule | LifecycleRule[], callback: SetBucketMetadataCallback): void;
Parameters
Name Description
rule LifecycleRule | LifecycleRule[]
callback SetBucketMetadataCallback
Returns
Type Description
void

combine(sources, destination, options)

combine(sources: string[] | File[], destination: string | File, options?: CombineOptions): Promise<CombineResponse>;
Parameters
Name Description
sources string[] | File[]
destination string | File
options CombineOptions
Returns
Type Description
Promise<CombineResponse>

combine(sources, destination, options, callback)

combine(sources: string[] | File[], destination: string | File, options: CombineOptions, callback: CombineCallback): void;
Parameters
Name Description
sources string[] | File[]
destination string | File
options CombineOptions
callback CombineCallback
Returns
Type Description
void

combine(sources, destination, callback)

combine(sources: string[] | File[], destination: string | File, callback: CombineCallback): void;
Parameters
Name Description
sources string[] | File[]
destination string | File
callback CombineCallback
Returns
Type Description
void

createChannel(id, config, options)

createChannel(id: string, config: CreateChannelConfig, options?: CreateChannelOptions): Promise<CreateChannelResponse>;
Parameters
Name Description
id string
config CreateChannelConfig
options CreateChannelOptions
Returns
Type Description
Promise<CreateChannelResponse>

createChannel(id, config, callback)

createChannel(id: string, config: CreateChannelConfig, callback: CreateChannelCallback): void;
Parameters
Name Description
id string
config CreateChannelConfig
callback CreateChannelCallback
Returns
Type Description
void

createChannel(id, config, options, callback)

createChannel(id: string, config: CreateChannelConfig, options: CreateChannelOptions, callback: CreateChannelCallback): void;
Parameters
Name Description
id string
config CreateChannelConfig
options CreateChannelOptions
callback CreateChannelCallback
Returns
Type Description
void

createNotification(topic, options)

createNotification(topic: string, options?: CreateNotificationOptions): Promise<CreateNotificationResponse>;
Parameters
Name Description
topic string
options CreateNotificationOptions
Returns
Type Description
Promise<CreateNotificationResponse>

createNotification(topic, options, callback)

createNotification(topic: string, options: CreateNotificationOptions, callback: CreateNotificationCallback): void;
Parameters
Name Description
topic string
options CreateNotificationOptions
callback CreateNotificationCallback
Returns
Type Description
void

createNotification(topic, callback)

createNotification(topic: string, callback: CreateNotificationCallback): void;
Parameters
Name Description
topic string
callback CreateNotificationCallback
Returns
Type Description
void

deleteFiles(query)

deleteFiles(query?: DeleteFilesOptions): Promise<void>;
Parameter
Name Description
query DeleteFilesOptions
Returns
Type Description
Promise<void>

deleteFiles(callback)

deleteFiles(callback: DeleteFilesCallback): void;
Parameter
Name Description
callback DeleteFilesCallback
Returns
Type Description
void

deleteFiles(query, callback)

deleteFiles(query: DeleteFilesOptions, callback: DeleteFilesCallback): void;
Parameters
Name Description
query DeleteFilesOptions
callback DeleteFilesCallback
Returns
Type Description
void

deleteLabels(labels)

deleteLabels(labels?: string | string[]): Promise<DeleteLabelsResponse>;
Parameter
Name Description
labels string | string[]
Returns
Type Description
Promise<DeleteLabelsResponse>

deleteLabels(options)

deleteLabels(options: DeleteLabelsOptions): Promise<DeleteLabelsResponse>;
Parameter
Name Description
options DeleteLabelsOptions
Returns
Type Description
Promise<DeleteLabelsResponse>

deleteLabels(callback)

deleteLabels(callback: DeleteLabelsCallback): void;
Parameter
Name Description
callback DeleteLabelsCallback
Returns
Type Description
void

deleteLabels(labels, options)

deleteLabels(labels: string | string[], options: DeleteLabelsOptions): Promise<DeleteLabelsResponse>;
Parameters
Name Description
labels string | string[]
options DeleteLabelsOptions
Returns
Type Description
Promise<DeleteLabelsResponse>

deleteLabels(labels, callback)

deleteLabels(labels: string | string[], callback: DeleteLabelsCallback): void;
Parameters
Name Description
labels string | string[]
callback DeleteLabelsCallback
Returns
Type Description
void

deleteLabels(labels, options, callback)

deleteLabels(labels: string | string[], options: DeleteLabelsOptions, callback: DeleteLabelsCallback): void;
Parameters
Name Description
labels string | string[]
options DeleteLabelsOptions
callback DeleteLabelsCallback
Returns
Type Description
void

disableAutoRetryConditionallyIdempotent_(coreOpts, methodType, localPreconditionOptions)

disableAutoRetryConditionallyIdempotent_(coreOpts: any, methodType: AvailableServiceObjectMethods, localPreconditionOptions?: PreconditionOptions): void;
Parameters
Name Description
coreOpts any
methodType AvailableServiceObjectMethods
localPreconditionOptions PreconditionOptions
Returns
Type Description
void

disableRequesterPays(options)

disableRequesterPays(options?: DisableRequesterPaysOptions): Promise<DisableRequesterPaysResponse>;
Parameter
Name Description
options DisableRequesterPaysOptions
Returns
Type Description
Promise<DisableRequesterPaysResponse>

disableRequesterPays(callback)

disableRequesterPays(callback: DisableRequesterPaysCallback): void;
Parameter
Name Description
callback DisableRequesterPaysCallback
Returns
Type Description
void

disableRequesterPays(options, callback)

disableRequesterPays(options: DisableRequesterPaysOptions, callback: DisableRequesterPaysCallback): void;
Parameters
Name Description
options DisableRequesterPaysOptions
callback DisableRequesterPaysCallback
Returns
Type Description
void

enableLogging(config)

enableLogging(config: EnableLoggingOptions): Promise<SetBucketMetadataResponse>;
Parameter
Name Description
config EnableLoggingOptions
Returns
Type Description
Promise<SetBucketMetadataResponse>

enableLogging(config, callback)

enableLogging(config: EnableLoggingOptions, callback: SetBucketMetadataCallback): void;
Parameters
Name Description
config EnableLoggingOptions
callback SetBucketMetadataCallback
Returns
Type Description
void

enableRequesterPays(options)

enableRequesterPays(options?: EnableRequesterPaysOptions): Promise<EnableRequesterPaysResponse>;
Parameter
Name Description
options EnableRequesterPaysOptions
Returns
Type Description
Promise<EnableRequesterPaysResponse>

enableRequesterPays(callback)

enableRequesterPays(callback: EnableRequesterPaysCallback): void;
Parameter
Name Description
callback EnableRequesterPaysCallback
Returns
Type Description
void

enableRequesterPays(options, callback)

enableRequesterPays(options: EnableRequesterPaysOptions, callback: EnableRequesterPaysCallback): void;
Parameters
Name Description
options EnableRequesterPaysOptions
callback EnableRequesterPaysCallback
Returns
Type Description
void

file(name, options)

file(name: string, options?: FileOptions): File;

Create a object. See to see how to handle the different use cases you may have.

Parameters
Name Description
name string

The name of the file in this bucket.
options FileOptions

Configuration options.
Returns
Type Description
File_2

{File}
Example 

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('albums');
const file = bucket.file('my-existing-file.png');

getFiles(query)

getFiles(query?: GetFilesOptions): Promise<GetFilesResponse>;
Parameter
Name Description
query GetFilesOptions
Returns
Type Description
Promise<GetFilesResponse>

getFiles(query, callback)

getFiles(query: GetFilesOptions, callback: GetFilesCallback): void;
Parameters
Name Description
query GetFilesOptions
callback GetFilesCallback
Returns
Type Description
void

getFiles(callback)

getFiles(callback: GetFilesCallback): void;
Parameter
Name Description
callback GetFilesCallback
Returns
Type Description
void

getFilesStream(query)

getFilesStream(query?: GetFilesOptions): Readable;
Parameter
Name Description
query GetFilesOptions
Returns
Type Description
Readable

getId()

getId(): string;
Returns
Type Description
string

getLabels(options)

getLabels(options?: GetLabelsOptions): Promise<GetLabelsResponse>;
Parameter
Name Description
options GetLabelsOptions
Returns
Type Description
Promise<GetLabelsResponse>

getLabels(callback)

getLabels(callback: GetLabelsCallback): void;
Parameter
Name Description
callback GetLabelsCallback
Returns
Type Description
void

getLabels(options, callback)

getLabels(options: GetLabelsOptions, callback: GetLabelsCallback): void;
Parameters
Name Description
options GetLabelsOptions
callback GetLabelsCallback
Returns
Type Description
void

getNotifications(options)

getNotifications(options?: GetNotificationsOptions): Promise<GetNotificationsResponse>;
Parameter
Name Description
options GetNotificationsOptions
Returns
Type Description
Promise<GetNotificationsResponse>

getNotifications(callback)

getNotifications(callback: GetNotificationsCallback): void;
Parameter
Name Description
callback GetNotificationsCallback
Returns
Type Description
void

getNotifications(options, callback)

getNotifications(options: GetNotificationsOptions, callback: GetNotificationsCallback): void;
Parameters
Name Description
options GetNotificationsOptions
callback GetNotificationsCallback
Returns
Type Description
void

getSignedUrl(cfg)

getSignedUrl(cfg: GetBucketSignedUrlConfig): Promise<GetSignedUrlResponse>;
Parameter
Name Description
cfg GetBucketSignedUrlConfig
Returns
Type Description
Promise<GetSignedUrlResponse>

getSignedUrl(cfg, callback)

getSignedUrl(cfg: GetBucketSignedUrlConfig, callback: GetSignedUrlCallback): void;
Parameters
Name Description
cfg GetBucketSignedUrlConfig
callback GetSignedUrlCallback
Returns
Type Description
void

lock(metageneration)

lock(metageneration: number | string): Promise<BucketLockResponse>;
Parameter
Name Description
metageneration number | string
Returns
Type Description
Promise<BucketLockResponse>

lock(metageneration, callback)

lock(metageneration: number | string, callback: BucketLockCallback): void;
Parameters
Name Description
metageneration number | string
callback BucketLockCallback
Returns
Type Description
void

makeAllFilesPublicPrivate_(options)

makeAllFilesPublicPrivate_(options?: MakeAllFilesPublicPrivateOptions): Promise<MakeAllFilesPublicPrivateResponse>;
Parameter
Name Description
options MakeAllFilesPublicPrivateOptions
Returns
Type Description
Promise<MakeAllFilesPublicPrivateResponse>

makeAllFilesPublicPrivate_(callback)

makeAllFilesPublicPrivate_(callback: MakeAllFilesPublicPrivateCallback): void;
Parameter
Name Description
callback MakeAllFilesPublicPrivateCallback
Returns
Type Description
void

makeAllFilesPublicPrivate_(options, callback)

makeAllFilesPublicPrivate_(options: MakeAllFilesPublicPrivateOptions, callback: MakeAllFilesPublicPrivateCallback): void;
Parameters
Name Description
options MakeAllFilesPublicPrivateOptions
callback MakeAllFilesPublicPrivateCallback
Returns
Type Description
void

makePrivate(options)

makePrivate(options?: MakeBucketPrivateOptions): Promise<MakeBucketPrivateResponse>;
Parameter
Name Description
options MakeBucketPrivateOptions
Returns
Type Description
Promise<MakeBucketPrivateResponse>

makePrivate(callback)

makePrivate(callback: MakeBucketPrivateCallback): void;
Parameter
Name Description
callback MakeBucketPrivateCallback
Returns
Type Description
void

makePrivate(options, callback)

makePrivate(options: MakeBucketPrivateOptions, callback: MakeBucketPrivateCallback): void;
Parameters
Name Description
options MakeBucketPrivateOptions
callback MakeBucketPrivateCallback
Returns
Type Description
void

makePublic(options)

makePublic(options?: MakeBucketPublicOptions): Promise<MakeBucketPublicResponse>;
Parameter
Name Description
options MakeBucketPublicOptions
Returns
Type Description
Promise<MakeBucketPublicResponse>

makePublic(callback)

makePublic(callback: MakeBucketPublicCallback): void;
Parameter
Name Description
callback MakeBucketPublicCallback
Returns
Type Description
void

makePublic(options, callback)

makePublic(options: MakeBucketPublicOptions, callback: MakeBucketPublicCallback): void;
Parameters
Name Description
options MakeBucketPublicOptions
callback MakeBucketPublicCallback
Returns
Type Description
void

notification(id)

notification(id: string): Notification;

Get a reference to a Cloud Pub/Sub Notification.

Parameter
Name Description
id string

ID of notification.
Returns
Type Description
Notification

{Notification}
Example 

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('my-bucket');
const notification = bucket.notification('1');

removeRetentionPeriod(options)

removeRetentionPeriod(options?: SetBucketMetadataOptions): Promise<SetBucketMetadataResponse>;
Parameter
Name Description
options SetBucketMetadataOptions
Returns
Type Description
Promise<SetBucketMetadataResponse>

removeRetentionPeriod(callback)

removeRetentionPeriod(callback: SetBucketMetadataCallback): void;
Parameter
Name Description
callback SetBucketMetadataCallback
Returns
Type Description
void

removeRetentionPeriod(options, callback)

removeRetentionPeriod(options: SetBucketMetadataOptions, callback: SetBucketMetadataCallback): void;
Parameters
Name Description
options SetBucketMetadataOptions
callback SetBucketMetadataCallback
Returns
Type Description
void

request(reqOpts)

request(reqOpts: DecorateRequestOptions): Promise<RequestResponse>;
Parameter
Name Description
reqOpts DecorateRequestOptions
Returns
Type Description
Promise<RequestResponse>

request(reqOpts, callback)

request(reqOpts: DecorateRequestOptions, callback: BodyResponseCallback): void;
Parameters
Name Description
reqOpts DecorateRequestOptions
callback BodyResponseCallback
Returns
Type Description
void

restore(options)

restore(options: RestoreOptions): Promise<Bucket>;

Restores a soft-deleted bucket

Parameter
Name Description
options RestoreOptions

Restore options.
Returns
Type Description
Promise<Bucket>

{Promise

setCorsConfiguration(corsConfiguration, options)

setCorsConfiguration(corsConfiguration: Cors[], options?: SetBucketMetadataOptions): Promise<SetBucketMetadataResponse>;
Parameters
Name Description
corsConfiguration Cors[]
options SetBucketMetadataOptions
Returns
Type Description
Promise<SetBucketMetadataResponse>

setCorsConfiguration(corsConfiguration, callback)

setCorsConfiguration(corsConfiguration: Cors[], callback: SetBucketMetadataCallback): void;
Parameters
Name Description
corsConfiguration Cors[]
callback SetBucketMetadataCallback
Returns
Type Description
void

setCorsConfiguration(corsConfiguration, options, callback)

setCorsConfiguration(corsConfiguration: Cors[], options: SetBucketMetadataOptions, callback: SetBucketMetadataCallback): void;
Parameters
Name Description
corsConfiguration Cors[]
options SetBucketMetadataOptions
callback SetBucketMetadataCallback
Returns
Type Description
void

setLabels(labels, options)

setLabels(labels: Labels, options?: SetLabelsOptions): Promise<SetLabelsResponse>;
Parameters
Name Description
labels Labels
options SetLabelsOptions
Returns
Type Description
Promise<SetLabelsResponse>

setLabels(labels, callback)

setLabels(labels: Labels, callback: SetLabelsCallback): void;
Parameters
Name Description
labels Labels
callback SetLabelsCallback
Returns
Type Description
void

setLabels(labels, options, callback)

setLabels(labels: Labels, options: SetLabelsOptions, callback: SetLabelsCallback): void;
Parameters
Name Description
labels Labels
options SetLabelsOptions
callback SetLabelsCallback
Returns
Type Description
void

setMetadata(metadata, options)

setMetadata(metadata: BucketMetadata, options?: SetMetadataOptions): Promise<SetMetadataResponse<BucketMetadata>>;
Parameters
Name Description
metadata BucketMetadata
options SetMetadataOptions
Returns
Type Description
Promise<SetMetadataResponse<BucketMetadata>>

setMetadata(metadata, callback)

setMetadata(metadata: BucketMetadata, callback: MetadataCallback<BucketMetadata>): void;
Parameters
Name Description
metadata BucketMetadata
callback MetadataCallback<BucketMetadata>
Returns
Type Description
void

setMetadata(metadata, options, callback)

setMetadata(metadata: BucketMetadata, options: SetMetadataOptions, callback: MetadataCallback<BucketMetadata>): void;
Parameters
Name Description
metadata BucketMetadata
options SetMetadataOptions
callback MetadataCallback<BucketMetadata>
Returns
Type Description
void

setRetentionPeriod(duration, options)

setRetentionPeriod(duration: number, options?: SetBucketMetadataOptions): Promise<SetBucketMetadataResponse>;
Parameters
Name Description
duration number
options SetBucketMetadataOptions
Returns
Type Description
Promise<SetBucketMetadataResponse>

setRetentionPeriod(duration, callback)

setRetentionPeriod(duration: number, callback: SetBucketMetadataCallback): void;
Parameters
Name Description
duration number
callback SetBucketMetadataCallback
Returns
Type Description
void

setRetentionPeriod(duration, options, callback)

setRetentionPeriod(duration: number, options: SetBucketMetadataOptions, callback: SetBucketMetadataCallback): void;
Parameters
Name Description
duration number
options SetBucketMetadataOptions
callback SetBucketMetadataCallback
Returns
Type Description
void

setStorageClass(storageClass, options)

setStorageClass(storageClass: string, options?: SetBucketStorageClassOptions): Promise<SetBucketMetadataResponse>;
Parameters
Name Description
storageClass string
options SetBucketStorageClassOptions
Returns
Type Description
Promise<SetBucketMetadataResponse>

setStorageClass(storageClass, callback)

setStorageClass(storageClass: string, callback: SetBucketStorageClassCallback): void;
Parameters
Name Description
storageClass string
callback SetBucketStorageClassCallback
Returns
Type Description
void

setStorageClass(storageClass, options, callback)

setStorageClass(storageClass: string, options: SetBucketStorageClassOptions, callback: SetBucketStorageClassCallback): void;
Parameters
Name Description
storageClass string
options SetBucketStorageClassOptions
callback SetBucketStorageClassCallback
Returns
Type Description
void

setUserProject(userProject)

setUserProject(userProject: string): void;

Set a user project to be billed for all requests made from this Bucket object and any files referenced from this Bucket object.

Parameter
Name Description
userProject string

The user project.
Returns
Type Description
void
Example 

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('albums');

bucket.setUserProject('grape-spaceship-123');

upload(pathString, options)

upload(pathString: string, options?: UploadOptions): Promise<UploadResponse>;
Parameters
Name Description
pathString string
options UploadOptions
Returns
Type Description
Promise<UploadResponse>

upload(pathString, options, callback)

upload(pathString: string, options: UploadOptions, callback: UploadCallback): void;
Parameters
Name Description
pathString string
options UploadOptions
callback UploadCallback
Returns
Type Description
void

upload(pathString, callback)

upload(pathString: string, callback: UploadCallback): void;
Parameters
Name Description
pathString string
callback UploadCallback
Returns
Type Description
void