A File object is created from your Bucket object using .
Inheritance
ServiceObject < File > > FilePackage
@google-cloud/storageConstructors
(constructor)(bucket, name, options)
constructor
(
bucket
:
Bucket
,
name
:
string
,
options
?:
FileOptions
);
Constructs a file object.
bucket
Bucket
The Bucket instance this file is attached to.
name
string
The name of the remote file.
options
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://
)
```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>
;
copy(destination, callback)
copy
(
destination
:
string
|
Bucket
|
File
,
callback
:
CopyCallback
)
:
void
;
void
copy(destination, options, callback)
copy
(
destination
:
string
|
Bucket
|
File
,
options
:
CopyOptions
,
callback
:
CopyCallback
)
:
void
;
destination
string | Bucket
| File
options
callback
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.
Readable
{ReadableStream}
//- //
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
;
options
callback
void
createResumableUpload(callback)
createResumableUpload
(
callback
:
CreateResumableUploadCallback
)
:
void
;
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
Writable
{WritableStream}
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.
options
DeleteOptions
Promise
<[r. Response
]>
delete(options, callback)
delete
(
options
:
DeleteOptions
,
callback
:
DeleteCallback
)
:
void
;
options
DeleteOptions
callback
DeleteCallback
void
delete(callback)
delete
(
callback
:
DeleteCallback
)
:
void
;
callback
DeleteCallback
void
disableAutoRetryConditionallyIdempotent_(coreOpts, methodType, localPreconditionOptions)
disableAutoRetryConditionallyIdempotent_
(
coreOpts
:
any
,
methodType
:
AvailableServiceObjectMethods
,
localPreconditionOptions
?:
PreconditionOptions
)
:
void
;
coreOpts
any
methodType
AvailableServiceObjectMethods
localPreconditionOptions
void
download(options)
download
(
options
?:
DownloadOptions
)
:
Promise<DownloadResponse>
;
download(options, callback)
download
(
options
:
DownloadOptions
,
callback
:
DownloadCallback
)
:
void
;
void
download(callback)
download
(
callback
:
DownloadCallback
)
:
void
;
void
generateSignedPostPolicyV2(options)
generateSignedPostPolicyV2
(
options
:
GenerateSignedPostPolicyV2Options
)
:
Promise<GenerateSignedPostPolicyV2Response>
;
generateSignedPostPolicyV2(options, callback)
generateSignedPostPolicyV2
(
options
:
GenerateSignedPostPolicyV2Options
,
callback
:
GenerateSignedPostPolicyV2Callback
)
:
void
;
callback
void
generateSignedPostPolicyV2(callback)
generateSignedPostPolicyV2
(
callback
:
GenerateSignedPostPolicyV2Callback
)
:
void
;
void
generateSignedPostPolicyV4(options)
generateSignedPostPolicyV4
(
options
:
GenerateSignedPostPolicyV4Options
)
:
Promise<GenerateSignedPostPolicyV4Response>
;
generateSignedPostPolicyV4(options, callback)
generateSignedPostPolicyV4
(
options
:
GenerateSignedPostPolicyV4Options
,
callback
:
GenerateSignedPostPolicyV4Callback
)
:
void
;
callback
void
generateSignedPostPolicyV4(callback)
generateSignedPostPolicyV4
(
callback
:
GenerateSignedPostPolicyV4Callback
)
:
void
;
void
getExpirationDate()
getExpirationDate
()
:
Promise<GetExpirationDateResponse>
;
getExpirationDate(callback)
getExpirationDate
(
callback
:
GetExpirationDateCallback
)
:
void
;
void
getSignedUrl(cfg)
getSignedUrl
(
cfg
:
GetSignedUrlConfig
)
:
Promise<GetSignedUrlResponse>
;
getSignedUrl(cfg, callback)
getSignedUrl
(
cfg
:
GetSignedUrlConfig
,
callback
:
GetSignedUrlCallback
)
:
void
;
void
isPublic()
isPublic
()
:
Promise<IsPublicResponse>
;
Promise
< IsPublicResponse
>
isPublic(callback)
isPublic
(
callback
:
IsPublicCallback
)
:
void
;
callback
IsPublicCallback
void
makePrivate(options)
makePrivate
(
options
?:
MakeFilePrivateOptions
)
:
Promise<MakeFilePrivateResponse>
;
makePrivate(callback)
makePrivate
(
callback
:
MakeFilePrivateCallback
)
:
void
;
void
makePrivate(options, callback)
makePrivate
(
options
:
MakeFilePrivateOptions
,
callback
:
MakeFilePrivateCallback
)
:
void
;
void
makePublic()
makePublic
()
:
Promise<MakeFilePublicResponse>
;
makePublic(callback)
makePublic
(
callback
:
MakeFilePublicCallback
)
:
void
;
void
move(destination, options)
move
(
destination
:
string
|
Bucket
|
File
,
options
?:
MoveOptions
)
:
Promise<MoveResponse>
;
move(destination, callback)
move
(
destination
:
string
|
Bucket
|
File
,
callback
:
MoveCallback
)
:
void
;
void
move(destination, options, callback)
move
(
destination
:
string
|
Bucket
|
File
,
options
:
MoveOptions
,
callback
:
MoveCallback
)
:
void
;
destination
string | Bucket
| File
options
callback
void
publicUrl()
publicUrl
()
:
string
;
The public URL of this File Use to enable anonymous access via the returned URL.
string
{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>
;
destinationFile
string | File
options
RenameOptions
Promise
< RenameResponse
>
rename(destinationFile, callback)
rename
(
destinationFile
:
string
|
File
,
callback
:
RenameCallback
)
:
void
;
destinationFile
string | File
callback
RenameCallback
void
rename(destinationFile, options, callback)
rename
(
destinationFile
:
string
|
File
,
options
:
RenameOptions
,
callback
:
RenameCallback
)
:
void
;
destinationFile
string | File
options
RenameOptions
callback
RenameCallback
void
request(reqOpts)
request
(
reqOpts
:
DecorateRequestOptions
)
:
Promise
< [
ResponseBody
,
Metadata
]>;
reqOpts
DecorateRequestOptions
Promise
<[ ResponseBody
, Metadata
]>
request(reqOpts, callback)
request
(
reqOpts
:
DecorateRequestOptions
,
callback
:
BodyResponseCallback
)
:
void
;
reqOpts
DecorateRequestOptions
callback
BodyResponseCallback
void
rotateEncryptionKey(options)
rotateEncryptionKey
(
options
?:
RotateEncryptionKeyOptions
)
:
Promise<RotateEncryptionKeyResponse>
;
rotateEncryptionKey(callback)
rotateEncryptionKey
(
callback
:
RotateEncryptionKeyCallback
)
:
void
;
void
rotateEncryptionKey(options, callback)
rotateEncryptionKey
(
options
:
RotateEncryptionKeyOptions
,
callback
:
RotateEncryptionKeyCallback
)
:
void
;
void
save(data, options)
save
(
data
:
string
|
Buffer
,
options
?:
SaveOptions
)
:
Promise<void>
;
Promise
<void>
save(data, callback)
save
(
data
:
string
|
Buffer
,
callback
:
SaveCallback
)
:
void
;
void
save(data, options, callback)
save
(
data
:
string
|
Buffer
,
options
:
SaveOptions
,
callback
:
SaveCallback
)
:
void
;
void
setEncryptionKey(encryptionKey)
setEncryptionKey
(
encryptionKey
:
string
|
Buffer
)
:
this
;
The Storage API allows you to use a custom key for server-side encryption.
encryptionKey
string | __global.Buffer
An AES-256 encryption key.
this
{File}
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>
;
metadata
Metadata
options
SetMetadataOptions
Promise
< SetMetadataResponse
>
setMetadata(metadata, callback)
setMetadata
(
metadata
:
Metadata
,
callback
:
MetadataCallback
)
:
void
;
metadata
Metadata
callback
MetadataCallback
void
setMetadata(metadata, options, callback)
setMetadata
(
metadata
:
Metadata
,
options
:
SetMetadataOptions
,
callback
:
MetadataCallback
)
:
void
;
metadata
Metadata
options
SetMetadataOptions
callback
MetadataCallback
void
setStorageClass(storageClass, options)
setStorageClass
(
storageClass
:
string
,
options
?:
SetStorageClassOptions
)
:
Promise<SetStorageClassResponse>
;
setStorageClass(storageClass, options, callback)
setStorageClass
(
storageClass
:
string
,
options
:
SetStorageClassOptions
,
callback
:
SetStorageClassCallback
)
:
void
;
storageClass
string
options
callback
void
setStorageClass(storageClass, callback)
setStorageClass
(
storageClass
:
string
,
callback
?:
SetStorageClassCallback
)
:
void
;
void
setUserProject(userProject)
setUserProject
(
userProject
:
string
)
:
void
;
Set a user project to be billed for all requests made from this File object.
userProject
string
The user project.
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
;
This creates a resumable-upload upload stream.
dup
Duplexify
options
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).
dup
Duplexify
Duplexify stream of data to pipe to the file.
options
void
