1 | /// <reference types="node" />
|
2 | import { ApiError, Service, ServiceOptions } from './nodejs-common/index.js';
|
3 | import { Readable } from 'stream';
|
4 | import { Bucket } from './bucket.js';
|
5 | import { Channel } from './channel.js';
|
6 | import { File } from './file.js';
|
7 | import { HmacKey, HmacKeyMetadata, HmacKeyOptions } from './hmacKey.js';
|
8 | import { CRC32CValidatorGenerator } from './crc32c.js';
|
9 | export interface GetServiceAccountOptions {
|
10 | userProject?: string;
|
11 | }
|
12 | export interface ServiceAccount {
|
13 | emailAddress?: string;
|
14 | }
|
15 | export type GetServiceAccountResponse = [ServiceAccount, unknown];
|
16 | export interface GetServiceAccountCallback {
|
17 | (err: Error | null, serviceAccount?: ServiceAccount, apiResponse?: unknown): void;
|
18 | }
|
19 | export interface CreateBucketQuery {
|
20 | project: string;
|
21 | userProject: string;
|
22 | enableObjectRetention: boolean;
|
23 | }
|
24 | export declare enum IdempotencyStrategy {
|
25 | RetryAlways = 0,
|
26 | RetryConditional = 1,
|
27 | RetryNever = 2
|
28 | }
|
29 | export interface RetryOptions {
|
30 | retryDelayMultiplier?: number;
|
31 | totalTimeout?: number;
|
32 | maxRetryDelay?: number;
|
33 | autoRetry?: boolean;
|
34 | maxRetries?: number;
|
35 | retryableErrorFn?: (err: ApiError) => boolean;
|
36 | idempotencyStrategy?: IdempotencyStrategy;
|
37 | }
|
38 | export interface PreconditionOptions {
|
39 | ifGenerationMatch?: number | string;
|
40 | ifGenerationNotMatch?: number | string;
|
41 | ifMetagenerationMatch?: number | string;
|
42 | ifMetagenerationNotMatch?: number | string;
|
43 | }
|
44 | export interface StorageOptions extends ServiceOptions {
|
45 | /**
|
46 | * The API endpoint of the service used to make requests.
|
47 | * Defaults to `storage.googleapis.com`.
|
48 | */
|
49 | apiEndpoint?: string;
|
50 | crc32cGenerator?: CRC32CValidatorGenerator;
|
51 | retryOptions?: RetryOptions;
|
52 | }
|
53 | export interface BucketOptions {
|
54 | crc32cGenerator?: CRC32CValidatorGenerator;
|
55 | kmsKeyName?: string;
|
56 | preconditionOpts?: PreconditionOptions;
|
57 | userProject?: string;
|
58 | }
|
59 | export interface Cors {
|
60 | maxAgeSeconds?: number;
|
61 | method?: string[];
|
62 | origin?: string[];
|
63 | responseHeader?: string[];
|
64 | }
|
65 | interface Versioning {
|
66 | enabled: boolean;
|
67 | }
|
68 | /**
|
69 | * Custom placement configuration.
|
70 | * Initially used for dual-region buckets.
|
71 | **/
|
72 | export interface CustomPlacementConfig {
|
73 | dataLocations?: string[];
|
74 | }
|
75 | export interface AutoclassConfig {
|
76 | enabled?: boolean;
|
77 | terminalStorageClass?: 'NEARLINE' | 'ARCHIVE';
|
78 | }
|
79 | export interface CreateBucketRequest {
|
80 | archive?: boolean;
|
81 | autoclass?: AutoclassConfig;
|
82 | coldline?: boolean;
|
83 | cors?: Cors[];
|
84 | customPlacementConfig?: CustomPlacementConfig;
|
85 | dra?: boolean;
|
86 | enableObjectRetention?: boolean;
|
87 | location?: string;
|
88 | multiRegional?: boolean;
|
89 | nearline?: boolean;
|
90 | regional?: boolean;
|
91 | requesterPays?: boolean;
|
92 | retentionPolicy?: object;
|
93 | rpo?: string;
|
94 | standard?: boolean;
|
95 | storageClass?: string;
|
96 | userProject?: string;
|
97 | versioning?: Versioning;
|
98 | }
|
99 | export type CreateBucketResponse = [Bucket, unknown];
|
100 | export interface BucketCallback {
|
101 | (err: Error | null, bucket?: Bucket | null, apiResponse?: unknown): void;
|
102 | }
|
103 | export type GetBucketsResponse = [Bucket[], {}, unknown];
|
104 | export interface GetBucketsCallback {
|
105 | (err: Error | null, buckets: Bucket[], nextQuery?: {}, apiResponse?: unknown): void;
|
106 | }
|
107 | export interface GetBucketsRequest {
|
108 | prefix?: string;
|
109 | project?: string;
|
110 | autoPaginate?: boolean;
|
111 | maxApiCalls?: number;
|
112 | maxResults?: number;
|
113 | pageToken?: string;
|
114 | userProject?: string;
|
115 | }
|
116 | export interface HmacKeyResourceResponse {
|
117 | metadata: HmacKeyMetadata;
|
118 | secret: string;
|
119 | }
|
120 | export type CreateHmacKeyResponse = [HmacKey, string, HmacKeyResourceResponse];
|
121 | export interface CreateHmacKeyOptions {
|
122 | projectId?: string;
|
123 | userProject?: string;
|
124 | }
|
125 | export interface CreateHmacKeyCallback {
|
126 | (err: Error | null, hmacKey?: HmacKey | null, secret?: string | null, apiResponse?: HmacKeyResourceResponse): void;
|
127 | }
|
128 | export interface GetHmacKeysOptions {
|
129 | projectId?: string;
|
130 | serviceAccountEmail?: string;
|
131 | showDeletedKeys?: boolean;
|
132 | autoPaginate?: boolean;
|
133 | maxApiCalls?: number;
|
134 | maxResults?: number;
|
135 | pageToken?: string;
|
136 | userProject?: string;
|
137 | }
|
138 | export interface GetHmacKeysCallback {
|
139 | (err: Error | null, hmacKeys: HmacKey[] | null, nextQuery?: {}, apiResponse?: unknown): void;
|
140 | }
|
141 | export declare enum ExceptionMessages {
|
142 | EXPIRATION_DATE_INVALID = "The expiration date provided was invalid.",
|
143 | EXPIRATION_DATE_PAST = "An expiration date cannot be in the past."
|
144 | }
|
145 | export declare enum StorageExceptionMessages {
|
146 | BUCKET_NAME_REQUIRED = "A bucket name is needed to use Cloud Storage.",
|
147 | BUCKET_NAME_REQUIRED_CREATE = "A name is required to create a bucket.",
|
148 | HMAC_SERVICE_ACCOUNT = "The first argument must be a service account email to create an HMAC key.",
|
149 | HMAC_ACCESS_ID = "An access ID is needed to create an HmacKey object."
|
150 | }
|
151 | export type GetHmacKeysResponse = [HmacKey[]];
|
152 | export declare const PROTOCOL_REGEX: RegExp;
|
153 | /**
|
154 | * Default behavior: Automatically retry retriable server errors.
|
155 | *
|
156 | * @const {boolean}
|
157 | */
|
158 | export declare const AUTO_RETRY_DEFAULT = true;
|
159 | /**
|
160 | * Default behavior: Only attempt to retry retriable errors 3 times.
|
161 | *
|
162 | * @const {number}
|
163 | */
|
164 | export declare const MAX_RETRY_DEFAULT = 3;
|
165 | /**
|
166 | * Default behavior: Wait twice as long as previous retry before retrying.
|
167 | *
|
168 | * @const {number}
|
169 | */
|
170 | export declare const RETRY_DELAY_MULTIPLIER_DEFAULT = 2;
|
171 | /**
|
172 | * Default behavior: If the operation doesn't succeed after 600 seconds,
|
173 | * stop retrying.
|
174 | *
|
175 | * @const {number}
|
176 | */
|
177 | export declare const TOTAL_TIMEOUT_DEFAULT = 600;
|
178 | /**
|
179 | * Default behavior: Wait no more than 64 seconds between retries.
|
180 | *
|
181 | * @const {number}
|
182 | */
|
183 | export declare const MAX_RETRY_DELAY_DEFAULT = 64;
|
184 | /**
|
185 | * Returns true if the API request should be retried, given the error that was
|
186 | * given the first time the request was attempted.
|
187 | * @const
|
188 | * @param {error} err - The API error to check if it is appropriate to retry.
|
189 | * @return {boolean} True if the API request should be retried, false otherwise.
|
190 | */
|
191 | export declare const RETRYABLE_ERR_FN_DEFAULT: (err?: ApiError) => boolean;
|
192 | /*! Developer Documentation
|
193 | *
|
194 | * Invoke this method to create a new Storage object bound with pre-determined
|
195 | * configuration options. For each object that can be created (e.g., a bucket),
|
196 | * there is an equivalent static and instance method. While they are classes,
|
197 | * they can be instantiated without use of the `new` keyword.
|
198 | */
|
199 | /**
|
200 | * Cloud Storage uses access control lists (ACLs) to manage object and
|
201 | * bucket access. ACLs are the mechanism you use to share objects with other
|
202 | * users and allow other users to access your buckets and objects.
|
203 | *
|
204 | * This object provides constants to refer to the three permission levels that
|
205 | * can be granted to an entity:
|
206 | *
|
207 | * - `gcs.acl.OWNER_ROLE` - ("OWNER")
|
208 | * - `gcs.acl.READER_ROLE` - ("READER")
|
209 | * - `gcs.acl.WRITER_ROLE` - ("WRITER")
|
210 | *
|
211 | * See {@link https://cloud.google.com/storage/docs/access-control/lists| About Access Control Lists}
|
212 | *
|
213 | * @name Storage#acl
|
214 | * @type {object}
|
215 | * @property {string} OWNER_ROLE
|
216 | * @property {string} READER_ROLE
|
217 | * @property {string} WRITER_ROLE
|
218 | *
|
219 | * @example
|
220 | * ```
|
221 | * const {Storage} = require('@google-cloud/storage');
|
222 | * const storage = new Storage();
|
223 | * const albums = storage.bucket('albums');
|
224 | *
|
225 | * //-
|
226 | * // Make all of the files currently in a bucket publicly readable.
|
227 | * //-
|
228 | * const options = {
|
229 | * entity: 'allUsers',
|
230 | * role: storage.acl.READER_ROLE
|
231 | * };
|
232 | *
|
233 | * albums.acl.add(options, function(err, aclObject) {});
|
234 | *
|
235 | * //-
|
236 | * // Make any new objects added to a bucket publicly readable.
|
237 | * //-
|
238 | * albums.acl.default.add(options, function(err, aclObject) {});
|
239 | *
|
240 | * //-
|
241 | * // Grant a user ownership permissions to a bucket.
|
242 | * //-
|
243 | * albums.acl.add({
|
244 | * entity: 'user-useremail@example.com',
|
245 | * role: storage.acl.OWNER_ROLE
|
246 | * }, function(err, aclObject) {});
|
247 | *
|
248 | * //-
|
249 | * // If the callback is omitted, we'll return a Promise.
|
250 | * //-
|
251 | * albums.acl.add(options).then(function(data) {
|
252 | * const aclObject = data[0];
|
253 | * const apiResponse = data[1];
|
254 | * });
|
255 | * ```
|
256 | */
|
257 | /**
|
258 | * Get {@link Bucket} objects for all of the buckets in your project as
|
259 | * a readable object stream.
|
260 | *
|
261 | * @method Storage#getBucketsStream
|
262 | * @param {GetBucketsRequest} [query] Query object for listing buckets.
|
263 | * @returns {ReadableStream} A readable stream that emits {@link Bucket}
|
264 | * instances.
|
265 | *
|
266 | * @example
|
267 | * ```
|
268 | * storage.getBucketsStream()
|
269 | * .on('error', console.error)
|
270 | * .on('data', function(bucket) {
|
271 | * // bucket is a Bucket object.
|
272 | * })
|
273 | * .on('end', function() {
|
274 | * // All buckets retrieved.
|
275 | * });
|
276 | *
|
277 | * //-
|
278 | * // If you anticipate many results, you can end a stream early to prevent
|
279 | * // unnecessary processing and API requests.
|
280 | * //-
|
281 | * storage.getBucketsStream()
|
282 | * .on('data', function(bucket) {
|
283 | * this.end();
|
284 | * });
|
285 | * ```
|
286 | */
|
287 | /**
|
288 | * Get {@link HmacKey} objects for all of the HMAC keys in the project in a
|
289 | * readable object stream.
|
290 | *
|
291 | * @method Storage#getHmacKeysStream
|
292 | * @param {GetHmacKeysOptions} [options] Configuration options.
|
293 | * @returns {ReadableStream} A readable stream that emits {@link HmacKey}
|
294 | * instances.
|
295 | *
|
296 | * @example
|
297 | * ```
|
298 | * storage.getHmacKeysStream()
|
299 | * .on('error', console.error)
|
300 | * .on('data', function(hmacKey) {
|
301 | * // hmacKey is an HmacKey object.
|
302 | * })
|
303 | * .on('end', function() {
|
304 | * // All HmacKey retrieved.
|
305 | * });
|
306 | *
|
307 | * //-
|
308 | * // If you anticipate many results, you can end a stream early to prevent
|
309 | * // unnecessary processing and API requests.
|
310 | * //-
|
311 | * storage.getHmacKeysStream()
|
312 | * .on('data', function(bucket) {
|
313 | * this.end();
|
314 | * });
|
315 | * ```
|
316 | */
|
317 | /**
|
318 | * <h4>ACLs</h4>
|
319 | * Cloud Storage uses access control lists (ACLs) to manage object and
|
320 | * bucket access. ACLs are the mechanism you use to share files with other users
|
321 | * and allow other users to access your buckets and files.
|
322 | *
|
323 | * To learn more about ACLs, read this overview on
|
324 | * {@link https://cloud.google.com/storage/docs/access-control| Access Control}.
|
325 | *
|
326 | * See {@link https://cloud.google.com/storage/docs/overview| Cloud Storage overview}
|
327 | * See {@link https://cloud.google.com/storage/docs/access-control| Access Control}
|
328 | *
|
329 | * @class
|
330 | */
|
331 | export declare class Storage extends Service {
|
332 | /**
|
333 | * {@link Bucket} class.
|
334 | *
|
335 | * @name Storage.Bucket
|
336 | * @see Bucket
|
337 | * @type {Constructor}
|
338 | */
|
339 | static Bucket: typeof Bucket;
|
340 | /**
|
341 | * {@link Channel} class.
|
342 | *
|
343 | * @name Storage.Channel
|
344 | * @see Channel
|
345 | * @type {Constructor}
|
346 | */
|
347 | static Channel: typeof Channel;
|
348 | /**
|
349 | * {@link File} class.
|
350 | *
|
351 | * @name Storage.File
|
352 | * @see File
|
353 | * @type {Constructor}
|
354 | */
|
355 | static File: typeof File;
|
356 | /**
|
357 | * {@link HmacKey} class.
|
358 | *
|
359 | * @name Storage.HmacKey
|
360 | * @see HmacKey
|
361 | * @type {Constructor}
|
362 | */
|
363 | static HmacKey: typeof HmacKey;
|
364 | static acl: {
|
365 | OWNER_ROLE: string;
|
366 | READER_ROLE: string;
|
367 | WRITER_ROLE: string;
|
368 | };
|
369 | /**
|
370 | * Reference to {@link Storage.acl}.
|
371 | *
|
372 | * @name Storage#acl
|
373 | * @see Storage.acl
|
374 | */
|
375 | acl: typeof Storage.acl;
|
376 | crc32cGenerator: CRC32CValidatorGenerator;
|
377 | getBucketsStream(): Readable;
|
378 | getHmacKeysStream(): Readable;
|
379 | retryOptions: RetryOptions;
|
380 | /**
|
381 | * @callback Crc32cGeneratorToStringCallback
|
382 | * A method returning the CRC32C as a base64-encoded string.
|
383 | *
|
384 | * @returns {string}
|
385 | *
|
386 | * @example
|
387 | * Hashing the string 'data' should return 'rth90Q=='
|
388 | *
|
389 | * ```js
|
390 | * const buffer = Buffer.from('data');
|
391 | * crc32c.update(buffer);
|
392 | * crc32c.toString(); // 'rth90Q=='
|
393 | * ```
|
394 | **/
|
395 | /**
|
396 | * @callback Crc32cGeneratorValidateCallback
|
397 | * A method validating a base64-encoded CRC32C string.
|
398 | *
|
399 | * @param {string} [value] base64-encoded CRC32C string to validate
|
400 | * @returns {boolean}
|
401 | *
|
402 | * @example
|
403 | * Should return `true` if the value matches, `false` otherwise
|
404 | *
|
405 | * ```js
|
406 | * const buffer = Buffer.from('data');
|
407 | * crc32c.update(buffer);
|
408 | * crc32c.validate('DkjKuA=='); // false
|
409 | * crc32c.validate('rth90Q=='); // true
|
410 | * ```
|
411 | **/
|
412 | /**
|
413 | * @callback Crc32cGeneratorUpdateCallback
|
414 | * A method for passing `Buffer`s for CRC32C generation.
|
415 | *
|
416 | * @param {Buffer} [data] data to update CRC32C value with
|
417 | * @returns {undefined}
|
418 | *
|
419 | * @example
|
420 | * Hashing buffers from 'some ' and 'text\n'
|
421 | *
|
422 | * ```js
|
423 | * const buffer1 = Buffer.from('some ');
|
424 | * crc32c.update(buffer1);
|
425 | *
|
426 | * const buffer2 = Buffer.from('text\n');
|
427 | * crc32c.update(buffer2);
|
428 | *
|
429 | * crc32c.toString(); // 'DkjKuA=='
|
430 | * ```
|
431 | **/
|
432 | /**
|
433 | * @typedef {object} CRC32CValidator
|
434 | * @property {Crc32cGeneratorToStringCallback}
|
435 | * @property {Crc32cGeneratorValidateCallback}
|
436 | * @property {Crc32cGeneratorUpdateCallback}
|
437 | */
|
438 | /**
|
439 | * @callback Crc32cGeneratorCallback
|
440 | * @returns {CRC32CValidator}
|
441 | */
|
442 | /**
|
443 | * @typedef {object} StorageOptions
|
444 | * @property {string} [projectId] The project ID from the Google Developer's
|
445 | * Console, e.g. 'grape-spaceship-123'. We will also check the environment
|
446 | * variable `GCLOUD_PROJECT` for your project ID. If your app is running
|
447 | * in an environment which supports {@link
|
448 | * https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application
|
449 | * Application Default Credentials}, your project ID will be detected
|
450 | * automatically.
|
451 | * @property {string} [keyFilename] Full path to the a .json, .pem, or .p12 key
|
452 | * downloaded from the Google Developers Console. If you provide a path to
|
453 | * a JSON file, the `projectId` option above is not necessary. NOTE: .pem and
|
454 | * .p12 require you to specify the `email` option as well.
|
455 | * @property {string} [email] Account email address. Required when using a .pem
|
456 | * or .p12 keyFilename.
|
457 | * @property {object} [credentials] Credentials object.
|
458 | * @property {string} [credentials.client_email]
|
459 | * @property {string} [credentials.private_key]
|
460 | * @property {object} [retryOptions] Options for customizing retries. Retriable server errors
|
461 | * will be retried with exponential delay between them dictated by the formula
|
462 | * max(maxRetryDelay, retryDelayMultiplier*retryNumber) until maxRetries or totalTimeout
|
463 | * has been reached. Retries will only happen if autoRetry is set to true.
|
464 | * @property {boolean} [retryOptions.autoRetry=true] Automatically retry requests if the
|
465 | * response is related to rate limits or certain intermittent server
|
466 | * errors. We will exponentially backoff subsequent requests by default.
|
467 | * @property {number} [retryOptions.retryDelayMultiplier = 2] the multiplier by which to
|
468 | * increase the delay time between the completion of failed requests, and the
|
469 | * initiation of the subsequent retrying request.
|
470 | * @property {number} [retryOptions.totalTimeout = 600] The total time, starting from
|
471 | * when the initial request is sent, after which an error will
|
472 | * be returned, regardless of the retrying attempts made meanwhile.
|
473 | * @property {number} [retryOptions.maxRetryDelay = 64] The maximum delay time between requests.
|
474 | * When this value is reached, ``retryDelayMultiplier`` will no longer be used to
|
475 | * increase delay time.
|
476 | * @property {number} [retryOptions.maxRetries=3] Maximum number of automatic retries
|
477 | * attempted before returning the error.
|
478 | * @property {function} [retryOptions.retryableErrorFn] Function that returns true if a given
|
479 | * error should be retried and false otherwise.
|
480 | * @property {enum} [retryOptions.idempotencyStrategy=IdempotencyStrategy.RetryConditional] Enumeration
|
481 | * controls how conditionally idempotent operations are retried. Possible values are: RetryAlways -
|
482 | * will respect other retry settings and attempt to retry conditionally idempotent operations. RetryConditional -
|
483 | * will retry conditionally idempotent operations if the correct preconditions are set. RetryNever - never
|
484 | * retry a conditionally idempotent operation.
|
485 | * @property {string} [userAgent] The value to be prepended to the User-Agent
|
486 | * header in API requests.
|
487 | * @property {object} [authClient] `AuthClient` or `GoogleAuth` client to reuse instead of creating a new one.
|
488 | * @property {number} [timeout] The amount of time in milliseconds to wait per http request before timing out.
|
489 | * @property {object[]} [interceptors_] Array of custom request interceptors to be returned in the order they were assigned.
|
490 | * @property {string} [apiEndpoint = storage.google.com] The API endpoint of the service used to make requests.
|
491 | * @property {boolean} [useAuthWithCustomEndpoint = false] Controls whether or not to use authentication when using a custom endpoint.
|
492 | * @property {Crc32cGeneratorCallback} [callback] A function that generates a CRC32C Validator. Defaults to {@link CRC32C}
|
493 | */
|
494 | /**
|
495 | * Constructs the Storage client.
|
496 | *
|
497 | * @example
|
498 | * Create a client that uses Application Default Credentials
|
499 | * (ADC)
|
500 | * ```
|
501 | * const {Storage} = require('@google-cloud/storage');
|
502 | * const storage = new Storage();
|
503 | * ```
|
504 | *
|
505 | * @example
|
506 | * Create a client with explicit credentials
|
507 | * ```
|
508 | * const storage = new Storage({
|
509 | * projectId: 'your-project-id',
|
510 | * keyFilename: '/path/to/keyfile.json'
|
511 | * });
|
512 | * ```
|
513 | *
|
514 | * @example
|
515 | * Create a client with credentials passed
|
516 | * by value as a JavaScript object
|
517 | * ```
|
518 | * const storage = new Storage({
|
519 | * projectId: 'your-project-id',
|
520 | * credentials: {
|
521 | * type: 'service_account',
|
522 | * project_id: 'xxxxxxx',
|
523 | * private_key_id: 'xxxx',
|
524 | * private_key:'-----BEGIN PRIVATE KEY-----xxxxxxx\n-----END PRIVATE KEY-----\n',
|
525 | * client_email: 'xxxx',
|
526 | * client_id: 'xxx',
|
527 | * auth_uri: 'https://accounts.google.com/o/oauth2/auth',
|
528 | * token_uri: 'https://oauth2.googleapis.com/token',
|
529 | * auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
|
530 | * client_x509_cert_url: 'xxx',
|
531 | * }
|
532 | * });
|
533 | * ```
|
534 | *
|
535 | * @example
|
536 | * Create a client with credentials passed
|
537 | * by loading a JSON file directly from disk
|
538 | * ```
|
539 | * const storage = new Storage({
|
540 | * projectId: 'your-project-id',
|
541 | * credentials: require('/path/to-keyfile.json')
|
542 | * });
|
543 | * ```
|
544 | *
|
545 | * @example
|
546 | * Create a client with an `AuthClient` (e.g. `DownscopedClient`)
|
547 | * ```
|
548 | * const {DownscopedClient} = require('google-auth-library');
|
549 | * const authClient = new DownscopedClient({...});
|
550 | *
|
551 | * const storage = new Storage({authClient});
|
552 | * ```
|
553 | *
|
554 | * Additional samples:
|
555 | * - https://github.com/googleapis/google-auth-library-nodejs#sample-usage-1
|
556 | * - https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/downscopedclient.js
|
557 | *
|
558 | * @param {StorageOptions} [options] Configuration options.
|
559 | */
|
560 | constructor(options?: StorageOptions);
|
561 | private static sanitizeEndpoint;
|
562 | /**
|
563 | * Get a reference to a Cloud Storage bucket.
|
564 | *
|
565 | * @param {string} name Name of the bucket.
|
566 | * {object} [options] Configuration object.
|
567 | * string} [options.kmsKeyName] A Cloud KMS key that will be used to
{ |
568 | * encrypt objects inserted into this bucket, if no encryption method is
|
569 | * specified.
|
570 | * string} [options.userProject] User project to be billed for all
{ |
571 | * requests made from this Bucket object.
|
572 | * {Bucket}
|
573 | * Bucket
|
574 | *
|
575 | *
|
576 | * ```
|
577 | * const {Storage} = require('@google-cloud/storage');
|
578 | * const storage = new Storage();
|
579 | * const albums = storage.bucket('albums');
|
580 | * const photos = storage.bucket('photos');
|
581 | * ```
|
582 | */
|
583 | bucket(name: string, options?: BucketOptions): Bucket;
|
584 | /**
|
585 | * Reference a channel to receive notifications about changes to your bucket.
|
586 | *
|
587 | * @param {string} id The ID of the channel.
|
588 | * @param {string} resourceId The resource ID of the channel.
|
589 | * @returns {Channel}
|
590 | * @see Channel
|
591 | *
|
592 | * @example
|
593 | * ```
|
594 | * const {Storage} = require('@google-cloud/storage');
|
595 | * const storage = new Storage();
|
596 | * const channel = storage.channel('id', 'resource-id');
|
597 | * ```
|
598 | */
|
599 | channel(id: string, resourceId: string): Channel;
|
600 | createBucket(name: string, metadata?: CreateBucketRequest): Promise<CreateBucketResponse>;
|
601 | createBucket(name: string, callback: BucketCallback): void;
|
602 | createBucket(name: string, metadata: CreateBucketRequest, callback: BucketCallback): void;
|
603 | createBucket(name: string, metadata: CreateBucketRequest, callback: BucketCallback): void;
|
604 | createHmacKey(serviceAccountEmail: string, options?: CreateHmacKeyOptions): Promise<CreateHmacKeyResponse>;
|
605 | createHmacKey(serviceAccountEmail: string, callback: CreateHmacKeyCallback): void;
|
606 | createHmacKey(serviceAccountEmail: string, options: CreateHmacKeyOptions, callback: CreateHmacKeyCallback): void;
|
607 | getBuckets(options?: GetBucketsRequest): Promise<GetBucketsResponse>;
|
608 | getBuckets(options: GetBucketsRequest, callback: GetBucketsCallback): void;
|
609 | getBuckets(callback: GetBucketsCallback): void;
|
610 | /**
|
611 | * Query object for listing HMAC keys.
|
612 | *
|
613 | * @typedef {object} GetHmacKeysOptions
|
614 | * @property {string} [projectId] The project ID of the project that owns
|
615 | * the service account of the requested HMAC key. If not provided,
|
616 | * the project ID used to instantiate the Storage client will be used.
|
617 | * @property {string} [serviceAccountEmail] If present, only HMAC keys for the
|
618 | * given service account are returned.
|
619 | * @property {boolean} [showDeletedKeys=false] If true, include keys in the DELETE
|
620 | * state. Default is false.
|
621 | * @property {boolean} [autoPaginate=true] Have pagination handled
|
622 | * automatically.
|
623 | * @property {number} [maxApiCalls] Maximum number of API calls to make.
|
624 | * @property {number} [maxResults] Maximum number of items plus prefixes to
|
625 | * return per call.
|
626 | * Note: By default will handle pagination automatically
|
627 | * if more than 1 page worth of results are requested per call.
|
628 | * When `autoPaginate` is set to `false` the smaller of `maxResults`
|
629 | * or 1 page of results will be returned per call.
|
630 | * @property {string} [pageToken] A previously-returned page token
|
631 | * representing part of the larger set of results to view.
|
632 | * @property {string} [userProject] This parameter is currently ignored.
|
633 | */
|
634 | /**
|
635 | * @typedef {array} GetHmacKeysResponse
|
636 | * @property {HmacKey[]} 0 Array of {@link HmacKey} instances.
|
637 | * @param {object} nextQuery 1 A query object to receive more results.
|
638 | * @param {object} apiResponse 2 The full API response.
|
639 | */
|
640 | /**
|
641 | * @callback GetHmacKeysCallback
|
642 | * @param {?Error} err Request error, if any.
|
643 | * @param {HmacKey[]} hmacKeys Array of {@link HmacKey} instances.
|
644 | * @param {object} nextQuery A query object to receive more results.
|
645 | * @param {object} apiResponse The full API response.
|
646 | */
|
647 | /**
|
648 | * Retrieves a list of HMAC keys matching the criteria.
|
649 | *
|
650 | * The authenticated user must have storage.hmacKeys.list permission for the project in which the key exists.
|
651 | *
|
652 | * @param {GetHmacKeysOption} options Configuration options.
|
653 | * @param {GetHmacKeysCallback} callback Callback function.
|
654 | * @return {Promise<GetHmacKeysResponse>}
|
655 | *
|
656 | * @example
|
657 | * ```
|
658 | * const {Storage} = require('@google-cloud/storage');
|
659 | * const storage = new Storage();
|
660 | * storage.getHmacKeys(function(err, hmacKeys) {
|
661 | * if (!err) {
|
662 | * // hmacKeys is an array of HmacKey objects.
|
663 | * }
|
664 | * });
|
665 | *
|
666 | * //-
|
667 | * // To control how many API requests are made and page through the results
|
668 | * // manually, set `autoPaginate` to `false`.
|
669 | * //-
|
670 | * const callback = function(err, hmacKeys, nextQuery, apiResponse) {
|
671 | * if (nextQuery) {
|
672 | * // More results exist.
|
673 | * storage.getHmacKeys(nextQuery, callback);
|
674 | * }
|
675 | *
|
676 | * // The `metadata` property is populated for you with the metadata at the
|
677 | * // time of fetching.
|
678 | * hmacKeys[0].metadata;
|
679 | * };
|
680 | *
|
681 | * storage.getHmacKeys({
|
682 | * autoPaginate: false
|
683 | * }, callback);
|
684 | *
|
685 | * //-
|
686 | * // If the callback is omitted, we'll return a Promise.
|
687 | * //-
|
688 | * storage.getHmacKeys().then(function(data) {
|
689 | * const hmacKeys = data[0];
|
690 | * });
|
691 | * ```
|
692 | */
|
693 | getHmacKeys(options?: GetHmacKeysOptions): Promise<GetHmacKeysResponse>;
|
694 | getHmacKeys(callback: GetHmacKeysCallback): void;
|
695 | getHmacKeys(options: GetHmacKeysOptions, callback: GetHmacKeysCallback): void;
|
696 | getServiceAccount(options?: GetServiceAccountOptions): Promise<GetServiceAccountResponse>;
|
697 | getServiceAccount(options?: GetServiceAccountOptions): Promise<GetServiceAccountResponse>;
|
698 | getServiceAccount(options: GetServiceAccountOptions, callback: GetServiceAccountCallback): void;
|
699 | getServiceAccount(callback: GetServiceAccountCallback): void;
|
700 | /**
|
701 | * Get a reference to an HmacKey object.
|
702 | * Note: this does not fetch the HMAC key's metadata. Use HmacKey#get() to
|
703 | * retrieve and populate the metadata.
|
704 | *
|
705 | * To get a reference to an HMAC key that's not created for a service
|
706 | * account in the same project used to instantiate the Storage client,
|
707 | * supply the project's ID as `projectId` in the `options` argument.
|
708 | *
|
709 | * @param {string} accessId The HMAC key's access ID.
|
710 | * @param {HmacKeyOptions} options HmacKey constructor options.
|
711 | * @returns {HmacKey}
|
712 | * @see HmacKey
|
713 | *
|
714 | * @example
|
715 | * ```
|
716 | * const {Storage} = require('@google-cloud/storage');
|
717 | * const storage = new Storage();
|
718 | * const hmacKey = storage.hmacKey('ACCESS_ID');
|
719 | * ```
|
720 | */
|
721 | hmacKey(accessId: string, options?: HmacKeyOptions): HmacKey;
|
722 | }
|
723 | export {};
|