使用 Java 客户端库连接到 Spanner Omni

Java 版 Spanner 客户端库与 Spanner Omni 的搭配使用方式与 Spanner 相同。本文档介绍了如何通过配置 Java 客户端库来建立与 Spanner Omni 的安全连接。您可以在创建数据库管理客户端或数据库客户端时设置客户端选项，以建立这些连接。

Java 客户端库支持纯文本、TLS、带凭据的 TLS 和 mTLS 连接。

如需了解详情，请参阅 Spanner 文档中的 Spanner 使用入门 (Java)。

准备工作

如需开始使用 Java 版 Spanner Omni，请使用 Java 客户端库 6.119.0 版或更高版本。

如果您使用的是不带物料清单 (BOM) 的 Maven，请将以下内容添加到 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 通信使用双向 TLS (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);