快速入门：使用 CQLSH 和 Azure Cosmos DB 生成 Cassandra 应用

2025-08-13

适用对象：卡珊德拉

在本快速入门中，你将创建一个 Azure Cosmos DB for Apache Cassandra 帐户，并使用 CQLSH 创建 Cassandra 数据库和容器。 Azure Cosmos DB 是一种多模型数据库服务，可让你通过多区域分布和水平缩放功能快速创建和查询文档、表、键/值和图形数据库。

先决条件

具有活动订阅的 Azure 帐户。创建试用版订阅。

创建数据库帐户

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

在 Azure 门户菜单或主页中，选择“ 创建资源”。
在“新建”页面中搜索“Azure Cosmos DB”，然后选择它。
在“Azure Cosmos DB”页上，选择“创建”。
在 API 页上的 Cassandra 部分下，选择“ 创建”。

API 确定要创建的帐户的类型。 Azure Cosmos DB 提供五种 API：适用于文档数据库的 NoSQL、适用于图形数据库的 Gremlin、适用于文档数据库的 MongoDB、Azure 表和 Cassandra。必须为每种 API 创建单独的帐户。

选择 Cassandra ，因为在本教程中，你将创建一个适用于 Cassandra API 的表。

若要了解有关 Cassandra API 的详细信息，请参阅什么是适用于 Apache Cassandra 的 Azure Cosmos DB？。

在 “创建 Azure Cosmos DB 帐户 ”页上，输入新 Azure Cosmos DB 帐户的基本设置。

设置	值	说明
订阅	你的订阅。	选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
资源组	新建。然后输入与帐户名称相同的名称。	选择“新建”。然后输入帐户的新资源组名称。为简单起见，请使用与 Azure Cosmos DB 帐户名称相同的名称。
帐户名	输入唯一名称。	输入标识此 Azure Cosmos DB 帐户的唯一名称。你的帐户 URI (`cassandra.cosmos.azure.com`)，已追加到唯一帐户名称。帐户名称只能使用小写字母、数字和连字符（-），并且长度必须介于 3 到 31 个字符之间。
位置	离用户最近的区域。	选择用于托管 Azure Cosmos DB 帐户的地理位置。使用离用户最近的位置，使他们能够以最快的速度访问数据。
容量模式	预配的吞吐量或无服务器。	选择 “预配吞吐量 ”以在预配吞吐量模式下创建帐户。选择 “无服务器 ”以在无服务器模式下创建帐户。
应用 Azure Cosmos DB 免费层折扣	应用或不适用。	使用 Azure Cosmos DB 免费层，可以在帐户中免费获取前 1,000 RU/秒和 25 GB 的存储空间。详细了解免费层。

注意

每个 Azure 订阅最多可拥有一个免费的 Azure Cosmos DB 帐户。创建帐户时必须选择加入。如果您未看到应用免费层的折扣选项，则是因为订阅中的另一个帐户已经启用了免费层。

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

在“ 全局分发 ”选项卡上，配置以下详细信息。使用本教程的默认值。

设置	值	说明
异地冗余	禁用	通过将你的区域与另一区域进行配对来启用或禁用帐户的全局分发。稍后可以将更多区域添加到帐户。
多区域写入	禁用	利用多区域写入功能，可以利用全球数据库和容器的预配吞吐量。
可用性区域	禁用	可用性区域是 Azure 区域中的独立位置。每个区域由一个或多个数据中心组成，这些数据中心配置了独立电源、冷却和网络。

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

应用免费层折扣
异地冗余
多区域写入

（可选）可以在以下选项卡上配置其他详细信息：
- 网络：配置来自虚拟网络的访问。
- 备份策略：配置定期或连续备份策略。
- 加密：使用服务管理的密钥或客户管理的密钥。
- 标记：标记是名称/值对，可用于对资源进行分类，并通过将同一标记应用于多个资源和资源组来查看合并计费。
选择“查看 + 创建”。
检查帐户设置，然后选择“创建”。创建帐户需要几分钟时间。等待门户页显示“你的部署已完成”消息。
选择“转到资源”，转到 Azure Cosmos DB 帐户页。

安装独立的 CQLSH 工具

请参阅 CQL shell，了解如何启动独立的 cqlsh 工具。

更新连接字符串

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

在 Azure 门户的 Azure Cosmos DB 帐户中，选择“连接字符串”。
使用屏幕右侧按钮复制用户名和密码值。

在终端中，设置 SSL 变量：

# Export the SSL variables:
export SSL_VERSION=TLSv1_2
export SSL_VALIDATE=false

连接到 Azure Cosmos DB for Apache Cassandra：

将用户名和密码值粘贴到命令中。

cqlsh <USERNAME>.cassandra.cosmos.azure.cn 10350 -u <USERNAME> -p <PASSWORD> --ssl --protocol-version=4

用于创建和运行应用的 CQL 命令

创建密钥空间

CREATE KEYSPACE IF NOT EXISTS uprofile 
WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 };

创建表

CREATE TABLE IF NOT EXISTS uprofile.user (user_id int PRIMARY KEY, user_name text, user_bcity text);

在用户表中插入行

INSERT INTO  uprofile.user (user_id, user_name, user_bcity) VALUES (101,'johnjoe','Beijing')

你也可使用 COPY 命令插入数据。

COPY uprofile.user(user_id, user_name, user_bcity) FROM '/path to file/fileName.csv' 
WITH DELIMITER = ',' ;

查询用户表

SELECT * FROM uprofile.users;

在 Azure 门户中，打开数据资源管理器，以查询、修改和处理这些新数据。在数据资源管理器中查看数据 - Azure Cosmos DB

在 Azure 门户中查看 SLA

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

若要查看指标和 SLA，请执行以下操作：

请在 Azure Cosmos DB 帐户的导航菜单中选择“指标”。
选择一个选项卡，如“延迟”，然后选择右侧的时间范围。比较图表上的“实际”和“SLA”线。
查看其他选项卡上的指标。

清理资源

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

在 Azure 门户的“搜索”栏中，搜索并选择“资源组”。
从列表中选择为本快速入门创建的资源组。
在资源组“概览”页上，选择“删除资源组”。
在下一窗口中输入要删除的资源组的名称，然后选择“删除”。

后续步骤

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

将 Cassandra 数据导入 Azure Cosmos DB

共用方式為