Рекомендации по пакету SDK Python в Azure Cosmos DB для NoSQL

  • Применяется к: ✅ NoSQL

Это руководство содержит рекомендации по решениям, созданным с помощью последней версии пакета SDK Python для Azure Cosmos DB для NoSQL. Рекомендации, включенные здесь, помогают повысить задержку, повысить доступность и повысить общую производительность решений.

Конфигурация учетной записи

Параметры конфигурации учетной записи

Parameter По умолчанию или ограничение Когда использовать
Совместное размещение в регионе То же, что и регион приложения Уменьшение задержки
Мульти-региональная репликация Отключено по умолчанию Включение 2+ регионов для доступности
Переключение при отказе, управляемое службой Optional Включение для рабочих нагрузок в производственной среде 
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

Дополнительные сведения о добавлении нескольких регионов с помощью пакета SDK для Python см. в руководстве по глобальному распространению.

Использование пакета SDK

Параметры использования пакета SDK

Parameter По умолчанию или ограничение Когда использовать
Версия пакета SDK Последняя версия доступна Всегда для оптимальной производительности
Экземпляр CosmosClient Одно для каждого приложения Повторное использование на протяжении всего срока службы приложения
предпочтительные_местоположения Нет Оптимизация операций чтения и переключения при отказе 
client = CosmosClient(
    url,
    credential,
    preferred_locations=["East US", "West US"]
)
print(client.client_connection._preferred_locations)
# Expected: ['East US', 'West US']

Временная ошибка — это ошибка, причина которой быстро устраняется сама собой. При разработке приложений, которые подключаются к вашей базе данных, необходимо учитывать возможность появления этих временных ошибок и предусматривать их обработку путем реализации логики повторных попыток в коде вместо вывода пользователю сообщений об ошибках приложения. В SDK есть встроенная логика обработки таких временных ошибок в повторяемых запросах, таких как операции чтения или запроса. Пакет SDK не может повторить попытку записи при транзиторных сбоях, так как записи не являются идемпотентными. В SDK пользователи могут настраивать логику повторных попыток для регулирования. Дополнительные сведения о том, какие ошибки следует повторить, см. в руководстве по устойчивому приложению.

Используйте ведение журнала SDK для сбора диагностических сведений и устранения проблем с задержкой.

Асинхронный клиент

Требования к асинхронным клиентам

Требование По умолчанию или ограничение Когда использовать
Путь импорта azure.cosmos.aio.CosmosClient Использование в асинхронных платформах и циклах событий
aiohttp Зависимость Не установлен по умолчанию Явным образом установите: pip install aiohttp
Жизненный цикл клиента Должен быть закрыт явным образом Используйте async with или вызовите 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()

Когда следует использовать асинхронную и синхронную синхронизацию

Scenario Рекомендуемый клиент
Веб-платформы (FastAPI, Quart) azure.cosmos.aio.CosmosClient
Бессерверные Функции Azure (асинхронные) azure.cosmos.aio.CosmosClient
Скрипты и пакетные задания azure.cosmos.CosmosClient
Простые инструменты CLI azure.cosmos.CosmosClient

Предупреждение

Не используйте синхронизацию CosmosClient внутри асинхронного цикла событий. Клиент синхронизации блокирует вызовы ввода-вывода, которые блокируют цикл событий, ухудшают производительность и могут привести к взаимоблокировкам в приложении.

Дополнительные сведения см. в разделе Python SDK README async.

Проектирование данных

Параметры проектирования данных

Parameter По умолчанию или ограничение Когда использовать
Размер документа N/A Сохранение небольшого размера, чтобы сократить затраты на единицу запросов
Символы идентификатора Специальные символы отсутствуют Избегайте непредвиденного поведения
Пути индексирования Все индексированные пути Исключить неиспользуемые пути для ускорения записи 
container_properties = {
    "id": "items",
    "indexingPolicy": {
        "excludedPaths": [{"path": "/*"}]
    }
}
print(container_properties["indexingPolicy"])
# Expected: excludedPaths configured

Дополнительные сведения см. в статье о создании индексов с помощью примера пакета SDK.

Характеристики хоста

Параметры характеристик хоста

Parameter По умолчанию или ограничение Когда использовать
Использование ЦП <Рекомендуется использовать 70% Масштабируйте систему вверх или вширь при высокой нагрузке.
Ускорение сети Disabled Включить на виртуальных машинах при высоком трафике
Размер страницы запроса 100 элементов / 4 МБ Увеличение для уменьшения круговых путей 
items = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)
print("Page size set to 500")
# Expected: fewer round trips

Дальнейшие действия

Для получения дополнительных сведений о советах по производительности для пакета Python SDK, смотрите Руководство по производительности для пакета Azure Cosmos DB Python SDK.

Дополнительные сведения о разработке приложения для масштабируемости и высокой производительности см. статью Разбиение на разделы и масштабирование в Azure Cosmos DB.

Пытаетесь составить план мощностей для миграции в Azure Cosmos DB? Для планирования ресурсов можно использовать сведения об имеющемся кластере базы данных.

  • Last updated on