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

Parameter

url

str

Erforderlich

Die URL des Cosmos DB-Kontos.

credential

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

Erforderlich

Dies kann der Kontoschlüssel oder ein Wörterbuch mit Ressourcentoken sein.

consistency_level

str

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

Ob die Verbindung überprüft werden soll, der Standardwert ist 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

Ein Wiederholungsintervall in Millisekunden wurde behoben.

retry_read

int

Maximale Anzahl von Wiederholungsversuchen für Socketlesevorgänge.

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 bestimmten status Codes, an deren Wiederholung versucht werden soll.

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 Anforderungs-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:

       async with CosmosClient(url, key) as client:

Methoden

close	Schließen Sie diese instance von CosmosClient.
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 der übergebenen Funktion 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 aus dem Azure-Portal abgerufen werden. Eine vollständige Liste der optionalen Schlüsselwort (keyword) Argumente finden Sie im CosmosClient-Konstruktor.
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.

close

Schließen Sie diese instance von CosmosClient.

async close() -> None

create_database

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

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

Parameter

id

str

Erforderlich

ID (Name) der zu erstellenden Datenbank.

offer_throughput

Union[int, ThroughputProperties]

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

Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.

Gibt zurück

Ein DatabaseProxy-instance, der die neue Datenbank darstellt.

Rückgabetyp

DatabaseProxy

Ausnahmen

CosmosResourceExistsError

Die Datenbank mit der angegebenen ID ist bereits vorhanden.

Beispiele

Erstellen Sie eine Datenbank im Cosmos DB-Konto:

           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

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 der übergebenen Funktion unterscheiden.

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

Parameter

id

str

Erforderlich

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

offer_throughput

Union[int, ThroughputProperties]

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

Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.

Gibt zurück

Ein DatabaseProxy-instance, der die Datenbank darstellt.

Rückgabetyp

DatabaseProxy

Ausnahmen

CosmosHttpResponseError

Fehler beim Lesen oder Erstellen der Datenbank.

delete_database

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

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

Parameter

database

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

Erforderlich

Die ID (Name), das Diktat, das die Eigenschaften darstellt, oder DatabaseProxy instance der zu löschenden Datenbank.

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

Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.

Rückgabetyp

None

Ausnahmen

CosmosHttpResponseError

Wenn die Datenbank nicht gelöscht werden konnte.

from_connection_string

Erstellen Sie eine CosmosClient-instance aus einer Verbindungszeichenfolge.

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

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

Parameter

conn_str

str

Erforderlich

Verbindungszeichenfolge.

credential

Union[str, Dict[str, str]]

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

consistency_level

str

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

Gibt zurück

CosmosClient-instance

Rückgabetyp

CosmosClient

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

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

Erforderlich

Die ID (Name), das Diktat, das die Eigenschaften darstellt, oder DatabaseProxy instance der abzurufenden Datenbank.

Gibt zurück

Ein DatabaseProxy-instance, der die abgerufene Datenbank darstellt.

Rückgabetyp

DatabaseProxy

list_databases

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

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

Parameter

max_item_count

int

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

Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.

Gibt zurück

Eine AsyncItemPaged der Datenbankeigenschaften (dicts).

Rückgabetyp

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

query_databases

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

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

Parameter

query

Union[str, Dict[str, Any]]

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

parameters

List[Dict[str, Any]]

Optionales Array von Parametern für die Abfrage. Jeder Parameter ist ein dict() mit den Schlüsseln "name" und "value".

max_item_count

int

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

Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.

Gibt zurück

Eine AsyncItemPaged der Datenbankeigenschaften (dicts).

Rückgabetyp

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