CosmosClient クラス

Azure Cosmos DB アカウントのクライアント側の論理表現。

このクライアントを使用して、Azure Cosmos DB サービスに対する要求を構成して実行します。

アプリケーションの有効期間ごとに CosmosClient の 1 つのインスタンスを維持することをお勧めします。これにより、効率的な接続管理とパフォーマンスが可能になります。

CosmosClient の初期化は負荷の高い操作です。資格情報やネットワーク接続の検証には、初期化 CosmosClient インスタンスを使用しないでください。

新しい CosmosClient をインスタンス化します。

継承

builtins.object

CosmosClient

コンストラクター

CosmosClient(url: str, credential: str | Dict[str, str] | TokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

パラメーター

url

str

必須

Cosmos DB アカウントの URL。

credential

Union[str, Dict[str, str], AsyncTokenCredential]

必須

アカウント キー、またはリソース トークンのディクショナリを指定できます。

consistency_level

str

セッションに使用する整合性レベル。 既定値は None (アカウント レベル) です。 整合性レベルと考えられる値の詳細: https://aka.ms/cosmos-consistency-levels

timeout

int

HTTP 要求と応答を組み合わせた処理の絶対タイムアウト (秒単位)。

connection_timeout

int

HTTP 要求のタイムアウト (秒単位)。

connection_mode

str

クライアントの接続モード - 現在、'Gateway' のみがサポートされています。

proxy_config

ProxyConfiguration

接続プロキシの構成。

ssl_config

SSLConfiguration

接続 SSL 構成。

connection_verify

bool

接続を確認するかどうか、既定値は True です。

connection_cert

str

接続を確認するための代替証明書。

retry_total

int

再試行の最大回数。

retry_backoff_max

int

最大再試行待機時間 (秒単位)。

retry_fixed_interval

int

再試行間隔をミリ秒単位で修正しました。

retry_read

int

ソケットの読み取り再試行の最大数。

retry_connect

int

接続エラーの再試行の最大数。

retry_status

int

エラー状態コードに対する再試行の最大数。

retry_on_status_codes

list[int]

再試行する特定の状態コードの一覧。

retry_backoff_factor

float

再試行の間の待機時間を計算する要因。

enable_endpoint_discovery

bool

geo レプリケートされたデータベース アカウントのエンドポイント検出を有効にします。 (既定値 : True)

preferred_locations

list[str]

geo レプリケートされたデータベース アカウントの優先する場所。

enable_diagnostics_logging

bool

CosmosHttpLogging ポリシーを有効にします。 機能するには、ロガーと共に使用する必要があります。

logger

Logger

要求診断の収集に使用するロガー。 クライアント レベル (すべての要求をログに記録する) または単一の要求レベルで渡すことができます。 要求は INFO レベルでログに記録されます。

例

Cosmos DB クライアントの新しいインスタンスを作成します。

       async with CosmosClient(url, key) as client:

メソッド

close	CosmosClient のこのインスタンスを閉じます。
create_database	指定した ID (名前) を使用して新しいデータベースを作成します。
create_database_if_not_exists	データベースがまだ存在しない場合は、データベースを作成します。 データベースが既に存在する場合は、既存の設定が返されます。 ..note:: この関数は、既存のデータベース設定をチェックしたり、更新したり、渡されたものと異なる場合はスループットを提供したりしません。
delete_database	指定された ID (名前) を持つデータベースを削除します。
from_connection_string	接続文字列から CosmosClient インスタンスを作成します。 これは、Azure portalから取得できます。省略可能なキーワード (keyword)引数の完全な一覧については、CosmosClient コンストラクターに関するページを参照してください。
get_database_client	ID (名前) ID を持つ既存のデータベースを取得 します。
list_databases	Cosmos DB SQL データベース アカウント内のデータベースを一覧表示します。
query_databases	Cosmos DB SQL データベース アカウント内のデータベースに対してクエリを実行します。

close

CosmosClient のこのインスタンスを閉じます。

async close() -> None

create_database

指定した ID (名前) を使用して新しいデータベースを作成します。

async create_database(id: str, **kwargs: Any) -> DatabaseProxy

パラメーター

id

str

必須

作成するデータベースの ID (名前)。

offer_throughput

Union[int, ThroughputProperties]

このオファーのプロビジョニング済みスループット。

session_token

str

セッション整合性で使用するトークン。

initial_headers

dict[str, str]

要求の一部として送信される初期ヘッダー。

etag

str

ETag 値またはワイルドカード文字 (*)。 リソースが変更されたかどうかをチェックし、match_condition パラメーターで指定された条件に従って動作するために使用されます。

match_condition

MatchConditions

etag で使用する一致条件。

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

応答メタデータを使用して呼び出される呼び出し可能。

戻り値

新しいデータベースを表す DatabaseProxy インスタンス。

の戻り値の型 :

DatabaseProxy

例外

CosmosResourceExistsError

指定された ID を持つデータベースは既に存在します。

例

Cosmos DB アカウントでデータベースを作成します。

           database_name = "testDatabase"
           try:
               database = await client.create_database(id=database_name)
           except exceptions.CosmosResourceExistsError:
               database = client.get_database_client(database=database_name)

create_database_if_not_exists

データベースがまだ存在しない場合は、データベースを作成します。

データベースが既に存在する場合は、既存の設定が返されます。

..note:: この関数は、既存のデータベース設定をチェックしたり、更新したり、渡されたものと異なる場合はスループットを提供したりしません。

async create_database_if_not_exists(id: str, **kwargs: Any) -> DatabaseProxy

パラメーター

id

str

必須

読み取りまたは作成するデータベースの ID (名前)。

offer_throughput

Union[int, ThroughputProperties]

このオファーのプロビジョニング済みスループット。

session_token

str

セッション整合性で使用するトークン。

initial_headers

dict[str, str]

要求の一部として送信される初期ヘッダー。

etag

str

ETag 値またはワイルドカード文字 (*)。 リソースが変更されたかどうかをチェックし、match_condition パラメーターで指定された条件に従って動作するために使用されます。

match_condition

MatchConditions

etag で使用する一致条件。

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

応答メタデータを使用して呼び出される呼び出し可能。

戻り値

データベースを表す DatabaseProxy インスタンス。

の戻り値の型 :

DatabaseProxy

例外

CosmosHttpResponseError

データベースの読み取りまたは作成に失敗しました。

delete_database

指定された ID (名前) を持つデータベースを削除します。

async delete_database(database: str | DatabaseProxy | Dict[str, Any], **kwargs: Any) -> None

パラメーター

database

Union[str, DatabaseProxy, Dict[str, Any]]

必須

削除するデータベースのプロパティまたは DatabaseProxy インスタンスを表す ID (名前)、dict。

session_token

str

セッション整合性で使用するトークン。

initial_headers

dict[str, str]

要求の一部として送信される初期ヘッダー。

etag

str

ETag 値またはワイルドカード文字 (*)。 リソースが変更されたかどうかをチェックし、match_condition パラメーターで指定された条件に従って動作するために使用されます。

match_condition

MatchConditions

etag で使用する一致条件。

response_hook

Callable[[Dict[str, str]], None]

応答メタデータを使用して呼び出される呼び出し可能。

の戻り値の型 :

None

例外

CosmosHttpResponseError

データベースを削除できなかった場合。

from_connection_string

接続文字列から CosmosClient インスタンスを作成します。

これは、Azure portalから取得できます。省略可能なキーワード (keyword)引数の完全な一覧については、CosmosClient コンストラクターに関するページを参照してください。

from_connection_string(conn_str: str, *, credential: str | Dict[str, str] | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

パラメーター

conn_str

str

必須

接続文字列。

credential

Union[str, Dict[str, str]]

接続文字列で指定されたキーの代わりに使用する代替資格情報。

consistency_level

str

セッションに使用する整合性レベル。 既定値は None (アカウント レベル) です。 整合性レベルと考えられる値の詳細: https://aka.ms/cosmos-consistency-levels

戻り値

CosmosClient インスタンス

の戻り値の型 :

CosmosClient

get_database_client

ID (名前) ID を持つ既存のデータベースを取得 します。

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

パラメーター

database

Union[str, DatabaseProxy, Dict[str, Any]]

必須

取得するデータベースのプロパティまたは DatabaseProxy インスタンスを表す ID (名前)、dict。

戻り値

取得したデータベースを表す DatabaseProxy インスタンス。

の戻り値の型 :

DatabaseProxy

list_databases

Cosmos DB SQL データベース アカウント内のデータベースを一覧表示します。

list_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

パラメーター

max_item_count

int

列挙操作で返されるアイテムの最大数。

session_token

str

セッション整合性で使用するトークン。

initial_headers

dict[str, str]

要求の一部として送信される初期ヘッダー。

response_hook

Callable[[Dict[str, str]], None]

応答メタデータを使用して呼び出される呼び出し可能。

戻り値

データベース プロパティ (dicts) の AsyncItemPaged。

の戻り値の型 :

<xref:AsyncItemPaged>[Dict[str, str]]

query_databases

Cosmos DB SQL データベース アカウント内のデータベースに対してクエリを実行します。

query_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

パラメーター

query

Union[str, Dict[str, Any]]

実行する Azure Cosmos DB SQL クエリ。

parameters

List[Dict[str, Any]]

クエリに対するパラメーターの省略可能な配列。 各パラメーターは、'name' キーと 'value' キーを持つ dict() です。

max_item_count

int

列挙操作で返されるアイテムの最大数。

session_token

str

セッション整合性で使用するトークン。

initial_headers

dict[str, str]

要求の一部として送信される初期ヘッダー。

response_hook

Callable[[Dict[str, str]], None]

応答メタデータを使用して呼び出される呼び出し可能。

戻り値

データベース プロパティ (dicts) の AsyncItemPaged。

の戻り値の型 :

<xref:AsyncItemPaged>[Dict[str, str]]