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

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

使用 Cassandra Java 客户端驱动程序以编程方式访问亚马逊Keyspaces

本节说明了如何使用 Java 客户端驱动程序连接到 Amazon Keyspaces。要向用户和应用程序提供凭证以编程方式访问 Amazon Keyspaces 资源的凭证,您可以执行以下任一操作:

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

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

注意

有关如何在 Spring Boot 中使用亚马逊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 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 Cassandr DataStax a 的 Java 驱动程序使用特定服务的证书连接到 Amazon Keyspaces 的tep-by-step 教程

以下 step-by-step 教程将引导您使用特定服务的凭证使用适用于 Cassandra 的 Java 驱动程序连接到 Amazon Keyspaces。具体而言,你将使用 Apache Cassandra 的 DataStax 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类创建身份验证提供商。ServiceUserName并且ServicePassword应与您在按照中的步骤生成服务特定凭证时获得的用户名和密码相匹配生成特定服务证书

    注意

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

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

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

步骤 1:先决条件

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

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

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

  • 将身份验证插件添加到您的应用程序。身份验证插件支持 Apache Cassandra 的 DataStax 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.5</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。Sigv4AuthProvider 是插件提供的用于执行 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 身份验证插件Connect 亚马逊 Keyspaces

下一节介绍如何使用适用于 Apache Cassandra 的 3.x 开源 DataStax Java 驱动程序的 Sigv4 身份验证插件来访问 Amazon Keyspaces。该插件可从GitHub 存储库获得。

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

步骤 1:先决条件

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

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

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

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

  • 将身份验证插件添加到您的应用程序。身份验证插件支持 Apache Cassandra 的 DataStax 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 服务端点

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