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

Parameters

url

str

Vereist

De URL van het Cosmos DB-account.

credential

Union[str, Dict[str, str], TokenCredential]

Vereist

Dit kan de accountsleutel zijn of een woordenlijst met resourcetokens.

consistency_level

str

standaardwaarde: None

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:

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

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

Methoden

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_account	Haal de gegevens van het databaseaccount op.
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.

create_database

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

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

Parameters

id

Vereist

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

offer_throughput

Vereist

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

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

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

Parameters

id

Vereist

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

populate_query_metrics

bool

Vereist

Schakel het retourneren van metrische querygegevens in antwoordheaders in.

offer_throughput

int of <xref:azure.cosmos.ThroughputProperties.>

Vereist

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

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

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

Parameters

database

str of dict(str, str) of DatabaseProxy

Vereist

De id (naam), de dicteerfunctie die de eigenschappen of <xref:azure.cosmos.cosmos_client.DatabaseProxy> het exemplaar van de database vertegenwoordigt 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

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

Parameters

conn_str

str

Vereist

De connection string.

credential

str of dict(str, str)

standaardwaarde: None

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

consistency_level

Optional[str]

standaardwaarde: None

Consistentieniveau dat moet worden gebruikt voor de sessie. De standaardwaarde is Geen (accountniveau).

Uitzonderingen

CosmosResourceExistsError

De database met de opgegeven id bestaat al.

get_database_account

Haal de gegevens van het databaseaccount op.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parameters

response_hook

Callable

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

Retouren

Een DatabaseAccount-exemplaar dat het Cosmos DB-databaseaccount vertegenwoordigt.

Retourtype

DatabaseAccount

Uitzonderingen

CosmosResourceExistsError

De database met de opgegeven id bestaat al.

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

str of dict(str, str) of DatabaseProxy

Vereist

De id (naam), de dict die de eigenschappen of het DatabaseProxy-exemplaar van de database vertegenwoordigt die moet worden gelezen.

Retouren

Een DatabaseProxy-exemplaar dat de opgehaalde database vertegenwoordigt.

Retourtype

DatabaseProxy

Uitzonderingen

CosmosResourceExistsError

De database met de opgegeven id bestaat al.

list_databases

De databases in een Cosmos DB SQL-databaseaccount weergeven.

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

Parameters

max_item_count

int

Vereist

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

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

Retouren

Een iterable van database-eigenschappen (dicts).

Retourtype

Iterable[dict[str, str]]

Uitzonderingen

CosmosResourceExistsError

De database met de opgegeven id bestaat al.

query_databases

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

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

Parameters

query

str

Vereist

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

parameters

List[Dict[str, Any]]

Vereist

Optionele matrix met parameters voor de query. Genegeerd als er geen query is opgegeven.

enable_cross_partition_query

bool

Vereist

Scannen toestaan op de query's die niet konden worden uitgevoerd als indexering, is afgemeld voor de aangevraagde paden.

max_item_count

int

Vereist

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

Een aanroepbare aangeroepen met de antwoordmetagegevens.

Retouren

Een iterable van database-eigenschappen (dicts).

Retourtype

Iterable[dict[str, str]]

Uitzonderingen

CosmosResourceExistsError

De database met de opgegeven id bestaat al.