免責事項

Python 2.7 の Azure SDK Python パッケージのサポートは、2022 年 1 月 1 日に終了しました。 詳細と質問については、https://github.com/Azure/azure-sdk-for-python/issues/20691 を参照してください

Python 用 Azure Cosmos DB SQL API クライアント ライブラリ - バージョン 4.5.1

Azure Cosmos DB はグローバル分散型のマルチモデル データベース サービスであり、ドキュメント、キー値、ワイドカラム、グラフのデータベースをサポートします。

Azure Cosmos DB SQL API SDK for Python を使用して、この NoSQL データベース サービスに含まれるデータベースと JSON ドキュメントを管理します。 高レベルの機能は次のとおりです。

• Cosmos DB データベース を作成し、その設定を変更する
• JSON ドキュメントのコレクションを格納する コンテナー を作成および変更する
• コンテナー内の 項目 (JSON ドキュメント) を作成、読み取り、更新、削除する
• SQL のような構文を使用してデータベース内のドキュメントに対してクエリを実行する

SDK ソース コード | パッケージ (PyPI) | パッケージ (Conda) | API リファレンス ドキュメント | 製品ドキュメント | サンプル

この SDK は SQL API に使用されます。 その他のすべての API については、Azure Cosmos DB のドキュメントをチェックして、プロジェクトに最適な SDK を評価してください。

作業の開始

Python 2.x サポートに関する重要な更新

この SDK の新しいリリースでは、2022 年 1 月 1 日以降は Python 2.x はサポートされません。 詳細については、変更ログに関する記事を確認してください。

前提条件

• Azure サブスクリプション - 無料アカウントを作成できます
• Azure Cosmos DB アカウント - SQL API
• Python 3.6 以降

Cosmos DB SQL API アカウントが必要な場合は、次の Azure CLI コマンドを使用して作成できます。

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-account-name>

パッケージをインストールする

pip install azure-cosmos

仮想環境を構成する (オプション)

必須ではありませんが、仮想環境を使用すると、お使いのベース システムと Azure SDK 環境を相互に分離させておくことができます。 次のコマンドを実行して venv を構成し、仮想環境に入ります。

python3 -m venv azure-cosmosdb-sdk-environment
source azure-cosmosdb-sdk-environment/bin/activate

クライアントを認証する

Cosmos DB との対話は、 CosmosClient クラスのインスタンスから始まります。 クライアント オブジェクトをインスタンス化するには、 アカウント、その URI、およびその アカウント キー のいずれかが必要です。

次の Azure CLI スニペットを使用して、2 つの環境変数にデータベース アカウント URI とその主マスター キーを設定します (これらの値はAzure portalでも確認できます)。 このスニペットは Bash シェル用にフォーマットされています。

RES_GROUP=<resource-group-name>
ACCT_NAME=<cosmos-db-account-name>

export ACCOUNT_URI=$(az cosmosdb show --resource-group $RES_GROUP --name $ACCT_NAME --query documentEndpoint --output tsv)
export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $ACCT_NAME --query primaryMasterKey --output tsv)

クライアントを作成する

環境変数と ACCOUNT_KEY 環境変数をACCOUNT_URI設定したら、CosmosClient を作成できます。

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

AAD 認証

サービス プリンシパルの AAD 資格情報と Azure ID パッケージを使用してクライアントを認証することもできます。 資格情報情報を ClientSecretCredential に直接渡すか、DefaultAzureCredential を使用できます。

from azure.cosmos import CosmosClient
from azure.identity import ClientSecretCredential, DefaultAzureCredential

import os
url = os.environ['ACCOUNT_URI']
tenant_id = os.environ['TENANT_ID']
client_id = os.environ['CLIENT_ID']
client_secret = os.environ['CLIENT_SECRET']

# Using ClientSecretCredential
aad_credentials = ClientSecretCredential(
    tenant_id=tenant_id,
    client_id=client_id,
    client_secret=client_secret)

# Using DefaultAzureCredential (recommended)
aad_credentials = DefaultAzureCredential()

client = CosmosClient(url, aad_credentials)

AAD 認証に使用するマネージド ID にアクセス許可があることを readMetadata 常に確認してください。
AAD 認証を設定する方法の詳細については、「AAD 認証の RBAC を設定する」を参照してください
AAD 認証クライアントに対して許可される操作の詳細: RBAC アクセス許可モデル

主要な概念

CosmosClient を初期化したら、Cosmos DB でプライマリ リソースの種類を操作できます。

• データベース: Cosmos DB アカウントに複数のデータベースを含めることができます。 データベースを作成する場合は、ドキュメントを操作するときに使用する API を指定します (SQL、MongoDB、Gremlin、Cassandra、または Azure Table)。 DatabaseProxy オブジェクトを使用してコンテナーを管理します。

• コンテナー:コンテナーは、JSON ドキュメントのコレクションです。 ContainerProxy オブジェクトのメソッドを使用して、コンテナー内の項目の作成 (挿入、読み取り、更新、および削除) を行います。

• Item: Item は、コンテナーに格納されている JSON ドキュメントのディクショナリに似た表現です。 コンテナーに追加する各項目には、コンテナー内の項目を id 一意に識別する値を持つキーを含める必要があります。

これらのリソースの詳細については、「Azure Cosmos データベース、コンテナー、および項目の操作」を参照してください。

使用方法 enable_cross_partition_query

キーワード (keyword)引数enable_cross_partition_queryは、(既定値) または Trueの 2 つのオプション None を受け入れます。

ID によるクエリの使用に関する注意

ID 値に基づいて項目を検索しようとするクエリを使用する場合は、常に文字列型変数を渡していることを確認してください。 Azure Cosmos DB では文字列 ID 値のみが許可され、他のデータ型を使用する場合、この SDK は結果を返せず、エラー メッセージも返しません。

クライアントの整合性レベルに関する注意

リリース バージョン 4.3.0b3 以降、ユーザーが明示的な整合性レベルをクライアントの初期化に渡さない場合、クライアントはデータベース アカウントの既定のレベルを使用します。 以前は、既定値は整合性に Session 設定されていました。 何らかの理由でこれを続けたい場合は、クライアントの初期化を変更して、次のように明示的なパラメーターを含めることができます。

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY, consistency_level='Session')

制限事項

現在、以下の機能は サポートされていません。 代替オプションについては、以下の「回避策」セクションをチェック。

データ プレーンの制限事項:

• グループ化クエリ
• DISTINCT サブクエリからの COUNT を使用したクエリ: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• 一括/トランザクション バッチ処理
• TCP モードへの直接アクセス
• 並べ替え、カウント、個別などの集計クロスパーティション クエリに対する継続トークンのサポート。 のようなSELECT * FROM WHEREストリーミング可能なクエリでは、継続トークンがサポートされます。
• 変更フィード: プロセッサ
• 変更フィード: 複数のパーティション キー値を読み取ります
• 変更フィード: 特定の時刻を読み取ります
• 変更フィード: 最初から読み取ります
• 変更フィード: プル モデル
• 混合型のクロスパーティション ORDER BY
• 非同期クエリ型メソッドの診断を有効にする

コントロール プレーンの制限事項:

• CollectionSizeUsage、DatabaseUsage、DocumentUsage のメトリックを取得する
• 地理空間インデックスを作成する
• 接続文字列を取得する
• コンテナーの最小 RU/秒を取得する

対処方法

一括処理の制限の回避策

Python SDK を使用して Cosmos DB への一括挿入を実行する場合は、 ストアド プロシージャ を使用して同じパーティション キーを持つ複数の項目を書き込むのが最善の方法です。

コントロール プレーンの制限事項の回避策

通常、コントロール プレーンでサポートされていない制限事項には、 Azure Portal、 Azure Cosmos DB リソース プロバイダー REST API、 Azure CLI 、 または PowerShell を使用できます。

Boolean データ型

Python 言語ではブール型に "True" と "False" が 使用 されますが、Cosmos DB では "true" と "false" のみを 受け入れます 。 言い換えると、Python 言語では、最初の大文字と他のすべての小文字でブール値が使用されますが、Cosmos DB とその SQL 言語では、同じブール値に対して小文字のみが使用されます。 この課題に対処する方法

• Python で作成された JSON ドキュメントでは、言語の検証に合格するために "True" と "False" を使用する必要があります。 SDK は、それを "true" と "false" に変換します。 つまり、"true" と "false" は Cosmos DB に格納されます。
• Cosmos DB ポータルのData Explorerでこれらのドキュメントを取得すると、"true" と "false" と表示されます。
• この Python SDK でこれらのドキュメントを取得すると、"true" と "false" の値が自動的に "True" と "False" に変換されます。

SQL クエリ x FROM 句サブ項目

この SDK では、 query_items メソッドを使用して SQL クエリを Azure Cosmos DB に送信します。

Cosmos DB SQL 言語を使用すると、 FROM 句を使用してサブ項目を取得して、ソースをより小さなサブセットに減らすことができます。 たとえば、 の代わりに select * from Familiesを使用select * from Families.childrenできます。 ただし、次の点にご注意ください。

• メソッドを使用する SQL クエリの query_items 場合、この SDK では、 フラグを指定するか、 フラグを partition_key 使用する enable_cross_partition_query 必要があります。
• サブ項目を取得し、 を指定している partition_key場合は、パーティション キーがサブ項目に含まれていることを確認してください。これはほとんどの場合に当てはまりません。

最大項目数

これは、query_items メソッドのパラメーターであり、ページごとに返されるアイテムの最大数を示す整数です。 この値を None 指定すると、サービスが最適な項目数を判断できます。 これは推奨される構成値であり、この SDK が設定されていない場合の既定の動作です。

例

次のセクションでは、以下を含む Cosmos DB の最も一般的なタスクのいくつかに対応したコード スニペットをいくつか紹介します。

• データベースを作成する
• コンテナーを作成する
• 分析ストアが有効なコンテナーを作成する
• 既存のコンテナーを取得する
• データの挿入
• データを削除する
• データベースに対してクエリを実行する
• データベースのプロパティを取得する
• データベースとコンテナーのスループットを取得する
• コンテナーのプロパティを変更する
• 非同期クライアントの使用

データベースを作成する

CosmosClient の認証後に、アカウント内の任意のリソースを操作できます。 次のコード スニペットは、SQL API データベースを作成します。これは、 create_database が呼び出されたときに API が指定されていない場合の既定値です。

from azure.cosmos import CosmosClient, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
try:
    database = client.create_database(DATABASE_NAME)
except exceptions.CosmosResourceExistsError:
    database = client.get_database_client(DATABASE_NAME)

コンテナーを作成する

この例では、既定の設定でコンテナーを作成します。 同じ名前のコンテナーが既にデータベースに存在する場合 (エラーが発生しています)、 409 Conflict 代わりに既存のコンテナーが取得されます。

from azure.cosmos import CosmosClient, PartitionKey, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'

try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

分析ストアが有効なコンテナーを作成する

この例では、レポート、BI、AI、Azure Synapse リンクを使用した Advanced Analytics 用に、分析ストアが有効になっているコンテナーを作成します。

analytical_storage_ttlのオプションは次のとおりです。

• 0 または Null または通知なし: 有効になっていません。
• -1: データは無限に格納されます。
• その他の数値: 実際の ttl (秒単位)。

CONTAINER_NAME = 'products'
try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1)
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

上記のスニペットでは、コンテナーの作成に失敗した場合に CosmosHttpResponseError 例外も処理します。 エラー処理とトラブルシューティングの詳細については、「 のトラブルシューティング 」セクションを参照してください。

既存のコンテナーを取得する

データベースから既存のコンテナーを取得します。

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

データの挿入

コンテナーに項目を挿入するには、データを含むディクショナリを ContainerProxy.upsert_itemに渡します。 コンテナーに追加する各項目には、コンテナー内の項目を id 一意に識別する値を持つキーを含める必要があります。

次の使用例は、コンテナーに複数の項目を挿入します。それぞれが一意 idです。

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for i in range(1, 10):
    container.upsert_item({
            'id': 'item{0}'.format(i),
            'productName': 'Widget',
            'productModel': 'Model {0}'.format(i)
        }
    )

データの削除

コンテナーから項目を削除するには、 ContainerProxy.delete_itemを使用します。 Cosmos DB の SQL API では、SQL DELETE ステートメントはサポートされていません。

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for item in container.query_items(
        query='SELECT * FROM products p WHERE p.productModel = "Model 2"',
        enable_cross_partition_query=True):
    container.delete_item(item, partition_key='Widget')

注: パーティション 分割コレクションを使用している場合、上記のコード例の の partitionKey 値は、コレクション内のパーティション キー列の名前ではなく、この特定の項目のパーティション キーの値に設定する必要があります。 これは、ポイントの読み取りと削除の両方に当てはまります。

データベースのクエリを実行する

Cosmos DB SQL API データベースでは、SQL に似た構文を使用して 、ContainerProxy.query_items を使用してコンテナー内の項目のクエリを実行できます。

次の例では、特定 idの を持つ項目についてコンテナーに対してクエリを実行します。

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

