DatabaseProxy Klasa

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

Ta klasa nie powinna być tworzone bezpośrednio. Zamiast tego należy użyć 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 niektórych 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: adresowalna ścieżka 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ę 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 istnieją już właściwości przepływności, zostanie zgłoszony wyjątek. :słowo kluczowe Wywołujące response_hook: wywoływane z metadanymi odpowiedzi. :zwraca: PrzepływnośćWłaściwości dla bazy danych. :zgłasza ~azure.cosmos.exceptions.CosmosHttpResponseError: dla kontenera nie istnieją właściwości przepływności lub

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

get_user_client

Pobierz wartość 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

Odczytaj właściwości bazy danych.

read_offer

Pobierz obiekt ThroughputProperties dla tej bazy danych. Jeśli dla bazy danych nie istnieją już właściwości przepływności, zostanie zgłoszony wyjątek. :słowo kluczowe Wywołujące response_hook: wywoływane z metadanymi odpowiedzi. :zwraca: PrzepływnośćWłaściwości dla bazy danych. :zgłasza ~azure.cosmos.exceptions.CosmosHttpResponseError: dla kontenera nie istnieją właściwości przepływności 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ą natychmiast utrwalane. Wszystkie nieokreślone właściwości zostaną zresetowane do ich 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 wygasają.

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

Aprowizowana przepływność dla tej oferty.

unique_key_policy
Wymagane

Unikatowe zasady klucza do zastosowania 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 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

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

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)

Utwórz kontener 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ę 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 wygasają.

populate_query_metrics
Wymagane

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

offer_throughput
Wymagane

Aprowizowana przepływność dla tej oferty.

unique_key_policy
Wymagane

Unikatowe zasady klucza do zastosowania 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 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

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 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łanie wywoływane przy użyciu metadanych 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

Utwórz 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

Usuń kontener.

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

Wywołanie wywoływane przy użyciu metadanych 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 UserProxy wystąpienie użytkownika do usunięcia.

response_hook
Callable

Wywołanie wywoływane przy użyciu metadanych 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, 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, obsługując 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 istnieją już właściwości przepływności, zostanie zgłoszony wyjątek. :słowo kluczowe Wywołujące response_hook: wywoływane z metadanymi odpowiedzi. :zwraca: PrzepływnośćWłaściwości dla bazy danych. :zgłasza ~azure.cosmos.exceptions.CosmosHttpResponseError: dla kontenera nie istnieją właściwości przepływności 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 wartość 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 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 wyliczenia.

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.

response_hook
Callable

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

Zwraca

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

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, które mają zostać zwrócone w operacji wyliczenia.

response_hook
Callable

Wywołanie wywoływane przy użyciu metadanych 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 wyliczenia.

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.

response_hook
Callable

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

Zwraca

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

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, które mają zostać zwrócone w operacji wyliczenia.

response_hook
Callable

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

Zwraca

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

Typ zwracany

Wyjątki

Tworzenie kontenera nie powiodło się.

read

Odczytaj 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 z 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łanie wywoływane przy użyciu metadanych 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 istnieją już właściwości przepływności, zostanie zgłoszony wyjątek. :słowo kluczowe Wywołujące response_hook: wywoływane z metadanymi odpowiedzi. :zwraca: PrzepływnośćWłaściwości dla bazy danych. :zgłasza ~azure.cosmos.exceptions.CosmosHttpResponseError: dla kontenera nie istnieją właściwości przepływności 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ą natychmiast utrwalane. Wszystkie nieokreślone właściwości zostaną zresetowane do ich 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 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 wygasają.

conflict_resolution_policy
Wymagane

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

populate_query_metrics
Wymagane

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

session_token
str

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

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.

initial_headers
dict[str,str]

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

response_hook
Callable

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 kontener po zakończeniu zamiany.

Typ zwracany

Wyjątki

Podniesione, jeśli nie można zamienić kontenera. Obejmuje to, czy kontener o danym 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łanie wywoływane przy użyciu metadanych odpowiedzi.

Zwraca

PrzepływnośćWłaściwości dla bazy danych, zaktualizowana 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 UserProxy wystąpienie użytkownika do zastąpienia.

body
Wymagane

Obiekt przypominający dykt reprezentujący użytkownika do zastąpienia.

response_hook
Callable

Wywołanie wywoływane przy użyciu metadanych 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łanie wywoływane przy użyciu metadanych odpowiedzi.

Zwraca

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

Typ zwracany

Wyjątki

Jeśli dany użytkownik nie może być upserted.