この記事では、Python SDK を使用して Azure Cosmos DB for NoSQL に接続する方法について説明します。 接続後、データベース、コンテナー、項目に対して操作を実行します。
Package (PyPi) | API リファレンス | ライブラリのソース コード | フィードバックを送信する
Prerequisites
- アクティブなサブスクリプションを持つ Azure アカウント。 アカウントを無料で作成する方法については、こちらを参照してください。
- NoSQL 用の Azure Cosmos DB アカウント。 NoSQL 用 API のアカウントを作成する方法については、こちらを参照してください。
- Python 3.7 以降。
- Azure コマンド ライン インターフェイス (CLI) または Azure PowerShell。
プロジェクトを設定する
Python コード用の環境を作成します。
仮想環境を使用して、システムに影響を与えることがないように、Python パッケージを別個にインストールします。
仮想環境に Azure Cosmos DB for NoSQL Python SDK をインストールします。
pip install azure-cosmos
Python アプリケーションを作成する
お使いの環境内で、新しい app.py ファイルを作成し、次のコードを追加します。
import json
import os
import sys
import uuid
from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey
上記のコードは、記事の残りの部分で使用されるモジュールをインポートします。
Azure Cosmos DB for NoSQL に接続する
Azure Cosmos DB API for NoSQL に接続するには、CosmosClient クラスのインスタンスを作成します。 このクラスは、データベースに対するすべての操作を実行するための開始点です。
Microsoft Entra を使用して NoSQL 用 API アカウントに接続するには、セキュリティ プリンシパルを使用します。 プリンシパルの正確な種類は、アプリケーション コードをホストする場所によって異なります。 次の表は、クイック リファレンス ガイドです。
| アプリケーションの実行場所 | セキュリティ プリンシパル |
|---|---|
| ローカル コンピューター (開発とテスト) | ユーザー ID またはサービス プリンシパル ID |
| Azure | マネージド ID |
| Azureの外部にあるサーバーまたはクライアント | サービス プリンシパル |
Azure.Identityをインポート
azure-identity パッケージは、すべての Azure SDK ライブラリで共有されるコア認証機能を提供します。
お使いの環境に azure-identity パッケージをインポートします。
pip install azure-identity
既定の資格情報の実装を使用して CosmosClient を作成する
ローカル コンピューターでテストしている場合、またはマネージド ID をサポートする Azure サービスでアプリケーションを実行している場合は、DefaultAzureCredential インスタンスを作成して OAuth トークンを取得します。
app.py ファイルで次の操作を行います。
アカウントのエンドポイントを取得し、それを環境変数
COSMOS_ENDPOINTとして設定します。DefaultAzureCredential をインポートし、そのインスタンスを作成します。
ENDPOINT と credential をパラメーターとして指定して、CosmosClient クラスの新しいインスタンスを作成します。
from azure.identity import DefaultAzureCredential
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
credential = DefaultAzureCredential()
client = CosmosClient(ENDPOINT, credential)
Important
DefaultAzureCredential を有効にするための適切なロールを追加する方法の詳細については、Microsoft Entra ID を使用した Azure Cosmos DB アカウントのロールベースのアクセス制御の構成に関するページを参照してください。 特に、ロールの作成とそれらのプリンシパル ID への割り当てに関するセクションを参照してください。
アプリケーションをビルドする
アプリケーションをビルドすると、コードは主に次の 4 種類のリソースと対話します。
noSQL 用 API アカウント。これは、Azure Cosmos DB データの一意の最上位レベルの名前空間です。
アカウント内のコンテナーを整理するデータベース。
データベース内の個々の項目のセットを含むコンテナー。
コンテナー内の JSON ドキュメントを表す項目。
次の図は、これらのリソース間の関係を示しています。
上部に Azure Cosmos DB アカウントを示す階層図。 アカウントには 2 つの子データベース ノードがあります。 一方のデータベース ノードには、2 つの子コンテナー ノードが含まれています。 もう一方のデータベース ノードには、1 つの子コンテナー ノードが含まれています。 その 1 つのコンテナー ノードには、3 つの子項目ノードがあります。
リソースの種類は、1 つ以上の関連付けられた Python クラスによって表されます。 次の一覧は、同期プログラミングの最も一般的なクラスを示しています。 (azure.cosmos.aio 名前空間の下には、非同期プログラミング用の同様のクラスがあります)。
| クラス | Description |
|---|---|
CosmosClient |
このクラスは、Azure Cosmos DB サービスのクライアント側の論理表現を提供します。 クライアント オブジェクトは、サービスに対する要求を構成して実行します。 |
DatabaseProxy |
サービスにまだ存在する (または存在していない) 可能性があるデータベースへのインターフェイス。 このクラスは、直接インスタンス化しないでください。 代わりに、CosmosClient get_database_client メソッドを使用します。 |
ContainerProxy |
特定の Cosmos DB コンテナーと対話するためのインターフェイス。 このクラスは、直接インスタンス化しないでください。 代わりに、DatabaseProxy get_container_client メソッドを使用して既存のコンテナーを取得するか、create_container メソッドを使用して新しいコンテナーを作成します。 |
次のガイドでは、これらの各クラスを使用してアプリケーションをビルドする方法を示しています。
| ガイド | Description |
|---|---|
| データベースの作成 | データベースを作成します。 |
| コンテナーの作成 | コンテナーを作成します。 |