client-libraries.md

Client Libraries HOWTO

This document shows how to use client libraries that use google-gax as their transport layer (most of the Google Cloud client TypeScript libraries do).

In all the examples below, we'll use @google-cloud/library as a library being used (e.g. @google-cloud/speech, @google-cloud/text-to-speech, etc.), so you can assume it's imported like this:

JavaScript:

const library = require('@google-cloud/library');

TypeScript:

import * as library from '@google-cloud/library';

We'll also assume that the library defines a SampleClient (e.g. SpeechClient, TextToSpeechClient, etc.)

Creating the client instance

For the majority of use cases, it should just work without any parameters:

const client = new library.SampleClient();

The library will figure out what kind of credentials to use, and will instantiate the client using gRPC transport with the default settings.

Please make sure you create the client instance once and then reuse it. Do not create a separate client instance for every call.

Please note that the created instance is not authenticated until the first actual request to the service is made. In most cases, it does not make any difference since authentication happens under the hood, but it can slow down the very first request to the API. If you want to make sure the client is authenticated, you can force its initialization right after it's created:

const client = new library.SampleClient();
await client.initialize(); // performs auth

Constructor options

You can pass additional options to the constructor:

const options = {};
// set options
const client = new library.SampleClient(options);

Authentication options

Please take a look at GoogleAuthOptions in google-auth-library documentation for a complete list.

• options.credentials: credentials object:
  • options.credentials.client_email
  • options.credentials.private_key
• options.email: account email address. Required when using a .pem or .p12 keyFilename.
• options.keyFilename: full path to the a .json, .pem, or .p12 key downloaded from the Google Developers Console. If you provide a path to a JSON file, the projectId option below is not necessary.
  Note: .pem and .p12 require you to specify options.email as well.
• options.projectId: the project ID from the Google Developer's Console, e.g. grape-spaceship-123. We will also check the environment variable GCLOUD_PROJECT for your project ID. If your app is running in an environment which supports Application Default Credentials, your project ID will be detected automatically.

Service options

For most use cases, default values for the following options work pretty well.

The following two options are useful if you need to connect to a different endpoint than the default one:

• options.port: the port on which to connect to the remote host.
• options.apiEndpoint: the domain name of the API remote host.

The following option can be used to override client configuration, such as various timeouts. The default configuration can be found in the JSON file src/v*/*_client_config.json. You can pass any subset of that JSON and the corresponding default settings will be overridden.

• options.clientConfig: client configuration override.\

By default, the client library will use gRPC, which is a binary tranport based on HTTP/2. It's Node.js implementation, @grpc/grpc-js, uses Node.js http2 module.

HTTP/1.1 REST API mode

• options.fallback: true or false, use HTTP fallback mode. Default value is false, unless the window object is defined. For compatibility, you can pass any non-empty string, it will be considered a true value.

If you need to use the client library in non-Node.js environment or when gRPC cannot be used for any reason, you can use the HTTP/1.1 fallback mode. In this mode, a special browser-compatible transport implementation is used instead of gRPC transport. It will send and receive JSONs over HTTP.

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.

Calling API methods

In all examples below we assume that client is an instance of the client library class:

const client = new library.SampleClient();

Regular methods

Recommended usage with async / await:

const [response] = await client.sampleMethod(request);

Using promises:

client.doStuff(request).then([response] => { /* handle response */ });

If you need to be able to cancel the API call that is currently running, use the .cancel() method of the returned promise:

const promise = client.sampleMethod(request);
// the returned promise can be canceled:
promise.cancel();

You can override the default call options (such as retry settings or timeouts) for the given call by passing an object of type CallOptions in the second parameter:

const [response] = await client.sampleMethod(request, options);

Long-running operations

Some methods are expected to run longer. They return an object of type Operation that contains unique name of the operation and allows to track its status.

const [operation] = await client.sampleLongRunningMethod(request);

To get the result of the operation, just await for its promise to resolve:

const [response] = await operation.promise(); // polls the operation until complete

To check the operation status (is it completed or not) and metadata (e.g. is progress):

console.log(operation.name);     // unique name
console.log(operation.done);     // true or false
console.log(operation.metadata); // current value of the metadata (often contains progress %)
console.log(operation.result);   // only if operation is completed

