快速入门：适用于 Java 的 Azure Cosmos DB for Apache Cassandra 客户端库

开始使用适用于 Java 的 Azure Cosmos DB for Apache Cassandra 客户端库，以存储、管理和查询非结构化数据。 按照本指南中的步骤创建新帐户、安装 Java 客户端库、连接到帐户、执行常见作以及查询最终示例数据。

API 参考文档 | 库源代码 | 包 （Maven）

先决条件

• Azure 订阅服务

  • 如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

• Azure Cloud Shell 中最新版本的 Azure CLI。

  • 如果想要在本地运行 CLI 引用命令，请使用 az login 该命令登录到 Azure CLI。

• Java 21 或更高版本

设置

首先，为本指南设置帐户和开发环境。 本部分将指导你完成创建帐户、获取其凭据以及准备开发环境的过程。

创建帐户

首先，创建用于 Apache Cassandra 帐户的 API。 创建帐户后，创建密钥空间和表资源。

获取凭据

现在，获取用于创建与最近创建的帐户的连接的客户端库的密码。

准备开发环境

然后，使用新项目和客户端库配置开发环境。 在转到本指南的其余部分之前，此步骤是最后一个必需的先决条件。

1. 从空目录中开始。

2. 使用 Maven 生成新的 Java 控制台项目。

   mvn archetype:generate -DgroupId=quickstart -DartifactId=console -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
   

3. 从 Maven 导入java-driver-core包。 将此部分添加到 pom.xml 文件。

   <dependency>
     <groupId>org.apache.cassandra</groupId>
     <artifactId>java-driver-core</artifactId>
     <version>[4.,)</version>
   </dependency>
   

4. 打开 /console/src/main/java/quickstart/App.java 文件。

5. 观察现有的 Java 应用程序样板代码。

   package quickstart;
   
   /**
    * Hello world!
    *
    */
   public class App 
   {
       public static void main( String[] args )
       {
           System.out.println( "Hello World!" );
       }
   }
   

6. 从模板中删除注释和控制台输出。 此代码块是本指南其余部分的起点。

   package quickstart;
   
   public class App 
   {
       public static void main(String[] args)
       {
       }
   }
   

7. 将java.security.NoSuchAlgorithmException命名空间导入。

   import java.security.NoSuchAlgorithmException;
   

8. 请更新main方法签名以指示它可能会抛出NoSuchAlgorithmException异常。

   public static void main(String[] args) throws NoSuchAlgorithmException
   {    
   }
   

   重要

   本指南中的其余步骤假定您在main方法中添加代码。

9. 构建项目。

   mvn compile
   

对象模型

代码示例

• 对客户端进行身份验证
• 更新插入数据
• 读取数据
• 查询数据

对客户端进行身份验证

首先，使用本指南前面收集的凭据对客户端进行身份验证。

1. 在集成开发环境（IDE）中打开 /console/src/main/java/quickstart/App.java 文件。

2. 导入以下类型：

   • java.net.InetSocketAddress
   • javax.net.ssl.SSLContext
   • com.datastax.oss.driver.api.core.CqlIdentifier
   • com.datastax.oss.driver.api.core.CqlSession
   • com.datastax.oss.driver.api.core.cql.BoundStatement
   • com.datastax.oss.driver.api.core.cql.PreparedStatement
   • com.datastax.oss.driver.api.core.cql.ResultSet
   • com.datastax.oss.driver.api.core.cql.Row

   import java.net.InetSocketAddress;    
   
   import javax.net.ssl.SSLContext;
   
   import com.datastax.oss.driver.api.core.CqlIdentifier;
   import com.datastax.oss.driver.api.core.CqlSession;
   import com.datastax.oss.driver.api.core.cql.BoundStatement;
   import com.datastax.oss.driver.api.core.cql.PreparedStatement;
   import com.datastax.oss.driver.api.core.cql.ResultSet;
   import com.datastax.oss.driver.api.core.cql.Row;
   

3. 为本指南前面收集的凭据创建字符串变量。 为变量 username命名， password以及 contactPoint。 此外，请创建一个名为本地数据中心的字符串变量 region 。

   String username = "<username>";
   String password = "<password>";
   String contactPoint = "<contact-point>";
   

4. 为创建 Azure Cosmos DB for Apache Cassandra 帐户的区域创建另一个字符串变量。 将此变量 region命名为 。

   String region = "<region>";
   

