CosmosClient Klasa

Logiczna reprezentacja konta usługi Azure Cosmos DB po stronie klienta.

Ten klient służy do konfigurowania i wykonywania żądań do usługi Azure Cosmos DB.

Zaleca się utrzymanie pojedynczego wystąpienia obiektu CosmosClient przez cały okres istnienia aplikacji, co umożliwia wydajne zarządzanie połączeniami i wydajność.

Inicjowanie usługi CosmosClient to duża operacja — nie używaj inicjalizacji wystąpień cosmosClient jako poświadczeń ani walidacji łączności sieciowej.

Utwórz wystąpienie nowego obiektu CosmosClient.

Dziedziczenie

builtins.object

CosmosClient

Konstruktor

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

Parametry

url

str

Wymagane

Adres URL konta usługi Cosmos DB.

credential

Union[str, Dict[str, str], TokenCredential]

Wymagane

Może być kluczem konta lub słownikiem tokenów zasobów.

consistency_level

str

wartość domyślna: None

Poziom spójności do użycia dla sesji. Wartość domyślna to Brak (poziom konta). Więcej informacji na temat poziomów spójności i możliwych wartości: https://aka.ms/cosmos-consistency-levels

timeout

int

Bezwzględny limit czasu w sekundach dla połączonego żądania HTTP i przetwarzania odpowiedzi.

connection_timeout

int

Limit czasu żądania HTTP w sekundach.

connection_mode

str

Tryb połączenia dla klienta — obecnie obsługuje tylko "Bramę".

proxy_config

ProxyConfiguration

Konfiguracja serwera proxy połączeń.

ssl_config

SSLConfiguration

Konfiguracja protokołu SSL połączenia.

connection_verify

bool

Czy zweryfikować połączenie, wartość domyślna to True.

connection_cert

str

Alternatywny certyfikat umożliwiający zweryfikowanie połączenia.

retry_total

int

Maksymalna liczba ponownych prób.

retry_backoff_max

int

Maksymalny czas oczekiwania ponawiania prób w sekundach.

retry_fixed_interval

int

Stały interwał ponawiania prób w milisekundach.

retry_read

int

Maksymalna liczba prób ponawiania próby odczytu gniazda.

retry_connect

int

Maksymalna liczba ponownych prób ponawiania próby połączenia.

retry_status

int

Maksymalna liczba ponownych prób w kodach stanu błędu.

retry_on_status_codes

list[int]

Lista określonych kodów stanu do ponowienia próby.

retry_backoff_factor

float

Współczynnik obliczania czasu oczekiwania między ponownymi próbami.

enable_endpoint_discovery

bool

Włącz odnajdywanie punktów końcowych dla kont bazy danych replikowanych geograficznie. (Wartość domyślna: Prawda)

preferred_locations

list[str]

Preferowane lokalizacje dla kont bazy danych replikowanych geograficznie.

enable_diagnostics_logging

bool

Włącz zasady CosmosHttpLogging. Musi być używany wraz z rejestratorem do pracy.

logger

Logger

Rejestrator używany do zbierania danych diagnostycznych żądań. Można przekazać na poziomie klienta (w celu rejestrowania wszystkich żądań) lub na poziomie pojedynczego żądania. Żądania będą rejestrowane na poziomie INFO.

Przykłady

Utwórz nowe wystąpienie klienta usługi Cosmos DB:

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

Metody

create_database	Utwórz nową bazę danych o podanym identyfikatorze (nazwie).
create_database_if_not_exists	Utwórz bazę danych, jeśli jeszcze nie istnieje. Jeśli baza danych już istnieje, zostaną zwrócone istniejące ustawienia. .. uwaga:: Ta funkcja nie sprawdza ani nie aktualizuje istniejących ustawień bazy danych ani nie oferuje przepływności, jeśli różnią się od tego, co jest przekazywane.
delete_database	Usuń bazę danych o podanym identyfikatorze (nazwie).
from_connection_string	Utwórz wystąpienie usługi CosmosClient na podstawie parametrów połączenia. Można to pobrać z Azure Portal. Aby uzyskać pełną listę opcjonalnych argumentów słów kluczowych, zobacz konstruktor CosmosClient.
get_database_account	Pobierz informacje o koncie bazy danych.
get_database_client	Pobierz istniejącą bazę danych o identyfikatorze (nazwie).
list_databases	Wyświetl listę baz danych na koncie bazy danych SQL usługi Cosmos DB.
query_databases	Wykonywanie zapytań dotyczących baz danych na koncie bazy danych SQL usługi Cosmos DB.

create_database

Utwórz nową bazę danych o podanym identyfikatorze (nazwie).

