Class File (7.3.2)

Package

Constructors

(constructor)(bucket, name, options)

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

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;

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;

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>;

copy(destination, callback)

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

copy(destination, options, callback)

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

createReadStream(options)

createReadStream(options?: CreateReadStreamOptions): Readable;

//-
// 
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>;

createResumableUpload(options, callback)

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

createResumableUpload(callback)

createResumableUpload(callback: CreateResumableUploadCallback): void;

createWriteStream(options)

createWriteStream(options?: CreateWriteStreamOptions): Writable;

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(options, callback)

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

delete(callback)

delete(callback: DeleteCallback): void;

disableAutoRetryConditionallyIdempotent_(coreOpts, methodType, localPreconditionOptions)

disableAutoRetryConditionallyIdempotent_(coreOpts: any, methodType: AvailableServiceObjectMethods, localPreconditionOptions?: PreconditionOptions): void;

download(options)

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

download(options, callback)

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

download(callback)

download(callback: DownloadCallback): void;

generateSignedPostPolicyV2(options)

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

generateSignedPostPolicyV2(options, callback)

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

generateSignedPostPolicyV2(callback)

generateSignedPostPolicyV2(callback: GenerateSignedPostPolicyV2Callback): void;

generateSignedPostPolicyV4(options)

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

generateSignedPostPolicyV4(options, callback)

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

generateSignedPostPolicyV4(callback)

generateSignedPostPolicyV4(callback: GenerateSignedPostPolicyV4Callback): void;

getExpirationDate()

getExpirationDate(): Promise<GetExpirationDateResponse>;

getExpirationDate(callback)

getExpirationDate(callback: GetExpirationDateCallback): void;

getSignedUrl(cfg)

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

getSignedUrl(cfg, callback)

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

isPublic()

isPublic(): Promise<IsPublicResponse>;

isPublic(callback)

isPublic(callback: IsPublicCallback): void;

makePrivate(options)

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

makePrivate(callback)

makePrivate(callback: MakeFilePrivateCallback): void;

makePrivate(options, callback)

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

makePublic()

makePublic(): Promise<MakeFilePublicResponse>;

makePublic(callback)

makePublic(callback: MakeFilePublicCallback): void;

move(destination, options)

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

move(destination, callback)

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

move(destination, options, callback)

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

publicUrl()

publicUrl(): string;

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>;

rename(destinationFile, callback)

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

rename(destinationFile, options, callback)

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

request(reqOpts)

request(reqOpts: DecorateRequestOptions): Promise<RequestResponse>;

request(reqOpts, callback)

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

rotateEncryptionKey(options)

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

rotateEncryptionKey(callback)

rotateEncryptionKey(callback: RotateEncryptionKeyCallback): void;

rotateEncryptionKey(options, callback)

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

save(data, options)

save(data: SaveData, options?: SaveOptions): Promise<void>;

save(data, callback)

save(data: SaveData, callback: SaveCallback): void;

save(data, options, callback)

save(data: SaveData, options: SaveOptions, callback: SaveCallback): void;

setEncryptionKey(encryptionKey)

setEncryptionKey(encryptionKey: string | Buffer): this;

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: FileMetadata, options?: SetMetadataOptions): Promise<SetMetadataResponse<FileMetadata>>;

setMetadata(metadata, callback)

setMetadata(metadata: FileMetadata, callback: MetadataCallback<FileMetadata>): void;

setMetadata(metadata, options, callback)

setMetadata(metadata: FileMetadata, options: SetMetadataOptions, callback: MetadataCallback<FileMetadata>): void;

setStorageClass(storageClass, options)

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

setStorageClass(storageClass, options, callback)

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

setStorageClass(storageClass, callback)

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

setUserProject(userProject)

setUserProject(userProject: string): void;

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;

startSimpleUpload_(dup, options)

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