DatabaseProxy クラス
特定のデータベースと対話するためのインターフェイス。
このクラスは直接インスタンス化しないでください。 代わりに、 メソッドを <xref:azure.cosmos.aio.cosmos_client.CosmosClient.get_database_client> 使用して既存のデータベースを取得するか、 メソッドを <xref:azure.cosmos.aio.cosmos_client.CosmosClient.create_database> 使用して新しいデータベースを作成します。
データベースには 1 つ以上のコンテナーが含まれており、各コンテナーには項目、ストアド プロシージャ、トリガー、およびユーザー定義関数を含めることができます。
データベースには関連付けられたユーザーを含めることもできます。各ユーザーは、特定のコンテナー、ストアド プロシージャ、トリガー、ユーザー定義関数、または項目にアクセスするための一連のアクセス許可で構成されます。
Azure Cosmos DB SQL API データベースには、システムによって生成された次のプロパティがあります。 これらのプロパティは読み取り専用です。
_rid: リソース ID。
_ts: リソースが最後に更新された日時。 値は、タイムスタンプです。
_self: リソースの一意のアドレス指定可能な URI。
_etag: オプティミスティック コンカレンシー制御に必要なリソース etag。
_colls: コレクション リソースのアドレス指定可能なパス。
_users: ユーザー リソースのアドレス指定可能なパス。
- 継承
-
builtins.objectDatabaseProxy
コンストラクター
DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)パラメーター
- client_connection
- <xref:azure.cosmos.aio.CosmosClientConnection>
このデータベースの取得元のクライアント。
- properties
変数
- 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 が既に存在しない場合は、例外が発生します。 |
| get_user_client |
指定した ID を持つユーザーの UserProxy を取得します。 |
| list_containers |
データベース内のコンテナーを一覧表示します。 |
| list_users |
コンテナー内のすべてのユーザーを一覧表示します。 |
| query_containers |
現在のデータベース内のコンテナーのプロパティを一覧表示します。 |
| query_users |
指定されたクエリに一致するすべてのユーザーを返 します。 |
| read |
データベースのプロパティを読み取る。 |
| replace_container |
コンテナーのプロパティをリセットします。 プロパティの変更は直ちに永続化されます。 指定されていないプロパティは、既定値にリセットされます。 |
| replace_throughput |
データベース レベルのスループットを置き換えます。 データベースに対して ThroughputProperties が既に存在しない場合は、例外が発生します。 |
| replace_user |
指定したユーザーがコンテナーに存在する場合は、それを置き換えます。 |
| upsert_user |
指定したユーザーを挿入または更新します。 ユーザーがコンテナーに既に存在する場合は、置き換えられます。 ユーザーがまだ存在しない場合は、挿入されます。 |
create_container
指定した ID (名前) を使用して新しいコンテナーを作成します。
指定された ID を持つコンテナーが既に存在する場合は、CosmosResourceExistsError が発生します。
async create_container(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyパラメーター
- default_ttl
- int
コンテナー内の項目の既定の有効期間 (TTL)。 指定しない場合、アイテムは期限切れになりません。
- offer_throughput
- Union[int, ThroughputProperties]
このオファーのプロビジョニング済みスループット。
- session_token
- str
セッション整合性で使用するトークン。
- etag
- str
ETag 値またはワイルドカード文字 (*)。 リソースが変更されたかどうかをチェックし、match_condition パラメーターで指定された条件に従って動作するために使用されます。
- match_condition
- MatchConditions
etag で使用する一致条件。
- analytical_storage_ttl
- int
コンテナー内のアイテムの分析ストアの有効期間 (TTL)。 値 None を指定すると、分析ストレージはオフになり、値 -1 は TTL なしで分析ストレージをオンにします。 分析ストレージは、Synapse Link有効なアカウントでのみ有効にできることに注意してください。
戻り値
新しいコンテナーを表す ContainerProxy インスタンス。
の戻り値の型 :
例外
コンテナーの作成に失敗しました。
例
既定の設定でコンテナーを作成します。
container_name = "products"
try:
container = await 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 = await 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
コンテナーがまだ存在しない場合は作成します。
コンテナーが既に存在する場合は、既存の設定が返されます。 注: メソッドに渡されたものと異なる場合、既存のコンテナー設定をチェックまたは更新したり、スループットを提供したりすることはありません。
async create_container_if_not_exists(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyパラメーター
- default_ttl
- int
コンテナー内の項目の既定の有効期間 (TTL)。 指定しない場合、アイテムは期限切れになりません。
- offer_throughput
- Union[int, ThroughputProperties]
このオファーのプロビジョニング済みスループット。
- session_token
- str
セッション整合性で使用するトークン。
- etag
- str
ETag 値またはワイルドカード文字 (*)。 リソースが変更されたかどうかをチェックし、match_condition パラメーターで指定された条件に従って動作するために使用されます。
- match_condition
- MatchConditions
etag で使用する一致条件。
- analytical_storage_ttl
- int
コンテナー内のアイテムの分析ストアの有効期間 (TTL)。 値 None を指定すると、分析ストレージはオフになり、値 -1 は TTL なしで分析ストレージをオンにします。 分析ストレージは、Synapse Link有効なアカウントでのみ有効にできることに注意してください。
戻り値
新しいコンテナーを表す ContainerProxy インスタンス。
の戻り値の型 :
例外
コンテナーの作成に失敗しました。
create_user
コンテナーに新しいユーザーを作成します。
既存のユーザーを更新または置換するには、 メソッドを使用します <xref:ContainerProxy.upsert_user> 。
async create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyパラメーター
作成するユーザーを表す id キーと値を持つ dict に似たオブジェクト。 ユーザー ID はデータベース内で一意である必要があり、255 文字以内で構成されている必要があります。
戻り値
新しいユーザーを表す UserProxy インスタンス。
の戻り値の型 :
例外
指定されたユーザーを作成できなかった場合。
例
データベース ユーザーを作成します。
try:
await database.create_user(dict(id="Walter Harp"))
print("Created user 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
コンテナーを削除します。
async delete_container(container: str | ContainerProxy | Dict[str, Any], **kwargs: Any) -> Noneパラメーター
- container
- str または Dict[str, Any] または ContainerProxy
削除するコンテナーの ID (名前)。 削除するコンテナーの ID、コンテナーのプロパティを ContainerProxy 表すインスタンスまたはディクテーションを渡すことができます。
- session_token
- str
セッション整合性で使用するトークン。
- etag
- str
ETag 値またはワイルドカード文字 (*)。 リソースが変更されたかどうかをチェックし、match_condition パラメーターで指定された条件に従って動作するために使用されます。
- match_condition
- MatchConditions
etag で使用する一致条件。
の戻り値の型 :
例外
コンテナーを削除できなかった場合。
delete_user
指定したユーザーをコンテナーから削除します。
async delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> Noneパラメーター
の戻り値の型 :
例外
ユーザーが正常に削除されませんでした。
ユーザーがコンテナーに存在しません。
get_container_client
指定した ID (名前) を持つコンテナーの ContainerProxy を取得します。
get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxyパラメーター
取得するコンテナーのプロパティまたは ContainerProxy インスタンスを表す ID (名前)、dict。
戻り値
コンテナーを表す ContainerProxy インスタンス。
の戻り値の型 :
例外
コンテナーの作成に失敗しました。
例
既存のコンテナーを取得し、発生した場合はエラーを処理します。
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
get_throughput
このデータベースの ThroughputProperties オブジェクトを取得します。
データベースに対して ThroughputProperties が既に存在しない場合は、例外が発生します。
async get_throughput(**kwargs: Any) -> ThroughputPropertiesパラメーター
戻り値
データベースの ThroughputProperties。
の戻り値の型 :
例外
データベースのスループット プロパティが存在しないか、スループット プロパティを取得できませんでした。
get_user_client
指定した ID を持つユーザーの UserProxy を取得します。
get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxyパラメーター
戻り値
取得したユーザーを表す UserProxy インスタンス。
の戻り値の型 :
例外
コンテナーの作成に失敗しました。
list_containers
データベース内のコンテナーを一覧表示します。
list_containers(**kwargs) -> AsyncItemPaged[Dict[str, Any]]パラメーター
- max_item_count
- int
列挙操作で返されるアイテムの最大数。
- session_token
- str
セッション整合性で使用するトークン。
応答メタデータを使用して呼び出される呼び出し可能。
戻り値
コンテナー プロパティ (dicts) の AsyncItemPaged。
の戻り値の型 :
例外
コンテナーの作成に失敗しました。
例
データベース内のすべてのコンテナーを一覧表示します。
database = client.get_database_client(database_name)
async for container in database.list_containers():
print("Container ID: {}".format(container['id']))
list_users
コンテナー内のすべてのユーザーを一覧表示します。
list_users(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]パラメーター
- max_item_count
- int
列挙操作で返されるユーザーの最大数。
応答メタデータを使用して呼び出される呼び出し可能。
戻り値
ユーザー プロパティ (dicts) の AsyncItemPaged。
の戻り値の型 :
例外
コンテナーの作成に失敗しました。
query_containers
現在のデータベース内のコンテナーのプロパティを一覧表示します。
query_containers(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]パラメーター
クエリに対するパラメーターの省略可能な配列。 各パラメーターは、'name' キーと 'value' キーを持つ dict() です。
- max_item_count
- int
列挙操作で返されるアイテムの最大数。
- session_token
- str
セッション整合性で使用するトークン。
応答メタデータを使用して呼び出される呼び出し可能。
戻り値
コンテナー プロパティ (dicts) の AsyncItemPaged。
の戻り値の型 :
例外
コンテナーの作成に失敗しました。
query_users
指定されたクエリに一致するすべてのユーザーを返 します。
query_users(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]パラメーター
クエリに対するパラメーターの省略可能な配列。 各パラメーターは、'name' キーと 'value' キーを持つ dict() です。 クエリが指定されていない場合は無視されます。
- max_item_count
- int
列挙操作で返されるユーザーの最大数。
応答メタデータを使用して呼び出される呼び出し可能。
戻り値
ユーザー プロパティ (dicts) の AsyncItemPaged。
の戻り値の型 :
例外
コンテナーの作成に失敗しました。
read
データベースのプロパティを読み取る。
async read(**kwargs: Any) -> Dict[str, Any]パラメーター
- session_token
- str
セッション整合性で使用するトークン。
戻り値
データベースのプロパティを表す dict
の戻り値の型 :
例外
指定されたデータベースを取得できなかった場合。
replace_container
コンテナーのプロパティをリセットします。
プロパティの変更は直ちに永続化されます。 指定されていないプロパティは、既定値にリセットされます。
async replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyパラメーター
置き換えるコンテナーのプロパティまたは ContainerProxy インスタンスを表す ID (名前) を指定します。
- default_ttl
- int
コンテナー内の項目の既定の有効期間 (TTL)。 指定しない場合、アイテムの有効期限は切れません。
- session_token
- str
セッション整合性で使用するトークン。
- etag
- str
ETag 値またはワイルドカード文字 (*)。 リソースが変更されたかどうかをチェックし、match_condition パラメーターで指定された条件に従って動作するために使用されます。
- match_condition
- MatchConditions
etag で使用する一致条件。
- analytical_storage_ttl
- int
コンテナー内の項目の分析ストアの有効期間 (TTL)。 値 None を指定すると、分析ストレージはオフになり、値 -1 は TTL なしで分析ストレージをオンにします。 分析ストレージは、Synapse Link有効なアカウントでのみ有効にできることに注意してください。
戻り値
置換が完了した後のコンテナーを表す ContainerProxy インスタンス。
の戻り値の型 :
例外
コンテナーを置き換えられなかった場合に発生します。 これには、指定された ID を持つコンテナーが存在しない場合が含まれます。
例
コンテナーの TTL プロパティをリセットし、更新されたプロパティを表示します。
# Set the TTL on the container to 3600 seconds (one hour)
await database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)
# Display the new TTL setting for the container
container_props = await database.get_container_client(container_name).read()
print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))
replace_throughput
データベース レベルのスループットを置き換えます。
データベースに対して ThroughputProperties が既に存在しない場合は、例外が発生します。
async replace_throughput(throughput: int | ThroughputProperties, **kwargs: Any) -> ThroughputPropertiesパラメーター
戻り値
新しいスループットで更新されたデータベースの ThroughputProperties。
の戻り値の型 :
例外
データベースのスループット プロパティが存在しないか、スループット プロパティを更新できませんでした。
replace_user
指定したユーザーがコンテナーに存在する場合は、それを置き換えます。
async replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxyパラメーター
置き換えるユーザーのプロパティまたは UserProxy インスタンスを表す ID (名前) を指定します。
戻り値
置換後にユーザーを表す UserProxy インスタンスが実行されます。
の戻り値の型 :
例外
置換に失敗した場合、または指定された ID を持つユーザーが存在しない場合。
upsert_user
指定したユーザーを挿入または更新します。
ユーザーがコンテナーに既に存在する場合は、置き換えられます。 ユーザーがまだ存在しない場合は、挿入されます。
async upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyパラメーター
戻り値
アップサートされたユーザーを表す UserProxy インスタンス。
の戻り値の型 :
例外
指定されたユーザーをアップサートできなかった場合。
Azure SDK for Python
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示