Class File (5.11.1)

A File object is created from your Bucket object using .

Inheritance

ServiceObject<File> > File

Package

@google-cloud/storage!

Constructors

(constructor)(bucket, name, options)

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

Constructs a file object.

Parameters

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

Properties

acl

acl: Acl;

Property Value

Type	Description
Acl

bucket

bucket: Bucket;

Property Value

Type	Description
Bucket

generation

generation?: number;

Property Value

Type	Description
number

kmsKeyName

kmsKeyName?: string;

Property Value

Type	Description
string

metadata

metadata: Metadata;

Property Value

Type	Description
Metadata

name

name: string;

Property Value

Type	Description
string

parent

parent: Bucket;

Property Value

Type	Description
Bucket

signer

signer?: URLSigner;

Property Value

Type	Description
URLSigner

storage

storage: Storage;

Property Value

Type	Description
Storage

userProject

userProject?: string;

Property Value

Type	Description
string

Methods

copy(destination, options)

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

Parameters

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

Returns

Type	Description
Promise<CopyResponse>

copy(destination, callback)

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

Parameters

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

Returns

Type	Description
void

copy(destination, options, callback)

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

Parameters

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

Returns

Type	Description
void

createReadStream(options)

createReadStream(options?: CreateReadStreamOptions): Readable;

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

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

