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

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

API 参考文档 | 库源代码 | 包 (NuGet)

先决条件

• Azure 订阅服务

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

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

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

• .NET SDK 9.0 或更高版本

设置

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

创建帐户

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

获取凭据

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

准备开发环境

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

1. 从空目录中开始。

2. 创建新的 .NET 控制台应用程序

   dotnet new console
   

3. 从 NuGet 添加 CassandraCSharpDriver 包。

   dotnet add package CassandraCSharpDriver
   

4. 构建项目。

   dotnet build
   

对象模型

代码示例

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

对客户端进行身份验证

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

1. 在集成开发环境（IDE）中打开 Program.cs 文件。

2. 删除文件中的任何现有内容。

3. 为以下命名空间添加 using 指令：

   • System.Security.Authentication
   • Cassandra
   • Cassandra.Mapping

   using System.Security.Authentication;
   using Cassandra;
   using Cassandra.Mapping;
   

4. 为本指南前面收集的凭据创建字符串常量变量。 为变量 username命名， password以及 contactPoint。

   const string username = "<username>";
   const string password = "<password>";
   const string contactPoint = "<contact-point>";
   

5. 创建一个新 SSLoptions 对象，以确保使用传输层安全性 （TLS） 1.2 协议，检查证书吊销，并且不执行任何额外的客户端认证验证。

   SSLOptions sslOptions = new(
       sslProtocol: SslProtocols.Tls12,
       checkCertificateRevocation: true,
       remoteCertValidationCallback: (_, _, _, _) => true);
   

6. 使用 fluent Cluster.Builder() 语法构造新Cluster对象。 使用在前面的步骤中创建的凭据和配置变量。

   Cluster cluster = Cluster.Builder()
       .WithCredentials(username, password)
       .WithPort(10350)
       .AddContactPoint(contactPoint)
       .WithSSL(sslOptions)
       .Build();
   

7. 使用ConnectAsync传入目标键空间名称的方法创建新session变量（cosmicworks）。

   using ISession session = await cluster.ConnectAsync("cosmicworks");
   

8. 通过使用Mapper类构造函数并传递最近创建的session变量来创建一个新的mapper变量。

   Mapper mapper = new(session);
   

更新插入数据

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

1. 定义一个名为 Product 的新记录类型，其中的字段对应于本指南前面创建的表。

   	类型
   Id	string
   Name	string
   Category	string
   Quantity	int
   Price	decimal
   Clearance	bool

   record Product
   {
       public required string Id { get; init; }
   
       public required string Name { get; init; }
   
       public required string Category { get; init; }
   
       public required int Quantity { get; init; }
   
       public required decimal Price { get; init; }
   
       public required bool Clearance { get; init; }
   }
   

   小窍门

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

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

   Product product = new()
   {
       Id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       Name = "Yamba Surfboard",
       Category = "gear-surf-surfboards",
       Quantity = 12,
       Price = 850.00m,
       Clearance = false
   };
   

3. 异步调用 InsertAsync 方法，并且传入变量 product，该变量是在上一步中创建的。

   await mapper.InsertAsync(product);
   

读取数据

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

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

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

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

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

3. SingleAsync<>使用泛型方法运行存储的readQuery查询，将id变量作为参数传入，并将输出映射到Product类型。 将此作的结果存储在类型的 Product变量中。

   Product matchedProduct = await mapper.SingleAsync<Product>(readQuery, [id]);
   

查询数据

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

1. 创建名为 findQuery 和 category 的字符串变量，包括 CQL 查询和必需参数。

   string findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
   string category = "gear-surf-surfboards";
   

2. 使用两个字符串变量和 FetchAsync<> 泛型方法异步查询多个结果。 将此查询的结果存储在类型为IEnumerable<Product>，名为queriedProducts的变量中。

   IEnumerable<Product> queriedProducts = await mapper.FetchAsync<Product>(findQuery, [category]);
   

3. 使用foreach循环迭代查询结果。

   foreach (Product queriedProduct in queriedProducts)
   {
       // Do something here with each result
   }
   

运行代码

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

dotnet run

清理资源

如果不再需要此帐户，请通过删除资源来从 Azure 订阅中删除该帐户。

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

后续步骤