使用 Java 用戶端程式庫連線至 Spanner Omni

Spanner 的 Java 用戶端程式庫與 Spanner Omni 的運作方式，與其與 Spanner 的運作方式相同。本文說明如何設定 Java 用戶端程式庫，建立與 Spanner Omni 的安全連線。建立資料庫管理用戶端或資料庫用戶端時，您可以設定用戶端選項來建立這些連線。

Java 用戶端程式庫支援純文字、TLS、含憑證的 TLS，以及 mTLS 連線。

詳情請參閱 Spanner 說明文件中的「開始使用 Java 版 Spanner」。

事前準備

如要在 Java 中開始使用 Spanner Omni，請使用 Java 用戶端程式庫 6.119.0 以上版本。

如果您使用 Maven 而不使用物料清單 (BOM)，請將下列指令新增至 pom.xml 檔案依附元件：

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner</artifactId>
  <version>6.119.0</version>
</dependency>

安全性設定

Spanner Java 用戶端程式庫支援四種安全性設定，可定義用戶端與 Spanner Omni 之間的通訊加密和驗證方式。下表說明各項設定：

安全性設定 說明
純文字 通訊內容未加密。
TLS 通訊內容會使用傳輸層安全標準 (TLS) 加密。如要使用這項設定，您必須將 Spanner Omni CA 憑證新增至 Java 信任儲存庫，詳情請參閱「設定 Java 信任儲存庫」。
使用憑證的 TLS 通訊內容會使用 TLS 加密，並透過使用者名稱和密碼進行驗證。
mTLS 通訊會使用相互傳輸層安全標準 (mTLS) 加密。這項設定需要您提供用戶端憑證和用戶端私鑰。

設定 Java 信任儲存區

對於所有加密連線類型 (TLS、TLS (含憑證) 和 mTLS)，您必須將 Spanner Omni CA 憑證新增至 Java 信任儲存區，用戶端才能驗證伺服器的憑證。

如要將 CA 憑證新增至預設 Java 信任儲存庫，請執行下列指令：

sudo keytool -import -trustcacerts -file ~/.spanner/certs/ca.crt -alias spanner-ca -keystore $JAVA_HOME/lib/security/cacerts

或者，您可以在執行應用程式時指定自訂信任儲存區：

  1. 為維持與使用標準憑證授權單位 (CA) 的其他服務相容，請複製預設的 Java 信任儲存區：

    cp $JAVA_HOME/lib/security/cacerts /PATH_TO_CUSTOM_CACERTS

  2. 將 CA 憑證匯入自訂信任儲存庫：

    keytool -import -trustcacerts -file ~/.spanner/certs/ca.crt -alias spanner-ca -keystore /PATH_TO_CUSTOM_CACERTS

  3. 執行應用程式時，請使用 JVM 系統屬性指定自訂信任儲存區：

    java -Djavax.net.ssl.trustStore=/PATH_TO_CUSTOM_CACERTS -Djavax.net.ssl.trustStorePassword=changeit app

設定 SpannerOptions 物件

設定 SpannerOptions 物件來建立 DatabaseClient 或 DatabaseAdminClient 時，請使用 setHost()，然後使用 setType(SpannerOptions.InstanceType.OMNI) 指定 Spanner Omni 端點。

以下範例說明如何為每個支援的安全性設定，設定 SpannerOptions 物件：

純文字

如要建立純文字連線，請使用 http:// 指定 Spanner Omni 端點，並使用 usePlainText() 方法：

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("http://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .usePlainText()
        .build();
Spanner spanner = options.getService();

TLS

為 TLS 連線設定 SpannerOptions 物件時，不需要指定使用者名稱和密碼憑證。使用 https:// 指定 Spanner Omni 端點：

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .build();
Spanner spanner = options.getService();

使用憑證的 TLS

如要透過使用者名稱和密碼驗證建立 TLS 連線，請使用 https:// 指定 Spanner Omni 端點，並使用 login() 方法指定使用者名稱和密碼：

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .login("USERNAME", "PASSWORD".toCharArray())
        .build();
Spanner spanner = options.getService();

mTLS

如要使用 mTLS 連線，請使用下列指令，將 Spanner Omni 產生的金鑰轉換為符合 Java 的格式：

openssl pkcs8 -topk8 -in ~/.spanner/certs/client.key -out ~/.spanner/certs/java-client.key -nocrypt

以下範例說明如何設定 SpannerOptions 物件，以使用用戶端憑證：

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .useClientCert(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_CERT_KEY")
        .build();
Spanner spanner = options.getService();

取得資料庫用戶端

設定 SpannerOptions 物件後，即可取得資料庫用戶端。由於 Spanner Omni 不會使用 Google Cloud 雲端專案或執行個體 ID，因此建立 DatabaseId 時，請為專案 ID 和執行個體 ID 指定 default：

DatabaseId dbId = DatabaseId.of("default", "default", "DATABASE_ID");
DatabaseClient client = spanner.getDatabaseClient(dbId);