Freigeben über


CosmosClient Klasse

Eine clientseitige logische Darstellung eines Azure Cosmos DB-Kontos.

Verwenden Sie diesen Client, um Anforderungen an den Azure Cosmos DB-Dienst zu konfigurieren und auszuführen.

Es wird empfohlen, eine einzelne instance von CosmosClient pro Lebensdauer der Anwendung beizubehalten, was eine effiziente Verbindungsverwaltung und -leistung ermöglicht.

Die CosmosClient-Initialisierung ist ein umfangreicher Vorgang. Verwenden Sie keine CosmosClient-Initialisierungsinstanzen als Anmeldeinformationen oder Netzwerkkonnektivitätsüberprüfungen.

Instanziieren sie einen neuen CosmosClient.

Vererbung
builtins.object
CosmosClient

Konstruktor

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

Parameter

url
str
Erforderlich

Die URL des Cosmos DB-Kontos.

credential
Union[str, Dict[str, str], TokenCredential]
Erforderlich

Kann der Kontoschlüssel oder ein Wörterbuch von Ressourcentoken sein.

consistency_level
str
Standardwert: None

Konsistenzebene, die für die Sitzung verwendet werden soll. Der Standardwert ist None (Kontoebene). Weitere Informationen zu Konsistenzebenen und möglichen Werten: https://aka.ms/cosmos-consistency-levels

timeout
int

Ein absolutes Timeout in Sekunden für die kombinierte HTTP-Anforderungs- und Antwortverarbeitung.

connection_timeout
int

Das HTTP-Anforderungstimeout in Sekunden.

connection_mode
str

Der Verbindungsmodus für den Client – unterstützt derzeit nur "Gateway".

proxy_config
ProxyConfiguration

Verbindungsproxykonfiguration.

ssl_config
SSLConfiguration

SSL-Konfiguration der Verbindung.

connection_verify
bool

Unabhängig davon, ob die Verbindung überprüft werden soll, ist der Standardwert True.

connection_cert
str

Ein alternatives Zertifikat zum Überprüfen der Verbindung.

retry_total
int

Maximale Wiederholungsversuche.

retry_backoff_max
int

Maximale Wiederholungswartezeit in Sekunden.

retry_fixed_interval
int

Wiederholungsintervall in Millisekunden korrigiert.

retry_read
int

Maximale Anzahl von Socketleseversuchen.

retry_connect
int

Maximale Anzahl von Wiederholungsversuchen bei Verbindungsfehlern.

retry_status
int

Maximale Anzahl von Wiederholungsversuchen für Fehler status Codes.

retry_on_status_codes
list[int]

Eine Liste mit spezifischen status Codes, die wiederholt werden sollen.

retry_backoff_factor
float

Faktor zum Berechnen der Wartezeit zwischen Wiederholungsversuchen.

enable_endpoint_discovery
bool

Aktivieren Sie die Endpunktermittlung für georeplizierte Datenbankkonten. (Standard: TRUE)

preferred_locations
list[str]

Die bevorzugten Speicherorte für georeplizierte Datenbankkonten.

enable_diagnostics_logging
bool

Aktivieren Sie die CosmosHttpLogging-Richtlinie. Muss zusammen mit einer Protokollierung verwendet werden, um zu funktionieren.

logger
Logger

Protokollierung, die zum Sammeln von Anforderungsanforderungen Diagnose verwendet werden soll. Kann auf Clientebene (zum Protokollieren aller Anforderungen) oder auf einer einzelnen Anforderungsebene übergeben werden. Anforderungen werden auf INFO-Ebene protokolliert.

Beispiele

Erstellen Sie eine neue instance des Cosmos DB-Clients:


   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

Erstellen Sie eine neue Datenbank mit der angegebenen ID (Name).

create_database_if_not_exists

Erstellen Sie die Datenbank, wenn sie noch nicht vorhanden ist.

Wenn die Datenbank bereits vorhanden ist, werden die vorhandenen Einstellungen zurückgegeben.

