ContainerProxy Clase

Interfaz para interactuar con un contenedor de base de datos específico.

Esta clase no se debe crear una instancia directamente. En su lugar, use el get_container_client método para obtener un contenedor existente o el create_container método para crear un nuevo contenedor.

Un contenedor de una base de datos de SQL API de Azure Cosmos DB es una colección de documentos, cada uno de los cuales se representa como un elemento.

Herencia

builtins.object

ContainerProxy

Constructor

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

Parámetros

client_connection

database_link

id

properties

valor predeterminado: None

Variables

id

str

Identificador (nombre) del contenedor

session_token

str

Token de sesión del contenedor.

Métodos

create_item	Cree un elemento en el contenedor. Para actualizar o reemplazar un elemento existente, use el upsert_item método .
delete_all_items_by_partition_key	La característica de eliminación por clave de partición es una operación asincrónica y en segundo plano que permite eliminar todos los documentos con el mismo valor de clave de partición lógica, mediante el SDK de Cosmos. La operación de eliminación por clave de partición se limita a un consumo máximo del 10 % del total de RU/s disponibles en el contenedor cada segundo. Esto ayuda a limitar los recursos utilizados por esta tarea en segundo plano.
delete_conflict	Elimine un conflicto especificado del contenedor. Si el conflicto aún no existe en el contenedor, se genera una excepción.
delete_item	Elimine el elemento especificado del contenedor. Si el elemento aún no existe en el contenedor, se genera una excepción.
get_conflict	Obtenga el conflicto identificado por conflicto.
get_throughput	Obtenga el objeto ThroughputProperties para este contenedor. Si no existen propiedades de rendimiento para el contenedor, se genera una excepción. :keyword Response_hook invocable: invocable con los metadatos de respuesta. :returns: rendimiento del contenedor. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: no existe ninguna propiedad de rendimiento para el contenedor o no se pudieron recuperar las propiedades de rendimiento.
list_conflicts	Enumere todos los conflictos del contenedor.
patch_item	Método provisional Aplica revisiones al elemento especificado con las operaciones proporcionadas si existe en el contenedor. Si el elemento aún no existe en el contenedor, se genera una excepción.
query_conflicts	Devuelve todos los conflictos que coinciden con una consulta determinada.
query_items	Devuelve todos los resultados que coinciden con la consulta especificada. Puede usar cualquier valor para el nombre del contenedor en la cláusula FROM, pero a menudo se usa el nombre del contenedor. En los ejemplos siguientes, el nombre del contenedor es "products" y tiene el alias "p" para facilitar la referencia en la cláusula WHERE. token de continuación de respuesta en la respuesta de consulta. Los valores válidos son enteros positivos. Un valor de 0 es el mismo que no pasar un valor (valor predeterminado sin límite). :keyword int max_integrated_cache_staleness_in_ms: obsolescencia máxima de caché para la caché integrada en Milisegundos. Para las cuentas configuradas para usar la memoria caché integrada, mediante la coherencia De sesión o Eventual, se garantiza que las respuestas no sean obsoletas que este valor.
query_items_change_feed	Obtiene una lista ordenada de elementos que se cambiaron, en el orden en que se modificaron.
read	Lea las propiedades del contenedor.
read_all_items	Enumere todos los elementos del contenedor.
read_item	Obtenga el elemento identificado por elemento.
read_offer	Obtenga el objeto ThroughputProperties para este contenedor. Si no existen propiedades de rendimiento para el contenedor, se genera una excepción. :keyword Response_hook invocable: invocable con los metadatos de respuesta. :returns: rendimiento del contenedor. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: no existe ninguna propiedad de rendimiento para el contenedor o no se pudieron recuperar las propiedades de rendimiento.
replace_item	Reemplaza el elemento especificado si existe en el contenedor. Si el elemento aún no existe en el contenedor, se genera una excepción.
replace_throughput	Reemplace el rendimiento del contenedor. Si no existen propiedades de rendimiento para el contenedor, se genera una excepción.
upsert_item	Inserte o actualice el elemento especificado. Si el elemento ya existe en el contenedor, se reemplaza. Si el elemento aún no existe, se inserta.

