legacy-libs/google-gax/build/src/operationsClient.js

   1 "use strict";
   2 /*
   3  * Copyright 2018 Google LLC. All rights reserved.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  * http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17 Object.defineProperty(exports, "__esModule", { value: true });
  18 const google_proto_files_1 = require("google-proto-files");
  19 const apiCallable = require("./apiCallable");
  20 const gax = require("./gax");
  21 const pagedIteration = require("./pagedIteration");
  22 const pathTemplate = require("./pathTemplate");
  23 const configData = require('./operations_client_config');
  24 Object.assign(gax, apiCallable);
  25 Object.assign(gax, pathTemplate);
  26 Object.assign(gax, pagedIteration);
  27 exports.SERVICE_ADDRESS = 'longrunning.googleapis.com';
  28 const DEFAULT_SERVICE_PORT = 443;
  29 const CODE_GEN_NAME_VERSION = 'gapic/0.7.1';
  30 const PAGE_DESCRIPTORS = {
  31     listOperations: new gax['PageDescriptor']('pageToken', 'nextPageToken', 'operations'),
  32 };
  33 /**
  34  * The scopes needed to make gRPC calls to all of the methods defined in
  35  * this service.
  36  */
  37 exports.ALL_SCOPES = [];
  38 /**
  39  * Manages long-running operations with an API service.
  40  *
  41  * When an API method normally takes long time to complete, it can be designed
  42  * to return {@link Operation} to the client, and the client can use this
  43  * interface to receive the real response asynchronously by polling the
  44  * operation resource, or pass the operation resource to another API (such as
  45  * Google Cloud Pub/Sub API) to receive the response.  Any API service that
  46  * returns long-running operations should implement the `Operations` interface
  47  * so developers can have a consistent client experience.
  48  *
  49  * This will be created through a builder function which can be obtained by the
  50  * module. See the following example of how to initialize the module and how to
  51  * access to the builder.
  52  * @see {@link operationsClient}
  53  *
  54  * @class
  55  */
  56 class OperationsClient {
  57     constructor(
  58     // tslint:disable-next-line no-any
  59     gaxGrpc, grpcClients, options) {
  60         const opts = Object.assign({
  61             servicePath: exports.SERVICE_ADDRESS,
  62             port: DEFAULT_SERVICE_PORT,
  63             clientConfig: {},
  64         }, options);
  65         const googleApiClient = ['gl-node/' + process.versions.node];
  66         if (opts.libName && opts.libVersion) {
  67             googleApiClient.push(opts.libName + '/' + opts.libVersion);
  68         }
  69         googleApiClient.push(CODE_GEN_NAME_VERSION, 'gax/' + gax['version'], 'grpc/' + gaxGrpc.grpcVersion);
  70         const defaults = gaxGrpc.constructSettings('google.longrunning.Operations', configData, opts.clientConfig, { 'x-goog-api-client': googleApiClient.join(' ') });
  71         this.auth = gaxGrpc.auth;
  72         const operationsStub = gaxGrpc.createStub(grpcClients.google.longrunning.Operations, opts);
  73         const operationsStubMethods = [
  74             'getOperation',
  75             'listOperations',
  76             'cancelOperation',
  77             'deleteOperation',
  78         ];
  79         operationsStubMethods.forEach(methodName => {
  80             this['_' + methodName] = gax['createApiCall'](operationsStub.then(operationsStub => {
  81                 return (...args) => {
  82                     return operationsStub[methodName].apply(operationsStub, args);
  83                 };
  84             }), defaults[methodName], PAGE_DESCRIPTORS[methodName]);
  85         });
  86     }
  87     getProjectId(callback) {
  88         return this.auth.getProjectId(callback);
  89     }
  90     // Service calls
  91     /**
  92      * Gets the latest state of a long-running operation.  Clients can use this
  93      * method to poll the operation result at intervals as recommended by the API
  94      * service.
  95      *
  96      * @param {Object} request - The request object that will be sent.
  97      * @param {string} request.name - The name of the operation resource.
  98      * @param {Object=} options
  99      *   Optional parameters. You can override the default settings for this call,
 100      *   e.g, timeout, retries, paginations, etc. See [gax.CallOptions]{@link
 101      *   https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the
 102      *   details.
 103      * @param {function(?Error, ?Object)=} callback
 104      *   The function which will be called with the result of the API call.
 105      *
 106      *   The second parameter to the callback is an object representing
 107      * [google.longrunning.Operation]{@link
 108      * external:"google.longrunning.Operation"}.
 109      * @return {Promise} - The promise which resolves to an array.
 110      *   The first element of the array is an object representing
 111      * [google.longrunning.Operation]{@link
 112      * external:"google.longrunning.Operation"}. The promise has a method named
 113      * "cancel" which cancels the ongoing API call.
 114      *
 115      * @example
 116      *
 117      * const client = longrunning.operationsClient();
 118      * const name = '';
 119      * const [response] = await client.getOperation({name});
 120      * // doThingsWith(response)
 121      */
 122     getOperation(request, options, callback) {
 123         if (options instanceof Function && callback === undefined) {
 124             callback = options;
 125             options = {};
 126         }
 127         options = options || {};
 128         return this._getOperation(request, options, callback);
 129     }
 130     /**
 131      * Lists operations that match the specified filter in the request. If the
 132      * server doesn't support this method, it returns `UNIMPLEMENTED`.
 133      *
 134      * NOTE: the `name` binding below allows API services to override the binding
 135      * to use different resource name schemes.
 136      *
 137      * @param {Object} request - The request object that will be sent.
 138      * @param {string} request.name - The name of the operation collection.
 139      * @param {string} request.filter - The standard list filter.
 140      * @param {number=} request.pageSize
 141      *   The maximum number of resources contained in the underlying API
 142      *   response. If page streaming is performed per-resource, this
 143      *   parameter does not affect the return value. If page streaming is
 144      *   performed per-page, this determines the maximum number of
 145      *   resources in a page.
 146      * @param {Object=} options
 147      *   Optional parameters. You can override the default settings for this call,
 148      * e.g, timeout, retries, paginations, etc. See [gax.CallOptions]{@link
 149      * https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the
 150      * details.
 151      * @param {function(?Error, ?Array, ?Object, ?Object)=} callback
 152      *   The function which will be called with the result of the API call.
 153      *
 154      *   The second parameter to the callback is Array of
 155      * [google.longrunning.Operation]{@link
 156      * external:"google.longrunning.Operation"}.
 157      *
 158      *   When autoPaginate: false is specified through options, it contains the
 159      * result in a single response. If the response indicates the next page
 160      * exists, the third parameter is set to be used for the next request object.
 161      * The fourth parameter keeps the raw response object of an object
 162      * representing [google.longrunning.ListOperationsResponse]{@link
 163      * external:"google.longrunning.ListOperationsResponse"}.
 164      * @return {Promise} - The promise which resolves to an array.
 165      *   The first element of the array is Array of
 166      * [google.longrunning.Operation]{@link
 167      * external:"google.longrunning.Operation"}.
 168      *
 169      *   When autoPaginate: false is specified through options, the array has
 170      * three elements. The first element is Array of
 171      * [google.longrunning.Operation]{@link
 172      * external:"google.longrunning.Operation"} in a single response. The second
 173      * element is the next request object if the response indicates the next page
 174      * exists, or null. The third element is an object representing
 175      * [google.longrunning.ListOperationsResponse]{@link
 176      * external:"google.longrunning.ListOperationsResponse"}.
 177      *
 178      *   The promise has a method named "cancel" which cancels the ongoing API
 179      * call.
 180      *
 181      * @example
 182      *
 183      * const client = longrunning.operationsClient();
 184      * const request = {
 185      *     name: '',
 186      *     filter: ''
 187      * };
 188      * // Iterate over all elements.
 189      * const [resources] = await client.listOperations(request);
 190      * for (const resource of resources) {
 191      *   console.log(resources);
 192      * }
 193      *
 194      * // Or obtain the paged response.
 195      * const options = {autoPaginate: false};
 196      * let nextRequest = request;
 197      * while(nextRequest) {
 198      *   const response = await client.listOperations(nextRequest, options);
 199      *   const resources = response[0];
 200      *   nextRequest = response[1];
 201      *   const rawResponse = response[2];
 202      *   for (const resource of resources) {
 203      *     // doThingsWith(resource);
 204      *   }
 205      * };
 206      */
 207     listOperations(request, options, callback) {
 208         if (options instanceof Function && callback === undefined) {
 209             callback = options;
 210             options = {};
 211         }
 212         options = options || {};
 213         return this['_listOperations'](request, options, callback);
 214     }
 215     /**
 216      * Equivalent to {@link listOperations}, but returns a NodeJS Stream object.
 217      *
 218      * This fetches the paged responses for {@link listOperations} continuously
 219      * and invokes the callback registered for 'data' event for each element in
 220      * the responses.
 221      *
 222      * The returned object has 'end' method when no more elements are required.
 223      *
 224      * autoPaginate option will be ignored.
 225      *
 226      * @see {@link https://nodejs.org/api/stream.html}
 227      *
 228      * @param {Object} request - The request object that will be sent.
 229      * @param {string} request.name - The name of the operation collection.
 230      * @param {string} request.filter - The standard list filter.
 231      * @param {number=} request.pageSize -
 232      *   The maximum number of resources contained in the underlying API
 233      *   response. If page streaming is performed per-resource, this
 234      *   parameter does not affect the return value. If page streaming is
 235      *   performed per-page, this determines the maximum number of
 236      *   resources in a page.
 237      * @param {Object=} options
 238      *   Optional parameters. You can override the default settings for this call,
 239      *   e.g, timeout, retries, paginations, etc. See [gax.CallOptions]{@link
 240      *   https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the
 241      *   details.
 242      * @return {Stream} - An object stream which emits an object representing [google.longrunning.Operation]{@link external:"google.longrunning.Operation"} on 'data' event.
 243      *
 244      * @example
 245      *
 246      * const client = longrunning.operationsClient();
 247      * const request = {
 248      *   name: '',
 249      *   filter: ''
 250      * };
 251      * client.listOperationsStream(request)
 252      *   .on('data', element => {
 253      *     // doThingsWith(element)
 254      *   })
 255      *   .on('error', err => {
 256      *     console.error(err);
 257      *   });
 258      */
 259     listOperationsStream(request, options = {}) {
 260         return PAGE_DESCRIPTORS.listOperations.createStream(this._listOperations, request, options);
 261     }
 262     /**
 263      * Starts asynchronous cancellation on a long-running operation.  The server
 264      * makes a best effort to cancel the operation, but success is not
 265      * guaranteed.  If the server doesn't support this method, it returns
 266      * `google.rpc.Code.UNIMPLEMENTED`.  Clients can use
 267      * {@link Operations.GetOperation} or
 268      * other methods to check whether the cancellation succeeded or whether the
 269      * operation completed despite cancellation. On successful cancellation,
 270      * the operation is not deleted; instead, it becomes an operation with
 271      * an {@link Operation.error} value with a {@link google.rpc.Status.code} of
 272      * 1, corresponding to `Code.CANCELLED`.
 273      *
 274      * @param {Object} request - The request object that will be sent.
 275      * @param {string} request.name - The name of the operation resource to be cancelled.
 276      * @param {Object=} options
 277      *   Optional parameters. You can override the default settings for this call,
 278      * e.g, timeout, retries, paginations, etc. See [gax.CallOptions]{@link
 279      * https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the
 280      * details.
 281      * @param {function(?Error)=} callback
 282      *   The function which will be called with the result of the API call.
 283      * @return {Promise} - The promise which resolves when API call finishes.
 284      *   The promise has a method named "cancel" which cancels the ongoing API
 285      * call.
 286      *
 287      * @example
 288      *
 289      * const client = longrunning.operationsClient();
 290      * await client.cancelOperation({name: ''});
 291      */
 292     cancelOperation(request, options, callback) {
 293         if (options instanceof Function && callback === undefined) {
 294             callback = options;
 295             options = {};
 296         }
 297         options = options || {};
 298         return this._cancelOperation(request, options, callback);
 299     }
 300     /**
 301      * Deletes a long-running operation. This method indicates that the client is
 302      * no longer interested in the operation result. It does not cancel the
 303      * operation. If the server doesn't support this method, it returns
 304      * `google.rpc.Code.UNIMPLEMENTED`.
 305      *
 306      * @param {Object} request - The request object that will be sent.
 307      * @param {string} request.name - The name of the operation resource to be deleted.
 308      * @param {Object=} options
 309      *   Optional parameters. You can override the default settings for this call,
 310      * e.g, timeout, retries, paginations, etc. See [gax.CallOptions]{@link
 311      * https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the
 312      * details.
 313      * @param {function(?Error)=} callback
 314      *   The function which will be called with the result of the API call.
 315      * @return {Promise} - The promise which resolves when API call finishes.
 316      *   The promise has a method named "cancel" which cancels the ongoing API
 317      * call.
 318      *
 319      * @example
 320      *
 321      * const client = longrunning.operationsClient();
 322      * await client.deleteOperation({name: ''});
 323      */
 324     deleteOperation(request, options, callback) {
 325         if (options instanceof Function && callback === undefined) {
 326             callback = options;
 327             options = {};
 328         }
 329         options = options || {};
 330         return this._deleteOperation(request, options, callback);
 331     }
 332 }
 333 exports.OperationsClient = OperationsClient;
 334 class OperationsClientBuilder {
 335     /**
 336      * Builds a new Operations Client
 337      * @param gaxGrpc {GrpcClient}
 338      */
 339     constructor(gaxGrpc) {
 340         const protoFilesRoot = google_proto_files_1.getProtoPath('..');
 341         // tslint:disable-next-line no-any
 342         const operationsClient = gaxGrpc.loadProto(protoFilesRoot, 'google/longrunning/operations.proto');
 343         Object.assign(this, operationsClient.google.longrunning);
 344         /**
 345          * Build a new instance of {@link OperationsClient}.
 346          *
 347          * @param {Object=} opts - The optional parameters.
 348          * @param {String=} opts.servicePath - Domain name of the API remote host.
 349          * @param {number=} opts.port - The port on which to connect to the remote host.
 350          * @param {grpc.ClientCredentials=} opts.sslCreds - A ClientCredentials for use with an SSL-enabled channel.
 351          * @param {Object=} opts.clientConfig - The customized config to build the call settings. See {@link gax.constructSettings} for the format.
 352          */
 353         this.operationsClient = opts => {
 354             return new OperationsClient(gaxGrpc, operationsClient, opts);
 355         };
 356         Object.assign(this.operationsClient, OperationsClient);
 357     }
 358 }
 359 exports.OperationsClientBuilder = OperationsClientBuilder;
 360 //# sourceMappingURL=operationsClient.js.map