生成 Java 应用以管理 Azure Cosmos DB Cassandra API 数据(v3 驱动程序)

适用于: Cassandra API

在本快速入门中,你将创建一个 Azure Cosmos DB Cassandra API 帐户,并使用从 GitHub 克隆的 Cassandra Java 应用通过 Java 的 v3.x Apache Cassandra 驱动程序创建一个 Cassandra 数据库和一个容器。 Azure Cosmos DB 是一种多模型数据库服务,可让你通过多区域分布和水平缩放功能快速创建和查询文档、表、键/值和图数据库。

先决条件

备注

这是一个简单的快速入门,使用适用于 Java 的开源 Apache Cassandra 驱动程序的版本 3。 在大多数情况下,你应该能够将现有的 Apache Cassandra 相关 Java 应用程序连接到 Azure Cosmos DB Cassandra API,而无需对现有代码进行任何更改。 但是,我们建议添加自定义 Java 扩展,其中包括了自定义重试和负载均衡策略,以便获得更好的整体体验。 这是为了在 Azure Cosmos DB 中分别处理速率限制和应用程序级别的故障转移。 可在此处找到实现该扩展的综合性示例。

创建数据库帐户

在创建文档数据库之前,需通过 Azure Cosmos DB 创建 Cassandra 帐户。

  1. 在 Azure 门户菜单或主页中,选择“创建资源” 。

  2. 在“新建”页面中搜索“Azure Cosmos DB”,然后选择它。

  3. 在“Azure Cosmos DB”页上,选择“创建”。

  4. 在“创建 Azure Cosmos DB 帐户”页中,输入新 Azure Cosmos 帐户的基本设置。

    设置 Value 说明
    订阅 你的订阅 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 新建

    然后,输入与帐户名称相同的名称。
    选择“新建”。 然后输入帐户的新资源组名称。 为简单起见,请使用与 Azure Cosmos 帐户名称相同的名称。
    帐户名 输入唯一的名称 输入标识此 Azure Cosmos DB 帐户的唯一名称。 帐户 URI 将是追加到唯一帐户名称的“cassandra.cosmos.azure.cn” 。

    帐户名称只能使用小写字母、数字及连字符 (-),必须为 3 到 31 个字符长。
    API Cassandra API 确定要创建的帐户的类型。 Azure Cosmos DB 提供五种 API:Core(SQL)(适用于文档数据库)、Gremlin(适用于图数据库)、MongoDB(适用于文档数据库)、Azure 表和 Cassandra。 必须为每种 API 创建单独的帐户。

    选择“Cassandra” ,因为本快速入门将创建使用 Cassandra API 的表。

    详细了解 Cassandra API
    位置 离用户最近的区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。
    容量模式 预配吞吐量或无服务器 选择“预配吞吐量”以在预配吞吐量模式下创建帐户。 选择“无服务器”以在无服务器模式下创建帐户。
    应用免费层折扣 “应用”或“不应用” 使用 Azure Cosmos DB 免费层,你将在帐户中获得每秒前 1000 RU 的免费吞吐量和 25 GB 的免费存储。 了解免费层的详细信息。

    备注

    每个 Azure 订阅最多可以有一个免费层 Azure Cosmos DB 帐户,并且你必须在创建帐户时选择加入使用。 如果看不到用于应用免费层折扣的选项,这意味着订阅中的另一个帐户已启用免费层。

    Azure Cosmos DB Cassandra API 的“新建帐户”页面

  5. 在“全局分发”选项卡中,配置以下详细信息。 对于本快速入门,可以保留默认值:

    设置 Value 说明
    异地冗余 禁用 通过将你的区域与某个配对区域进行配对来启用或禁用帐户的多区域分发。 稍后可以将更多区域添加到帐户。
    多区域写入 禁用 借助多区域写入功能,可以利用全中国的数据库和容器的预配吞吐量。

    备注

    如果选择“无服务器”作为“容量模式”,则以下选项不可用 :

    • 应用免费层折扣
    • 异地冗余
    • 多区域写入
  6. (可选)可以在以下选项卡中配置其他详细信息:

    • 网络 - 配置 来自虚拟网络的访问

    • 备份策略 - 配置 定期备份策略。

    • 加密 - 使用服务管理的密钥或 客户管理的密钥

    • 标记 - 标记是名称/值对,通过将相同的标记应用到多个资源和资源组,可以对资源进行分类并查看合并的账单。

  7. 选择“查看 + 创建”。

  8. 检查帐户设置,然后选择“创建”。 创建帐户需要几分钟时间。 等待门户页显示“你的部署已完成”消息。

    Azure 门户“通知”窗格

  9. 选择“转到资源”,转到 Azure Cosmos DB 帐户页。

