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

[アーティクル]
08/15/2024

適用対象: MongoDB

MongoDB の使用を開始して、Azure Cosmos DB リソース内にデータベース、コレクション、ドキュメントを作成します。 Azure Developer CLI を使って最小限のソリューションを環境にデプロイするには、以下の手順に従います。

MongoDB 用 API リファレンスドキュメント | pymongo パッケージ | Azure Developer CLI

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
GitHub アカウント

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Azure Developer CLI
Docker Desktop

設定

このプロジェクトの開発コンテナーをお使いの環境にデプロイします。次に、Azure Developer CLI (azd) を使って、Azure Cosmos DB for MongoDB アカウントを作成し、コンテナー化されたサンプルアプリケーションをデプロイします。サンプルアプリケーションでは、クライアントライブラリを使って、サンプルデータの管理、作成、読み取り、クエリを実行します。

重要

GitHub アカウントには、ストレージとコア時間のエンタイトルメントが無料で含まれています。詳細については、GitHub アカウントに含まれるストレージとコア時間に関する記事を参照してください。

プロジェクトのルートディレクトリでターミナルを開きます。
azd auth login を使って Azure Developer CLI に対して認証します。ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。
```
azd auth login
```
azd init を使ってプロジェクトを初期化します。
```
azd init --template cosmos-db-mongodb-python-quickstart
```
Note

このクイックスタートでは、azure-samples/cosmos-db-mongodb-python-quickstart テンプレートの GitHub リポジトリを使用します。このプロジェクトがまだお使いのマシンにない場合は、Azure Developer CLI によって自動的にクローンされます。
初期化中に、一意の環境名を構成します。

ヒント

この環境名は、ターゲットリソースグループ名としても使用されます。このクイックスタートでは、msdocs-cosmos-db の使用を検討してください。
azd up を使って、Azure Cosmos DB アカウントをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。
```
azd up
```
プロビジョニングプロセス中に、サブスクリプションと目的の場所を選択します。プロビジョニングプロセスが完了するまで待ちます。このプロセスには 5 分ほどかかる可能性があります。

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 アプリケーションに移動します。実行中のアプリの出力を確認します。

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

PyMongo と python-dotenv パッケージの一覧が記載された、requirements.txt ファイルをアプリディレクトリに作成します。
```
# requirements.txt
pymongo
python-dotenv
```

仮想環境を作成し、パッケージをインストールします。

Windows
Linux または macOS

# py -3 uses the global python interpreter. You can also use python3 -m venv .venv.
py -3 -m venv .venv
source .venv/Scripts/activate   
pip install -r requirements.txt

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

オブジェクトモデル

MongoDB 用 API のリソースの階層と、これらのリソースの作成とアクセスに使用されるオブジェクトモデルについて説明します。 Azure Cosmos DB によって、アカウント、データベース、コレクション、ドキュメントで構成される階層内にリソースが作成されます。

アカウント、データベース、コレクション、ドキュメントを含む Azure Cosmos DB 階層の図。

リソースの各種類は、Python クラスによって表されます。最も一般的なクラスを次に示します。

MongoClient - PyMongo を使用する最初のステップは、Azure Cosmos DB の MongoDB 用 API に接続する MongoClient を作成することです。このクライアントオブジェクトは、サービスに対する要求の構成と実行に使用されます。
データベース - Azure Cosmos DB の MongoDB 用 API では、1 つ以上の独立したデータベースをサポートできます。
コレクション - データベースには 1 つまたは複数のコレクションを格納できます。コレクションは MongoDB に格納されているドキュメントのグループであり、リレーショナルデータベースのテーブルとほぼ同等と考えられます。
ドキュメント - ドキュメントはキーと値のペアのセットです。ドキュメントには動的スキーマがあります。動的スキーマとは、同じコレクション内のドキュメントに同じフィールドまたは構造のセットが必要ないことを意味します。また、コレクションのドキュメント内の共通フィールドには、さまざまな種類のデータが含まれている場合があります。

