DatabaseProxy Classe
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:azure.cosmos.aio.cosmos_client.CosmosClient.get_database_client> méthode pour obtenir une base de données existante ou la <xref:azure.cosmos.aio.cosmos_client.CosmosClient.create_database> méthode pour créer une base de données.
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.objectDatabaseProxy
Constructeur
DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)Paramètres
- client_connection
- <xref:azure.cosmos.aio.CosmosClientConnection>
Client à partir duquel cette base de données a été récupérée.
- properties
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 levé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 : il ne 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. |
| 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. |
| 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. Si aucune propriété de débit n’existe déjà pour la base de données, une exception est levée. |
| 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 levée.
async create_container(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyParamètres
- default_ttl
- int
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
- Union[int, ThroughputProperties]
Débit provisionné pour cette offre.
Stratégie de résolution des conflits à appliquer au conteneur.
- 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.
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 Aucun 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
Exceptions
La création du conteneur a échoué.
Exemples
Créez un conteneur avec les paramètres par défaut :
container_name = "products"
try:
container = await 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 = await 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 : il ne 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.
async create_container_if_not_exists(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyParamètres
- default_ttl
- int
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
- Union[int, ThroughputProperties]
Débit provisionné pour cette offre.
Stratégie de résolution des conflits à appliquer au conteneur.
- 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.
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 Aucun 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
Exceptions
La création du conteneur a échoué.
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 .
async create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyParamètres
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 ne doit pas comporter plus de 255 caractères.
Appelable avec les métadonnées de réponse.
Retours
Un instance UserProxy représentant le nouvel utilisateur.
Type de retour
Exceptions
Si l’utilisateur donné n’a pas pu être créé.
Exemples
Créer un utilisateur de base de données :
try:
await database.create_user(dict(id="Walter Harp"))
print("Created user 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.
async delete_container(container: str | ContainerProxy | Dict[str, Any], **kwargs: Any) -> NoneParamètres
- container
- str ou Dict[str, Any] ou ContainerProxy
ID (nom) du conteneur à supprimer. Vous pouvez transmettre l’ID du conteneur à supprimer, un ContainerProxy instance ou un dict représentant les propriétés du conteneur.
- 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.
Type de retour
Exceptions
Si le conteneur n’a pas pu être supprimé.
delete_user
Supprimez l’utilisateur spécifié du conteneur.
async delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> NoneParamètres
ID (nom), dict représentant les propriétés ou UserProxy instance de l’utilisateur à supprimer.
Type de retour
Exceptions
L’utilisateur n’a pas été supprimé avec succès.
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]) -> ContainerProxyParamètres
ID (nom), dict représentant les propriétés ou ContainerProxy instance du conteneur à obtenir.
Retours
Une instance ContainerProxy représentant le conteneur.
Type de retour
Exceptions
La création du conteneur a échoué.
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.
async get_throughput(**kwargs: Any) -> ThroughputPropertiesParamètres
Appelable avec les métadonnées de réponse.
Retours
ThroughputProperties pour la base de données.
Type de retour
Exceptions
Il n’existe aucune propriété de débit pour la base de données 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é.
get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxyParamètres
ID (nom), dict représentant les propriétés ou UserProxy instance de l’utilisateur à obtenir.
Retours
UserProxy instance représentant l’utilisateur récupéré.
Type de retour
Exceptions
La création du conteneur a échoué.
list_containers
Répertoriez les conteneurs dans la base de données.
list_containers(**kwargs) -> 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.
Appelable avec les métadonnées de réponse.
Retours
AsyncItemPaged des propriétés de conteneur (dicts).
Type de retour
Exceptions
La création du conteneur a échoué.
Exemples
Répertorier tous les conteneurs de la base de données :
database = client.get_database_client(database_name)
async for container in database.list_containers():
print("Container ID: {}".format(container['id']))
list_users
Répertorier tous les utilisateurs du conteneur.
list_users(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]Paramètres
- max_item_count
- int
Nombre maximal d’utilisateurs à retourner dans l’opération d’énumération.
Appelable avec les métadonnées de réponse.
Retours
AsyncItemPaged des propriétés utilisateur (dicts).
Type de retour
Exceptions
La création du conteneur a échoué.
query_containers
Répertorier les propriétés des conteneurs dans la base de données active.
query_containers(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]Paramètres
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.
Appelable avec les métadonnées de réponse.
Retours
AsyncItemPaged des propriétés de conteneur (dicts).
Type de retour
Exceptions
La création du conteneur a échoué.
query_users
Retourne tous les utilisateurs correspondant à la requête donnée.
query_users(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]Paramètres
Tableau facultatif de paramètres de la requête. Chaque paramètre est un dict() avec les clés « name » et « value ». Ignoré si aucune requête n’est fournie.
- max_item_count
- int
Nombre maximal d’utilisateurs à retourner dans l’opération d’énumération.
Appelable avec les métadonnées de réponse.
Retours
AsyncItemPaged des propriétés utilisateur (dicts).
Type de retour
Exceptions
La création du conteneur a échoué.
read
Lisez les propriétés de la base de données.
async read(**kwargs: Any) -> Dict[str, Any]Paramètres
- session_token
- str
Jeton à utiliser avec la cohérence de session.
Appelable avec les métadonnées de réponse.
Retours
Dict représentant les propriétés de la base de données
Type de retour
Exceptions
Si la base de données donnée n’a pas pu être récupérée.
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.
async replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyParamètres
ID (nom), dict qui représente les propriétés ou ContainerProxy instance du conteneur à remplacer.
- default_ttl
- int
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.
Stratégie de résolution des conflits à appliquer au conteneur.
- 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.
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
Exceptions
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)
await database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)
# Display the new TTL setting for the container
container_props = await 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.
Si aucune propriété de débit n’existe déjà pour la base de données, une exception est levée.
async replace_throughput(throughput: int | ThroughputProperties, **kwargs: Any) -> ThroughputPropertiesParamètres
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
Exceptions
Il n’existe aucune propriété de débit pour la base de données ou 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.
async replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxyParamètres
ID (nom), dict représentant les propriétés ou UserProxy instance de l’utilisateur à remplacer.
Appelable avec les métadonnées de réponse.
Retours
UserProxy instance représentant l’utilisateur après le remplacement.
Type de retour
Exceptions
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é.
async upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyParamètres
Objet de type dict qui représente l’utilisateur à mettre à jour ou à insérer.
Appelable avec les métadonnées de réponse.
Retours
UserProxy instance représentant l’utilisateur upserted.
Type de retour
Exceptions
Si l’utilisateur donné n’a pas pu être upserted.
Azure SDK for Python