CosmosClient Classe

Représentation logique côté client d’un compte Azure Cosmos DB.

Utilisez ce client pour configurer et exécuter des requêtes adressées au service Azure Cosmos DB.

Il est recommandé de conserver une seule instance de CosmosClient par durée de vie de l’application, ce qui permet une gestion et des performances efficaces des connexions.

L’initialisation de CosmosClient est une opération lourde : n’utilisez pas d’initialisation d’instances CosmosClient comme informations d’identification ou validations de connectivité réseau.

Instanciez un nouveau CosmosClient.

Héritage

builtins.object

CosmosClient

Constructeur

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

Paramètres

url

str

Obligatoire

URL du compte Cosmos DB.

credential

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

Obligatoire

Il peut s’agir de la clé de compte ou d’un dictionnaire de jetons de ressource.

consistency_level

str

Niveau de cohérence à utiliser pour la session. La valeur par défaut est None (au niveau du compte). En savoir plus sur les niveaux de cohérence et les valeurs possibles : https://aka.ms/cosmos-consistency-levels

timeout

int

Délai d’attente absolu en secondes pour le traitement combiné de la requête ET de la réponse HTTP.

connection_timeout

int

Délai d’expiration de la requête HTTP en secondes.

connection_mode

str

Le mode de connexion pour le client ne prend actuellement en charge que « Passerelle ».

proxy_config

ProxyConfiguration

Configuration du proxy de connexion.

ssl_config

SSLConfiguration

Configuration SSL de connexion.

connection_verify

bool

Pour vérifier la connexion, la valeur par défaut est True.

connection_cert

str

Un autre certificat pour vérifier la connexion.

retry_total

int

Nombre maximal de nouvelles tentatives.

retry_backoff_max

int

Temps d’attente maximal des nouvelles tentatives en secondes.

retry_fixed_interval

int

Correction de l’intervalle de nouvelles tentatives en millisecondes.

retry_read

int

Nombre maximal de tentatives de lecture de socket.

retry_connect

int

Nombre maximal de tentatives de nouvelle tentative d’erreur de connexion.

retry_status

int

Nombre maximal de nouvelles tentatives sur les codes de status d’erreur.

retry_on_status_codes

list[int]

Liste des codes status spécifiques sur lesquels réessayer.

retry_backoff_factor

float

Facteur pour calculer le temps d’attente entre les tentatives de nouvelle tentative.

enable_endpoint_discovery

bool

Activez la découverte de point de terminaison pour les comptes de base de données géorépliqués. (Valeur par défaut : True)

preferred_locations

list[str]

Emplacements préférés pour les comptes de base de données géorépliqués.

enable_diagnostics_logging

bool

Activez la stratégie CosmosHttpLogging. Doit être utilisé avec un enregistreur d’événements pour fonctionner.

logger

Logger

Enregistreur d’événements à utiliser pour collecter les diagnostics de requête. Peut être transmis au niveau du client (pour journaliser toutes les demandes) ou à un seul niveau de requête. Les demandes seront enregistrées au niveau INFO.

Exemples

Créez une instance du client Cosmos DB :

       async with CosmosClient(url, key) as client:

Méthodes

close	Fermez cette instance de CosmosClient.
create_database	Créez une base de données avec l’ID (nom) donné.
create_database_if_not_exists	Créez la base de données si elle n’existe pas déjà. Si la base de données existe déjà, les paramètres existants sont retournés. .. remarque :: cette fonction ne case activée ni ne met à jour les paramètres de base de données existants ou n’offre pas de débit s’ils diffèrent de ce qui est transmis.
delete_database	Supprimez la base de données avec l’ID (nom) donné.
from_connection_string	Créez un instance CosmosClient à partir d’une chaîne de connexion. Il peut être récupéré à partir du Portail Azure. Pour obtenir la liste complète des arguments mot clé facultatifs, consultez le constructeur CosmosClient.
get_database_client	Récupérez une base de données existante avec l’ID (nom) ID.
list_databases	Répertoriez les bases de données d’un compte de base de données SQL Cosmos DB.
query_databases	Interrogez les bases de données dans un compte de base de données SQL Cosmos DB.

close

Fermez cette instance de CosmosClient.

async close() -> None

create_database

Créez une base de données avec l’ID (nom) donné.

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

Paramètres

id

str

Obligatoire

ID (nom) de la base de données à créer.

offer_throughput

Union[int, ThroughputProperties]

Débit provisionné pour cette offre.

session_token

str

Jeton à utiliser avec la cohérence de session.

initial_headers

dict[str, str]

En-têtes initiaux à envoyer dans le cadre de la demande.

etag

str

Spécifiez une valeur ETag ou le caractère générique *. Permet de case activée si la ressource a changé et d’agir en fonction de la condition spécifiée par le paramètre match_condition.

