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

```

include:samples/files.js

region_tag:storage_copy_file
Another example:

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

```

include:samples/files.js

region_tag:storage_delete_file
Another example:

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

```

include:samples/files.js

region_tag:storage_download_file
Another example:

include:samples/encryption.js

region_tag:storage_download_encrypted_file
Example of downloading an encrypted file:

include:samples/requesterPays.js

region_tag:storage_download_file_requester_pays
Example of downloading a file where the requester pays:

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

```

include:samples/files.js

region_tag:storage_get_metadata
Another example:

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

```

include:samples/files.js

region_tag:storage_generate_signed_url
Another example:

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

```

include:samples/files.js

region_tag:storage_make_public
Another example:

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

```

include:samples/files.js

region_tag:storage_move_file
Another example:

Examples

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

//-
// Assume 'my-bucket' is a bucket.
//-
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.moveFileAtomic('moved-image.png', function(err, movedFile, apiResponse) {
  // `my-bucket` now contains:
  // - "moved-image.png"

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

//-
// Move the file to a subdirectory, creating parent folders if necessary.
//-
file.moveFileAtomic('new-folder/subfolder/moved-image.png', function(err, movedFile, apiResponse) {
// `my-bucket` now contains:
// - "new-folder/subfolder/moved-image.png"
});

//-
// Prevent overwriting an existing destination object using preconditions.
//-
file.moveFileAtomic('existing-destination.png', {
preconditionOpts: {
ifGenerationMatch: 0 // Fails if the destination object exists.
}
}, function(err, movedFile, apiResponse) {
if (err) {
// Handle the error (e.g., the destination object already exists).
} else {
// Move successful.
}
});

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

```

include:samples/files.js

region_tag:storage_move_file
Another example:

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

include:samples/encryption.js

region_tag:storage_rotate_encryption_key
Example of rotating the encryption key for this file:

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

```

include:samples/encryption.js

region_tag:storage_upload_encrypted_file
Example of uploading an encrypted file:

include:samples/encryption.js

region_tag:storage_download_encrypted_file
Example of downloading an encrypted file:

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