Class File (6.7.0)

A File object is created from your Bucket object using .

Inheritance

ServiceObject<File> > File

Package

Constructors

(constructor)(bucket, name, options)

constructor(bucket: Bucket, name: string, options?: FileOptions);

Constructs a file object.

Parameters
Name	Description
`bucket`	`Bucket` The Bucket instance this file is attached to.
`name`	`string` The name of the remote file.
`options`	`FileOptions` Configuration options.

Example


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

const file = myBucket.file('my-file');

Properties

acl

acl: Acl;

bucket

bucket: Bucket;

cloudStorageURI

get cloudStorageURI(): URL;

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

Example

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

// gs://my-bucket/image.png const href = file.cloudStorageURI.href;

crc32cGenerator

crc32cGenerator: CRC32CValidatorGenerator;

generation

generation?: number;

instancePreconditionOpts

instancePreconditionOpts?: PreconditionOptions;

kmsKeyName

kmsKeyName?: string;

metadata

metadata: Metadata;

name

name: string;

parent

parent: Bucket;

signer

signer?: URLSigner;

storage

storage: Storage;

userProject

userProject?: string;

Methods

copy(destination, options)

copy(destination: string | Bucket | File, options?: CopyOptions): Promise<CopyResponse>;

Parameters
Name	Description
`destination`	`string \| Bucket \| File`
`options`	`CopyOptions`

Returns
Type	Description
`Promise<CopyResponse>`

copy(destination, callback)

copy(destination: string | Bucket | File, callback: CopyCallback): void;

Parameters
Name	Description
`destination`	`string \| Bucket \| File`
`callback`	`CopyCallback`

Returns
Type	Description
`void`

copy(destination, options, callback)

copy(destination: string | Bucket | File, options: CopyOptions, callback: CopyCallback): void;

Parameters
Name	Description
`destination`	`string \| Bucket \| File`
`options`	`CopyOptions`
`callback`	`CopyCallback`

Returns
Type	Description
`void`

createReadStream(options)

createReadStream(options?: CreateReadStreamOptions): Readable;

Create a readable stream to read the contents of the remote file. It can be piped to a writable stream or listened to for 'data' events to read a file's contents.

In the unlikely event there is a mismatch between what you downloaded and the version in your Bucket, your error handler will receive an error with code "CONTENT_DOWNLOAD_MISMATCH". If you receive this error, the best recourse is to try downloading the file again.

NOTE: Readable streams will emit the end event when the file is fully downloaded.

Parameter
Name	Description
`options`	`CreateReadStreamOptions` Configuration options.

Returns
Type	Description
`Readable`	{ReadableStream}

Example

//- //

Downloading a File

// // The example below demonstrates how we can reference a remote file, then // pipe its contents to a local file. This is effectively creating a local // backup of your remote data. //- const {Storage} = require('@google-cloud/storage'); const storage = new Storage(); const bucket = storage.bucket('my-bucket');

const fs = require('fs'); const remoteFile = bucket.file('image.png'); const localFilename = '/Users/stephen/Photos/image.png';

