CosmosClient Classe

Rappresentazione logica lato client di un account Azure Cosmos DB.

Usare questo client per configurare ed eseguire richieste al servizio Azure Cosmos DB.

È consigliabile mantenere una singola istanza di CosmosClient per durata dell'applicazione, che consente una gestione e prestazioni efficienti delle connessioni.

L'inizializzazione di CosmosClient è un'operazione pesante: non usare le istanze cosmosClient di inizializzazione come credenziali o convalide della connettività di rete.

Creare un'istanza di un nuovo CosmosClient.

Ereditarietà

builtins.object

CosmosClient

Costruttore

CosmosClient(url: str, credential: str | Dict[str, str] | TokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

Parametri

url

str

Necessario

URL dell'account Cosmos DB.

credential

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

Necessario

Può essere la chiave dell'account o un dizionario di token di risorsa.

consistency_level

str

Livello di coerenza da usare per la sessione. Il valore predefinito è Nessuno (a livello di account). Altre informazioni sui livelli di coerenza e sui valori possibili: https://aka.ms/cosmos-consistency-levels

timeout

int

Timeout assoluto in secondi, per l'elaborazione combinata della richiesta HTTP e della risposta.

connection_timeout

int

Timeout della richiesta HTTP in secondi.

connection_mode

str

La modalità di connessione per il client, attualmente supporta solo "Gateway".

proxy_config

ProxyConfiguration

Configurazione del proxy di connessione.

ssl_config

SSLConfiguration

Configurazione SSL della connessione.

connection_verify

bool

Indica se verificare la connessione, il valore predefinito è True.

connection_cert

str

Un certificato alternativo per verificare la connessione.

retry_total

int

Numero massimo di tentativi.

retry_backoff_max

int

Tempo massimo di attesa dei tentativi in secondi.

retry_fixed_interval

int

È stato risolto l'intervallo di ripetizione dei tentativi in millisecondi.

retry_read

int

Numero massimo di tentativi di lettura socket.

retry_connect

int

Numero massimo di tentativi di errore di connessione.

retry_status

int

Numero massimo di tentativi sui codici di stato degli errori.

retry_on_status_codes

list[int]

Elenco di codici di stato specifici da riprovare.

retry_backoff_factor

float

Fattore per calcolare il tempo di attesa tra i tentativi.

enable_endpoint_discovery

bool

Abilitare l'individuazione degli endpoint per gli account di database con replica geografica. (Impostazione predefinita: True)

preferred_locations

list[str]

Le posizioni preferite per gli account di database con replica geografica.

enable_diagnostics_logging

bool

Abilitare i criteri CosmosHttpLogging. Deve essere usato insieme a un logger per funzionare.

logger

Logger

Logger da usare per la raccolta della diagnostica delle richieste. Può essere passato a livello di client (per registrare tutte le richieste) o a un singolo livello di richiesta. Le richieste verranno registrate a livello di INFO.

Esempio

Creare una nuova istanza del client Cosmos DB:

       async with CosmosClient(url, key) as client:

Metodi

close	Chiudere questa istanza di CosmosClient.
create_database	Creare un nuovo database con l'ID (nome) specificato.
create_database_if_not_exists	Creare il database se non esiste già. Se il database esiste già, vengono restituite le impostazioni esistenti. .. nota: questa funzione non controlla o aggiorna le impostazioni del database esistenti o offre velocità effettiva se differisce da quella passata.
delete_database	Eliminare il database con l'ID (nome) specificato.
from_connection_string	Creare un'istanza di CosmosClient da una stringa di connessione. Questa operazione può essere recuperata dal portale di Azure. Per un elenco completo degli argomenti di parole chiave facoltativi, vedere il costruttore CosmosClient.
get_database_client	Recuperare un database esistente con l'ID (nome).
list_databases	Elencare i database in un account di database SQL di Cosmos DB.
query_databases	Eseguire query sui database in un account di database SQL di Cosmos DB.

close

Chiudere questa istanza di CosmosClient.

async close() -> None

create_database

Creare un nuovo database con l'ID (nome) specificato.

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

Parametri

id

str

Necessario

ID (nome) del database da creare.

offer_throughput

Union[int, ThroughputProperties]

Velocità effettiva con provisioning per questa offerta.

session_token

str

Token da usare con coerenza della sessione.

initial_headers

dict[str, str]

Intestazioni iniziali da inviare come parte della richiesta.

etag

str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è stata modificata e agire in base alla condizione specificata dal parametro match_condition .

match_condition

MatchConditions

Condizione di corrispondenza da utilizzare sull'etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Istanza di DatabaseProxy che rappresenta il nuovo database.

Tipo restituito

DatabaseProxy

Eccezioni

CosmosResourceExistsError

Il database con l'ID specificato esiste già.

Esempio

Creare un database nell'account Cosmos DB:

           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

Creare il database se non esiste già.

Se il database esiste già, vengono restituite le impostazioni esistenti.

.. nota: questa funzione non controlla o aggiorna le impostazioni del database esistenti o offre velocità effettiva se differisce da quella passata.

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

Parametri

id

str

Necessario

ID (nome) del database da leggere o creare.

offer_throughput

Union[int, ThroughputProperties]

Velocità effettiva con provisioning per questa offerta.

session_token

str

Token da usare con coerenza della sessione.

initial_headers

dict[str, str]

Intestazioni iniziali da inviare come parte della richiesta.

etag

str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è stata modificata e agire in base alla condizione specificata dal parametro match_condition .

match_condition

MatchConditions

Condizione di corrispondenza da utilizzare sull'etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Istanza di DatabaseProxy che rappresenta il database.

Tipo restituito

DatabaseProxy

Eccezioni

CosmosHttpResponseError

Lettura o creazione del database non riuscita.

delete_database

Eliminare il database con l'ID (nome) specificato.

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

Parametri

database

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

Necessario

ID (nome), dict che rappresenta le proprietà o DatabaseProxy l'istanza del database da eliminare.

session_token

str

Token da usare con coerenza della sessione.

initial_headers

dict[str, str]

Intestazioni iniziali da inviare come parte della richiesta.

etag

str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è stata modificata e agire in base alla condizione specificata dal parametro match_condition .

match_condition

MatchConditions

Condizione di corrispondenza da utilizzare sull'etag.

response_hook

Callable[[Dict[str, str]], None]

Oggetto chiamabile richiamato con i metadati della risposta.

Tipo restituito

None

Eccezioni

CosmosHttpResponseError

Se non è stato possibile eliminare il database.

from_connection_string

Creare un'istanza di CosmosClient da una stringa di connessione.

Questa operazione può essere recuperata dal portale di Azure. Per un elenco completo degli argomenti di parole chiave facoltativi, vedere il costruttore CosmosClient.

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

Parametri

conn_str

str

Necessario

Stringa di connessione.

credential

Union[str, Dict[str, str]]

Credenziali alternative da usare anziché la chiave specificata nella stringa di connessione.

consistency_level

str

Livello di coerenza da usare per la sessione. Il valore predefinito è Nessuno (a livello di account). Altre informazioni sui livelli di coerenza e sui valori possibili: https://aka.ms/cosmos-consistency-levels

Restituisce

un'istanza di CosmosClient

Tipo restituito

CosmosClient

get_database_client

Recuperare un database esistente con l'ID (nome).

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

Parametri

database

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

Necessario

ID (nome), dict che rappresenta le proprietà o DatabaseProxy l'istanza del database da ottenere.

Restituisce

Istanza di DatabaseProxy che rappresenta il database recuperato.

Tipo restituito

DatabaseProxy

list_databases

Elencare i database in un account di database SQL di Cosmos DB.

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

Parametri

max_item_count

int

Numero massimo di elementi da restituire nell'operazione di enumerazione.

session_token

str

Token da usare con coerenza della sessione.

initial_headers

dict[str, str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook

Callable[[Dict[str, str]], None]

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Oggetto AsyncItemPaged delle proprietà del database (dict).

Tipo restituito

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

query_databases

Eseguire query sui database in un account di database SQL di Cosmos DB.

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

Parametri

query

Union[str, Dict[str, Any]]

Query SQL di Azure Cosmos DB da eseguire.

parameters

List[Dict[str, Any]]

Matrice facoltativa di parametri per la query. Ogni parametro è un dict() con chiavi 'name' e 'value'.

max_item_count

int

Numero massimo di elementi da restituire nell'operazione di enumerazione.

session_token

str

Token da usare con coerenza della sessione.

initial_headers

dict[str, str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook

Callable[[Dict[str, str]], None]

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Oggetto AsyncItemPaged delle proprietà del database (dict).

Tipo restituito

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