Compartir a través de

DatabaseProxy Clase

  • Referencia

Interfaz para interactuar con una base de datos específica.

Esta clase no se debe crear una instancia directamente. En su lugar, use el <xref:CosmosClient.get_database_client> método .

Una base de datos contiene uno o varios contenedores, cada uno de los cuales puede contener elementos, procedimientos almacenados, desencadenadores y funciones definidas por el usuario.

Una base de datos también puede tener usuarios asociados, cada uno de los cuales está configurado con un conjunto de permisos para acceder a determinados contenedores, procedimientos almacenados, desencadenadores, funciones definidas por el usuario o elementos.

Una base de datos de SQL API de Azure Cosmos DB tiene las siguientes propiedades generadas por el sistema. Estas propiedades son de solo lectura:

  • _rid: identificador de recurso.

  • _ts: cuándo se actualizó por última vez el recurso. El valor es una marca de tiempo.

  • _self: el identificador URI direccionable único para el recurso.

  • _etag: etag del recurso necesario para el control de simultaneidad optimista.

  • _colls: ruta de acceso direccionable del recurso de colecciones.

  • _users: ruta de acceso direccionable del recurso de usuarios.

Herencia
builtins.object
DatabaseProxy

Constructor

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

Parámetros

client_connection
<xref:ClientSession>
Requerido

Cliente del que se recuperó esta base de datos.

id
str
Requerido

Id. (nombre) de la base de datos.

properties
valor predeterminado: None

Variables

id

Identificador (nombre) de la base de datos.

Métodos

create_container

Cree un contenedor con el identificador (nombre) especificado.

Si ya existe un contenedor con el identificador especificado, se genera un cosmosResourceExistsError.
create_container_if_not_exists

Cree un contenedor si aún no existe.

Si el contenedor ya existe, se devuelve la configuración existente. Nota: no comprueba ni actualiza la configuración de contenedor existente ni ofrece rendimiento si difieren de lo que se pasó al método .
create_user

Cree un nuevo usuario en el contenedor.

Para actualizar o reemplazar un usuario existente, use el <xref:ContainerProxy.upsert_user> método .
delete_container

Elimina un contenedor.
delete_user

Elimine el usuario especificado del contenedor.
get_container_client

Obtenga un containerProxy para un contenedor con el identificador (nombre) especificado.
get_throughput

Obtenga el objeto ThroughputProperties para esta base de datos. Si no existe Ninguna propiedad de rendimiento para la base de datos, se genera una excepción. :keyword Callable response_hook: invocable con los metadatos de respuesta. :returns: ThroughputProperties para la base de datos. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: no existe ninguna propiedad de rendimiento para el contenedor o

no se pudieron recuperar las propiedades de rendimiento.
get_user_client

Obtiene un userProxy para un usuario con el identificador especificado.
list_containers

Enumere los contenedores de la base de datos.
list_users

Enumere todos los usuarios del contenedor.
query_containers

Enumere las propiedades de los contenedores de la base de datos actual.
query_users

Devuelve todos los usuarios que coinciden con la consulta especificada.
read

Lea las propiedades de la base de datos.
read_offer

Obtenga el objeto ThroughputProperties para esta base de datos. Si no existe Ninguna propiedad de rendimiento para la base de datos, se genera una excepción. :keyword Callable response_hook: invocable con los metadatos de respuesta. :returns: ThroughputProperties para la base de datos. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: no existe ninguna propiedad de rendimiento para el contenedor o

no se pudieron recuperar las propiedades de rendimiento.
replace_container

Restablezca las propiedades del contenedor.

Los cambios de propiedad se conservan inmediatamente. Las propiedades no especificadas se restablecerán a sus valores predeterminados.
replace_throughput

Reemplace el rendimiento de nivel de base de datos.
replace_user

Reemplaza al usuario especificado si existe en el contenedor.
upsert_user

Inserte o actualice el usuario especificado.

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

