diff --git a/packages/google-cloud-monitoring/package.json b/packages/google-cloud-monitoring/package.json index 2e66dd92385..1b80a1eaf71 100644 --- a/packages/google-cloud-monitoring/package.json +++ b/packages/google-cloud-monitoring/package.json @@ -45,7 +45,7 @@ "api-documenter": "api-documenter yaml --input-folder=temp" }, "dependencies": { - "google-gax": "^2.1.0" + "google-gax": "^2.9.2" }, "devDependencies": { "@types/mocha": "^8.0.0", diff --git a/packages/google-cloud-monitoring/src/index.ts b/packages/google-cloud-monitoring/src/index.ts index 8ed785d32a8..2b0f78d83ad 100644 --- a/packages/google-cloud-monitoring/src/index.ts +++ b/packages/google-cloud-monitoring/src/index.ts @@ -19,11 +19,17 @@ import * as v3 from './v3'; const AlertPolicyServiceClient = v3.AlertPolicyServiceClient; +type AlertPolicyServiceClient = v3.AlertPolicyServiceClient; const GroupServiceClient = v3.GroupServiceClient; +type GroupServiceClient = v3.GroupServiceClient; const MetricServiceClient = v3.MetricServiceClient; +type MetricServiceClient = v3.MetricServiceClient; const NotificationChannelServiceClient = v3.NotificationChannelServiceClient; +type NotificationChannelServiceClient = v3.NotificationChannelServiceClient; const ServiceMonitoringServiceClient = v3.ServiceMonitoringServiceClient; +type ServiceMonitoringServiceClient = v3.ServiceMonitoringServiceClient; const UptimeCheckServiceClient = v3.UptimeCheckServiceClient; +type UptimeCheckServiceClient = v3.UptimeCheckServiceClient; export { v3, diff --git a/packages/google-cloud-monitoring/src/v3/alert_policy_service_client.ts b/packages/google-cloud-monitoring/src/v3/alert_policy_service_client.ts index 4111238dcde..76394756799 100644 --- a/packages/google-cloud-monitoring/src/v3/alert_policy_service_client.ts +++ b/packages/google-cloud-monitoring/src/v3/alert_policy_service_client.ts @@ -68,8 +68,10 @@ export class AlertPolicyServiceClient { /** * Construct an instance of AlertPolicyServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @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/master/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] @@ -89,42 +91,33 @@ export class AlertPolicyServiceClient { * 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. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof AlertPolicyServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the AlertPolicyServiceClient constructor. + + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof AlertPolicyServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -133,6 +126,11 @@ export class AlertPolicyServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -337,6 +335,7 @@ export class AlertPolicyServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'monitoring.googleapis.com'; @@ -345,6 +344,7 @@ export class AlertPolicyServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'monitoring.googleapis.com'; @@ -352,6 +352,7 @@ export class AlertPolicyServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -360,6 +361,7 @@ export class AlertPolicyServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return [ @@ -373,8 +375,7 @@ export class AlertPolicyServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -429,7 +430,11 @@ export class AlertPolicyServiceClient { * 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 [AlertPolicy]{@link google.monitoring.v3.AlertPolicy}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getAlertPolicy(request); */ getAlertPolicy( request: protos.google.monitoring.v3.IGetAlertPolicyRequest, @@ -522,7 +527,11 @@ export class AlertPolicyServiceClient { * 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 [AlertPolicy]{@link google.monitoring.v3.AlertPolicy}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createAlertPolicy(request); */ createAlertPolicy( request: protos.google.monitoring.v3.ICreateAlertPolicyRequest, @@ -608,7 +617,11 @@ export class AlertPolicyServiceClient { * 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 [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.deleteAlertPolicy(request); */ deleteAlertPolicy( request: protos.google.monitoring.v3.IDeleteAlertPolicyRequest, @@ -718,7 +731,11 @@ export class AlertPolicyServiceClient { * 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 [AlertPolicy]{@link google.monitoring.v3.AlertPolicy}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.updateAlertPolicy(request); */ updateAlertPolicy( request: protos.google.monitoring.v3.IUpdateAlertPolicyRequest, @@ -828,19 +845,14 @@ export class AlertPolicyServiceClient { * 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 [AlertPolicy]{@link google.monitoring.v3.AlertPolicy}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [AlertPolicy]{@link google.monitoring.v3.AlertPolicy} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListAlertPoliciesRequest]{@link google.monitoring.v3.ListAlertPoliciesRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListAlertPoliciesResponse]{@link google.monitoring.v3.ListAlertPoliciesResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listAlertPoliciesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listAlertPolicies( request: protos.google.monitoring.v3.IListAlertPoliciesRequest, @@ -886,18 +898,7 @@ export class AlertPolicyServiceClient { } /** - * Equivalent to {@link listAlertPolicies}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listAlertPolicies} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.name @@ -933,6 +934,13 @@ export class AlertPolicyServiceClient { * 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 [AlertPolicy]{@link google.monitoring.v3.AlertPolicy} 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 `listAlertPoliciesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listAlertPoliciesStream( request?: protos.google.monitoring.v3.IListAlertPoliciesRequest, @@ -957,10 +965,9 @@ export class AlertPolicyServiceClient { } /** - * Equivalent to {@link listAlertPolicies}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listAlertPolicies`, 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.name @@ -995,7 +1002,18 @@ export class AlertPolicyServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [AlertPolicy]{@link google.monitoring.v3.AlertPolicy}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listAlertPoliciesAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listAlertPoliciesAsync( request?: protos.google.monitoring.v3.IListAlertPoliciesRequest, @@ -2212,9 +2230,10 @@ export class AlertPolicyServiceClient { } /** - * Terminate the GRPC channel and close the client. + * 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 { this.initialize(); diff --git a/packages/google-cloud-monitoring/src/v3/group_service_client.ts b/packages/google-cloud-monitoring/src/v3/group_service_client.ts index ba6068ea86e..60565bac44f 100644 --- a/packages/google-cloud-monitoring/src/v3/group_service_client.ts +++ b/packages/google-cloud-monitoring/src/v3/group_service_client.ts @@ -71,8 +71,10 @@ export class GroupServiceClient { /** * Construct an instance of GroupServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @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/master/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] @@ -92,42 +94,33 @@ export class GroupServiceClient { * 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. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof GroupServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the GroupServiceClient constructor. + + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof GroupServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -136,6 +129,11 @@ export class GroupServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -346,6 +344,7 @@ export class GroupServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'monitoring.googleapis.com'; @@ -354,6 +353,7 @@ export class GroupServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'monitoring.googleapis.com'; @@ -361,6 +361,7 @@ export class GroupServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -369,6 +370,7 @@ export class GroupServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return [ @@ -382,8 +384,7 @@ export class GroupServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -438,7 +439,11 @@ export class GroupServiceClient { * 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 [Group]{@link google.monitoring.v3.Group}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getGroup(request); */ getGroup( request: protos.google.monitoring.v3.IGetGroupRequest, @@ -525,7 +530,11 @@ export class GroupServiceClient { * 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 [Group]{@link google.monitoring.v3.Group}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createGroup(request); */ createGroup( request: protos.google.monitoring.v3.ICreateGroupRequest, @@ -609,7 +618,11 @@ export class GroupServiceClient { * 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 [Group]{@link google.monitoring.v3.Group}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.updateGroup(request); */ updateGroup( request: protos.google.monitoring.v3.IUpdateGroupRequest, @@ -695,7 +708,11 @@ export class GroupServiceClient { * 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 [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.deleteGroup(request); */ deleteGroup( request: protos.google.monitoring.v3.IDeleteGroupRequest, @@ -808,19 +825,14 @@ export class GroupServiceClient { * 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 [Group]{@link google.monitoring.v3.Group}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [Group]{@link google.monitoring.v3.Group} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListGroupsRequest]{@link google.monitoring.v3.ListGroupsRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListGroupsResponse]{@link google.monitoring.v3.ListGroupsResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listGroupsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listGroups( request: protos.google.monitoring.v3.IListGroupsRequest, @@ -864,18 +876,7 @@ export class GroupServiceClient { } /** - * Equivalent to {@link listGroups}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listGroups} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.name @@ -916,6 +917,13 @@ export class GroupServiceClient { * 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 [Group]{@link google.monitoring.v3.Group} 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 `listGroupsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listGroupsStream( request?: protos.google.monitoring.v3.IListGroupsRequest, @@ -940,10 +948,9 @@ export class GroupServiceClient { } /** - * Equivalent to {@link listGroups}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listGroups`, 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.name @@ -983,7 +990,18 @@ export class GroupServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [Group]{@link google.monitoring.v3.Group}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listGroupsAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listGroupsAsync( request?: protos.google.monitoring.v3.IListGroupsRequest, @@ -1067,19 +1085,14 @@ export class GroupServiceClient { * 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 [MonitoredResource]{@link google.api.MonitoredResource}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [MonitoredResource]{@link google.api.MonitoredResource} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListGroupMembersRequest]{@link google.monitoring.v3.ListGroupMembersRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListGroupMembersResponse]{@link google.monitoring.v3.ListGroupMembersResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listGroupMembersAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listGroupMembers( request: protos.google.monitoring.v3.IListGroupMembersRequest, @@ -1125,18 +1138,7 @@ export class GroupServiceClient { } /** - * Equivalent to {@link listGroupMembers}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listGroupMembers} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.name @@ -1167,6 +1169,13 @@ export class GroupServiceClient { * 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 [MonitoredResource]{@link google.api.MonitoredResource} 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 `listGroupMembersAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listGroupMembersStream( request?: protos.google.monitoring.v3.IListGroupMembersRequest, @@ -1191,10 +1200,9 @@ export class GroupServiceClient { } /** - * Equivalent to {@link listGroupMembers}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listGroupMembers`, 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.name @@ -1224,7 +1232,18 @@ export class GroupServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [MonitoredResource]{@link google.api.MonitoredResource}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listGroupMembersAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listGroupMembersAsync( request?: protos.google.monitoring.v3.IListGroupMembersRequest, @@ -2441,9 +2460,10 @@ export class GroupServiceClient { } /** - * Terminate the GRPC channel and close the client. + * 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 { this.initialize(); diff --git a/packages/google-cloud-monitoring/src/v3/metric_service_client.ts b/packages/google-cloud-monitoring/src/v3/metric_service_client.ts index 91487ca0c3c..707bcfcb6c0 100644 --- a/packages/google-cloud-monitoring/src/v3/metric_service_client.ts +++ b/packages/google-cloud-monitoring/src/v3/metric_service_client.ts @@ -61,8 +61,10 @@ export class MetricServiceClient { /** * Construct an instance of MetricServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @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/master/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] @@ -82,42 +84,33 @@ export class MetricServiceClient { * 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. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof MetricServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the MetricServiceClient constructor. + + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof MetricServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -126,6 +119,11 @@ export class MetricServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -361,6 +359,7 @@ export class MetricServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'monitoring.googleapis.com'; @@ -369,6 +368,7 @@ export class MetricServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'monitoring.googleapis.com'; @@ -376,6 +376,7 @@ export class MetricServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -384,6 +385,7 @@ export class MetricServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return [ @@ -398,8 +400,7 @@ export class MetricServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -464,7 +465,11 @@ export class MetricServiceClient { * 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 [MonitoredResourceDescriptor]{@link google.api.MonitoredResourceDescriptor}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getMonitoredResourceDescriptor(request); */ getMonitoredResourceDescriptor( request: protos.google.monitoring.v3.IGetMonitoredResourceDescriptorRequest, @@ -564,7 +569,11 @@ export class MetricServiceClient { * 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 [MetricDescriptor]{@link google.api.MetricDescriptor}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getMetricDescriptor(request); */ getMetricDescriptor( request: protos.google.monitoring.v3.IGetMetricDescriptorRequest, @@ -659,7 +668,11 @@ export class MetricServiceClient { * 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 [MetricDescriptor]{@link google.api.MetricDescriptor}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createMetricDescriptor(request); */ createMetricDescriptor( request: protos.google.monitoring.v3.ICreateMetricDescriptorRequest, @@ -758,7 +771,11 @@ export class MetricServiceClient { * 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 [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.deleteMetricDescriptor(request); */ deleteMetricDescriptor( request: protos.google.monitoring.v3.IDeleteMetricDescriptorRequest, @@ -859,7 +876,11 @@ export class MetricServiceClient { * 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 [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createTimeSeries(request); */ createTimeSeries( request: protos.google.monitoring.v3.ICreateTimeSeriesRequest, @@ -961,19 +982,14 @@ export class MetricServiceClient { * 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 [MonitoredResourceDescriptor]{@link google.api.MonitoredResourceDescriptor}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [MonitoredResourceDescriptor]{@link google.api.MonitoredResourceDescriptor} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListMonitoredResourceDescriptorsRequest]{@link google.monitoring.v3.ListMonitoredResourceDescriptorsRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListMonitoredResourceDescriptorsResponse]{@link google.monitoring.v3.ListMonitoredResourceDescriptorsResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listMonitoredResourceDescriptorsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listMonitoredResourceDescriptors( request: protos.google.monitoring.v3.IListMonitoredResourceDescriptorsRequest, @@ -1025,18 +1041,7 @@ export class MetricServiceClient { } /** - * Equivalent to {@link listMonitoredResourceDescriptors}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listMonitoredResourceDescriptors} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.name @@ -1060,6 +1065,13 @@ export class MetricServiceClient { * 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 [MonitoredResourceDescriptor]{@link google.api.MonitoredResourceDescriptor} 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 `listMonitoredResourceDescriptorsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listMonitoredResourceDescriptorsStream( request?: protos.google.monitoring.v3.IListMonitoredResourceDescriptorsRequest, @@ -1084,10 +1096,9 @@ export class MetricServiceClient { } /** - * Equivalent to {@link listMonitoredResourceDescriptors}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listMonitoredResourceDescriptors`, 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.name @@ -1110,7 +1121,18 @@ export class MetricServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [MonitoredResourceDescriptor]{@link google.api.MonitoredResourceDescriptor}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listMonitoredResourceDescriptorsAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listMonitoredResourceDescriptorsAsync( request?: protos.google.monitoring.v3.IListMonitoredResourceDescriptorsRequest, @@ -1193,19 +1215,14 @@ export class MetricServiceClient { * 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 [MetricDescriptor]{@link google.api.MetricDescriptor}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [MetricDescriptor]{@link google.api.MetricDescriptor} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListMetricDescriptorsRequest]{@link google.monitoring.v3.ListMetricDescriptorsRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListMetricDescriptorsResponse]{@link google.monitoring.v3.ListMetricDescriptorsResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listMetricDescriptorsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listMetricDescriptors( request: protos.google.monitoring.v3.IListMetricDescriptorsRequest, @@ -1253,18 +1270,7 @@ export class MetricServiceClient { } /** - * Equivalent to {@link listMetricDescriptors}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listMetricDescriptors} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.name @@ -1290,6 +1296,13 @@ export class MetricServiceClient { * 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 [MetricDescriptor]{@link google.api.MetricDescriptor} 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 `listMetricDescriptorsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listMetricDescriptorsStream( request?: protos.google.monitoring.v3.IListMetricDescriptorsRequest, @@ -1314,10 +1327,9 @@ export class MetricServiceClient { } /** - * Equivalent to {@link listMetricDescriptors}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listMetricDescriptors`, 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.name @@ -1342,7 +1354,18 @@ export class MetricServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [MetricDescriptor]{@link google.api.MetricDescriptor}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listMetricDescriptorsAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listMetricDescriptorsAsync( request?: protos.google.monitoring.v3.IListMetricDescriptorsRequest, @@ -1439,19 +1462,14 @@ export class MetricServiceClient { * 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 [TimeSeries]{@link google.monitoring.v3.TimeSeries}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [TimeSeries]{@link google.monitoring.v3.TimeSeries} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListTimeSeriesRequest]{@link google.monitoring.v3.ListTimeSeriesRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListTimeSeriesResponse]{@link google.monitoring.v3.ListTimeSeriesResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listTimeSeriesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listTimeSeries( request: protos.google.monitoring.v3.IListTimeSeriesRequest, @@ -1497,18 +1515,7 @@ export class MetricServiceClient { } /** - * Equivalent to {@link listTimeSeries}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listTimeSeries} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.name @@ -1552,6 +1559,13 @@ export class MetricServiceClient { * 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 [TimeSeries]{@link google.monitoring.v3.TimeSeries} 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 `listTimeSeriesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listTimeSeriesStream( request?: protos.google.monitoring.v3.IListTimeSeriesRequest, @@ -1576,10 +1590,9 @@ export class MetricServiceClient { } /** - * Equivalent to {@link listTimeSeries}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listTimeSeries`, 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.name @@ -1622,7 +1635,18 @@ export class MetricServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [TimeSeries]{@link google.monitoring.v3.TimeSeries}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listTimeSeriesAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listTimeSeriesAsync( request?: protos.google.monitoring.v3.IListTimeSeriesRequest, @@ -3121,9 +3145,10 @@ export class MetricServiceClient { } /** - * Terminate the GRPC channel and close the client. + * 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 { this.initialize(); diff --git a/packages/google-cloud-monitoring/src/v3/notification_channel_service_client.ts b/packages/google-cloud-monitoring/src/v3/notification_channel_service_client.ts index be004146958..ab75d9e7322 100644 --- a/packages/google-cloud-monitoring/src/v3/notification_channel_service_client.ts +++ b/packages/google-cloud-monitoring/src/v3/notification_channel_service_client.ts @@ -61,8 +61,10 @@ export class NotificationChannelServiceClient { /** * Construct an instance of NotificationChannelServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @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/master/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] @@ -82,44 +84,34 @@ export class NotificationChannelServiceClient { * 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. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this .constructor as typeof NotificationChannelServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the NotificationChannelServiceClient constructor. + + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this - .constructor as typeof NotificationChannelServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -128,6 +120,11 @@ export class NotificationChannelServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -342,6 +339,7 @@ export class NotificationChannelServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'monitoring.googleapis.com'; @@ -350,6 +348,7 @@ export class NotificationChannelServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'monitoring.googleapis.com'; @@ -357,6 +356,7 @@ export class NotificationChannelServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -365,6 +365,7 @@ export class NotificationChannelServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return [ @@ -378,8 +379,7 @@ export class NotificationChannelServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -442,7 +442,11 @@ export class NotificationChannelServiceClient { * 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 [NotificationChannelDescriptor]{@link google.monitoring.v3.NotificationChannelDescriptor}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getNotificationChannelDescriptor(request); */ getNotificationChannelDescriptor( request: protos.google.monitoring.v3.IGetNotificationChannelDescriptorRequest, @@ -543,7 +547,11 @@ export class NotificationChannelServiceClient { * 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 [NotificationChannel]{@link google.monitoring.v3.NotificationChannel}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getNotificationChannel(request); */ getNotificationChannel( request: protos.google.monitoring.v3.IGetNotificationChannelRequest, @@ -645,7 +653,11 @@ export class NotificationChannelServiceClient { * 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 [NotificationChannel]{@link google.monitoring.v3.NotificationChannel}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createNotificationChannel(request); */ createNotificationChannel( request: protos.google.monitoring.v3.ICreateNotificationChannelRequest, @@ -743,7 +755,11 @@ export class NotificationChannelServiceClient { * 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 [NotificationChannel]{@link google.monitoring.v3.NotificationChannel}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.updateNotificationChannel(request); */ updateNotificationChannel( request: protos.google.monitoring.v3.IUpdateNotificationChannelRequest, @@ -842,7 +858,11 @@ export class NotificationChannelServiceClient { * 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 [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.deleteNotificationChannel(request); */ deleteNotificationChannel( request: protos.google.monitoring.v3.IDeleteNotificationChannelRequest, @@ -938,7 +958,11 @@ export class NotificationChannelServiceClient { * 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 [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.sendNotificationChannelVerificationCode(request); */ sendNotificationChannelVerificationCode( request: protos.google.monitoring.v3.ISendNotificationChannelVerificationCodeRequest, @@ -1068,7 +1092,11 @@ export class NotificationChannelServiceClient { * 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 [GetNotificationChannelVerificationCodeResponse]{@link google.monitoring.v3.GetNotificationChannelVerificationCodeResponse}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getNotificationChannelVerificationCode(request); */ getNotificationChannelVerificationCode( request: protos.google.monitoring.v3.IGetNotificationChannelVerificationCodeRequest, @@ -1173,7 +1201,11 @@ export class NotificationChannelServiceClient { * 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 [NotificationChannel]{@link google.monitoring.v3.NotificationChannel}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.verifyNotificationChannel(request); */ verifyNotificationChannel( request: protos.google.monitoring.v3.IVerifyNotificationChannelRequest, @@ -1283,19 +1315,14 @@ export class NotificationChannelServiceClient { * 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 [NotificationChannelDescriptor]{@link google.monitoring.v3.NotificationChannelDescriptor}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [NotificationChannelDescriptor]{@link google.monitoring.v3.NotificationChannelDescriptor} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListNotificationChannelDescriptorsRequest]{@link google.monitoring.v3.ListNotificationChannelDescriptorsRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListNotificationChannelDescriptorsResponse]{@link google.monitoring.v3.ListNotificationChannelDescriptorsResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listNotificationChannelDescriptorsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listNotificationChannelDescriptors( request: protos.google.monitoring.v3.IListNotificationChannelDescriptorsRequest, @@ -1347,18 +1374,7 @@ export class NotificationChannelServiceClient { } /** - * Equivalent to {@link listNotificationChannelDescriptors}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listNotificationChannelDescriptors} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.name @@ -1383,6 +1399,13 @@ export class NotificationChannelServiceClient { * 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 [NotificationChannelDescriptor]{@link google.monitoring.v3.NotificationChannelDescriptor} 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 `listNotificationChannelDescriptorsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listNotificationChannelDescriptorsStream( request?: protos.google.monitoring.v3.IListNotificationChannelDescriptorsRequest, @@ -1407,10 +1430,9 @@ export class NotificationChannelServiceClient { } /** - * Equivalent to {@link listNotificationChannelDescriptors}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listNotificationChannelDescriptors`, 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.name @@ -1434,7 +1456,18 @@ export class NotificationChannelServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [NotificationChannelDescriptor]{@link google.monitoring.v3.NotificationChannelDescriptor}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listNotificationChannelDescriptorsAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listNotificationChannelDescriptorsAsync( request?: protos.google.monitoring.v3.IListNotificationChannelDescriptorsRequest, @@ -1532,19 +1565,14 @@ export class NotificationChannelServiceClient { * 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 [NotificationChannel]{@link google.monitoring.v3.NotificationChannel}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [NotificationChannel]{@link google.monitoring.v3.NotificationChannel} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListNotificationChannelsRequest]{@link google.monitoring.v3.ListNotificationChannelsRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListNotificationChannelsResponse]{@link google.monitoring.v3.ListNotificationChannelsResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listNotificationChannelsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listNotificationChannels( request: protos.google.monitoring.v3.IListNotificationChannelsRequest, @@ -1596,18 +1624,7 @@ export class NotificationChannelServiceClient { } /** - * Equivalent to {@link listNotificationChannels}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listNotificationChannels} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.name @@ -1646,6 +1663,13 @@ export class NotificationChannelServiceClient { * 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 [NotificationChannel]{@link google.monitoring.v3.NotificationChannel} 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 `listNotificationChannelsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listNotificationChannelsStream( request?: protos.google.monitoring.v3.IListNotificationChannelsRequest, @@ -1670,10 +1694,9 @@ export class NotificationChannelServiceClient { } /** - * Equivalent to {@link listNotificationChannels}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listNotificationChannels`, 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.name @@ -1711,7 +1734,18 @@ export class NotificationChannelServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [NotificationChannel]{@link google.monitoring.v3.NotificationChannel}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listNotificationChannelsAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listNotificationChannelsAsync( request?: protos.google.monitoring.v3.IListNotificationChannelsRequest, @@ -2928,9 +2962,10 @@ export class NotificationChannelServiceClient { } /** - * Terminate the GRPC channel and close the client. + * 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 { this.initialize(); diff --git a/packages/google-cloud-monitoring/src/v3/service_monitoring_service_client.ts b/packages/google-cloud-monitoring/src/v3/service_monitoring_service_client.ts index 9fdaaf48382..5590bd92aeb 100644 --- a/packages/google-cloud-monitoring/src/v3/service_monitoring_service_client.ts +++ b/packages/google-cloud-monitoring/src/v3/service_monitoring_service_client.ts @@ -63,8 +63,10 @@ export class ServiceMonitoringServiceClient { /** * Construct an instance of ServiceMonitoringServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @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/master/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] @@ -84,44 +86,34 @@ export class ServiceMonitoringServiceClient { * 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. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this .constructor as typeof ServiceMonitoringServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the ServiceMonitoringServiceClient constructor. + + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this - .constructor as typeof ServiceMonitoringServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -130,6 +122,11 @@ export class ServiceMonitoringServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -344,6 +341,7 @@ export class ServiceMonitoringServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'monitoring.googleapis.com'; @@ -352,6 +350,7 @@ export class ServiceMonitoringServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'monitoring.googleapis.com'; @@ -359,6 +358,7 @@ export class ServiceMonitoringServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -367,6 +367,7 @@ export class ServiceMonitoringServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return [ @@ -380,8 +381,7 @@ export class ServiceMonitoringServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -441,7 +441,11 @@ export class ServiceMonitoringServiceClient { * 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 [Service]{@link google.monitoring.v3.Service}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createService(request); */ createService( request: protos.google.monitoring.v3.ICreateServiceRequest, @@ -523,7 +527,11 @@ export class ServiceMonitoringServiceClient { * 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 [Service]{@link google.monitoring.v3.Service}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getService(request); */ getService( request: protos.google.monitoring.v3.IGetServiceRequest, @@ -606,7 +614,11 @@ export class ServiceMonitoringServiceClient { * 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 [Service]{@link google.monitoring.v3.Service}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.updateService(request); */ updateService( request: protos.google.monitoring.v3.IUpdateServiceRequest, @@ -688,7 +700,11 @@ export class ServiceMonitoringServiceClient { * 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 [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.deleteService(request); */ deleteService( request: protos.google.monitoring.v3.IDeleteServiceRequest, @@ -785,7 +801,11 @@ export class ServiceMonitoringServiceClient { * 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 [ServiceLevelObjective]{@link google.monitoring.v3.ServiceLevelObjective}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createServiceLevelObjective(request); */ createServiceLevelObjective( request: protos.google.monitoring.v3.ICreateServiceLevelObjectiveRequest, @@ -887,7 +907,11 @@ export class ServiceMonitoringServiceClient { * 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 [ServiceLevelObjective]{@link google.monitoring.v3.ServiceLevelObjective}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getServiceLevelObjective(request); */ getServiceLevelObjective( request: protos.google.monitoring.v3.IGetServiceLevelObjectiveRequest, @@ -985,7 +1009,11 @@ export class ServiceMonitoringServiceClient { * 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 [ServiceLevelObjective]{@link google.monitoring.v3.ServiceLevelObjective}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.updateServiceLevelObjective(request); */ updateServiceLevelObjective( request: protos.google.monitoring.v3.IUpdateServiceLevelObjectiveRequest, @@ -1085,7 +1113,11 @@ export class ServiceMonitoringServiceClient { * 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 [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.deleteServiceLevelObjective(request); */ deleteServiceLevelObjective( request: protos.google.monitoring.v3.IDeleteServiceLevelObjectiveRequest, @@ -1204,19 +1236,14 @@ export class ServiceMonitoringServiceClient { * 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 [Service]{@link google.monitoring.v3.Service}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [Service]{@link google.monitoring.v3.Service} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListServicesRequest]{@link google.monitoring.v3.ListServicesRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListServicesResponse]{@link google.monitoring.v3.ListServicesResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listServicesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listServices( request: protos.google.monitoring.v3.IListServicesRequest, @@ -1260,18 +1287,7 @@ export class ServiceMonitoringServiceClient { } /** - * Equivalent to {@link listServices}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listServices} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.parent @@ -1307,6 +1323,13 @@ export class ServiceMonitoringServiceClient { * 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 [Service]{@link google.monitoring.v3.Service} 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 `listServicesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listServicesStream( request?: protos.google.monitoring.v3.IListServicesRequest, @@ -1331,10 +1354,9 @@ export class ServiceMonitoringServiceClient { } /** - * Equivalent to {@link listServices}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listServices`, 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 @@ -1369,7 +1391,18 @@ export class ServiceMonitoringServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [Service]{@link google.monitoring.v3.Service}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listServicesAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listServicesAsync( request?: protos.google.monitoring.v3.IListServicesRequest, @@ -1453,19 +1486,14 @@ export class ServiceMonitoringServiceClient { * 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 [ServiceLevelObjective]{@link google.monitoring.v3.ServiceLevelObjective}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [ServiceLevelObjective]{@link google.monitoring.v3.ServiceLevelObjective} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListServiceLevelObjectivesRequest]{@link google.monitoring.v3.ListServiceLevelObjectivesRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListServiceLevelObjectivesResponse]{@link google.monitoring.v3.ListServiceLevelObjectivesResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listServiceLevelObjectivesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listServiceLevelObjectives( request: protos.google.monitoring.v3.IListServiceLevelObjectivesRequest, @@ -1517,18 +1545,7 @@ export class ServiceMonitoringServiceClient { } /** - * Equivalent to {@link listServiceLevelObjectives}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listServiceLevelObjectives} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.parent @@ -1555,6 +1572,13 @@ export class ServiceMonitoringServiceClient { * 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 [ServiceLevelObjective]{@link google.monitoring.v3.ServiceLevelObjective} 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 `listServiceLevelObjectivesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listServiceLevelObjectivesStream( request?: protos.google.monitoring.v3.IListServiceLevelObjectivesRequest, @@ -1579,10 +1603,9 @@ export class ServiceMonitoringServiceClient { } /** - * Equivalent to {@link listServiceLevelObjectives}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listServiceLevelObjectives`, 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 @@ -1608,7 +1631,18 @@ export class ServiceMonitoringServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [ServiceLevelObjective]{@link google.monitoring.v3.ServiceLevelObjective}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listServiceLevelObjectivesAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listServiceLevelObjectivesAsync( request?: protos.google.monitoring.v3.IListServiceLevelObjectivesRequest, @@ -2825,9 +2859,10 @@ export class ServiceMonitoringServiceClient { } /** - * Terminate the GRPC channel and close the client. + * 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 { this.initialize(); diff --git a/packages/google-cloud-monitoring/src/v3/uptime_check_service_client.ts b/packages/google-cloud-monitoring/src/v3/uptime_check_service_client.ts index 7d44e34d266..a685f94efb3 100644 --- a/packages/google-cloud-monitoring/src/v3/uptime_check_service_client.ts +++ b/packages/google-cloud-monitoring/src/v3/uptime_check_service_client.ts @@ -67,8 +67,10 @@ export class UptimeCheckServiceClient { /** * Construct an instance of UptimeCheckServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @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/master/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] @@ -88,42 +90,33 @@ export class UptimeCheckServiceClient { * 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. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof UptimeCheckServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the UptimeCheckServiceClient constructor. + + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof UptimeCheckServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -132,6 +125,11 @@ export class UptimeCheckServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -342,6 +340,7 @@ export class UptimeCheckServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'monitoring.googleapis.com'; @@ -350,6 +349,7 @@ export class UptimeCheckServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'monitoring.googleapis.com'; @@ -357,6 +357,7 @@ export class UptimeCheckServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -365,6 +366,7 @@ export class UptimeCheckServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return [ @@ -378,8 +380,7 @@ export class UptimeCheckServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -438,7 +439,11 @@ export class UptimeCheckServiceClient { * 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 [UptimeCheckConfig]{@link google.monitoring.v3.UptimeCheckConfig}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getUptimeCheckConfig(request); */ getUptimeCheckConfig( request: protos.google.monitoring.v3.IGetUptimeCheckConfigRequest, @@ -530,7 +535,11 @@ export class UptimeCheckServiceClient { * 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 [UptimeCheckConfig]{@link google.monitoring.v3.UptimeCheckConfig}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createUptimeCheckConfig(request); */ createUptimeCheckConfig( request: protos.google.monitoring.v3.ICreateUptimeCheckConfigRequest, @@ -640,7 +649,11 @@ export class UptimeCheckServiceClient { * 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 [UptimeCheckConfig]{@link google.monitoring.v3.UptimeCheckConfig}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.updateUptimeCheckConfig(request); */ updateUptimeCheckConfig( request: protos.google.monitoring.v3.IUpdateUptimeCheckConfigRequest, @@ -736,7 +749,11 @@ export class UptimeCheckServiceClient { * 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 [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.deleteUptimeCheckConfig(request); */ deleteUptimeCheckConfig( request: protos.google.monitoring.v3.IDeleteUptimeCheckConfigRequest, @@ -841,19 +858,14 @@ export class UptimeCheckServiceClient { * 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 [UptimeCheckConfig]{@link google.monitoring.v3.UptimeCheckConfig}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [UptimeCheckConfig]{@link google.monitoring.v3.UptimeCheckConfig} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListUptimeCheckConfigsRequest]{@link google.monitoring.v3.ListUptimeCheckConfigsRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListUptimeCheckConfigsResponse]{@link google.monitoring.v3.ListUptimeCheckConfigsResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listUptimeCheckConfigsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listUptimeCheckConfigs( request: protos.google.monitoring.v3.IListUptimeCheckConfigsRequest, @@ -905,18 +917,7 @@ export class UptimeCheckServiceClient { } /** - * Equivalent to {@link listUptimeCheckConfigs}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listUptimeCheckConfigs} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.parent @@ -936,6 +937,13 @@ export class UptimeCheckServiceClient { * 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 [UptimeCheckConfig]{@link google.monitoring.v3.UptimeCheckConfig} 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 `listUptimeCheckConfigsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listUptimeCheckConfigsStream( request?: protos.google.monitoring.v3.IListUptimeCheckConfigsRequest, @@ -960,10 +968,9 @@ export class UptimeCheckServiceClient { } /** - * Equivalent to {@link listUptimeCheckConfigs}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listUptimeCheckConfigs`, 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 @@ -982,7 +989,18 @@ export class UptimeCheckServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [UptimeCheckConfig]{@link google.monitoring.v3.UptimeCheckConfig}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listUptimeCheckConfigsAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listUptimeCheckConfigsAsync( request?: protos.google.monitoring.v3.IListUptimeCheckConfigsRequest, @@ -1057,19 +1075,14 @@ export class UptimeCheckServiceClient { * 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 [UptimeCheckIp]{@link google.monitoring.v3.UptimeCheckIp}. - * The client library support auto-pagination by default: it will call the API as many + * 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. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [UptimeCheckIp]{@link google.monitoring.v3.UptimeCheckIp} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListUptimeCheckIpsRequest]{@link google.monitoring.v3.ListUptimeCheckIpsRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListUptimeCheckIpsResponse]{@link google.monitoring.v3.ListUptimeCheckIpsResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listUptimeCheckIpsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listUptimeCheckIps( request: protos.google.monitoring.v3.IListUptimeCheckIpsRequest, @@ -1110,18 +1123,7 @@ export class UptimeCheckServiceClient { } /** - * Equivalent to {@link listUptimeCheckIps}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listUptimeCheckIps} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {number} request.pageSize @@ -1139,6 +1141,13 @@ export class UptimeCheckServiceClient { * 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 [UptimeCheckIp]{@link google.monitoring.v3.UptimeCheckIp} 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 `listUptimeCheckIpsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listUptimeCheckIpsStream( request?: protos.google.monitoring.v3.IListUptimeCheckIpsRequest, @@ -1156,10 +1165,9 @@ export class UptimeCheckServiceClient { } /** - * Equivalent to {@link listUptimeCheckIps}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listUptimeCheckIps`, 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 {number} request.pageSize @@ -1176,7 +1184,18 @@ export class UptimeCheckServiceClient { * @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 conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [UptimeCheckIp]{@link google.monitoring.v3.UptimeCheckIp}. 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 + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listUptimeCheckIpsAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listUptimeCheckIpsAsync( request?: protos.google.monitoring.v3.IListUptimeCheckIpsRequest, @@ -2386,9 +2405,10 @@ export class UptimeCheckServiceClient { } /** - * Terminate the GRPC channel and close the client. + * 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 { this.initialize(); diff --git a/packages/google-cloud-monitoring/synth.metadata b/packages/google-cloud-monitoring/synth.metadata index 322b0e20cb5..0a499efd392 100644 --- a/packages/google-cloud-monitoring/synth.metadata +++ b/packages/google-cloud-monitoring/synth.metadata @@ -3,23 +3,15 @@ { "git": { "name": ".", - "remote": "https://github.com/googleapis/nodejs-monitoring.git", - "sha": "6445e65c0ff84e9cb0dac2c9b7bf172300f4bd2a" - } - }, - { - "git": { - "name": "googleapis", - "remote": "https://github.com/googleapis/googleapis.git", - "sha": "4c5071b615d96ef9dfd6a63d8429090f1f2872bb", - "internalRef": "327369997" + "remote": "git@github.com:googleapis/nodejs-monitoring.git", + "sha": "69f9bcf752172e6a5a793d0150176d6f9c6658b2" } }, { "git": { "name": "synthtool", "remote": "https://github.com/googleapis/synthtool.git", - "sha": "ba9918cd22874245b55734f57470c719b577e591" + "sha": "1f1148d3c7a7a52f0c98077f976bd9b3c948ee2b" } } ], @@ -87,6 +79,7 @@ "README.md", "api-extractor.json", "linkinator.config.json", + "package-lock.json.592367270", "protos/google/monitoring/v3/alert.proto", "protos/google/monitoring/v3/alert_service.proto", "protos/google/monitoring/v3/common.proto", @@ -108,6 +101,7 @@ "protos/protos.json", "renovate.json", "samples/README.md", + "samples/package-lock.json.4124165143", "src/index.ts", "src/v3/alert_policy_service_client.ts", "src/v3/alert_policy_service_client_config.json", diff --git a/packages/google-cloud-monitoring/system-test/fixtures/sample/src/index.ts b/packages/google-cloud-monitoring/system-test/fixtures/sample/src/index.ts index 70b78043268..c456bb14d99 100644 --- a/packages/google-cloud-monitoring/system-test/fixtures/sample/src/index.ts +++ b/packages/google-cloud-monitoring/system-test/fixtures/sample/src/index.ts @@ -25,13 +25,49 @@ import { UptimeCheckServiceClient, } from '@google-cloud/monitoring'; +// check that the client class type name can be used +function doStuffWithAlertPolicyServiceClient(client: AlertPolicyServiceClient) { + client.close(); +} +function doStuffWithGroupServiceClient(client: GroupServiceClient) { + client.close(); +} +function doStuffWithMetricServiceClient(client: MetricServiceClient) { + client.close(); +} +function doStuffWithNotificationChannelServiceClient( + client: NotificationChannelServiceClient +) { + client.close(); +} +function doStuffWithServiceMonitoringServiceClient( + client: ServiceMonitoringServiceClient +) { + client.close(); +} +function doStuffWithUptimeCheckServiceClient(client: UptimeCheckServiceClient) { + client.close(); +} + function main() { - new AlertPolicyServiceClient(); - new GroupServiceClient(); - new MetricServiceClient(); - new NotificationChannelServiceClient(); - new ServiceMonitoringServiceClient(); - new UptimeCheckServiceClient(); + // check that the client instance can be created + const alertPolicyServiceClient = new AlertPolicyServiceClient(); + doStuffWithAlertPolicyServiceClient(alertPolicyServiceClient); + // check that the client instance can be created + const groupServiceClient = new GroupServiceClient(); + doStuffWithGroupServiceClient(groupServiceClient); + // check that the client instance can be created + const metricServiceClient = new MetricServiceClient(); + doStuffWithMetricServiceClient(metricServiceClient); + // check that the client instance can be created + const notificationChannelServiceClient = new NotificationChannelServiceClient(); + doStuffWithNotificationChannelServiceClient(notificationChannelServiceClient); + // check that the client instance can be created + const serviceMonitoringServiceClient = new ServiceMonitoringServiceClient(); + doStuffWithServiceMonitoringServiceClient(serviceMonitoringServiceClient); + // check that the client instance can be created + const uptimeCheckServiceClient = new UptimeCheckServiceClient(); + doStuffWithUptimeCheckServiceClient(uptimeCheckServiceClient); } main(); diff --git a/packages/google-cloud-monitoring/system-test/install.ts b/packages/google-cloud-monitoring/system-test/install.ts index 4c1ba3eb79a..39d90f771de 100644 --- a/packages/google-cloud-monitoring/system-test/install.ts +++ b/packages/google-cloud-monitoring/system-test/install.ts @@ -20,32 +20,32 @@ import {packNTest} from 'pack-n-play'; import {readFileSync} from 'fs'; import {describe, it} from 'mocha'; -describe('typescript consumer tests', () => { - it('should have correct type signature for typescript users', async function () { +describe('📦 pack-n-play test', () => { + it('TypeScript code', async function () { this.timeout(300000); const options = { - packageDir: process.cwd(), // path to your module. + packageDir: process.cwd(), sample: { - description: 'typescript based user can use the type definitions', + description: 'TypeScript user can use the type definitions', ts: readFileSync( './system-test/fixtures/sample/src/index.ts' ).toString(), }, }; - await packNTest(options); // will throw upon error. + await packNTest(options); }); - it('should have correct type signature for javascript users', async function () { + it('JavaScript code', async function () { this.timeout(300000); const options = { - packageDir: process.cwd(), // path to your module. + packageDir: process.cwd(), sample: { - description: 'typescript based user can use the type definitions', + description: 'JavaScript user can use the library', ts: readFileSync( './system-test/fixtures/sample/src/index.js' ).toString(), }, }; - await packNTest(options); // will throw upon error. + await packNTest(options); }); });