Udostępnij za pośrednictwem

DatabaseProxy Klasa

  • Odwołanie

Interfejs umożliwiający interakcję z określoną bazą danych.

Nie należy bezpośrednio utworzyć wystąpienia tej klasy. Zamiast tego użyj <xref:azure.cosmos.aio.cosmos_client.CosmosClient.get_database_client> metody , aby uzyskać istniejącą bazę danych lub <xref:azure.cosmos.aio.cosmos_client.CosmosClient.create_database> metodę tworzenia nowej bazy danych.

Baza danych zawiera co najmniej jeden kontener, z których każdy może zawierać elementy, procedury składowane, wyzwalacze i funkcje zdefiniowane przez użytkownika.

Baza danych może również mieć skojarzonych użytkowników, z których każdy jest skonfigurowany z zestawem uprawnień dostępu do określonych kontenerów, procedur składowanych, wyzwalaczy, funkcji zdefiniowanych przez użytkownika lub elementów.

Baza danych interfejsu API SQL usługi Azure Cosmos DB ma następujące właściwości wygenerowane przez system. Te właściwości są tylko do odczytu:

  • _rid: identyfikator zasobu.

  • _ts: kiedy zasób został ostatnio zaktualizowany. Wartość jest znacznikiem czasu.

  • _self: unikatowy adresowalny identyfikator URI zasobu.

  • _etag: tag zasobu wymagany do optymistycznej kontroli współbieżności.

  • _colls: adresowalna ścieżka zasobu kolekcji.

  • _users: ścieżka adresowa zasobu użytkowników.

Dziedziczenie
builtins.object
DatabaseProxy

Konstruktor

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

Parametry

client_connection
<xref:azure.cosmos.aio.CosmosClientConnection>
Wymagane

Klient, z którego pobrano tę bazę danych.

id
str
Wymagane

Identyfikator (nazwa) bazy danych.

properties
wartość domyślna: None

Zmienne

id

Identyfikator (nazwa) bazy danych.

Metody

create_container

Utwórz nowy kontener o podanym identyfikatorze (nazwie).

Jeśli kontener o danym identyfikatorze już istnieje, zostanie zgłoszony błąd CosmosResourceExistsError.
create_container_if_not_exists

Utwórz kontener, jeśli jeszcze nie istnieje.

Jeśli kontener już istnieje, zostaną zwrócone istniejące ustawienia. Uwaga: nie sprawdza ani nie aktualizuje istniejących ustawień kontenera ani nie oferuje przepływności, jeśli różnią się od tego, co zostało przekazane do metody.
create_user

Utwórz nowego użytkownika w kontenerze.

Aby zaktualizować lub zastąpić istniejącego użytkownika, użyj <xref:ContainerProxy.upsert_user> metody .
delete_container

Usuń kontener.
delete_user

Usuń określonego użytkownika z kontenera.
get_container_client

Pobierz kontener ContainerProxy dla kontenera o określonym identyfikatorze (nazwie).
get_throughput

Pobierz obiekt ThroughputProperties dla tej bazy danych.

Jeśli dla bazy danych nie istnieje już żadne właściwości przepływności, zgłaszany jest wyjątek.
get_user_client

Pobierz element UserProxy dla użytkownika o określonym identyfikatorze.
list_containers

Wyświetl listę kontenerów w bazie danych.
list_users

Wyświetl listę wszystkich użytkowników w kontenerze.
query_containers

Wyświetl listę właściwości kontenerów w bieżącej bazie danych.
query_users

Zwróć wszystkich użytkowników pasujących do danego zapytania.
read

Odczytywanie właściwości bazy danych.
replace_container

Zresetuj właściwości kontenera.

Zmiany właściwości są utrwalane natychmiast. Wszystkie nieokreślone właściwości zostaną zresetowane do wartości domyślnych.
replace_throughput

Zastąp przepływność na poziomie bazy danych.

Jeśli dla bazy danych nie ma już właściwości przepływności, zgłaszany jest wyjątek.
replace_user

