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

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

DatabaseProxy

Ausnahmen

CosmosHttpResponseError

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

None

Ausnahmen

CosmosHttpResponseError

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

CosmosResourceExistsError

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

DatabaseAccount

Ausnahmen

CosmosResourceExistsError

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

DatabaseProxy

Ausnahmen

CosmosResourceExistsError

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

Iterable[dict[str, str]]

Ausnahmen

CosmosResourceExistsError

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

Iterable[dict[str, str]]

Ausnahmen

CosmosResourceExistsError

Die Datenbank mit der angegebenen ID ist bereits vorhanden.