次の方法で共有

DatabaseProxy クラス

  • リファレンス

特定のデータベースと対話するためのインターフェイス。

このクラスを直接インスタンス化しないでください。 代わりに、 メソッドを使用します <xref:CosmosClient.get_database_client> 。

データベースには 1 つ以上のコンテナーが含まれており、それぞれに項目、ストアド プロシージャ、トリガー、およびユーザー定義関数を含めることができます。

データベースには関連付けられたユーザーを含めることもできます。各ユーザーは、特定のコンテナー、ストアド プロシージャ、トリガー、ユーザー定義関数、または項目にアクセスするための一連のアクセス許可で構成されます。

Azure Cosmos DB SQL API データベースには、システムによって生成される次のプロパティがあります。 これらのプロパティは読み取り専用です。

  • _rid: リソース ID。

  • _ts: リソースが最後に更新された日時。 値は、タイムスタンプです。

  • _self: リソースの一意のアドレス指定可能な URI。

  • _etag: オプティミスティック コンカレンシー制御に必要なリソース etag。

  • _colls: コレクション リソースのアドレス指定可能なパス。

  • _users: ユーザー リソースのアドレス指定可能なパス。

継承
builtins.object
DatabaseProxy

コンストラクター

DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)

パラメーター

client_connection
<xref:ClientSession>
必須

このデータベースの取得元のクライアント。

id
str
必須

データベースの ID (名前)。

properties
既定値: None

変数

id

データベースの ID (名前)。

メソッド

create_container

指定した ID (名前) を使用して新しいコンテナーを作成します。

指定された ID を持つコンテナーが既に存在する場合は、CosmosResourceExistsError が発生します。
create_container_if_not_exists

コンテナーがまだ存在しない場合は作成します。

コンテナーが既に存在する場合は、既存の設定が返されます。 注: メソッドに渡されたものと異なる場合、既存のコンテナー設定をチェックまたは更新したり、スループットを提供したりすることはありません。
create_user

コンテナーに新しいユーザーを作成します。

既存のユーザーを更新または置換するには、 メソッドを使用します <xref:ContainerProxy.upsert_user> 。
delete_container

コンテナーを削除します。
delete_user

指定したユーザーをコンテナーから削除します。
get_container_client

指定した ID (名前) を持つコンテナーの ContainerProxy を取得します。
get_throughput

このデータベースの ThroughputProperties オブジェクトを取得します。 データベースに対して ThroughputProperties が既に存在しない場合は、例外が発生します。 :キーワード (keyword) 呼び出し可能なresponse_hook: 応答メタデータを使用して呼び出される呼び出し可能。 :returns: データベースの ThroughputProperties。 :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: コンテナーまたは

スループット プロパティを取得できませんでした。
get_user_client

指定した ID を持つユーザーの UserProxy を取得します。
list_containers

データベース内のコンテナーを一覧表示します。
list_users

コンテナー内のすべてのユーザーを一覧表示します。
query_containers

現在のデータベース内のコンテナーのプロパティを一覧表示します。
query_users

指定されたクエリに一致するすべてのユーザーを返 します。
read

データベースのプロパティを読み取る。
read_offer

このデータベースの ThroughputProperties オブジェクトを取得します。 データベースに対して ThroughputProperties が既に存在しない場合は、例外が発生します。 :キーワード (keyword) 呼び出し可能なresponse_hook: 応答メタデータを使用して呼び出される呼び出し可能。 :returns: データベースの ThroughputProperties。 :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: コンテナーまたは

スループット プロパティを取得できませんでした。
replace_container

コンテナーのプロパティをリセットします。

プロパティの変更は直ちに永続化されます。 指定されていないプロパティは、既定値にリセットされます。
replace_throughput

データベース レベルのスループットを置き換えます。
replace_user

指定したユーザーがコンテナーに存在する場合は、そのユーザーを置き換えます。
upsert_user

指定したユーザーを挿入または更新します。

ユーザーがコンテナーに既に存在する場合は、置き換えられます。 ユーザーがまだ存在しない場合は、挿入されます。

create_container

指定した ID (名前) を使用して新しいコンテナーを作成します。

指定された ID を持つコンテナーが既に存在する場合は、CosmosResourceExistsError が発生します。

