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: str | Dict[str, str] | TokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

Parametrar

url

str

Obligatorisk

URL:en för Cosmos DB-kontot.

credential

Union[str, Dict[str, str], AsyncTokenCredential]

Obligatorisk

Kan vara kontonyckeln eller en ordlista med resurstoken.

consistency_level

str

Konsekvensnivå som ska användas för sessionen. Standardvärdet är None (account-level). 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:

       async with CosmosClient(url, key) as client:

Metoder

close	Stäng den här instansen av CosmosClient.
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_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.

close

Stäng den här instansen av CosmosClient.

async close() -> None

create_database

Skapa en ny databas med angivet ID (namn).

async create_database(id: str, **kwargs: Any) -> DatabaseProxy

Parametrar

id

str

Obligatorisk

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

offer_throughput

Union[int, ThroughputProperties]

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[[Dict[str, str], Dict[str, Any]], None]

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 = await 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.

async create_database_if_not_exists(id: str, **kwargs: Any) -> DatabaseProxy

Parametrar

id

str

Obligatorisk

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

offer_throughput

Union[int, ThroughputProperties]

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[[Dict[str, str], Dict[str, Any]], None]

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).

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

Parametrar

database

Union[str, DatabaseProxy, Dict[str, Any]]

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[[Dict[str, str]], None]

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: str | Dict[str, str] | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Parametrar

conn_str

str

Obligatorisk

Anslutningssträngen.

credential

Union[str, Dict[str, str]]

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

consistency_level

str

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

Returer

en CosmosClient-instans

Returtyp

CosmosClient

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

Union[str, DatabaseProxy, Dict[str, Any]]

Obligatorisk

ID :t (namn), diktamen som representerar egenskaperna eller DatabaseProxy instansen av databasen som ska hämtas.

Returer

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

Returtyp

DatabaseProxy

list_databases

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

list_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parametrar

max_item_count

int

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[[Dict[str, str]], None]

En anropsbar anropas med svarsmetadata.

Returer

AsyncItemPaged med databasegenskaper (dikteringar).

Returtyp

<xref:AsyncItemPaged>[Dict[str, str]]

query_databases

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

query_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parametrar

query

Union[str, Dict[str, Any]]

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

parameters

List[Dict[str, Any]]

Valfri matris med parametrar till frågan. Varje parameter är en dict() med "name" och "value"-nycklar.

max_item_count

int

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[[Dict[str, str]], None]

En anropsbar anropas med svarsmetadata.

Returer

En AsyncItemPaged med databasegenskaper (dikteringar).

Returtyp

<xref:AsyncItemPaged>[Dict[str, str]]