create_item

Cree un elemento en el contenedor.

Para actualizar o reemplazar un elemento existente, use el upsert_item método .

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]

Parámetros

body

Requerido

Objeto de tipo dict que representa el elemento que se va a crear.

pre_trigger_include

Requerido

id. de desencadenador que se va a usar como desencadenador de operación previa.

post_trigger_include

Requerido

trigger id que se va a usar como desencadenador posterior a la operación.

indexing_directive

Requerido

Indique si se debe omitir el documento de la indexación.

enable_automatic_id_generation

bool

Habilite la generación automática de identificadores si no hay ningún identificador presente.

session_token

str

Token para su uso con coherencia de sesión.

initial_headers

dict[str,str]

Encabezados iniciales que se enviarán como parte de la solicitud.

etag

str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition

MatchConditions

Condición de coincidencia que se va a usar en el etag.

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

Un dict que representa el nuevo elemento.

Tipo de valor devuelto

dict[str, Any]

Excepciones

CosmosHttpResponseError

El elemento con el identificador especificado ya existe.

delete_all_items_by_partition_key

La característica de eliminación por clave de partición es una operación asincrónica y en segundo plano que permite eliminar todos los documentos con el mismo valor de clave de partición lógica, mediante el SDK de Cosmos. La operación de eliminación por clave de partición se limita a un consumo máximo del 10 % del total de RU/s disponibles en el contenedor cada segundo. Esto ayuda a limitar los recursos utilizados por esta tarea en segundo plano.

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

Parámetros

partition_key

Any

Requerido

Clave de partición para los elementos que se van a eliminar.

pre_trigger_include

str

id. de desencadenador que se va a usar como desencadenador de operación previa.

post_trigger_include

str

trigger id que se va a usar como desencadenador posterior a la operación.

session_token

str

Token para su uso con coherencia de sesión.

etag

str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition

MatchConditions

Condición de coincidencia que se va a usar en el etag.

response_hook

Callable

Invocable con los metadatos de respuesta.

Tipo de valor devuelto

None

Excepciones

CosmosHttpResponseError

El elemento con el identificador especificado ya existe.

delete_conflict

Elimine un conflicto especificado del contenedor.

Si el conflicto aún no existe en el contenedor, se genera una excepción.

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

Parámetros

conflict

Requerido

Identificador (nombre) o dict que representa el conflicto que se va a eliminar.

partition_key

Requerido

Clave de partición del conflicto que se va a eliminar.

response_hook

Callable

Invocable con los metadatos de respuesta.

Tipo de valor devuelto

None

Excepciones

CosmosHttpResponseError

El conflicto no se eliminó correctamente.

CosmosResourceNotFoundError

El conflicto no existe en el contenedor.

delete_item

Elimine el elemento especificado del contenedor.

Si el elemento aún no existe en el contenedor, se genera una excepción.

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

Parámetros

item

Requerido

Identificador (nombre) o dict que representa el elemento que se va a eliminar.

partition_key

Requerido

Especifica el valor de clave de partición para el elemento.

pre_trigger_include

Requerido

id. de desencadenador que se va a usar como desencadenador de operación previa.

post_trigger_include

Requerido

trigger id que se va a usar como desencadenador posterior a la operación.

session_token

str

Token para su uso con coherencia de sesión.

initial_headers

dict[str,str]

Encabezados iniciales que se enviarán como parte de la solicitud.

etag

str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition

MatchConditions

Condición de coincidencia que se va a usar en el etag.

response_hook

Callable

Invocable con los metadatos de respuesta.

Tipo de valor devuelto

None

Excepciones

CosmosHttpResponseError

El elemento no se eliminó correctamente.

CosmosResourceNotFoundError