create_container(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

パラメーター

id
必須

作成するコンテナーの ID (名前)。

partition_key
必須

コンテナーに使用するパーティション キー。

indexing_policy
必須

コンテナーに適用するインデックス作成ポリシー。

default_ttl
必須

コンテナー内の項目の既定の有効期間 (TTL)。 指定しない場合、アイテムは期限切れになりません。

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

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

unique_key_policy
必須

コンテナーに適用する一意のキー ポリシー。

conflict_resolution_policy
必須

コンテナーに適用する競合解決ポリシー。

session_token
str

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

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

etag で使用する一致条件。

response_hook
Callable

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

analytical_storage_ttl
int

コンテナー内のアイテムの分析ストアの有効期間 (TTL)。 値 None を指定すると、分析ストレージはオフになり、値 -1 は TTL なしで分析ストレージをオンにします。 分析ストレージは、Synapse Link有効なアカウントでのみ有効にできることに注意してください。

戻り値

新しいコンテナーを表す ContainerProxy インスタンス。

の戻り値の型 :

ContainerProxy

例外

CosmosHttpResponseError

コンテナーの作成に失敗しました。

例

既定の設定でコンテナーを作成します。


   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)

特定の設定を使用してコンテナーを作成します。この場合、カスタム パーティション キー:


   customer_container_name = "customers"
   try:
       customer_container = database.create_container(
           id=customer_container_name,
           partition_key=PartitionKey(path="/city"),
           default_ttl=200,
       )
   except exceptions.CosmosResourceExistsError:
       customer_container = database.get_container_client(customer_container_name)

create_container_if_not_exists

コンテナーがまだ存在しない場合は作成します。

コンテナーが既に存在する場合は、既存の設定が返されます。 注: メソッドに渡されたものと異なる場合、既存のコンテナー設定をチェックまたは更新したり、スループットを提供したりすることはありません。