# Enumerate the returned items
import json
for item in container.query_items(
        query='SELECT * FROM mycontainer r WHERE r.id="item3"',
        enable_cross_partition_query=True):
    print(json.dumps(item, indent=True))

注: 句ではコンテナー名に任意の値を FROM 指定できますが、一貫性を保つにはコンテナー名を使用することをお勧めします。

パラメーターとその値を含むディクショナリを ContainerProxy.query_itemsに渡して、パラメーター化されたクエリを実行します。

discontinued_items = container.query_items(
    query='SELECT * FROM products p WHERE p.productModel = @model',
    parameters=[
        dict(name='@model', value='Model 7')
    ],
    enable_cross_partition_query=True
)
for item in discontinued_items:
    print(json.dumps(item, indent=True))

SQL API を使用する Cosmos DB データベースに対するクエリの実行について詳しくは、SQL クエリを使用する Azure Cosmos DB データに対するクエリの実行に関するページを参照してください。

データベースのプロパティを取得する

データベースのプロパティを取得して表示します。

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
properties = database.read()
print(json.dumps(properties))

データベースとコンテナーのスループットを取得する

専用スループットを使用して、データベースとコンテナーのスループット値を取得して表示します。

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

# Database
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
db_offer = database.read_offer()
print('Found Offer \'{0}\' for Database \'{1}\' and its throughput is \'{2}\''.format(db_offer.properties['id'], database.id, db_offer.properties['content']['offerThroughput']))

# Container with dedicated throughput only. Will return error "offer not found" for containers without dedicated throughput
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)
container_offer = container.read_offer()
print('Found Offer \'{0}\' for Container \'{1}\' and its throughput is \'{2}\''.format(container_offer.properties['id'], container.id, container_offer.properties['content']['offerThroughput']))

コンテナーのプロパティを変更する

既存のコンテナーの特定のプロパティを変更できます。 次の使用例は、コンテナー内の項目の既定の有効期間 (TTL) を 10 秒に設定します。

from azure.cosmos import CosmosClient, PartitionKey
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

database.replace_container(
    container,
    partition_key=PartitionKey(path="/productName"),
    default_ttl=10,
)
# Display the new TTL setting for the container
container_props = container.read()
print(json.dumps(container_props['defaultTtl']))

TTL の詳細については、「 Time to Live for Azure Cosmos DB data」を参照してください。

非同期クライアントの使用

非同期 Cosmos クライアントは、既存の同期クライアントと同様の方法で外観と動作を行う個別のクライアントです。 ただし、非同期クライアントは個別にインポートする必要があり、そのメソッドは async/await キーワードと共に使用する必要があります。 非同期クライアントは、使用後に初期化して閉じる必要があります。これは手動で行うか、コンテキスト マネージャーを使用して実行できます。 次の例は、手動で行う方法を示しています。

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'    

async def create_products():
    client = CosmosClient(URL, credential=KEY)
    database = client.get_database_client(DATABASE_NAME)
    container = database.get_container_client(CONTAINER_NAME)
    for i in range(10):
        await container.upsert_item({
                'id': 'item{0}'.format(i),
                'productName': 'Widget',
                'productModel': 'Model {0}'.format(i)
            }
        )
    await client.close() # the async client must be closed manually if it's not initialized in a with statement

クライアントを手動で開いたり閉じたりするのではなく、キーワードを使用 async with することを強くお勧めします。 これにより、ステートメントから抜け出すと、クライアントを初期化して後で閉じるコンテキスト マネージャーが作成されます。 次の例は、その方法を示しています。

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'

async def create_products():
    async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically initialize and close the async client
        database = client.get_database_client(DATABASE_NAME)
        container = database.get_container_client(CONTAINER_NAME)
        for i in range(10):
            await container.upsert_item({
                    'id': 'item{0}'.format(i),
                    'productName': 'Widget',
                    'productModel': 'Model {0}'.format(i)
                }
            )

非同期クライアントを使用したクエリ

同期クライアントとは異なり、非同期クライアントには要求に enable_cross_partition フラグがありません。 指定されたパーティション キー値を持たないクエリでは、既定でクロス パーティション クエリの実行が試行されます。

クエリの結果は反復処理できますが、クエリの生出力は非同期反復子を返します。 つまり、反復子の各オブジェクトは待機可能なオブジェクトであり、真のクエリ結果がまだ含まれていません。 クエリ結果を取得するには、非同期 for ループを使用します。このループは、オブジェクトを反復処理するときに各結果を待機するか、非同期反復子を反復処理するときに各クエリ結果を手動で待機します。

