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, de standaardwaarde is True.

connection_cert

str

Een alternatief certificaat om de verbinding te verifiëren.

retry_total

int

Maximum aantal nieuwe pogingen.

retry_backoff_max

int

Maximale wachttijd voor opnieuw proberen 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 nieuwe pogingen voor verbindingsfouten.

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

Logger 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 geen doorvoer aangeboden als deze afwijken van wat wordt doorgegeven.
delete_database	Verwijder de database met de opgegeven id (naam).
from_connection_string	Maak een CosmosClient-exemplaar 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 aangeroepen met de antwoordmetagegevens.

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 geen doorvoer aangeboden als deze afwijken 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 geretourneerde 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 aangeroepen met de antwoordmetagegevens.

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), het dictaat dat de eigenschappen of 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 aangeroepen met de antwoordmetagegevens.

Retourtype

None

Uitzonderingen

CosmosHttpResponseError

Als de database niet kan worden verwijderd.

from_connection_string

Maak een CosmosClient-exemplaar 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 aangeroepen met de antwoordmetagegevens.

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), het dict dat de eigenschappen of het DatabaseProxy-exemplaar van de te lezen database vertegenwoordigt.

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

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 wordt opgegeven.

enable_cross_partition_query

bool

Vereist

Scan toestaan op de query's die niet kunnen worden uitgevoerd omdat 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.