クイックスタート: .NET 用 Azure Cosmos DB for Apache Cassandra クライアントライブラリ

適用対象: ✅ Apache Cassanda

.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 を作成します。アカウントが作成されたら、キースペースとテーブルリソースを作成します。

Azure CLI
Azure Portal

ターゲットリソースグループがまだない場合は、 az group create コマンドを使用して、サブスクリプションに新しいリソースグループを作成します。
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

az cosmosdb create コマンドを使用して、既定の設定で新しい Azure Cosmos DB for Apache Cassandra アカウントを作成します。

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

az cosmosdb cassandra keyspace createという名前のcosmicworksを使用して、新しいキースペースを作成します。

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

複数行の Bash コマンドを使用して、スキーマを表す新しい JSON オブジェクトを作成します。次に、 az cosmosdb cassandra table create コマンドを使用して、 productsという名前の新しいテーブルを作成します。

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Azure portal (https://portal.azure.com) にサインインします。
グローバル検索バーに 「Azure Cosmos DB 」と入力します。
サービス内で、Azure Cosmos DB を選択します。
Azure Cosmos DB ペインで、[作成] を選択し、[その他] タブで Azure Cosmos DB for Apache Cassandra を選択します。
アカウントの種類として[ 要求ユニット (RU)] データベースアカウント を選択します。

[基本情報] ウィンドウで、次のオプションを構成し、[レビュー + 作成] を選択します。

	価値
ワークロードの種類	学習
サブスクリプション	Azure サブスクリプションを選択する
リソースグループ	新しいリソースグループを作成するか、既存のリソースグループを選択
アカウント名	グローバルに一意の名前を指定
アベイラビリティゾーン	無効にする
場所	サブスクリプションでサポートされている Azure リージョンを選択

ヒント

指定されていないオプションは、既定値のままでかまいません。アカウントの合計スループットを 1 秒あたり 1,000 要求ユニット (RU/秒) に制限するようにアカウントを構成したり、Free レベルを有効にしてコストを最小限に抑えたりすることもできます。

[レビュー + 作成] ウィンドウで、アカウントの検証が正常に完了するまで待ってから、[作成] を選択します。
Portal は自動的に [展開] ウィンドウに移動します。デプロイが完了するまで待ちます。
デプロイが完了したら、[ リソースに移動 ] を選択して、Apache Cassandra 用の新しい API アカウントに移動します。
リソースメニューで、[ データエクスプローラー ] オプションを選択します。
データエクスプローラーで、[ + 新しいテーブル] を選択します。

[ テーブルの追加 ] ダイアログで、次のオプションを構成し、[ OK] を選択します。

	価値
Keyspace	新規作成
キースペース名	`cosmicworks`
テーブル名	`product`
テーブルスキーマ	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

ヒント

指定されていないオプションは、既定値のままでかまいません。

資格情報の取得

ここで、最近作成したアカウントへの接続を作成するために使用するクライアントライブラリのパスワードを取得します。

Azure CLI
Azure Portal

az cosmosdb showを使用して、アカウントの連絡先ポイントとユーザー名を取得します。

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

前のコマンドの出力の contactPoint プロパティと username プロパティの値を記録します。これらのプロパティの値は、このガイドの後半でライブラリを使用してアカウントに接続するために使用する 連絡先ポイント と ユーザー名 です。

az cosmosdb keys listを使用して、アカウントのキーを取得します。

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

前のコマンドの出力の primaryMasterKey プロパティの値を記録します。このプロパティの値は、このガイドの後半でライブラリを使用してアカウントに接続するために使用する パスワード です。

開発環境の準備

次に、新しいプロジェクトとクライアントライブラリを使用して開発環境を構成します。この手順は、このガイドの残りの部分に進む前に必要な最後の前提条件です。

空のディレクトリから開始します。
新しい .NET コンソールアプリケーションを作成する
```
dotnet new console
```
NuGet から CassandraCSharpDriver パッケージを追加します。
```
dotnet add package CassandraCSharpDriver
```
プロジェクトをビルドします。
```
dotnet build
```

オブジェクトモデル

	説明
`Cluster`	クラスターへの接続状態を表します
`ISession`	クラスターへの特定の接続を保持するスレッドセーフエンティティ
`Mapper`	クエリの実行に使用される Cassandra クエリ言語 (CQL) クライアント

クライアントの認証

まず、このガイドで前に収集した資格情報を使用してクライアントを認証します。

統合開発環境 (IDE) で Program.cs ファイルを開きます。
ファイル内に既存のコンテンツがあれば削除します。
ディレクティブを使用して次の名前空間のために追加します。
- System.Security.Authentication
- Cassandra
- Cassandra.Mapping
```
using System.Security.Authentication;
using Cassandra;
using Cassandra.Mapping;
```
このガイドで前に収集した資格情報の文字列定数変数を作成します。変数に username、 password、および contactPointという名前を付けます。
```
const string username = "<username>";
const string password = "<password>";
const string contactPoint = "<contact-point>";
```
トランスポート層セキュリティ (TLS) 1.2 プロトコルを使用し、証明書の失効を確認し、追加のクライアント側の証明書検証を実行していないことを確認するために、新しい SSLoptions オブジェクトを作成します。
```
SSLOptions sslOptions = new(
    sslProtocol: SslProtocols.Tls12,
    checkCertificateRevocation: true,
    remoteCertValidationCallback: (_, _, _, _) => true);
```
fluent Cluster 構文を使用して、新しいCluster.Builder() オブジェクトを構築します。前の手順で作成した資格情報と構成変数を使用します。
```
Cluster cluster = Cluster.Builder()
    .WithCredentials(username, password)
    .WithPort(10350)
    .AddContactPoint(contactPoint)
    .WithSSL(sslOptions)
    .Build();
```
ターゲットキースペース (session) の名前を渡す ConnectAsync メソッドを使用して、新しいcosmicworks変数を作成します。
```
using ISession session = await cluster.ConnectAsync("cosmicworks");
```
最近作成したmapper変数を渡すMapper クラスコンストラクターを使用して、新しいsession変数を作成します。
```
Mapper mapper = new(session);
```

Warnung

このガイドでは、認証を簡略化するために、トランスポート層セキュリティ (TLS) の完全な検証が無効になっています。運用環境のデプロイでは、検証を完全に有効にします。

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

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

このガイドで前に作成したテーブルに対応するフィールドを使用して、 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 では、この型を別のファイルに作成することも、既存のファイルの末尾に作成することもできます。

	タイプ
`Id`	`string`
`Name`	`string`
`Category`	`string`
`Quantity`	`int`
`Price`	`decimal`
`Clearance`	`bool`

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
};

