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 インスタンス。

の戻り値の型 :

例外

指定された 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 インスタンス。

の戻り値の型 :

例外

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

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]

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

の戻り値の型 :

例外

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

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 インスタンス

の戻り値の型 :

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 インスタンス。

の戻り値の型 :

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]]