DatabaseProxy Klasa

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

Nie należy bezpośrednio utworzyć wystąpienia tej klasy. Zamiast tego należy użyć <xref:CosmosClient.get_database_client> metody .

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 adresowy identyfikator URI zasobu.

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

  • _colls: ścieżka adresowa 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:ClientSession>
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ę one 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

Usuwanie kontenera.

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 ma już właściwości przepływności, zgłaszany jest wyjątek. :keyword Callable response_hook: Wywoływanie wywoływane z metadanymi odpowiedzi. :returns: PrzepływnośćWłaściwości dla bazy danych. :zgłasza błąd ~azure.cosmos.exceptions.CosmosHttpResponseError: nie ma właściwości przepływności dla kontenera 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.

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.

read_offer

Pobierz obiekt ThroughputProperties dla tej bazy danych. Jeśli dla bazy danych nie ma już właściwości przepływności, zgłaszany jest wyjątek. :keyword Callable response_hook: Wywoływanie wywoływane z metadanymi odpowiedzi. :returns: PrzepływnośćWłaściwości dla bazy danych. :zgłasza błąd ~azure.cosmos.exceptions.CosmosHttpResponseError: nie ma właściwości przepływności dla kontenera lub

nie można pobrać właściwości przepływności.

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.

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.

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

Parametry

id
Wymagane

Identyfikator (nazwa) kontenera do utworzenia.

partition_key
Wymagane

Klucz partycji do użycia dla kontenera.

indexing_policy
Wymagane

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

default_ttl
Wymagane

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

offer_throughput
int lub <xref:azure.cosmos.ThroughputProperties.>
Wymagane

Aprowizowana przepływność dla tej oferty.

unique_key_policy
Wymagane

Unikatowe zasady klucza, które mają być stosowane do kontenera.

conflict_resolution_policy
Wymagane

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

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.

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.

response_hook
Callable

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 nowy kontener.

Typ zwracany

Wyjątki

Tworzenie kontenera nie powiodło się.

Przykłady

Utwórz kontener z ustawieniami domyślnymi:


   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)

Tworzenie kontenera z określonymi ustawieniami; w tym przypadku niestandardowy klucz partycji:


   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

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ę one od tego, co zostało przekazane do metody.

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

Parametry

id
Wymagane

Identyfikator (nazwa) kontenera do odczytu lub utworzenia.

partition_key
Wymagane

Klucz partycji do użycia dla kontenera.

indexing_policy
Wymagane

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

default_ttl
Wymagane

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

populate_query_metrics
Wymagane

Włącz zwracanie metryk zapytania w nagłówkach odpowiedzi.

offer_throughput
Wymagane

Aprowizowana przepływność dla tej oferty.

unique_key_policy
Wymagane

Unikatowe zasady klucza, które mają być stosowane do kontenera.

conflict_resolution_policy
Wymagane

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

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.

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.

response_hook
Callable

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.

Typ zwracany

Wyjątki

Nie można odczytać lub utworzyć kontenera.

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 .

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

Parametry

body
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

Wywoływany element z metadanymi odpowiedzi.

Zwraca

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

Typ zwracany

Wyjątki

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

Przykłady

Tworzenie użytkownika bazy danych:


   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

Usuwanie kontenera.

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

Parametry

container
Wymagane

Identyfikator (nazwa) kontenera do usunięcia. Możesz przekazać identyfikator kontenera do usunięcia, <xref:azure.cosmos.database.ContainerProxy> wystąpienia lub dykt reprezentującego właściwości kontenera.

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.

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.

response_hook
Callable

Wywoływany element z metadanymi odpowiedzi.

Typ zwracany

Wyjątki

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

delete_user

Usuń określonego użytkownika z kontenera.

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

Parametry

user
Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub <xref:azure.cosmos.database.UserProxy> wystąpienie użytkownika do usunięcia.

response_hook
Callable

Wywoływany element z metadanymi odpowiedzi.

Typ zwracany

Wyjątki

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

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
Wymagane

Identyfikator (nazwa) kontenera, <xref:azure.cosmos.database.ContainerProxy> wystąpienia lub dykt reprezentujący właściwości kontenera do pobrania.

Zwraca

Wystąpienie ContainerProxy reprezentujące pobraną bazę danych.

Typ zwracany