前の手順で作成したInsertAsync変数を渡すproduct メソッドを非同期で呼び出します。
```
await mapper.InsertAsync(product);
```

データの読み取り

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

同じreadQuery フィールドを持つ項目と一致する CQL クエリを使用して、idという名前の新しい文字列変数を作成します。
```
string readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
```
このガイドで前に作成した製品と同じ値を使用して、 id という名前の文字列変数を作成します。
```
string id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
```
SingleAsync<>ジェネリックメソッドを使用して、readQueryに格納されているクエリを実行し、id変数を引数として渡し、出力をProduct型にマップします。この操作の結果を、 Product型の変数に格納します。
```
Product matchedProduct = await mapper.SingleAsync<Product>(readQuery, [id]);
```

データのクエリを実行する

最後に、クエリを使用して、テーブル内の特定のフィルターに一致するすべてのデータを検索します。

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]);
```

foreach ループを使用して、クエリ結果を反復処理します。

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

コードを実行する

アプリケーションディレクトリのターミナルを使用して、新しく作成したアプリケーションを実行します。

dotnet run

リソースをクリーンアップする

アカウントが不要になったら、リソースを削除して Azure サブスクリプションからアカウント を削除 します。

Azure CLI
Azure Portal

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

次のステップ

Azure Cosmos DB for Apache Cassandra の概要

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-07-22