5. 创建一个 SSLContext 对象，以确保使用传输层安全性 （TLS） 协议。

   SSLContext sslContext = SSLContext.getDefault();
   

6. 使用前面步骤中创建的凭据和配置变量创建新 CqlSession 对象。 设置联系人点、本地数据中心、身份验证凭据、密钥空间和传输层安全性（TLS）上下文。

   CqlSession session = CqlSession.builder()
       .addContactPoint(new InetSocketAddress(contactPoint, 10350))
       .withLocalDatacenter(region)
       .withAuthCredentials(username, password)
       .withKeyspace(CqlIdentifier.fromCql("cosmicworks"))
       .withSslContext(sslContext)
       .build();
   

更新插入数据

接下来，将新数据插入或更新到表中。 Upserting 可确保根据表中是否已存在相同的数据，适当地创建或替换数据。

1. 定义一个名为 Product 的新类，其字段与本指南前面创建的表相对应。

   class Product {
       public String id;
       public String name;
       public String category;
       public int quantity;
       public boolean clearance;
   
       public Product(String id, String name, String category, int quantity, boolean clearance) {
           this.id = id;
           this.name = name;
           this.category = category;
           this.quantity = quantity;
           this.clearance = clearance;
       }
   
       @Override
       public String toString() {
           return String.format("Product{id='%s', name='%s', category='%s', quantity=%d, clearance=%b}",
                   id, name, category, quantity, clearance);
       }
   }
   

   小窍门

   在 Java 中，可以在另一个文件中创建此类型，也可以在现有文件的末尾创建它。

2. 创建一个Product类型的新对象。 将对象存储在名为 .. 的 product变量中。

   Product product = new Product(
       "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       "Yamba Surfboard",
       "gear-surf-surfboards",
       12,
       false
   );
   

3. 创建一个名为 Cassandra 查询语言（CQL）查询的新字符串变量 insertQuery ，用于插入新行。

   String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
   

4. 准备插入语句并将产品属性绑定为参数。

   PreparedStatement insertStmt = session.prepare(insertQuery);
   BoundStatement boundInsert = insertStmt.bind(
       product.id,
       product.name,
       product.category,
       product.quantity,
       product.clearance
   );
   

5. 通过执行绑定语句来更新插入产品。

   session.execute(boundInsert);
   

读取数据

然后，读取以前插入到表中的数据。

1. 创建一个名为 CQL 查询的新字符串变量 readQuery ，该查询与具有相同 id 字段的项匹配。

   String readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
   

2. 创建与本指南前面创建的产品相同的值的字符串变量 id 。

   String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
   

3. 准备语句并将产品的 id 字段绑定为参数。

   PreparedStatement readStmt = session.prepare(readQuery);
   BoundStatement boundRead = readStmt.bind(id);
   

4. 执行绑定语句，并将结果存储在名为 readResult 的变量中。

   ResultSet readResult = session.execute(boundRead);
   

5. 从结果集中检索第一行，如果找到，则将其映射到对象 Product 。

   Row row = readResult.one();
   Product matchedProduct = new Product(
       row.getString("id"),
       row.getString("name"),
       row.getString("category"),
       row.getInt("quantity"),
       row.getBoolean("clearance")
   );
   

查询数据

现在，使用查询查找与表中特定筛选器匹配的所有数据。

1. 创建一个名为 CQL 查询的新字符串变量 findQuery ，该查询与具有相同 category 字段的项匹配。

   String findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
   

2. 创建与本指南前面创建的产品相同的值的字符串变量 id 。

   String category = "gear-surf-surfboards";
   

3. 准备语句并将产品类别绑定为参数。

   PreparedStatement findStmt = session.prepare(findQuery);
   BoundStatement boundFind = findStmt.bind(category);
   

4. 执行绑定语句，并将结果存储在名为findResults的变量中。

   ResultSet results = session.execute(boundFind);
   

5. 循环访问查询结果并将每一行映射到对象 Product 。

   for (Row result : results) {
       Product queriedProduct = new Product(
           result.getString("id"),
           result.getString("name"),
           result.getString("category"),
           result.getInt("quantity"),
           result.getBoolean("clearance")
       );
       // Do something here with each result
   }
   

关闭会话

在 Java 中，完成任何查询和作后，需要关闭会话。

session.close();

运行代码

使用应用程序目录中的终端运行新创建的应用程序。

mvn compile
mvn exec:java -Dexec.mainClass="quickstart.App"

清理资源

现在，获取用于创建与最近创建的帐户的连接的客户端库的密码。

后续步骤