本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
使用卡桑德拉 Java 客戶端驅動程序以編程方式訪問 Amazon Keyspaces
本節介紹如何使用 Java 客戶端驅動程序連接到 Amazon Keyspaces。
注意
Java 17 和 DataStax Java 驅動程式 4.17 目前僅提供測試版支援。如需詳細資訊，請參閱 https://docs.datastax.com/en/developer/java-driver/4.17/upgrade_guide/
若要提供使用者和應用程式以程式設計方式存取 Amazon Keyspace 資源的登入資料，您可以執行下列其中一項作業：
-
建立與特定 AWS Identity and Access Management (IAM) 使用者相關聯的服務特定登入資料。
-
為了增強安全性，我們建議為跨所有 AWS 服務使用的 IAM 身分建立 IAM 存取金鑰。適用於 Cassandra 客戶端驅動程序的 Amazon 密 Keyspaces Sigv4 身份驗證插件使您可以使用 IAM 訪問密鑰而不是用戶名和密碼對 Amazon 密鑰 Keyspaces 進行身份驗證呼叫。如需詳細資訊，請參閱 如何創建和配置 Amazon Keyspaces 的 AWS 憑據。
注意
有關如何在 Spring Boot 中使用 Amazon Keyspaces 的示例，請參閱https://github.com/aws-samples/amazon-keyspaces-examples/tree/main/java/datastax-v4/spring
主題
開始之前
若要連接到 Amazon Keyspaces，您必須先完成下列任務，才能開始。
Amazon Keyspaces 需要使用傳輸層安全性 (TLS) 來協助保護與用戶端的連線安全。
使用下列指令下載 Starfield 數位憑證，並儲存在
sf-class2-root.crt本機或主目錄中。curl https://certs.secureserver.net/repository/sf-class2-root.crt -O注意
您也可以使用 Amazon 數位憑證連線到 Amazon Keyspaces，如果您的用戶端成功連線至 Amazon Keyspaces，則可以繼續這麼做。Starfield 憑證為使用舊版憑證授權單位的用戶端提供額外的向後相容性。
將星空數位憑證轉換為信任庫檔案。
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
-
在 JVM 引數中附加信任庫檔案：
-Djavax.net.ssl.trustStore=path_to_file/cassandra_truststore.jks -Djavax.net.ssl.trustStorePassword=my_password
S tep-by-step 教程連接到 Amazon Keyspaces 使用 DataStax Java 驅動程序的 Apache 卡桑德拉使用特定於服務的憑據
以下 step-by-step 教程將引導您使用特定服務的憑據使用 Cassandra 的 Java 驅動程序連接到 Amazon Keyspaces。具體來說，你會使用 4.0 版本的 DataStax Java 驅動程序的阿帕奇卡桑德拉。
步驟 1：事前準備
要遵循本教程，您需要生成特定於服務的憑據，並為 Apache 卡桑德拉 DataStax Java 驅動程序添加到您的 Java 項目。
透過完成中的步驟，為您的 Amazon Keyspaces IAM 使用者產生服務特定的登入資料。產生服務特定認證如果您偏好使用 IAM 存取金鑰進行身份驗證，請參閱S tep-by-step 教程連接到 Amazon Keyspaces 使用 4.x DataStax Java 驅動程序阿帕奇卡桑德拉和 SIGv4 身份驗證插件。
阿帕奇卡桑德拉 DataStax Java 驅動程序添加到您的 Java 項目。確保您使用的是支持阿帕奇卡桑德拉 3.11.2 的驅動程序版本。有關更多信息，請參閱 DataStax Java 驅動程序阿帕奇卡桑德拉
文檔。
步驟 2：設定驅動程式
您可以通過為您的應用程序創建一個配置文件指定 DataStax Java 卡桑德拉驅動程序的設置。此組態檔案會覆寫預設設定，並告知驅動程式使用連接埠 9142 連接至 Amazon Keyspaces 服務端點。如需可用服務端點的清單，請參閱亞馬遜 Keyspaces 的服務端點。
建立組態檔案並將檔案儲存在應用程式的資源資料夾中，例如。src/main/resources/application.conf開啟application.conf並新增下列組態設定。
驗證提供者 — 使用
PlainTextAuthProvider類別建立驗證提供者。ServiceUser名稱和ServicePassword應符合您依照中產生服務特定認證的步驟產生服務特定認證時所取得的使用者名稱和密碼。注意
您可以通過使用 Apache Cassandra 的 DataStax Java 驅動程序的身份驗證插件來使用短期憑據，而不是在驅動程序配置文件中硬編碼憑據。若要深入了解，請遵循的指示S tep-by-step 教程連接到 Amazon Keyspaces 使用 4.x DataStax Java 驅動程序阿帕奇卡桑德拉和 SIGv4 身份驗證插件。
本機資料中心 — 將值設定
local-datacenter為您要連線的區域。例如，如果應用程式正在連線到cassandra.us-east-2.amazonaws.com，則將本機資料中心設定為us-east-2。對於所有可用的 AWS 區域，請參閱亞馬遜 Keyspaces 的服務端點。設定slow-replica-avoidance = false為針對較少節點的負載平衡。SSL/TLS — EngineFactory 透過使用單行指定類別的組態檔案中新增區段來初始化 SSL。
class = DefaultSslEngineFactory提供信任庫檔案的路徑和您先前建立的密碼。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 } }
注意
您也可以直接在應用程式程式碼中新增信任存放區路徑，或者將信任存放區的路徑新增至 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塊，請記住關閉連接以避免資源洩漏。
S tep-by-step 教程連接到 Amazon Keyspaces 使用 4.x DataStax Java 驅動程序阿帕奇卡桑德拉和 SIGv4 身份驗證插件
下一節介紹如何使用 Sigv4 身份驗證插件的開源 4.x DataStax Java 驅動程序阿帕奇卡桑德拉訪問 Amazon Keyspaces（阿帕奇卡桑德拉）。該插件可從GitHub存儲庫
Sigv4 身份驗證外掛程式可讓您在連線至 Amazon Keyspaces 時，為使用者或角色使用 IAM 登入資料。此插件不需要用戶名和密碼，而是使用訪問密鑰簽署 API 請求。如需詳細資訊，請參閱 如何創建和配置 Amazon Keyspaces 的 AWS 憑據。
步驟 1：事前準備
若要遵循本教學課程，您需要完成下列工作。
如果您尚未這麼做，請依照中的步驟為您的 IAM 使用者或角色建立登入資料如何創建和配置 Amazon Keyspaces 的 AWS 憑據。本教學課程假設存取金鑰儲存為環境變數。如需詳細資訊，請參閱 如何管理 IAM 使用者的存取金鑰。
阿帕奇卡桑德拉 DataStax Java 驅動程序添加到您的 Java 項目。確保您使用的是支持阿帕奇卡桑德拉 3.11.2 的驅動程序版本。有關更多信息，請參閱 DataStax Java 驅動程序阿帕奇卡桑德拉
文檔。 將身份驗證插件添加到您的應用程序。身份驗證插件支持的 DataStax Java 驅動程序的 Apache 卡桑德拉 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 卡桑德拉驅動程序的設置。此組態檔案會覆寫預設設定，並告知驅動程式使用連接埠 9142 連接至 Amazon Keyspaces 服務端點。如需可用服務端點的清單，請參閱亞馬遜 Keyspaces 的服務端點。
建立組態檔案並將檔案儲存在應用程式的資源資料夾中，例如。src/main/resources/application.conf開啟application.conf並新增下列組態設定。
驗證提供者 —
advanced.auth-provider.class將設定為的新執行個體software.aws.mcs.auth.SigV4AuthProvider。Sigv4 AuthProvider 是由插件提供用於執行 Sigv4 身份驗證的身份驗證處理程序。本機資料中心 — 將值設定
local-datacenter為您要連線的區域。例如，如果應用程式正在連線到cassandra.us-east-2.amazonaws.com，則將本機資料中心設定為us-east-2。對於所有可用的 AWS 區域，請參閱亞馬遜 Keyspaces 的服務端點。設定slow-replica-avoidance = false為對所有可用節點的負載平衡。Idempotence — 設置應用程序的默認值，以
true配置驅動程序始終重試失敗的讀/寫/idempotence準備/執行請求。這是分散式應用程式的最佳作法，可透過重試失敗的要求來協助處理暫時性失敗。SSL/TLS — EngineFactory 透過使用單行指定類別的組態檔案中新增區段來初始化 SSL。
class = DefaultSslEngineFactory提供信任庫檔案的路徑和您先前建立的密碼。Amazon Keyspaces 不支持hostname-validation對等，因此將此選項設置為 false。連線 — 透過設定，為每個端點建立至少 3 個本機連線
local.size = 3。這是幫助您的應用程序處理開銷和流量突發的最佳實踐。如需如何根據預期的流量模式計算應用程式每個端點需要多少本機連線的詳細資訊，請參閱如何在 Amazon Keyspaces 中配置連接。重試政策 — Amazon Keyspaces 重試政策
AmazonKeyspacesExponentialRetryPolicy是 Cassandra 驅動程DefaultRetryPolicy序附帶的替代方案。兩個重試原則之間的主要差異在於，您可以設定重試嘗試的次數，AmazonKeyspacesExponentialRetryPolicy以符合您的需求。依預設，的重試次數設定AmazonKeyspacesExponentialRetryPolicy為 3。此外，Amazon Keyspaces 重試政策不會返回通NoHostAvailableException用。相反，Amazon Keyspaces 重試政策會傳回服務傳回的原始例外狀況。如需實作重試政策的更多程式碼範例，請參閱 Github 上的 Amazon Keyspaces 重試政策。 準備好的陳述式 — 設
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 } } }
注意
您也可以直接在應用程式程式碼中新增信任存放區路徑，或者將信任存放區的路徑新增至 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塊，請記住關閉連接以避免資源洩漏。
Connect 到 Amazon Keyspaces 使用 3.x DataStax Java 驅動程序阿帕奇卡桑德拉和 Sigv4 身份驗證插件
以下部分介紹如何使用 Sigv4 身份驗證插件為阿帕奇卡桑德拉的 3.x 開源 DataStax Java 驅動程序訪問 Amazon Keyspaces。該插件可從GitHub 存儲庫
Sigv4 身份驗證外掛程式可讓您在連線至 Amazon Keyspaces 時，針對使用者和角色使用 IAM 登入資料。此插件不需要用戶名和密碼，而是使用訪問密鑰簽署 API 請求。如需詳細資訊，請參閱 如何創建和配置 Amazon Keyspaces 的 AWS 憑據。
步驟 1：事前準備
若要執行此程式碼範例，您必須先完成下列工作。
按照中的步驟為您的 IAM 使用者或角色建立登入資料如何創建和配置 Amazon Keyspaces 的 AWS 憑據。本教學課程假設存取金鑰儲存為環境變數。如需詳細資訊，請參閱 如何管理 IAM 使用者的存取金鑰。
請依照下列步驟下載 Starfield 數位憑證、將其轉換為信任庫檔案，並將 JVM 引數中的 TrustStore 檔案附加至您的應用程式。開始之前
阿帕奇卡桑德拉 DataStax Java 驅動程序添加到您的 Java 項目。確保您使用的是支持阿帕奇卡桑德拉 3.11.2 的驅動程序版本。有關更多信息，請參閱 DataStax Java 驅動程序阿帕奇卡桑德拉
文檔。 將身份驗證插件添加到您的應用程序。身份驗證插件支持的 DataStax Java 驅動程序的 Apache 卡桑德拉 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")); } }
使用注意事項：
如需可用端點的清單，請參閱亞馬遜 Keyspaces 的服務端點。
如需將 Java 驅動程式與 Amazon Keyspaces 搭配使用時的有用 Java 驅動程式政策、範例和最佳實務，請參閱下列儲存庫：https://github.com/aws-samples/amazon-keyspaces-java-driver-helpers
