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

DatabaseProxy

Excepciones

CosmosResourceExistsError

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

DatabaseProxy

Excepciones

CosmosHttpResponseError

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

None

Excepciones

CosmosHttpResponseError

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

CosmosResourceExistsError

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

DatabaseAccount

Excepciones

CosmosResourceExistsError

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

DatabaseProxy

Excepciones

CosmosResourceExistsError

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

Iterable[dict[str, str]]

Excepciones

CosmosResourceExistsError

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

Iterable[dict[str, str]]

Excepciones

CosmosResourceExistsError

La base de datos con el identificador especificado ya existe.