create_container

Cree un contenedor con el identificador (nombre) especificado.

Si ya existe un contenedor con el identificador especificado, se genera un cosmosResourceExistsError.

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

Parámetros

id
Requerido

Identificador (nombre) del contenedor que se va a crear.

partition_key
Requerido

Clave de partición que se va a usar para el contenedor.

indexing_policy
Requerido

Directiva de indexación que se va a aplicar al contenedor.

default_ttl
Requerido

Período de vida predeterminado (TTL) para los elementos del contenedor. Si no se especifica, los elementos no expiran.

offer_throughput
int o <xref:azure.cosmos.ThroughputProperties.>
Requerido

Rendimiento aprovisionado para esta oferta.

unique_key_policy
Requerido

Directiva de clave única que se va a aplicar al contenedor.

conflict_resolution_policy
Requerido

Directiva de resolución de conflictos que se va a aplicar al contenedor.

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 la etiqueta electrónica.

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

analytical_storage_ttl
int

Período de vida del almacén analítico (TTL) para los elementos del contenedor. Un valor de None deja el almacenamiento analítico desactivado y un valor de -1 activa el almacenamiento analítico sin TTL. Tenga en cuenta que el almacenamiento analítico solo se puede habilitar en Synapse Link cuentas habilitadas.

Devoluciones

Una instancia de ContainerProxy que representa el nuevo contenedor.

Tipo de valor devuelto

ContainerProxy

Excepciones

CosmosHttpResponseError

Error en la creación del contenedor.

Ejemplos

Cree un contenedor con la configuración predeterminada:


   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)

Crear un contenedor con una configuración específica; en este caso, una clave de partición personalizada:


   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

Cree un contenedor si aún no existe.

Si el contenedor ya existe, se devuelve la configuración existente. Nota: no comprueba ni actualiza la configuración de contenedor existente ni ofrece rendimiento si difieren de lo que se pasó al método .

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

Parámetros

id
Requerido

Identificador (nombre) del contenedor que se va a leer o crear.

partition_key
Requerido

Clave de partición que se va a usar para el contenedor.

indexing_policy
Requerido

Directiva de indexación que se va a aplicar al contenedor.

default_ttl
Requerido

Período de vida predeterminado (TTL) para los elementos del contenedor. Si no se especifica, los elementos no expiran.

populate_query_metrics
Requerido

Habilite la devolución de métricas de consulta en encabezados de respuesta.

offer_throughput
Requerido

Rendimiento aprovisionado para esta oferta.

unique_key_policy
Requerido

Directiva de clave única que se va a aplicar al contenedor.

conflict_resolution_policy
Requerido

Directiva de resolución de conflictos que se va a aplicar al contenedor.

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 la etiqueta electrónica.

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

analytical_storage_ttl
int

Período de vida del almacén analítico (TTL) para los elementos del contenedor. Un valor de None deja el almacenamiento analítico desactivado y un valor de -1 activa el almacenamiento analítico sin TTL. Tenga en cuenta que el almacenamiento analítico solo se puede habilitar en Synapse Link cuentas habilitadas.

Devoluciones

Una instancia de ContainerProxy que representa el contenedor.

Tipo de valor devuelto

ContainerProxy

Excepciones

CosmosHttpResponseError

Error en la lectura o creación del contenedor.

create_user

Cree un nuevo usuario en el contenedor.

Para actualizar o reemplazar un usuario existente, use el <xref:ContainerProxy.upsert_user> método .

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

Parámetros

body
Requerido

Objeto de tipo dict con una clave de identificador y un valor que representa al usuario que se va a crear. El identificador de usuario debe ser único dentro de la base de datos y no debe tener más de 255 caracteres.

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

Devoluciones

Una instancia de UserProxy que representa al nuevo usuario.

Tipo de valor devuelto

UserProxy

Excepciones

CosmosHttpResponseError

Si no se pudo crear el usuario especificado.