克隆示例应用程序

现在,让我们转到如何使用代码上来。 从 GitHub 克隆 Cassandra 应用,设置连接字符串,并运行应用。 会看到以编程方式处理数据是多么容易。

  1. 打开命令提示符。 创建名为 git-samples 的新文件夹。 然后,关闭命令提示符。

    md "C:\git-samples"
    
  2. 打开诸如 git bash 之类的 git 终端窗口,并使用 cd 命令更改为要安装示例应用的新文件夹。

    cd "C:\git-samples"
    
  3. 运行下列命令,克隆示例存储库。 此命令在计算机上创建示例应用程序的副本。

    git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-java-getting-started.git
    

查看代码

此步骤是可选的。 如果有意了解如何通过代码创建数据库资源,可以查看以下代码片段。 否则,可以直接跳转到更新连接字符串。 这些代码片段全部摘自 src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java 文件。

  • 已设置 Cassandra 主机、端口、用户名、密码和 TLS/SSL 选项。 连接字符串信息来自 Azure 门户中的连接字符串页。

    cluster = Cluster.builder().addContactPoint(cassandraHost).withPort(cassandraPort).withCredentials(cassandraUsername, cassandraPassword).withSSL(sslOptions).build();
    
  • cluster 连接到 Azure Cosmos DB Cassandra API 并返回可供访问的会话。

    return cluster.connect();
    

    以下代码片段来自 src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java 文件。

  • 创建新密钥空间。

    public void createKeyspace() {
        final String query = "CREATE KEYSPACE IF NOT EXISTS uprofile WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '3' } ";
        session.execute(query);
        LOGGER.info("Created keyspace 'uprofile'");
    }
    
  • 创建新表。

    public void createTable() {
        final String query = "CREATE TABLE IF NOT EXISTS uprofile.user (user_id int PRIMARY KEY, user_name text, user_bcity text)";
        session.execute(query);
        LOGGER.info("Created table 'user'");
    }
    
  • 使用准备的语句对象插入用户实体。

    public PreparedStatement prepareInsertStatement() {
        final String insertStatement = "INSERT INTO  uprofile.user (user_id, user_name , user_bcity) VALUES (?,?,?)";
        return session.prepare(insertStatement);
    }
    
    public void insertUser(PreparedStatement statement, int id, String name, String city) {
        BoundStatement boundStatement = new BoundStatement(statement);
        session.execute(boundStatement.bind(id, name, city));
    }
    
  • 通过查询获取所有用户信息。

    public void selectAllUsers() {
        final String query = "SELECT * FROM uprofile.user";
        List<Row> rows = session.execute(query).all();
    
        for (Row row : rows) {
            LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
        }
    }
    
  • 通过查询获取单个用户的信息。

    public void selectUser(int id) {
        final String query = "SELECT * FROM uprofile.user where user_id = 3";
        Row row = session.execute(query).one();
    
        LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
    }
    

更新连接字符串