エンティティの階層について詳しくは、「Azure Cosmos DB リソースモデル」の記事を参照してください。

この記事で説明されているサンプルコードでは、products という名前のコレクションを使用して adventureworks という名前のデータベースを作成します。 products コレクションは、名前、カテゴリ、数量、販売インジケーターなどの製品の詳細が含まれるように設計されています。各製品には、一意の識別子も含まれています。完全なサンプルコードは https://github.com/Azure-Samples/azure-cosmos-db-mongodb-python-getting-started/tree/main/001-quickstart/ にあります。

次のステップでは、データベースでシャーディングが使用されず、PyMongo ドライバーを使用した同期アプリケーションを示しています。非同期アプリケーションの場合は、Motor ドライバーを使用します。

クライアントを認証する

プロジェクトディレクトリで、run.py ファイルを作成します。使用するパッケージ (PyMongo パッケージや python-dotenv パッケージなど) を参照するために、エディターで require ステートメントを追加します。
```
import os
import sys
from random import randint

import pymongo
from dotenv import load_dotenv
```
.env ファイルで定義されている環境変数から接続情報を取得します。
```
load_dotenv()
CONNECTION_STRING = os.environ.get("COSMOS_CONNECTION_STRING")
```

コードで使用する定数を定義します。

DB_NAME = "adventureworks"
COLLECTION_NAME = "products"

Azure Cosmos DB の MongoDB 用 API に接続する

MongoClient オブジェクトを使用して、Azure Cosmos DB for MongoDB リソースに接続します。この接続メソッドは、データベースへの参照を返します。

client = pymongo.MongoClient(CONNECTION_STRING)

データベースの取得

list_database_names メソッドを使用して、データベースが存在するかどうかを確認します。データベースが存在しない場合は、データベースを作成する拡張機能コマンドを使用して、プロビジョニングされたスループットを指定して作成します。

# Create database if it doesn't exist
db = client[DB_NAME]
if DB_NAME not in client.list_database_names():
    # Create a database with 400 RU throughput that can be shared across
    # the DB's collections
    db.command({"customAction": "CreateDatabase", "offerThroughput": 400})
    print("Created db '{}' with shared throughput.\n".format(DB_NAME))
else:
    print("Using database: '{}'.\n".format(DB_NAME))

コレクションの取得

list_collection_names メソッドを使用して、コレクションが存在するかどうかを確認します。コレクションが存在しない場合は、コレクションを作成する拡張機能コマンドを使用して作成します。

# Create collection if it doesn't exist
collection = db[COLLECTION_NAME]
if COLLECTION_NAME not in db.list_collection_names():
    # Creates a unsharded collection that uses the DBs shared throughput
    db.command(
        {"customAction": "CreateCollection", "collection": COLLECTION_NAME}
    )
    print("Created collection '{}'.\n".format(COLLECTION_NAME))
else:
    print("Using collection: '{}'.\n".format(COLLECTION_NAME))

インデックスを作成する

コレクションを更新する拡張機能コマンドを使用して、インデックスを作成します。コレクションを作成する拡張機能コマンドでインデックスを設定することもできます。この例では、後で製品名のカーソルクラス sort メソッドを使用して並べ替えられるように、インデックスを name プロパティに設定します。

indexes = [
    {"key": {"_id": 1}, "name": "_id_1"},
    {"key": {"name": 2}, "name": "_id_2"},
]
db.command(
    {
        "customAction": "UpdateCollection",
        "collection": COLLECTION_NAME,
        "indexes": indexes,
    }
)
print("Indexes are: {}\n".format(sorted(collection.index_information())))

ドキュメントの作成

adventureworks データベースの product プロパティを使用してドキュメントを作成します。

category プロパティ。このプロパティは、論理パーティションキーとして使用できます。
name プロパティ。
インベントリの quantity プロパティ。
sale プロパティ。製品が販売されているかどうかを示します。