El elemento no existe en el contenedor.

get_conflict

Obtenga el conflicto identificado por conflicto.

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

Parámetros

conflict

Requerido

Identificador (nombre) o dict que representa el conflicto que se va a recuperar.

partition_key

Requerido

Clave de partición del conflicto que se va a recuperar.

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

Un dict que representa el conflicto recuperado.

Tipo de valor devuelto

dict[str, Any]

Excepciones

CosmosHttpResponseError

No se pudo recuperar el conflicto especificado.

get_throughput

Obtenga el objeto ThroughputProperties para este contenedor.

Si no existen propiedades de rendimiento para el contenedor, se genera una excepción. :keyword Response_hook invocable: invocable con los metadatos de respuesta. :returns: rendimiento del contenedor. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: no existe ninguna propiedad de rendimiento para el contenedor o

no se pudieron recuperar las propiedades de rendimiento.

get_throughput(**kwargs: Any) -> ThroughputProperties

Tipo de valor devuelto

ThroughputProperties

Excepciones

CosmosHttpResponseError

El elemento con el identificador especificado ya existe.

list_conflicts

Enumere todos los conflictos del contenedor.

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

Parámetros

max_item_count

Requerido

Número máximo de elementos que se van a devolver en la operación de enumeración.

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

Iterable de conflictos (dicts).

Tipo de valor devuelto

Iterable[dict[str, Any]]

Excepciones

CosmosHttpResponseError

El elemento con el identificador especificado ya existe.

patch_item

Método provisional Aplica revisiones al elemento especificado con las operaciones proporcionadas si existe en el contenedor.

Si el elemento aún no existe en el contenedor, se genera una excepción.

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

Parámetros

item

Union[str, Dict[str, Any]]

Requerido

Identificador (nombre) o dict que representa el elemento que se va a aplicar revisiones.

partition_key

Union[str, int, float, bool]

Requerido

Clave de partición del objeto que se va a aplicar a la revisión.

patch_operations

List[Dict[str, Any]]

Requerido

Lista de operaciones de revisión que se van a aplicar al elemento.

filter_predicate

str

filtro condicional que se va a aplicar a las operaciones de revisión.

pre_trigger_include

str

id. de desencadenador que se va a usar como desencadenador de operación previa.

post_trigger_include

str

trigger id que se va a usar como desencadenador posterior a la operación.

session_token

str

Token para su uso con coherencia de sesión.

etag

str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition

MatchConditions

Condición de coincidencia que se va a usar en el etag.

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

Un dict que representa el elemento después de que se han pasado las operaciones de revisión.

Tipo de valor devuelto

dict[str, Any]

Excepciones

CosmosHttpResponseError

Error en las operaciones de revisión o el elemento con el identificador especificado no existe.

query_conflicts

Devuelve todos los conflictos que coinciden con una consulta determinada.

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]]

Parámetros

query

Requerido

Consulta SQL de Azure Cosmos DB que se va a ejecutar.

parameters

Requerido

Matriz opcional de parámetros para la consulta. Se omite si no se proporciona ninguna consulta.

enable_cross_partition_query

Requerido

Permite el envío de más de una solicitud para ejecutar la consulta en el servicio Azure Cosmos DB. Se necesita más de una solicitud si la consulta no tiene como ámbito el valor de clave de partición única.

partition_key

Requerido

Especifica el valor de clave de partición para el elemento.

max_item_count

Requerido

Número máximo de elementos que se van a devolver en la operación de enumeración.

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

Iterable de conflictos (dicts).

Tipo de valor devuelto

Iterable[dict[str, Any]]

Excepciones

CosmosHttpResponseError

El elemento con el identificador especificado ya existe.

query_items

Devuelve todos los resultados que coinciden con la consulta especificada.

Puede usar cualquier valor para el nombre del contenedor en la cláusula FROM, pero a menudo se usa el nombre del contenedor. En los ejemplos siguientes, el nombre del contenedor es "products" y tiene el alias "p" para facilitar la referencia en la cláusula WHERE.

