}
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('albums');
*
* bucket.getFiles(function(err, files) {
* if (!err) {
* // files is an array of File objects.
* }
* });
*
* //-
* // If your bucket has versioning enabled, you can get all of your files
* // scoped to their generation.
* //-
* bucket.getFiles({
* versions: true
* }, function(err, files) {
* // Each file is scoped to its generation.
* });
*
* //-
* // To control how many API requests are made and page through the results
* // manually, set `autoPaginate` to `false`.
* //-
* const callback = function(err, files, nextQuery, apiResponse) {
* if (nextQuery) {
* // More results exist.
* bucket.getFiles(nextQuery, callback);
* }
*
* // The `metadata` property is populated for you with the metadata at the
* // time of fetching.
* files[0].metadata;
*
* // However, in cases where you are concerned the metadata could have
* // changed, use the `getMetadata` method.
* files[0].getMetadata(function(err, metadata) {});
* };
*
* bucket.getFiles({
* autoPaginate: false
* }, callback);
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.getFiles().then(function(data) {
* const files = data[0];
* });
*
* ```
* @example
* Simulating a File System
With `autoPaginate: false`, it's possible to iterate over files which incorporate a common structure using a delimiter.
Consider the following remote objects:
- "a"
- "a/b/c/d"
- "b/d/e"
Using a delimiter of `/` will return a single file, "a".
`apiResponse.prefixes` will return the "sub-directories" that were found:
- "a/"
- "b/"
* ```
* bucket.getFiles({
* autoPaginate: false,
* delimiter: '/'
* }, function(err, files, nextQuery, apiResponse) {
* // files = [
* // {File} // File object for file "a"
* // ]
*
* // apiResponse.prefixes = [
* // 'a/',
* // 'b/'
* // ]
* });
* ```
*
* @example
* Using prefixes, it's now possible to simulate a file system with follow-up requests.
* ```
* bucket.getFiles({
* autoPaginate: false,
* delimiter: '/',
* prefix: 'a/'
* }, function(err, files, nextQuery, apiResponse) {
* // No files found within "directory" a.
* // files = []
*
* // However, a "sub-directory" was found.
* // This prefix can be used to continue traversing the "file system".
* // apiResponse.prefixes = [
* // 'a/b/'
* // ]
* });
* ```
*
* @example include:samples/files.js
* region_tag:storage_list_files
* Another example:
*
* @example include:samples/files.js
* region_tag:storage_list_files_with_prefix
* Example of listing files, filtered by a prefix:
*/
getFiles(queryOrCallback, callback) {
let query = typeof queryOrCallback === 'object' ? queryOrCallback : {};
if (!callback) {
callback = queryOrCallback;
}
query = Object.assign({}, query);
this.request({
uri: '/o',
qs: query,
}, (err, resp) => {
if (err) {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
callback(err, null, null, resp);
return;
}
const itemsArray = resp.items ? resp.items : [];
const files = itemsArray.map((file) => {
const options = {};
if (query.fields) {
const fileInstance = file;
return fileInstance;
}
if (query.versions) {
options.generation = file.generation;
}
if (file.kmsKeyName) {
options.kmsKeyName = file.kmsKeyName;
}
const fileInstance = this.file(file.name, options);
fileInstance.metadata = file;
return fileInstance;
});
let nextQuery = null;
if (resp.nextPageToken) {
nextQuery = Object.assign({}, query, {
pageToken: resp.nextPageToken,
});
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
callback(null, files, nextQuery, resp);
});
}
/**
* @deprecated
* @typedef {object} GetLabelsOptions Configuration options for Bucket#getLabels().
* @param {string} [userProject] The ID of the project which will be
* billed for the request.
*/
/**
* @deprecated
* @typedef {array} GetLabelsResponse
* @property {object} 0 Object of labels currently set on this bucket.
*/
/**
* @deprecated
* @callback GetLabelsCallback
* @param {?Error} err Request error, if any.
* @param {object} labels Object of labels currently set on this bucket.
*/
/**
* @deprecated Use getMetadata directly.
* Get the labels currently set on this bucket.
*
* @param {object} [options] Configuration options.
* @param {string} [options.userProject] The ID of the project which will be
* billed for the request.
* @param {GetLabelsCallback} [callback] Callback function.
* @returns {Promise}
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('albums');
*
* bucket.getLabels(function(err, labels) {
* if (err) {
* // Error handling omitted.
* }
*
* // labels = {
* // label: 'labelValue',
* // ...
* // }
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.getLabels().then(function(data) {
* const labels = data[0];
* });
* ```
*/
getLabels(optionsOrCallback, callback) {
let options = {};
if (typeof optionsOrCallback === 'function') {
callback = optionsOrCallback;
}
else if (optionsOrCallback) {
options = optionsOrCallback;
}
this.getMetadata(options, (err, metadata) => {
if (err) {
callback(err, null);
return;
}
callback(null, (metadata === null || metadata === void 0 ? void 0 : metadata.labels) || {});
});
}
/**
* @typedef {object} GetNotificationsOptions Configuration options for Bucket#getNotification().
* @property {string} [userProject] The ID of the project which will be
* billed for the request.
*/
/**
* @callback GetNotificationsCallback
* @param {?Error} err Request error, if any.
* @param {Notification[]} notifications Array of {@link Notification}
* instances.
* @param {object} apiResponse The full API response.
*/
/**
* @typedef {array} GetNotificationsResponse
* @property {Notification[]} 0 Array of {@link Notification} instances.
* @property {object} 1 The full API response.
*/
/**
* Retrieves a list of notification subscriptions for a given bucket.
*
* See {@link https://cloud.google.com/storage/docs/json_api/v1/notifications/list| Notifications: list}
*
* @param {GetNotificationsOptions} [options] Configuration options.
* @param {string} [options.userProject] The ID of the project which will be
* billed for the request.
* @param {GetNotificationsCallback} [callback] Callback function.
* @returns {Promise}
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('my-bucket');
*
* bucket.getNotifications(function(err, notifications, apiResponse) {
* if (!err) {
* // notifications is an array of Notification objects.
* }
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.getNotifications().then(function(data) {
* const notifications = data[0];
* const apiResponse = data[1];
* });
*
* ```
* @example include:samples/listNotifications.js
* region_tag:storage_list_bucket_notifications
* Another example:
*/
getNotifications(optionsOrCallback, callback) {
let options = {};
if (typeof optionsOrCallback === 'function') {
callback = optionsOrCallback;
}
else if (optionsOrCallback) {
options = optionsOrCallback;
}
this.request({
uri: '/notificationConfigs',
qs: options,
}, (err, resp) => {
if (err) {
callback(err, null, resp);
return;
}
const itemsArray = resp.items ? resp.items : [];
const notifications = itemsArray.map((notification) => {
const notificationInstance = this.notification(notification.id);
notificationInstance.metadata = notification;
return notificationInstance;
});
callback(null, notifications, resp);
});
}
/**
* @typedef {array} GetSignedUrlResponse
* @property {object} 0 The signed URL.
*/
/**
* @callback GetSignedUrlCallback
* @param {?Error} err Request error, if any.
* @param {object} url The signed URL.
*/
/**
* @typedef {object} GetBucketSignedUrlConfig
* @property {string} action Only listing objects within a bucket (HTTP: GET) is supported for bucket-level signed URLs.
* @property {*} expires A timestamp when this link will expire. Any value
* given is passed to `new Date()`.
* Note: 'v4' supports maximum duration of 7 days (604800 seconds) from now.
* @property {string} [version='v2'] The signing version to use, either
* 'v2' or 'v4'.
* @property {boolean} [virtualHostedStyle=false] Use virtual hosted-style
* URLs ('https://mybucket.storage.googleapis.com/...') instead of path-style
* ('https://storage.googleapis.com/mybucket/...'). Virtual hosted-style URLs
* should generally be preferred instaed of path-style URL.
* Currently defaults to `false` for path-style, although this may change in a
* future major-version release.
* @property {string} [cname] The cname for this bucket, i.e.,
* "https://cdn.example.com".
* See [reference]{@link https://cloud.google.com/storage/docs/access-control/signed-urls#example}
* @property {object} [extensionHeaders] If these headers are used, the
* server will check to make sure that the client provides matching
* values. See {@link https://cloud.google.com/storage/docs/access-control/signed-urls#about-canonical-extension-headers| Canonical extension headers}
* for the requirements of this feature, most notably:
* - The header name must be prefixed with `x-goog-`
* - The header name must be all lowercase
*
* Note: Multi-valued header passed as an array in the extensionHeaders
* object is converted into a string, delimited by `,` with
* no space. Requests made using the signed URL will need to
* delimit multi-valued headers using a single `,` as well, or
* else the server will report a mismatched signature.
* @property {object} [queryParams] Additional query parameters to include
* in the signed URL.
*/
/**
* Get a signed URL to allow limited time access to a bucket.
*
* In Google Cloud Platform environments, such as Cloud Functions and App
* Engine, you usually don't provide a `keyFilename` or `credentials` during
* instantiation. In those environments, we call the
* {@link https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob| signBlob API}
* to create a signed URL. That API requires either the
* `https://www.googleapis.com/auth/iam` or
* `https://www.googleapis.com/auth/cloud-platform` scope, so be sure they are
* enabled.
*
* See {@link https://cloud.google.com/storage/docs/access-control/signed-urls| Signed URLs Reference}
*
* @throws {Error} if an expiration timestamp from the past is given.
*
* @param {GetBucketSignedUrlConfig} config Configuration object.
* @param {string} config.action Currently only supports "list" (HTTP: GET).
* @param {*} config.expires A timestamp when this link will expire. Any value
* given is passed to `new Date()`.
* Note: 'v4' supports maximum duration of 7 days (604800 seconds) from now.
* @param {string} [config.version='v2'] The signing version to use, either
* 'v2' or 'v4'.
* @param {boolean} [config.virtualHostedStyle=false] Use virtual hosted-style
* URLs ('https://mybucket.storage.googleapis.com/...') instead of path-style
* ('https://storage.googleapis.com/mybucket/...'). Virtual hosted-style URLs
* should generally be preferred instaed of path-style URL.
* Currently defaults to `false` for path-style, although this may change in a
* future major-version release.
* @param {string} [config.cname] The cname for this bucket, i.e.,
* "https://cdn.example.com".
* See [reference]{@link https://cloud.google.com/storage/docs/access-control/signed-urls#example}
* @param {object} [config.extensionHeaders] If these headers are used, the
* server will check to make sure that the client provides matching
* values. See {@link https://cloud.google.com/storage/docs/access-control/signed-urls#about-canonical-extension-headers| Canonical extension headers}
* for the requirements of this feature, most notably:
* - The header name must be prefixed with `x-goog-`
* - The header name must be all lowercase
*
* Note: Multi-valued header passed as an array in the extensionHeaders
* object is converted into a string, delimited by `,` with
* no space. Requests made using the signed URL will need to
* delimit multi-valued headers using a single `,` as well, or
* else the server will report a mismatched signature.
* @property {object} [config.queryParams] Additional query parameters to include
* in the signed URL.
* @param {GetSignedUrlCallback} [callback] Callback function.
* @returns {Promise}
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const myBucket = storage.bucket('my-bucket');
*
* //-
* // Generate a URL that allows temporary access to list files in a bucket.
* //-
* const request = require('request');
*
* const config = {
* action: 'list',
* expires: '03-17-2025'
* };
*
* bucket.getSignedUrl(config, function(err, url) {
* if (err) {
* console.error(err);
* return;
* }
*
* // The bucket is now available to be listed from this URL.
* request(url, function(err, resp) {
* // resp.statusCode = 200
* });
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.getSignedUrl(config).then(function(data) {
* const url = data[0];
* });
* ```
*/
getSignedUrl(cfg, callback) {
const method = BucketActionToHTTPMethod[cfg.action];
const signConfig = {
method,
expires: cfg.expires,
version: cfg.version,
cname: cfg.cname,
extensionHeaders: cfg.extensionHeaders || {},
queryParams: cfg.queryParams || {},
host: cfg.host,
signingEndpoint: cfg.signingEndpoint,
};
if (!this.signer) {
this.signer = new signer_js_1.URLSigner(this.storage.authClient, this, undefined, this.storage);
}
this.signer
.getSignedUrl(signConfig)
.then(signedUrl => callback(null, signedUrl), callback);
}
/**
* @callback BucketLockCallback
* @param {?Error} err Request error, if any.
* @param {object} apiResponse The full API response.
*/
/**
* Lock a previously-defined retention policy. This will prevent changes to
* the policy.
*
* @throws {Error} if a metageneration is not provided.
*
* @param {number|string} metageneration The bucket's metageneration. This is
* accesssible from calling {@link File#getMetadata}.
* @param {BucketLockCallback} [callback] Callback function.
* @returns {Promise}
*
* @example
* ```
* const storage = require('@google-cloud/storage')();
* const bucket = storage.bucket('albums');
*
* const metageneration = 2;
*
* bucket.lock(metageneration, function(err, apiResponse) {});
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.lock(metageneration).then(function(data) {
* const apiResponse = data[0];
* });
* ```
*/
lock(metageneration, callback) {
const metatype = typeof metageneration;
if (metatype !== 'number' && metatype !== 'string') {
throw new Error(BucketExceptionMessages.METAGENERATION_NOT_PROVIDED);
}
this.request({
method: 'POST',
uri: '/lockRetentionPolicy',
qs: {
ifMetagenerationMatch: metageneration,
},
}, callback);
}
/**
* @typedef {array} MakeBucketPrivateResponse
* @property {File[]} 0 List of files made private.
*/
/**
* @callback MakeBucketPrivateCallback
* @param {?Error} err Request error, if any.
* @param {File[]} files List of files made private.
*/
/**
* @typedef {object} MakeBucketPrivateOptions
* @property {boolean} [includeFiles=false] Make each file in the bucket
* private.
* @property {Metadata} [metadata] Define custom metadata properties to define
* along with the operation.
* @property {boolean} [force] Queue errors occurred while making files
* private until all files have been processed.
* @property {string} [userProject] The ID of the project which will be
* billed for the request.
*/
/**
* Make the bucket listing private.
*
* You may also choose to make the contents of the bucket private by
* specifying `includeFiles: true`. This will automatically run
* {@link File#makePrivate} for every file in the bucket.
*
* When specifying `includeFiles: true`, use `force: true` to delay execution
* of your callback until all files have been processed. By default, the
* callback is executed after the first error. Use `force` to queue such
* errors until all files have been processed, after which they will be
* returned as an array as the first argument to your callback.
*
* NOTE: This may cause the process to be long-running and use a high number
* of requests. Use with caution.
*
* See {@link https://cloud.google.com/storage/docs/json_api/v1/buckets/patch| Buckets: patch API Documentation}
*
* @param {MakeBucketPrivateOptions} [options] Configuration options.
* @param {boolean} [options.includeFiles=false] Make each file in the bucket
* private.
* @param {Metadata} [options.metadata] Define custom metadata properties to define
* along with the operation.
* @param {boolean} [options.force] Queue errors occurred while making files
* private until all files have been processed.
* @param {string} [options.userProject] The ID of the project which will be
* billed for the request.
* @param {MakeBucketPrivateCallback} [callback] Callback function.
* @returns {Promise}
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('albums');
*
* //-
* // Make the bucket private.
* //-
* bucket.makePrivate(function(err) {});
*
* //-
* // Make the bucket and its contents private.
* //-
* const opts = {
* includeFiles: true
* };
*
* bucket.makePrivate(opts, function(err, files) {
* // `err`:
* // The first error to occur, otherwise null.
* //
* // `files`:
* // Array of files successfully made private in the bucket.
* });
*
* //-
* // Make the bucket and its contents private, using force to suppress errors
* // until all files have been processed.
* //-
* const opts = {
* includeFiles: true,
* force: true
* };
*
* bucket.makePrivate(opts, function(errors, files) {
* // `errors`:
* // Array of errors if any occurred, otherwise null.
* //
* // `files`:
* // Array of files successfully made private in the bucket.
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.makePrivate(opts).then(function(data) {
* const files = data[0];
* });
* ```
*/
makePrivate(optionsOrCallback, callback) {
var _a, _b, _c, _d;
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
callback =
typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
options.private = true;
const query = {
predefinedAcl: 'projectPrivate',
};
if (options.userProject) {
query.userProject = options.userProject;
}
if ((_a = options.preconditionOpts) === null || _a === void 0 ? void 0 : _a.ifGenerationMatch) {
query.ifGenerationMatch = options.preconditionOpts.ifGenerationMatch;
}
if ((_b = options.preconditionOpts) === null || _b === void 0 ? void 0 : _b.ifGenerationNotMatch) {
query.ifGenerationNotMatch =
options.preconditionOpts.ifGenerationNotMatch;
}
if ((_c = options.preconditionOpts) === null || _c === void 0 ? void 0 : _c.ifMetagenerationMatch) {
query.ifMetagenerationMatch =
options.preconditionOpts.ifMetagenerationMatch;
}
if ((_d = options.preconditionOpts) === null || _d === void 0 ? void 0 : _d.ifMetagenerationNotMatch) {
query.ifMetagenerationNotMatch =
options.preconditionOpts.ifMetagenerationNotMatch;
}
// You aren't allowed to set both predefinedAcl & acl properties on a bucket
// so acl must explicitly be nullified.
const metadata = { ...options.metadata, acl: null };
this.setMetadata(metadata, query, (err) => {
if (err) {
callback(err);
}
const internalCall = () => {
if (options.includeFiles) {
return (0, util_1.promisify)(this.makeAllFilesPublicPrivate_).call(this, options);
}
return Promise.resolve([]);
};
internalCall()
.then(files => callback(null, files))
.catch(callback);
});
}
/**
* @typedef {object} MakeBucketPublicOptions
* @property {boolean} [includeFiles=false] Make each file in the bucket
* private.
* @property {boolean} [force] Queue errors occurred while making files
* private until all files have been processed.
*/
/**
* @callback MakeBucketPublicCallback
* @param {?Error} err Request error, if any.
* @param {File[]} files List of files made public.
*/
/**
* @typedef {array} MakeBucketPublicResponse
* @property {File[]} 0 List of files made public.
*/
/**
* Make the bucket publicly readable.
*
* You may also choose to make the contents of the bucket publicly readable by
* specifying `includeFiles: true`. This will automatically run
* {@link File#makePublic} for every file in the bucket.
*
* When specifying `includeFiles: true`, use `force: true` to delay execution
* of your callback until all files have been processed. By default, the
* callback is executed after the first error. Use `force` to queue such
* errors until all files have been processed, after which they will be
* returned as an array as the first argument to your callback.
*
* NOTE: This may cause the process to be long-running and use a high number
* of requests. Use with caution.
*
* See {@link https://cloud.google.com/storage/docs/json_api/v1/buckets/patch| Buckets: patch API Documentation}
*
* @param {MakeBucketPublicOptions} [options] Configuration options.
* @param {boolean} [options.includeFiles=false] Make each file in the bucket
* private.
* @param {boolean} [options.force] Queue errors occurred while making files
* private until all files have been processed.
* @param {MakeBucketPublicCallback} [callback] Callback function.
* @returns {Promise}
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('albums');
*
* //-
* // Make the bucket publicly readable.
* //-
* bucket.makePublic(function(err) {});
*
* //-
* // Make the bucket and its contents publicly readable.
* //-
* const opts = {
* includeFiles: true
* };
*
* bucket.makePublic(opts, function(err, files) {
* // `err`:
* // The first error to occur, otherwise null.
* //
* // `files`:
* // Array of files successfully made public in the bucket.
* });
*
* //-
* // Make the bucket and its contents publicly readable, using force to
* // suppress errors until all files have been processed.
* //-
* const opts = {
* includeFiles: true,
* force: true
* };
*
* bucket.makePublic(opts, function(errors, files) {
* // `errors`:
* // Array of errors if any occurred, otherwise null.
* //
* // `files`:
* // Array of files successfully made public in the bucket.
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.makePublic(opts).then(function(data) {
* const files = data[0];
* });
* ```
*/
makePublic(optionsOrCallback, callback) {
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
callback =
typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
const req = { public: true, ...options };
this.acl
.add({
entity: 'allUsers',
role: 'READER',
})
.then(() => {
return this.acl.default.add({
entity: 'allUsers',
role: 'READER',
});
})
.then(() => {
if (req.includeFiles) {
return (0, util_1.promisify)(this.makeAllFilesPublicPrivate_).call(this, req);
}
return [];
})
.then(files => callback(null, files), callback);
}
/**
* Get a reference to a Cloud Pub/Sub Notification.
*
* @param {string} id ID of notification.
* @returns {Notification}
* @see Notification
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('my-bucket');
* const notification = bucket.notification('1');
* ```
*/
notification(id) {
if (!id) {
throw new Error(BucketExceptionMessages.SUPPLY_NOTIFICATION_ID);
}
return new notification_js_1.Notification(this, id);
}
/**
* Remove an already-existing retention policy from this bucket, if it is not
* locked.
*
* @param {SetBucketMetadataCallback} [callback] Callback function.
* @param {SetBucketMetadataOptions} [options] Options, including precondition options
* @returns {Promise}
*
* @example
* ```
* const storage = require('@google-cloud/storage')();
* const bucket = storage.bucket('albums');
*
* bucket.removeRetentionPeriod(function(err, apiResponse) {});
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.removeRetentionPeriod().then(function(data) {
* const apiResponse = data[0];
* });
* ```
*/
removeRetentionPeriod(optionsOrCallback, callback) {
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
callback =
typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
this.setMetadata({
retentionPolicy: null,
}, options, callback);
}
/**
* Makes request and applies userProject query parameter if necessary.
*
* @private
*
* @param {object} reqOpts - The request options.
* @param {function} callback - The callback function.
*/
request(reqOpts, callback) {
if (this.userProject && (!reqOpts.qs || !reqOpts.qs.userProject)) {
reqOpts.qs = { ...reqOpts.qs, userProject: this.userProject };
}
return super.request(reqOpts, callback);
}
/**
* @deprecated
* @typedef {array} SetLabelsResponse
* @property {object} 0 The bucket metadata.
*/
/**
* @deprecated
* @callback SetLabelsCallback
* @param {?Error} err Request error, if any.
* @param {object} metadata The bucket metadata.
*/
/**
* @deprecated
* @typedef {object} SetLabelsOptions Configuration options for Bucket#setLabels().
* @property {string} [userProject] The ID of the project which will be
* billed for the request.
*/
/**
* @deprecated Use setMetadata directly.
* Set labels on the bucket.
*
* This makes an underlying call to {@link Bucket#setMetadata}, which
* is a PATCH request. This means an individual label can be overwritten, but
* unmentioned labels will not be touched.
*
* @param {object} labels Labels to set on the bucket.
* @param {SetLabelsOptions} [options] Configuration options.
* @param {string} [options.userProject] The ID of the project which will be
* billed for the request.
* @param {SetLabelsCallback} [callback] Callback function.
* @returns {Promise}
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('albums');
*
* const labels = {
* labelone: 'labelonevalue',
* labeltwo: 'labeltwovalue'
* };
*
* bucket.setLabels(labels, function(err, metadata) {
* if (!err) {
* // Labels set successfully.
* }
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.setLabels(labels).then(function(data) {
* const metadata = data[0];
* });
* ```
*/
setLabels(labels, optionsOrCallback, callback) {
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
callback =
typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
callback = callback || index_js_1.util.noop;
this.setMetadata({ labels }, options, callback);
}
setMetadata(metadata, optionsOrCallback, cb) {
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
cb =
typeof optionsOrCallback === 'function'
? optionsOrCallback
: cb;
this.disableAutoRetryConditionallyIdempotent_(this.methods.setMetadata, AvailableServiceObjectMethods.setMetadata, options);
super
.setMetadata(metadata, options)
.then(resp => cb(null, ...resp))
.catch(cb)
.finally(() => {
this.storage.retryOptions.autoRetry = this.instanceRetryValue;
});
}
/**
* Lock all objects contained in the bucket, based on their creation time. Any
* attempt to overwrite or delete objects younger than the retention period
* will result in a `PERMISSION_DENIED` error.
*
* An unlocked retention policy can be modified or removed from the bucket via
* {@link File#removeRetentionPeriod} and {@link File#setRetentionPeriod}. A
* locked retention policy cannot be removed or shortened in duration for the
* lifetime of the bucket. Attempting to remove or decrease period of a locked
* retention policy will result in a `PERMISSION_DENIED` error. You can still
* increase the policy.
*
* @param {*} duration In seconds, the minimum retention time for all objects
* contained in this bucket.
* @param {SetBucketMetadataCallback} [callback] Callback function.
* @param {SetBucketMetadataCallback} [options] Options, including precondition options.
* @returns {Promise}
*
* @example
* ```
* const storage = require('@google-cloud/storage')();
* const bucket = storage.bucket('albums');
*
* const DURATION_SECONDS = 15780000; // 6 months.
*
* //-
* // Lock the objects in this bucket for 6 months.
* //-
* bucket.setRetentionPeriod(DURATION_SECONDS, function(err, apiResponse) {});
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.setRetentionPeriod(DURATION_SECONDS).then(function(data) {
* const apiResponse = data[0];
* });
* ```
*/
setRetentionPeriod(duration, optionsOrCallback, callback) {
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
callback =
typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
this.setMetadata({
retentionPolicy: {
retentionPeriod: duration.toString(),
},
}, options, callback);
}
/**
*
* @typedef {object} Cors
* @property {number} [maxAgeSeconds] The number of seconds the browser is
* allowed to make requests before it must repeat the preflight request.
* @property {string[]} [method] HTTP method allowed for cross origin resource
* sharing with this bucket.
* @property {string[]} [origin] an origin allowed for cross origin resource
* sharing with this bucket.
* @property {string[]} [responseHeader] A header allowed for cross origin
* resource sharing with this bucket.
*/
/**
* This can be used to set the CORS configuration on the bucket.
*
* The configuration will be overwritten with the value passed into this.
*
* @param {Cors[]} corsConfiguration The new CORS configuration to set
* @param {number} [corsConfiguration.maxAgeSeconds] The number of seconds the browser is
* allowed to make requests before it must repeat the preflight request.
* @param {string[]} [corsConfiguration.method] HTTP method allowed for cross origin resource
* sharing with this bucket.
* @param {string[]} [corsConfiguration.origin] an origin allowed for cross origin resource
* sharing with this bucket.
* @param {string[]} [corsConfiguration.responseHeader] A header allowed for cross origin
* resource sharing with this bucket.
* @param {SetBucketMetadataCallback} [callback] Callback function.
* @param {SetBucketMetadataOptions} [options] Options, including precondition options.
* @returns {Promise}
*
* @example
* ```
* const storage = require('@google-cloud/storage')();
* const bucket = storage.bucket('albums');
*
* const corsConfiguration = [{maxAgeSeconds: 3600}]; // 1 hour
* bucket.setCorsConfiguration(corsConfiguration);
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.setCorsConfiguration(corsConfiguration).then(function(data) {
* const apiResponse = data[0];
* });
* ```
*/
setCorsConfiguration(corsConfiguration, optionsOrCallback, callback) {
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
callback =
typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
this.setMetadata({
cors: corsConfiguration,
}, options, callback);
}
/**
* @typedef {object} SetBucketStorageClassOptions
* @property {string} [userProject] - The ID of the project which will be
* billed for the request.
*/
/**
* @callback SetBucketStorageClassCallback
* @param {?Error} err Request error, if any.
*/
/**
* Set the default storage class for new files in this bucket.
*
* See {@link https://cloud.google.com/storage/docs/storage-classes| Storage Classes}
*
* @param {string} storageClass The new storage class. (`standard`,
* `nearline`, `coldline`, or `archive`).
* **Note:** The storage classes `multi_regional`, `regional`, and
* `durable_reduced_availability` are now legacy and will be deprecated in
* the future.
* @param {object} [options] Configuration options.
* @param {string} [options.userProject] - The ID of the project which will be
* billed for the request.
* @param {SetStorageClassCallback} [callback] Callback function.
* @returns {Promise}
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('albums');
*
* bucket.setStorageClass('nearline', function(err, apiResponse) {
* if (err) {
* // Error handling omitted.
* }
*
* // The storage class was updated successfully.
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.setStorageClass('nearline').then(function() {});
* ```
*/
setStorageClass(storageClass, optionsOrCallback, callback) {
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
callback =
typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
// In case we get input like `storageClass`, convert to `storage_class`.
storageClass = storageClass
.replace(/-/g, '_')
.replace(/([a-z])([A-Z])/g, (_, low, up) => {
return low + '_' + up;
})
.toUpperCase();
this.setMetadata({ storageClass }, options, callback);
}
/**
* Set a user project to be billed for all requests made from this Bucket
* object and any files referenced from this Bucket object.
*
* @param {string} userProject The user project.
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('albums');
*
* bucket.setUserProject('grape-spaceship-123');
* ```
*/
setUserProject(userProject) {
this.userProject = userProject;
const methods = [
'create',
'delete',
'exists',
'get',
'getMetadata',
'setMetadata',
];
methods.forEach(method => {
const methodConfig = this.methods[method];
if (typeof methodConfig === 'object') {
if (typeof methodConfig.reqOpts === 'object') {
Object.assign(methodConfig.reqOpts.qs, { userProject });
}
else {
methodConfig.reqOpts = {
qs: { userProject },
};
}
}
});
}
/**
* @typedef {object} UploadOptions Configuration options for Bucket#upload().
* @property {string|File} [destination] The place to save
* your file. If given a string, the file will be uploaded to the bucket
* using the string as a filename. When given a File object, your local
* file will be uploaded to the File object's bucket and under the File
* object's name. Lastly, when this argument is omitted, the file is uploaded
* to your bucket using the name of the local file.
* @property {string} [encryptionKey] A custom encryption key. See
* {@link https://cloud.google.com/storage/docs/encryption#customer-supplied| Customer-supplied Encryption Keys}.
* @property {boolean} [gzip] Automatically gzip the file. This will set
* `options.metadata.contentEncoding` to `gzip`.
* @property {string} [kmsKeyName] The name of the Cloud KMS key that will
* be used to encrypt the object. Must be in the format:
* `projects/my-project/locations/location/keyRings/my-kr/cryptoKeys/my-key`.
* @property {object} [metadata] See an
* {@link https://cloud.google.com/storage/docs/json_api/v1/objects/insert#request_properties_JSON| Objects: insert request body}.
* @property {string} [offset] The starting byte of the upload stream, for
* resuming an interrupted upload. Defaults to 0.
* @property {string} [predefinedAcl] Apply a predefined set of access
* controls to this object.
*
* Acceptable values are:
* - **`authenticatedRead`** - Object owner gets `OWNER` access, and
* `allAuthenticatedUsers` get `READER` access.
*
* - **`bucketOwnerFullControl`** - Object owner gets `OWNER` access, and
* project team owners get `OWNER` access.
*
* - **`bucketOwnerRead`** - Object owner gets `OWNER` access, and project
* team owners get `READER` access.
*
* - **`private`** - Object owner gets `OWNER` access.
*
* - **`projectPrivate`** - Object owner gets `OWNER` access, and project
* team members get access according to their roles.
*
* - **`publicRead`** - Object owner gets `OWNER` access, and `allUsers`
* get `READER` access.
* @property {boolean} [private] Make the uploaded file private. (Alias for
* `options.predefinedAcl = 'private'`)
* @property {boolean} [public] Make the uploaded file public. (Alias for
* `options.predefinedAcl = 'publicRead'`)
* @property {boolean} [resumable=true] Resumable uploads are automatically
* enabled and must be shut off explicitly by setting to false.
* @property {number} [timeout=60000] Set the HTTP request timeout in
* milliseconds. This option is not available for resumable uploads.
* Default: `60000`
* @property {string} [uri] The URI for an already-created resumable
* upload. See {@link File#createResumableUpload}.
* @property {string} [userProject] The ID of the project which will be
* billed for the request.
* @property {string|boolean} [validation] Possible values: `"md5"`,
* `"crc32c"`, or `false`. By default, data integrity is validated with an
* MD5 checksum for maximum reliability. CRC32c will provide better
* performance with less reliability. You may also choose to skip
* validation completely, however this is **not recommended**.
*/
/**
* @typedef {array} UploadResponse
* @property {object} 0 The uploaded {@link File}.
* @property {object} 1 The full API response.
*/
/**
* @callback UploadCallback
* @param {?Error} err Request error, if any.
* @param {object} file The uploaded {@link File}.
* @param {object} apiResponse The full API response.
*/
/**
* Upload a file to the bucket. This is a convenience method that wraps
* {@link File#createWriteStream}.
*
* Resumable uploads are enabled by default
*
* See {@link https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload#uploads| Upload Options (Simple or Resumable)}
* See {@link https://cloud.google.com/storage/docs/json_api/v1/objects/insert| Objects: insert API Documentation}
*
* @param {string} pathString The fully qualified path to the file you
* wish to upload to your bucket.
* @param {UploadOptions} [options] Configuration options.
* @param {string|File} [options.destination] The place to save
* your file. If given a string, the file will be uploaded to the bucket
* using the string as a filename. When given a File object, your local
* file will be uploaded to the File object's bucket and under the File
* object's name. Lastly, when this argument is omitted, the file is uploaded
* to your bucket using the name of the local file.
* @param {string} [options.encryptionKey] A custom encryption key. See
* {@link https://cloud.google.com/storage/docs/encryption#customer-supplied| Customer-supplied Encryption Keys}.
* @param {boolean} [options.gzip] Automatically gzip the file. This will set
* `options.metadata.contentEncoding` to `gzip`.
* @param {string} [options.kmsKeyName] The name of the Cloud KMS key that will
* be used to encrypt the object. Must be in the format:
* `projects/my-project/locations/location/keyRings/my-kr/cryptoKeys/my-key`.
* @param {object} [options.metadata] See an
* {@link https://cloud.google.com/storage/docs/json_api/v1/objects/insert#request_properties_JSON| Objects: insert request body}.
* @param {string} [options.offset] The starting byte of the upload stream, for
* resuming an interrupted upload. Defaults to 0.
* @param {string} [options.predefinedAcl] Apply a predefined set of access
* controls to this object.
* Acceptable values are:
* - **`authenticatedRead`** - Object owner gets `OWNER` access, and
* `allAuthenticatedUsers` get `READER` access.
*
* - **`bucketOwnerFullControl`** - Object owner gets `OWNER` access, and
* project team owners get `OWNER` access.
*
* - **`bucketOwnerRead`** - Object owner gets `OWNER` access, and project
* team owners get `READER` access.
*
* - **`private`** - Object owner gets `OWNER` access.
*
* - **`projectPrivate`** - Object owner gets `OWNER` access, and project
* team members get access according to their roles.
*
* - **`publicRead`** - Object owner gets `OWNER` access, and `allUsers`
* get `READER` access.
* @param {boolean} [options.private] Make the uploaded file private. (Alias for
* `options.predefinedAcl = 'private'`)
* @param {boolean} [options.public] Make the uploaded file public. (Alias for
* `options.predefinedAcl = 'publicRead'`)
* @param {boolean} [options.resumable=true] Resumable uploads are automatically
* enabled and must be shut off explicitly by setting to false.
* @param {number} [options.timeout=60000] Set the HTTP request timeout in
* milliseconds. This option is not available for resumable uploads.
* Default: `60000`
* @param {string} [options.uri] The URI for an already-created resumable
* upload. See {@link File#createResumableUpload}.
* @param {string} [options.userProject] The ID of the project which will be
* billed for the request.
* @param {string|boolean} [options.validation] Possible values: `"md5"`,
* `"crc32c"`, or `false`. By default, data integrity is validated with an
* MD5 checksum for maximum reliability. CRC32c will provide better
* performance with less reliability. You may also choose to skip
* validation completely, however this is **not recommended**.
* @param {UploadCallback} [callback] Callback function.
* @returns {Promise}
*
* @example
* ```
* const {Storage} = require('@google-cloud/storage');
* const storage = new Storage();
* const bucket = storage.bucket('albums');
*
* //-
* // Upload a file from a local path.
* //-
* bucket.upload('/local/path/image.png', function(err, file, apiResponse) {
* // Your bucket now contains:
* // - "image.png" (with the contents of `/local/path/image.png')
*
* // `file` is an instance of a File object that refers to your new file.
* });
*
*
* //-
* // It's not always that easy. You will likely want to specify the filename
* // used when your new file lands in your bucket.
* //
* // You may also want to set metadata or customize other options.
* //-
* const options = {
* destination: 'new-image.png',
* validation: 'crc32c',
* metadata: {
* metadata: {
* event: 'Fall trip to the zoo'
* }
* }
* };
*
* bucket.upload('local-image.png', options, function(err, file) {
* // Your bucket now contains:
* // - "new-image.png" (with the contents of `local-image.png')
*
* // `file` is an instance of a File object that refers to your new file.
* });
*
* //-
* // You can also have a file gzip'd on the fly.
* //-
* bucket.upload('index.html', { gzip: true }, function(err, file) {
* // Your bucket now contains:
* // - "index.html" (automatically compressed with gzip)
*
* // Downloading the file with `file.download` will automatically decode
* the
* // file.
* });
*
* //-
* // You may also re-use a File object, {File}, that references
* // the file you wish to create or overwrite.
* //-
* const options = {
* destination: bucket.file('existing-file.png'),
* resumable: false
* };
*
* bucket.upload('local-img.png', options, function(err, newFile) {
* // Your bucket now contains:
* // - "existing-file.png" (with the contents of `local-img.png')
*
* // Note:
* // The `newFile` parameter is equal to `file`.
* });
*
* //-
* // To use
* //
* // Customer-supplied Encryption Keys, provide the `encryptionKey`
* option.
* //-
* const crypto = require('crypto');
* const encryptionKey = crypto.randomBytes(32);
*
* bucket.upload('img.png', {
* encryptionKey: encryptionKey
* }, function(err, newFile) {
* // `img.png` was uploaded with your custom encryption key.
*
* // `newFile` is already configured to use the encryption key when making
* // operations on the remote object.
*
* // However, to use your encryption key later, you must create a `File`
* // instance with the `key` supplied:
* const file = bucket.file('img.png', {
* encryptionKey: encryptionKey
* });
*
* // Or with `file#setEncryptionKey`:
* const file = bucket.file('img.png');
* file.setEncryptionKey(encryptionKey);
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* bucket.upload('local-image.png').then(function(data) {
* const file = data[0];
* });
*
* To upload a file from a URL, use {@link File#createWriteStream}.
*
* ```
* @example include:samples/files.js
* region_tag:storage_upload_file
* Another example:
*
* @example include:samples/encryption.js
* region_tag:storage_upload_encrypted_file
* Example of uploading an encrypted file:
*/
upload(pathString, optionsOrCallback, callback) {
var _a, _b;
const upload = (numberOfRetries) => {
const returnValue = (0, async_retry_1.default)(async (bail) => {
await new Promise((resolve, reject) => {
var _a, _b;
if (numberOfRetries === 0 &&
((_b = (_a = newFile === null || newFile === void 0 ? void 0 : newFile.storage) === null || _a === void 0 ? void 0 : _a.retryOptions) === null || _b === void 0 ? void 0 : _b.autoRetry)) {
newFile.storage.retryOptions.autoRetry = false;
}
const writable = newFile.createWriteStream(options);
if (options.onUploadProgress) {
writable.on('progress', options.onUploadProgress);
}
fs.createReadStream(pathString)
.on('error', bail)
.pipe(writable)
.on('error', err => {
if (this.storage.retryOptions.autoRetry &&
this.storage.retryOptions.retryableErrorFn(err)) {
return reject(err);
}
else {
return bail(err);
}
})
.on('finish', () => {
return resolve();
});
});
}, {
retries: numberOfRetries,
factor: this.storage.retryOptions.retryDelayMultiplier,
maxTimeout: this.storage.retryOptions.maxRetryDelay * 1000, //convert to milliseconds
maxRetryTime: this.storage.retryOptions.totalTimeout * 1000, //convert to milliseconds
});
if (!callback) {
return returnValue;
}
else {
return returnValue
.then(() => {
if (callback) {
return callback(null, newFile, newFile.metadata);
}
})
.catch(callback);
}
};
// eslint-disable-next-line @typescript-eslint/no-explicit-any
if (global['GCLOUD_SANDBOX_ENV']) {
return;
}
let options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
callback =
typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
options = Object.assign({
metadata: {},
}, options);
// Do not retry if precondition option ifGenerationMatch is not set
// because this is a file operation
let maxRetries = this.storage.retryOptions.maxRetries;
if ((((_a = options === null || options === void 0 ? void 0 : options.preconditionOpts) === null || _a === void 0 ? void 0 : _a.ifGenerationMatch) === undefined &&
((_b = this.instancePreconditionOpts) === null || _b === void 0 ? void 0 : _b.ifGenerationMatch) === undefined &&
this.storage.retryOptions.idempotencyStrategy ===
storage_js_1.IdempotencyStrategy.RetryConditional) ||
this.storage.retryOptions.idempotencyStrategy ===
storage_js_1.IdempotencyStrategy.RetryNever) {
maxRetries = 0;
}
let newFile;
if (options.destination instanceof file_js_1.File) {
newFile = options.destination;
}
else if (options.destination !== null &&
typeof options.destination === 'string') {
// Use the string as the name of the file.
newFile = this.file(options.destination, {
encryptionKey: options.encryptionKey,
kmsKeyName: options.kmsKeyName,
preconditionOpts: this.instancePreconditionOpts,
});
}
else {
// Resort to using the name of the incoming file.
const destination = path.basename(pathString);
newFile = this.file(destination, {
encryptionKey: options.encryptionKey,
kmsKeyName: options.kmsKeyName,
preconditionOpts: this.instancePreconditionOpts,
});
}
upload(maxRetries);
}
/**
* @private
*
* @typedef {object} MakeAllFilesPublicPrivateOptions
* @property {boolean} [force] Suppress errors until all files have been
* processed.
* @property {boolean} [private] Make files private.
* @property {boolean} [public] Make files public.
* @property {string} [userProject] The ID of the project which will be
* billed for the request.
*/
/**
* @private
*
* @callback SetBucketMetadataCallback
* @param {?Error} err Request error, if any.
* @param {File[]} files Files that were updated.
*/
/**
* @typedef {array} MakeAllFilesPublicPrivateResponse
* @property {File[]} 0 List of files affected.
*/
/**
* Iterate over all of a bucket's files, calling `file.makePublic()` (public)
* or `file.makePrivate()` (private) on each.
*
* Operations are performed in parallel, up to 10 at once. The first error
* breaks the loop, and will execute the provided callback with it. Specify
* `{ force: true }` to suppress the errors.
*
* @private
*
* @param {MakeAllFilesPublicPrivateOptions} [options] Configuration options.
* @param {boolean} [options.force] Suppress errors until all files have been
* processed.
* @param {boolean} [options.private] Make files private.
* @param {boolean} [options.public] Make files public.
* @param {string} [options.userProject] The ID of the project which will be
* billed for the request.
* @param {MakeAllFilesPublicPrivateCallback} callback Callback function.
*
* @return {Promise}
*/
makeAllFilesPublicPrivate_(optionsOrCallback, callback) {
const MAX_PARALLEL_LIMIT = 10;
const errors = [];
const updatedFiles = [];
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
callback =
typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
const processFile = async (file) => {
try {
await (options.public ? file.makePublic() : file.makePrivate(options));
updatedFiles.push(file);
}
catch (e) {
if (!options.force) {
throw e;
}
errors.push(e);
}
};
this.getFiles(options)
.then(([files]) => {
const limit = (0, p_limit_1.default)(MAX_PARALLEL_LIMIT);
const promises = files.map(file => {
return limit(() => processFile(file));
});
return Promise.all(promises);
})
.then(() => callback(errors.length > 0 ? errors : null, updatedFiles), err => callback(err, updatedFiles));
}
getId() {
return this.id;
}
disableAutoRetryConditionallyIdempotent_(
// eslint-disable-next-line @typescript-eslint/no-explicit-any
coreOpts,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
methodType, localPreconditionOptions) {
var _a, _b;
if (typeof coreOpts === 'object' &&
((_b = (_a = coreOpts === null || coreOpts === void 0 ? void 0 : coreOpts.reqOpts) === null || _a === void 0 ? void 0 : _a.qs) === null || _b === void 0 ? void 0 : _b.ifMetagenerationMatch) === undefined &&
(localPreconditionOptions === null || localPreconditionOptions === void 0 ? void 0 : localPreconditionOptions.ifMetagenerationMatch) === undefined &&
(methodType === AvailableServiceObjectMethods.setMetadata ||
methodType === AvailableServiceObjectMethods.delete) &&
this.storage.retryOptions.idempotencyStrategy ===
storage_js_1.IdempotencyStrategy.RetryConditional) {
this.storage.retryOptions.autoRetry = false;
}
else if (this.storage.retryOptions.idempotencyStrategy ===
storage_js_1.IdempotencyStrategy.RetryNever) {
this.storage.retryOptions.autoRetry = false;
}
}
}
exports.Bucket = Bucket;
/*! Developer Documentation
*
* These methods can be auto-paginated.
*/
paginator_1.paginator.extend(Bucket, 'getFiles');
/*! Developer Documentation
*
* All async methods (except for streams) will return a Promise in the event
* that a callback is omitted.
*/
(0, promisify_1.promisifyAll)(Bucket, {
exclude: ['cloudStorageURI', 'request', 'file', 'notification'],
});