"""Create new document and upsert (create or replace) to collection"""
product = {
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard-{}".format(randint(50, 5000)),
    "quantity": 1,
    "sale": False,
}
result = collection.update_one(
    {"name": product["name"]}, {"$set": product}, upsert=True
)
print("Upserted document with _id {}\n".format(result.upserted_id))

コレクションレベルの操作 update_one を呼び出して、コレクション内にドキュメントを作成します。この例では、新しいドキュメントを作成する代わりにアップサートします。この例では、製品名がランダムであるため、アップサートは必要ありません。ただし、コードを複数回実行し、製品名が同じである場合に備えて、アップサートすることをお勧めします。

update_one 操作の結果には、後続の操作で使用できる _id フィールドの値が含まれます。 _id プロパティは自動的に作成されています。

1 つのドキュメントを取得する

find_one メソッドを使用して、ドキュメントを取得します。

doc = collection.find_one({"_id": result.upserted_id})
print("Found a document with _id {}: {}\n".format(result.upserted_id, doc))

Azure Cosmos DB では、一意識別子 (_id) とパーティションキーの両方を使用して、低コストのポイント読み取り操作を実行できます。

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

ドキュメントを挿入した後、クエリを実行して、特定のフィルターに一致するすべてのドキュメントを取得できます。この例では、特定のカテゴリ gear-surf-surfboards に一致するすべてのドキュメントを検索します。クエリを定義したら、Collection.find を呼び出して Cursor の結果を取得してから、sort を使用します。

"""Query for documents in the collection"""
print("Products with category 'gear-surf-surfboards':\n")
allProductsQuery = {"category": "gear-surf-surfboards"}
for doc in collection.find(allProductsQuery).sort(
    "name", pymongo.ASCENDING
):
    print("Found a product with _id {}: {}\n".format(doc["_id"], doc))

トラブルシューティング:

The index path corresponding to the specified order-by item is excluded. などのエラーが発生した場合は、インデックスを作成していることを確認してください。

コードの実行

このアプリでは、MongoDB 用 API データベースとコレクションが作成され、ドキュメントが作成されてから、まったく同じドキュメントが読み戻されます。この例では、最後に、指定した製品カテゴリと一致するドキュメントを返すクエリが発行されます。この例では、ステップごとに、実行したステップに関する情報がコンソールに出力されます。

アプリを実行するには、ターミナルを使用してアプリケーションディレクトリに移動し、アプリケーションを実行します。

python run.py

アプリの出力は次の例のようになります。


Created db 'adventureworks' with shared throughput.

Created collection 'products'.

Indexes are: ['_id_', 'name_1']

Upserted document with _id <ID>

Found a document with _id <ID>:
{'_id': <ID>,
'category': 'gear-surf-surfboards',
'name': 'Yamba Surfboard-50',
'quantity': 1,
'sale': False}

Products with category 'gear-surf-surfboards':

Found a product with _id <ID>:
{'_id': ObjectId('<ID>'),
'name': 'Yamba Surfboard-386',
'category': 'gear-surf-surfboards',
'quantity': 1,
'sale': False}

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

Azure Cosmos DB for NoSQL アカウントが不要になったら、対応するリソースグループを削除できます。

az group delete コマンドを使用して、リソースグループを削除します。

az group delete --name $resourceGroupName

Remove-AzResourceGroup コマンドレットを使用して、リソースグループを削除します。

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

次の方法で共有

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

前提条件

設定

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

オブジェクトモデル

コード例

クライアントを認証する

Azure Cosmos DB の MongoDB 用 API に接続する

データベースの取得

コレクションの取得

インデックスを作成する

ドキュメントの作成

1 つのドキュメントを取得する

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

コードの実行

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

フィードバック

その他のリソース

次の方法で共有

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

前提条件

設定

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

オブジェクト モデル

コード例

クライアントを認証する

Azure Cosmos DB の MongoDB 用 API に接続する

データベースの取得

コレクションの取得

インデックスを作成する

ドキュメントの作成

1 つのドキュメントを取得する

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

コードの実行

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

フィードバック

その他のリソース

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

オブジェクトモデル