现在返回到 Azure 门户,获取连接字符串信息,并将其复制到应用。 连接字符串详细信息使应用能够与托管数据库进行通信。

  1. Azure 门户的 Azure Cosmos DB 帐户中,选择“连接字符串”。

    在 Azure 门户的“连接字符串”页面中查看并复制用户名

  2. 使用屏幕右侧的 按钮复制“CONTACT POINT”值。

  3. 打开 C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources 文件夹中的 config.properties 文件。

  4. 粘贴门户中的“联系点”值,并覆盖第 2 行中的 <Cassandra endpoint host>

    config.properties 的第 2 行现在应类似于

    cassandra_host=cosmos-db-quickstart.cassandra.cosmos.azure.cn

  5. 返回到门户,并复制“用户名”值。 粘贴门户中的“用户名”值,并覆盖第 4 行中的 <cassandra endpoint username>

    config.properties 的第 4 行现在应类似于

    cassandra_username=cosmos-db-quickstart

  6. 返回到门户,并复制“密码”值。 粘贴门户中的“密码”值,并覆盖第 5 行中的 <cassandra endpoint password>

    config.properties 的第 5 行现在应类似于

    cassandra_password=2Ggkr662ifxz2Mg...==

  7. 在第 6 行中,如果需要使用特定的 TLS/SSL 证书,请将 <SSL key store file location> 替换为该 TLS/SSL 证书的位置。 如果未提供值,则会使用安装在 <JAVA_HOME>/jre/lib/security/cacerts 中的 JDK 证书。

  8. 如果将第 6 行更改为使用特定的 TLS/SSL 证书,请将第 7 行更新为对该证书使用密码。

  9. 保存 config.properties 文件。

运行 Java 应用

  1. 在 git 终端窗口中,通过 cd 转至 azure-cosmosdb-cassandra-java-getting-started 文件夹。

    cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started"
    
  2. 在 git 终端窗口中,使用以下命令生成 cosmosdb-cassandra-examples.jar 文件。

    mvn clean install
    
  3. 在 git 终端窗口中,运行以下命令以启动 Java 应用程序。

    java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile
    

    终端窗口会显示通知,指出密钥空间和表已创建。 然后,它会选择并返回表中的所有用户,然后显示输出,接着按 ID 选择行并显示值。

    按 Ctrl+C 停止执行程序并关闭控制台窗口。

  4. 在 Azure 门户中,打开数据资源管理器,以查询、修改和处理这些新数据。

    在数据资源管理器中查看数据 - Azure Cosmos DB

在 Azure 门户中查看 SLA

Azure 门户监视 Cosmos DB 帐户吞吐量、存储、可用性、延迟和一致性。 与 Azure Cosmos DB 服务级别协议 (SLA) 关联的指标的图表显示与实际性能相比的 SLA 值。 此套指标使得监视 SLA 十分透明。

若要查看指标和 SLA,请执行以下操作:

  1. 在 Cosmos DB 帐户的导航菜单中选择“指标”。

  2. 选择一个选项卡,如“延迟”,然后选择右侧的时间范围。 比较图表上的“实际”和“SLA”线。

    Azure Cosmos DB 指标套件

  3. 查看其他选项卡上的指标。

清理资源

执行完应用和 Azure Cosmos DB 帐户的操作以后,可以删除所创建的 Azure 资源,以免产生更多费用。 若要删除资源,请执行以下操作:

  1. 在 Azure 门户的“搜索”栏中,搜索并选择“资源组” 。

  2. 从列表中选择为本快速入门创建的资源组。

    选择要删除的资源组

  3. 在资源组“概览”页上,选择“删除资源组” 。

    删除资源组

  4. 在下一窗口中输入要删除的资源组的名称,然后选择“删除” 。

后续步骤

本快速入门介绍了如何使用 Cassandra API 创建 Azure Cosmos DB 帐户,以及如何运行用于创建 Cassandra 数据库和容器的 Cassandra Java 应用。 现在可以将其他数据导入 Azure Cosmos DB 帐户了。