create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Parametry

id

Wymagane

Identyfikator (nazwa) bazy danych do utworzenia.

offer_throughput

Wymagane

Aprowizowana przepływność dla tej oferty.

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.

Zwraca

Wystąpienie databaseProxy reprezentujące nową bazę danych.

Typ zwracany

DatabaseProxy

Wyjątki

CosmosResourceExistsError

Baza danych o danym identyfikatorze już istnieje.

Przykłady

Utwórz bazę danych na koncie usługi Cosmos DB:

   database_name = "testDatabase"
   try:
       database = client.create_database(id=database_name)
   except exceptions.CosmosResourceExistsError:
       database = client.get_database_client(database=database_name)

create_database_if_not_exists

Utwórz bazę danych, jeśli jeszcze nie istnieje.

Jeśli baza danych już istnieje, zostaną zwrócone istniejące ustawienia.

.. uwaga:: Ta funkcja nie sprawdza ani nie aktualizuje istniejących ustawień bazy danych ani nie oferuje przepływności, jeśli różnią się od tego, co jest przekazywane.

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Parametry

id

Wymagane

Identyfikator (nazwa) bazy danych do odczytu lub utworzenia.

populate_query_metrics

bool

Wymagane

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

offer_throughput

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

Wymagane

Aprowizowana przepływność dla tej oferty.

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.

Zwraca

Wystąpienie databaseProxy reprezentujące bazę danych.

Typ zwracany

DatabaseProxy

Wyjątki

CosmosHttpResponseError

Nie można odczytać lub utworzyć bazy danych.

delete_database

Usuń bazę danych o podanym identyfikatorze (nazwie).

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

Parametry

database

str lub dict(str, str) lub DatabaseProxy

Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub DatabaseProxy wystąpienie bazy danych do usunięcia.

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

None

Wyjątki

CosmosHttpResponseError

Jeśli nie można usunąć bazy danych.

from_connection_string

Utwórz wystąpienie usługi CosmosClient na podstawie parametrów połączenia.

Można to pobrać z Azure Portal. Aby uzyskać pełną listę opcjonalnych argumentów słów kluczowych, zobacz konstruktor CosmosClient.

from_connection_string(conn_str: str, credential: Any | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Parametry

conn_str

str

Wymagane

Parametry połączenia.

credential

str lub dict(str, str)

wartość domyślna: None

Alternatywne poświadczenia do użycia zamiast klucza podanego w parametrach połączenia.

consistency_level

Optional[str]

wartość domyślna: None

Poziom spójności do użycia dla sesji. Wartość domyślna to Brak (poziom konta).

Wyjątki

CosmosResourceExistsError

Baza danych o danym identyfikatorze już istnieje.

get_database_account

Pobierz informacje o koncie bazy danych.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parametry

response_hook

Callable

Wywoływany element z metadanymi odpowiedzi.

Zwraca

Wystąpienie databaseAccount reprezentujące konto bazy danych usługi Cosmos DB.

Typ zwracany

DatabaseAccount

Wyjątki

CosmosResourceExistsError

Baza danych o danym identyfikatorze już istnieje.

get_database_client

Pobierz istniejącą bazę danych o identyfikatorze (nazwie).

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

Parametry

database

str lub dict(str, str) lub DatabaseProxy

Wymagane

Identyfikator (nazwa), dykt reprezentujący właściwości lub wystąpienie DatabaseProxy bazy danych do odczytu.

Zwraca

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

Typ zwracany

DatabaseProxy

Wyjątki

CosmosResourceExistsError

Baza danych o danym identyfikatorze już istnieje.

list_databases

Wyświetl listę baz danych na koncie bazy danych SQL usługi Cosmos DB.

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

Parametry

max_item_count

int

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 bazy danych (dykt).

Typ zwracany

Iterable[dict[str, str]]

Wyjątki

CosmosResourceExistsError

Baza danych o danym identyfikatorze już istnieje.

query_databases

Wykonywanie zapytań dotyczących baz danych na koncie bazy danych SQL usługi Cosmos DB.

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

Parametry

query

str

Wymagane

Zapytanie SQL usługi Azure Cosmos DB do wykonania.

parameters

List[Dict[str, Any]]

Wymagane

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

enable_cross_partition_query

bool

Wymagane

Zezwalaj na skanowanie zapytań, których nie można służyć jako indeksowanie zostało odrzucone w żądanych ścieżkach.

max_item_count

int

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 bazy danych (dykt).

Typ zwracany

Iterable[dict[str, str]]

Wyjątki

CosmosResourceExistsError

Baza danych o danym identyfikatorze już istnieje.