Wyjątki

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 ma już właściwości przepływności, zgłaszany jest wyjątek. :keyword Callable response_hook: Wywoływanie wywoływane z metadanymi odpowiedzi. :returns: PrzepływnośćWłaściwości dla bazy danych. :zgłasza błąd ~azure.cosmos.exceptions.CosmosHttpResponseError: nie ma właściwości przepływności dla kontenera lub

nie można pobrać właściwości przepływności.

get_throughput(**kwargs: Any) -> ThroughputProperties

Typ zwracany

Wyjątki

Tworzenie kontenera nie powiodło się.

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
Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub <xref:azure.cosmos.database.UserProxy> wystąpienie użytkownika do pobrania.

Zwraca

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

Typ zwracany

Wyjątki

Tworzenie kontenera nie powiodło się.

list_containers

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

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

Parametry

max_item_count
Wymagane

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

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Iterable właściwości kontenera (dykt).

Typ zwracany

Wyjątki

Tworzenie kontenera nie powiodło się.

Przykłady

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


   database = client.get_database_client(database_name)
   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(max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parametry

max_item_count
Wymagane

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

response_hook
Callable

Wywoływany element z metadanymi odpowiedzi.

Zwraca

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

Typ zwracany

Wyjątki

Tworzenie kontenera nie powiodło się.

query_containers

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

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

Parametry

query
Wymagane

Zapytanie SQL usługi Azure Cosmos DB do wykonania.

parameters
Wymagane

Opcjonalna tablica parametrów zapytania. Ignorowane, jeśli nie podano kwerendy.

max_item_count
Wymagane

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

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Iterable właściwości kontenera (dykt).

Typ zwracany

Wyjątki

Tworzenie kontenera nie powiodło się.

query_users

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

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

Parametry

query
Wymagane

Zapytanie SQL usługi Azure Cosmos DB do wykonania.

parameters
Wymagane

Opcjonalna tablica parametrów zapytania. Ignorowane, jeśli nie podano kwerendy.

max_item_count
Wymagane

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

response_hook
Callable

Wywoływany element z metadanymi odpowiedzi.

Zwraca

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

Typ zwracany

Wyjątki

Tworzenie kontenera nie powiodło się.

read

Odczytywanie właściwości bazy danych.

read(populate_query_metrics: bool | None = None, **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

Wywoływany element z metadanymi odpowiedzi.

Typ zwracany

Dict[<xref:Str>, Any]

Wyjątki

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

read_offer

Pobierz obiekt ThroughputProperties dla tej bazy danych. Jeśli dla bazy danych nie ma już właściwości przepływności, zgłaszany jest wyjątek. :keyword Callable response_hook: Wywoływanie wywoływane z metadanymi odpowiedzi. :returns: PrzepływnośćWłaściwości dla bazy danych. :zgłasza błąd ~azure.cosmos.exceptions.CosmosHttpResponseError: nie ma właściwości przepływności dla kontenera lub

nie można pobrać właściwości przepływności.

read_offer(**kwargs: Any) -> ThroughputProperties

Typ zwracany

Wyjątki

Tworzenie kontenera nie powiodło się.

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

Parametry

container
Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub <xref:azure.cosmos.database.ContainerProxy> wystąpienie kontenera do zastąpienia.

partition_key
Wymagane

Klucz partycji do użycia dla kontenera.

indexing_policy
Wymagane

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

default_ttl
Wymagane

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

conflict_resolution_policy
Wymagane

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

populate_query_metrics
Wymagane

Włącz zwracanie metryk zapytania w nagłówkach odpowiedzi.

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

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

Wyjątki

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

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

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

Parametry

throughput
Wymagane

Przepływność do ustawienia (liczba całkowita).

response_hook
Callable

Wywoływany element z metadanymi odpowiedzi.

Zwraca

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

Typ zwracany

Wyjątki

Jeśli dla bazy danych nie istnieją żadne właściwości przepływności 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.

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

Parametry

user
Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub <xref:azure.cosmos.database.UserProxy> wystąpienie użytkownika do zastąpienia.

body
Wymagane

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

response_hook
Callable

Wywoływany element z metadanymi odpowiedzi.

Zwraca

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

Typ zwracany

Wyjątki

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.

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

Parametry

body
Wymagane

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

response_hook
Callable

Wywoływany element z metadanymi odpowiedzi.

Zwraca

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

Typ zwracany

Wyjątki

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