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

[アーティクル]
04/13/2023

適用対象: MongoDB

PyMongo パッケージの使用を開始して、Azure Cosmos DB リソース内にデータベース、コレクション、ドキュメントを作成します。以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。

Note

コードスニペットの例は、Python プロジェクトとして GitHub 上で使用できます。

このクイックスタートでは、Python 用のオープンソース MongoDB クライアントドライバーの 1 つである PyMongo を使用して、Azure Cosmos DB の MongoDB 用 API と通信します。また、MongoDB 拡張機能コマンドを使用します。このコマンドは、Azure Cosmos DB 容量モデルに固有のデータベースリソースを作成および取得する際に役立ちます。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
python=3.8.10
Azure コマンドラインインターフェイス (CLI) または Azure PowerShell

前提条件のチェック

ターミナルまたはコマンドウィンドウで python --version を実行して、Python が最新バージョンであることを確認します。
az --version (Azure CLI) または Get-Module -ListAvailable Az* (Azure PowerShell) を実行して、適切な Azure コマンドラインツールがインストールされていることを確認します。

設定

このセクションでは、Azure Cosmos DB アカウントを作成し、MongoDB npm パッケージを使用するプロジェクトを設定する手順について説明します。

Azure Cosmos DB アカウントを作成する

このクイックスタートでは、MongoDB 用 API を使って Azure Cosmos DB アカウントを 1 つ作成します。

accountName、resourceGroupName、および location のシェル変数を作成します。

# Variable for resource group name
resourceGroupName="msdocs-cosmos-quickstart-rg"
location="westus"

# Variable for account name with a randomnly generated suffix
let suffix=$RANDOM*$RANDOM
accountName="msdocs-$suffix"

az login コマンドを使用して Azure CLI にサインインします (まだ行っていない場合)。
az group create コマンドを使用して、サブスクリプションに新しいリソースグループを作成します。
```
az group create \
    --name $resourceGroupName \
    --location $location
```

az cosmosdb create コマンドを使って、既定の設定で新しい Azure Cosmos DB for MongoDB アカウントを作成します。

az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --kind MongoDB

ACCOUNT_NAME、RESOURCE_GROUP_NAME、LOCATION のシェル変数を作成します。

# Variable for resource group name
$RESOURCE_GROUP_NAME = "msdocs-cosmos-quickstart-rg"
$LOCATION = "West US"

# Variable for account name with a randomnly generated suffix
$SUFFIX = Get-Random
$ACCOUNT_NAME = "msdocs-$SUFFIX"

Connect-AzAccount コマンドレットを使用して Azure PowerShell にサインインします (まだ行っていない場合)。
New-AzResourceGroup コマンドレットを使用して、サブスクリプションに新しいリソースグループを作成します。
```
$parameters = @{
    Name = $RESOURCE_GROUP_NAME
    Location = $LOCATION
}
New-AzResourceGroup @parameters    
```

New-AzCosmosDBAccount コマンドレットを使って、既定の設定で新しい Azure Cosmos DB for MongoDB アカウントを作成します。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Location = $LOCATION
    ApiKind = "MongoDB"
}
New-AzCosmosDBAccount @parameters

ヒント

このクイックスタートでは、リソースグループ名 msdocs-cosmos-quickstart-rg を使用することをお勧めします。

Azure portal にサインインします。
Azure portal のメニューまたは [ホーム] ページで、 [リソースの作成] を選択します。
[新規] ページで、 [Azure Cosmos DB] を検索して選択します。
[API オプションの選択] ページで、[MongoDB] セクション内の [作成] オプションを選択します。 Azure Cosmos DB には、SQL、MongoDB、Gremlin、Table、Cassandra の 5 つの API があります。 MongoDB 用 API に関する詳細を参照してください。

[Azure Cosmos DB アカウントの作成] ページで、次の情報を入力します。

設定	値	説明
サブスクリプション	サブスクリプション名	この Azure Cosmos DB アカウントに使う Azure サブスクリプションを選びます。
リソースグループ	リソースグループ名	リソースグループを選択するか、 [新規作成] を選択し、新しいリソースグループの一意の名前を入力します。
アカウント名	一意の名前	自分の Azure Cosmos DB アカウントを識別するための名前を入力します。名前は、サフィックスが documents.azure.com の完全修飾ドメイン名 (FQDN) の一部として使用されるため、グローバルに一意である必要があります。名前に含めることができるのは、英小文字、数字、ハイフン (-) のみです。また、名前の長さは 3 文字から 44 文字である必要があります。
場所	ユーザーに最も近いリージョン	Azure Cosmos DB アカウントをホストする地理的な場所を選択します。データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。
容量モード	プロビジョニングスループットまたはサーバーレス	プロビジョニングスループットモードでアカウントを作成するには、 [Provisioned throughput](プロビジョニングスループット) を選択します。サーバーレスモードでアカウントを作成するには、 [サーバーレス] を選択します。
Apply Azure Cosmos DB free tier discount (Azure Cosmos DB Free レベル割引を適用する)	[適用] または [適用しない]	Azure Cosmos DB Free レベルのアカウントでは、最初の 1000 RU/s と 25 GB のストレージを無料でご利用いただけます。 Free レベルの詳細を確認してください。
バージョン	MongoDB バージョン	アプリケーションの要件に一致する MongoDB サーバーのバージョンを選択します。

Note

Azure サブスクリプションにつき所有できる Free レベルの Azure Cosmos DB アカウントは 1 つまでです。また、アカウントの作成時にオプトインする必要があります。 Free レベルの割引を適用するオプションが表示されない場合は、サブスクリプション内の別のアカウントが Free レベルで既に有効になっていることを意味します。

[Review + create](レビュー + 作成) を選択します。
指定した設定を確認し、[作成] を選択します。アカウントの作成には数分かかります。ポータルページに "デプロイが完了しました" と表示されるまで待ってから移動します。
[リソースに移動] を選択し、Azure Cosmos DB アカウントページに移動します。

MongoDB 接続文字列の取得

az cosmosdb keys list コマンドを使って、アカウントの接続文字列の一覧から MongoDB 用 API の接続文字列を見つけます。
```
az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName 
```
"主キー" の値を記録します。これらの資格情報は後で使用します。

Get-AzCosmosDBAccountKey コマンドレットを使用して、アカウントの接続文字列の一覧から "接続文字列" を見つけます。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary MongoDB Connection String"

"接続文字列" の値を記録します。これらの資格情報は後で使用します。

新しい Python アプリを作成する

任意のターミナルを使用して新しい空のフォルダーを作成し、ディレクトリをそのフォルダーに変更します。

Note

完成したコードが必要な場合は、完全な例を含むサンプルコードスニペットリポジトリをダウンロードまたはフォークして複製します。また、Azure Cloud Shell のリポジトリで git clone を実行して、このクイックスタートに示されているステップに従うこともできます。
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

環境変数を構成する

コード内で接続文字列の値を使用するには、アプリケーションを実行しているローカル環境でこの値を設定します。環境変数を設定するには、任意のターミナルを使用して次のコマンドを実行します。

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env ファイルは、環境変数をプロジェクトに格納する標準的な方法です。プロジェクトのルートに .env ファイルを作成します。次の行を .env ファイルに追加します。

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

オブジェクトモデル

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

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

リソースの各種類は、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