使用 Cassandra 客户端驱动程序以编程方式访问 Amazon Keyspaces - Amazon Keyspaces(Apache Cassandra 兼容)
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

使用 Cassandra 客户端驱动程序以编程方式访问 Amazon Keyspaces

本部分介绍了如何使用 Java 客户端驱动程序连接 Amazon Keyspaces。

注意

Java 17 和 DataStax Java 驱动程序 4.17 目前仅支持测试版。有关更多信息,请参阅 https://docs.datastax.com/en/developer/java-driver/4.17/upgrade_guide/

要为用户和应用程序提供凭证,以通过编程方式访问 Amazon Keyspaces 资源,您可以执行以下任一操作:

  • 创建与特定 Amazon Identity and Access Management (IAM) 用户关联的服务特定凭证。

  • 为了增强安全性,我们建议为所有 Amazon 服务中使用的 IAM 身份创建 IAM 访问密钥。借助适用于 Cassandra 客户端驱动程序的 Amazon Keyspaces SigV4 身份验证插件,您可以使用 IAM 访问密钥而不是用户名和密码来验证对 Amazon Keyspaces 的调用。有关更多信息,请参阅 如何为 Amazon Keyspaces 创建和配置 Amazon 证书

注意

有关如何在 Spring Boot 中使用 Amazon Keyspaces 的示例,请参阅。https://github.com/aws-samples/amazon-keyspaces-examples/tree/main/java/datastax-v4/spring

开始前的准备工作

要连接到 Amazon Keyspaces,您需要先完成以下任务。

  1. Amazon Keyspaces 要求使用传输层安全性协议 (TLS) 来帮助保护与客户端的连接。

    1. 使用以下命令下载 Starfield 数字证书,并将 sf-class2-root.crt 保存在本地或您的主目录中。

      curl https://certs.secureserver.net/repository/sf-class2-root.crt -O
      注意

      您还可以使用 Amazon 数字证书连接到 Amazon Keyspaces。如果您的客户端成功连接到 Amazon Keyspaces,您可以继续这样做。Starfield 证书为使用旧证书颁发机构的客户端提供了额外的向后兼容性。

    2. 将 Starfield 数字证书转换为 trustStore 文件:

      openssl x509 -outform der -in sf-class2-root.crt -out temp_file.der keytool -import -alias cassandra -keystore cassandra_truststore.jks -file temp_file.der

      在这一步中,您需要为密钥存储创建一个密码,并信任该证书。交互式命令如下所示。

      Enter keystore password: Re-enter new password: Owner: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US Issuer: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US Serial number: 0 Valid from: Tue Jun 29 17:39:16 UTC 2004 until: Thu Jun 29 17:39:16 UTC 2034 Certificate fingerprints: MD5: 32:4A:4B:BB:C8:63:69:9B:BE:74:9A:C6:DD:1D:46:24 SHA1: AD:7E:1C:28:B0:64:EF:8F:60:03:40:20:14:C3:D0:E3:37:0E:B5:8A SHA256: 14:65:FA:20:53:97:B8:76:FA:A6:F0:A9:95:8E:55:90:E4:0F:CC:7F:AA:4F:B7:C2:C8:67:75:21:FB:5F:B6:58 Signature algorithm name: SHA1withRSA Subject Public Key Algorithm: 2048-bit RSA key Version: 3 Extensions: #1: ObjectId: 2.5.29.35 Criticality=false AuthorityKeyIdentifier [ KeyIdentifier [ 0000: BF 5F B7 D1 CE DD 1F 86 F4 5B 55 AC DC D7 10 C2 ._.......[U..... 0010: 0E A9 88 E7 .... ] [OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US] SerialNumber: [ 00] ] #2: ObjectId: 2.5.29.19 Criticality=false BasicConstraints:[ CA:true PathLen:2147483647 ] #3: ObjectId: 2.5.29.14 Criticality=false SubjectKeyIdentifier [ KeyIdentifier [ 0000: BF 5F B7 D1 CE DD 1F 86 F4 5B 55 AC DC D7 10 C2 ._.......[U..... 0010: 0E A9 88 E7 .... ] ] Trust this certificate? [no]: y
  2. 将 trustStore 文件附加到 JVM 参数中:

    -Djavax.net.ssl.trustStore=path_to_file/cassandra_truststore.jks -Djavax.net.ssl.trustStorePassword=my_password

