File

Examples

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

//-
// You can pass in a variety of types for the destination.
//
// For all of the below examples, assume we are working with the following
// Bucket and File objects.
//-
const bucket = storage.bucket('my-bucket');
const file = bucket.file('my-image.png');

//-
// If you pass in a string for the destination, the file is copied to its
// current bucket, under the new name provided.
//-
file.copy('my-image-copy.png', function(err, copiedFile, apiResponse) {
  // `my-bucket` now contains:
  // - "my-image.png"
  // - "my-image-copy.png"

  // `copiedFile` is an instance of a File object that refers to your new
  // file.
});

//-
// If you pass in a string starting with "gs://" for the destination, the
// file is copied to the other bucket and under the new name provided.
//-
const newLocation = 'gs://another-bucket/my-image-copy.png';
file.copy(newLocation, function(err, copiedFile, apiResponse) {
  // `my-bucket` still contains:
  // - "my-image.png"
  //
  // `another-bucket` now contains:
  // - "my-image-copy.png"

  // `copiedFile` is an instance of a File object that refers to your new
  // file.
});

//-
// If you pass in a Bucket object, the file will be copied to that bucket
// using the same name.
//-
const anotherBucket = storage.bucket('another-bucket');
file.copy(anotherBucket, function(err, copiedFile, apiResponse) {
  // `my-bucket` still contains:
  // - "my-image.png"
  //
  // `another-bucket` now contains:
  // - "my-image.png"

  // `copiedFile` is an instance of a File object that refers to your new
  // file.
});

//-
// If you pass in a File object, you have complete control over the new
// bucket and filename.
//-
const anotherFile = anotherBucket.file('my-awesome-image.png');
file.copy(anotherFile, function(err, copiedFile, apiResponse) {
  // `my-bucket` still contains:
  // - "my-image.png"
  //
  // `another-bucket` now contains:
  // - "my-awesome-image.png"

  // Note:
  // The `copiedFile` parameter is equal to `anotherFile`.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.copy(newLocation).then(function(data) {
  const newFile = data[0];
  const apiResponse = data[1];
});

```

Another example:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of the bucket the original file is in
  // const srcBucketName = 'your-source-bucket';

  // The ID of the GCS file to copy
  // const srcFilename = 'your-file-name';

  // The ID of the bucket to copy the file to
  // const destBucketName = 'target-file-bucket';

  // The ID of the GCS file to create
  // const destFileName = 'target-file-name';

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

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

  async function copyFile() {
    const copyDestination = storage.bucket(destBucketName).file(destFileName);

    // Optional:
    // Set a generation-match precondition to avoid potential race conditions
    // and data corruptions. The request to copy 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.
    const copyOptions = {
      preconditionOpts: {
        ifGenerationMatch: destinationGenerationMatchPrecondition,
      },
    };

    // Copies the file to the other bucket
    await storage
      .bucket(srcBucketName)
      .file(srcFilename)
      .copy(copyDestination, copyOptions);

    console.log(
      `gs://${srcBucketName}/${srcFilename} copied to gs://${destBucketName}/${destFileName}`
    );
  }

  copyFile().catch(console.error);

Example

```
//-
// <h4>Downloading a File</h4>
//
// 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'));
```

Example

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

