CosmosClient Třída

Logická reprezentace účtu služby Azure Cosmos DB na straně klienta

Pomocí tohoto klienta můžete nakonfigurovat a spouštět požadavky na službu Azure Cosmos DB.

Doporučuje se udržovat jednu instanci CosmosClient po celou dobu životnosti aplikace, což umožňuje efektivní správu připojení a výkon.

Inicializace CosmosClient je těžká operace – nepoužívejte inicializaci instancí CosmosClient jako přihlašovací údaje nebo ověření připojení k síti.

Vytvořte instanci nového Klienta služby CosmosClient.

Dědičnost

builtins.object

CosmosClient

Konstruktor

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

Parametry

url

str

Vyžadováno

Adresa URL účtu služby Cosmos DB.

credential

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

Vyžadováno

Může to být klíč účtu nebo slovník tokenů prostředků.

consistency_level

str

výchozí hodnota: None

Úroveň konzistence, která se má použít pro relaci. Výchozí hodnota je None (úroveň účtu). Další informace o úrovních konzistence a možných hodnotách: https://aka.ms/cosmos-consistency-levels

timeout

int

Absolutní časový limit v sekundách pro kombinované zpracování požadavku HTTP a odpovědi

connection_timeout

int

Časový limit požadavku HTTP v sekundách.

connection_mode

str

Režim připojení pro klienta v současné době podporuje pouze bránu.

proxy_config

ProxyConfiguration

Konfigurace proxy připojení.

ssl_config

SSLConfiguration

Konfigurace SSL připojení.

connection_verify

bool

Jestli chcete ověřit připojení, výchozí hodnota je True.

connection_cert

str

Alternativní certifikát pro ověření připojení.

retry_total

int

Maximální počet opakovaných pokusů.

retry_backoff_max

int

Maximální doba čekání na opakování v sekundách

retry_fixed_interval

int

Byl opraven interval opakování v milisekundách.

retry_read

int

Maximální počet pokusů o čtení soketu

retry_connect

int

Maximální počet pokusů o opakování chyb připojení

retry_status

int

Maximální počet opakovaných pokusů o stavové kódy chyb

retry_on_status_codes

list[int]

Seznam konkrétních stavových kódů, se které se mají opakovat.

retry_backoff_factor

float

Faktor pro výpočet doby čekání mezi opakovanými pokusy

enable_endpoint_discovery

bool

Povolte zjišťování koncových bodů pro účty geograficky replikované databáze. (Výchozí: True)

preferred_locations

list[str]

Upřednostňovaná umístění pro geograficky replikované databázové účty

enable_diagnostics_logging

bool

Povolte zásadu CosmosHttpLogging. Aby fungovala, musí být použita společně s protokolovacím nástrojem.

logger

Logger

Protokolovací nástroj, který se má použít ke shromažďování diagnostiky požadavků. Dá se předat na úrovni klienta (k protokolování všech požadavků) nebo na úrovni jednoho požadavku. Požadavky se budou protokolovat na úrovni INFO.

Příklady

Vytvořte novou instanci klienta 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	Vytvořte novou databázi s daným ID (názvem).
create_database_if_not_exists	Vytvořte databázi, pokud ještě neexistuje. Pokud databáze již existuje, vrátí se existující nastavení. .. poznámka:: Tato funkce nekontroluje ani neaktualizuje stávající nastavení databáze ani nenabízí propustnost, pokud se liší od toho, co se předává.
delete_database	Odstraňte databázi s daným ID (názvem).
from_connection_string	Vytvořte instanci CosmosClient z připojovacího řetězce. To můžete načíst z Azure Portal. Úplný seznam volitelných argumentů klíčových slov najdete v konstruktoru CosmosClient.
get_database_account	Načtěte informace o databázovém účtu.
get_database_client	Načtěte existující databázi s ID (název) ID.
list_databases	Výpis databází v účtu databáze SQL Cosmos DB
query_databases	Dotazování databází v účtu databáze SQL cosmos DB

create_database

Vytvořte novou databázi s daným ID (názvem).

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

Parametry

id

Vyžadováno

ID (název) databáze, která se má vytvořit.

offer_throughput

Vyžadováno

Zřízená propustnost pro tuto nabídku

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

etag

str

Hodnota značky ETag nebo zástupný znak (*). Slouží ke kontrole, jestli se prostředek změnil, a k chování podle podmínky zadané parametrem match_condition .

match_condition

MatchConditions

Podmínka shody, která se má použít u značky etag.

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Instance DatabaseProxy představující novou databázi.

