ContainerProxy Classe

Référence

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

Cette classe ne doit pas être instanciée directement. Utilisez plutôt la get_container_client méthode pour obtenir un conteneur existant ou la create_container méthode pour créer un conteneur.

Un conteneur dans une base de données d’API SQL Azure Cosmos DB est une collection de documents, chacun d’eux étant représenté sous la forme d’un élément.

Héritage: builtins.object

ContainerProxy

Constructeur

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

Paramètres

client_connection

database_link

id

properties

valeur par défaut: None

Variables

id: str

ID (nom) du conteneur

session_token: str

Jeton de session pour le conteneur.

Méthodes

create_item	Créez un élément dans le conteneur. Pour mettre à jour ou remplacer un élément existant, utilisez la upsert_item méthode .
delete_all_items_by_partition_key	La fonctionnalité de suppression par clé de partition est une opération asynchrone en arrière-plan qui vous permet de supprimer tous les documents qui ont la même valeur de clé de partition logique, en utilisant le SDK Cosmos. L’opération de suppression par clé de partition est limitée pour consommer au maximum 10 % du total des RU/s disponibles chaque seconde sur le conteneur. Cela permet de limiter les ressources utilisées par cette tâche en arrière-plan.
delete_conflict	Supprimez un conflit spécifié du conteneur. Si le conflit n’existe pas déjà dans le conteneur, une exception est levée.
delete_item	Supprimez l’élément spécifié du conteneur. Si l’élément n’existe pas déjà dans le conteneur, une exception est levée.
get_conflict	Obtenez le conflit identifié par le conflit.
get_throughput	Obtenez l’objet ThroughputProperties pour ce conteneur. Si aucune propriété de débit n’existe déjà pour le conteneur, une exception est levée. :mot clé callable response_hook : callable appelé avec les métadonnées de réponse. :returns: Débit pour le conteneur. :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.
list_conflicts	Répertoriez tous les conflits dans le conteneur.
patch_item	Méthode provisoire Corrige l’élément spécifié avec les opérations fournies s’il existe dans le conteneur. Si l’élément n’existe pas déjà dans le conteneur, une exception est levée.
query_conflicts	Retourne tous les conflits correspondant à une requête donnée.
query_items	Retourne tous les résultats correspondant à la requête donnée. Vous pouvez utiliser n’importe quelle valeur pour le nom du conteneur dans la clause FROM, mais souvent le nom du conteneur est utilisé. Dans les exemples ci-dessous, le nom du conteneur est « products » et est alias « p » pour faciliter le référencement dans la clause WHERE. jeton de continuation de réponse dans la réponse de requête. Les valeurs valides sont des entiers positifs. La valeur 0 équivaut à ne pas passer de valeur (aucune limite par défaut). :mot clé int max_integrated_cache_staleness_in_ms : l’obsolescence maximale du cache pour le cache intégré dans Millisecondes. Pour les comptes configurés pour utiliser le cache intégré, à l’aide de la cohérence de session ou éventuelle, les réponses ne sont pas limitées à cette valeur.
query_items_change_feed	Obtenez une liste triée des éléments qui ont été modifiés, dans l’ordre dans lequel ils ont été modifiés.
read	Lisez les propriétés du conteneur.
read_all_items	Répertorie tous les éléments du conteneur.
read_item	Obtenez l’élément identifié par l’élément.
read_offer	Obtenez l’objet ThroughputProperties pour ce conteneur. Si aucune propriété de débit n’existe déjà pour le conteneur, une exception est levée. :mot clé callable response_hook : callable appelé avec les métadonnées de réponse. :returns: Débit pour le conteneur. :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_item	Remplace l’élément spécifié s’il existe dans le conteneur. Si l’élément n’existe pas déjà dans le conteneur, une exception est levée.
replace_throughput	Remplacez le débit du conteneur. Si aucune propriété de débit n’existe déjà pour le conteneur, une exception est levée.
upsert_item	Insérez ou mettez à jour l’élément spécifié. Si l’élément existe déjà dans le conteneur, il est remplacé. Si l’élément n’existe pas déjà, il est inséré.

create_item

Créez un élément dans le conteneur.

Pour mettre à jour ou remplacer un élément existant, utilisez la upsert_item méthode .

create_item(body: Dict[str, Any], populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, indexing_directive: Any | None = None, **kwargs: Any) -> Dict[str, Any]

Paramètres

body

Obligatoire

Objet de type dict qui représente l’élément à créer.

pre_trigger_include

