Partager via

DatabaseProxy Classe

  • Référence

Interface permettant d’interagir avec une base de données spécifique.

Cette classe ne doit pas être instanciée directement. Utilisez plutôt la <xref:CosmosClient.get_database_client> méthode .

Une base de données contient un ou plusieurs conteneurs, chacun pouvant contenir des éléments, des procédures stockées, des déclencheurs et des fonctions définies par l’utilisateur.

Une base de données peut également avoir des utilisateurs associés, chacun étant configuré avec un ensemble d’autorisations pour accéder à certains conteneurs, procédures stockées, déclencheurs, fonctions définies par l’utilisateur ou éléments.

Une base de données d’API SQL Azure Cosmos DB possède les propriétés générées par le système suivantes. Ces propriétés sont en lecture seule :

  • _rid : ID de ressource.

  • _ts : date de la dernière mise à jour de la ressource. La valeur est un horodateur.

  • _self : URI adressable unique pour la ressource.

  • _etag : etag de ressource requis pour le contrôle d’accès concurrentiel optimiste.

  • _colls : chemin adressable de la ressource de collections.

  • _users : chemin adressable de la ressource users.

Héritage
builtins.object
DatabaseProxy

Constructeur

DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)

Paramètres

client_connection
<xref:ClientSession>
Obligatoire

Client à partir duquel cette base de données a été récupérée.

id
str
Obligatoire

ID (nom) de la base de données.

properties
valeur par défaut: None

Variables

id

ID (nom) de la base de données.

Méthodes

create_container

Créez un conteneur avec l’ID (nom) donné.

Si un conteneur avec l’ID donné existe déjà, une erreur CosmosResourceExistsError est déclenchée.
create_container_if_not_exists

Créez un conteneur s’il n’existe pas déjà.

Si le conteneur existe déjà, les paramètres existants sont retournés. Remarque : elle n’case activée ni ne met à jour les paramètres de conteneur existants ni le débit d’offre s’ils diffèrent de ce qui a été passé dans la méthode.
create_user

Créez un utilisateur dans le conteneur.

Pour mettre à jour ou remplacer un utilisateur existant, utilisez la <xref:ContainerProxy.upsert_user> méthode .
delete_container

Supprimer un conteneur.
delete_user

Supprimez l’utilisateur spécifié du conteneur.
get_container_client

Obtenez un ContainerProxy pour un conteneur avec l’ID (nom) spécifié.
get_throughput

Obtenez l’objet ThroughputProperties pour cette base de données. Si aucune propriété de débit n’existe déjà pour la base de données, une exception est levée. :mot clé callable response_hook : callable appelé avec les métadonnées de réponse. :returns: ThroughputProperties pour la base de données. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError : aucune propriété de débit n’existe pour le conteneur ou

les propriétés de débit n’ont pas pu être récupérées.
get_user_client

Obtenez un UserProxy pour un utilisateur avec l’ID spécifié.
list_containers

Répertoriez les conteneurs dans la base de données.
list_users

Répertorier tous les utilisateurs du conteneur.
query_containers

Répertorier les propriétés des conteneurs dans la base de données active.
query_users

Retourne tous les utilisateurs correspondant à la requête donnée.
read

Lisez les propriétés de la base de données.
read_offer

Obtenez l’objet ThroughputProperties pour cette base de données. Si aucune propriété de débit n’existe déjà pour la base de données, une exception est levée. :mot clé callable response_hook : callable appelé avec les métadonnées de réponse. :returns: ThroughputProperties pour la base de données. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError : aucune propriété de débit n’existe pour le conteneur ou

les propriétés de débit n’ont pas pu être récupérées.
replace_container

Réinitialisez les propriétés du conteneur.

Les modifications de propriété sont conservées immédiatement. Toutes les propriétés non spécifiées sont réinitialisées à leurs valeurs par défaut.
replace_throughput

Remplacez le débit au niveau de la base de données.
replace_user

Remplace l’utilisateur spécifié s’il existe dans le conteneur.
upsert_user

Insérez ou mettez à jour l’utilisateur spécifié.

Si l’utilisateur existe déjà dans le conteneur, il est remplacé. Si l’utilisateur n’existe pas déjà, il est inséré.

create_container

Créez un conteneur avec l’ID (nom) donné.

Si un conteneur avec l’ID donné existe déjà, une erreur CosmosResourceExistsError est déclenchée.

