OperationsClient

OperationsClient

Manages long-running operations with an API service.

When an API method normally takes long time to complete, it can be designed to return Operation to the client, and the client can use this interface to receive the real response asynchronously by polling the operation resource, or pass the operation resource to another API (such as Google Cloud Pub/Sub API) to receive the response. Any API service that returns long-running operations should implement the Operations interface so developers can have a consistent client experience.

This will be created through a builder function which can be obtained by the module. See the following example of how to initialize the module and how to access to the builder.

Constructor

new OperationsClient()

See:
  • operationsClient

Methods

cancelOperation(request, optionsopt, callbackopt) → {Promise}

Starts asynchronous cancellation on a long-running operation. The server makes a best effort to cancel the operation, but success is not guaranteed. If the server doesn't support this method, it returns google.rpc.Code.UNIMPLEMENTED. Clients can use Operations.GetOperation or other methods to check whether the cancellation succeeded or whether the operation completed despite cancellation. On successful cancellation, the operation is not deleted; instead, it becomes an operation with an Operation.error value with a google.rpc.Status.code of 1, corresponding to Code.CANCELLED.

Parameters:
Name Type Attributes Description
request Object

The request object that will be sent.

Properties
Name Type Description
name string

The name of the operation resource to be cancelled.
options Object <optional>

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.
callback function <optional>

The function which will be called with the result of the API call.
Returns:
Type Description
Promise
  • The promise which resolves when API call finishes. The promise has a method named "cancel" which cancels the ongoing API call.
Example
const client = longrunning.operationsClient();
await client.cancelOperation({name: ''});

close()

Closes this operations client.

deleteOperation(request, optionsopt, callbackopt) → {Promise}

Deletes a long-running operation. This method indicates that the client is no longer interested in the operation result. It does not cancel the operation. If the server doesn't support this method, it returns google.rpc.Code.UNIMPLEMENTED.

Parameters:
Name Type Attributes Description
request Object

The request object that will be sent.

Properties
Name Type Description
name string

The name of the operation resource to be deleted.
options Object <optional>

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.
callback function <optional>

The function which will be called with the result of the API call.
Returns:
Type Description
Promise
  • The promise which resolves when API call finishes. The promise has a method named "cancel" which cancels the ongoing API call.
Example
const client = longrunning.operationsClient();
await client.deleteOperation({name: ''});

getOperation(request, optionsopt, callbackopt) → {Promise}

Gets the latest state of a long-running operation. Clients can use this method to poll the operation result at intervals as recommended by the API service.

Parameters:
Name Type Attributes Description
request Object

The request object that will be sent.

Properties
Name Type Description
name string

The name of the operation resource.
options Object <optional>

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.
callback function <optional>

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing google.longrunning.Operation.
Returns:
Type Description
Promise
  • The promise which resolves to an array. The first element of the array is an object representing google.longrunning.Operation. The promise has a method named "cancel" which cancels the ongoing API call.
Example
const client = longrunning.operationsClient();
const name = '';
const [response] = await client.getOperation({name});
// doThingsWith(response)

listOperations(request, optionsopt, callbackopt) → {Promise}

Lists operations that match the specified filter in the request. If the server doesn't support this method, it returns UNIMPLEMENTED.

NOTE: the name binding below allows API services to override the binding to use different resource name schemes.

Parameters:
Name Type Attributes Description
request Object

The request object that will be sent.

Properties
Name Type Attributes Description
name string

The name of the operation collection.
filter string

The standard list filter.
pageSize number <optional>

The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.
options Object <optional>

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.
callback function <optional>

The function which will be called with the result of the API call.

The second parameter to the callback is Array of google.longrunning.Operation.

When autoPaginate: false is specified through options, it contains the result in a single response. If the response indicates the next page exists, the third parameter is set to be used for the next request object. The fourth parameter keeps the raw response object of an object representing google.longrunning.ListOperationsResponse.
Returns:
Type Description
Promise

  • The promise which resolves to an array. The first element of the array is Array of google.longrunning.Operation.

    When autoPaginate: false is specified through options, the array has three elements. The first element is Array of google.longrunning.Operation in a single response. The second element is the next request object if the response indicates the next page exists, or null. The third element is an object representing google.longrunning.ListOperationsResponse.

    The promise has a method named "cancel" which cancels the ongoing API call.
Example
const client = longrunning.operationsClient();
const request = {
    name: '',
    filter: ''
};
// Iterate over all elements.
const [resources] = await client.listOperations(request);
for (const resource of resources) {
  console.log(resources);
}

// Or obtain the paged response.
const options = {autoPaginate: false};
let nextRequest = request;
while(nextRequest) {
  const response = await client.listOperations(nextRequest, options);
  const resources = response[0];
  nextRequest = response[1];
  const rawResponse = response[2];
  for (const resource of resources) {
    // doThingsWith(resource);
  }
};

listOperationsAsync(request, optionsopt) → {Object}

Equivalent to listOperations, but returns an iterable object.

for-await-of syntax is used with the iterable to recursively get response element on-demand.

Parameters:
Name Type Attributes Description
request Object

The request object that will be sent.

Properties
Name Type Attributes Description
name string

The name of the operation collection.
filter string

The standard list filter.
pageSize number <optional>

The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.
options Object <optional>

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.
Returns:
Type Description
Object

An iterable Object that conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols.

listOperationsStream(request, optionsopt) → {Stream}

Equivalent to listOperations, but returns a NodeJS Stream object.

This fetches the paged responses for listOperations 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.

Parameters:
Name Type Attributes Description
request Object

The request object that will be sent.

Properties
Name Type Attributes Description
name string

The name of the operation collection.
filter string

The standard list filter.
pageSize number <optional>

The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.
options Object <optional>

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.
Returns:
Type Description
Stream
  • An object stream which emits an object representing google.longrunning.Operation on 'data' event.
See:
Example
const client = longrunning.operationsClient();
const request = {
  name: '',
  filter: ''
};
client.listOperationsStream(request)
  .on('data', element => {
    // doThingsWith(element)
  })
  .on('error', err => {
    console.error(err);
  });