token de continuación de respuesta en la respuesta de consulta. Los valores válidos son enteros positivos. Un valor de 0 es el mismo que no pasar un valor (valor predeterminado sin límite). :keyword int max_integrated_cache_staleness_in_ms: obsolescencia máxima de caché para la caché integrada en

Milisegundos. Para las cuentas configuradas para usar la memoria caché integrada, mediante la coherencia De sesión o Eventual, se garantiza que las respuestas no sean obsoletas que este valor.

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]]

Devoluciones

Iterable de elementos (dicts).

Tipo de valor devuelto

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

Excepciones

CosmosHttpResponseError

El elemento con el identificador especificado ya existe.

Ejemplos

Obtenga todos los productos que no se han dejado de usar:

   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))

Consulta con parámetros para obtener todos los productos que se han interrumpido:

   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

Obtiene una lista ordenada de elementos que se cambiaron, en el orden en que se modificaron.

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]]

Parámetros

partition_key_range_id

Requerido

Las solicitudes ChangeFeed se pueden ejecutar en intervalos de claves de partición específicos. Se usa para procesar la fuente de cambios en paralelo en varios consumidores.

partition_key

Requerido

clave de partición en la que se destinan las solicitudes ChangeFeed.

is_start_from_beginning

Requerido

Obtenga si la fuente de cambios debe comenzar desde el principio (true) o desde el actual (false). De forma predeterminada, comienza desde el actual (false).

continuation

Requerido

e_tag valor que se usará como continuación para leer la fuente de cambios.

max_item_count

Requerido

Número máximo de elementos que se van a devolver en la operación de enumeración.

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

Iterable de elementos (dicts).

Tipo de valor devuelto

Iterable[dict[str, Any]]

Excepciones

CosmosHttpResponseError

El elemento con el identificador especificado ya existe.

read

Lea las propiedades del contenedor.

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

Parámetros

populate_partition_key_range_statistics

bool

Habilite la devolución de estadísticas de intervalo de claves de partición en los encabezados de respuesta.

populate_quota_info

bool

Habilite la devolución de información de cuota de almacenamiento de recopilación en los encabezados de respuesta.

session_token

str

Token para su uso con coherencia de sesión.

initial_headers

dict[str,str]

Encabezados iniciales que se enviarán como parte de la solicitud.

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

Dict que representa el contenedor recuperado.

Tipo de valor devuelto

dict[str, Any]

Excepciones

CosmosHttpResponseError

Se genera si no se pudo recuperar el contenedor. Esto incluye si el contenedor no existe.

read_all_items

Enumere todos los elementos del contenedor.

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

Parámetros

max_item_count

Requerido

Número máximo de elementos que se van a devolver en la operación de enumeración.

session_token

str

Token para su uso con coherencia de sesión.

initial_headers

dict[str,str]

Encabezados iniciales que se enviarán como parte de la solicitud.

response_hook

Callable

Invocable con los metadatos de respuesta.

max_integrated_cache_staleness_in_ms

int

Obsolescencia máxima de caché para la caché integrada en milisegundos. Para las cuentas configuradas para usar la memoria caché integrada, mediante la coherencia De sesión o Eventual, se garantiza que las respuestas no sean obsoletas que este valor.

Devoluciones

Iterable de elementos (dicts).

Tipo de valor devuelto

Iterable[dict[str, Any]]

Excepciones

CosmosHttpResponseError

El elemento con el identificador especificado ya existe.

read_item

Obtenga el elemento identificado por elemento.

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]

Parámetros

item

Requerido

Identificador (nombre) o dict que representa el elemento que se va a recuperar.

partition_key

Requerido

Clave de partición del elemento que se va a recuperar.

post_trigger_include

Requerido

trigger id que se va a usar como desencadenador posterior a la operación.

session_token

str

Token para su uso con coherencia de sesión.

initial_headers