const file = myBucket.file('my-file');
file.createResumableUpload(function(err, uri) {
  if (!err) {
    // `uri` can be used to PUT data to.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.createResumableUpload().then(function(data) {
  const uri = data[0];
});
```

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

//-
// <h4>Uploading a File</h4>
//
// Now, consider a case where we want to upload a file to your bucket. You
// have the option of using 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.
  });

//-
// <h4>Uploading a File with gzip compression</h4>
//-
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.
//-

//-
// <h4>Uploading a File with Metadata</h4>
//
// 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
// 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.
  });
```

//-
// <h4>Continuing a Resumable Upload</h4>
//
// One can capture a `uri` from a resumable upload to reuse later.
// Additionally, for validation, one can also capture and pass `crc32c`.
//-
let uri: string | undefined = undefined;
let resumeCRC32C: string | undefined = undefined;

fs.createWriteStream()
  .on('uri', link => {uri = link})
  .on('crc32', crc32c => {resumeCRC32C = crc32c});

// later...
fs.createWriteStream({uri, resumeCRC32C});

Examples

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

const file = myBucket.file('my-file');
file.delete(function(err, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.delete().then(function(data) {
  const apiResponse = data[0];
});

```

Another example:

  /**
   * 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 fileName = 'your-file-name';

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

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

  // Optional:
  // Set a generation-match precondition to avoid potential race conditions
  // and data corruptions. The request to delete 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.
  const deleteOptions = {
    ifGenerationMatch: generationMatchPrecondition,
  };
  async function deleteFile() {
    await storage.bucket(bucketName).file(fileName).delete(deleteOptions);

    console.log(`gs://${bucketName}/${fileName} deleted`);
  }

  deleteFile().catch(console.error);

Examples

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

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

//-
// Download a file into memory. The contents will be available as the
second
// argument in the demonstration below, `contents`.
//-
file.download(function(err, contents) {});

//-
// Download a file to a local destination.
//-
file.download({
  destination: '/Users/me/Desktop/file-backup.txt'
}, function(err) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.download().then(function(data) {
  const contents = data[0];
});

```

Another example:

  /**
   * 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 fileName = 'your-file-name';

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

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

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

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

    // Downloads the file
    await storage.bucket(bucketName).file(fileName).download(options);

    console.log(
      `gs://${bucketName}/${fileName} downloaded to ${destFileName}.`
    );
  }

  downloadFile().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);

Example of downloading a file where the requester pays:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The project ID to bill
  // const projectId = 'my-billable-project-id';

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

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

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

  async function downloadFileUsingRequesterPays() {
    const options = {
      destination: destFileName,
      userProject: projectId,
    };

    // Downloads the file
    await storage.bucket(bucketName).file(srcFileName).download(options);

    console.log(
      `gs://${bucketName}/${srcFileName} downloaded to ${destFileName} using requester-pays requests`
    );
  }

  downloadFileUsingRequesterPays().catch(console.error);

Example

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

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

