CosmosClient クラス

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

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

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

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

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

継承

builtins.object

CosmosClient

コンストラクター

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

パラメーター

url

str

必須

Cosmos DB アカウントの URL。

credential

Union[str, Dict[str, str], TokenCredential]

必須

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

consistency_level

str

既定値: None

セッションに使用する整合性レベル。 既定値は 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 クライアントの新しいインスタンスを作成します。

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

メソッド

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

create_database

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

create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

パラメーター

id

必須

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

offer_throughput

必須

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

session_token

str

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

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

etag で使用する一致条件。

response_hook

Callable

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

戻り値

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

の戻り値の型 :

DatabaseProxy

例外

CosmosResourceExistsError

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

例

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

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

create_database_if_not_exists

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

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

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

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

パラメーター

id

必須

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

populate_query_metrics

bool

必須

応答ヘッダーでクエリ メトリックの返しを有効にします。

offer_throughput

int または <xref:azure.cosmos.ThroughputProperties.>

必須

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

session_token

str

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

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

etag で使用する一致条件。

response_hook

Callable

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

戻り値

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

の戻り値の型 :

DatabaseProxy

例外

CosmosHttpResponseError

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

delete_database

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

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

パラメーター

database

str または dict(str, str) または DatabaseProxy

必須

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

session_token

str

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

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

etag で使用する一致条件。

response_hook

Callable

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

の戻り値の型 :

None

例外

CosmosHttpResponseError

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

from_connection_string

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

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

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

パラメーター

conn_str

str

必須

接続文字列。

credential

str または dict(str, str)

既定値: None

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

consistency_level

Optional[str]

既定値: None

セッションに使用する整合性レベル。 既定値は None (アカウント レベル) です。

例外

CosmosResourceExistsError

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

get_database_account

データベース アカウント情報を取得します。

get_database_account(**kwargs: Any) -> DatabaseAccount

パラメーター

response_hook

Callable

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

戻り値

Cosmos DB データベース アカウントを表す DatabaseAccount インスタンス。

の戻り値の型 :

DatabaseAccount

例外

CosmosResourceExistsError

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

get_database_client

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

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

パラメーター

database

str または dict(str, str) または DatabaseProxy

必須

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

戻り値

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

の戻り値の型 :

DatabaseProxy

例外

CosmosResourceExistsError

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

list_databases

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

list_databases(max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

パラメーター

max_item_count

int

必須

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

session_token

str

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

initial_headers

dict[str,str]

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

response_hook

Callable

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

戻り値

データベース プロパティ (ディクテーション) の Iterable。

の戻り値の型 :

Iterable[dict[str, str]]

例外

CosmosResourceExistsError

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

query_databases

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

query_databases(query: str | None = None, parameters: List[Dict[str, Any]] | None = None, enable_cross_partition_query: bool | None = None, max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

パラメーター

query

str

必須

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

parameters

List[Dict[str, Any]]

必須

クエリに対するパラメーターの省略可能な配列。 クエリが指定されていない場合は無視されます。

enable_cross_partition_query

bool

必須

要求されたパスでインデックス作成がオプトアウトされたクエリでスキャンを許可します。

max_item_count

int

必須

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

session_token

str

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

initial_headers

dict[str,str]

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

response_hook

Callable

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

戻り値

データベース プロパティ (ディクテーション) の Iterable。

の戻り値の型 :

Iterable[dict[str, str]]

例外

CosmosResourceExistsError

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