Configure client library endpoints

Each Google Cloud API service is accessed through a service-specific endpoint.

For example, the Java-Speech and Java-Translate client libraries have default endpoints of https://speech.googleapis.com:443 and https://translate.googleapis.com:443 respectively.

The Cloud Client Libraries for Java automatically determine the correct service endpoint during client initialization. If no custom endpoint is configured, the libraries use the service's default endpoint.

Anatomy of an endpoint

Using the Java-Speech endpoint as an example, the following table details the sections that make up the endpoint:

These are the default values of all Cloud Client Libraries for Java endpoints, apart from the service name. The service name does not have a default value because every Google Cloud service has a different value.

When to configure a custom endpoint

There are certain use cases to replace the default endpoint, such as:

• The service offers regional endpoints. The default endpoint does not consider regional variants.
• You are not working in production. For example, you are testing locally with an emulator without configuring TLS.

Only modify the endpoint configuration if necessary. When using a custom endpoint, you must include the port number (for example, example.com:443). The client libraries do not automatically append a default port like 443 to custom endpoints, unlike they do for default service endpoints.

Configure a custom endpoint

You can set the endpoint from the service-specific ClientSettings in Cloud Client Libraries for Java.

The following example uses Java-KMS:

1. Set the endpoint in the ClientSettings.Builder and create the ClientSettings:

   // Replace with your desired endpoint
   String endpoint = "customEndpoint.com:443";
   KeyManagementServiceSettings keyManagementServiceSettings =
    KeyManagementServiceSettings.newBuilder()
       .setEndpoint(endpoint)
       .build();
   

2. Initiate the client with ClientSettings:

   try (KeyManagementServiceClient keyManagementServiceClient =
     KeyManagementServiceClient.create(keyManagementServiceSettings)) {
     ...
   }
   

   The endpoint resolves to customEndpoint.com:443.

   The client uses the endpoint from the first of the following sources that provides one:

   1. The endpoint set programmatically via ClientSettings.Builder.setEndpoint().
   2. The service's default endpoint, such as https://{serviceName}.googleapis.com:443.

The following snippet shows how to determine the client's resolved endpoint:

// The client's settings class contains a getter for the endpoint
keyManagementServiceClient.getSettings().getEndpoint();