Python を使用して Azure Cosmos DB for NoSQL の使用を開始する
適用対象: NoSQL
この記事では、Python SDK を使用して Azure Cosmos DB for NoSQL に接続する方法を示します。 接続すると、データベース、コンテナー、および項目に対する操作を実行できます。
パッケージ (PyPi) | サンプル | API リファレンス | ライブラリ ソース コード | フィードバックを送る
前提条件
- アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
- Azure Cosmos DB for NoSQL アカウント。 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 の NoSQL 用 API に接続するために、CosmosClient クラスのインスタンスを作成します。 このクラスは、データベースに対するすべての操作を実行するための開始点です。 CosmosClient クラスを使用して NoSQL 用 API アカウントに接続する方法には次の 3 つがあります。
エンドポイントとキーを使用して接続する
CosmosClient のコンストラクターには、次の 2 つのパラメーターがあります。
パラメーター | 値の例 | 説明 |
---|---|---|
url |
COSMOS_ENDPOINT 環境変数 |
すべての要求に使用する NoSQL 用 API エンドポイント。 |
credential |
COSMOS_KEY 環境変数 |
認証時に使用するアカウント キーまたはリソース トークン。 |
アカウント エンドポイントとキーを取得する
resourceGroupName のシェル変数を作成します。
# Variable for resource group name resourceGroupName="msdocs-cosmos-python-howto-rg"
az cosmosdb list
コマンドを使用して、リソース グループ内の最初の Azure Cosmos DB アカウントの名前を取得し、それを accountName シェル変数に格納します。# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
az cosmosdb show
コマンドを使用して、アカウントの NoSQL 用 API エンドポイント URI を取得します。az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
az-cosmosdb-keys-list
コマンドを使用して、アカウントのキーの一覧から PRIMARY KEY を見つけます。az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
URI と PRIMARY KEY の値を記録します。 これらの資格情報は後で使用します。
Python コード内で URI と PRIMARY KEY の値を使用するために、アプリケーションを実行しているローカル コンピューター上の新しい環境変数にそれらを保持します。
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
アカウント エンドポイントとキーを使用して CosmosClient を作成する
COSMOS_ENDPOINT
および COSMOS_KEY
環境変数をパラメーターとして使用し、CosmosClient クラスの新しいインスタンスを作成します。
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
KEY = os.environ["COSMOS_KEY"]
client = CosmosClient(url=ENDPOINT, credential=KEY)
接続文字列を使用して接続する
CosmosClient クラスには、1 つの必須パラメーターで接続するために使用できる from_connection_string メソッドがあります。
パラメーター | 値の例 | 説明 |
---|---|---|
conn_str |
COSMOS_CONNECTION_STRING 環境変数 |
NoSQL 用 API アカウントへの接続文字列。 |
credential |
COSMOS_KEY 環境変数 |
接続文字列の代わりに使用するオプションの代替アカウント キーまたはリソース トークン。 |
アカウント接続文字列を取得する
az cosmosdb list
コマンドを使用して、リソース グループ内の最初の Azure Cosmos DB アカウントの名前を取得し、それを accountName シェル変数に格納します。# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
az-cosmosdb-keys-list
コマンドを使用して、アカウントの接続文字列の一覧から "プライマリ接続文字列" を見つけます。az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
Python コード内でプライマリ接続文字列値を使用するために、アプリケーションを実行しているローカル コンピューター上で新しい環境変数にそれを保持します。
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
接続文字列を使用して CosmosClient を作成する
COSMOS_CONNECTION_STRING
環境変数を唯一のパラメーターとして使用し、CosmosClient クラスの新しいインスタンスを作成します。
CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]
client = CosmosClient.from_connection_string(conn_str=CONN_STR)
Microsoft ID プラットフォームを使用して接続する
Microsoft ID プラットフォームと Microsoft Entra ID を使用して NoSQL 用 API アカウントに接続するには、セキュリティ プリンシパルを使用します。 プリンシパルの正確な種類は、アプリケーション コードをホストする場所によって異なります。 次の表は、クイック リファレンス ガイドとして機能します。
アプリケーションの実行場所 | セキュリティ プリンシパル |
---|---|
ローカル コンピューター (開発とテスト) | ユーザー 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)
重要
DefaultAzureCredential
を有効にするための正しいロールを追加する方法の詳細については、「Microsoft Entra ID を使用して Azure Cosmos DB アカウントのロールベースのアクセス制御を構成する」を参照してください。 特に、ロールの作成とそれらのプリンシパル ID への割り当てに関するセクションを参照してください。
カスタム資格情報の実装を使用して CosmosClient を作成する
Azure の外部のアプリケーションをデプロイする場合は、Python 用 Azure Identity クライアント ライブラリの他のクラスを使用して、OAuth トークンを取得できます。 これらの他のクラスは、TokenCredential
クラスからも派生します。
この例では、クライアントとテナントの識別子、およびクライアント シークレットを使用して ClientSecretCredential
インスタンスを作成します。
ご使用の "app.py" で次のようにします。
サービス プリンシパルの環境変数から資格情報を取得します。 アプリケーションを Microsoft Entra ID に登録するときに、クライアント ID、テナント ID、クライアント シークレットを取得できます。 Microsoft Entra アプリケーションの登録の詳細については、「Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。
ClientSecretCredential をインポートし、
TENANT_ID
、CLIENT_ID
、およびCLIENT_SECRET
の各環境変数をパラメーターとして指定してインスタンスを作成します。ENDPOINT と credential をパラメーターとして指定して、CosmosClient クラスの新しいインスタンスを作成します。
from azure.identity import ClientSecretCredential
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
TENANT_ID = os.environ["TENANT_ID"]
CLIENT_ID = os.environ["CLIENT_ID"]
CLIENT_SECRET = os.environ["CLIENT_SECRET"]
credential = ClientSecretCredential(
tenant_id=TENANT_ID, client_id=CLIENT_ID, client_secret=CLIENT_SECRET
)
client = CosmosClient(ENDPOINT, credential)
アプリケーションをビルドする
アプリケーションをビルドすると、コードは主に 4 種類のリソースと対話します。
NoSQL 用 API アカウント。これは、Azure Cosmos DB データに対する一意で最上位の名前空間です。
アカウント内のコンテナーを整理するデータベース。
データベース内の個々の項目のセットを含むコンテナー。
コンテナー内の JSON ドキュメントを表す項目。
次の図に、これらのリソースの関係を示します。
上部に Azure Cosmos DB アカウントを示す階層図。 アカウントには 2 つの子データベース ノードがあります。 一方のデータベース ノードには、2 つの子コンテナー ノードが含まれています。 もう一方のデータベース ノードには、1 つの子コンテナー ノードが含まれています。 その 1 つのコンテナー ノードには、3 つの子項目ノードがあります。
各種類のリソースは、1 つまたは複数の関連付けられた Python クラスによって表されます。 同期プログラミングの最も一般的なクラスの一覧を次に示します。 (azure.cosmos.aio 名前空間の下には、非同期プログラミング用の同様のクラスがあります)。
クラス | 説明 |
---|---|
CosmosClient |
このクラスは、Azure Cosmos DB サービスのクライアント側の論理表現を提供します。 このクライアント オブジェクトは、サービスに対する要求の構成と実行に使用されます。 |
DatabaseProxy |
サービスに存在する (または、まだ存在しない) 場合があるデータベースへのインターフェイス。 このクラスは、直接インスタンス化しないでください。 代わりに、CosmosClient get_database_client メソッドを使用する必要があります。 |
ContainerProxy |
特定の Cosmos DB コンテナーと対話するためのインターフェイス。 このクラスは、直接インスタンス化しないでください。 代わりに、DatabaseProxy get_container_client メソッドを使用して既存のコンテナーを取得するか、create_container メソッドを使用して新しいコンテナーを作成します。 |
次のガイドでは、これらの各クラスを使ってアプリケーションをビルドする方法を示します。
ガイド | 説明 |
---|---|
データベースの作成 | データベースを作成する |
コンテナーの作成 | コンテナーを作成する |
項目の例 | 特定の項目のポイント読み取り |
こちらもご覧ください
次のステップ
これで NoSQL 用 API アカウントに接続したので、次のガイドを使用してデータベースを作成し、管理してください。