match_condition

MatchConditions

Condition de correspondance à utiliser sur l’etag.

response_hook

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

Appelable avec les métadonnées de réponse.

Retours

Une instance DatabaseProxy représentant la nouvelle base de données.

Type de retour

DatabaseProxy

Exceptions

CosmosResourceExistsError

La base de données avec l’ID donné existe déjà.

Exemples

Créez une base de données dans le compte 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

Créez la base de données si elle n’existe pas déjà.

Si la base de données existe déjà, les paramètres existants sont retournés.

.. remarque :: cette fonction ne case activée ni ne met à jour les paramètres de base de données existants ou n’offre pas de débit s’ils diffèrent de ce qui est transmis.

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

Paramètres

id

str

Obligatoire

ID (nom) de la base de données à lire ou à créer.

offer_throughput

Union[int, ThroughputProperties]

Débit provisionné pour cette offre.

session_token

str

Jeton à utiliser avec la cohérence de session.

initial_headers

dict[str, str]

En-têtes initiaux à envoyer dans le cadre de la demande.

etag

str

Spécifiez une valeur ETag ou le caractère générique *. Permet de case activée si la ressource a changé et d’agir en fonction de la condition spécifiée par le paramètre match_condition.

match_condition

MatchConditions

Condition de correspondance à utiliser sur l’etag.

response_hook

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

Appelable avec les métadonnées de réponse.

Retours

Une instance DatabaseProxy représentant la base de données.

Type de retour

DatabaseProxy

Exceptions

CosmosHttpResponseError

Échec de la lecture ou de la création de la base de données.

delete_database

Supprimez la base de données avec l’ID (nom) donné.

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

Paramètres

database

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

Obligatoire

ID (nom), dict représentant les propriétés ou DatabaseProxy instance de la base de données à supprimer.

session_token

str

Jeton à utiliser avec la cohérence de session.

initial_headers

dict[str, str]

En-têtes initiaux à envoyer dans le cadre de la demande.

etag

str

Spécifiez une valeur ETag ou le caractère générique *. Permet de case activée si la ressource a changé et d’agir en fonction de la condition spécifiée par le paramètre match_condition.

match_condition

MatchConditions

Condition de correspondance à utiliser sur l’etag.

response_hook

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

Appelable avec les métadonnées de réponse.

Type de retour

None

Exceptions

CosmosHttpResponseError

Si la base de données n’a pas pu être supprimée.

from_connection_string

Créez un instance CosmosClient à partir d’une chaîne de connexion.

Il peut être récupéré à partir du Portail Azure. Pour obtenir la liste complète des arguments mot clé facultatifs, consultez le constructeur CosmosClient.

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

Paramètres

conn_str

str

Obligatoire

Chaîne de connexion

credential

Union[str, Dict[str, str]]

Autres informations d’identification à utiliser au lieu de la clé fournie dans la chaîne de connexion.

consistency_level

str

Niveau de cohérence à utiliser pour la session. La valeur par défaut est None (au niveau du compte). En savoir plus sur les niveaux de cohérence et les valeurs possibles : https://aka.ms/cosmos-consistency-levels

Retours

un instance CosmosClient

Type de retour

CosmosClient

get_database_client

Récupérez une base de données existante avec l’ID (nom) ID.

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

Paramètres

database

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

Obligatoire

ID (nom), dict représentant les propriétés ou DatabaseProxy instance de la base de données à obtenir.

Retours

Une instance DatabaseProxy représentant la base de données récupérée.

Type de retour

DatabaseProxy

list_databases

Répertoriez les bases de données d’un compte de base de données SQL Cosmos DB.

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

Paramètres

max_item_count

int

Nombre maximal d’éléments à retourner dans l’opération d’énumération.

session_token

str

Jeton à utiliser avec la cohérence de session.

initial_headers

dict[str, str]

En-têtes initiaux à envoyer dans le cadre de la demande.

response_hook

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

Appelable avec les métadonnées de réponse.

Retours

AsyncItemPaged des propriétés de base de données (dicts).

Type de retour

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

query_databases

Interrogez les bases de données dans un compte de base de données SQL Cosmos DB.

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

Paramètres

query

Union[str, Dict[str, Any]]

Requête SQL Azure Cosmos DB à exécuter.

parameters

List[Dict[str, Any]]

Tableau facultatif de paramètres de la requête. Chaque paramètre est un dict() avec les clés « name » et « value ».

max_item_count

int

Nombre maximal d’éléments à retourner dans l’opération d’énumération.

session_token

str

Jeton à utiliser avec la cohérence de session.

initial_headers

dict[str, str]

En-têtes initiaux à envoyer dans le cadre de la demande.

response_hook

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

Appelable avec les métadonnées de réponse.

Retours

AsyncItemPaged des propriétés de base de données (dicts).

Type de retour

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