使用适用于 Apache Cassandra 的 DataStax Java 驱动程序使用特定于服务的凭证连接亚马逊密钥空间的tep-by-step 教程

以下 step-by-step 教程将引导您使用特定于服务的凭证使用适用于 Cassandra 的 Java 驱动程序连接到 Amazon Keyspaces。具体而言,你将使用适用于 Apache Cassandr DataStax a 的 Java 驱动程序的 4.0 版本。

步骤 1:先决条件

要学习本教程,你需要生成特定于服务的凭证,并将适用于 Apache Cassandra 的 DataStax Java 驱动程序添加到你的 Java 项目中。

步骤 2:配置驱动程序

您可以通过为应用程序创建配置文件来指定 DataStax Java Cassandra 驱动程序的设置。此配置文件会覆盖默认设置,并告诉驱动程序使用端口 9142 连接到 Amazon Keyspaces 服务端点。有关可用服务端点的列表,请参阅 Amazon Keyspaces 的服务端点

创建配置文件,并将该文件保存在应用程序的资源文件夹中,例如 src/main/resources/application.conf。打开 application.conf,然后添加以下配置设置。

  1. 身份验证提供程序:使用 类创建身份验证提供程序。ServiceUserNameServicePassword应与您按照中的步骤生成服务专用凭证时获得的用户名和密码相匹配。生成服务特定凭证

    注意

    您可以使用适用于 Apache Cassandra 的 DataStax Java 驱动程序的身份验证插件,而不是在驱动程序配置文件中对凭据进行硬编码,从而使用短期证书。要了解更多信息,请按照使用适用于 Apache Cassandra 的 4.x DataStax Java 驱动程序和 Sigv4 身份验证插件连接亚马逊密钥空间的tep-by-step 教程中的说明进行操作。

  2. 本地数据中心:将 local-datacenter 的值设置为要连接的区域。例如,如果应用程序要连接到 cassandra.us-east-2.amazonaws.com,则将本地数据中心设置为 us-east-2。有关所有可用的 Amazon Web Services 区域,请参阅 Amazon Keyspaces 的服务端点。设置 slow-replica-avoidance = false 以针对更少的节点进行负载均衡。

  3. SSL/TLS — EngineFactory 通过在配置文件中添加一段来初始化 SSL,其中有一行用于指定类别。class = DefaultSslEngineFactory提供 trustStore 文件的路径和您之前创建的密码。Amazon Keyspaces 不支持对等设备的 hostname-validation,因此请将此选项设为 false。

datastax-java-driver { basic.contact-points = [ "cassandra.us-east-2.amazonaws.com:9142"] advanced.auth-provider{ class = PlainTextAuthProvider username = "ServiceUserName" password = "ServicePassword" } basic.load-balancing-policy { local-datacenter = "us-east-2" slow-replica-avoidance = false } advanced.ssl-engine-factory { class = DefaultSslEngineFactory truststore-path = "./src/main/resources/cassandra_truststore.jks" truststore-password = "my_password" hostname-validation = false } }
注意

除了在配置文件中添加 trustStore 的路径外,您还可以直接在应用程序代码中添加 trustStore 的路径,或者在 JVM 参数中添加 trustStore 的路径。

步骤 3:运行示例应用程序

本代码示例展示了一个简单的命令行应用程序,它使用我们之前创建的配置文件创建了一个连接到 Amazon Keyspaces 的连接池。它通过运行一个简单的查询来确认连接已建立。

package <your package>; // add the following imports to your project import com.datastax.oss.driver.api.core.CqlSession; import com.datastax.oss.driver.api.core.config.DriverConfigLoader; import com.datastax.oss.driver.api.core.cql.ResultSet; import com.datastax.oss.driver.api.core.cql.Row; public class App { public static void main( String[] args ) { //Use DriverConfigLoader to load your configuration file DriverConfigLoader loader = DriverConfigLoader.fromClasspath("application.conf"); try (CqlSession session = CqlSession.builder() .withConfigLoader(loader) .build()) { ResultSet rs = session.execute("select * from system_schema.keyspaces"); Row row = rs.one(); System.out.println(row.getString("keyspace_name")); } } }
注意

使用 try 代码块建立连接,以确保连接始终处于关闭状态。如果不使用 try 代码块,请记得关闭连接,以免泄漏资源。