Návratový typ

DatabaseProxy

Výjimky

CosmosResourceExistsError

Databáze s daným ID již existuje.

Příklady

Vytvořte databázi v účtu 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

Vytvořte databázi, pokud ještě neexistuje.

Pokud databáze již existuje, vrátí se existující nastavení.

.. poznámka:: Tato funkce nekontroluje ani neaktualizuje stávající nastavení databáze ani nenabízí propustnost, pokud se liší od toho, co se předává.

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

Parametry

id

Vyžadováno

ID (název) databáze, která se má číst nebo vytvořit.

populate_query_metrics

bool

Vyžadováno

Povolte v hlavičce odpovědi vracené metriky dotazů.

offer_throughput

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

Vyžadováno

Zřízená propustnost pro tuto nabídku

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

etag

str

Hodnota značky ETag nebo zástupný znak (*). Slouží ke kontrole, jestli se prostředek změnil, a k chování podle podmínky zadané parametrem match_condition .

match_condition

MatchConditions

Podmínka shody, která se má použít u značky etag.

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Instance DatabaseProxy představující databázi.

Návratový typ

DatabaseProxy

Výjimky

CosmosHttpResponseError

Čtení nebo vytvoření databáze se nezdařilo.

delete_database

Odstraňte databázi s daným ID (názvem).

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

Parametry

database

str nebo dict(str, str) nebo DatabaseProxy

Vyžadováno

ID (název), dikt představující vlastnosti nebo <xref:azure.cosmos.cosmos_client.DatabaseProxy> instanci databáze, která se má odstranit.

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

etag

str

Hodnota značky ETag nebo zástupný znak (*). Slouží ke kontrole, jestli se prostředek změnil, a k chování podle podmínky zadané parametrem match_condition .

match_condition

MatchConditions

Podmínka shody, která se má použít u značky etag.

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návratový typ

None

Výjimky

CosmosHttpResponseError

Pokud databázi nejde odstranit.

from_connection_string

Vytvořte instanci CosmosClient z připojovacího řetězce.

To můžete načíst z Azure Portal. Úplný seznam volitelných argumentů klíčových slov najdete v konstruktoru CosmosClient.

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

Parametry

conn_str

str

Vyžadováno

Připojovací řetězec

credential

str nebo dict(str, str)

výchozí hodnota: None

Alternativní přihlašovací údaje, které se mají použít místo klíče zadaného v připojovacím řetězci.

consistency_level

Optional[str]

výchozí hodnota: None

Úroveň konzistence, která se má použít pro relaci. Výchozí hodnota je None (úroveň účtu).

Výjimky

CosmosResourceExistsError

Databáze s daným ID již existuje.

get_database_account

Načtěte informace o databázovém účtu.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parametry

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Instance DatabaseAccount představující účet databáze Cosmos DB.

Návratový typ

DatabaseAccount

Výjimky

CosmosResourceExistsError

Databáze s daným ID již existuje.

get_database_client

Načtěte existující databázi s ID (název) ID.

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

Parametry

database

str nebo dict(str, str) nebo DatabaseProxy

Vyžadováno

ID (název) – dict představující vlastnosti nebo instanci DatabaseProxy databáze, která se má číst.

Návraty

Instance DatabaseProxy představující načtenou databázi.

Návratový typ

DatabaseProxy

Výjimky

CosmosResourceExistsError

Databáze s daným ID již existuje.

list_databases

Výpis databází v účtu databáze SQL 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

Vyžadováno

Maximální počet položek, které se mají vrátit v operaci výčtu.

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Iterable of database properties (dicts).

Návratový typ

Iterable[dict[str, str]]

Výjimky

CosmosResourceExistsError

Databáze s daným ID již existuje.

query_databases

Dotazování databází v účtu databáze SQL 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

Vyžadováno

Dotaz SQL služby Azure Cosmos DB, který se má spustit.

parameters

List[Dict[str, Any]]

Vyžadováno

Volitelné pole parametrů dotazu. Ignorováno, pokud není zadaný žádný dotaz.

enable_cross_partition_query

bool

Vyžadováno

Povolit kontrolu dotazů, které se nedají obsložení, protože indexování bylo na požadovaných cestách odhlášení.

max_item_count

int

Vyžadováno

Maximální počet položek, které se mají vrátit v operaci výčtu.

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Iterable of database properties (dicts).

Návratový typ

Iterable[dict[str, str]]

Výjimky

CosmosResourceExistsError

Databáze s daným ID již existuje.