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

2025-07-22
適用対象: ✅ Apache Cassanda

Python 用 Azure Cosmos DB for Apache Cassandra クライアントライブラリを使用して、非構造化データの格納、管理、クエリを実行します。このガイドの手順に従って、新しいアカウントの作成、Python クライアントライブラリのインストール、アカウントへの接続、一般的な操作の実行、最終的なサンプルデータのクエリを実行します。

API リファレンスドキュメント | ライブラリのソースコード | パッケージ (PyPI)

[前提条件]

Azure サブスクリプション
- Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。

Azure Cloud Shell の Azure CLI の最新バージョン。
- CLI 参照コマンドをローカルで実行する場合は、 az login コマンドを使用して Azure CLI にサインインします。

Python 3.12 以降

セットアップ中

まず、このガイドのアカウントと開発環境を設定します。このセクションでは、アカウントの作成、資格情報の取得、開発環境の準備のプロセスについて説明します。

アカウントを作成する

まず、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"

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

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 プロパティの値を記録します。このプロパティの値は、このガイドの後半でライブラリを使用してアカウントに接続するために使用する パスワード です。

開発環境の準備

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

空のディレクトリから開始します。
Python パッケージインデックス (PyPI) から cassandra-driver パッケージをインポートします。
```
pip install cassandra-driver
```
app.py ファイルを作成します。

オブジェクトモデル

	説明
`Cluster`	クラスターへの特定の接続を表します

クライアントの認証

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

統合開発環境 (IDE) で app.py ファイルを開きます。
cassandra-driver モジュールから次の型をインポートします。
- cassandra.cluster.Cluster
- cassandra.auth.PlainTextAuthProvider
```
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
```
ssl モジュールから次の型をインポートします。
- ssl.PROTOCOL_TLS_CLIENT
- ssl.SSLContext
- ssl.CERT_NONE
```
from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
```
このガイドで前に収集した資格情報の文字列変数を作成します。変数に username、 password、および contactPointという名前を付けます。
```
username = "<username>"
password = "<password>"
contactPoint = "<contact-point>"
```
ssl_contextという名前の新しい変数を作成し、プロトコルをPROTOCOL_TLS_CLIENTに設定し、ホスト名チェックを無効にして、検証モードをCERT_NONEに設定して、SSLContextを構成します。
```
ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
ssl_context.check_hostname = False
ssl_context.verify_mode = CERT_NONE
```
前の手順で指定した資格情報を使用して、新しい PlainTextAuthProvider オブジェクトを作成します。結果を auth_provider という名前の変数に格納します。
```
auth_provider = PlainTextAuthProvider(username=username, password=password)
```
前の手順で作成した資格情報と構成変数を使用して、 Cluster オブジェクトを作成します。結果を cluster という名前の変数に格納します。
```
cluster = Cluster([contactPoint], port=10350, auth_provider=auth_provider, ssl_context=ssl_context)
```

クラスターに接続します。

session = cluster.connect("cosmicworks")

Warnung

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

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

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

新しい行を挿入するための Cassandra クエリ言語 (CQL) クエリを使用して、 insertQuery という名前の新しい文字列変数を作成します。

insertQuery = """
INSERT INTO
    product (id, name, category, quantity, price, clearance)
VALUES
    (%(id)s, %(name)s, %(category)s, %(quantity)s, %(price)s, %(clearance)s)
"""

新しい製品のさまざまなプロパティを持つ新しいオブジェクトを作成し、 paramsという名前の変数に格納します。

params = {
    "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "name": "Yamba Surfboard",
    "category": "gear-surf-surfboards",
    "quantity": 12,
    "price": 850.00,
    "clearance": False
}

execute関数を使用して、指定したパラメーターでクエリを実行します。
```
session.execute(insertQuery, params)
```

データの読み取り

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

同じid フィールドを持つ項目と一致する CQL クエリを使用して、readQueryという名前の新しい文字列変数を作成します。
```
readQuery = "SELECT * FROM product WHERE id = %s LIMIT 1"
```
このガイドで前に作成した製品と同じ値を使用して、 id という名前の文字列変数を作成します。
```
id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
```
execute関数を使用して、id変数を引数として渡readQueryに格納されているクエリを実行します。結果を readResults という名前の変数に格納します。
```
readResults = session.execute(readQuery, (id,))
```
one関数を使用して、期待される単一の結果を取得します。この 1 つの結果を matchedProduct という名前の変数に格納します。
```
matchedProduct = readResults.one()
```

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

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

findQueryおよびcategoryという名前の文字列変数を作成し、CQLクエリと必須パラメーターを設定します。
```
findQuery = "SELECT * FROM product WHERE category = %s ALLOW FILTERING"
category = "gear-surf-surfboards"
```
複数の結果を照会するには、2 つの文字列変数と execute 関数を使用します。このクエリの結果を、 findResultsという名前の変数に格納します。
```
findResults = session.execute(findQuery, (category,))
```
for ループを使用して、クエリ結果を反復処理します。
```
for row in findResults:
    # Do something here with each result
```

コードを実行する

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

python app.py

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

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

Azure CLI
Azure Portal

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

次のステップ

Azure Cosmos DB for Apache Cassandra の概要