クイックスタート: Python 用 MongoDB ドライバーで Azure Cosmos DB for MongoDB 仮想コアを使用する

2025-06-11
適用対象: ✅ MongoDB (vCore)

このクイックスタートでは、Python を使用して基本的な Azure Cosmos DB for MongoDB アプリケーションを展開します。 Azure Cosmos DB for MongoDB 仮想コアはスキーマレスデータストアであり、アプリケーションは MongoDB ライブラリを使用して非構造化ドキュメントをクラウドに格納できます。 Python を使用して、Azure Cosmos DB リソース内でドキュメントを作成し、基本的なタスクを実行する方法について説明します。

ライブラリのソースコード | パッケージ (PyPI) | Azure Developer CLI

[前提条件]

Azure 開発者コマンドラインインターフェース
Docker Desktop

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

Python 3.12

プロジェクトを初期化する

Azure Developer CLI (azd) を使用して、Azure Cosmos DB for MongoDB 仮想コアクラスターを作成し、コンテナー化されたサンプルアプリケーションをデプロイします。サンプルアプリケーションでは、クライアントライブラリを使って、サンプルデータの管理、作成、読み取り、クエリを実行します。

空のディレクトリでターミナルを開きます。
まだ認証されていない場合は、azd auth loginを使用して Azure Developer CLI に対して認証します。ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。
```
azd auth login
```
azd init を使用してプロジェクトを初期化します。
```
azd init --template cosmos-db-mongodb-vcore-python-quickstart
```
初期化中に、一意の環境名を構成します。
azd upを使用してクラスターをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。
```
azd up
```
このプロビジョニングプロセス中に、サブスクリプション、目的の場所、ターゲットリソースグループを選択します。プロビジョニングプロセスが完了するまで待ちます。このプロセスには 約 10 分かかる場合があります。

Azure リソースのプロビジョニングが完了すると、実行中の Web アプリケーションへの URL が出力に含まれます。

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-___domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

コンソールで URL を使って、ブラウザーで Web アプリケーションに移動します。実行中のアプリの出力を確認します。

実行中の Web アプリケーションのスクリーンショット。

クライアントライブラリをインストールする

クライアントライブラリは、pymongo パッケージとして PyPi 経由で使用できます。

ターミナルを開き、/src フォルダーに移動します。
```
cd ./src
```
pymongo パッケージがまだインストールされていない場合は、pip install を使ってインストールします。
```
pip install pymongo
```
azure.identity パッケージがまだインストールされていない場合は、pip install を使ってインストールします。
```
pip install azure.identity
```
src/requirements.txt ファイルを開いて確認し、両方のパッケージエントリが存在することを検証します。

ライブラリをインポートする

次の名前空間をアプリケーションコードにインポートします。

	パッケージ	情報源
`DefaultAzureCredential`	`azure.identity`	Azure SDK for Python
`MongoClient`	`pymongo`	Python 用の公式 MongoDB ドライバー
`OIDCCallback`	`pymongo`	Python 用の公式 MongoDB ドライバー
`OIDCCallbackContext`	`pymongo`	Python 用の公式 MongoDB ドライバー
`OIDCCallbackResult`	`pymongo`	Python 用の公式 MongoDB ドライバー

from azure.identity import DefaultAzureCredential

from pymongo import MongoClient
from pymongo.auth_oidc import OIDCCallback, OIDCCallbackContext, OIDCCallbackResult

オブジェクトモデル

名前	説明
MongoClient	MongoDB への接続に使用される型。
`Database`	クラスター内のデータベースを表します。
`Collection`	クラスター内のデータベース内のコレクションを表します。

テンプレートのサンプルコードは、cosmicworks という名前のデータベースと products という名前のコンテナーを使います。 products コレクションには、名前、カテゴリ、数量、各製品のユニークな識別子などの詳細が含まれています。コレクションは、/category プロパティをシャードキーとして使用します。

