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 di connessione efficienti.

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

Creare un'istanza di un nuovo CosmosClient.

Ereditarietà

builtins.object

CosmosClient

Costruttore

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

Parametri

url

str

Necessario

URL dell'account Cosmos DB.

credential

Union[str, Dict[str, str], TokenCredential]

Necessario

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

consistency_level

str

valore predefinito: None

Livello di coerenza da usare per la sessione. Il valore predefinito è Nessuno (livello 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:

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

Metodi

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_account	Recuperare le informazioni sull'account del database.
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.

create_database

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

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

Parametri

id

Necessario

ID (nome) del database da creare.

offer_throughput

Necessario

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

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

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

Parametri

id

Necessario

ID (nome) del database da leggere o creare.

populate_query_metrics

bool

Necessario

Abilitare la restituzione delle metriche di query nelle intestazioni di risposta.

offer_throughput

int oppure <xref:azure.cosmos.ThroughputProperties.>

Necessario

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

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.

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

Parametri

database

str oppure dict(str, str) oppure DatabaseProxy

Necessario

ID (nome), che rappresenta le proprietà o <xref:azure.cosmos.cosmos_client.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

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: Any | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Parametri

conn_str

str

Necessario

Stringa di connessione.

credential

str oppure dict(str, str)

valore predefinito: None

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

consistency_level

Optional[str]

valore predefinito: None

Livello di coerenza da usare per la sessione. Il valore predefinito è Nessuno (livello account).

Eccezioni

CosmosResourceExistsError

Il database con l'ID specificato esiste già.

get_database_account

Recuperare le informazioni sull'account del database.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parametri

response_hook

Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Istanza di DatabaseAccount che rappresenta l'account del database Cosmos DB.

Tipo restituito

DatabaseAccount

Eccezioni

CosmosResourceExistsError

Il database con l'ID specificato esiste già.

get_database_client

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

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

Parametri

database

str oppure dict(str, str) oppure DatabaseProxy

Necessario

ID (nome), che rappresenta le proprietà o l'istanza databaseProxy del database da leggere.

Restituisce

Istanza di DatabaseProxy che rappresenta il database recuperato.

Tipo restituito

DatabaseProxy

Eccezioni

CosmosResourceExistsError

Il database con l'ID specificato esiste già.

list_databases

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

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

Parametri

max_item_count

int

Necessario

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Iterabile delle proprietà del database (dict).

Tipo restituito

Iterable[dict[str, str]]

Eccezioni

CosmosResourceExistsError

Il database con l'ID specificato esiste già.

query_databases

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

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

Parametri

query

str

Necessario

Query SQL di Azure Cosmos DB da eseguire.

parameters

List[Dict[str, Any]]

Necessario

Matrice facoltativa di parametri per la query. Ignorato se non viene specificata alcuna query.

enable_cross_partition_query

bool

Necessario

Consentire l'analisi sulle query che non è stato possibile servire come indicizzazione è stata esplicitamente disattivata sui percorsi richiesti.

max_item_count

int

Necessario

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

session_token

str

Token da usare con coerenza sessione.

initial_headers

dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook

Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Iterabile delle proprietà del database (dict).

Tipo restituito

Iterable[dict[str, str]]

Eccezioni

CosmosResourceExistsError

Il database con l'ID specificato esiste già.