remoteFile.createReadStream() .on('error', function(err) {}) .on('response', function(response) { // Server connected and responded with the specified status and headers. }) .on('end', function() { // The file is fully downloaded. }) .pipe(fs.createWriteStream(localFilename));

//- // To limit the downloaded data to only a byte range, pass an options // object. //- const logFile = myBucket.file('access_log'); logFile.createReadStream({ start: 10000, end: 20000 }) .on('error', function(err) {}) .pipe(fs.createWriteStream('/Users/stephen/logfile.txt'));

//- // To read a tail byte range, specify only options.end as a negative // number. //- const logFile = myBucket.file('access_log'); logFile.createReadStream({ end: -100 }) .on('error', function(err) {}) .pipe(fs.createWriteStream('/Users/stephen/logfile.txt'));

createResumableUpload(options)

createResumableUpload(options?: CreateResumableUploadOptions): Promise<CreateResumableUploadResponse>;

Parameter
Name	Description
`options`	`CreateResumableUploadOptions`

Returns
Type	Description
`Promise<CreateResumableUploadResponse>`

createResumableUpload(options, callback)

createResumableUpload(options: CreateResumableUploadOptions, callback: CreateResumableUploadCallback): void;

Parameters
Name	Description
`options`	`CreateResumableUploadOptions`
`callback`	`CreateResumableUploadCallback`

Returns
Type	Description
`void`

createResumableUpload(callback)

createResumableUpload(callback: CreateResumableUploadCallback): void;

Parameter
Name	Description
`callback`	`CreateResumableUploadCallback`

Returns
Type	Description
`void`

createWriteStream(options)

createWriteStream(options?: CreateWriteStreamOptions): Writable;

Create a writable stream to overwrite the contents of the file in your bucket.

A File object can also be used to create files for the first time.

Resumable uploads are automatically enabled and must be shut off explicitly by setting options.resumable to false.

There is some overhead when using a resumable upload that can cause noticeable performance degradation while uploading a series of small files. When uploading files less than 10MB, it is recommended that the resumable feature is disabled.

NOTE: Writable streams will emit the finish event when the file is fully uploaded.

See Upload Options (Simple or Resumable) See Objects: insert API Documentation

Parameter
Name	Description
`options`	`CreateWriteStreamOptions` Configuration options.

Returns
Type	Description
`Writable`	{WritableStream}

Example

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

const file = myBucket.file('my-file');

//- //

Uploading a File

// // Now, consider a case where we want to upload a file to your bucket. You // have the option of using {@link Bucket#upload}, but that is just // a convenience method which will do the following. //- fs.createReadStream('/Users/stephen/Photos/birthday-at-the-zoo/panda.jpg') .pipe(file.createWriteStream()) .on('error', function(err) {}) .on('finish', function() { // The file upload is complete. });

//- //

Uploading a File with gzip compression

//- fs.createReadStream('/Users/stephen/site/index.html') .pipe(file.createWriteStream({ gzip: true })) .on('error', function(err) {}) .on('finish', function() { // The file upload is complete. });

//- // Downloading the file with createReadStream will automatically decode // the file. //-

//- //

Uploading a File with Metadata

// // One last case you may run into is when you want to upload a file to your // bucket and set its metadata at the same time. Like above, you can use // {@link Bucket#upload} to do this, which is just a wrapper around // the following. //- fs.createReadStream('/Users/stephen/Photos/birthday-at-the-zoo/panda.jpg') .pipe(file.createWriteStream({ metadata: { contentType: 'image/jpeg', metadata: { custom: 'metadata' } } })) .on('error', function(err) {}) .on('finish', function() { // The file upload is complete. });

delete(options)

delete(options?: DeleteOptions): Promise<[r.Response]>;

Delete the object.

Parameter
Name	Description
`options`	`DeleteOptions`

Returns
Type	Description
`Promise<[r.Response]>`

delete(options, callback)

delete(options: DeleteOptions, callback: DeleteCallback): void;

Parameters
Name	Description
`options`	`DeleteOptions`
`callback`	`DeleteCallback`

Returns
Type	Description
`void`

delete(callback)

delete(callback: DeleteCallback): void;

Parameter
Name	Description
`callback`	`DeleteCallback`

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`

download(options)

download(options?: DownloadOptions): Promise<DownloadResponse>;

Parameter
Name	Description
`options`	`DownloadOptions`

Returns
Type	Description
`Promise<DownloadResponse>`

download(options, callback)

download(options: DownloadOptions, callback: DownloadCallback): void;

Parameters
Name	Description
`options`	`DownloadOptions`
`callback`	`DownloadCallback`

Returns
Type	Description
`void`

download(callback)

download(callback: DownloadCallback): void;

Parameter
Name	Description
`callback`	`DownloadCallback`

Returns
Type	Description
`void`

generateSignedPostPolicyV2(options)

generateSignedPostPolicyV2(options: GenerateSignedPostPolicyV2Options): Promise<GenerateSignedPostPolicyV2Response>;

Parameter
Name	Description
`options`	`GenerateSignedPostPolicyV2Options`

Returns
Type	Description
`Promise<GenerateSignedPostPolicyV2Response>`

generateSignedPostPolicyV2(options, callback)

generateSignedPostPolicyV2(options: GenerateSignedPostPolicyV2Options, callback: GenerateSignedPostPolicyV2Callback): void;

Parameters
Name	Description
`options`	`GenerateSignedPostPolicyV2Options`
`callback`	`GenerateSignedPostPolicyV2Callback`

Returns
Type	Description
`void`

generateSignedPostPolicyV2(callback)

generateSignedPostPolicyV2(callback: GenerateSignedPostPolicyV2Callback): void;

Parameter
Name	Description
`callback`	`GenerateSignedPostPolicyV2Callback`

Returns
Type	Description
`void`

generateSignedPostPolicyV4(options)

generateSignedPostPolicyV4(options: GenerateSignedPostPolicyV4Options): Promise<GenerateSignedPostPolicyV4Response>;

Parameter
Name	Description
`options`	`GenerateSignedPostPolicyV4Options`

Returns
Type	Description
`Promise<GenerateSignedPostPolicyV4Response>`

generateSignedPostPolicyV4(options, callback)

generateSignedPostPolicyV4(options: GenerateSignedPostPolicyV4Options, callback: GenerateSignedPostPolicyV4Callback): void;

Parameters
Name	Description
`options`	`GenerateSignedPostPolicyV4Options`
`callback`	`GenerateSignedPostPolicyV4Callback`

Returns
Type	Description
`void`

generateSignedPostPolicyV4(callback)

generateSignedPostPolicyV4(callback: GenerateSignedPostPolicyV4Callback): void;

Parameter
Name	Description
`callback`	`GenerateSignedPostPolicyV4Callback`

Returns
Type	Description
`void`

getExpirationDate()

getExpirationDate(): Promise<GetExpirationDateResponse>;

Returns
Type	Description
`Promise<GetExpirationDateResponse>`

getExpirationDate(callback)

getExpirationDate(callback: GetExpirationDateCallback): void;

Parameter
Name	Description
`callback`	`GetExpirationDateCallback`

Returns
Type	Description
`void`

getSignedUrl(cfg)

getSignedUrl(cfg: GetSignedUrlConfig): Promise<GetSignedUrlResponse>;

Parameter
Name	Description
`cfg`	`GetSignedUrlConfig`

Returns
Type	Description
`Promise<GetSignedUrlResponse>`

getSignedUrl(cfg, callback)

getSignedUrl(cfg: GetSignedUrlConfig, callback: GetSignedUrlCallback): void;

Parameters
Name	Description
`cfg`	`GetSignedUrlConfig`
`callback`	`GetSignedUrlCallback`

Returns
Type	Description
`void`

isPublic()

isPublic(): Promise<IsPublicResponse>;

Returns
Type	Description
`Promise<IsPublicResponse>`

isPublic(callback)

isPublic(callback: IsPublicCallback): void;

Parameter
Name	Description
`callback`	`IsPublicCallback`

Returns
Type	Description
`void`

makePrivate(options)

makePrivate(options?: MakeFilePrivateOptions): Promise<MakeFilePrivateResponse>;

Parameter
Name	Description
`options`	`MakeFilePrivateOptions`

Returns
Type	Description
`Promise<MakeFilePrivateResponse>`

makePrivate(callback)

makePrivate(callback: MakeFilePrivateCallback): void;

Parameter
Name	Description
`callback`	`MakeFilePrivateCallback`

Returns
Type	Description
`void`

makePrivate(options, callback)

makePrivate(options: MakeFilePrivateOptions, callback: MakeFilePrivateCallback): void;

Parameters
Name	Description
`options`	`MakeFilePrivateOptions`
`callback`	`MakeFilePrivateCallback`

Returns
Type	Description
`void`

makePublic()

makePublic(): Promise<MakeFilePublicResponse>;

Returns
Type	Description
`Promise<MakeFilePublicResponse>`

makePublic(callback)

makePublic(callback: MakeFilePublicCallback): void;

Parameter
Name	Description
`callback`	`MakeFilePublicCallback`

Returns
Type	Description
`void`

move(destination, options)

move(destination: string | Bucket | File, options?: MoveOptions): Promise<MoveResponse>;

Parameters
Name	Description
`destination`	`string \| Bucket \| File`
`options`	`MoveOptions`

Returns
Type	Description
`Promise<MoveResponse>`

move(destination, callback)

move(destination: string | Bucket | File, callback: MoveCallback): void;

Parameters
Name	Description
`destination`	`string \| Bucket \| File`
`callback`	`MoveCallback`

Returns
Type	Description
`void`

move(destination, options, callback)

move(destination: string | Bucket | File, options: MoveOptions, callback: MoveCallback): void;

Parameters
Name	Description
`destination`	`string \| Bucket \| File`
`options`	`MoveOptions`
`callback`	`MoveCallback`

Returns
Type	Description
`void`

publicUrl()

publicUrl(): string;

The public URL of this File Use to enable anonymous access via the returned URL.

Returns
Type	Description
`string`	{string}

Example

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

// publicUrl will be "https://storage.googleapis.com/albums/my-file" const publicUrl = file.publicUrl();

rename(destinationFile, options)

rename(destinationFile: string | File, options?: RenameOptions): Promise<RenameResponse>;

Parameters
Name	Description
`destinationFile`	`string \| File`
`options`	`RenameOptions`

Returns
Type	Description
`Promise<RenameResponse>`

rename(destinationFile, callback)

rename(destinationFile: string | File, callback: RenameCallback): void;

Parameters
Name	Description
`destinationFile`	`string \| File`
`callback`	`RenameCallback`

Returns
Type	Description
`void`

rename(destinationFile, options, callback)

rename(destinationFile: string | File, options: RenameOptions, callback: RenameCallback): void;

Parameters
Name	Description
`destinationFile`	`string \| File`
`options`	`RenameOptions`
`callback`	`RenameCallback`

Returns
Type	Description
`void`

request(reqOpts)

request(reqOpts: DecorateRequestOptions): Promise<[ResponseBody, Metadata]>;

Parameter
Name	Description
`reqOpts`	`DecorateRequestOptions`

Returns
Type	Description
`Promise<[ResponseBody, Metadata]>`

request(reqOpts, callback)

request(reqOpts: DecorateRequestOptions, callback: BodyResponseCallback): void;

Parameters
Name	Description
`reqOpts`	`DecorateRequestOptions`
`callback`	`BodyResponseCallback`

Returns
Type	Description
`void`

rotateEncryptionKey(options)

rotateEncryptionKey(options?: RotateEncryptionKeyOptions): Promise<RotateEncryptionKeyResponse>;

Parameter
Name	Description
`options`	`RotateEncryptionKeyOptions`

Returns
Type	Description
`Promise<RotateEncryptionKeyResponse>`

rotateEncryptionKey(callback)

rotateEncryptionKey(callback: RotateEncryptionKeyCallback): void;

Parameter
Name	Description
`callback`	`RotateEncryptionKeyCallback`

Returns
Type	Description
`void`

rotateEncryptionKey(options, callback)

rotateEncryptionKey(options: RotateEncryptionKeyOptions, callback: RotateEncryptionKeyCallback): void;

Parameters
Name	Description
`options`	`RotateEncryptionKeyOptions`
`callback`	`RotateEncryptionKeyCallback`

Returns
Type	Description
`void`

save(data, options)

save(data: string | Buffer, options?: SaveOptions): Promise<void>;

Parameters
Name	Description
`data`	`string \| __global.Buffer`
`options`	`SaveOptions`

Returns
Type	Description
`Promise<void>`

save(data, callback)

save(data: string | Buffer, callback: SaveCallback): void;

Parameters
Name	Description
`data`	`string \| __global.Buffer`
`callback`	`SaveCallback`

Returns
Type	Description
`void`

save(data, options, callback)

save(data: string | Buffer, options: SaveOptions, callback: SaveCallback): void;

Parameters
Name	Description
`data`	`string \| __global.Buffer`
`options`	`SaveOptions`
`callback`	`SaveCallback`

Returns
Type	Description
`void`

setEncryptionKey(encryptionKey)

setEncryptionKey(encryptionKey: string | Buffer): this;

The Storage API allows you to use a custom key for server-side encryption.

See Customer-supplied Encryption Keys

Parameter
Name	Description
`encryptionKey`	`string \| __global.Buffer` An AES-256 encryption key.

Returns
Type	Description
`this`	{File}

Examples

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

const encryptionKey = crypto.randomBytes(32);

const fileWithCustomEncryption = myBucket.file('my-file'); fileWithCustomEncryption.setEncryptionKey(encryptionKey);

const fileWithoutCustomEncryption = myBucket.file('my-file');

fileWithCustomEncryption.save('data', function(err) { // Try to download with the File object that hasn't had // setEncryptionKey() called: fileWithoutCustomEncryption.download(function(err) { // We will receive an error: // err.message === 'Bad Request'

// Try again with the File object we called `setEncryptionKey()` on:
fileWithCustomEncryption.download(function(err, contents) {
  // contents.toString() === 'data'
});

}); });

Example of uploading an encrypted file:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The path to your file to upload
  // const filePath = 'path/to/your/file';

  // The new ID for your GCS file
  // const destFileName = 'your-new-file-name';

  // The key to encrypt the object with
  // const key = 'TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g=';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function uploadEncryptedFile() {
    const options = {
      destination: destFileName,
      encryptionKey: Buffer.from(key, 'base64'),

      // Optional:
      // Set a generation-match precondition to avoid potential race conditions
      // and data corruptions. The request to upload is aborted if the object's
      // generation number does not match your precondition. For a destination
      // object that does not yet exist, set the ifGenerationMatch precondition to 0
      // If the destination object already exists in your bucket, set instead a
      // generation-match precondition using its generation number.
      preconditionOpts: {ifGenerationMatch: generationMatchPrecondition},
    };

    await storage.bucket(bucketName).upload(filePath, options);

    console.log(
      `File ${filePath} uploaded to gs://${bucketName}/${destFileName}`
    );
  }

  uploadEncryptedFile().catch(console.error);

