Sdílet prostřednictvím


CosmosClient Třída

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

Pomocí tohoto klienta můžete konfigurovat 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 náročné – nepoužívejte inicializační instance CosmosClient jako přihlašovací údaje nebo ověřování připojení k síti.

Vytvořte instanci nového klienta 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

Výjimky

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

Výjimky

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

Výjimky

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

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

Výjimky

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

Výjimky

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

Výjimky

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

Výjimky

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