For faster crc32c computation, you must manually install [fast-crc32c](https://www.npmjs.com/package/fast-crc32c):

$ npm install --save fast-crc32c

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

Parameter

Name	Description
options	`CreateReadStreamOptions` Configuration options.

Returns

Type	Description
Readable	{ReadableStream}

createResumableUpload(options)

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

Parameter

Name	Description
options	`CreateResumableUploadOptions`

Returns

Type	Description
Promise<CreateResumableUploadResponse>

createResumableUpload(options, callback)

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

Parameters

Name	Description
options	`CreateResumableUploadOptions`
callback	`CreateResumableUploadCallback`

Returns

Type	Description
void

createResumableUpload(callback)

createResumableUpload(callback: CreateResumableUploadCallback): void;

Parameter

Name	Description
callback	`CreateResumableUploadCallback`

Returns

Type	Description
void

createWriteStream(options)

createWriteStream(options?: CreateWriteStreamOptions): Writable;

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

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

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

Resumable uploads require write access to the $HOME directory. Through [config-store](https://www.npmjs.com/package/configstore), some metadata is stored. By default, if the directory is not writable, we will fall back to a simple upload. However, if you explicitly request a resumable upload, and we cannot write to the config directory, we will return a ResumableUploadError.

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.

For faster crc32c computation, you must manually install [fast-crc32c](https://www.npmjs.com/package/fast-crc32c):

$ npm install --save fast-crc32c

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

[Upload Options (Simple or Resumable)]https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload [Objects: insert API Documentation]https://cloud.google.com/storage/docs/json_api/v1/objects/insert

Parameter

Name	Description
options	`CreateWriteStreamOptions` Configuration options.

Returns

Type	Description
Writable	{WritableStream}

deleteResumableCache()

deleteResumableCache(): void;

Delete failed resumable upload file cache.

Resumable file upload cache the config file to restart upload in case of failure. In certain scenarios, the resumable upload will not works and upload file cache needs to be deleted to upload the same file.

Following are some of the scenarios.

Resumable file upload failed even though the file is successfully saved on the google storage and need to clean up a resumable file cache to update the same file.

Resumable file upload failed due to pre-condition (i.e generation number is not matched) and want to upload a same file with the new generation number.

Returns

Type	Description
void

download(options)

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

Parameter

Name	Description
options	`DownloadOptions`

Returns

Type	Description
Promise<DownloadResponse>

download(options, callback)

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

Parameters

Name	Description
options	`DownloadOptions`
callback	`DownloadCallback`

Returns

Type	Description
void

download(callback)

download(callback: DownloadCallback): void;

Parameter

Name	Description
callback	`DownloadCallback`

Returns

Type	Description
void

generateSignedPostPolicyV2(options)

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

Parameter

Name	Description
options	`GenerateSignedPostPolicyV2Options`

Returns

Type	Description
Promise<GenerateSignedPostPolicyV2Response>

generateSignedPostPolicyV2(options, callback)

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

Parameters

Name	Description
options	`GenerateSignedPostPolicyV2Options`
callback	`GenerateSignedPostPolicyV2Callback`

Returns

Type	Description
void

generateSignedPostPolicyV2(callback)

generateSignedPostPolicyV2(callback: GenerateSignedPostPolicyV2Callback): void;

Parameter

Name	Description
callback	`GenerateSignedPostPolicyV2Callback`

Returns

Type	Description
void

generateSignedPostPolicyV4(options)

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

Parameter

Name	Description
options	`GenerateSignedPostPolicyV4Options`

Returns

Type	Description
Promise<GenerateSignedPostPolicyV4Response>

generateSignedPostPolicyV4(options, callback)

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

Parameters

Name	Description
options	`GenerateSignedPostPolicyV4Options`
callback	`GenerateSignedPostPolicyV4Callback`

Returns

Type	Description
void

generateSignedPostPolicyV4(callback)

generateSignedPostPolicyV4(callback: GenerateSignedPostPolicyV4Callback): void;

Parameter

Name	Description
callback	`GenerateSignedPostPolicyV4Callback`

Returns

Type	Description
void

getExpirationDate()

getExpirationDate(): Promise<GetExpirationDateResponse>;

Returns

Type	Description
Promise<GetExpirationDateResponse>

getExpirationDate(callback)

getExpirationDate(callback: GetExpirationDateCallback): void;

Parameter

Name	Description
callback	`GetExpirationDateCallback`

Returns

Type	Description
void

getSignedPolicy(options)

getSignedPolicy(options: GetSignedPolicyOptions): Promise<GetSignedPolicyResponse>;

Parameter

Name	Description
options	`GetSignedPolicyOptions`

Returns

Type	Description
Promise<GetSignedPolicyResponse>

getSignedPolicy(options, callback)

getSignedPolicy(options: GetSignedPolicyOptions, callback: GetSignedPolicyCallback): void;

Parameters

Name	Description
options	`GetSignedPolicyOptions`
callback	`GetSignedPolicyCallback`

Returns

Type	Description
void

getSignedPolicy(callback)

getSignedPolicy(callback: GetSignedPolicyCallback): void;

Parameter

Name	Description
callback	`GetSignedPolicyCallback`

Returns

Type	Description
void

getSignedUrl(cfg)

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

Parameter

Name	Description
cfg	`GetSignedUrlConfig`

Returns

Type	Description
Promise<GetSignedUrlResponse>

getSignedUrl(cfg, callback)

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

Parameters

Name	Description
cfg	`GetSignedUrlConfig`
callback	`GetSignedUrlCallback`

Returns

Type	Description
void

isPublic()

isPublic(): Promise<IsPublicResponse>;

Returns

Type	Description
Promise<IsPublicResponse>

isPublic(callback)

isPublic(callback: IsPublicCallback): void;

Parameter

Name	Description
callback	`IsPublicCallback`

Returns

Type	Description
void

makePrivate(options)

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

Parameter

Name	Description
options	`MakeFilePrivateOptions`

Returns

Type	Description
Promise<MakeFilePrivateResponse>

makePrivate(callback)

makePrivate(callback: MakeFilePrivateCallback): void;

Parameter

Name	Description
callback	`MakeFilePrivateCallback`

Returns

Type	Description
void

makePrivate(options, callback)

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

Parameters

Name	Description
options	`MakeFilePrivateOptions`
callback	`MakeFilePrivateCallback`

Returns

Type	Description
void

makePublic()

makePublic(): Promise<MakeFilePublicResponse>;

Returns

Type	Description
Promise<MakeFilePublicResponse>

makePublic(callback)

makePublic(callback: MakeFilePublicCallback): void;

Parameter

Name	Description
callback	`MakeFilePublicCallback`

Returns

Type	Description
void

move(destination, options)

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

Parameters

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

Returns

Type	Description
Promise<MoveResponse>

move(destination, callback)

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

Parameters

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

Returns

Type	Description
void

move(destination, options, callback)

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

Parameters

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

Returns

Type	Description
void

publicUrl()

publicUrl(): string;

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

Returns

Type	Description
string	{string}

rename(destinationFile, options)

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

Parameters

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

Returns

Type	Description
Promise<RenameResponse>

rename(destinationFile, callback)

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

Parameters

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

Returns

Type	Description
void

rename(destinationFile, options, callback)

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

Parameters

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

Returns

Type	Description
void

request(reqOpts)

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

Parameter

Name	Description
reqOpts	`DecorateRequestOptions`

Returns

Type	Description
Promise<[ResponseBody, Metadata]>

request(reqOpts, callback)

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

Parameters

Name	Description
reqOpts	`DecorateRequestOptions`
callback	`BodyResponseCallback`

Returns

Type	Description
void

rotateEncryptionKey(options)

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

Parameter

Name	Description
options	`RotateEncryptionKeyOptions`

Returns

Type	Description
Promise<RotateEncryptionKeyResponse>

rotateEncryptionKey(callback)

rotateEncryptionKey(callback: RotateEncryptionKeyCallback): void;

Parameter

Name	Description
callback	`RotateEncryptionKeyCallback`

Returns

Type	Description
void

rotateEncryptionKey(options, callback)

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

Parameters

Name	Description
options	`RotateEncryptionKeyOptions`
callback	`RotateEncryptionKeyCallback`

Returns

Type	Description
void

save(data, options)

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

Parameters

Name	Description
data	`string \| Buffer`
options	`SaveOptions`

Returns

Type	Description
Promise<void>

save(data, callback)

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

Parameters

Name	Description
data	`string \| Buffer`
callback	`SaveCallback`

Returns

Type	Description
void

save(data, options, callback)

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

Parameters

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

Returns

Type	Description
void

setEncryptionKey(encryptionKey)

setEncryptionKey(encryptionKey: string | Buffer): this;

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

[Customer-supplied Encryption Keys]https://cloud.google.com/storage/docs/encryption#customer-supplied

Parameter

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

Returns

Type	Description
this	{File}

setStorageClass(storageClass, options)

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

Parameters

Name	Description
storageClass	`string`
options	`SetStorageClassOptions`

Returns

Type	Description
Promise<SetStorageClassResponse>

setStorageClass(storageClass, options, callback)

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

Parameters

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

Returns

Type	Description
void

setStorageClass(storageClass, callback)

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

Parameters

Name	Description
storageClass	`string`
callback	`SetStorageClassCallback`

Returns

Type	Description
void

setUserProject(userProject)

setUserProject(userProject: string): void;

Set a user project to be billed for all requests made from this File object.

Parameter

Name	Description
userProject	`string` The user project.

Returns

Type	Description
void

startResumableUpload_(dup, options)

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

This creates a gcs-resumable-upload upload stream.

[gcs-resumable-upload]https://github.com/stephenplusplus/gcs-resumable-upload

Parameters

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

Returns

Type	Description
void

startSimpleUpload_(dup, options)

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

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

Parameters

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

Returns

Type	Description
void