Obligatoire

id de déclencheur à utiliser comme déclencheur de pré-opération.

post_trigger_include

Obligatoire

id de déclencheur à utiliser comme déclencheur de post-opération.

indexing_directive

Obligatoire

Indique si le document doit être omis de l’indexation.

enable_automatic_id_generation: bool

Activez la génération automatique d’ID si aucun ID n’est présent.

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

Dict représentant le nouvel élément.

Type de retour

dict[str, Any]

Exceptions

CosmosHttpResponseError

L’élément avec l’ID donné existe déjà.

delete_all_items_by_partition_key

La fonctionnalité de suppression par clé de partition est une opération asynchrone en arrière-plan qui vous permet de supprimer tous les documents qui ont la même valeur de clé de partition logique, en utilisant le SDK Cosmos. L’opération de suppression par clé de partition est limitée pour consommer au maximum 10 % du total des RU/s disponibles chaque seconde sur le conteneur. Cela permet de limiter les ressources utilisées par cette tâche en arrière-plan.

delete_all_items_by_partition_key(partition_key: str | int | float | bool, **kwargs: Any) -> None

Paramètres

partition_key: Any

Obligatoire

Clé de partition pour les éléments à supprimer.

pre_trigger_include: str

id de déclencheur à utiliser comme déclencheur de pré-opération.

post_trigger_include: str

id de déclencheur à utiliser comme déclencheur de post-opération.

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.

response_hook: Callable

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

Type de retour

None

Exceptions

CosmosHttpResponseError

L’élément avec l’ID donné existe déjà.

delete_conflict

Supprimez un conflit spécifié du conteneur.

Si le conflit n’existe pas déjà dans le conteneur, une exception est levée.

delete_conflict(conflict: str | Dict[str, Any], partition_key: Any, **kwargs: Any) -> None

Paramètres

conflict

Obligatoire

ID (nom) ou dict représentant le conflit à supprimer.

partition_key

Obligatoire

Clé de partition pour le conflit à supprimer.

response_hook: Callable

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

Type de retour

None

Exceptions

CosmosHttpResponseError

Le conflit n’a pas été supprimé avec succès.

CosmosResourceNotFoundError

Le conflit n’existe pas dans le conteneur.

delete_item

Supprimez l’élément spécifié du conteneur.

Si l’élément n’existe pas déjà dans le conteneur, une exception est levée.