Example of downloading an encrypted file:


  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The ID of your GCS file
  // const srcFileName = 'your-file-name';

  // The path to which the file should be downloaded
  // const destFileName = '/local/path/to/file.txt';

  // The Base64 encoded decryption key, which should be the same key originally
  // used to encrypt the file
  // const encryptionKey = 'TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g=';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function downloadEncryptedFile() {
    const options = {
      destination: destFileName,
    };

    // Decrypts and downloads the file. This can only be done with the key used
    // to encrypt and upload the file.
    await storage
      .bucket(bucketName)
      .file(srcFileName)
      .setEncryptionKey(Buffer.from(encryptionKey, 'base64'))
      .download(options);

    console.log(`File ${srcFileName} downloaded to ${destFileName}`);
  }

  downloadEncryptedFile().catch(console.error);

setMetadata(metadata, options)

setMetadata(metadata: Metadata, options?: SetMetadataOptions): Promise<SetMetadataResponse>;

Parameters
Name	Description
`metadata`	`Metadata`
`options`	`SetMetadataOptions`

Returns
Type	Description
`Promise<SetMetadataResponse>`

setMetadata(metadata, callback)

setMetadata(metadata: Metadata, callback: MetadataCallback): void;

Parameters
Name	Description
`metadata`	`Metadata`
`callback`	`MetadataCallback`

