1 | /// <reference types="node" />
|
2 | import { BodyResponseCallback, DecorateRequestOptions, GetConfig, Metadata, ServiceObject } from '@google-cloud/common';
|
3 | import { Writable, Readable } from 'stream';
|
4 | import * as http from 'http';
|
5 | import { Storage } from './storage';
|
6 | import { Bucket } from './bucket';
|
7 | import { Acl } from './acl';
|
8 | import { GetSignedUrlResponse, GetSignedUrlCallback, URLSigner, Query } from './signer';
|
9 | import { ResponseBody, Duplexify } from '@google-cloud/common/build/src/util';
|
10 | export declare type GetExpirationDateResponse = [Date];
|
11 | export interface GetExpirationDateCallback {
|
12 | (err: Error | null, expirationDate?: Date | null, apiResponse?: Metadata): void;
|
13 | }
|
14 | export interface PolicyDocument {
|
15 | string: string;
|
16 | base64: string;
|
17 | signature: string;
|
18 | }
|
19 | export declare type GetSignedPolicyResponse = [PolicyDocument];
|
20 | export interface GetSignedPolicyCallback {
|
21 | (err: Error | null, policy?: PolicyDocument): void;
|
22 | }
|
23 | export interface GetSignedPolicyOptions {
|
24 | equals?: string[] | string[][];
|
25 | expires: string | number | Date;
|
26 | startsWith?: string[] | string[][];
|
27 | acl?: string;
|
28 | successRedirect?: string;
|
29 | successStatus?: string;
|
30 | contentLengthRange?: {
|
31 | min?: number;
|
32 | max?: number;
|
33 | };
|
34 | }
|
35 | export declare type GenerateSignedPostPolicyV2Options = GetSignedPolicyOptions;
|
36 | export declare type GenerateSignedPostPolicyV2Response = GetSignedPolicyResponse;
|
37 | export declare type GenerateSignedPostPolicyV2Callback = GetSignedPolicyCallback;
|
38 | export interface PolicyFields {
|
39 | [key: string]: string;
|
40 | }
|
41 | export interface GenerateSignedPostPolicyV4Options {
|
42 | expires: string | number | Date;
|
43 | bucketBoundHostname?: string;
|
44 | virtualHostedStyle?: boolean;
|
45 | conditions?: object[];
|
46 | fields?: PolicyFields;
|
47 | }
|
48 | export interface GenerateSignedPostPolicyV4Callback {
|
49 | (err: Error | null, output?: SignedPostPolicyV4Output): void;
|
50 | }
|
51 | export declare type GenerateSignedPostPolicyV4Response = [SignedPostPolicyV4Output];
|
52 | export interface SignedPostPolicyV4Output {
|
53 | url: string;
|
54 | fields: PolicyFields;
|
55 | }
|
56 | export interface GetSignedUrlConfig {
|
57 | action: 'read' | 'write' | 'delete' | 'resumable';
|
58 | version?: 'v2' | 'v4';
|
59 | virtualHostedStyle?: boolean;
|
60 | cname?: string;
|
61 | contentMd5?: string;
|
62 | contentType?: string;
|
63 | expires: string | number | Date;
|
64 | accessibleAt?: string | number | Date;
|
65 | extensionHeaders?: http.OutgoingHttpHeaders;
|
66 | promptSaveAs?: string;
|
67 | responseDisposition?: string;
|
68 | responseType?: string;
|
69 | queryParams?: Query;
|
70 | }
|
71 | export interface GetFileMetadataOptions {
|
72 | userProject?: string;
|
73 | }
|
74 | export declare type GetFileMetadataResponse = [Metadata, Metadata];
|
75 | export interface GetFileMetadataCallback {
|
76 | (err: Error | null, metadata?: Metadata, apiResponse?: Metadata): void;
|
77 | }
|
78 | export interface GetFileOptions extends GetConfig {
|
79 | userProject?: string;
|
80 | }
|
81 | export declare type GetFileResponse = [File, Metadata];
|
82 | export interface GetFileCallback {
|
83 | (err: Error | null, file?: File, apiResponse?: Metadata): void;
|
84 | }
|
85 | export interface FileExistsOptions {
|
86 | userProject?: string;
|
87 | }
|
88 | export declare type FileExistsResponse = [boolean];
|
89 | export interface FileExistsCallback {
|
90 | (err: Error | null, exists?: boolean): void;
|
91 | }
|
92 | export interface DeleteFileOptions {
|
93 | ignoreNotFound?: boolean;
|
94 | userProject?: string;
|
95 | }
|
96 | export declare type DeleteFileResponse = [Metadata];
|
97 | export interface DeleteFileCallback {
|
98 | (err: Error | null, apiResponse?: Metadata): void;
|
99 | }
|
100 | export declare type PredefinedAcl = 'authenticatedRead' | 'bucketOwnerFullControl' | 'bucketOwnerRead' | 'private' | 'projectPrivate' | 'publicRead';
|
101 | export interface CreateResumableUploadOptions {
|
102 | configPath?: string;
|
103 | metadata?: Metadata;
|
104 | origin?: string;
|
105 | offset?: number;
|
106 | predefinedAcl?: PredefinedAcl;
|
107 | private?: boolean;
|
108 | public?: boolean;
|
109 | uri?: string;
|
110 | userProject?: string;
|
111 | }
|
112 | export declare type CreateResumableUploadResponse = [string];
|
113 | export interface CreateResumableUploadCallback {
|
114 | (err: Error | null, uri?: string): void;
|
115 | }
|
116 | export interface CreateWriteStreamOptions extends CreateResumableUploadOptions {
|
117 | contentType?: string;
|
118 | gzip?: string | boolean;
|
119 | resumable?: boolean;
|
120 | timeout?: number;
|
121 | validation?: string | boolean;
|
122 | }
|
123 | export interface MakeFilePrivateOptions {
|
124 | metadata?: Metadata;
|
125 | strict?: boolean;
|
126 | userProject?: string;
|
127 | }
|
128 | export declare type MakeFilePrivateResponse = [Metadata];
|
129 | export declare type MakeFilePrivateCallback = SetFileMetadataCallback;
|
130 | export interface IsPublicCallback {
|
131 | (err: Error | null, resp?: boolean): void;
|
132 | }
|
133 | export declare type IsPublicResponse = [boolean];
|
134 | export declare type MakeFilePublicResponse = [Metadata];
|
135 | export interface MakeFilePublicCallback {
|
136 | (err?: Error | null, apiResponse?: Metadata): void;
|
137 | }
|
138 | export declare type MoveResponse = [Metadata];
|
139 | export interface MoveCallback {
|
140 | (err: Error | null, destinationFile?: File | null, apiResponse?: Metadata): void;
|
141 | }
|
142 | export interface MoveOptions {
|
143 | userProject?: string;
|
144 | }
|
145 | export declare type RenameOptions = MoveOptions;
|
146 | export declare type RenameResponse = MoveResponse;
|
147 | export declare type RenameCallback = MoveCallback;
|
148 | export declare type RotateEncryptionKeyOptions = string | Buffer | EncryptionKeyOptions;
|
149 | export interface EncryptionKeyOptions {
|
150 | encryptionKey?: string | Buffer;
|
151 | kmsKeyName?: string;
|
152 | }
|
153 | export declare type RotateEncryptionKeyCallback = CopyCallback;
|
154 | export declare type RotateEncryptionKeyResponse = CopyResponse;
|
155 | export declare enum ActionToHTTPMethod {
|
156 | read = "GET",
|
157 | write = "PUT",
|
158 | delete = "DELETE",
|
159 | resumable = "POST"
|
160 | }
|
161 | /**
|
162 | * @const {string}
|
163 | * @private
|
164 | */
|
165 | export declare const STORAGE_POST_POLICY_BASE_URL = "https://storage.googleapis.com";
|
166 | export interface FileOptions {
|
167 | encryptionKey?: string | Buffer;
|
168 | generation?: number | string;
|
169 | kmsKeyName?: string;
|
170 | userProject?: string;
|
171 | }
|
172 | export interface CopyOptions {
|
173 | cacheControl?: string;
|
174 | contentEncoding?: string;
|
175 | contentType?: string;
|
176 | contentDisposition?: string;
|
177 | destinationKmsKeyName?: string;
|
178 | metadata?: Metadata;
|
179 | predefinedAcl?: string;
|
180 | token?: string;
|
181 | userProject?: string;
|
182 | }
|
183 | export declare type CopyResponse = [File, Metadata];
|
184 | export interface CopyCallback {
|
185 | (err: Error | null, file?: File | null, apiResponse?: Metadata): void;
|
186 | }
|
187 | export declare type DownloadResponse = [Buffer];
|
188 | export declare type DownloadCallback = (err: RequestError | null, contents: Buffer) => void;
|
189 | export interface DownloadOptions extends CreateReadStreamOptions {
|
190 | destination?: string;
|
191 | }
|
192 | export interface CreateReadStreamOptions {
|
193 | userProject?: string;
|
194 | validation?: 'md5' | 'crc32c' | false | true;
|
195 | start?: number;
|
196 | end?: number;
|
197 | decompress?: boolean;
|
198 | }
|
199 | export interface SaveOptions extends CreateWriteStreamOptions {
|
200 | onUploadProgress?: (progressEvent: any) => void;
|
201 | }
|
202 | export interface SaveCallback {
|
203 | (err?: Error | null): void;
|
204 | }
|
205 | export interface SetFileMetadataOptions {
|
206 | userProject?: string;
|
207 | }
|
208 | export interface SetFileMetadataCallback {
|
209 | (err?: Error | null, apiResponse?: Metadata): void;
|
210 | }
|
211 | export declare type SetFileMetadataResponse = [Metadata];
|
212 | export declare type SetStorageClassResponse = [Metadata];
|
213 | export interface SetStorageClassOptions {
|
214 | userProject?: string;
|
215 | }
|
216 | export interface SetStorageClassCallback {
|
217 | (err?: Error | null, apiResponse?: Metadata): void;
|
218 | }
|
219 | declare class RequestError extends Error {
|
220 | code?: string;
|
221 | errors?: Error[];
|
222 | }
|
223 | /**
|
224 | * A File object is created from your {@link Bucket} object using
|
225 | * {@link Bucket#file}.
|
226 | *
|
227 | * @class
|
228 | */
|
229 | declare class File extends ServiceObject<File> {
|
230 | acl: Acl;
|
231 | bucket: Bucket;
|
232 | storage: Storage;
|
233 | kmsKeyName?: string;
|
234 | userProject?: string;
|
235 | signer?: URLSigner;
|
236 | metadata: Metadata;
|
237 | name: string;
|
238 | generation?: number;
|
239 | parent: Bucket;
|
240 | private encryptionKey?;
|
241 | private encryptionKeyBase64?;
|
242 | private encryptionKeyHash?;
|
243 | private encryptionKeyInterceptor?;
|
244 | /**
|
245 | * Cloud Storage uses access control lists (ACLs) to manage object and
|
246 | * bucket access. ACLs are the mechanism you use to share objects with other
|
247 | * users and allow other users to access your buckets and objects.
|
248 | *
|
249 | * An ACL consists of one or more entries, where each entry grants permissions
|
250 | * to an entity. Permissions define the actions that can be performed against
|
251 | * an object or bucket (for example, `READ` or `WRITE`); the entity defines
|
252 | * who the permission applies to (for example, a specific user or group of
|
253 | * users).
|
254 | *
|
255 | * The `acl` object on a File instance provides methods to get you a list of
|
256 | * the ACLs defined on your bucket, as well as set, update, and delete them.
|
257 | *
|
258 | * @see [About Access Control lists]{@link http://goo.gl/6qBBPO}
|
259 | *
|
260 | * @name File#acl
|
261 | * @mixes Acl
|
262 | *
|
263 | * @example
|
264 | * const {Storage} = require('@google-cloud/storage');
|
265 | * const storage = new Storage();
|
266 | * const myBucket = storage.bucket('my-bucket');
|
267 | *
|
268 | * const file = myBucket.file('my-file');
|
269 | * //-
|
270 | * // Make a file publicly readable.
|
271 | * //-
|
272 | * const options = {
|
273 | * entity: 'allUsers',
|
274 | * role: storage.acl.READER_ROLE
|
275 | * };
|
276 | *
|
277 | * file.acl.add(options, function(err, aclObject) {});
|
278 | *
|
279 | * //-
|
280 | * // If the callback is omitted, we'll return a Promise.
|
281 | * //-
|
282 | * file.acl.add(options).then(function(data) {
|
283 | * const aclObject = data[0];
|
284 | * const apiResponse = data[1];
|
285 | * });
|
286 | */
|
287 | /**
|
288 | * The API-formatted resource description of the file.
|
289 | *
|
290 | * Note: This is not guaranteed to be up-to-date when accessed. To get the
|
291 | * latest record, call the `getMetadata()` method.
|
292 | *
|
293 | * @name File#metadata
|
294 | * @type {object}
|
295 | */
|
296 | /**
|
297 | * The file's name.
|
298 | * @name File#name
|
299 | * @type {string}
|
300 | */
|
301 | /**
|
302 | * @typedef {object} FileOptions Options passed to the File constructor.
|
303 | * @property {string} [encryptionKey] A custom encryption key.
|
304 | * @property {number} [generation] Generation to scope the file to.
|
305 | * @property {string} [kmsKeyName] Cloud KMS Key used to encrypt this
|
306 | * object, if the object is encrypted by such a key. Limited availability;
|
307 | * usable only by enabled projects.
|
308 | * @property {string} [userProject] The ID of the project which will be
|
309 | * billed for all requests made from File object.
|
310 | */
|
311 | /**
|
312 | * Constructs a file object.
|
313 | *
|
314 | * @param {Bucket} bucket The Bucket instance this file is
|
315 | * attached to.
|
316 | * @param {string} name The name of the remote file.
|
317 | * @param {FileOptions} [options] Configuration options.
|
318 | * @example
|
319 | * const {Storage} = require('@google-cloud/storage');
|
320 | * const storage = new Storage();
|
321 | * const myBucket = storage.bucket('my-bucket');
|
322 | *
|
323 | * const file = myBucket.file('my-file');
|
324 | */
|
325 | constructor(bucket: Bucket, name: string, options?: FileOptions);
|
326 | copy(destination: string | Bucket | File, options?: CopyOptions): Promise<CopyResponse>;
|
327 | copy(destination: string | Bucket | File, callback: CopyCallback): void;
|
328 | copy(destination: string | Bucket | File, options: CopyOptions, callback: CopyCallback): void;
|
329 | /**
|
330 | * @typedef {object} CreateReadStreamOptions Configuration options for File#createReadStream.
|
331 | * string} [userProject] The ID of the project which will be
{ |
332 | * billed for the request.
|
333 | * string|boolean} [validation] Possible values: `"md5"`,
{ |
334 | * `"crc32c"`, or `false`. By default, data integrity is validated with a
|
335 | * CRC32c checksum. You may use MD5 if preferred, but that hash is not
|
336 | * supported for composite objects. An error will be raised if MD5 is
|
337 | * specified but is not available. You may also choose to skip validation
|
338 | * completely, however this is **not recommended**.
|
339 | * @property {number} [start] A byte offset to begin the file's download
|
340 | * from. Default is 0. NOTE: Byte ranges are inclusive; that is,
|
341 | * `options.start = 0` and `options.end = 999` represent the first 1000
|
342 | * bytes in a file or object. NOTE: when specifying a byte range, data
|
343 | * integrity is not available.
|
344 | * number} [end] A byte offset to stop reading the file at.
{ |
345 | * NOTE: Byte ranges are inclusive; that is, `options.start = 0` and
|
346 | * `options.end = 999` represent the first 1000 bytes in a file or object.
|
347 | * NOTE: when specifying a byte range, data integrity is not available.
|
348 | * boolean} [decompress=true] Disable auto decompression of the
{ |
349 | * received data. By default this option is set to `true`.
|
350 | * Applicable in cases where the data was uploaded with
|
351 | * `gzip: true` option. See { File#createWriteStream}.
|
352 | */
|
353 | /**
|
354 | * Create a readable stream to read the contents of the remote file. It can be
|
355 | * piped to a writable stream or listened to for 'data' events to read a
|
356 | * file's contents.
|
357 | *
|
358 | * In the unlikely event there is a mismatch between what you downloaded and
|
359 | * the version in your Bucket, your error handler will receive an error with
|
360 | * code "CONTENT_DOWNLOAD_MISMATCH". If you receive this error, the best
|
361 | * recourse is to try downloading the file again.
|
362 | *
|
363 | * For faster crc32c computation, you must manually install
|
364 | * [`fast-crc32c`](https://www.npmjs.com/package/fast-crc32c):
|
365 | *
|
366 | * $ npm install --save fast-crc32c
|
367 | *
|
368 | * NOTE: Readable streams will emit the `end` event when the file is fully
|
369 | * downloaded.
|
370 | *
|
371 | * @param {CreateReadStreamOptions} [options] Configuration options.
|
372 | * @returns {ReadableStream}
|
373 | *
|
374 | * @example
|
375 | * //-
|
376 | * // <h4>Downloading a File</h4>
|
377 | * //
|
378 | * // The example below demonstrates how we can reference a remote file, then
|
379 | * // pipe its contents to a local file. This is effectively creating a local
|
380 | * // backup of your remote data.
|
381 | * //-
|
382 | * const {Storage} = require('@google-cloud/storage');
|
383 | * const storage = new Storage();
|
384 | * const bucket = storage.bucket('my-bucket');
|
385 | *
|
386 | * const fs = require('fs');
|
387 | * const remoteFile = bucket.file('image.png');
|
388 | * const localFilename = '/Users/stephen/Photos/image.png';
|
389 | *
|
390 | * remoteFile.createReadStream()
|
391 | * .on('error', function(err) {})
|
392 | * .on('response', function(response) {
|
393 | * // Server connected and responded with the specified status and headers.
|
394 | * })
|
395 | * .on('end', function() {
|
396 | * // The file is fully downloaded.
|
397 | * })
|
398 | * .pipe(fs.createWriteStream(localFilename));
|
399 | *
|
400 | * //-
|
401 | * // To limit the downloaded data to only a byte range, pass an options
|
402 | * // object.
|
403 | * //-
|
404 | * const logFile = myBucket.file('access_log');
|
405 | * logFile.createReadStream({
|
406 | * start: 10000,
|
407 | * end: 20000
|
408 | * })
|
409 | * .on('error', function(err) {})
|
410 | * .pipe(fs.createWriteStream('/Users/stephen/logfile.txt'));
|
411 | *
|
412 | * //-
|
413 | * // To read a tail byte range, specify only `options.end` as a negative
|
414 | * // number.
|
415 | * //-
|
416 | * const logFile = myBucket.file('access_log');
|
417 | * logFile.createReadStream({
|
418 | * end: -100
|
419 | * })
|
420 | * .on('error', function(err) {})
|
421 | * .pipe(fs.createWriteStream('/Users/stephen/logfile.txt'));
|
422 | */
|
423 | createReadStream(options?: CreateReadStreamOptions): Readable;
|
424 | createResumableUpload(options?: CreateResumableUploadOptions): Promise<CreateResumableUploadResponse>;
|
425 | createResumableUpload(options: CreateResumableUploadOptions, callback: CreateResumableUploadCallback): void;
|
426 | createResumableUpload(callback: CreateResumableUploadCallback): void;
|
427 | /**
|
428 | * @typedef {object} CreateWriteStreamOptions Configuration options for File#createWriteStream().
|
429 | * @property {string} [configPath] **This only applies to resumable
|
430 | * uploads.** A full JSON file path to use with `gcs-resumable-upload`.
|
431 | * This maps to the [configstore option by the same
|
432 | * name](https://github.com/yeoman/configstore/tree/0df1ec950d952b1f0dfb39ce22af8e505dffc71a#configpath).
|
433 | * @property {string} [contentType] Alias for
|
434 | * `options.metadata.contentType`. If set to `auto`, the file name is used
|
435 | * to determine the contentType.
|
436 | * @property {string|boolean} [gzip] If true, automatically gzip the file.
|
437 | * If set to `auto`, the contentType is used to determine if the file
|
438 | * should be gzipped. This will set `options.metadata.contentEncoding` to
|
439 | * `gzip` if necessary.
|
440 | * @property {object} [metadata] See the examples below or
|
441 | * [Objects: insert request
|
442 | * body](https://cloud.google.com/storage/docs/json_api/v1/objects/insert#request_properties_JSON)
|
443 | * for more details.
|
444 | * @property {number} [offset] The starting byte of the upload stream, for
|
445 | * resuming an interrupted upload. Defaults to 0.
|
446 | * @property {string} [predefinedAcl] Apply a predefined set of access
|
447 | * controls to this object.
|
448 | *
|
449 | * Acceptable values are:
|
450 | * - **`authenticatedRead`** - Object owner gets `OWNER` access, and
|
451 | * `allAuthenticatedUsers` get `READER` access.
|
452 | *
|
453 | * - **`bucketOwnerFullControl`** - Object owner gets `OWNER` access, and
|
454 | * project team owners get `OWNER` access.
|
455 | *
|
456 | * - **`bucketOwnerRead`** - Object owner gets `OWNER` access, and project
|
457 | * team owners get `READER` access.
|
458 | *
|
459 | * - **`private`** - Object owner gets `OWNER` access.
|
460 | *
|
461 | * - **`projectPrivate`** - Object owner gets `OWNER` access, and project
|
462 | * team members get access according to their roles.
|
463 | *
|
464 | * - **`publicRead`** - Object owner gets `OWNER` access, and `allUsers`
|
465 | * get `READER` access.
|
466 | * @property {boolean} [private] Make the uploaded file private. (Alias for
|
467 | * `options.predefinedAcl = 'private'`)
|
468 | * @property {boolean} [public] Make the uploaded file public. (Alias for
|
469 | * `options.predefinedAcl = 'publicRead'`)
|
470 | * @property {boolean} [resumable] Force a resumable upload. NOTE: When
|
471 | * working with streams, the file format and size is unknown until it's
|
472 | * completely consumed. Because of this, it's best for you to be explicit
|
473 | * for what makes sense given your input.
|
474 | * @param {number} [timeout=60000] Set the HTTP request timeout in
|
475 | * milliseconds. This option is not available for resumable uploads.
|
476 | * Default: `60000`
|
477 | * @property {string} [uri] The URI for an already-created resumable
|
478 | * upload. See {@link File#createResumableUpload}.
|
479 | * @property {string} [userProject] The ID of the project which will be
|
480 | * billed for the request.
|
481 | * @property {string|boolean} [validation] Possible values: `"md5"`,
|
482 | * `"crc32c"`, or `false`. By default, data integrity is validated with a
|
483 | * CRC32c checksum. You may use MD5 if preferred, but that hash is not
|
484 | * supported for composite objects. An error will be raised if MD5 is
|
485 | * specified but is not available. You may also choose to skip validation
|
486 | * completely, however this is **not recommended**.
|
487 | * NOTE: Validation is automatically skipped for objects that were
|
488 | * uploaded using the `gzip` option and have already compressed content.
|
489 | */
|
490 | /**
|
491 | * Create a writable stream to overwrite the contents of the file in your
|
492 | * bucket.
|
493 | *
|
494 | * A File object can also be used to create files for the first time.
|
495 | *
|
496 | * Resumable uploads are automatically enabled and must be shut off explicitly
|
497 | * by setting `options.resumable` to `false`.
|
498 | *
|
499 | * Resumable uploads require write access to the $HOME directory. Through
|
500 | * [`config-store`](https://www.npmjs.com/package/configstore), some metadata
|
501 | * is stored. By default, if the directory is not writable, we will fall back
|
502 | * to a simple upload. However, if you explicitly request a resumable upload,
|
503 | * and we cannot write to the config directory, we will return a
|
504 | * `ResumableUploadError`.
|
505 | *
|
506 | * <p class="notice">
|
507 | * There is some overhead when using a resumable upload that can cause
|
508 | * noticeable performance degradation while uploading a series of small
|
509 | * files. When uploading files less than 10MB, it is recommended that the
|
510 | * resumable feature is disabled.
|
511 | * </p>
|
512 | *
|
513 | * For faster crc32c computation, you must manually install
|
514 | * [`fast-crc32c`](https://www.npmjs.com/package/fast-crc32c):
|
515 | *
|
516 | * $ npm install --save fast-crc32c
|
517 | *
|
518 | * NOTE: Writable streams will emit the `finish` event when the file is fully
|
519 | * uploaded.
|
520 | *
|
521 | * @see [Upload Options (Simple or Resumable)]{@link https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload}
|
522 | * @see [Objects: insert API Documentation]{@link https://cloud.google.com/storage/docs/json_api/v1/objects/insert}
|
523 | *
|
524 | * @param {CreateWriteStreamOptions} [options] Configuration options.
|
525 | * @returns {WritableStream}
|
526 | *
|
527 | * @example
|
528 | * const fs = require('fs');
|
529 | * const {Storage} = require('@google-cloud/storage');
|
530 | * const storage = new Storage();
|
531 | * const myBucket = storage.bucket('my-bucket');
|
532 | *
|
533 | * const file = myBucket.file('my-file');
|
534 | *
|
535 | * //-
|
536 | * // <h4>Uploading a File</h4>
|
537 | * //
|
538 | * // Now, consider a case where we want to upload a file to your bucket. You
|
539 | * // have the option of using {@link Bucket#upload}, but that is just
|
540 | * // a convenience method which will do the following.
|
541 | * //-
|
542 | * fs.createReadStream('/Users/stephen/Photos/birthday-at-the-zoo/panda.jpg')
|
543 | * .pipe(file.createWriteStream())
|
544 | * .on('error', function(err) {})
|
545 | * .on('finish', function() {
|
546 | * // The file upload is complete.
|
547 | * });
|
548 | *
|
549 | * //-
|
550 | * // <h4>Uploading a File with gzip compression</h4>
|
551 | * //-
|
552 | * fs.createReadStream('/Users/stephen/site/index.html')
|
553 | * .pipe(file.createWriteStream({ gzip: true }))
|
554 | * .on('error', function(err) {})
|
555 | * .on('finish', function() {
|
556 | * // The file upload is complete.
|
557 | * });
|
558 | *
|
559 | * //-
|
560 | * // Downloading the file with `createReadStream` will automatically decode
|
561 | * // the file.
|
562 | * //-
|
563 | *
|
564 | * //-
|
565 | * // <h4>Uploading a File with Metadata</h4>
|
566 | * //
|
567 | * // One last case you may run into is when you want to upload a file to your
|
568 | * // bucket and set its metadata at the same time. Like above, you can use
|
569 | * // {@link Bucket#upload} to do this, which is just a wrapper around
|
570 | * // the following.
|
571 | * //-
|
572 | * fs.createReadStream('/Users/stephen/Photos/birthday-at-the-zoo/panda.jpg')
|
573 | * .pipe(file.createWriteStream({
|
574 | * metadata: {
|
575 | * contentType: 'image/jpeg',
|
576 | * metadata: {
|
577 | * custom: 'metadata'
|
578 | * }
|
579 | * }
|
580 | * }))
|
581 | * .on('error', function(err) {})
|
582 | * .on('finish', function() {
|
583 | * // The file upload is complete.
|
584 | * });
|
585 | */
|
586 | createWriteStream(options?: CreateWriteStreamOptions): Writable;
|
587 | /**
|
588 | * Delete failed resumable upload file cache.
|
589 | *
|
590 | * Resumable file upload cache the config file to restart upload in case of
|
591 | * failure. In certain scenarios, the resumable upload will not works and
|
592 | * upload file cache needs to be deleted to upload the same file.
|
593 | *
|
594 | * Following are some of the scenarios.
|
595 | *
|
596 | * Resumable file upload failed even though the file is successfully saved
|
597 | * on the google storage and need to clean up a resumable file cache to
|
598 | * update the same file.
|
599 | *
|
600 | * Resumable file upload failed due to pre-condition
|
601 | * (i.e generation number is not matched) and want to upload a same
|
602 | * file with the new generation number.
|
603 | *
|
604 | * @example
|
605 | * const {Storage} = require('@google-cloud/storage');
|
606 | * const storage = new Storage();
|
607 | * const myBucket = storage.bucket('my-bucket');
|
608 | *
|
609 | * const file = myBucket.file('my-file', { generation: 0 });
|
610 | * const contents = 'This is the contents of the file.';
|
611 | *
|
612 | * file.save(contents, function(err) {
|
613 | * if (err) {
|
614 | * file.deleteResumableCache();
|
615 | * }
|
616 | * });
|
617 | *
|
618 | */
|
619 | deleteResumableCache(): void;
|
620 | download(options?: DownloadOptions): Promise<DownloadResponse>;
|
621 | download(options: DownloadOptions, callback: DownloadCallback): void;
|
622 | download(callback: DownloadCallback): void;
|
623 | /**
|
624 | * The Storage API allows you to use a custom key for server-side encryption.
|
625 | *
|
626 | * @see [Customer-supplied Encryption Keys]{@link https://cloud.google.com/storage/docs/encryption#customer-supplied}
|
627 | *
|
628 | * @param {string|buffer} encryptionKey An AES-256 encryption key.
|
629 | * @returns {File}
|
630 | *
|
631 | * @example
|
632 | * const crypto = require('crypto');
|
633 | * const {Storage} = require('@google-cloud/storage');
|
634 | * const storage = new Storage();
|
635 | * const myBucket = storage.bucket('my-bucket');
|
636 | *
|
637 | * const encryptionKey = crypto.randomBytes(32);
|
638 | *
|
639 | * const fileWithCustomEncryption = myBucket.file('my-file');
|
640 | * fileWithCustomEncryption.setEncryptionKey(encryptionKey);
|
641 | *
|
642 | * const fileWithoutCustomEncryption = myBucket.file('my-file');
|
643 | *
|
644 | * fileWithCustomEncryption.save('data', function(err) {
|
645 | * // Try to download with the File object that hasn't had
|
646 | * // `setEncryptionKey()` called:
|
647 | * fileWithoutCustomEncryption.download(function(err) {
|
648 | * // We will receive an error:
|
649 | * // err.message === 'Bad Request'
|
650 | *
|
651 | * // Try again with the File object we called `setEncryptionKey()` on:
|
652 | * fileWithCustomEncryption.download(function(err, contents) {
|
653 | * // contents.toString() === 'data'
|
654 | * });
|
655 | * });
|
656 | * });
|
657 | *
|
658 | * @example <caption>include:samples/encryption.js</caption>
|
659 | * region_tag:storage_upload_encrypted_file
|
660 | * Example of uploading an encrypted file:
|
661 | *
|
662 | * @example <caption>include:samples/encryption.js</caption>
|
663 | * region_tag:storage_download_encrypted_file
|
664 | * Example of downloading an encrypted file:
|
665 | */
|
666 | setEncryptionKey(encryptionKey: string | Buffer): this;
|
667 | getExpirationDate(): Promise<GetExpirationDateResponse>;
|
668 | getExpirationDate(callback: GetExpirationDateCallback): void;
|
669 | getSignedPolicy(options: GetSignedPolicyOptions): Promise<GetSignedPolicyResponse>;
|
670 | getSignedPolicy(options: GetSignedPolicyOptions, callback: GetSignedPolicyCallback): void;
|
671 | getSignedPolicy(callback: GetSignedPolicyCallback): void;
|
672 | generateSignedPostPolicyV2(options: GenerateSignedPostPolicyV2Options): Promise<GenerateSignedPostPolicyV2Response>;
|
673 | generateSignedPostPolicyV2(options: GenerateSignedPostPolicyV2Options, callback: GenerateSignedPostPolicyV2Callback): void;
|
674 | generateSignedPostPolicyV2(callback: GenerateSignedPostPolicyV2Callback): void;
|
675 | generateSignedPostPolicyV4(options: GenerateSignedPostPolicyV4Options): Promise<GenerateSignedPostPolicyV4Response>;
|
676 | generateSignedPostPolicyV4(options: GenerateSignedPostPolicyV4Options, callback: GenerateSignedPostPolicyV4Callback): void;
|
677 | generateSignedPostPolicyV4(callback: GenerateSignedPostPolicyV4Callback): void;
|
678 | getSignedUrl(cfg: GetSignedUrlConfig): Promise<GetSignedUrlResponse>;
|
679 | getSignedUrl(cfg: GetSignedUrlConfig, callback: GetSignedUrlCallback): void;
|
680 | isPublic(): Promise<IsPublicResponse>;
|
681 | isPublic(callback: IsPublicCallback): void;
|
682 | makePrivate(options?: MakeFilePrivateOptions): Promise<MakeFilePrivateResponse>;
|
683 | makePrivate(callback: MakeFilePrivateCallback): void;
|
684 | makePrivate(options: MakeFilePrivateOptions, callback: MakeFilePrivateCallback): void;
|
685 | makePublic(): Promise<MakeFilePublicResponse>;
|
686 | makePublic(callback: MakeFilePublicCallback): void;
|
687 | /**
|
688 | * The public URL of this File
|
689 | * Use {@link File#makePublic} to enable anonymous access via the returned URL.
|
690 | *
|
691 | * @returns {string}
|
692 | *
|
693 | * @example
|
694 | * const {Storage} = require('@google-cloud/storage');
|
695 | * const storage = new Storage();
|
696 | * const bucket = storage.bucket('albums');
|
697 | * const file = bucket.file('my-file');
|
698 | *
|
699 | * // publicUrl will be "https://storage.googleapis.com/albums/my-file"
|
700 | * const publicUrl = file.publicUrl();
|
701 | */
|
702 | publicUrl(): string;
|
703 | move(destination: string | Bucket | File, options?: MoveOptions): Promise<MoveResponse>;
|
704 | move(destination: string | Bucket | File, callback: MoveCallback): void;
|
705 | move(destination: string | Bucket | File, options: MoveOptions, callback: MoveCallback): void;
|
706 | rename(destinationFile: string | File, options?: RenameOptions): Promise<RenameResponse>;
|
707 | rename(destinationFile: string | File, callback: RenameCallback): void;
|
708 | rename(destinationFile: string | File, options: RenameOptions, callback: RenameCallback): void;
|
709 | request(reqOpts: DecorateRequestOptions): Promise<[ResponseBody, Metadata]>;
|
710 | request(reqOpts: DecorateRequestOptions, callback: BodyResponseCallback): void;
|
711 | rotateEncryptionKey(options?: RotateEncryptionKeyOptions): Promise<RotateEncryptionKeyResponse>;
|
712 | rotateEncryptionKey(callback: RotateEncryptionKeyCallback): void;
|
713 | rotateEncryptionKey(options: RotateEncryptionKeyOptions, callback: RotateEncryptionKeyCallback): void;
|
714 | save(data: string | Buffer, options?: SaveOptions): Promise<void>;
|
715 | save(data: string | Buffer, callback: SaveCallback): void;
|
716 | save(data: string | Buffer, options: SaveOptions, callback: SaveCallback): void;
|
717 | setStorageClass(storageClass: string, options?: SetStorageClassOptions): Promise<SetStorageClassResponse>;
|
718 | setStorageClass(storageClass: string, options: SetStorageClassOptions, callback: SetStorageClassCallback): void;
|
719 | setStorageClass(storageClass: string, callback?: SetStorageClassCallback): void;
|
720 | /**
|
721 | * Set a user project to be billed for all requests made from this File
|
722 | * object.
|
723 | *
|
724 | * @param {string} userProject The user project.
|
725 | *
|
726 | * @example
|
727 | * const {Storage} = require('@google-cloud/storage');
|
728 | * const storage = new Storage();
|
729 | * const bucket = storage.bucket('albums');
|
730 | * const file = bucket.file('my-file');
|
731 | *
|
732 | * file.setUserProject('grape-spaceship-123');
|
733 | */
|
734 | setUserProject(userProject: string): void;
|
735 | /**
|
736 | * This creates a gcs-resumable-upload upload stream.
|
737 | *
|
738 | * @see [gcs-resumable-upload]{@link https://github.com/stephenplusplus/gcs-resumable-upload}
|
739 | *
|
740 | * @param {Duplexify} stream - Duplexify stream of data to pipe to the file.
|
741 | * @param {object=} options - Configuration object.
|
742 | *
|
743 | * @private
|
744 | */
|
745 | startResumableUpload_(dup: Duplexify, options: CreateResumableUploadOptions): void;
|
746 | /**
|
747 | * Takes a readable stream and pipes it to a remote file. Unlike
|
748 | * `startResumableUpload_`, which uses the resumable upload technique, this
|
749 | * method uses a simple upload (all or nothing).
|
750 | *
|
751 | * @param {Duplexify} dup - Duplexify stream of data to pipe to the file.
|
752 | * @param {object=} options - Configuration object.
|
753 | *
|
754 | * @private
|
755 | */
|
756 | startSimpleUpload_(dup: Duplexify, options?: CreateWriteStreamOptions): void;
|
757 | }
|
758 | /**
|
759 | * Reference to the {@link File} class.
|
760 | * @name module:@google-cloud/storage.File
|
761 | * @see File
|
762 | */
|
763 | export { File };
|