import type * as gax from 'google-gax'; import type { Callback, CallOptions, Descriptors, ClientOptions, PaginationCallback } from 'google-gax'; import { Transform } from 'stream'; import * as protos from '../../protos/protos'; /** * ## API Overview and Naming Syntax * * The Cloud Storage gRPC API allows applications to read and write data through * the abstractions of buckets and objects. For a description of these * abstractions please see [Cloud Storage * documentation](https://cloud.google.com/storage/docs). * * Resources are named as follows: * * - Projects are referred to as they are defined by the Resource Manager API, * using strings like `projects/123456` or `projects/my-string-id`. * - Buckets are named using string names of the form: * `projects/{project}/buckets/{bucket}`. * For globally unique buckets, `_` might be substituted for the project. * - Objects are uniquely identified by their name along with the name of the * bucket they belong to, as separate strings in this API. For example: * * ``` * ReadObjectRequest { * bucket: 'projects/_/buckets/my-bucket' * object: 'my-object' * } * ``` * * Note that object names can contain `/` characters, which are treated as * any other character (no special directory semantics). * @class * @memberof v2 * @internal */ export declare class StorageClient { private _terminated; private _opts; private _providedCustomServicePath; private _gaxModule; private _gaxGrpc; private _protos; private _defaults; private _universeDomain; private _servicePath; private _log; auth: gax.GoogleAuth; descriptors: Descriptors; warn: (code: string, message: string, warnType?: string) => void; innerApiCalls: { [name: string]: Function; }; pathTemplates: { [name: string]: gax.PathTemplate; }; storageStub?: Promise<{ [name: string]: Function; }>; /** * Construct an instance of StorageClient. * * @param {object} [options] - The configuration object. * The options accepted by the constructor are described in detail * in [this document](https://github.com/googleapis/gax-nodejs/blob/main/client-libraries.md#creating-the-client-instance). * The common options are: * @param {object} [options.credentials] - Credentials object. * @param {string} [options.credentials.client_email] * @param {string} [options.credentials.private_key] * @param {string} [options.email] - Account email address. Required when * using a .pem or .p12 keyFilename. * @param {string} [options.keyFilename] - Full path to the a .json, .pem, or * .p12 key downloaded from the Google Developers Console. If you provide * a path to a JSON file, the projectId option below is not necessary. * NOTE: .pem and .p12 require you to specify options.email as well. * @param {number} [options.port] - The port on which to connect to * the remote host. * @param {string} [options.projectId] - The project ID from the Google * Developer's Console, e.g. 'grape-spaceship-123'. We will also check * the environment variable GCLOUD_PROJECT for your project ID. If your * app is running in an environment which supports * {@link https://cloud.google.com/docs/authentication/application-default-credentials Application Default Credentials}, * your project ID will be detected automatically. * @param {string} [options.apiEndpoint] - The domain name of the * API remote host. * @param {gax.ClientConfig} [options.clientConfig] - Client configuration override. * Follows the structure of {@link gapicConfig}. * @param {boolean} [options.fallback] - Use HTTP/1.1 REST mode. * For more information, please check the * {@link https://github.com/googleapis/gax-nodejs/blob/main/client-libraries.md#http11-rest-api-mode documentation}. * @param {gax} [gaxInstance]: loaded instance of `google-gax`. Useful if you * need to avoid loading the default gRPC version and want to use the fallback * HTTP implementation. Load only fallback version and pass it to the constructor: * ``` * const gax = require('google-gax/build/src/fallback'); // avoids loading google-gax with gRPC * const client = new StorageClient({fallback: true}, gax); * ``` */ constructor(opts?: ClientOptions, gaxInstance?: typeof gax | typeof gax.fallback); /** * Initialize the client. * Performs asynchronous operations (such as authentication) and prepares the client. * This function will be called automatically when any class method is called for the * first time, but if you need to initialize it before calling an actual method, * feel free to call initialize() directly. * * You can await on this method if you want to make sure the client is initialized. * * @returns {Promise} A promise that resolves to an authenticated service stub. */ initialize(): Promise<{ [name: string]: Function; }>; /** * The DNS address for this API service. * @deprecated Use the apiEndpoint method of the client instance. * @returns {string} The DNS address for this service. */ static get servicePath(): string; /** * The DNS address for this API service - same as servicePath. * @deprecated Use the apiEndpoint method of the client instance. * @returns {string} The DNS address for this service. */ static get apiEndpoint(): string; /** * The DNS address for this API service. * @returns {string} The DNS address for this service. */ get apiEndpoint(): string; get universeDomain(): string; /** * The port for this API service. * @returns {number} The default port for this service. */ static get port(): number; /** * The scopes needed to make gRPC calls for every method defined * in this service. * @returns {string[]} List of default scopes. */ static get scopes(): string[]; getProjectId(): Promise; getProjectId(callback: Callback): void; /** * Permanently deletes an empty bucket. * The request fails if there are any live or * noncurrent objects in the bucket, but the request succeeds if the * bucket only contains soft-deleted objects or incomplete uploads, such * as ongoing XML API multipart uploads. Does not permanently delete * soft-deleted objects. * * When this API is used to delete a bucket containing an object that has a * soft delete policy * enabled, the object becomes soft deleted, and the * `softDeleteTime` and `hardDeleteTime` properties are set on the * object. * * Objects and multipart uploads that were in the bucket at the time of * deletion are also retained for the specified retention duration. When * a soft-deleted bucket reaches the end of its retention duration, it * is permanently deleted. The `hardDeleteTime` of the bucket always * equals * or exceeds the expiration time of the last soft-deleted object in the * bucket. * * **IAM Permissions**: * * Requires `storage.buckets.delete` IAM permission on the bucket. * * @param {Object} request * The request object that will be sent. * @param {string} request.name * Required. Name of a bucket to delete. * @param {number} request.ifMetagenerationMatch * If set, only deletes the bucket if its metageneration matches this value. * @param {number} request.ifMetagenerationNotMatch * If set, only deletes the bucket if its metageneration does not match this * value. * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing {@link protos.google.protobuf.Empty|Empty}. * Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods | documentation } * for more details and examples. * @example include:samples/generated/v2/storage.delete_bucket.js * region_tag:storage_v2_generated_Storage_DeleteBucket_async */ deleteBucket(request?: protos.google.storage.v2.IDeleteBucketRequest, options?: CallOptions): Promise<[ protos.google.protobuf.IEmpty, protos.google.storage.v2.IDeleteBucketRequest | undefined, {} | undefined ]>; deleteBucket(request: protos.google.storage.v2.IDeleteBucketRequest, options: CallOptions, callback: Callback): void; deleteBucket(request: protos.google.storage.v2.IDeleteBucketRequest, callback: Callback): void; /** * Returns metadata for the specified bucket. * * **IAM Permissions**: * * Requires `storage.buckets.get` * IAM permission on * the bucket. Additionally, to return specific bucket metadata, the * authenticated user must have the following permissions: * * - To return the IAM policies: `storage.buckets.getIamPolicy` * - To return the bucket IP filtering rules: `storage.buckets.getIpFilter` * * @param {Object} request * The request object that will be sent. * @param {string} request.name * Required. Name of a bucket. * @param {number} request.ifMetagenerationMatch * If set, only gets the bucket metadata if its metageneration matches this * value. * @param {number} request.ifMetagenerationNotMatch * If set, and if the bucket's current metageneration matches the specified * value, the request returns an error. * @param {google.protobuf.FieldMask} request.readMask * Mask specifying which fields to read. * A `*` field might be used to indicate all fields. * If no mask is specified, it defaults to all fields. * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing {@link protos.google.storage.v2.Bucket|Bucket}. * Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods | documentation } * for more details and examples. * @example include:samples/generated/v2/storage.get_bucket.js * region_tag:storage_v2_generated_Storage_GetBucket_async */ getBucket(request?: protos.google.storage.v2.IGetBucketRequest, options?: CallOptions): Promise<[ protos.google.storage.v2.IBucket, protos.google.storage.v2.IGetBucketRequest | undefined, {} | undefined ]>; getBucket(request: protos.google.storage.v2.IGetBucketRequest, options: CallOptions, callback: Callback): void; getBucket(request: protos.google.storage.v2.IGetBucketRequest, callback: Callback): void; /** * Creates a new bucket. * * **IAM Permissions**: * * Requires `storage.buckets.create` IAM permission on the bucket. * Additionally, to enable specific bucket features, the authenticated user * must have the following permissions: * * - To enable object retention using the `enableObjectRetention` query * parameter: `storage.buckets.enableObjectRetention` * - To set the bucket IP filtering rules: `storage.buckets.setIpFilter` * * @param {Object} request * The request object that will be sent. * @param {string} request.parent * Required. The project to which this bucket belongs. This field must either * be empty or `projects/_`. The project ID that owns this bucket should be * specified in the `bucket.project` field. * @param {google.storage.v2.Bucket} [request.bucket] * Optional. Properties of the new bucket being inserted. * The name of the bucket is specified in the `bucket_id` field. Populating * `bucket.name` field results in an error. * The project of the bucket must be specified in the `bucket.project` field. * This field must be in `projects/{projectIdentifier}` format, * {projectIdentifier} can be the project ID or project number. The `parent` * field must be either empty or `projects/_`. * @param {string} request.bucketId * Required. The ID to use for this bucket, which becomes the final component * of the bucket's resource name. For example, the value `foo` might result in * a bucket with the name `projects/123456/buckets/foo`. * @param {string} [request.predefinedAcl] * Optional. Apply a predefined set of access controls to this bucket. * Valid values are `authenticatedRead`, `private`, `projectPrivate`, * `publicRead`, or `publicReadWrite`. * @param {string} [request.predefinedDefaultObjectAcl] * Optional. Apply a predefined set of default object access controls to this * bucket. Valid values are `authenticatedRead`, `bucketOwnerFullControl`, * `bucketOwnerRead`, `private`, `projectPrivate`, or `publicRead`. * @param {boolean} [request.enableObjectRetention] * Optional. If true, enable object retention on the bucket. * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing {@link protos.google.storage.v2.Bucket|Bucket}. * Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods | documentation } * for more details and examples. * @example include:samples/generated/v2/storage.create_bucket.js * region_tag:storage_v2_generated_Storage_CreateBucket_async */ createBucket(request?: protos.google.storage.v2.ICreateBucketRequest, options?: CallOptions): Promise<[ protos.google.storage.v2.IBucket, protos.google.storage.v2.ICreateBucketRequest | undefined, {} | undefined ]>; createBucket(request: protos.google.storage.v2.ICreateBucketRequest, options: CallOptions, callback: Callback): void; createBucket(request: protos.google.storage.v2.ICreateBucketRequest, callback: Callback): void; /** * Permanently locks the retention * policy that is * currently applied to the specified bucket. * * Caution: Locking a bucket is an * irreversible action. Once you lock a bucket: * * - You cannot remove the retention policy from the bucket. * - You cannot decrease the retention period for the policy. * * Once locked, you must delete the entire bucket in order to remove the * bucket's retention policy. However, before you can delete the bucket, you * must delete all the objects in the bucket, which is only * possible if all the objects have reached the retention period set by the * retention policy. * * **IAM Permissions**: * * Requires `storage.buckets.update` IAM permission on the bucket. * * @param {Object} request * The request object that will be sent. * @param {string} request.bucket * Required. Name of a bucket. * @param {number} request.ifMetagenerationMatch * Required. Makes the operation conditional on whether bucket's current * metageneration matches the given value. Must be positive. * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing {@link protos.google.storage.v2.Bucket|Bucket}. * Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods | documentation } * for more details and examples. * @example include:samples/generated/v2/storage.lock_bucket_retention_policy.js * region_tag:storage_v2_generated_Storage_LockBucketRetentionPolicy_async */ lockBucketRetentionPolicy(request?: protos.google.storage.v2.ILockBucketRetentionPolicyRequest, options?: CallOptions): Promise<[ protos.google.storage.v2.IBucket, protos.google.storage.v2.ILockBucketRetentionPolicyRequest | undefined, {} | undefined ]>; lockBucketRetentionPolicy(request: protos.google.storage.v2.ILockBucketRetentionPolicyRequest, options: CallOptions, callback: Callback): void; lockBucketRetentionPolicy(request: protos.google.storage.v2.ILockBucketRetentionPolicyRequest, callback: Callback): void; /** * Updates a bucket. Changes to the bucket are readable immediately after * writing, but configuration changes might take time to propagate. This * method supports `patch` semantics. * * **IAM Permissions**: * * Requires `storage.buckets.update` IAM permission on the bucket. * Additionally, to enable specific bucket features, the authenticated user * must have the following permissions: * * - To set bucket IP filtering rules: `storage.buckets.setIpFilter` * - To update public access prevention policies or access control lists * (ACLs): `storage.buckets.setIamPolicy` * * @param {Object} request * The request object that will be sent. * @param {google.storage.v2.Bucket} request.bucket * Required. The bucket to update. * The bucket's `name` field is used to identify the bucket. * @param {number} request.ifMetagenerationMatch * If set, the request modifies the bucket if its metageneration matches this * value. * @param {number} request.ifMetagenerationNotMatch * If set, the request modifies the bucket if its metageneration doesn't * match this value. * @param {string} [request.predefinedAcl] * Optional. Apply a predefined set of access controls to this bucket. * Valid values are `authenticatedRead`, `private`, `projectPrivate`, * `publicRead`, or `publicReadWrite`. * @param {string} [request.predefinedDefaultObjectAcl] * Optional. Apply a predefined set of default object access controls to this * bucket. Valid values are `authenticatedRead`, `bucketOwnerFullControl`, * `bucketOwnerRead`, `private`, `projectPrivate`, or `publicRead`. * @param {google.protobuf.FieldMask} request.updateMask * Required. List of fields to be updated. * * To specify ALL fields, equivalent to the JSON API's "update" function, * specify a single field with the value `*`. Note: not recommended. If a new * field is introduced at a later time, an older client updating with the `*` * might accidentally reset the new field's value. * * Not specifying any fields is an error. * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing {@link protos.google.storage.v2.Bucket|Bucket}. * Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods | documentation } * for more details and examples. * @example include:samples/generated/v2/storage.update_bucket.js * region_tag:storage_v2_generated_Storage_UpdateBucket_async */ updateBucket(request?: protos.google.storage.v2.IUpdateBucketRequest, options?: CallOptions): Promise<[ protos.google.storage.v2.IBucket, protos.google.storage.v2.IUpdateBucketRequest | undefined, {} | undefined ]>; updateBucket(request: protos.google.storage.v2.IUpdateBucketRequest, options: CallOptions, callback: Callback): void; updateBucket(request: protos.google.storage.v2.IUpdateBucketRequest, callback: Callback): void; /** * Retrieves a list of buckets for a given project, ordered * lexicographically by name. * * **IAM Permissions**: * * Requires `storage.buckets.list` IAM permission on the bucket. * Additionally, to enable specific bucket features, the authenticated * user must have the following permissions: * * - To list the IAM policies: `storage.buckets.getIamPolicy` * - To list the bucket IP filtering rules: `storage.buckets.getIpFilter` * * @param {Object} request * The request object that will be sent. * @param {string} request.parent * Required. The project whose buckets we are listing. * @param {number} [request.pageSize] * Optional. Maximum number of buckets to return in a single response. The * service uses this parameter or `1,000` items, whichever is smaller. If * `acl` is present in the `read_mask`, the service uses this parameter of * `200` items, whichever is smaller. * @param {string} [request.pageToken] * Optional. A previously-returned page token representing part of the larger * set of results to view. * @param {string} [request.prefix] * Optional. Filter results to buckets whose names begin with this prefix. * @param {google.protobuf.FieldMask} request.readMask * Mask specifying which fields to read from each result. * If no mask is specified, it defaults to all fields except `items. * owner`, `items.acl`, and `items.default_object_acl`. * `*` might be used to mean "all fields". * @param {boolean} [request.returnPartialSuccess] * Optional. Allows listing of buckets, even if there are buckets that are * unreachable. * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is Array of {@link protos.google.storage.v2.Bucket|Bucket}. * The client library will perform auto-pagination by default: it will call the API as many * times as needed and will merge results from all the pages into this array. * Note that it can affect your quota. * We recommend using `listBucketsAsync()` * method described below for async iteration which you can stop as needed. * Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination | documentation } * for more details and examples. */ listBuckets(request?: protos.google.storage.v2.IListBucketsRequest, options?: CallOptions): Promise<[ protos.google.storage.v2.IBucket[], protos.google.storage.v2.IListBucketsRequest | null, protos.google.storage.v2.IListBucketsResponse ]>; listBuckets(request: protos.google.storage.v2.IListBucketsRequest, options: CallOptions, callback: PaginationCallback): void; listBuckets(request: protos.google.storage.v2.IListBucketsRequest, callback: PaginationCallback): void; /** * Equivalent to `listBuckets`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.parent * Required. The project whose buckets we are listing. * @param {number} [request.pageSize] * Optional. Maximum number of buckets to return in a single response. The * service uses this parameter or `1,000` items, whichever is smaller. If * `acl` is present in the `read_mask`, the service uses this parameter of * `200` items, whichever is smaller. * @param {string} [request.pageToken] * Optional. A previously-returned page token representing part of the larger * set of results to view. * @param {string} [request.prefix] * Optional. Filter results to buckets whose names begin with this prefix. * @param {google.protobuf.FieldMask} request.readMask * Mask specifying which fields to read from each result. * If no mask is specified, it defaults to all fields except `items. * owner`, `items.acl`, and `items.default_object_acl`. * `*` might be used to mean "all fields". * @param {boolean} [request.returnPartialSuccess] * Optional. Allows listing of buckets, even if there are buckets that are * unreachable. * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Stream} * An object stream which emits an object representing {@link protos.google.storage.v2.Bucket|Bucket} on 'data' event. * The client library will perform auto-pagination by default: it will call the API as many * times as needed. Note that it can affect your quota. * We recommend using `listBucketsAsync()` * method described below for async iteration which you can stop as needed. * Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination | documentation } * for more details and examples. */ listBucketsStream(request?: protos.google.storage.v2.IListBucketsRequest, options?: CallOptions): Transform; /** * Equivalent to `listBuckets`, but returns an iterable object. * * `for`-`await`-`of` syntax is used with the iterable to get response elements on-demand. * @param {Object} request * The request object that will be sent. * @param {string} request.parent * Required. The project whose buckets we are listing. * @param {number} [request.pageSize] * Optional. Maximum number of buckets to return in a single response. The * service uses this parameter or `1,000` items, whichever is smaller. If * `acl` is present in the `read_mask`, the service uses this parameter of * `200` items, whichever is smaller. * @param {string} [request.pageToken] * Optional. A previously-returned page token representing part of the larger * set of results to view. * @param {string} [request.prefix] * Optional. Filter results to buckets whose names begin with this prefix. * @param {google.protobuf.FieldMask} request.readMask * Mask specifying which fields to read from each result. * If no mask is specified, it defaults to all fields except `items. * owner`, `items.acl`, and `items.default_object_acl`. * `*` might be used to mean "all fields". * @param {boolean} [request.returnPartialSuccess] * Optional. Allows listing of buckets, even if there are buckets that are * unreachable. * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Object} * An iterable Object that allows {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols | async iteration }. * When you iterate the returned iterable, each element will be an object representing * {@link protos.google.storage.v2.Bucket|Bucket}. The API will be called under the hood as needed, once per the page, * so you can stop the iteration when you don't need more results. * Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination | documentation } * for more details and examples. * @example include:samples/generated/v2/storage.list_buckets.js * region_tag:storage_v2_generated_Storage_ListBuckets_async */ listBucketsAsync(request?: protos.google.storage.v2.IListBucketsRequest, options?: CallOptions): AsyncIterable; /** * Return a fully-qualified bucket resource name string. * * @param {string} project * @param {string} bucket * @returns {string} Resource name string. */ bucketPath(project: string, bucket: string): string; /** * Parse the project from Bucket resource. * * @param {string} bucketName * A fully-qualified path representing Bucket resource. * @returns {string} A string representing the project. */ matchProjectFromBucketName(bucketName: string): string | number; /** * Parse the bucket from Bucket resource. * * @param {string} bucketName * A fully-qualified path representing Bucket resource. * @returns {string} A string representing the bucket. */ matchBucketFromBucketName(bucketName: string): string | number; /** * Return a fully-qualified cryptoKey resource name string. * * @param {string} project * @param {string} location * @param {string} key_ring * @param {string} crypto_key * @returns {string} Resource name string. */ cryptoKeyPath(project: string, location: string, keyRing: string, cryptoKey: string): string; /** * Parse the project from CryptoKey resource. * * @param {string} cryptoKeyName * A fully-qualified path representing CryptoKey resource. * @returns {string} A string representing the project. */ matchProjectFromCryptoKeyName(cryptoKeyName: string): string | number; /** * Parse the location from CryptoKey resource. * * @param {string} cryptoKeyName * A fully-qualified path representing CryptoKey resource. * @returns {string} A string representing the location. */ matchLocationFromCryptoKeyName(cryptoKeyName: string): string | number; /** * Parse the key_ring from CryptoKey resource. * * @param {string} cryptoKeyName * A fully-qualified path representing CryptoKey resource. * @returns {string} A string representing the key_ring. */ matchKeyRingFromCryptoKeyName(cryptoKeyName: string): string | number; /** * Parse the crypto_key from CryptoKey resource. * * @param {string} cryptoKeyName * A fully-qualified path representing CryptoKey resource. * @returns {string} A string representing the crypto_key. */ matchCryptoKeyFromCryptoKeyName(cryptoKeyName: string): string | number; /** * Return a fully-qualified project resource name string. * * @param {string} project * @returns {string} Resource name string. */ projectPath(project: string): string; /** * Parse the project from Project resource. * * @param {string} projectName * A fully-qualified path representing Project resource. * @returns {string} A string representing the project. */ matchProjectFromProjectName(projectName: string): string | number; /** * Terminate the gRPC channel and close the client. * * The client will no longer be usable and all future behavior is undefined. * @returns {Promise} A promise that resolves when the client is closed. */ close(): Promise; }