使用适用于 Apache Cassandra 的 4.x DataStax Java 驱动程序和 Sigv4 身份验证插件连接亚马逊密钥空间的tep-by-step 教程

以下部分介绍如何使用适用于 Apache Cassandra 的开源 4.x DataStax Java 驱动程序的 SigV4 身份验证插件来访问亚马逊密钥空间(适用于 Apache Cassandra)。该插件可从GitHub存储库中获得。

使用 SigV4 身份验证插件,您可以在连接 Amazon Keyspaces 时为用户或角色使用 IAM 凭据。该插件不需要用户名和密码,而是使用访问密钥签署 API 请求。有关更多信息,请参阅 如何为 Amazon Keyspaces 创建和配置 Amazon 证书

步骤 1:先决条件

要学习本教程,您需要完成以下任务。

  • 请按照如何为 Amazon Keyspaces 创建和配置 Amazon 证书中的步骤为 IAM 用户或角色创建凭证(如果您尚未创建)。本教程假设访问密钥将存储为环境变量。有关更多信息,请参阅 如何管理 IAM 用户的访问密钥

  • 将 Apache Cassandra 的 DataStax Java 驱动程序添加到你的 Java 项目中。确保您使用的驱动程序版本支持 Apache Cassandra 3.11.2。有关更多信息,请参阅 A pache Cassandra 的 DataStax Java 驱动程序文档。

  • 将身份验证插件添加到您的应用程序。该身份验证插件支持 Apache Cassandr DataStax a 的 Java 驱动程序 4.x 版本。如果您使用的是 Apache Maven 或可以使用 Maven 依赖关系的构建系统,请将以下依赖关系添加到您的 pom.xml 文件中。

    重要

    将插件版本替换为GitHub 存储库中显示的最新版本。

    <dependency> <groupId>software.aws.mcs</groupId> <artifactId>aws-sigv4-auth-cassandra-java-driver-plugin</artifactId> <version>4.0.9</version> </dependency>

步骤 2:配置驱动程序

您可以通过为应用程序创建配置文件来指定 DataStax Java Cassandra 驱动程序的设置。此配置文件会覆盖默认设置,并告诉驱动程序使用端口 9142 连接到 Amazon Keyspaces 服务端点。有关可用服务端点的列表,请参阅 Amazon Keyspaces 的服务端点

创建配置文件,并将该文件保存在应用程序的资源文件夹中,例如 src/main/resources/application.conf。打开 application.conf,然后添加以下配置设置。

  1. 身份验证提供程序:将 advanced.auth-provider.class设置为 software.aws.mcs.auth.SigV4AuthProvider 的新实例。Sigv4 AuthProvider 是插件提供的用于执行 Sigv4 身份验证的身份验证处理程序。

  2. 本地数据中心:将 local-datacenter 的值设置为要连接的区域。例如,如果应用程序要连接到 cassandra.us-east-2.amazonaws.com,则将本地数据中心设置为 us-east-2。有关所有可用的 Amazon Web Services 区域,请参阅 Amazon Keyspaces 的服务端点。设置 slow-replica-avoidance = false 以针对更少的节点进行负载均衡。

  3. SSL/TLS — EngineFactory 通过在配置文件中添加一段来初始化 SSL,其中有一行用于指定类别。class = DefaultSslEngineFactory提供 trustStore 文件的路径和您之前创建的密码。Amazon Keyspaces 不支持对等设备的 hostname-validation,因此请将此选项设为 false。

datastax-java-driver { basic.contact-points = ["cassandra.us-east-2.amazonaws.com:9142"] basic.load-balancing-policy { class = DefaultLoadBalancingPolicy local-datacenter = us-east-2 slow-replica-avoidance = false } advanced { auth-provider = { class = software.aws.mcs.auth.SigV4AuthProvider aws-region = us-east-2 } ssl-engine-factory { class = DefaultSslEngineFactory truststore-path = "./src/main/resources/cassandra_truststore.jks" truststore-password = "my_password" hostname-validation = false } } }
注意

除了在配置文件中添加 trustStore 的路径外,您还可以直接在应用程序代码中添加 trustStore 的路径,或者在 JVM 参数中添加 trustStore 的路径。

步骤 3:运行应用程序

