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.objectCosmosClient
Constructeur
CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)
Paramètres
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 (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_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)
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 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_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) 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. |
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
ID (nom) de la base de données à créer.
- offer_throughput
Débit provisionné pour cette offre.
- session_token
- str
Jeton à utiliser avec la cohérence de session.
- 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
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 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.
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
ID (nom) de la base de données à lire ou à créer.
- populate_query_metrics
- bool
Activez le retour des métriques de requête dans les en-têtes de réponse.
- offer_throughput
- int ou <xref:azure.cosmos.ThroughputProperties.>
Débit provisionné pour cette offre.
- session_token
- str
Jeton à utiliser avec la cohérence de session.
- 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
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
ID (nom), dict représentant les propriétés ou <xref:azure.cosmos.cosmos_client.DatabaseProxy> instance de la base de données à supprimer.
- session_token
- str
Jeton à utiliser avec la cohérence de session.
- 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
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
Autres informations d’identification à utiliser au lieu de la clé fournie dans la chaîne de connexion.
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
Un 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) ID.
get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy
Paramètres
- database
- str ou dict(str, str) ou DatabaseProxy
ID (nom), dict représentant les propriétés ou DatabaseProxy instance de la base de données à lire.
Retours
Une instance DatabaseProxy 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épertoriez les bases de données d’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
Nombre maximal d’éléments à retourner dans l’opération d’énumération.
- session_token
- str
Jeton à utiliser avec la cohérence de session.
- 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
Tableau facultatif de paramètres de la requête. Ignoré si aucune requête n’est fournie.
- enable_cross_partition_query
- bool
Autoriser l’analyse sur les requêtes qui ne pouvaient pas être servies en tant qu’indexation a été désactivé sur les chemins d’accès demandés.
- 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.
- 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à.
Azure SDK for Python
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour