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

DatabaseProxy

Undantag

CosmosResourceExistsError

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

DatabaseProxy

Undantag

CosmosHttpResponseError

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

None

Undantag

CosmosHttpResponseError

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

CosmosResourceExistsError

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

DatabaseAccount

Undantag

CosmosResourceExistsError

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

DatabaseProxy

Undantag

CosmosResourceExistsError

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

Iterable[dict[str, str]]

Undantag

CosmosResourceExistsError

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

Iterable[dict[str, str]]

Undantag

CosmosResourceExistsError

Databasen med det angivna ID:t finns redan.