Partager via


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

Exceptions

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

Exceptions

É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

Exceptions

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

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

Exceptions

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

Exceptions

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

Exceptions

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

Exceptions

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