delete_item(item: Dict[str, Any] | str, partition_key: Any, populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> None

Paramètres

item

Obligatoire

ID (nom) ou dict représentant l’élément à supprimer.

partition_key

Obligatoire

Spécifie la valeur de clé de partition pour l’élément.

pre_trigger_include

Obligatoire

id de déclencheur à utiliser comme déclencheur de pré-opération.

post_trigger_include

Obligatoire

id de déclencheur à utiliser comme déclencheur de post-opé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.

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

L’élément n’a pas été supprimé avec succès.

CosmosResourceNotFoundError

L’élément n’existe pas dans le conteneur.

get_conflict

Obtenez le conflit identifié par le conflit.

get_conflict(conflict: str | Dict[str, Any], partition_key: Any, **kwargs: Any) -> Dict[str, Any]

Paramètres

conflict

Obligatoire

ID (nom) ou dict représentant le conflit à récupérer.

partition_key

Obligatoire

Clé de partition pour le conflit à récupérer.

response_hook: Callable

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

Retours

Dict représentant le conflit récupéré.

Type de retour

dict[str, Any]

Exceptions

CosmosHttpResponseError

Impossible de récupérer le conflit donné.

get_throughput

Obtenez l’objet ThroughputProperties pour ce conteneur.

Si aucune propriété de débit n’existe déjà pour le conteneur, une exception est levée. :mot clé callable response_hook : callable appelé avec les métadonnées de réponse. :returns: Débit pour le conteneur. :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

L’élément avec l’ID donné existe déjà.

list_conflicts

Répertoriez tous les conflits dans le conteneur.

list_conflicts(max_item_count: int | 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.

response_hook: Callable

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

Retours

Itérable de conflits (dicts).

Type de retour

Iterable[dict[str, Any]]

Exceptions

CosmosHttpResponseError

L’élément avec l’ID donné existe déjà.

patch_item

Méthode provisoire Corrige l’élément spécifié avec les opérations fournies s’il existe dans le conteneur.

Si l’élément n’existe pas déjà dans le conteneur, une exception est levée.

patch_item(item: str | Dict[str, Any], partition_key: str | int | float | bool, patch_operations: List[Dict[str, Any]], **kwargs: Any) -> Dict[str, Any]

Paramètres

item: Union[str, Dict[str, Any]]

Obligatoire

ID (nom) ou dict représentant l’élément à corriger.

partition_key: Union[str, int, float, bool]

Obligatoire

Clé de partition de l’objet à corriger.

patch_operations: List[Dict[str, Any]]

Obligatoire

Liste des opérations correctives à appliquer à l’élément.

filter_predicate: str

filtre conditionnel à appliquer aux opérations de correctif.

pre_trigger_include: str

id de déclencheur à utiliser comme déclencheur de pré-opération.

post_trigger_include: str

id de déclencheur à utiliser comme déclencheur de post-opération.

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.

response_hook: Callable

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

Retours

Dict représentant l’élément après le passage des opérations correctives.

Type de retour

dict[str, Any]

Exceptions

CosmosHttpResponseError

Les opérations correctives ont échoué ou l’élément avec l’ID donné n’existe pas.

query_conflicts

Retourne tous les conflits correspondant à une requête donnée.

query_conflicts(query: str, parameters: List[str] | None = None, enable_cross_partition_query: bool | None = None, partition_key: Any | 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.

enable_cross_partition_query

Obligatoire

Autorise l’envoi de plusieurs requêtes pour exécuter la requête dans le service Azure Cosmos DB. Plusieurs requêtes sont nécessaires si la requête n’est pas limitée à une valeur de clé de partition unique.

partition_key

Obligatoire

Spécifie la valeur de clé de partition pour l’élément.

max_item_count

Obligatoire

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

response_hook: Callable

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

Retours

Itérable de conflits (dicts).

Type de retour

Iterable[dict[str, Any]]

Exceptions

CosmosHttpResponseError

L’élément avec l’ID donné existe déjà.

query_items

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

Vous pouvez utiliser n’importe quelle valeur pour le nom du conteneur dans la clause FROM, mais souvent le nom du conteneur est utilisé. Dans les exemples ci-dessous, le nom du conteneur est « products » et est alias « p » pour faciliter le référencement dans la clause WHERE.

jeton de continuation de réponse dans la réponse de requête. Les valeurs valides sont des entiers positifs. La valeur 0 équivaut à ne pas passer de valeur (aucune limite par défaut). :mot clé int max_integrated_cache_staleness_in_ms : l’obsolescence maximale du cache pour le cache intégré dans

Millisecondes. Pour les comptes configurés pour utiliser le cache intégré, à l’aide de la cohérence de session ou éventuelle, les réponses ne sont pas limitées à cette valeur.

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

Retours

Itérable d’éléments (dicts).

Type de retour

<xref:ItemPaged>[Dict[str, Any]]

Exceptions

CosmosHttpResponseError

L’élément avec l’ID donné existe déjà.

Exemples

Obtenez tous les produits qui n’ont pas été abandonnés :


   import json

   for item in container.query_items(
       query='SELECT * FROM products p WHERE p.productModel <> "DISCONTINUED"',
       enable_cross_partition_query=True,
   ):
       print(json.dumps(item, indent=True))

Requête paramétrable pour obtenir tous les produits qui ont été abandonnés :


   discontinued_items = container.query_items(
       query='SELECT * FROM products p WHERE p.productModel = @model AND p.productName="Widget"',
       parameters=[dict(name="@model", value="DISCONTINUED")],
   )
   for item in discontinued_items:
       print(json.dumps(item, indent=True))

query_items_change_feed

Obtenez une liste triée des éléments qui ont été modifiés, dans l’ordre dans lequel ils ont été modifiés.

query_items_change_feed(partition_key_range_id: str | None = None, is_start_from_beginning: bool = False, continuation: str | None = None, max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Paramètres

partition_key_range_id

Obligatoire

Les demandes ChangeFeed peuvent être exécutées sur des plages de clés de partition spécifiques. Il est utilisé pour traiter le flux de modification en parallèle sur plusieurs consommateurs.

partition_key

Obligatoire

clé de partition à laquelle les demandes ChangeFeed sont cibles.

is_start_from_beginning

Obligatoire

Déterminez si le flux de modification doit commencer à partir du début (true) ou du flux actuel (false). Par défaut, elle commence à partir de current (false).

continuation

Obligatoire

e_tag valeur à utiliser comme continuation pour la lecture du flux de modification.

max_item_count

Obligatoire

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

response_hook: Callable

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

Retours

Itérable d’éléments (dicts).

Type de retour

Iterable[dict[str, Any]]

Exceptions

CosmosHttpResponseError

L’élément avec l’ID donné existe déjà.

read

Lisez les propriétés du conteneur.

read(*, populate_partition_key_range_statistics: bool | None = None, populate_quota_info: bool | None = None, **kwargs)

Paramètres

populate_partition_key_range_statistics: bool

Activez le retour des statistiques de plage de clés de partition dans les en-têtes de réponse.

populate_quota_info: bool

Activez le retour des informations de quota de stockage de collecte dans les en-têtes de réponse.

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

Dict représentant le conteneur récupéré.

Type de retour

dict[str, Any]

Exceptions

CosmosHttpResponseError

Déclenché si le conteneur n’a pas pu être récupéré. Cela inclut si le conteneur n’existe pas.

read_all_items

Répertorie tous les éléments du conteneur.

read_all_items(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.

max_integrated_cache_staleness_in_ms: int

L’obsolescence maximale du cache pour le cache intégré en millisecondes. Pour les comptes configurés pour utiliser le cache intégré, à l’aide de la cohérence de session ou éventuelle, les réponses ne sont pas limitées à cette valeur.

Retours

Itérable d’éléments (dicts).

Type de retour

Iterable[dict[str, Any]]

Exceptions

CosmosHttpResponseError

L’élément avec l’ID donné existe déjà.

read_item

Obtenez l’élément identifié par l’élément.

read_item(item: str | Dict[str, Any], partition_key: Any, populate_query_metrics: bool | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> Dict[str, Any]

Paramètres

item

Obligatoire

ID (nom) ou dict représentant l’élément à récupérer.

partition_key

Obligatoire

Clé de partition pour l’élément à récupérer.

post_trigger_include

Obligatoire

id de déclencheur à utiliser comme déclencheur de post-opé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.

max_integrated_cache_staleness_in_ms: int

Retours

Dict représentant l’élément à récupérer.

Type de retour

dict[str, Any]

Exceptions

CosmosHttpResponseError

Impossible de récupérer l’élément donné.

Exemples

Obtenez un élément de la base de données et mettez à jour l’une de ses propriétés :


   item = container.read_item("item2", partition_key="Widget")
   item["productModel"] = "DISCONTINUED"
   updated_item = container.upsert_item(item)

read_offer

Obtenez l’objet ThroughputProperties pour ce conteneur. Si aucune propriété de débit n’existe déjà pour le conteneur, une exception est levée. :mot clé callable response_hook : callable appelé avec les métadonnées de réponse. :returns: Débit pour le conteneur. :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) -> Offer

Type de retour

ThroughputProperties

Exceptions

CosmosHttpResponseError

L’élément avec l’ID donné existe déjà.

replace_item

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

Si l’élément n’existe pas déjà dans le conteneur, une exception est levée.

replace_item(item: str | Dict[str, Any], body: Dict[str, Any], populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> Dict[str, Any]

Paramètres

item

Obligatoire

ID (nom) ou dict représentant l’élément à remplacer.

body

Obligatoire

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

pre_trigger_include

Obligatoire

id de déclencheur à utiliser comme déclencheur de pré-opération.

post_trigger_include

Obligatoire

id de déclencheur à utiliser comme déclencheur de post-opé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.

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

Dict représentant l’élément après remplacement.

Type de retour

dict[str, Any]

Exceptions

CosmosHttpResponseError

Le remplacement a échoué ou l’élément avec un ID donné n’existe pas.

replace_throughput

Remplacez le débit du conteneur.

Si aucune propriété de débit n’existe déjà pour le conteneur, une exception est levée.

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 le conteneur, mise à jour avec un nouveau débit.

Type de retour

ThroughputProperties

Exceptions

CosmosHttpResponseError

Il n’existe aucune propriété de débit pour le conteneur ou les propriétés de débit n’ont pas pu être mises à jour.

upsert_item

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

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

upsert_item(body: Dict[str, Any], populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> Dict[str, Any]

Paramètres

body

Obligatoire

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

pre_trigger_include

Obligatoire

id de déclencheur à utiliser comme déclencheur de pré-opération.

post_trigger_include

Obligatoire

id de déclencheur à utiliser comme déclencheur de post-opé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.

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

Dict représentant l’élément upserted.

Type de retour

dict[str, Any]

Exceptions

CosmosHttpResponseError

L’élément donné n’a pas pu être upserted.