Ejemplos

Cree un usuario de base de datos:


   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

Elimina un contenedor.

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

Parámetros

container
Requerido

Identificador (nombre) del contenedor que se va a eliminar. Puede pasar el identificador del contenedor para eliminar, una <xref:azure.cosmos.database.ContainerProxy> instancia o un dict que represente las propiedades del contenedor.

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 la etiqueta electrónica.

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

Tipo de valor devuelto

None

Excepciones

CosmosHttpResponseError

Si no se pudo eliminar el contenedor.

delete_user

Elimine el usuario especificado del contenedor.

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

Parámetros

user
Requerido

Identificador (nombre), que representa las propiedades o <xref:azure.cosmos.database.UserProxy> la instancia del usuario que se va a eliminar.

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

Tipo de valor devuelto

None

Excepciones

CosmosHttpResponseError

El usuario no se eliminó correctamente.

CosmosResourceNotFoundError

El usuario no existe en el contenedor.

get_container_client

Obtenga un containerProxy para un contenedor con el identificador (nombre) especificado.

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

Parámetros

container
Requerido

Identificador (nombre) del contenedor, una <xref:azure.cosmos.database.ContainerProxy> instancia o un dict que representa las propiedades del contenedor que se van a recuperar.

Devoluciones

Una instancia de ContainerProxy que representa la base de datos recuperada.

Tipo de valor devuelto

ContainerProxy

Excepciones

CosmosHttpResponseError

Error en la creación del contenedor.

Ejemplos

Obtenga un contenedor existente y controle un error si se encuentra:


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

get_throughput

Obtenga el objeto ThroughputProperties para esta base de datos. Si no existe Ninguna propiedad de rendimiento para la base de datos, se genera una excepción. :keyword Callable response_hook: invocable con los metadatos de respuesta. :returns: ThroughputProperties para la base de datos. :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

Error en la creación del contenedor.

get_user_client

Obtiene un userProxy para un usuario con el identificador especificado.

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

Parámetros

user
Requerido

Identificador (nombre), que representa las propiedades o <xref:azure.cosmos.database.UserProxy> la instancia del usuario que se va a recuperar.

Devoluciones

Una instancia de UserProxy que representa al usuario recuperado.

Tipo de valor devuelto

UserProxy

Excepciones

CosmosHttpResponseError

Error en la creación del contenedor.

list_containers

Enumere los contenedores de la base de datos.