file.exists(function(err, exists) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.exists().then(function(data) {
  const exists = data[0];
});
```

Example

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

const file = myBucket.file('my-file');
const options = {
  equals: ['$Content-Type', 'image/jpeg'],
  expires: '10-25-2022',
  contentLengthRange: {
    min: 0,
    max: 1024
  }
};

file.generateSignedPostPolicyV2(options, function(err, policy) {
  // policy.string: the policy document in plain text.
  // policy.base64: the policy document in base64.
  // policy.signature: the policy signature in base64.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.generateSignedPostPolicyV2(options).then(function(data) {
  const policy = data[0];
});
```

Example

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

const file = myBucket.file('my-file');
const options = {
  expires: '10-25-2022',
  conditions: [
    ['eq', '$Content-Type', 'image/jpeg'],
    ['content-length-range', 0, 1024],
  ],
  fields: {
    acl: 'public-read',
    'x-goog-meta-foo': 'bar',
    'x-ignore-mykey': 'data'
  }
};

file.generateSignedPostPolicyV4(options, function(err, response) {
  // response.url The request URL
  // response.fields The form fields (including the signature) to include
  //     to be used to upload objects by HTML forms.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.generateSignedPostPolicyV4(options).then(function(data) {
  const response = data[0];
  // response.url The request URL
  // response.fields The form fields (including the signature) to include
  //     to be used to upload objects by HTML forms.
});
```

Example

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

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

file.get(function(err, file, apiResponse) {
  // file.metadata` has been populated.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.get().then(function(data) {
  const file = data[0];
  const apiResponse = data[1];
});
```

Example

```
const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');

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

file.getExpirationDate(function(err, expirationDate) {
  // expirationDate is a Date object.
});
```

Examples

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

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

file.getMetadata(function(err, metadata, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.getMetadata().then(function(data) {
  const metadata = data[0];
  const apiResponse = data[1];
});

```

Another example:

  /**
   * 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 fileName = 'your-file-name';

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

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

  async function getMetadata() {
    // Gets the metadata for the file
    const [metadata] = await storage
      .bucket(bucketName)
      .file(fileName)
      .getMetadata();

    console.log(`Bucket: ${metadata.bucket}`);
    console.log(`CacheControl: ${metadata.cacheControl}`);
    console.log(`ComponentCount: ${metadata.componentCount}`);
    console.log(`ContentDisposition: ${metadata.contentDisposition}`);
    console.log(`ContentEncoding: ${metadata.contentEncoding}`);
    console.log(`ContentLanguage: ${metadata.contentLanguage}`);
    console.log(`ContentType: ${metadata.contentType}`);
    console.log(`CustomTime: ${metadata.customTime}`);
    console.log(`Crc32c: ${metadata.crc32c}`);
    console.log(`ETag: ${metadata.etag}`);
    console.log(`Generation: ${metadata.generation}`);
    console.log(`Id: ${metadata.id}`);
    console.log(`KmsKeyName: ${metadata.kmsKeyName}`);
    console.log(`Md5Hash: ${metadata.md5Hash}`);
    console.log(`MediaLink: ${metadata.mediaLink}`);
    console.log(`Metageneration: ${metadata.metageneration}`);
    console.log(`Name: ${metadata.name}`);
    console.log(`Size: ${metadata.size}`);
    console.log(`StorageClass: ${metadata.storageClass}`);
    console.log(`TimeCreated: ${new Date(metadata.timeCreated)}`);
    console.log(`Last Metadata Update: ${new Date(metadata.updated)}`);
    console.log(`TurboReplication: ${metadata.rpo}`);
    console.log(
      `temporaryHold: ${metadata.temporaryHold ? 'enabled' : 'disabled'}`
    );
    console.log(
      `eventBasedHold: ${metadata.eventBasedHold ? 'enabled' : 'disabled'}`
    );
    if (metadata.retentionExpirationTime) {
      console.log(
        `retentionExpirationTime: ${new Date(metadata.retentionExpirationTime)}`
      );
    }
    if (metadata.metadata) {
      console.log('\n\n\nUser metadata:');
      for (const key in metadata.metadata) {
        console.log(`${key}=${metadata.metadata[key]}`);
      }
    }
  }

  getMetadata().catch(console.error);

Examples

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

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

//-
// Generate a URL that allows temporary access to download your file.
//-
const request = require('request');

const config = {
  action: 'read',
  expires: '03-17-2025',
};

file.getSignedUrl(config, function(err, url) {
  if (err) {
    console.error(err);
    return;
  }

  // The file is now available to read from this URL.
  request(url, function(err, resp) {
    // resp.statusCode = 200
  });
});

//-
// Generate a URL that allows temporary access to download your file.
// Access will begin at accessibleAt and end at expires.
//-
const request = require('request');

const config = {
  action: 'read',
  expires: '03-17-2025',
  accessibleAt: '03-13-2025'
};

file.getSignedUrl(config, function(err, url) {
  if (err) {
    console.error(err);
    return;
  }

  // The file will be available to read from this URL from 03-13-2025 to 03-17-2025.
  request(url, function(err, resp) {
    // resp.statusCode = 200
  });
});

//-
// Generate a URL to allow write permissions. This means anyone with this
URL
// can send a POST request with new data that will overwrite the file.
//-
file.getSignedUrl({
  action: 'write',
  expires: '03-17-2025'
}, function(err, url) {
  if (err) {
    console.error(err);
    return;
  }

  // The file is now available to be written to.
  const writeStream = request.put(url);
  writeStream.end('New data');

  writeStream.on('complete', function(resp) {
    // Confirm the new content was saved.
    file.download(function(err, fileContents) {
      console.log('Contents:', fileContents.toString());
      // Contents: New data
    });
  });
});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.getSignedUrl(config).then(function(data) {
  const url = data[0];
});

```

Another example:

  /**
   * 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 fileName = 'your-file-name';

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

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

  async function generateSignedUrl() {
    // These options will allow temporary read access to the file
    const options = {
      version: 'v2', // defaults to 'v2' if missing.
      action: 'read',
      expires: Date.now() + 1000 * 60 * 60, // one hour
    };

    // Get a v2 signed URL for the file
    const [url] = await storage
      .bucket(bucketName)
      .file(fileName)
      .getSignedUrl(options);

    console.log(`The signed url for ${fileName} is ${url}.`);
  }

  generateSignedUrl().catch(console.error);

Example

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

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

//-
// Check whether the file is publicly accessible.
//-
file.isPublic(function(err, resp) {
  if (err) {
    console.error(err);
    return;
  }
  console.log(`the file ${file.id} is public: ${resp}`) ;
})
//-
// If the callback is omitted, we'll return a Promise.
//-
file.isPublic().then(function(data) {
  const resp = data[0];
});
```

Example

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

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

//-
// Set the file private so only project maintainers can see and modify it.
//-
file.makePrivate(function(err) {});

//-
// Set the file private so only the owner can see and modify it.
//-
file.makePrivate({ strict: true }, function(err) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.makePrivate().then(function(data) {
  const apiResponse = data[0];
});
```

Examples

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

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

file.makePublic(function(err, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.makePublic().then(function(data) {
  const apiResponse = data[0];
});

```

Another example:

  /**
   * 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 fileName = 'your-file-name';

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

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

  async function makePublic() {
    await storage.bucket(bucketName).file(fileName).makePublic();

    console.log(`gs://${bucketName}/${fileName} is now public.`);
  }

  makePublic().catch(console.error);

Examples

```
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
//-
// You can pass in a variety of types for the destination.
//
// For all of the below examples, assume we are working with the following
// Bucket and File objects.
//-
const bucket = storage.bucket('my-bucket');
const file = bucket.file('my-image.png');

//-
// If you pass in a string for the destination, the file is moved to its
// current bucket, under the new name provided.
//-
file.move('my-image-new.png', function(err, destinationFile, apiResponse) {
  // `my-bucket` no longer contains:
  // - "my-image.png"
  // but contains instead:
  // - "my-image-new.png"

  // `destinationFile` is an instance of a File object that refers to your
  // new file.
});

//-
// If you pass in a string starting with "gs://" for the destination, the
// file is copied to the other bucket and under the new name provided.
//-
const newLocation = 'gs://another-bucket/my-image-new.png';
file.move(newLocation, function(err, destinationFile, apiResponse) {
  // `my-bucket` no longer contains:
  // - "my-image.png"
  //
  // `another-bucket` now contains:
  // - "my-image-new.png"

  // `destinationFile` is an instance of a File object that refers to your
  // new file.
});

//-
// If you pass in a Bucket object, the file will be moved to that bucket
// using the same name.
//-
const anotherBucket = gcs.bucket('another-bucket');

file.move(anotherBucket, function(err, destinationFile, apiResponse) {
  // `my-bucket` no longer contains:
  // - "my-image.png"
  //
  // `another-bucket` now contains:
  // - "my-image.png"

  // `destinationFile` is an instance of a File object that refers to your
  // new file.
});

//-
// If you pass in a File object, you have complete control over the new
// bucket and filename.
//-
const anotherFile = anotherBucket.file('my-awesome-image.png');

file.move(anotherFile, function(err, destinationFile, apiResponse) {
  // `my-bucket` no longer contains:
  // - "my-image.png"
  //
  // `another-bucket` now contains:
  // - "my-awesome-image.png"

  // Note:
  // The `destinationFile` parameter is equal to `anotherFile`.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.move('my-image-new.png').then(function(data) {
  const destinationFile = data[0];
  const apiResponse = data[1];
});

```

Another example:

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

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

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

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

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

  async function moveFile() {
    // Optional:
    // Set a generation-match precondition to avoid potential race conditions
    // and data corruptions. The request to copy 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.
    const moveOptions = {
      preconditionOpts: {
        ifGenerationMatch: destinationGenerationMatchPrecondition,
      },
    };

    // Moves the file within the bucket
    await storage
      .bucket(bucketName)
      .file(srcFileName)
      .move(destFileName, moveOptions);

    console.log(
      `gs://${bucketName}/${srcFileName} moved to gs://${bucketName}/${destFileName}`
    );
  }

  moveFile().catch(console.error);

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();
```

Example

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

//-
// You can pass in a string or a File object.
//
// For all of the below examples, assume we are working with the following
// Bucket and File objects.
//-

const bucket = storage.bucket('my-bucket');
const file = bucket.file('my-image.png');

//-
// You can pass in a string for the destinationFile.
//-
file.rename('renamed-image.png', function(err, renamedFile, apiResponse) {
  // `my-bucket` no longer contains:
  // - "my-image.png"
  // but contains instead:
  // - "renamed-image.png"

  // `renamedFile` is an instance of a File object that refers to your
  // renamed file.
});

//-
// You can pass in a File object.
//-
const anotherFile = anotherBucket.file('my-awesome-image.png');

file.rename(anotherFile, function(err, renamedFile, apiResponse) {
  // `my-bucket` no longer contains:
  // - "my-image.png"

  // Note:
  // The `renamedFile` parameter is equal to `anotherFile`.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.rename('my-renamed-image.png').then(function(data) {
  const renamedFile = data[0];
  const apiResponse = data[1];
});
```

Example

Example of rotating the encryption key for this 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 fileName = 'your-file-name';

  // The Base64 encoded AES-256 encryption key originally used to encrypt the
  // object. See the documentation on Customer-Supplied Encryption keys for
  // more info:
  // https://cloud.google.com/storage/docs/encryption/using-customer-supplied-keys
  // The Base64 encoded AES-256 encryption key originally used to encrypt the
  // const oldKey = 'TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g=';

  // The new encryption key to use
  // const newKey = '0mMWhFvQOdS4AmxRpo8SJxXn5MjFhbz7DkKBUdUIef8=';

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

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

  async function rotateEncryptionKey() {
    const rotateEncryptionKeyOptions = {
      encryptionKey: Buffer.from(newKey, 'base64'),

      // Optional: set a generation-match precondition to avoid potential race
      // conditions and data corruptions. The request to copy is aborted if the
      // object's generation number does not match your precondition.
      preconditionOpts: {
        ifGenerationMatch: generationMatchPrecondition,
      },
    };
    await storage
      .bucket(bucketName)
      .file(fileName, {
        encryptionKey: Buffer.from(oldKey, 'base64'),
      })
      .rotateEncryptionKey({
        rotateEncryptionKeyOptions,
      });

    console.log('Encryption key rotated successfully');
  }

  rotateEncryptionKey().catch(console.error);

Example

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

const file = myBucket.file('my-file');
const contents = 'This is the contents of the file.';

file.save(contents, function(err) {
  if (!err) {
    // File written successfully.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.save(contents).then(function() {});
```

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

Example

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

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

const metadata = {
  contentType: 'application/x-font-ttf',
  metadata: {
    my: 'custom',
    properties: 'go here'
  }
};

file.setMetadata(metadata, function(err, apiResponse) {});

// Assuming current metadata = { hello: 'world', unsetMe: 'will do' }
file.setMetadata({
  metadata: {
    abc: '123', // will be set.
    unsetMe: null, // will be unset (deleted).
    hello: 'goodbye' // will be updated from 'world' to 'goodbye'.
  }
}, function(err, apiResponse) {
  // metadata should now be { abc: '123', hello: 'goodbye' }
});

//-
// Set a temporary hold on this file from its bucket's retention period
// configuration.
//
file.setMetadata({
  temporaryHold: true
}, function(err, apiResponse) {});

//-
// Alternatively, you may set a temporary hold. This will follow the
// same behavior as an event-based hold, with the exception that the
// bucket's retention policy will not renew for this file from the time
// the hold is released.
//-
file.setMetadata({
  eventBasedHold: true
}, function(err, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
file.setMetadata(metadata).then(function(data) {
  const apiResponse = data[0];
});
```

Example

```
file.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.
//-
file.setStorageClass('nearline').then(function() {});
```

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');
```