create_container_if_not_exists(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

パラメーター

id
必須

読み取りまたは作成するコンテナーの ID (名前)。

partition_key
必須

コンテナーに使用するパーティション キー。

indexing_policy
必須

コンテナーに適用するインデックス作成ポリシー。

default_ttl
必須

コンテナー内の項目の既定の有効期間 (TTL)。 指定しない場合、アイテムは期限切れになりません。

populate_query_metrics
必須

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

offer_throughput
必須

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

unique_key_policy
必須

コンテナーに適用する一意のキー ポリシー。

conflict_resolution_policy
必須

コンテナーに適用する競合解決ポリシー。

session_token
str

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

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

etag で使用する一致条件。

response_hook
Callable

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

analytical_storage_ttl
int

コンテナー内のアイテムの分析ストアの有効期間 (TTL)。 値 None を指定すると、分析ストレージはオフになり、値 -1 は TTL なしで分析ストレージをオンにします。 分析ストレージは、Synapse Link有効なアカウントでのみ有効にできることに注意してください。

戻り値

コンテナーを表す ContainerProxy インスタンス。

の戻り値の型 :

ContainerProxy

例外

CosmosHttpResponseError

コンテナーの読み取りまたは作成に失敗しました。

create_user

コンテナーに新しいユーザーを作成します。

既存のユーザーを更新または置換するには、 メソッドを使用します <xref:ContainerProxy.upsert_user> 。

create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

パラメーター

body
必須

作成するユーザーを表す id キーと値を持つ dict に似たオブジェクト。 ユーザー ID はデータベース内で一意である必要があり、255 文字以内で構成されている必要があります。

response_hook
Callable

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

戻り値

新しいユーザーを表す UserProxy インスタンス。

の戻り値の型 :

UserProxy

例外

CosmosHttpResponseError

指定されたユーザーを作成できなかった場合。

例

データベース ユーザーを作成します。


   try:
       database.create_user(dict(id="Walter Harp"))
   except exceptions.CosmosResourceExistsError:
       print("A user with that ID already exists.")
   except exceptions.CosmosHttpResponseError as failure:
       print("Failed to create user. Status code:{}".format(failure.status_code))

delete_container

コンテナーを削除します。

delete_container(container: str | ContainerProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None

パラメーター

container
必須

削除するコンテナーの ID (名前)。 削除するコンテナーの ID、コンテナーのプロパティを <xref:azure.cosmos.database.ContainerProxy> 表すインスタンスまたはディクテーションを渡すことができます。

session_token
str

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

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

etag で使用する一致条件。

response_hook
Callable

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

の戻り値の型 :

None

例外

CosmosHttpResponseError

コンテナーを削除できなかった場合。

delete_user

指定したユーザーをコンテナーから削除します。

delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> None

パラメーター

user
必須

ID (名前)、削除するユーザーのプロパティまたは <xref:azure.cosmos.database.UserProxy> インスタンスを表す dict。

response_hook
Callable

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

の戻り値の型 :

None

例外

CosmosHttpResponseError

ユーザーが正常に削除されませんでした。

CosmosResourceNotFoundError

ユーザーがコンテナーに存在しません。

get_container_client

指定した ID (名前) を持つコンテナーの ContainerProxy を取得します。

get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxy

パラメーター

container
必須

取得するコンテナーのプロパティを <xref:azure.cosmos.database.ContainerProxy> 表すコンテナー、インスタンス、または dict の ID (名前)。

戻り値

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

の戻り値の型 :

ContainerProxy

例外

CosmosHttpResponseError

コンテナーの作成に失敗しました。

例

既存のコンテナーを取得し、発生した場合にエラーを処理します。


   database = client.get_database_client(database_name)
   container = database.get_container_client(container_name)

get_throughput

このデータベースの ThroughputProperties オブジェクトを取得します。 データベースに対して ThroughputProperties が既に存在しない場合は、例外が発生します。 :キーワード (keyword) 呼び出し可能なresponse_hook: 応答メタデータを使用して呼び出される呼び出し可能。 :returns: データベースの ThroughputProperties。 :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: コンテナーまたは

スループット プロパティを取得できませんでした。

get_throughput(**kwargs: Any) -> ThroughputProperties

の戻り値の型 :

ThroughputProperties

例外

CosmosHttpResponseError

コンテナーの作成に失敗しました。

get_user_client

指定した ID を持つユーザーの UserProxy を取得します。

get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxy

パラメーター

user
必須

取得するユーザーのプロパティまたは <xref:azure.cosmos.database.UserProxy> インスタンスを表す ID (名前)。

戻り値

取得したユーザーを表す UserProxy インスタンス。

の戻り値の型 :

UserProxy

例外

CosmosHttpResponseError

コンテナーの作成に失敗しました。

list_containers

データベース内のコンテナーを一覧表示します。

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

パラメーター

max_item_count
必須

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

session_token
str

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

initial_headers
dict[str,str]

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

response_hook
Callable

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

戻り値

コンテナー プロパティ (ディクテーション) の Iterable。

の戻り値の型 :

Iterable[dict[str, Any]]

例外

CosmosHttpResponseError

コンテナーの作成に失敗しました。

例

データベース内のすべてのコンテナーを一覧表示します。


   database = client.get_database_client(database_name)
   for container in database.list_containers():
       print("Container ID: {}".format(container['id']))

list_users

コンテナー内のすべてのユーザーを一覧表示します。

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

パラメーター

max_item_count
必須

列挙操作で返されるユーザーの最大数。

response_hook
Callable

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

戻り値

ユーザー プロパティ (ディクテーション) の Iterable。

の戻り値の型 :

Iterable[dict[str, Any]]

例外

CosmosHttpResponseError

コンテナーの作成に失敗しました。

query_containers

現在のデータベース内のコンテナーのプロパティを一覧表示します。

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

パラメーター

query
必須

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

parameters
必須

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

max_item_count
必須

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

session_token
str

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

initial_headers
dict[str,str]

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

response_hook
Callable

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

戻り値

コンテナー プロパティ (ディクテーション) の Iterable。

の戻り値の型 :

Iterable[dict[str, Any]]

例外

CosmosHttpResponseError

コンテナーの作成に失敗しました。

query_users

指定されたクエリに一致するすべてのユーザーを返 します。

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

パラメーター

query
必須

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

parameters
必須

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

max_item_count
必須

列挙操作で返されるユーザーの最大数。

response_hook
Callable

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

戻り値

ユーザー プロパティ (ディクテーション) の Iterable。

の戻り値の型 :

Iterable[str, Any]

例外

CosmosHttpResponseError

コンテナーの作成に失敗しました。

read

データベースのプロパティを読み取る。

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

パラメーター

session_token
str

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

initial_headers
dict[str,str]

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

response_hook
Callable

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

の戻り値の型 :

Dict[<xref:Str>, Any]

例外

CosmosHttpResponseError

指定されたデータベースを取得できなかった場合。

read_offer

このデータベースの ThroughputProperties オブジェクトを取得します。 データベースに対して ThroughputProperties が既に存在しない場合は、例外が発生します。 :キーワード (keyword) 呼び出し可能なresponse_hook: 応答メタデータを使用して呼び出される呼び出し可能。 :returns: データベースの ThroughputProperties。 :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: コンテナーまたは

スループット プロパティを取得できませんでした。

read_offer(**kwargs: Any) -> ThroughputProperties

の戻り値の型 :

ThroughputProperties

例外

CosmosHttpResponseError

コンテナーの作成に失敗しました。

replace_container

コンテナーのプロパティをリセットします。

プロパティの変更は直ちに永続化されます。 指定されていないプロパティは、既定値にリセットされます。

replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> ContainerProxy

パラメーター

container
必須

ID (名前)、置換するコンテナーのプロパティまたは <xref:azure.cosmos.database.ContainerProxy> インスタンスを表す dict。

partition_key
必須

コンテナーに使用するパーティション キー。

indexing_policy
必須

コンテナーに適用するインデックス作成ポリシー。

default_ttl
必須

コンテナー内の項目の既定の有効期間 (TTL)。 指定しない場合、アイテムは期限切れになりません。

conflict_resolution_policy
必須

コンテナーに適用する競合解決ポリシー。

populate_query_metrics
必須

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

session_token
str

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

etag
str

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

match_condition
MatchConditions

etag で使用する一致条件。

initial_headers
dict[str,str]

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

response_hook
Callable

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

analytical_storage_ttl
int

コンテナー内のアイテムの分析ストアの有効期間 (TTL)。 値 None を指定すると、分析ストレージはオフになり、値 -1 は TTL なしで分析ストレージをオンにします。 分析ストレージは、Synapse Link有効なアカウントでのみ有効にできることに注意してください。

戻り値

置換が完了した後のコンテナーを表す ContainerProxy インスタンス。

の戻り値の型 :

ContainerProxy

例外

CosmosHttpResponseError

コンテナーを置き換えられなかった場合に発生します。 これには、指定された ID を持つコンテナーが存在しない場合が含まれます。

例

コンテナーの TTL プロパティをリセットし、更新されたプロパティを表示します。


   # Set the TTL on the container to 3600 seconds (one hour)
   database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

   # Display the new TTL setting for the container
   container_props = database.get_container_client(container_name).read()
   print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))