クライアントを認証する

Azure Cosmos DB for MongoDB 仮想コアの Microsoft Entra 認証では既知の TokenCredential 型を使用できますが、カスタムトークンハンドラーを実装する必要があります。このサンプル実装を使用して、多くの ID の種類の標準的な Microsoft Entra 認証をサポートする MongoClient を作成できます。

まず、OIDCCallbackContext パラメーターを受け取ってOIDCCallbackResultを返すfetch関数を定義する AzureIdentityTokenCallback という名前のクラスを定義します。

class AzureIdentityTokenCallback(OIDCCallback):
    def __init__(self, credential):
        self.credential = credential

    def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
        token = self.credential.get_token(
            "https://ossrdbms-aad.database.windows.net/.default").token
        return OIDCCallbackResult(access_token=token)

DefaultAzureCredential型の新しいインスタンスを渡すカスタムハンドラークラスを使用する
```
credential = DefaultAzureCredential()

authProperties = {"OIDC_CALLBACK": AzureIdentityTokenCallback(credential)}
```

クラスター名と、Azure Cosmos DB for MongoDB 仮想コアの既知のベストプラクティス構成オプションを使用して、 MongoClient のインスタンスを構築します。また、カスタム認証メカニズムを構成します。

clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>"

client = MongoClient(
    f"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/",
    connectTimeoutMS=120000,
    tls=True,
    retryWrites=True,
    authMechanism="MONGODB-OIDC",
    authMechanismProperties=authProperties
)

データベースの取得

このサンプルでは、Database 型の get_database 関数を使用して MongoClient 型のインスタンスを作成します。

database = client.get_database("<database-name>")

コレクションを取得する

このサンプルでは、Collection 型の get_collection 関数を使用して Database 型のインスタンスを作成します。

collection = database.get_collection("<collection-name>")

ドキュメントの作成

collection.update_one を使用してコレクション内にドキュメントを作成します。このメソッドは "アップサート" を行い、項目が既に存在する場合は、それを効果的に置き換えます。

new_document = {
    "_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard",
    "quantity": 12,
    "sale": False,
}

filter = {
    "_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "category": "gear-surf-surfboards"
}

payload = {
    "$set": new_document
}

result = collection.update_one(filter, payload, upsert=True);

ドキュメントを読み取る

一意の識別子 (id) フィールドとシャードキーフィールドの両方を使って、ポイント読み取り操作を実行します。 collection.find_one を使って、特定の項目を効率的に取得できます。

filter = {
    "_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
    "category": "gear-surf-surfboards"
}

existing_document = collection.find_one(filter)

ドキュメントにクエリを実行する

collection.find を使って、コンテナー内の複数の項目に対してクエリを実行します。このクエリは、指定されたカテゴリ (シャードキー) 内のすべての項目を見つけます。

filter = {
    "category": "gear-surf-surfboards"
}

matched_documents = collection.find(filter)

for document in matched_documents:
    # Do something with each item

ドキュメントの削除

ドキュメントを削除するには、そのドキュメントの一意識別子のフィルターを送信します。 delete_oneを使用して、コレクションからドキュメントを削除します。

filter = {
    '_id': id
}

result = collection.delete_one(filter)

データを調査する

Azure Cosmos DB の Visual Studio Code 拡張機能を使用して、MongoDB 仮想コアデータを探索します。次のようなコアデータベース操作を実行できます。ただし、これらに限定されません:

スクラップブックまたはクエリエディターを使用したクエリの実行
ドキュメントの変更、更新、作成、および削除
他のソースからのデータの一括インポート
データベースとコレクションの管理

詳細については、「 Visual Studio Code 拡張機能を使用して Azure Cosmos DB for MongoDB 仮想コアデータを探索する方法」を参照してください。

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

サンプルアプリケーションまたはリソースが不要になったら、対応するデプロイとすべてのリソースを削除します。

azd down --force