Compartir a través de


CosmosClient Clase

Representación lógica del lado cliente de una cuenta de Azure Cosmos DB.

Use este cliente para configurar y ejecutar solicitudes en el servicio Azure Cosmos DB.

Se recomienda mantener una única instancia de CosmosClient por duración de la aplicación, lo que permite una administración y un rendimiento eficaces de la conexión.

La inicialización de CosmosClient es una operación intensiva: no use instancias de CosmosClient de inicialización como credenciales ni validaciones de conectividad de red.

Cree una instancia de un nuevo CosmosClient.

Herencia
builtins.object
CosmosClient

Constructor

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

Parámetros

url
str
Requerido

Dirección URL de la cuenta de Cosmos DB.

credential
Union[str, Dict[str, str], TokenCredential]
Requerido

Puede ser la clave de cuenta o un diccionario de tokens de recursos.

consistency_level
str
valor predeterminado: None

Nivel de coherencia que se va a usar para la sesión. El valor predeterminado es None (Nivel de cuenta). Más información sobre los niveles de coherencia y los valores posibles: https://aka.ms/cosmos-consistency-levels

timeout
int

Tiempo de espera absoluto en segundos para el procesamiento combinado de solicitudes y respuestas HTTP.

connection_timeout
int

Tiempo de espera de la solicitud HTTP en segundos.

connection_mode
str

El modo de conexión para el cliente: actualmente solo admite "Puerta de enlace".

proxy_config
ProxyConfiguration

Configuración del proxy de conexión.

ssl_config
SSLConfiguration

Configuración de SSL de conexión.

connection_verify
bool

Si se va a comprobar la conexión, el valor predeterminado es True.

connection_cert
str

Un certificado alternativo para comprobar la conexión.

retry_total
int

Número máximo de reintentos.

retry_backoff_max
int

Tiempo máximo de espera de reintento en segundos.

retry_fixed_interval
int

Se ha corregido el intervalo de reintento en milisegundos.

retry_read
int

Número máximo de reintentos de lectura de socket.

retry_connect
int

Número máximo de reintentos de error de conexión.

retry_status
int

Número máximo de reintentos en códigos de estado de error.

retry_on_status_codes
list[int]

Lista de códigos de estado específicos en los que se va a reintentar.

retry_backoff_factor
float

Factor para calcular el tiempo de espera entre los reintentos.

enable_endpoint_discovery
bool

Habilite la detección de puntos de conexión para las cuentas de base de datos con replicación geográfica. (Valor predeterminado: Verdadero)

preferred_locations
list[str]

Las ubicaciones preferidas para las cuentas de base de datos con replicación geográfica.

enable_diagnostics_logging
bool

Habilite la directiva CosmosHttpLogging. Debe usarse junto con un registrador para funcionar.

logger
Logger

Registrador que se va a usar para recopilar diagnósticos de solicitudes. Se puede pasar en el nivel de cliente (para registrar todas las solicitudes) o en un único nivel de solicitud. Las solicitudes se registrarán en el nivel info.

Ejemplos

Cree una nueva instancia del cliente de Cosmos DB:


   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

Métodos

create_database

Cree una nueva base de datos con el identificador especificado (nombre).

create_database_if_not_exists

Cree la base de datos si aún no existe.

Si la base de datos ya existe, se devuelve la configuración existente.

.. nota: Esta función no comprueba ni actualiza la configuración de la base de datos existente ni ofrece rendimiento si difieren de lo que se pasa.

delete_database

Elimine la base de datos con el identificador especificado (nombre).

from_connection_string

Cree una instancia de CosmosClient a partir de una cadena de conexión.

Esto se puede recuperar del Azure Portal. Para obtener una lista completa de los argumentos de palabra clave opcionales, consulte el constructor CosmosClient.

get_database_account

Recupere la información de la cuenta de base de datos.

get_database_client

Recupere una base de datos existente con el identificador (nombre).

list_databases

Enumere las bases de datos de una cuenta de base de datos SQL de Cosmos DB.

query_databases

Consulte las bases de datos en una cuenta de base de datos SQL de Cosmos DB.