Returns
Type	Description
`void`

setMetadata(metadata, options, callback)

setMetadata(metadata: Metadata, options: SetMetadataOptions, callback: MetadataCallback): void;

Parameters
Name	Description
`metadata`	`Metadata`
`options`	`SetMetadataOptions`
`callback`	`MetadataCallback`

Returns
Type	Description
`void`

setStorageClass(storageClass, options)

setStorageClass(storageClass: string, options?: SetStorageClassOptions): Promise<SetStorageClassResponse>;

Parameters
Name	Description
`storageClass`	`string`
`options`	`SetStorageClassOptions`

Returns
Type	Description
`Promise<SetStorageClassResponse>`

setStorageClass(storageClass, options, callback)

setStorageClass(storageClass: string, options: SetStorageClassOptions, callback: SetStorageClassCallback): void;

Parameters
Name	Description
`storageClass`	`string`
`options`	`SetStorageClassOptions`
`callback`	`SetStorageClassCallback`

Returns
Type	Description
`void`

setStorageClass(storageClass, callback)

setStorageClass(storageClass: string, callback?: SetStorageClassCallback): void;

Parameters
Name	Description
`storageClass`	`string`
`callback`	`SetStorageClassCallback`

Returns
Type	Description
`void`

setUserProject(userProject)

setUserProject(userProject: string): void;

Set a user project to be billed for all requests made from this File 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'); const file = bucket.file('my-file');

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

startResumableUpload_(dup, options)

startResumableUpload_(dup: Duplexify, options: CreateResumableUploadOptions): void;

This creates a resumable-upload upload stream.

Parameters
Name	Description
`dup`	`Duplexify`
`options`	`CreateResumableUploadOptions` Configuration object.

Returns
Type	Description
`void`

startSimpleUpload_(dup, options)

startSimpleUpload_(dup: Duplexify, options?: CreateWriteStreamOptions): void;

Takes a readable stream and pipes it to a remote file. Unlike startResumableUpload_, which uses the resumable upload technique, this method uses a simple upload (all or nothing).

Parameters
Name	Description
`dup`	`Duplexify` Duplexify stream of data to pipe to the file.
`options`	`CreateWriteStreamOptions` Configuration object.

Returns
Type	Description
`void`