list_containers(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

Un invocable invocable con los metadatos de respuesta.

Devoluciones

Iterable de propiedades de contenedor (dicts).

Tipo de valor devuelto

Iterable[dict[str, Any]]

Excepciones

CosmosHttpResponseError

Error en la creación del contenedor.

Ejemplos

Enumere todos los contenedores de la base de datos:


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

list_users

Enumere todos los usuarios del contenedor.

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

Parámetros

max_item_count
Requerido

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

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

Devoluciones

Iterable de propiedades de usuario (dicts).

Tipo de valor devuelto

Iterable[dict[str, Any]]

Excepciones

CosmosHttpResponseError

Error en la creación del contenedor.

query_containers

Enumere las propiedades de los contenedores de la base de datos actual.

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

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.

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

Un invocable invocable con los metadatos de respuesta.

Devoluciones

Iterable de propiedades de contenedor (dicts).

Tipo de valor devuelto

Iterable[dict[str, Any]]

Excepciones

CosmosHttpResponseError

Error en la creación del contenedor.

query_users

Devuelve todos los usuarios que coinciden con la consulta especificada.

query_users(query: str, parameters: List[str] | 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.

max_item_count
Requerido

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

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

Devoluciones

Iterable de propiedades de usuario (dicts).

Tipo de valor devuelto

Iterable[str, Any]

Excepciones

CosmosHttpResponseError

Error en la creación del contenedor.

read

Lea las propiedades de la base de datos.

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

Parámetros

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

Un invocable invocable con los metadatos de respuesta.

Tipo de valor devuelto

Dict[<xref:Str>, Any]

Excepciones

CosmosHttpResponseError

Si no se pudo recuperar la base de datos especificada.

read_offer

Obtenga el objeto ThroughputProperties para esta base de datos. Si no existe Ninguna propiedad de rendimiento para la base de datos, se genera una excepción. :keyword Callable response_hook: invocable con los metadatos de respuesta. :returns: ThroughputProperties para la base de datos. :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) -> ThroughputProperties

Tipo de valor devuelto

ThroughputProperties

Excepciones

CosmosHttpResponseError

Error en la creación del contenedor.

replace_container

Restablezca las propiedades del contenedor.

Los cambios de propiedad se conservan inmediatamente. Las propiedades no especificadas se restablecerán a sus valores predeterminados.

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

Parámetros

container
Requerido

Identificador (nombre), dict que representa las propiedades o <xref:azure.cosmos.database.ContainerProxy> la instancia del contenedor que se va a reemplazar.

partition_key
Requerido

Clave de partición que se va a usar para el contenedor.

indexing_policy
Requerido

Directiva de indexación que se va a aplicar al contenedor.

default_ttl
Requerido

Período de vida predeterminado (TTL) para los elementos del contenedor. Si no se especifica, los elementos no expiran.

conflict_resolution_policy
Requerido

Directiva de resolución de conflictos que se va a aplicar al contenedor.

populate_query_metrics
Requerido

Habilite la devolución de métricas de consulta en encabezados de respuesta.

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 la etiqueta electrónica.

initial_headers
dict[str,str]

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

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

analytical_storage_ttl
int

Período de vida del almacén analítico (TTL) para los elementos del contenedor. Un valor de None deja el almacenamiento analítico desactivado y un valor de -1 activa el almacenamiento analítico sin TTL. Tenga en cuenta que el almacenamiento analítico solo se puede habilitar en Synapse Link cuentas habilitadas.

Devoluciones

Una instancia de ContainerProxy que representa el contenedor una vez completado el reemplazo.

Tipo de valor devuelto

ContainerProxy

Excepciones

CosmosHttpResponseError

Se genera si no se pudo reemplazar el contenedor. Esto incluye si el contenedor con el identificador especificado no existe.

Ejemplos

Restablezca la propiedad TTL en un contenedor y muestre las propiedades actualizadas:


   # 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

Reemplace el rendimiento de nivel de base de datos.

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

Parámetros

throughput
Requerido

Rendimiento que se va a establecer (un entero).

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

Devoluciones

ThroughputProperties para la base de datos, actualizada con un nuevo rendimiento.

Tipo de valor devuelto

ThroughputProperties

Excepciones

CosmosHttpResponseError

Si no existe ninguna propiedad de rendimiento para la base de datos o si no se pudieron actualizar las propiedades de rendimiento.

replace_user

Reemplaza al usuario especificado si existe en el contenedor.

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

Parámetros

user
Requerido

Identificador (nombre), dict que representa las propiedades o <xref:azure.cosmos.database.UserProxy> la instancia del usuario que se va a reemplazar.

body
Requerido

Objeto de tipo dict que representa al usuario que se va a reemplazar.

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

Devoluciones

Una instancia de UserProxy que representa al usuario después de pasar por el reemplazo.

Tipo de valor devuelto

UserProxy

Excepciones

CosmosHttpResponseError

Si no se pudo reemplazar o el usuario con el identificador especificado no existe.

upsert_user

Inserte o actualice el usuario especificado.

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

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

Parámetros

body
Requerido

Objeto de tipo dict que representa al usuario que se va a actualizar o insertar.

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

Devoluciones

Una instancia de UserProxy que representa el usuario con upserted.

Tipo de valor devuelto

UserProxy

Excepciones

CosmosHttpResponseError

Si no se pudo subir el usuario especificado.