本代码示例展示了一个简单的命令行应用程序,它使用我们之前创建的配置文件创建了一个连接到 Amazon Keyspaces 的连接池。它通过运行一个简单的查询来确认连接已建立。

package <your package>; // add the following imports to your project import com.datastax.oss.driver.api.core.CqlSession; import com.datastax.oss.driver.api.core.config.DriverConfigLoader; import com.datastax.oss.driver.api.core.cql.ResultSet; import com.datastax.oss.driver.api.core.cql.Row; public class App { public static void main( String[] args ) { //Use DriverConfigLoader to load your configuration file DriverConfigLoader loader = DriverConfigLoader.fromClasspath("application.conf"); try (CqlSession session = CqlSession.builder() .withConfigLoader(loader) .build()) { ResultSet rs = session.execute("select * from system_schema.keyspaces"); Row row = rs.one(); System.out.println(row.getString("keyspace_name")); } } }
注意

使用 try 代码块建立连接,以确保连接始终处于关闭状态。如果不使用 try 代码块,请记得关闭连接,以免泄漏资源。

使用适用于 Apache Cassandra 的 3.x DataStax Java 驱动程序和 SigV4 身份验证插件连接亚马逊密钥空间

以下部分介绍如何使用适用于 Apache Cassandra 的 3.x 开源 DataStax Java 驱动程序的 Sigv4 身份验证插件来访问亚马逊密钥空间。该插件可从GitHub 存储库中获得。

使用 SigV4 身份验证插件,您可以在连接 Amazon Keyspaces 时为用户和角色使用 IAM 凭据。该插件不需要用户名和密码,而是使用访问密钥签署 API 请求。有关更多信息,请参阅 如何为 Amazon Keyspaces 创建和配置 Amazon 证书

步骤 1:先决条件

要运行此代码示例,您首先需要完成以下任务。

  • 按照如何为 Amazon Keyspaces 创建和配置 Amazon 证书中的步骤为 IAM 用户或角色创建凭证。本教程假设访问密钥将存储为环境变量。有关更多信息,请参阅 如何管理 IAM 用户的访问密钥

  • 请按照开始前的准备工作中的步骤下载 Starfield 数字证书,将其转换为 trustStore 文件,然后将 trustStore 文件附加到应用程序的 JVM 参数中。

  • 将 Apache Cassandra 的 DataStax Java 驱动程序添加到你的 Java 项目中。确保您使用的驱动程序版本支持 Apache Cassandra 3.11.2。有关更多信息,请参阅 A pache Cassandra 的 DataStax Java 驱动程序文档。

  • 将身份验证插件添加到您的应用程序。该身份验证插件支持 Apache Cassandr DataStax a 的 Java 驱动程序版本 3.x。如果您使用的是 Apache Maven 或可以使用 Maven 依赖关系的构建系统,请将以下依赖关系添加到您的 pom.xml 文件中。将插件版本替换为GitHub 存储库中显示的最新版本。

    <dependency> <groupId>software.aws.mcs</groupId> <artifactId>aws-sigv4-auth-cassandra-java-driver-plugin_3</artifactId> <version>3.0.3</version> </dependency>

步骤 2:运行应用程序

本代码示例展示了一个简单的命令行应用程序,它创建了一个连接到 Amazon Keyspaces 的连接池。它通过运行一个简单的查询来确认连接已建立。

package <your package>; // add the following imports to your project import software.aws.mcs.auth.SigV4AuthProvider; import com.datastax.driver.core.Cluster; import com.datastax.driver.core.ResultSet; import com.datastax.driver.core.Row; import com.datastax.driver.core.Session; public class App { public static void main( String[] args ) { String endPoint = "cassandra.us-east-2.amazonaws.com"; int portNumber = 9142; Session session = Cluster.builder() .addContactPoint(endPoint) .withPort(portNumber) .withAuthProvider(new SigV4AuthProvider("us-east-2")) .withSSL() .build() .connect(); ResultSet rs = session.execute("select * from system_schema.keyspaces"); Row row = rs.one(); System.out.println(row.getString("keyspace_name")); } }

使用说明:

有关可用端点的列表,请参阅Amazon Keyspaces 的服务端点

请参阅以下存储库,获取实用的 Java 驱动程序策略、示例,以及结合使用 Java 驱动程序和 Amazon Keyspaces 的最佳实践,:https://github.com/aws-samples/amazon-keyspaces-java-driver-helpers