Procedimientos recomendados para Python SDK en Azure Cosmos DB para NoSQL

  • Se aplica a: ✅ NoSQL

En esta guía se incluyen los procedimientos recomendados para las soluciones creadas con la versión más reciente del SDK de Python para Azure Cosmos DB para NoSQL. Los procedimientos recomendados que se incluyen aquí ayudan a mejorar la latencia, mejorar la disponibilidad y aumentar el rendimiento general de las soluciones.

Configuración de la cuenta

Parámetros de configuración de la cuenta

Parámetro Predeterminado o restricción Cuándo usar
Coubicación de regiones Igual que la región de la aplicación Reducción de la latencia
Replicación en varias regiones Deshabilitado de manera predeterminada Habilitar 2 o más regiones para la disponibilidad
Conmutación por error administrada por el servicio Opcional Habilitar para cargas de trabajo de producción 
from azure.cosmos import CosmosClient
client = CosmosClient(url, credential)
print(client.client_connection._global_endpoint_manager.write_endpoint)
# Expected: write endpoint resolves to configured write region

Para obtener más información sobre cómo agregar varias regiones mediante el SDK de Python, consulte el tutorial de distribución global global.

Uso del SDK

Parámetros de uso del SDK

Parámetro Predeterminado o restricción Cuándo usar
Versión del SDK Más reciente disponible Siempre para obtener un rendimiento óptimo
Instancia de CosmosClient Una por aplicación Reutilización durante toda la vida útil de la aplicación
ubicaciones preferidas Ninguno Optimización de lecturas y conmutación por error 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

Un error transitorio es un error que tiene una causa subyacente que pronto se resuelve por él mismo. Las aplicaciones que se conectan a la base de datos deberían crearse de modo que contemplen esos errores transitorios. Para controlarlos, implemente una lógica de reintento en el código en lugar de mostrarlas a los usuarios como errores de aplicación. El SDK tiene lógica integrada para controlar estos errores transitorios en solicitudes que se pueden reintentar, como operaciones de lectura o consulta. El SDK no puede reintentar las escrituras para errores transitorios, ya que las escrituras no son idempotentes. El SDK permite a los usuarios configurar la lógica de reintento para las limitaciones. Para más información sobre los errores en los que se debe reintentar, consulte la guía de aplicación resiliente.

Use el registro del SDK para capturar información de diagnóstico y solucionar problemas de latencia.

Cliente asíncrono

Requisitos del cliente asincrónico

Requisito Predeterminado o restricción Cuándo usar
Ruta de importación azure.cosmos.aio.CosmosClient Uso en marcos asincrónicos y bucles de eventos
aiohttp dependencia No instalado de forma predeterminada Instalar explícitamente: pip install aiohttp
Ciclo de vida del cliente Debe cerrarse explícitamente Utilice async with o llame a await client.close() 
from azure.cosmos.aio import CosmosClient

# Preferred: use async with to manage lifecycle automatically
async with CosmosClient(url, credential) as client:
    database = client.get_database_client("mydb")
    container = database.get_container_client("mycontainer")
    item = await container.read_item(item="id1", partition_key="pk1")

# Alternative: manage lifecycle manually
client = CosmosClient(url, credential)
try:
    database = client.get_database_client("mydb")
    container = database.get_container_client("mycontainer")
    item = await container.read_item(item="id1", partition_key="pk1")
finally:
    await client.close()

Cuándo usar asincronía vs sincronización

Escenario Cliente recomendado
Marcos web (FastAPI, Quart) azure.cosmos.aio.CosmosClient
Serverless (Azure Functions async) azure.cosmos.aio.CosmosClient
Scripts y trabajos por lotes azure.cosmos.CosmosClient
Herramientas sencillas de la CLI azure.cosmos.CosmosClient

Advertencia

No use la sincronización CosmosClient dentro de un bucle de eventos asincrónico. El cliente de sincronización realiza llamadas de E/S de bloqueo que bloquean el bucle de eventos, degradan el rendimiento y pueden provocar interbloqueos en la aplicación.

Para obtener más información, consulte la sección asincrónica del README del SDK de Python.

Diseño de datos

Parámetros de diseño de datos

Parámetro Predeterminado o restricción Cuándo usar
Tamaño del documento N/A Mantenerlo pequeño para reducir los costos de recursos compartidos (RU)
Caracteres de identificador Sin caracteres especiales Evitar un comportamiento inesperado
Rutas de indexación Todas las rutas de acceso indexadas Excluir rutas sin usar para escrituras más rápidas 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

Para obtener más información, consulte Creación de índices mediante el ejemplo del SDK.

Características del host

Parámetros de características de host

Parámetro Predeterminado o restricción Cuándo usar
Uso de CPU <70% recomendado Escalado vertical o horizontal si es alto
Redes aceleradas Disabled Habilitación en máquinas virtuales para un tráfico elevado
Tamaño de página de consulta 100 elementos / 4 MB Aumento para reducir los recorridos de ida y vuelta 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

Pasos siguientes

Para obtener más información sobre las sugerencias de rendimiento para Python SDK, consulte Sugerencias de rendimiento para Azure Cosmos DB Python SDK.

Para obtener más información sobre el diseño de la aplicación para el escalado y el alto rendimiento, consulte Particionamiento y escalado en Azure Cosmos DB.

Intentar planificar la capacidad para una migración a Azure Cosmos DB? Puede utilizar información sobre su clúster de bases de datos existente para la planificación de capacidad.

  • Last updated on