Zastępuje określonego użytkownika, jeśli istnieje w kontenerze.
upsert_user

Wstaw lub zaktualizuj określonego użytkownika.

Jeśli użytkownik już istnieje w kontenerze, zostanie zastąpiony. Jeśli użytkownik jeszcze nie istnieje, zostanie wstawiony.

create_container

Utwórz nowy kontener o podanym identyfikatorze (nazwie).

Jeśli kontener o danym identyfikatorze już istnieje, zostanie zgłoszony błąd CosmosResourceExistsError.

async create_container(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxy

Parametry

id
str
Wymagane

Identyfikator (nazwa) kontenera do utworzenia.

partition_key
PartitionKey
Wymagane

Klucz partycji do użycia dla kontenera.

indexing_policy
dict[str, str]

Zasady indeksowania, które mają być stosowane do kontenera.

default_ttl
int

Domyślny czas wygaśnięcia (TTL) dla elementów w kontenerze. Jeśli nie zostanie określona, elementy nie wygasają.

offer_throughput
Union[int, ThroughputProperties]

Aprowizowana przepływność dla tej oferty.

unique_key_policy
dict[str, str]

Unikatowe zasady klucza do zastosowania do kontenera.

conflict_resolution_policy
dict[str, str]

Zasady rozwiązywania konfliktów, które mają być stosowane do kontenera.

session_token
str

Token do użycia z spójnością sesji.

initial_headers
dict[str, str]

Początkowe nagłówki, które mają być wysyłane w ramach żądania.

etag
str

Wartość ETag lub symbol wieloznaczny (*). Służy do sprawdzania, czy zasób uległ zmianie i działa zgodnie z warunkiem określonym przez parametr match_condition .

match_condition
MatchConditions

Warunek dopasowania do użycia na etagu.

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

Wywołanie wywoływane przy użyciu metadanych odpowiedzi.

analytical_storage_ttl
int

Czas przechowywania analitycznego na żywo (TTL) dla elementów w kontenerze. Wartość None pozostawia magazyn analityczny wyłączony, a wartość -1 włącza magazyn analityczny bez czasu wygaśnięcia. Należy pamiętać, że magazyn analityczny można włączyć tylko na kontach z włączoną obsługą Synapse Link.

Zwraca

Wystąpienie ContainerProxy reprezentujące nowy kontener.

Typ zwracany

ContainerProxy

Wyjątki

CosmosHttpResponseError

Tworzenie kontenera nie powiodło się.

Przykłady

Utwórz kontener z ustawieniami domyślnymi:


           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)

Utwórz kontener z określonymi ustawieniami; w tym przypadku niestandardowy klucz partycji:


           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

Utwórz kontener, jeśli jeszcze nie istnieje.

Jeśli kontener już istnieje, zostaną zwrócone istniejące ustawienia. Uwaga: nie sprawdza ani nie aktualizuje istniejących ustawień kontenera ani nie oferuje przepływności, jeśli różnią się od tego, co zostało przekazane do metody.