.. Hinweis:: Diese Funktion überprüft oder aktualisiert keine vorhandenen Datenbankeinstellungen oder bietet keinen Durchsatz, wenn sie sich von dem, was übergeben wird, unterscheiden.

delete_database

Löschen Sie die Datenbank mit der angegebenen ID (Name).

from_connection_string

Erstellen Sie eine CosmosClient-instance aus einer Verbindungszeichenfolge.

Dies kann vom Azure-Portal abgerufen werden. Eine vollständige Liste optionaler Schlüsselwort (keyword) Argumente finden Sie im CosmosClient-Konstruktor.

get_database_account

Rufen Sie die Datenbankkontoinformationen ab.

get_database_client

Rufen Sie eine vorhandene Datenbank mit der ID (Name) -ID ab.

list_databases

Listen Sie die Datenbanken in einem Cosmos DB SQL-Datenbankkonto auf.

query_databases

Fragen Sie die Datenbanken in einem Cosmos DB-SQL-Datenbankkonto ab.

create_database

Erstellen Sie eine neue Datenbank mit der angegebenen ID (Name).

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

Parameter

id
Erforderlich

ID (Name) der zu erstellenden Datenbank.

offer_throughput
Erforderlich

Der bereitgestellte Durchsatz für dieses Angebot.

session_token
str

Token zur Verwendung mit Sitzungskonsistenz.

initial_headers
dict[str,str]

Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.

etag
str

Ein ETag-Wert oder das Platzhalterzeichen (*). Wird verwendet, um zu überprüfen, ob sich die Ressource geändert hat, und handelt gemäß der Bedingung, die vom parameter match_condition angegeben wird.

match_condition
MatchConditions

Die Übereinstimmungsbedingung, die für das etag verwendet werden soll.

response_hook
Callable

Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.

Gibt zurück

Eine DatabaseProxy-instance, die die neue Datenbank darstellt.

Rückgabetyp

Ausnahmen

Die Datenbank mit der angegebenen ID ist bereits vorhanden.

Beispiele

Erstellen Sie eine Datenbank im Cosmos DB-Konto:


   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

Erstellen Sie die Datenbank, wenn sie noch nicht vorhanden ist.

Wenn die Datenbank bereits vorhanden ist, werden die vorhandenen Einstellungen zurückgegeben.

.. Hinweis:: Diese Funktion überprüft oder aktualisiert keine vorhandenen Datenbankeinstellungen oder bietet keinen Durchsatz, wenn sie sich von dem, was übergeben wird, unterscheiden.

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

Parameter

id
Erforderlich

ID (Name) der zu lesenden oder zu erstellenden Datenbank.

populate_query_metrics
bool
Erforderlich

Aktivieren Sie die Rückgabe von Abfragemetriken in Antwortheadern.

offer_throughput
int oder <xref:azure.cosmos.ThroughputProperties.>
Erforderlich

Der bereitgestellte Durchsatz für dieses Angebot.

session_token
str

Token zur Verwendung mit Sitzungskonsistenz.

initial_headers
dict[str,str]

Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.

etag
str

Ein ETag-Wert oder das Platzhalterzeichen (*). Wird verwendet, um zu überprüfen, ob sich die Ressource geändert hat, und handelt gemäß der Bedingung, die vom parameter match_condition angegeben wird.

match_condition
MatchConditions

Die Übereinstimmungsbedingung, die für das etag verwendet werden soll.

response_hook
Callable

Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.

Gibt zurück

Eine DatabaseProxy-instance, die die Datenbank darstellt.

Rückgabetyp

Ausnahmen

Fehler beim Lesen oder Erstellen der Datenbank.

delete_database

Löschen Sie die Datenbank mit der angegebenen ID (Name).

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

Parameter

database
str oder dict(str, str) oder DatabaseProxy
Erforderlich

Die ID (Name), das Diktat, das die Eigenschaften oder <xref:azure.cosmos.cosmos_client.DatabaseProxy> instance der zu löschenden Datenbank darstellt.

session_token
str

Token zur Verwendung mit Sitzungskonsistenz.