create_database

Cree una nueva base de datos con el identificador especificado (nombre).

create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Parámetros

id
Requerido

Identificador (nombre) de la base de datos que se va a crear.

offer_throughput
Requerido

Rendimiento aprovisionado para esta oferta.

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.

Devoluciones

Una instancia de DatabaseProxy que representa la nueva base de datos.

Tipo de valor devuelto

Excepciones

La base de datos con el identificador especificado ya existe.

Ejemplos

Cree una base de datos en la cuenta de Cosmos DB:


   database_name = "testDatabase"
   try:
       database = client.create_database(id=database_name)
   except exceptions.CosmosResourceExistsError:
       database = client.get_database_client(database=database_name)

create_database_if_not_exists

Cree la base de datos si aún no existe.

Si la base de datos ya existe, se devuelve la configuración existente.

.. nota: Esta función no comprueba ni actualiza la configuración de la base de datos existente ni ofrece rendimiento si difieren de lo que se pasa.

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Parámetros

id
Requerido

Identificador (nombre) de la base de datos que se va a leer o crear.

populate_query_metrics
bool
Requerido

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

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

Rendimiento aprovisionado para esta oferta.

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.

Devoluciones

Una instancia de DatabaseProxy que representa la base de datos.

Tipo de valor devuelto

Excepciones

Error en la lectura o creación de la base de datos.

delete_database

Elimine la base de datos con el identificador especificado (nombre).

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

Parámetros

database
str o dict(str, str) o DatabaseProxy
Requerido

Identificador (nombre), dict que representa las propiedades o <xref:azure.cosmos.cosmos_client.DatabaseProxy> la instancia de la base de datos que se va a eliminar.

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

Excepciones

Si no se pudo eliminar la base de datos.

from_connection_string

Cree una instancia de CosmosClient a partir de una cadena de conexión.

Esto se puede recuperar del Azure Portal. Para obtener una lista completa de los argumentos de palabra clave opcionales, consulte el constructor CosmosClient.

from_connection_string(conn_str: str, credential: Any | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Parámetros

conn_str
str
Requerido

La cadena de conexión.

credential
str o dict(str, str)
valor predeterminado: None

Credenciales alternativas para usar en lugar de la clave proporcionada en la cadena de conexión.

consistency_level
Optional[str]
valor predeterminado: None

Nivel de coherencia que se va a usar para la sesión. El valor predeterminado es None (Nivel de cuenta).

Excepciones

La base de datos con el identificador especificado ya existe.

get_database_account

Recupere la información de la cuenta de base de datos.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parámetros

response_hook
Callable

Un invocable invocable con los metadatos de respuesta.

Devoluciones

Una instancia de DatabaseAccount que representa la cuenta de base de datos de Cosmos DB.

Tipo de valor devuelto

Excepciones

La base de datos con el identificador especificado ya existe.

get_database_client

Recupere una base de datos existente con el identificador (nombre).

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

Parámetros

database
str o dict(str, str) o DatabaseProxy
Requerido

Identificador (nombre), que representa las propiedades o la instancia databaseProxy de la base de datos que se va a leer.

Devoluciones

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

Tipo de valor devuelto

Excepciones

La base de datos con el identificador especificado ya existe.

list_databases

Enumere las bases de datos de una cuenta de base de datos SQL de Cosmos DB.

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

Parámetros

max_item_count
int
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 base de datos (dicts).

Tipo de valor devuelto

Excepciones

La base de datos con el identificador especificado ya existe.

query_databases

Consulte las bases de datos en una cuenta de base de datos SQL de Cosmos DB.

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

Parámetros

query
str
Requerido

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

parameters
List[Dict[str, Any]]
Requerido

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

enable_cross_partition_query
bool
Requerido

Permitir el examen en las consultas que no se pudieron servir como indexación se optó por no participar en las rutas de acceso solicitadas.

max_item_count
int
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.

Devoluciones

Iterable de propiedades de base de datos (dicts).

Tipo de valor devuelto

Excepciones

La base de datos con el identificador especificado ya existe.