async create_container_if_not_exists(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxy

Parametry

id
str
Wymagane

Identyfikator (nazwa) kontenera do utworzenia.

partition_key
PartitionKey
Wymagane

Klucz partycji do użycia dla kontenera.

indexing_policy
dict[str, str]

Zasady indeksowania, które mają być stosowane do kontenera.

default_ttl
int

Domyślny czas wygaśnięcia (TTL) dla elementów w kontenerze. Jeśli nie zostanie określona, elementy nie wygasają.

offer_throughput
Union[int, ThroughputProperties]

Aprowizowana przepływność dla tej oferty.

unique_key_policy
dict[str, str]

Unikatowe zasady klucza do zastosowania do kontenera.

conflict_resolution_policy
dict[str, str]

Zasady rozwiązywania konfliktów, które mają być stosowane do kontenera.

session_token
str

Token do użycia z spójnością sesji.

initial_headers
dict[str, str]

Początkowe nagłówki, które mają być wysyłane w ramach żądania.

etag
str

Wartość ETag lub symbol wieloznaczny (*). Służy do sprawdzania, czy zasób uległ zmianie i działa zgodnie z warunkiem określonym przez parametr match_condition .

match_condition
MatchConditions

Warunek dopasowania do użycia na etagu.

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

Wywołanie wywoływane przy użyciu metadanych odpowiedzi.

analytical_storage_ttl
int

Czas przechowywania analitycznego na żywo (TTL) dla elementów w kontenerze. Wartość None pozostawia magazyn analityczny wyłączony, a wartość -1 włącza magazyn analityczny bez czasu wygaśnięcia. Należy pamiętać, że magazyn analityczny można włączyć tylko na kontach z włączoną obsługą Synapse Link.

Zwraca

Wystąpienie ContainerProxy reprezentujące nowy kontener.

Typ zwracany

ContainerProxy

Wyjątki

CosmosHttpResponseError

Tworzenie kontenera nie powiodło się.

create_user

Utwórz nowego użytkownika w kontenerze.

Aby zaktualizować lub zastąpić istniejącego użytkownika, użyj <xref:ContainerProxy.upsert_user> metody .

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

Parametry

body
Dict[str, Any]
Wymagane

Obiekt przypominający dykt z kluczem identyfikatora i wartością reprezentującą użytkownika do utworzenia. Identyfikator użytkownika musi być unikatowy w bazie danych i składać się z nie więcej niż 255 znaków.

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

Wywołanie wywoływane przy użyciu metadanych odpowiedzi.

Zwraca

Wystąpienie UserProxy reprezentujące nowego użytkownika.

Typ zwracany

UserProxy

Wyjątki

CosmosHttpResponseError

Jeśli nie można utworzyć danego użytkownika.

Przykłady

Utwórz użytkownika bazy danych:


           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

Usuń kontener.

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

Parametry

container
str lub Dict[str, Any] lub ContainerProxy
Wymagane

Identyfikator (nazwa) kontenera do usunięcia. Możesz przekazać identyfikator kontenera do usunięcia, ContainerProxy wystąpienia lub dyktu reprezentującego właściwości kontenera.

session_token
str

Token do użycia z spójnością sesji.

initial_headers
dict[str, str]

Początkowe nagłówki, które mają być wysyłane w ramach żądania.

etag
str

Wartość ETag lub symbol wieloznaczny (*). Służy do sprawdzania, czy zasób uległ zmianie i działa zgodnie z warunkiem określonym przez parametr match_condition .

match_condition
MatchConditions

Warunek dopasowania do użycia na etagu.

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

Wywołanie wywoływane przy użyciu metadanych odpowiedzi.

Typ zwracany

None

Wyjątki

CosmosHttpResponseError

Jeśli nie można usunąć kontenera.

delete_user

Usuń określonego użytkownika z kontenera.

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

Parametry

user
Union[str, Dict[str, Any], UserProxy]
Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub UserProxy wystąpienie użytkownika do usunięcia.

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

Wywołanie wywoływane przy użyciu metadanych odpowiedzi.

Typ zwracany

None

Wyjątki

CosmosHttpResponseError

Użytkownik nie został pomyślnie usunięty.

CosmosResourceNotFoundError

Użytkownik nie istnieje w kontenerze.

get_container_client

Pobierz kontener ContainerProxy dla kontenera o określonym identyfikatorze (nazwie).

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

Parametry

container
Union[str, Dict[str, Any], ContainerProxy]
Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub ContainerProxy wystąpienie kontenera do pobrania.

Zwraca

Wystąpienie ContainerProxy reprezentujące kontener.

Typ zwracany

ContainerProxy

Wyjątki

CosmosHttpResponseError

Tworzenie kontenera nie powiodło się.

Przykłady

Pobierz istniejący kontener, który obsługuje błąd, jeśli wystąpią:


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

get_throughput

Pobierz obiekt ThroughputProperties dla tej bazy danych.

Jeśli dla bazy danych nie istnieje już żadne właściwości przepływności, zgłaszany jest wyjątek.

async get_throughput(**kwargs: Any) -> ThroughputProperties

Parametry

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

Wywoływany element z metadanymi odpowiedzi.

Zwraca

PrzepływnośćWłaściwości dla bazy danych.

Typ zwracany

ThroughputProperties

Wyjątki

CosmosHttpResponseError

Nie ma właściwości przepływności dla bazy danych lub nie można pobrać właściwości przepływności.

get_user_client

Pobierz element UserProxy dla użytkownika o określonym identyfikatorze.

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

Parametry

user
Union[str, Dict[str, Any], UserProxy]
Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub UserProxy wystąpienie użytkownika do pobrania.

Zwraca

Wystąpienie UserProxy reprezentujące pobranego użytkownika.

Typ zwracany

UserProxy

Wyjątki

CosmosHttpResponseError

Tworzenie kontenera nie powiodło się.

list_containers

Wyświetl listę kontenerów w bazie danych.

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

Parametry

max_item_count
int

Maksymalna liczba elementów do zwrócenia w operacji wyliczania.

session_token
str

Token do użycia ze spójnością sesji.

initial_headers
dict[str, str]

Początkowe nagłówki, które mają być wysyłane w ramach żądania.

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Element AsyncItemPaged właściwości kontenera (dicts).

Typ zwracany

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

Wyjątki

CosmosHttpResponseError

Tworzenie kontenera nie powiodło się.

Przykłady

Wyświetl listę wszystkich kontenerów w bazie danych:


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

list_users

Wyświetl listę wszystkich użytkowników w kontenerze.

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

Parametry

max_item_count
int

Maksymalna liczba użytkowników do zwrócenia w operacji wyliczania.

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Element AsyncItemPaged właściwości użytkownika (dykt).

Typ zwracany

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

Wyjątki

CosmosHttpResponseError

Tworzenie kontenera nie powiodło się.

query_containers

Wyświetl listę właściwości kontenerów w bieżącej bazie danych.

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

Parametry

query
Union[str, Dict[str, Any]]

Zapytanie SQL usługi Azure Cosmos DB do wykonania.

parameters
Optional[List[Dict[str, Any]]]

Opcjonalna tablica parametrów zapytania. Każdy parametr jest dict() z kluczami "name" i "value".

max_item_count
int

Maksymalna liczba elementów do zwrócenia w operacji wyliczania.

session_token
str

Token do użycia ze spójnością sesji.

initial_headers
dict[str, str]

Początkowe nagłówki, które mają być wysyłane w ramach żądania.

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Element AsyncItemPaged właściwości kontenera (dicts).

Typ zwracany

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

Wyjątki

CosmosHttpResponseError

Tworzenie kontenera nie powiodło się.

query_users

Zwróć wszystkich użytkowników pasujących do danego zapytania.

query_users(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parametry

query
Union[str, Dict[str, Any]]
Wymagane

Zapytanie SQL usługi Azure Cosmos DB do wykonania.

parameters
Optional[List[Dict[str, Any]]]

Opcjonalna tablica parametrów zapytania. Każdy parametr jest dict() z kluczami "name" i "value". Ignorowane, jeśli nie podano kwerendy.

max_item_count
int

Maksymalna liczba użytkowników do zwrócenia w operacji wyliczania.

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Element AsyncItemPaged właściwości użytkownika (dykt).

Typ zwracany

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

Wyjątki

CosmosHttpResponseError

Tworzenie kontenera nie powiodło się.

read

Odczytywanie właściwości bazy danych.

async read(**kwargs: Any) -> Dict[str, Any]

Parametry

session_token
str

Token do użycia ze spójnością sesji.

initial_headers
dict[str, str]

Początkowe nagłówki, które mają być wysyłane w ramach żądania.

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

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Dykt reprezentujący właściwości bazy danych

Typ zwracany

Dict[str, Any]

Wyjątki

CosmosHttpResponseError

Jeśli nie można pobrać danej bazy danych.

replace_container

Zresetuj właściwości kontenera.

Zmiany właściwości są utrwalane natychmiast. Wszystkie nieokreślone właściwości zostaną zresetowane do wartości domyślnych.

async replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: PartitionKey, **kwargs: Any) -> ContainerProxy

Parametry

container
Union[str, Dict[str, Any], ContainerProxy]
Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub ContainerProxy wystąpienie kontenera do zastąpienia.

partition_key
PartitionKey
Wymagane

Klucz partycji do użycia dla kontenera.

indexing_policy
dict[str, str]

Zasady indeksowania, które mają być stosowane do kontenera.

default_ttl
int

Domyślny czas wygaśnięcia (TTL) dla elementów w kontenerze. Jeśli nie zostanie określona, elementy nie wygasną.

conflict_resolution_policy
dict[str, str]

Zasady rozwiązywania konfliktów, które mają być stosowane do kontenera.

session_token
str

Token do użycia ze spójnością sesji.

etag
str

Wartość elementu ETag lub symbol wieloznaczny (*). Służy do sprawdzania, czy zasób uległ zmianie i działa zgodnie z warunkiem określonym przez parametr match_condition .

match_condition
MatchConditions

Warunek dopasowania do użycia na etagu.

initial_headers
dict[str, str]

Początkowe nagłówki, które mają być wysyłane w ramach żądania.

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

Wywoływany element z metadanymi odpowiedzi.

analytical_storage_ttl
int

Czas wygaśnięcia magazynu analitycznego (TTL) dla elementów w kontenerze. Wartość None pozostawia magazyn analityczny wyłączony, a wartość -1 włącza magazyn analityczny bez czasu wygaśnięcia. Należy pamiętać, że magazyn analityczny można włączyć tylko na kontach z włączoną obsługą Synapse Link.

Zwraca

Wystąpienie ContainerProxy reprezentujące kontener po zakończeniu zamiany.

Typ zwracany

ContainerProxy

Wyjątki

CosmosHttpResponseError

Podniesione, jeśli nie można zamienić kontenera. Dotyczy to również tego, czy kontener o podanym identyfikatorze nie istnieje.

Przykłady

Zresetuj właściwość TTL w kontenerze i wyświetl zaktualizowane właściwości:


           # 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

Zastąp przepływność na poziomie bazy danych.

Jeśli dla bazy danych nie ma już właściwości przepływności, zgłaszany jest wyjątek.

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

Parametry

throughput
Union[int, ThroughputProperties]
Wymagane

Przepływność do ustawienia.

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

Wywoływany element z metadanymi odpowiedzi.

Zwraca

PrzepływnośćWłaściwości dla bazy danych, zaktualizowane o nową przepływność.

Typ zwracany

ThroughputProperties

Wyjątki

CosmosHttpResponseError

Nie ma właściwości przepływności dla bazy danych lub nie można zaktualizować właściwości przepływności.

replace_user

Zastępuje określonego użytkownika, jeśli istnieje w kontenerze.

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

Parametry

user
Union[str, Dict[str, Any], UserProxy]
Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub UserProxy wystąpienie użytkownika do zastąpienia.

body
Dict[str, Any]
Wymagane

Obiekt przypominający dykt reprezentujący użytkownika, który ma zastąpić.

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

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Wystąpienie UserProxy reprezentujące użytkownika po zastąpieniu przeszedł.

Typ zwracany

UserProxy

Wyjątki

CosmosHttpResponseError

Jeśli zamiana nie powiodła się lub użytkownik o podanym identyfikatorze nie istnieje.

upsert_user

Wstaw lub zaktualizuj określonego użytkownika.

Jeśli użytkownik już istnieje w kontenerze, zostanie zastąpiony. Jeśli użytkownik jeszcze nie istnieje, zostanie wstawiony.

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

Parametry

body
Dict[str, Any]
Wymagane

Obiekt przypominający dykt reprezentujący użytkownika w celu zaktualizowania lub wstawienia.

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

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Wystąpienie userProxy reprezentujące użytkownika upserted.

Typ zwracany

UserProxy

Wyjątki

CosmosHttpResponseError

Jeśli dany użytkownik nie może zostać rozbudowany.