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

Paramètres

url

str

Obligatoire

URL du compte Cosmos DB.

credential

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

Obligatoire

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

consistency_level

str

valeur par défaut: None

Niveau de cohérence à utiliser pour la session. La valeur par défaut est None (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’expiration 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 du 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

Si vous souhaitez vérifier la connexion, la valeur par défaut est True.

connection_cert

str

Autre certificat pour vérifier la connexion.

retry_total

int

Nombre maximal de tentatives.

retry_backoff_max

int

Temps d’attente maximal de nouvelle tentative en secondes.

retry_fixed_interval

int

Correction de l’intervalle de nouvelle tentative en millisecondes.

retry_read

int

Nombre maximal de tentatives de lecture de socket.

retry_connect

int

Nombre maximal de tentatives d’erreur de connexion.

retry_status

int

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

retry_on_status_codes

list[int]

Liste des codes de status spécifiques sur lesquels effectuer une nouvelle tentative.

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 :

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

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

Méthodes

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 n’case activée ni ne met à jour les paramètres de base de données existants, ni n’offre de débit s’ils diffèrent de ce qui est passé.
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_account	Récupérez les informations du compte de base de données.
get_database_client	Récupérez une base de données existante avec l’ID (nom).
list_databases	Répertorier les bases de données dans 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.

create_database

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

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

Paramètres

id

Obligatoire

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

offer_throughput

Obligatoire

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 selon la condition spécifiée par le paramètre match_condition.

match_condition

MatchConditions

Condition de correspondance à utiliser sur l’etag.

response_hook

Callable

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 = 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 n’case activée ni ne met à jour les paramètres de base de données existants, ni n’offre de débit s’ils diffèrent de ce qui est passé.

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

Paramètres

id

Obligatoire

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

populate_query_metrics

bool

Obligatoire

Activer le retour de métriques de requête dans les en-têtes de réponse.

offer_throughput

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

Obligatoire

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 selon la condition spécifiée par le paramètre match_condition.

match_condition

MatchConditions

Condition de correspondance à utiliser sur l’etag.

response_hook

Callable

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

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

Paramètres

database

str ou dict(str, str) ou DatabaseProxy

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 selon la condition spécifiée par le paramètre match_condition.

match_condition

MatchConditions

Condition de correspondance à utiliser sur l’etag.

response_hook

Callable

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

Paramètres

conn_str

str

Obligatoire

Chaîne de connexion

credential

str ou dict(str, str)

valeur par défaut: None

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

consistency_level

Optional[str]

valeur par défaut: None

Niveau de cohérence à utiliser pour la session. La valeur par défaut est None (niveau du compte).

Exceptions

CosmosResourceExistsError

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

get_database_account

Récupérez les informations du compte de base de données.

get_database_account(**kwargs: Any) -> DatabaseAccount

Paramètres

response_hook

Callable

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

Retours

DatabaseAccount instance représentant le compte de base de données Cosmos DB.

Type de retour

DatabaseAccount

Exceptions

CosmosResourceExistsError

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

get_database_client

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

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

Paramètres

database

str ou dict(str, str) ou DatabaseProxy

Obligatoire

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

Retours

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

Type de retour

DatabaseProxy

Exceptions

CosmosResourceExistsError

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

list_databases

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

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

Paramètres

max_item_count

int

Obligatoire

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

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

Retours

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

Type de retour

Iterable[dict[str, str]]

Exceptions

CosmosResourceExistsError

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

query_databases

Interrogez les bases de données dans un compte de base de données SQL 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]]

Paramètres

query

str

Obligatoire

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

parameters

List[Dict[str, Any]]

Obligatoire

Tableau facultatif de paramètres de la requête. Ignoré si aucune requête n’est fournie.

enable_cross_partition_query

bool

Obligatoire

Autoriser l’analyse sur les requêtes qui n’ont pas pu être servies en tant qu’indexation a été désactivée sur les chemins demandés.

max_item_count

int

Obligatoire

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

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

Retours

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

Type de retour

Iterable[dict[str, str]]

Exceptions

CosmosResourceExistsError

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