使用 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 证书

注意

有关如何在 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. 在JVM参数中附上该 trustStore 文件:

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

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

以下 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. 身份验证提供商-使用PlainTextAuthProvider类创建身份验证提供程序。 ServiceUserNameServicePassword应与您按照中的步骤生成服务专用凭证时获得的用户名和密码相匹配。创建用于通过编程方式访问 Amazon Keyspaces 的服务特定凭证。

    注意

    您可以使用适用于 Apache Cassandra 的 DataStax Java 驱动程序的身份验证插件,而不是在驱动程序配置文件中对凭据进行硬编码,从而使用短期证书。要了解更多信息,请按照Step-by-step 使用适用于 Apache Cassandra 的 4.x DataStax Java 驱动程序和 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— SSLEngineFactory 通过在配置文件中添加一节来初始化,用一行指定该类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 路径,也可以将路径 trustStore 添加到JVM参数中。

步骤 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 代码块,请记得关闭连接,以免泄漏资源。

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

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

Sigv4 身份验证插件允许您在连接到 Amazon Keyspaces 时使用用户或角色的IAM凭证。此插件不需要用户名和密码,而是使用访问密钥对API请求进行签名。有关更多信息,请参阅 为 Amazon Keyspaces 创建和配置 Amazon 证书

步骤 1:先决条件

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

  • 如果您尚未这样做,请按照中的步骤为您的IAM用户或角色创建证书为 Amazon Keyspaces 创建和配置 Amazon 证书。本教程假设访问密钥将存储为环境变量。有关更多信息,请参阅 存储用于通过编程方式进行访问的访问密钥

  • 将 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. Idempotence — 将应用程序的默认值设置为,将驱动程序配置idempotencetrue为始终重试失败的请求。read/write/prepare/execute这是适用于分布式应用程序的最佳实践,可通过重试失败的请求来协助处理暂时性故障。

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

  5. 连接 - 通过设置 local.size = 3 为每个端点创建至少 3 个本地连接。这是一种最佳实践,方便您的应用程序应对开销和流量暴增。有关如何根据预期流量模式计算应用程序每个端点需要多少本地连接的更多信息,请参阅如何在 Amazon Keyspaces 中配置连接

  6. 重试策略 - 实施 Amazon Keyspaces 重试策略 AmazonKeyspacesExponentialRetryPolicy,而非 Cassandra 驱动程序附带的 DefaultRetryPolicy。这样您就可以根据自己的需求配置 AmazonKeyspacesExponentialRetryPolicy 的重试次数。默认情况下,AmazonKeyspacesExponentialRetryPolicy 的重试次数设置为 3。有关更多信息,请参阅 如何在 Amazon Keyspaces 中配置连接的重试策略

  7. 准备的语句 - 将 prepare-on-all-nodes 设置为 false 以优化网络使用情况。

datastax-java-driver { basic { contact-points = [ "cassandra.us-east-2.amazonaws.com:9142"] request { timeout = 2 seconds consistency = LOCAL_QUORUM page-size = 1024 default-idempotence = true } load-balancing-policy { local-datacenter = "us-east-2" class = DefaultLoadBalancingPolicy 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 } connection { connect-timeout = 5 seconds max-requests-per-connection = 512 pool { local.size = 3 } } retry-policy { class = com.aws.ssa.keyspaces.retry.AmazonKeyspacesExponentialRetryPolicy max-attempts = 3 min-wait = 10 mills max-wait = 100 mills } prepared-statements { prepare-on-all-nodes = false } } }
注意

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

步骤 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:先决条件

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

  • 按照中的步骤为您的IAM用户或角色创建证书为 Amazon Keyspaces 创建和配置 Amazon 证书。本教程假设访问密钥将存储为环境变量。有关更多信息,请参阅 存储用于通过编程方式进行访问的访问密钥

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

  • 将 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