dict[str,str]

Encabezados iniciales que se enviarán como parte de la solicitud.

response_hook

Callable

Invocable con los metadatos de respuesta.

max_integrated_cache_staleness_in_ms

int

Obsolescencia máxima de caché para la caché integrada en milisegundos. Para las cuentas configuradas para usar la memoria caché integrada, mediante la coherencia De sesión o Eventual, se garantiza que las respuestas no sean obsoletas que este valor.

Devoluciones

Dict que representa el elemento que se va a recuperar.

Tipo de valor devuelto

dict[str, Any]

Excepciones

CosmosHttpResponseError

No se pudo recuperar el elemento especificado.

Ejemplos

Obtenga un elemento de la base de datos y actualice una de sus propiedades:

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

read_offer

Obtenga el objeto ThroughputProperties para este contenedor. Si no existen propiedades de rendimiento para el contenedor, se genera una excepción. :keyword Response_hook invocable: invocable con los metadatos de respuesta. :returns: rendimiento del contenedor. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: no existe ninguna propiedad de rendimiento para el contenedor o

no se pudieron recuperar las propiedades de rendimiento.

read_offer(**kwargs: Any) -> Offer

Tipo de valor devuelto

ThroughputProperties

Excepciones

CosmosHttpResponseError

El elemento con el identificador especificado ya existe.

replace_item

Reemplaza el elemento especificado si existe en el contenedor.

Si el elemento aún no existe en el contenedor, se genera una excepción.

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]

Parámetros

item

Requerido

Identificador (nombre) o dict que representa el elemento que se va a reemplazar.

body

Requerido

Objeto de tipo dict que representa el elemento que se va a reemplazar.

pre_trigger_include

Requerido

id. de desencadenador que se va a usar como desencadenador de operación previa.

post_trigger_include

Requerido

trigger id que se va a usar como desencadenador posterior a la operación.

session_token

str

Token para su uso con coherencia de sesión.

initial_headers

dict[str,str]

Encabezados iniciales que se enviarán como parte de la solicitud.

etag

str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition

MatchConditions

Condición de coincidencia que se va a usar en el etag.

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

Un dict que representa el elemento después de reemplazar pasó.

Tipo de valor devuelto

dict[str, Any]

Excepciones

CosmosHttpResponseError

Error en el reemplazo o el elemento con el identificador especificado no existe.

replace_throughput

Reemplace el rendimiento del contenedor.

Si no existen propiedades de rendimiento para el contenedor, se genera una excepción.

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

Parámetros

throughput

Requerido

Rendimiento que se va a establecer (un entero).

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

RendimientoPropiedades para el contenedor, actualizadas con un nuevo rendimiento.

Tipo de valor devuelto

ThroughputProperties

Excepciones

CosmosHttpResponseError

No se pudieron actualizar las propiedades de rendimiento para el contenedor o no se pudieron actualizar las propiedades de rendimiento.

upsert_item

Inserte o actualice el elemento especificado.

Si el elemento ya existe en el contenedor, se reemplaza. Si el elemento aún no existe, se inserta.

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]

Parámetros

body

Requerido

Objeto de tipo dict que representa el elemento que se va a actualizar o insertar.

pre_trigger_include

Requerido

id. de desencadenador que se va a usar como desencadenador de operación previa.

post_trigger_include

Requerido

trigger id que se va a usar como desencadenador posterior a la operación.

session_token

str

Token para su uso con coherencia de sesión.

initial_headers

dict[str,str]

Encabezados iniciales que se enviarán como parte de la solicitud.

etag

str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition

MatchConditions

Condición de coincidencia que se va a usar en el etag.

response_hook

Callable

Invocable con los metadatos de respuesta.

Devoluciones

Un dict que representa el elemento upserted.

Tipo de valor devuelto

dict[str, Any]

Excepciones

CosmosHttpResponseError

No se pudo subir el elemento especificado.

Atributos

is_system_key

scripts