replace_throughput

データベース レベルのスループットを置き換えます。

replace_throughput(throughput: int | ThroughputProperties | None, **kwargs: Any) -> ThroughputProperties

パラメーター

throughput
必須

設定するスループット (整数)。

response_hook
Callable

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

戻り値

新しいスループットで更新されたデータベースの ThroughputProperties。

の戻り値の型 :

ThroughputProperties

例外

CosmosHttpResponseError

データベースのスループット プロパティが存在しない場合、またはスループット プロパティを更新できなかった場合。

replace_user

指定したユーザーがコンテナーに存在する場合は、そのユーザーを置き換えます。

replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxy

パラメーター

user
必須

置き換えるユーザーのプロパティまたは <xref:azure.cosmos.database.UserProxy> インスタンスを表す ID (名前)、dict。

body
必須

置換するユーザーを表す dict に似たオブジェクト。

response_hook
Callable

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

戻り値

置換後のユーザーを表す UserProxy インスタンスが完了しました。

の戻り値の型 :

UserProxy

例外

CosmosHttpResponseError

置換に失敗した場合、または指定された ID を持つユーザーが存在しない場合。

upsert_user

指定したユーザーを挿入または更新します。

ユーザーがコンテナーに既に存在する場合は、置き換えられます。 ユーザーがまだ存在しない場合は、挿入されます。

upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

パラメーター

body
必須

更新または挿入するユーザーを表す dict に似たオブジェクト。

response_hook
Callable

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

戻り値

アップサートされたユーザーを表す UserProxy インスタンス。

の戻り値の型 :

UserProxy

例外

CosmosHttpResponseError

指定されたユーザーをアップサートできなかった場合。