快速入门：使用 .NET SDK 和 Azure Cosmos DB 构建 Apache Cassandra 应用

项目
09/14/2024

适用对象： Cassandra

本快速入门介绍如何使用 .NET 和 Azure Cosmos DB Cassandra API，通过克隆 GitHub 中的示例来生成配置文件应用。此外，本快速入门还介绍了如何使用基于 Web 的 Azure 门户创建 Azure Cosmos DB 帐户。

Azure Cosmos DB 是世纪互联提供的多区域分布式多模型数据库服务。可快速创建和查询文档、表、键-值和图形数据库，所有这些都受益于 Azure Cosmos DB 核心的多区域分布和水平缩放功能。

先决条件

如果没有 Azure 订阅，可在开始前创建一个试用帐户。

此外，还需要：

具有 Azure 开发工作负载的最新 Visual Studio。开始时，可以先使用免费的 Visual Studio Community IDE。在安装 Visual Studio 的过程中，请启用“Azure 开发”工作负载。
安装 Git 以克隆示例。

创建数据库帐户

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

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

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

详细了解 API for Cassandra。

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

设置	值	说明
订阅	订阅	选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
资源组	新建然后，输入与帐户名称相同的名称。	选择“新建”。然后输入帐户的新资源组名称。为简单起见，请使用与 Azure Cosmos DB 帐户名称相同的名称。
帐户名	输入唯一的名称	输入标识此 Azure Cosmos DB 帐户的唯一名称。帐户 URI 将是追加到唯一帐户名称的“cassandra.cosmos.azure.cn” 。帐户名称只能使用小写字母、数字及连字符 (-)，必须为 3 到 31 个字符长。
API	Cassandra	API 确定要创建的帐户的类型。 Azure Cosmos DB 提供五种 API：适用于文档数据库的 NoSQL、适用于图形数据库的 Gremlin、适用于文档数据库的 MongoDB、Azure 表和 Cassandra。必须为每种 API 创建单独的帐户。选择“Cassandra”，因为本快速入门将创建使用 API for Cassandra 的表。详细了解 API for Cassandra。
位置	离用户最近的区域	选择用于托管 Azure Cosmos DB 帐户的地理位置。使用离用户最近的位置，使他们能够以最快的速度访问数据。
容量模式	预配吞吐量或无服务器	选择“预配吞吐量”以在预配吞吐量模式下创建帐户。选择“无服务器”以在无服务器模式下创建帐户。
应用 Azure Cosmos DB 免费层折扣	“应用”或“不应用”	使用 Azure Cosmos DB 免费层，你将在帐户中获得每秒前 1000 RU 的免费吞吐量和 25 GB 的免费存储。了解免费层的详细信息。

注意

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

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

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

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

注意

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

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

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

克隆示例应用程序

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

打开命令提示符。创建名为 git-samples 的新文件夹。然后，关闭命令提示符。
```
md "C:\git-samples"
```
打开诸如 git bash 之类的 git 终端窗口，并使用 cd 命令更改为要安装示例应用的新文件夹。
```
cd "C:\git-samples"
```
运行下列命令，克隆示例存储库。此命令在计算机上创建示例应用程序的副本。
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-dotnet-getting-started.git
```
接下来，在 Visual Studio 中打开 CassandraQuickStartSample 解决方案文件。

查看代码

此步骤是可选的。如果有意了解如何通过代码创建数据库资源，可以查看以下代码片段。这些代码片段全部摘自安装在 C:\git-samples\azure-cosmos-db-cassandra-dotnet-getting-started\CassandraQuickStartSample 文件夹中 Program.cs 文件。否则，可以直接跳转到更新连接字符串。

通过连接到 Cassandra 群集终结点初始化会话。 Azure Cosmos DB 上的 API for Cassandra 仅支持 TLSv1.2。

var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
options.SetHostNameResolver((ipAddress) => CassandraContactPoint);
Cluster cluster = Cluster.Builder().WithCredentials(UserName, Password).WithPort(CassandraPort).AddContactPoint(CassandraContactPoint).WithSSL(options).Build();
ISession session = cluster.Connect();

创建新密钥空间。

session.Execute("CREATE KEYSPACE uprofile WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 };");

创建新表。

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

使用有连接到配置文件密钥空间的新会话的 IMapper 对象插入用户实体。
```
mapper.Insert<User>(new User(1, "LyubovK", "Dubai"));
```

通过查询获取所有用户的信息。

foreach (User user in mapper.Fetch<User>("Select * from user"))
{
   Console.WriteLine(user);
}

通过查询获取单个用户的信息。

mapper.FirstOrDefault<User>("Select * from user where user_id = ?", 3);

更新连接字符串

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

在 Azure 门户中，选择“连接字符串”。
使用屏幕右侧的按钮以复制“用户名”值。
在 Visual Studio 中，打开 Program.cs 文件。
粘贴门户中的“用户名”值，并覆盖第 13 行中的 <FILLME>。

Program.cs 的第 13 行现在应该类似

private const string UserName = "cosmos-db-quickstart";
返回到门户，然后复制“密码”值。粘贴门户中的“密码”值，并覆盖第 14 行中的 <FILLME>。

Program.cs 的第 14 行现在应该类似

private const string Password = "2Ggkr662ifxz2Mg...==";
返回到门户，然后复制“联系点”值。粘贴门户中的“联系点”值，并覆盖第 15 行中的 <FILLME>。

Program.cs 的第 15 行现在应该类似

private const string CassandraContactPoint = "cosmos-db-quickstarts.cassandra.cosmosdb.azure.cn"; // DnsName
保存 Program.cs 文件。

运行 .NET 应用

在 Visual Studio 中，选择“工具”>“NuGet 包管理器”>“包管理器控制台” 。
在命令提示符处，使用以下命令安装 .NET 驱动程序的 NuGet 包。
```
Install-Package CassandraCSharpDriver
```
按 CTRL + F5 运行应用程序。应用将显示在控制台窗口中。

按 CTRL + C 停止执行程序并关闭控制台窗口。
在 Azure 门户中，打开数据资源管理器，以查询、修改和处理这些新数据。