クイック スタート: .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. ディレクティブを使用して次の名前空間のために追加します。

   • 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. トランスポート層セキュリティ (TLS) 1.2 プロトコルを使用し、証明書の失効を確認し、追加のクライアント側の証明書検証を実行していないことを確認するために、新しい SSLoptions オブジェクトを作成します。

   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. ターゲット キースペース (cosmicworks) の名前を渡す ConnectAsync メソッドを使用して、新しいsession変数を作成します。

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

8. 最近作成したsession変数を渡すMapper クラス コンストラクターを使用して、新しいmapper変数を作成します。

   Mapper mapper = new(session);
   

データをアップサートする

次に、新しいデータをテーブルにアップサートします。 アップサートにより、同じデータがテーブルに既に存在するかどうかに応じて、データが適切に作成または置換されます。

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. 前の手順で作成したproduct変数を渡すInsertAsync メソッドを非同期で呼び出します。

   await mapper.InsertAsync(product);
   

データの読み取り

次に、テーブルにアップサートされたデータを読み取る。

1. 同じid フィールドを持つ項目と一致する CQL クエリを使用して、readQueryという名前の新しい文字列変数を作成します。

   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. 2 つの文字列変数と FetchAsync<> ジェネリック メソッドを使用して、複数の結果に非同期的にクエリを実行します。 このクエリの結果を、queriedProductsという名前の型IEnumerable<Product>変数に格納します。

   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>"

次のステップ