クイックスタート: Python 用 Azure Cosmos DB for NoSQL ライブラリ

[アーティクル]
01/17/2024

適用対象: NoSQL

Python 用の Azure Cosmos DB for NoSQL クライアントライブラリを使って、コンテナー内のデータのクエリを実行し、個々の項目に対して一般的な操作を行います。 Azure Developer CLI を使って最小限のソリューションを環境にデプロイするには、以下の手順に従います。

API のリファレンスドキュメント | ライブラリのソースコード | パッケージ (PyPI) | Azure Developer CLI

前提条件

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

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

設定

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

重要

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

プロジェクトのルートディレクトリでターミナルを開きます。
azd auth login を使って Azure Developer CLI に対して認証します。ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。
```
azd auth login
```
azd init を使ってプロジェクトを初期化します。
```
azd init
```
初期化中に、一意の環境名を構成します。

ヒント

この環境名は、ターゲットリソースグループ名としても使用されます。このクイックスタートでは、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 アプリケーションに移動します。実行中のアプリの出力を確認します。

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

クライアントライブラリは、Python Package Index から azure-cosmos ライブラリとして入手できます。

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

オブジェクトモデル

名前	説明
`CosmosClient`	このクラスは主要なクライアントクラスであり、アカウント全体のメタデータやデータベースを管理するために使われます。
`DatabaseProxy`	このクラスはアカウント内のデータベースを表します。
`ContainerProxy`	このクラスは主に、コンテナーまたはコンテナー内に格納されている項目の読み取り、更新、削除操作を実行するために使われます。
`PartitionKey`	このクラスは論理パーティションキーを表します。このクラスは、多くの一般的な操作とクエリに必要です。

テンプレートのサンプルコードでは、cosmicworks というデータベースと products というコンテナーを使います。 products コンテナーには、各製品の名前、カテゴリ、数量、一意識別子、販売フラグなどの詳細が含まれています。コンテナーでは、論理パーティションキーとして /category プロパティを使います。

クライアントを認証する

ほとんどの Azure サービスに対するアプリケーション要求は、承認される必要があります。アプリケーションと Azure Cosmos DB for NoSQL の間でパスワードレスの接続を実装するため、推奨される方法として、DefaultAzureCredential 型を使います。 DefaultAzureCredential は複数の認証方法をサポートしており、実行時に使用する方法が決定されます。

重要

パスワード、接続文字列、その他の資格情報を使用して、Azure サービスへの要求を直接承認することもできます。ただし、この方法は慎重に使用する必要があります。開発者は、安全でない場所にこれらのシークレットを公開しないように注意する必要があります。パスワードまたは秘密鍵へのアクセス権を取得したユーザーは誰でも、データベースサービスに対して認証を行うことができます。 DefaultAzureCredential では、アカウントキーよりも管理とセキュリティの利点が向上し、キーを保存するリスクなしでパスワードレス認証が可能になります。

このサンプルでは、CosmosClient 型の新しいインスタンスを作成し、DefaultAzureCredential インスタンスを使って認証します。

credential = DefaultAzureCredential()
client = CosmosClient(url=endpoint, credential=credential)

データベースの取得

client.get_database_client を使って、cosmicworks という既存のデータベースを取得します。

database = client.get_database_client("cosmicworks")

コンテナーの取得

database.get_container_client を使って既存の products コンテナーを取得します。

container = database.get_container_client("products")

項目を作成する

JSON にシリアル化するすべてのメンバーを含む新しいオブジェクトを構築します。この例では、型には一意識別子と、カテゴリ、名前、数量、価格、セールのフィールドがあります。 container.upsert_item を使ってコンテナー内に項目を作成します。このメソッドは "アップサート" を行い、項目が既に存在する場合は、それを効果的に置き換えます。

new_item = {
    "id": "70b63682-b93a-4c77-aad2-65501347265f",
    "category": "gear-surf-surfboards",
    "name": "Yamba Surfboard",
    "quantity": 12,
    "sale": False,
}
created_item = container.upsert_item(new_item)

項目を読み取る

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

existing_item = container.read_item(
    item="70b63682-b93a-4c77-aad2-65501347265f",
    partition_key="gear-surf-surfboards",
)

クエリ項目

container.GetItemQueryIterator を使って、コンテナー内の複数の項目に対してクエリを実行します。次のパラメーター化されたクエリを使って、指定されたカテゴリ内のすべての項目を検索します。

SELECT * FROM products p WHERE p.category = @category

queryText = "SELECT * FROM products p WHERE p.category = @category"
results = container.query_items(
    query=queryText,
    parameters=[
        dict(
            name="@category",
            value="gear-surf-surfboards",
        )
    ],
    enable_cross_partition_query=False,
)

クエリの結果をループ処理します。

items = [item for item in results]
output = json.dumps(items, indent=True)

次のステップ

PyPI パッケージ