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

Dies kann der Kontoschlüssel oder ein Wörterbuch mit 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

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:

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

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

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), Diktat, die die Eigenschaften oder 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, 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: 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, 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), dikt, die die Eigenschaften oder databaseProxy instance der zu lesenden Datenbank darstellt.

Gibt zurück

Ein DatabaseProxy-instance, der 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, 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.

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 für die Abfragen zu, die nicht bereitgestellt 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.