To cancel the running operation:

operation.cancel();

You can override the default call options (such as retry settings or timeouts) for the given call by passing an object of type CallOptions in the second parameter:

const [operation] = await client.sampleLongRunningMethod(request, options);

In some cases you might need to be able to track the operation status and result by its name (e.g. if you are running in a Google Cloud Function and you don't want to execute the function while the operation is running). To do that, use the check...Progress method (e.g. for longRunningRecognize method in Speech-To-Text API, the method will be called checkLongRunningRecognizeProgress).

const operation = await checkSampleLongRunningMethodProgress(operationName);
// now check `operation.done`, `operation.metadata`, `operation.result`

Streaming methods

Server streaming

In server streaming methods, the result of the API call is an EventEmitter which will emit data event every time the new response is available.

const stream = client.sampleServerStreamingMethod(request);
stream.on('data', (response) => { /* handle response */ });
stream.on('error', (err) => { /* handle error */ });
stream.on('end', () => { /* API call completed */ });

You can cancel the running API call:

stream.cancel();

You can override the default call options (such as retry settings or timeouts) for the given call by passing an object of type CallOptions in the second parameter:

const stream = client.sampleServerStreamingMethod(request, options);

Bi-directional streaming

Bi-directional streaming calls return a stream that is both readable and writable. It accepts object of the correct request type for its .write() method, and emits responses in its data event.

const stream = client.sampleBidiStreamingMethod();
stream.on('data', (response) => { /* process response */ });
stream.on('error', (err) => { /* handle error */ });
stream.on('end', () => { /* API call completed */ });

stream.write(request1);
stream.write(request2);
stream.end();

You can cancel the running API call:

stream.cancel();

You can override the default call options (such as retry settings or timeouts) for the given call by passing an object of type CallOptions as the only parameter:

const stream = client.sampleBidiStreamingMethod(options);

Client streaming

Client streaming call return a writable stream. The API call is executed and its result is returned using a callback function.

const stream = client.sampleClientStreamingMethod(callback);
stream.write(request1);
stream.write(request2);
stream.end();
// callback(err, response) will be called

You can override the default call options (such as retry settings or timeouts) for the given call by passing an object of type CallOptions in the first parameter:

const stream = client.sampleClientStreamingMethod(options, callback);

Auto-pagination

Some API calls (e.g. the List* calls) return paginated results. For such calls, the client library will perform the page polling for you by default.

The recommended way of working with API that provides paging is to call *Async method that returns an asynchronous iterator that can be iterated using for await loop. E.g. for a method called samplePaginatedMethod the client library provides a method called samplePaginatedMethodAsync which can be used like this:

const iterable = client.samplePaginagedMethodAsync(request);
for await (const response of iterable) {
  // process response
}

The *Async method will fetch new pages as needed.

If you want to receive the content of all the pages at once, just call the method without the Async suffix. The resulting array will contain responses from all the pages, merged in one array. Please note that if your query returns a lot of results, the library will send many single page requests under the hood and those requests will hit your quota.

const [resultArray] = await client.samplePaginatedMethod(request);

If you want to specify the pageSize parameter in the request, it should be done along with disabling auto-pagination. The auto-pagination functionality can be disabled by passing autoPaginate: false as a request option (the second parameter). In this case, the resulting promise will resolve to an array:

const request = {request, pageSize: 50}
const [resultArray, nextPageRequest, rawResponse] =
  await client.samplePaginatedMethod(request, {autoPaginate: false});

Here resultArray contains the responses from the given page, nextPageRequest is the request object that can be used to retrieve the next page of the responses, and rawResponse is the actual response received from the server (before it was converted to an array of responses).

An alternative method of using the paginated API is to use *Stream method that will return an EventEmitter that will emit data event for each response element:

const stream = await client.samplePaginatedMethodStream(request);
stream.on('data', (response) => { /* process response */ });
stream.on('error', (err) => { /* handle error */ });
stream.on('end', () => { /* API call completed */ });

You can override the default call options (such as retry settings or timeouts) for the given call by passing an object of type CallOptions in the second parameter:

const stream = client.sampleServerStreamingMethod(request, options);

Closing the client

To close the connection, call close():

client.close();

After the client instance is closed, it cannot be used anymore.