クエリ結果は非同期反復子であるため、リストに直接キャストすることはできません。代わりに、結果からリストを作成する必要がある場合は、非同期 for ループまたは Python のリスト理解を使用してリストを設定します。

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

async def create_lists():
    results = container.query_items(
            query='SELECT * FROM products p WHERE p.productModel = "Model 2"')

    # iterates on "results" iterator to asynchronously create a complete list of the actual query results

    item_list = []
    async for item in results:
        item_list.append(item)

    # Asynchronously creates a complete list of the actual query results. This code performs the same action as the for-loop example above.
    item_list = [item async for item in results]
    await client.close()

統合キャッシュの使用

統合キャッシュはメモリ内キャッシュであり、要求量の増加に合わせて管理可能なコストと低待機時間を確保するのに役立ちます。 統合キャッシュには、ポイント読み取り用の項目キャッシュとクエリ用のクエリ キャッシュという 2 つの部分があります。 次のコード スニペットは、ポイント読み取りおよびクエリ キャッシュ メソッドでこの機能を使用する方法を示しています。

これを使用する利点は、統合キャッシュにヒットしたポイントの読み取りとクエリで RU が使用されない点です。 つまり、バックエンドからの読み取りよりも操作ごとのコストがはるかに低くなります。

Azure Cosmos DB 統合キャッシュを構成する方法 (プレビュー)

import azure.cosmos.cosmos_client as cosmos_client
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = cosmos_client.CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)

def integrated_cache_snippet():
    item_id = body['id'] 
    query = 'SELECT * FROM c'

    #item cache
    container.read_item(item=item_id, partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

    #query cache   
    container.query_items(query=query,
         partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

統合キャッシュの詳細については、「 Azure Cosmos DB 統合キャッシュ - 概要」を参照してください。

トラブルシューティング

全般

Python SDK を使用して Cosmos DB を操作する場合、サービスによって返される例外は、REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。

Azure Cosmos DB の HTTP 状態コード

たとえば、Cosmos DB データベースで既に使用されている ID (名前) を使用してコンテナーを作成しようとすると、 409 競合を示すエラーが返されます。 次のスニペットでは、例外をキャッチし、エラーに関する追加情報を表示することで、エラーが適切に処理されます。

try:
    database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    print("""Error creating container
HTTP status code 409: The ID (name) provided for the container is already in use.
The container name must be unique within the database.""")

ログの記録

このライブラリでは、ログ記録に標準 のログ ライブラリが使用されます。 HTTP セッションに関する基本情報 (URL、ヘッダーなど) は INFO レベルでログに記録されます。

要求/応答本文、未変換ヘッダーなど、詳細な DEBUG レベルのログは、 引数を使用してクライアントで logging_enable 有効にすることができます。

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

同様に、logging_enable は、詳細なログ記録がクライアントで有効になっていない場合でも、1 回の操作のために有効にすることができます。

database = client.create_database(DATABASE_NAME, logging_enable=True)

または、ロガーを 引数に渡すことで、Azure コア HttpLoggingPolicy から拡張される CosmosHttpLoggingPolicy を使用してログを logger 記録することもできます。 既定では、HttpLoggingPolicy の動作が使用されます。 引数を enable_diagnostics_logging 渡すと、CosmosHttpLoggingPolicy が有効になり、Cosmos の問題のデバッグに関連する追加情報が応答に含まれます。

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

同様に、ロガーを単一の要求に渡すことで、1 つの操作に対してログ記録を有効にできます。 ただし、CosmosHttpLoggingPolicy を使用して追加情報を取得する場合は、 enable_diagnostics_logging クライアント コンストラクターで引数を渡す必要があります。

# This example enables the CosmosHttpLoggingPolicy and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

テレメトリ

Azure Core には、Python SDK で OpenTelemetry を使用する機能が用意されています。 この機能を使用するためにインストールする必要があるパッケージは次だけです。

pip install azure-core-tracing-opentelemetry
pip install opentelemetry-sdk

この詳細については、Azure Core で設定方法を説明したこの ドキュメント を参照することをお勧めします。 また、SDK で使用する方法を示す サンプル ファイル も追加しました。 これは、使用している Cosmos クライアントに関係なく、同じように動作します。

次のステップ

Cosmos DB サービスに関するさらに詳細なドキュメントについては、docs.microsoft.com にある Azure Cosmos DB のドキュメントを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。