Compartilhar via

Práticas recomendadas para Python SDK no Azure Cosmos DB para NoSQL

  • Aplica-se a: ✅ NoSQL

Este guia inclui as práticas recomendadas para soluções criadas usando a versão mais recente do SDK do Python para Azure Cosmos DB para NoSQL. As práticas recomendadas incluídas aqui ajudam a melhorar a latência, melhorar a disponibilidade e aumentar o desempenho geral para suas soluções.

Configuração da conta

Parâmetros de configuração de conta

Parâmetro Padrão ou restrição Quando usar
Colocação de região O mesmo que a região do aplicativo Reduzir latência
Replicação entre regiões Desabilitado por padrão Habilitar mais 2 regiões para disponibilidade
Failover gerenciado pelo serviço Opcional Habilitar para cargas de trabalho de produção 
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 obter mais informações sobre como adicionar várias regiões usando o SDK do Python, consulte o tutorial de distribuição global.

Uso do SDK

Parâmetros de uso do SDK

Parâmetro Padrão ou restrição Quando usar
Versão do SDK Mais recente disponível Sempre para um desempenho ideal
Instância do Cosmos Client Um por aplicativo Reutilização durante todo o ciclo de vida do aplicativo
locais_preferidos None Otimizar leituras e failover 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

Um erro transitório é um erro que tem uma causa subjacente que será resolvida por si só em breve. Aplicativos que se conectam ao banco de dados devem ser criados para esperar esses erros transitórios. Para lidar com eles, implemente a lógica de repetição no código, em vez de mostrá-los aos usuários como erros de aplicativo. O SDK tem lógica interna para lidar com essas falhas transitórias em solicitações de novas tentativas, como operações de leitura ou consulta. O SDK não repetirá as gravações em caso de falhas transitórias, pois as gravações não são idempotentes. O SDK permite que os usuários configurem a lógica de repetir para limitações. Para obter detalhes sobre quais erros tentar novamente, consulte as diretrizes para aplicativos resilientes.

Use o log do SDK para capturar informações de diagnóstico e solucionar problemas de latência.

Cliente assíncrono

Requisitos do cliente assíncrono

Requisito Padrão ou restrição Quando usar
Caminho de importação azure.cosmos.aio.CosmosClient Uso em estruturas assíncronas e loops de eventos
aiohttp Dependência Não instalado por padrão Instale explicitamente: pip install aiohttp
Ciclo de vida do cliente Deve ser fechado explicitamente Usar async with ou chamar 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()

Quando usar assíncrono versus sincronização

Scenario Cliente recomendado
Estruturas da Web (FastAPI, Quart) azure.cosmos.aio.CosmosClient
Sem servidor (Azure Functions assíncrono) azure.cosmos.aio.CosmosClient
Scripts e trabalhos em lotes azure.cosmos.CosmosClient
Ferramentas simples da CLI azure.cosmos.CosmosClient

Aviso

Não use a sincronização CosmosClient dentro de um loop de evento assíncrono. O cliente de sincronização faz chamadas de E/S de bloqueio que bloqueiam o loop de eventos, degradando o desempenho e potencialmente causando deadlocks em seu aplicativo.

Para obter mais informações, consulte a seção assíncrona do SDK Python README.

Design de dados

Parâmetros de design de dados

Parâmetro Padrão ou restrição Quando usar
Tamanho do documento N/A Mantenha o tamanho reduzido para diminuir o custo da RU
Caracteres do identificador Sem chars especiais Evitar comportamento inesperado
Caminhos de indexação Todos os caminhos indexados Excluir caminhos não utilizados para gravações mais rápidas 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

Para obter mais informações, consulte a criação de índices usando o exemplo do SDK.

Características do host

Parâmetros de características do host

Parâmetro Padrão ou restrição Quando usar
Utilização da CPU <70% recomendado Aumente ou diminua a escala se for alto
Rede Acelerada Disabled Habilitar em máquinas virtuais para tráfego intenso
Tamanho da página de consulta 100 itens/4 MB Aumentar para reduzir viagens de ida e volta 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

Próximas etapas

Para saber mais sobre dicas de desempenho para o Python SDK, consulte Dicas de desempenho para Azure Cosmos DB Python SDK.

Para saber mais sobre como projetar seu aplicativo para escala e alto desempenho, consulte Partitionamento e dimensionamento no Azure Cosmos DB.

Tentando fazer o planejamento de capacidade para uma migração para Azure Cosmos DB? Você pode usar informações sobre o seu cluster de banco de dados existente para planejamento de capacidade.

  • Last updated on