create_container(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Paramètres

id
Obligatoire

ID (nom) du conteneur à créer.

partition_key
Obligatoire

Clé de partition à utiliser pour le conteneur.

indexing_policy
Obligatoire

Stratégie d’indexation à appliquer au conteneur.

default_ttl
Obligatoire

Durée de vie (TTL) par défaut pour les éléments du conteneur. S’ils ne sont pas spécifiés, les éléments n’expirent pas.

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

Débit provisionné pour cette offre.

unique_key_policy
Obligatoire

Stratégie de clé unique à appliquer au conteneur.

conflict_resolution_policy
Obligatoire

Stratégie de résolution des conflits à appliquer au conteneur.

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.

analytical_storage_ttl
int

Durée de vie (TTL) du magasin analytique pour les éléments du conteneur. La valeur None désactive le stockage analytique et la valeur -1 active le stockage analytique sans durée de vie. Notez que le stockage analytique ne peut être activé que sur Synapse Link comptes activés.

Retours

Une instance ContainerProxy représentant le nouveau conteneur.

Type de retour

ContainerProxy

Exceptions

CosmosHttpResponseError

Échec de la création du conteneur.

Exemples

Créez un conteneur avec les paramètres par défaut :


   container_name = "products"
   try:
       container = database.create_container(
           id=container_name, partition_key=PartitionKey(path="/productName")
       )
   except exceptions.CosmosResourceExistsError:
       container = database.get_container_client(container_name)

Créer un conteneur avec des paramètres spécifiques ; dans ce cas, une clé de partition personnalisée :


   customer_container_name = "customers"
   try:
       customer_container = database.create_container(
           id=customer_container_name,
           partition_key=PartitionKey(path="/city"),
           default_ttl=200,
       )
   except exceptions.CosmosResourceExistsError:
       customer_container = database.get_container_client(customer_container_name)

create_container_if_not_exists

Créez un conteneur s’il n’existe pas déjà.

Si le conteneur existe déjà, les paramètres existants sont retournés. Remarque : elle n’case activée ni ne met à jour les paramètres de conteneur existants ni le débit d’offre s’ils diffèrent de ce qui a été passé dans la méthode.

create_container_if_not_exists(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Paramètres

id
Obligatoire

ID (nom) du conteneur à lire ou à créer.

partition_key
Obligatoire

Clé de partition à utiliser pour le conteneur.

indexing_policy
Obligatoire

Stratégie d’indexation à appliquer au conteneur.

default_ttl
Obligatoire

Durée de vie (TTL) par défaut pour les éléments du conteneur. S’ils ne sont pas spécifiés, les éléments n’expirent pas.

populate_query_metrics
Obligatoire

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

offer_throughput
Obligatoire

Débit provisionné pour cette offre.

unique_key_policy
Obligatoire

Stratégie de clé unique à appliquer au conteneur.

conflict_resolution_policy
Obligatoire

Stratégie de résolution des conflits à appliquer au conteneur.

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.

analytical_storage_ttl
int

Durée de vie (TTL) du magasin analytique pour les éléments du conteneur. La valeur None désactive le stockage analytique et la valeur -1 active le stockage analytique sans durée de vie. Notez que le stockage analytique ne peut être activé que sur Synapse Link comptes activés.

Retours

Une instance ContainerProxy représentant le conteneur.

Type de retour

ContainerProxy

Exceptions

CosmosHttpResponseError

Échec de la lecture ou de la création du conteneur.

create_user

Créez un utilisateur dans le conteneur.

Pour mettre à jour ou remplacer un utilisateur existant, utilisez la <xref:ContainerProxy.upsert_user> méthode .

create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Paramètres

body
Obligatoire

Objet de type dict avec une clé d’ID et une valeur représentant l’utilisateur à créer. L’ID utilisateur doit être unique au sein de la base de données et comporter au maximum 255 caractères.

response_hook
Callable

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

Retours

UserProxy instance représentant le nouvel utilisateur.

Type de retour

UserProxy

Exceptions

CosmosHttpResponseError

Si l’utilisateur donné n’a pas pu être créé.

Exemples

Créez un utilisateur de base de données :


   try:
       database.create_user(dict(id="Walter Harp"))
   except exceptions.CosmosResourceExistsError:
       print("A user with that ID already exists.")
   except exceptions.CosmosHttpResponseError as failure:
       print("Failed to create user. Status code:{}".format(failure.status_code))

delete_container

Supprimer un conteneur.

delete_container(container: str | ContainerProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None

Paramètres

container
Obligatoire

ID (nom) du conteneur à supprimer. Vous pouvez transmettre l’ID du conteneur à supprimer, un <xref:azure.cosmos.database.ContainerProxy> instance ou un dict qui représente les propriétés du conteneur.

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 le conteneur n’a pas pu être supprimé.

delete_user

Supprimez l’utilisateur spécifié du conteneur.

delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> None

Paramètres

user
Obligatoire

ID (nom), dict représentant les propriétés ou <xref:azure.cosmos.database.UserProxy> instance de l’utilisateur à supprimer.

response_hook
Callable

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

Type de retour

None

Exceptions

CosmosHttpResponseError

L’utilisateur n’a pas été supprimé.

CosmosResourceNotFoundError

L’utilisateur n’existe pas dans le conteneur.

get_container_client

Obtenez un ContainerProxy pour un conteneur avec l’ID (nom) spécifié.

get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxy

Paramètres

container
Obligatoire

ID (nom) du conteneur, d’un <xref:azure.cosmos.database.ContainerProxy> instance ou d’un dict qui représente les propriétés du conteneur à récupérer.

Retours

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

Type de retour

ContainerProxy

Exceptions

CosmosHttpResponseError

Échec de la création du conteneur.

Exemples

Obtenez un conteneur existant, en gérant une défaillance si elle est rencontrée :


   database = client.get_database_client(database_name)
   container = database.get_container_client(container_name)

get_throughput

Obtenez l’objet ThroughputProperties pour cette base de données. Si aucune propriété de débit n’existe déjà pour la base de données, une exception est levée. :mot clé callable response_hook : callable appelé avec les métadonnées de réponse. :returns: ThroughputProperties pour la base de données. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError : aucune propriété de débit n’existe pour le conteneur ou

les propriétés de débit n’ont pas pu être récupérées.

get_throughput(**kwargs: Any) -> ThroughputProperties

Type de retour

ThroughputProperties

Exceptions

CosmosHttpResponseError

Échec de la création du conteneur.

get_user_client

Obtenez un UserProxy pour un utilisateur avec l’ID spécifié.

get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxy

Paramètres

user
Obligatoire

ID (nom), dict représentant les propriétés ou <xref:azure.cosmos.database.UserProxy> instance de l’utilisateur à récupérer.

Retours

UserProxy instance représentant l’utilisateur récupéré.

Type de retour

UserProxy

Exceptions

CosmosHttpResponseError

Échec de la création du conteneur.

list_containers

Répertoriez les conteneurs dans la base de données.

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

Paramètres

max_item_count
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 de propriétés de conteneur (dicts).

Type de retour

Iterable[dict[str, Any]]

Exceptions

CosmosHttpResponseError

Échec de la création du conteneur.

Exemples

Répertorier tous les conteneurs de la base de données :


   database = client.get_database_client(database_name)
   for container in database.list_containers():
       print("Container ID: {}".format(container['id']))

list_users

Répertorier tous les utilisateurs du conteneur.

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

Paramètres

max_item_count
Obligatoire

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

response_hook
Callable

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

Retours

Itérable des propriétés utilisateur (dicts).

Type de retour

Iterable[dict[str, Any]]

Exceptions

CosmosHttpResponseError

Échec de la création du conteneur.

query_containers

Répertorier les propriétés des conteneurs dans la base de données active.

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

Paramètres

query
Obligatoire

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

parameters
Obligatoire

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

max_item_count
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 de propriétés de conteneur (dicts).

Type de retour

Iterable[dict[str, Any]]

Exceptions

CosmosHttpResponseError

Échec de la création du conteneur.

query_users

Retourne tous les utilisateurs correspondant à la requête donnée.

query_users(query: str, parameters: List[str] | None = None, max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Paramètres

query
Obligatoire

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

parameters
Obligatoire

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

max_item_count
Obligatoire

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

response_hook
Callable

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

Retours

Itérable des propriétés utilisateur (dicts).

Type de retour

Iterable[str, Any]

Exceptions

CosmosHttpResponseError

Échec de la création du conteneur.

read

Lisez les propriétés de la base de données.

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

Paramètres

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.

Type de retour

Dict[<xref:Str>, Any]

Exceptions

CosmosHttpResponseError

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

read_offer

Obtenez l’objet ThroughputProperties pour cette base de données. Si aucune propriété de débit n’existe déjà pour la base de données, une exception est levée. :mot clé callable response_hook : callable appelé avec les métadonnées de réponse. :returns: ThroughputProperties pour la base de données. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError : aucune propriété de débit n’existe pour le conteneur ou

les propriétés de débit n’ont pas pu être récupérées.

read_offer(**kwargs: Any) -> ThroughputProperties

Type de retour

ThroughputProperties

Exceptions

CosmosHttpResponseError

Échec de la création du conteneur.

replace_container

Réinitialisez les propriétés du conteneur.

Les modifications de propriété sont conservées immédiatement. Toutes les propriétés non spécifiées sont réinitialisées à leurs valeurs par défaut.

replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> ContainerProxy

Paramètres

container
Obligatoire

ID (nom), dict qui représente les propriétés ou <xref:azure.cosmos.database.ContainerProxy> instance du conteneur à remplacer.

partition_key
Obligatoire

Clé de partition à utiliser pour le conteneur.

indexing_policy
Obligatoire

Stratégie d’indexation à appliquer au conteneur.

default_ttl
Obligatoire

Durée de vie (TTL) par défaut pour les éléments du conteneur. S’ils ne sont pas spécifiés, les éléments n’expirent pas.

conflict_resolution_policy
Obligatoire

Stratégie de résolution des conflits à appliquer au conteneur.

populate_query_metrics
Obligatoire

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

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

match_condition
MatchConditions

Condition de correspondance à utiliser sur l’etag.

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.

analytical_storage_ttl
int

Durée de vie (TTL) du magasin analytique pour les éléments du conteneur. La valeur None désactive le stockage analytique et la valeur -1 active le stockage analytique sans durée de vie. Notez que le stockage analytique ne peut être activé que sur Synapse Link comptes activés.

Retours

Un containerProxy instance représentant le conteneur une fois le remplacement terminé.

Type de retour

ContainerProxy

Exceptions

CosmosHttpResponseError

Déclenché si le conteneur n’a pas pu être remplacé. Cela inclut si le conteneur avec l’ID donné n’existe pas.

Exemples

Réinitialisez la propriété TTL sur un conteneur et affichez les propriétés mises à jour :


   # Set the TTL on the container to 3600 seconds (one hour)
   database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

   # Display the new TTL setting for the container
   container_props = database.get_container_client(container_name).read()
   print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))

replace_throughput

Remplacez le débit au niveau de la base de données.

replace_throughput(throughput: int | ThroughputProperties | None, **kwargs: Any) -> ThroughputProperties

Paramètres

throughput
Obligatoire

Débit à définir (entier).

response_hook
Callable

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

Retours

ThroughputProperties pour la base de données, mise à jour avec un nouveau débit.

Type de retour

ThroughputProperties

Exceptions

CosmosHttpResponseError

Si aucune propriété de débit n’existe pour la base de données ou si les propriétés de débit n’ont pas pu être mises à jour.

replace_user

Remplace l’utilisateur spécifié s’il existe dans le conteneur.

replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxy

Paramètres

user
Obligatoire

ID (nom), dict représentant les propriétés ou <xref:azure.cosmos.database.UserProxy> instance de l’utilisateur à remplacer.

body
Obligatoire

Objet de type dict qui représente l’utilisateur à remplacer.

response_hook
Callable

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

Retours

UserProxy instance représentant l’utilisateur après le remplacement.

Type de retour

UserProxy

Exceptions

CosmosHttpResponseError

Si le remplacement a échoué ou si l’utilisateur avec l’ID donné n’existe pas.

upsert_user

Insérez ou mettez à jour l’utilisateur spécifié.

Si l’utilisateur existe déjà dans le conteneur, il est remplacé. Si l’utilisateur n’existe pas déjà, il est inséré.

upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Paramètres

body
Obligatoire

Objet de type dict qui représente l’utilisateur à mettre à jour ou à insérer.

response_hook
Callable

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

Retours

UserProxy instance représentant l’utilisateur upserted.

Type de retour

UserProxy

Exceptions

CosmosHttpResponseError

Si l’utilisateur donné n’a pas pu être upserted.