Dela via


CosmosClient Klass

En logisk representation på klientsidan av ett Azure Cosmos DB-konto.

Använd den här klienten för att konfigurera och köra begäranden till Azure Cosmos DB-tjänsten.

Vi rekommenderar att du underhåller en enda instans av CosmosClient per livslängd för programmet, vilket möjliggör effektiv anslutningshantering och prestanda.

CosmosClient-initiering är en tung åtgärd – använd inte initiering av CosmosClient-instanser som autentiseringsuppgifter eller valideringar av nätverksanslutningar.

Instansiera en ny CosmosClient.

Arv
builtins.object
CosmosClient

Konstruktor

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

Parametrar

url
str
Obligatorisk

URL:en för Cosmos DB-kontot.

credential
Union[str, Dict[str, str], TokenCredential]
Obligatorisk

Kan vara kontonyckeln eller en ordlista med resurstoken.

consistency_level
str
standardvärde: None

Konsekvensnivå som ska användas för sessionen. Standardvärdet är Ingen (kontonivå). Mer om konsekvensnivåer och möjliga värden: https://aka.ms/cosmos-consistency-levels

timeout
int

En absolut timeout i sekunder för den kombinerade HTTP-begäran och svarsbearbetningen.

connection_timeout
int

Tidsgränsen för HTTP-begäran i sekunder.

connection_mode
str

Anslutningsläget för klienten – stöder för närvarande endast "Gateway".

proxy_config
ProxyConfiguration

Konfiguration av anslutningsproxy.

ssl_config
SSLConfiguration

SSL-konfiguration för anslutning.

connection_verify
bool

Om du vill verifiera anslutningen är standardvärdet Sant.

connection_cert
str

Ett alternativt certifikat för att verifiera anslutningen.

retry_total
int

Maximalt antal återförsök.

retry_backoff_max
int

Maximal väntetid för återförsök i sekunder.

retry_fixed_interval
int

Fast återförsöksintervall i millisekunder.

retry_read
int

Maximalt antal återförsök av socketläsningar.

retry_connect
int

Maximalt antal återförsök av anslutningsfel.

retry_status
int

Maximalt antal återförsök för felstatuskoder.

retry_on_status_codes
list[int]

En lista med specifika statuskoder att försöka igen på.

retry_backoff_factor
float

Faktor för att beräkna väntetiden mellan återförsök.

enable_endpoint_discovery
bool

Aktivera slutpunktsidentifiering för geo-replikerade databaskonton. (Standard: Sant)

preferred_locations
list[str]

Önskade platser för geo-replikerade databaskonton.

enable_diagnostics_logging
bool

Aktivera CosmosHttpLogging-principen. Måste användas tillsammans med en loggare för att fungera.

logger
Logger

Loggare som ska användas för att samla in begärandediagnostik. Kan skickas in på klientnivå (för att logga alla begäranden) eller på en enda begärandenivå. Begäranden loggas på INFO-nivå.

Exempel

Skapa en ny instans av Cosmos DB-klienten:


   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

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

Metoder

create_database

Skapa en ny databas med angivet ID (namn).

create_database_if_not_exists

Skapa databasen om den inte redan finns.

Om databasen redan finns returneras de befintliga inställningarna.

.. obs!: Den här funktionen kontrollerar eller uppdaterar inte befintliga databasinställningar eller erbjuder dataflöde om de skiljer sig från vad som skickas in.

delete_database

Ta bort databasen med angivet ID (namn).

from_connection_string

Skapa en CosmosClient-instans från en anslutningssträng.

Detta kan hämtas från Azure Portal. En fullständig lista över valfria nyckelordsargument finns i CosmosClient-konstruktorn.

get_database_account

Hämta databaskontoinformationen.

get_database_client

Hämta en befintlig databas med ID-ID: t (namn).

list_databases

Visa en lista över databaserna i ett Cosmos DB SQL-databaskonto.

query_databases

Fråga databaserna i ett Cosmos DB SQL-databaskonto.

create_database

Skapa en ny databas med angivet ID (namn).

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

Parametrar

id
Obligatorisk

ID (namn) för databasen som ska skapas.

offer_throughput
Obligatorisk

Det etablerade dataflödet för det här erbjudandet.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande huvuden som ska skickas som en del av begäran.

etag
str

Ett ETag-värde eller jokertecknet (*). Används för att kontrollera om resursen har ändrats och agera enligt villkoret som anges av parametern match_condition .

match_condition
MatchConditions

Matchningsvillkoret som ska användas på etag.

response_hook
Callable

En anropsbar anropas med svarsmetadata.

Returer

En DatabaseProxy-instans som representerar den nya databasen.

Returtyp

Undantag

Databasen med det angivna ID:t finns redan.

Exempel

Skapa en databas i Cosmos DB-kontot:


   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

Skapa databasen om den inte redan finns.

Om databasen redan finns returneras de befintliga inställningarna.

.. obs!: Den här funktionen kontrollerar eller uppdaterar inte befintliga databasinställningar eller erbjuder dataflöde om de skiljer sig från vad som skickas in.

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

Parametrar

id
Obligatorisk

ID (namn) för databasen som ska läsas eller skapas.

populate_query_metrics
bool
Obligatorisk

Aktivera returnerade frågemått i svarshuvuden.

offer_throughput
int eller <xref:azure.cosmos.ThroughputProperties.>
Obligatorisk

Det etablerade dataflödet för det här erbjudandet.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande huvuden som ska skickas som en del av begäran.

etag
str

Ett ETag-värde eller jokertecknet (*). Används för att kontrollera om resursen har ändrats och agera enligt villkoret som anges av parametern match_condition .

match_condition
MatchConditions

Matchningsvillkoret som ska användas på etag.

response_hook
Callable

En anropsbar anropas med svarsmetadata.

Returer

En DatabaseProxy-instans som representerar databasen.

Returtyp

Undantag

Det gick inte att läsa eller skapa databasen.

delete_database

Ta bort databasen med angivet ID (namn).

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

Parametrar

database
str eller dict(str, str) eller DatabaseProxy
Obligatorisk

ID :t (namn), diktamen som representerar egenskaperna eller DatabaseProxy instansen av databasen som ska tas bort.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande huvuden som ska skickas som en del av begäran.

etag
str

Ett ETag-värde eller jokertecknet (*). Används för att kontrollera om resursen har ändrats och agera enligt villkoret som anges av parametern match_condition .

match_condition
MatchConditions

Matchningsvillkoret som ska användas på etag.

response_hook
Callable

En anropsbar anropas med svarsmetadata.

Returtyp

Undantag

Om det inte gick att ta bort databasen.

from_connection_string

Skapa en CosmosClient-instans från en anslutningssträng.

Detta kan hämtas från Azure Portal. En fullständig lista över valfria nyckelordsargument finns i CosmosClient-konstruktorn.

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

Parametrar

conn_str
str
Obligatorisk

Anslutningssträngen.

credential
str eller dict(str, str)
standardvärde: None

Alternativa autentiseringsuppgifter att använda i stället för nyckeln som anges i anslutningssträngen.

consistency_level
Optional[str]
standardvärde: None

Konsekvensnivå som ska användas för sessionen. Standardvärdet är Ingen (kontonivå).

Undantag

Databasen med det angivna ID:t finns redan.

get_database_account

Hämta databaskontoinformationen.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parametrar

response_hook
Callable

En anropsbar anropas med svarsmetadata.

Returer

En DatabaseAccount-instans som representerar Cosmos DB-databaskontot.

Returtyp

Undantag

Databasen med det angivna ID:t finns redan.

get_database_client

Hämta en befintlig databas med ID-ID: t (namn).

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

Parametrar

database
str eller dict(str, str) eller DatabaseProxy
Obligatorisk

ID :t (namn), diktamen som representerar egenskaperna eller DatabaseProxy-instansen för databasen som ska läsas.

Returer

En DatabaseProxy-instans som representerar den hämtade databasen.

Returtyp

Undantag

Databasen med det angivna ID:t finns redan.

list_databases

Visa en lista över databaserna i ett Cosmos DB SQL-databaskonto.

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

Parametrar

max_item_count
int
Obligatorisk

Maximalt antal objekt som ska returneras i uppräkningsåtgärden.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande huvuden som ska skickas som en del av begäran.

response_hook
Callable

En anropsbar anropas med svarsmetadata.

Returer

En iterabel av databasegenskaper (dikteringar).

Returtyp

Undantag

Databasen med det angivna ID:t finns redan.

query_databases

Fråga databaserna i ett Cosmos DB SQL-databaskonto.

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

Parametrar

query
str
Obligatorisk

Azure Cosmos DB SQL-frågan som ska köras.

parameters
List[Dict[str, Any]]
Obligatorisk

Valfri matris med parametrar till frågan. Ignoreras om ingen fråga har angetts.

enable_cross_partition_query
bool
Obligatorisk

Tillåt genomsökning på de frågor som inte kunde hanteras eftersom indexering har avregistrerats på de begärda sökvägarna.

max_item_count
int
Obligatorisk

Maximalt antal objekt som ska returneras i uppräkningsåtgärden.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande rubriker som ska skickas som en del av begäran.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returer

En iterabel databasegenskaper (diktadata).

Returtyp

Undantag

Databasen med det angivna ID:t finns redan.