CosmosClient Klas

Een logische weergave aan de clientzijde van een Azure Cosmos DB-account.

Gebruik deze client om aanvragen voor de Azure Cosmos DB-service te configureren en uit te voeren.

Het wordt aanbevolen om één exemplaar van CosmosClient per levensduur van de toepassing te onderhouden, wat efficiënt verbindingsbeheer en prestaties mogelijk maakt.

CosmosClient-initialisatie is een zware bewerking. Gebruik geen initialisatie cosmosClient-exemplaren als referenties of netwerkverbindingsvalidaties.

Maak een instantie van een nieuwe CosmosClient.

Overname

builtins.object

CosmosClient

Constructor

CosmosClient(url: str, credential: str | Dict[str, str] | TokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

Parameters

url

str

Vereist

De URL van het Cosmos DB-account.

credential

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

Vereist

Dit kan de accountsleutel zijn of een woordenlijst met resourcetokens.

consistency_level

str

Consistentieniveau dat moet worden gebruikt voor de sessie. De standaardwaarde is Geen (accountniveau). Meer informatie over consistentieniveaus en mogelijke waarden: https://aka.ms/cosmos-consistency-levels

timeout

int

Een absolute time-out in seconden voor de gecombineerde verwerking van HTTP-aanvragen en -antwoorden.

connection_timeout

int

De time-out van de HTTP-aanvraag in seconden.

connection_mode

str

De verbindingsmodus voor de client - ondersteunt momenteel alleen 'Gateway'.

proxy_config

ProxyConfiguration

Configuratie van verbindingsproxy.

ssl_config

SSLConfiguration

SSL-configuratie van verbinding.

connection_verify

bool

Of u de verbinding wilt controleren, is de standaardwaarde True.

connection_cert

str

Een alternatief certificaat om de verbinding te controleren.

retry_total

int

Maximum aantal nieuwe pogingen.

retry_backoff_max

int

Maximale wachttijd voor nieuwe pogingen in seconden.

retry_fixed_interval

int

Vast interval voor opnieuw proberen in milliseconden.

retry_read

int

Maximum aantal socket-leespogingen.

retry_connect

int

Maximum aantal pogingen om de verbindingsfout opnieuw te proberen.

retry_status

int

Maximum aantal nieuwe pogingen voor foutcodes.

retry_on_status_codes

list[int]

Een lijst met specifieke statuscodes om opnieuw te proberen.

retry_backoff_factor

float

Factor voor het berekenen van de wachttijd tussen nieuwe pogingen.

enable_endpoint_discovery

bool

Schakel eindpuntdetectie in voor geo-gerepliceerde databaseaccounts. (Standaard: Waar)

preferred_locations

list[str]

De voorkeurslocaties voor geo-gerepliceerde databaseaccounts.

enable_diagnostics_logging

bool

Schakel het CosmosHttpLogging-beleid in. Moet samen met een logger worden gebruikt om te werken.

logger

Logger

Logboekregistratie die moet worden gebruikt voor het verzamelen van diagnostische gegevens over aanvragen. Kan worden doorgegeven op clientniveau (om alle aanvragen te registreren) of op één aanvraagniveau. Aanvragen worden geregistreerd op INFO-niveau.

Voorbeelden

Maak een nieuw exemplaar van de Cosmos DB-client:

       async with CosmosClient(url, key) as client:

Methoden

close	Sluit dit exemplaar van CosmosClient.
create_database	Maak een nieuwe database met de opgegeven id (naam).
create_database_if_not_exists	Maak de database als deze nog niet bestaat. Als de database al bestaat, worden de bestaande instellingen geretourneerd. .. opmerking:: met deze functie worden bestaande database-instellingen niet gecontroleerd of bijgewerkt en wordt doorvoer niet aangeboden als deze verschillen van wat wordt doorgegeven.
delete_database	Verwijder de database met de opgegeven id (naam).
from_connection_string	Een CosmosClient-exemplaar maken op basis van een connection string. Dit kan worden opgehaald uit de Azure Portal. Zie de CosmosClient-constructor voor een volledige lijst met optionele trefwoordargumenten.
get_database_client	Haal een bestaande database op met de id (naam) id.
list_databases	De databases in een Cosmos DB SQL-databaseaccount weergeven.
query_databases	Query's uitvoeren op de databases in een Cosmos DB SQL-databaseaccount.

close

Sluit dit exemplaar van CosmosClient.

async close() -> None

create_database

Maak een nieuwe database met de opgegeven id (naam).

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

Parameters

id

str

Vereist

Id (naam) van de database die moet worden gemaakt.

offer_throughput

Union[int, ThroughputProperties]

De ingerichte doorvoer voor deze aanbieding.

session_token

str

Token voor gebruik met sessieconsistentie.

initial_headers

dict[str, str]

Eerste headers die moeten worden verzonden als onderdeel van de aanvraag.

etag

str

Een ETag-waarde of het jokerteken (*). Wordt gebruikt om te controleren of de resource is gewijzigd en om te handelen volgens de voorwaarde die is opgegeven door de parameter match_condition .

match_condition

MatchConditions

De overeenkomstvoorwaarde die moet worden gebruikt voor de etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

Een aanroepbare die wordt aangeroepen met de metagegevens van het antwoord.

Retouren

Een DatabaseProxy-exemplaar dat de nieuwe database vertegenwoordigt.

Retourtype

DatabaseProxy

Uitzonderingen

CosmosResourceExistsError

De database met de opgegeven id bestaat al.

Voorbeelden

Maak een database in het Cosmos DB-account:

           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

Maak de database als deze nog niet bestaat.

Als de database al bestaat, worden de bestaande instellingen geretourneerd.

.. opmerking:: met deze functie worden bestaande database-instellingen niet gecontroleerd of bijgewerkt en wordt doorvoer niet aangeboden als deze verschillen van wat wordt doorgegeven.

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

Parameters

id

str

Vereist

Id (naam) van de database die moet worden gelezen of gemaakt.

offer_throughput

Union[int, ThroughputProperties]

De ingerichte doorvoer voor deze aanbieding.

session_token

str

Token voor gebruik met sessieconsistentie.

initial_headers

dict[str, str]

Eerste headers die moeten worden verzonden als onderdeel van de aanvraag.

etag

str

Een ETag-waarde of het jokerteken (*). Wordt gebruikt om te controleren of de resource is gewijzigd en om te handelen volgens de voorwaarde die is opgegeven door de parameter match_condition .

match_condition

MatchConditions

De overeenkomstvoorwaarde die moet worden gebruikt voor de etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

Een aanroepbare die wordt aangeroepen met de metagegevens van het antwoord.

Retouren

Een DatabaseProxy-exemplaar dat de database vertegenwoordigt.

Retourtype

DatabaseProxy

Uitzonderingen

CosmosHttpResponseError

Het lezen of maken van de database is mislukt.

delete_database

Verwijder de database met de opgegeven id (naam).

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

Parameters

database

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

Vereist

De id (naam), de dict die de eigenschappen vertegenwoordigt of DatabaseProxy het exemplaar van de database die u wilt verwijderen.

session_token

str

Token voor gebruik met sessieconsistentie.

initial_headers

dict[str, str]

Eerste headers die moeten worden verzonden als onderdeel van de aanvraag.

etag

str

Een ETag-waarde of het jokerteken (*). Wordt gebruikt om te controleren of de resource is gewijzigd en om te handelen volgens de voorwaarde die is opgegeven door de parameter match_condition .

match_condition

MatchConditions

De overeenkomstvoorwaarde die moet worden gebruikt voor de etag.

response_hook

Callable[[Dict[str, str]], None]

Een aanroepbare die wordt aangeroepen met de metagegevens van het antwoord.

Retourtype

None

Uitzonderingen

CosmosHttpResponseError

Als de database niet kan worden verwijderd.

from_connection_string

Een CosmosClient-exemplaar maken op basis van een connection string.

Dit kan worden opgehaald uit de Azure Portal. Zie de CosmosClient-constructor voor een volledige lijst met optionele trefwoordargumenten.

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

Parameters

conn_str

str

Vereist

De connection string.

credential

Union[str, Dict[str, str]]

Alternatieve referenties die moeten worden gebruikt in plaats van de sleutel die is opgegeven in de connection string.

consistency_level

str

Consistentieniveau dat moet worden gebruikt voor de sessie. De standaardwaarde is Geen (accountniveau). Meer informatie over consistentieniveaus en mogelijke waarden: https://aka.ms/cosmos-consistency-levels

Retouren

een CosmosClient-exemplaar

Retourtype

CosmosClient

get_database_client

Haal een bestaande database op met de id (naam) id.

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

Parameters

database

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

Vereist

De id (naam), de dict die de eigenschappen of DatabaseProxy het exemplaar van de database vertegenwoordigt die u wilt ophalen.

Retouren

Een DatabaseProxy-exemplaar dat de opgehaalde database vertegenwoordigt.

Retourtype

DatabaseProxy

list_databases

De databases in een Cosmos DB SQL-databaseaccount weergeven.

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

Parameters

max_item_count

int

Maximum aantal items dat moet worden geretourneerd in de opsommingsbewerking.

session_token

str

Token voor gebruik met sessieconsistentie.

initial_headers

dict[str, str]

Eerste headers die moeten worden verzonden als onderdeel van de aanvraag.

response_hook

Callable[[Dict[str, str]], None]

Een aanroepbare die wordt aangeroepen met de metagegevens van het antwoord.

Retouren

Een AsyncItemPagina van database-eigenschappen (dicts).

Retourtype

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

query_databases

Query's uitvoeren op de databases in een Cosmos DB SQL-databaseaccount.

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

Parameters

query

Union[str, Dict[str, Any]]

De Azure Cosmos DB SQL-query die moet worden uitgevoerd.

parameters

List[Dict[str, Any]]

Optionele matrix met parameters voor de query. Elke parameter is een dict() met de sleutels 'name' en 'value'.

max_item_count

int

Maximum aantal items dat moet worden geretourneerd in de opsommingsbewerking.

session_token

str

Token voor gebruik met sessieconsistentie.

initial_headers

dict[str, str]

Eerste headers die moeten worden verzonden als onderdeel van de aanvraag.

response_hook

Callable[[Dict[str, str]], None]

Een aanroepbare die wordt aangeroepen met de metagegevens van het antwoord.

Retouren

Een AsyncitemPagina van database-eigenschappen (dicts).

Retourtype

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