initial_headers
dict[str,str]

Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.

etag
str

Ein ETag-Wert oder das Platzhalterzeichen (*). Wird verwendet, um zu überprüfen, ob sich die Ressource geändert hat, und handelt gemäß der Bedingung, die vom parameter match_condition angegeben wird.

match_condition
MatchConditions

Die Übereinstimmungsbedingung, die für das etag verwendet werden soll.

response_hook
Callable

Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.

Rückgabetyp

Ausnahmen

Wenn die Datenbank nicht gelöscht werden konnte.

from_connection_string

Erstellen Sie eine CosmosClient-instance aus einer Verbindungszeichenfolge.

Dies kann vom Azure-Portal abgerufen werden. Eine vollständige Liste optionaler Schlüsselwort (keyword) Argumente finden Sie im CosmosClient-Konstruktor.

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

Parameter

conn_str
str
Erforderlich

Verbindungszeichenfolge.

credential
str oder dict(str, str)
Standardwert: None

Alternative Anmeldeinformationen, die anstelle des in der Verbindungszeichenfolge angegebenen Schlüssels verwendet werden sollen.

consistency_level
Optional[str]
Standardwert: None

Konsistenzebene, die für die Sitzung verwendet werden soll. Der Standardwert ist None (Kontoebene).

Ausnahmen

Die Datenbank mit der angegebenen ID ist bereits vorhanden.

get_database_account

Rufen Sie die Datenbankkontoinformationen ab.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parameter

response_hook
Callable

Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.

Gibt zurück

Ein DatabaseAccount-instance, das das Cosmos DB-Datenbankkonto darstellt.

Rückgabetyp

Ausnahmen

Die Datenbank mit der angegebenen ID ist bereits vorhanden.

get_database_client

Rufen Sie eine vorhandene Datenbank mit der ID (Name) -ID ab.

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

Parameter

database
str oder dict(str, str) oder DatabaseProxy
Erforderlich

Die ID (Name), das Diktat, das die Eigenschaften oder databaseProxy instance der zu lesenden Datenbank darstellt.

Gibt zurück

Eine DatabaseProxy-instance, die die abgerufene Datenbank darstellt.

Rückgabetyp

Ausnahmen

Die Datenbank mit der angegebenen ID ist bereits vorhanden.

list_databases

Listen Sie die Datenbanken in einem Cosmos DB SQL-Datenbankkonto auf.

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

Parameter

max_item_count
int
Erforderlich

Maximale Anzahl von Elementen, die im Enumerationsvorgang zurückgegeben werden sollen.

session_token
str

Token zur Verwendung mit Sitzungskonsistenz.

initial_headers
dict[str,str]

Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.

response_hook
Callable

Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.

Gibt zurück

Eine Iterable von Datenbankeigenschaften (dicts).

Rückgabetyp

Ausnahmen

Die Datenbank mit der angegebenen ID ist bereits vorhanden.

query_databases

Fragen Sie die Datenbanken in einem Cosmos DB-SQL-Datenbankkonto ab.

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

Parameter

query
str
Erforderlich

Die auszuführende Azure Cosmos DB-SQL-Abfrage.

parameters
List[Dict[str, Any]]
Erforderlich

Optionales Array von Parametern für die Abfrage. Wird ignoriert, wenn keine Abfrage bereitgestellt wird.

enable_cross_partition_query
bool
Erforderlich

Lassen Sie die Überprüfung der Abfragen zu, die nicht verwendet werden konnten, da die Indizierung für die angeforderten Pfade deaktiviert wurde.

max_item_count
int
Erforderlich

Maximale Anzahl von Elementen, die im Enumerationsvorgang zurückgegeben werden sollen.

session_token
str

Token zur Verwendung mit Sitzungskonsistenz.

initial_headers
dict[str,str]

Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.

response_hook
Callable

Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.

Gibt zurück

Eine Iterable von Datenbankeigenschaften (Diktaten).

Rückgabetyp

Ausnahmen

Die Datenbank mit der angegebenen ID ist bereits vorhanden.