Заявление об отказе

Поддержка пакетов Python пакета Azure SDK для Python 2.7 завершилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Клиентская библиотека API SQL Azure Cosmos DB для Python версии 4.5.1

Azure Cosmos DB — это глобально распределенная многомодельная служба баз данных, которая поддерживает базы данных документов, пар "ключ-значение" и графов, а также базы данных с широкими столбцами.

Используйте пакет SDK API SQL Azure Cosmos DB для Python для управления базами данных и документами JSON, которые они содержат в этой службе базы данных NoSQL. Ниже приведены высокоуровневые возможности.

• Создание баз данных Cosmos DB и изменение их параметров
• Создание и изменение контейнеров для хранения коллекций документов JSON
• Создание, чтение, обновление и удаление элементов (документов JSON) в контейнерах
• Запрос документов в базе данных с помощью синтаксиса, подобного SQL

Исходный код | пакета SDKПакет (PyPI) | Пакет (Conda) | Справочная документация по | APIДокументация по продукту | Образцы

Этот пакет SDK используется для API SQL. Для всех остальных API проверка документацию по Azure Cosmos DB, чтобы оценить лучший пакет SDK для проекта.

Начало работы

Важное обновление касательно поддержки Python 2.x

Новые выпуски этого пакета SDK не будут поддерживать Python 2.x начиная с 1 января 2022 г. Дополнительные сведения см. в журнале изменений.

Предварительные требования

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись Azure Cosmos DB — API SQL
• Python 3.6+

Если вам нужна учетная запись API SQL Cosmos DB, ее можно создать с помощью следующей команды Azure CLI :

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-account-name>

Установка пакета

pip install azure-cosmos

Настройка виртуальной среды (необязательно)

Хотя это и не требуется, можно сохранять базовую систему и среды пакета SDK для Azure изолированными друг от друга при использовании виртуальной среды. Выполните следующие команды, чтобы настроить и войти в виртуальную среду с помощью venv:

python3 -m venv azure-cosmosdb-sdk-environment
source azure-cosmosdb-sdk-environment/bin/activate

Аутентификация клиента

Взаимодействие с Cosmos DB начинается с экземпляра класса CosmosClient . Для создания экземпляра объекта клиента требуется учетная запись, ее URI и один из ключей учетной записи .

Используйте приведенный ниже фрагмент Azure CLI, чтобы заполнить две переменные среды универсальным кодом ресурса (URI) учетной записи базы данных и ее первичным ключом master (эти значения также можно найти в портал Azure). Фрагмент кода отформатирован для оболочки Bash.

RES_GROUP=<resource-group-name>
ACCT_NAME=<cosmos-db-account-name>

export ACCOUNT_URI=$(az cosmosdb show --resource-group $RES_GROUP --name $ACCT_NAME --query documentEndpoint --output tsv)
export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $ACCT_NAME --query primaryMasterKey --output tsv)

Создание клиента

После заполнения ACCOUNT_URI переменных среды и ACCOUNT_KEY можно создать CosmosClient.

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

Проверка подлинности AAD

Вы также можете пройти проверку подлинности клиента, используя учетные данные AAD субъекта-службы и пакет удостоверений Azure. Вы можете напрямую передать учетные данные в ClientSecretCredential или использовать DefaultAzureCredential:

from azure.cosmos import CosmosClient
from azure.identity import ClientSecretCredential, DefaultAzureCredential

import os
url = os.environ['ACCOUNT_URI']
tenant_id = os.environ['TENANT_ID']
client_id = os.environ['CLIENT_ID']
client_secret = os.environ['CLIENT_SECRET']

# Using ClientSecretCredential
aad_credentials = ClientSecretCredential(
    tenant_id=tenant_id,
    client_id=client_id,
    client_secret=client_secret)

# Using DefaultAzureCredential (recommended)
aad_credentials = DefaultAzureCredential()

client = CosmosClient(url, aad_credentials)

Всегда убедитесь, что управляемое удостоверение, используемое для проверки подлинности AAD, имеет readMetadata разрешения.
Дополнительные сведения о настройке проверки подлинности AAD: Настройка RBAC для проверки подлинности AAD
Дополнительные сведения о разрешенных операциях для клиентов, прошедших проверку подлинности AAD: модель разрешений RBAC

Основные понятия

После инициализации CosmosClient можно работать с ресурсами основных типов в Cosmos DB:

• База данных: Учетная запись Cosmos DB может предоставлять доступ к нескольким базам данных. При создании базы данных задается API, который будет использоваться для работы с документами в ней: SQL, MongoDB, Gremlin, Cassandra или Azure Table. Используйте объект DatabaseProxy для управления контейнерами.

• Контейнер: Контейнер — это набор документов JSON. Вы создаете (вставляете), считываете, обновляете и удаляете элементы в контейнере с помощью методов объекта ContainerProxy .

• Item— это словарное представление документа JSON, хранящегося в контейнере. Каждый элемент, добавляемый в контейнер, должен содержать id ключ со значением, уникальным образом идентифицирующее элемент в контейнере.

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

Использование enable_cross_partition_query

Аргумент ключевое слово enable_cross_partition_query принимает 2 параметра: None (по умолчанию) или True.

Примечание об использовании запросов по идентификатору

При использовании запросов, которые пытаются найти элементы на основе значения идентификатора , всегда убедитесь, что вы передаете переменную строкового типа. Azure Cosmos DB допускает только значения идентификаторов строк, и если вы используете любой другой тип данных, этот пакет SDK не вернет результатов и сообщений об ошибках.

Примечание об уровнях согласованности клиента

Начиная с версии 4.3.0b3, если пользователь не передает явный уровень согласованности для инициализации клиента, клиент будет использовать уровень по умолчанию для учетной записи базы данных. Ранее по умолчанию устанавливалась Session согласованность. Если по какой-либо причине вы хотите продолжать делать это, вы можете изменить инициализацию клиента, чтобы включить явный параметр для этого, как показано ниже:

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY, consistency_level='Session')

Ограничения

В настоящее время приведенные ниже функции не поддерживаются. Варианты альтернативных вариантов проверка в разделе Обходные пути ниже.

Ограничения плоскости данных:

• Запросы группирования по
• Запросы со значением COUNT из вложенного запроса DISTINCT: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Массовая/транзакционная пакетная обработка
• Прямой доступ в режиме TCP
• Поддержка маркера продолжения для агрегированных межсекционных запросов, таких как сортировка, подсчет и разделение. Потоковые запросы, такие как SELECT * FROM WHERE, поддерживают маркеры продолжения.
• Канал изменений: обработчик
• Канал изменений: чтение значений ключей нескольких секций
• Канал изменений: время чтения
• Канал изменений: чтение с самого начала
• Канал изменений: модель извлечения
• Cross-partition ORDER BY для смешанных типов
• Включение диагностика для асинхронных методов запроса

Ограничения уровня управления:

• Получение метрик CollectionSizeUsage, DatabaseUsage и DocumentUsage
• Создание геопространственного индекса
• Получение строки подключения
• Получение минимального количества единиц запросов в секунду для контейнера

Методы обхода проблемы

Обходной путь ограничения массовой обработки

Если вы хотите использовать пакет SDK для Python для выполнения массовых операций вставки в Cosmos DB, лучше всего использовать хранимые процедуры для записи нескольких элементов с одним ключом секции.

Обходное решение ограничений уровня управления

Как правило, для неподдерживаемых ограничений уровня управления можно использовать портал Azure, REST API поставщика ресурсов Azure Cosmos DB, Azure CLI или PowerShell .

Логический тип данных

Хотя в языке Python для логических типов используются значения True и False, Cosmos DB принимает только "true" и "false". Иными словами, в языке Python используются логические значения с первой прописной буквой и всеми остальными строчными буквами, тогда как Cosmos DB и его язык SQL используют только строчные буквы для тех же логических значений. Как справиться с этой проблемой?

• Документы JSON, созданные с помощью Python, должны использовать значения True и False для прохождения проверки языка. Пакет SDK преобразует его в true и false. Это означает, что значения true и false будут храниться в Cosmos DB.
• Если вы извлекаете эти документы с помощью Data Explorer портала Cosmos DB, вы увидите true и false.
• Если вы извлекаете эти документы с помощью этого пакета SDK для Python, значения true и false автоматически преобразуются в true и false.

SQL Queries x FROM Clause Subitems

Этот пакет SDK использует метод query_items для отправки SQL-запросов в Azure Cosmos DB.

Язык SQL Cosmos DB позволяет получать подэлементы с помощью предложения FROM, чтобы уменьшить исходное подмножество. Например, можно использовать select * from Families.children вместо select * from Families. Но обратите внимание, что:

• Для SQL-запросов, использующих query_items метод , этот пакет SDK требует указать partition_key или использовать enable_cross_partition_query флаг .
• Если вы получаете подэлементы и указываете partition_key, убедитесь, что ключ секции включен в вложенные, что не так в большинстве случаев.

Максимальное количество элементов

Это параметр метода query_items, целое число, указывающее максимальное количество элементов, возвращаемых на страницу. Значение None можно указать, чтобы служба определяла оптимальное количество элементов. Это рекомендуемое значение конфигурации и поведение по умолчанию этого пакета SDK, если он не задан.

Примеры

В следующих разделах приведено несколько фрагментов кода для наиболее распространенных задач в Cosmos DB.

• Создание базы данных
• Создание контейнера
• Создание контейнера с поддержкой аналитического хранилища
• Получение существующего контейнера
• Вставка данных
• Удаление данных
• Запрос к базе данных
• Получение свойств базы данных
• Получение пропускной способности базы данных и контейнера
• Изменение свойств контейнера
• Использование асинхронного клиента

Создание базы данных

После проверки подлинности CosmosClient можно работать с любым ресурсом в учетной записи. Приведенный ниже фрагмент кода создает базу данных API SQL, которая используется по умолчанию, если при вызове create_database не указан API.

from azure.cosmos import CosmosClient, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
try:
    database = client.create_database(DATABASE_NAME)
except exceptions.CosmosResourceExistsError:
    database = client.get_database_client(DATABASE_NAME)

Создание контейнера

В этом примере создается контейнер с параметрами по умолчанию. Если контейнер с таким же именем уже существует в базе данных (что создает ошибку 409 Conflict ), вместо этого получается существующий контейнер.

from azure.cosmos import CosmosClient, PartitionKey, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'

try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

Создание контейнера с включенным аналитическим хранилищем

В этом примере создается контейнер с включенным аналитическим хранилищем для создания отчетов, бизнес-аналитики, искусственного интеллекта и расширенной аналитики с помощью Azure Synapse Link.

Варианты analytical_storage_ttl:

• 0 или NULL или не сообщается: не включено.
• -1: данные будут храниться бесконечно.
• Любое другое число: фактический ttl, в секундах.

CONTAINER_NAME = 'products'
try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1)
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

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

Получение существующего контейнера

Получите существующий контейнер из базы данных:

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

Добавление данных

Чтобы вставить элементы в контейнер, передайте словарь, содержащий данные , в ContainerProxy.upsert_item. Каждый элемент, добавляемый в контейнер, должен содержать id ключ со значением, уникальным образом определяющим элемент в контейнере.

В этом примере в контейнер вставляется несколько элементов, каждый из которых имеет уникальный id:

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for i in range(1, 10):
    container.upsert_item({
            'id': 'item{0}'.format(i),
            'productName': 'Widget',
            'productModel': 'Model {0}'.format(i)
        }
    )

Удаление данных

Чтобы удалить элементы из контейнера, используйте ContainerProxy.delete_item. API SQL в Cosmos DB не поддерживает инструкцию SQL DELETE .

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for item in container.query_items(
        query='SELECT * FROM products p WHERE p.productModel = "Model 2"',
        enable_cross_partition_query=True):
    container.delete_item(item, partition_key='Widget')

ПРИМЕЧАНИЕ. Если вы используете секционированную коллекцию, значение partitionKey в приведенном выше примере кода должно быть равно значению ключа секции для данного элемента, а не имени столбца ключа секции в коллекции. Это справедливо как для точечного чтения, так и для удаления.

Выполнение запросов к базе данных

База данных API SQL Cosmos DB поддерживает запросы элементов в контейнере с ContainerProxy.query_items с помощью синтаксиса, подобного SQL.

В этом примере контейнер запрашивает элементы с определенным id:

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

# Enumerate the returned items
import json
for item in container.query_items(
        query='SELECT * FROM mycontainer r WHERE r.id="item3"',
        enable_cross_partition_query=True):
    print(json.dumps(item, indent=True))

Примечание. Хотя в FROM предложении можно указать любое значение для имени контейнера, рекомендуется использовать имя контейнера для обеспечения согласованности.

Выполняйте параметризованные запросы, передав словарь, содержащий параметры и их значения , в ContainerProxy.query_items:

discontinued_items = container.query_items(
    query='SELECT * FROM products p WHERE p.productModel = @model',
    parameters=[
        dict(name='@model', value='Model 7')
    ],
    enable_cross_partition_query=True
)
for item in discontinued_items:
    print(json.dumps(item, indent=True))

Дополнительные сведения о запросах к базам данных Cosmos DB с помощью API SQL см. в статье SQL-запросы к базе данных Azure Cosmos DB".

Получение свойств базы данных

Получение и отображение свойств базы данных:

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
properties = database.read()
print(json.dumps(properties))

Получение пропускной способности базы данных и контейнера

Получение и отображение значений пропускной способности базы данных и контейнера с выделенной пропускной способностью:

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

# Database
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
db_offer = database.read_offer()
print('Found Offer \'{0}\' for Database \'{1}\' and its throughput is \'{2}\''.format(db_offer.properties['id'], database.id, db_offer.properties['content']['offerThroughput']))

# Container with dedicated throughput only. Will return error "offer not found" for containers without dedicated throughput
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)
container_offer = container.read_offer()
print('Found Offer \'{0}\' for Container \'{1}\' and its throughput is \'{2}\''.format(container_offer.properties['id'], container.id, container_offer.properties['content']['offerThroughput']))

Изменение свойств контейнера

Некоторые свойства существующего контейнера можно изменить. В этом примере устанавливается срок жизни по умолчанию (TTL) для элементов в контейнере равным 10 секундам:

from azure.cosmos import CosmosClient, PartitionKey
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

database.replace_container(
    container,
    partition_key=PartitionKey(path="/productName"),
    default_ttl=10,
)
# Display the new TTL setting for the container
container_props = container.read()
print(json.dumps(container_props['defaultTtl']))

Дополнительные сведения о сроке жизни см. в статье Время жизни для данных Azure Cosmos DB.

Использование асинхронного клиента

Асинхронный клиент Cosmos — это отдельный клиент, который выглядит и работает аналогично существующему синхронному клиенту. Однако асинхронный клиент необходимо импортировать отдельно, а его методы должны использоваться с ключевыми словами async/await. Асинхронный клиент должен быть инициализирован и закрыт после использования, что можно сделать вручную или с помощью диспетчера контекста. В приведенном ниже примере показано, как это сделать вручную.

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'    

async def create_products():
    client = CosmosClient(URL, credential=KEY)
    database = client.get_database_client(DATABASE_NAME)
    container = database.get_container_client(CONTAINER_NAME)
    for i in range(10):
        await container.upsert_item({
                'id': 'item{0}'.format(i),
                'productName': 'Widget',
                'productModel': 'Model {0}'.format(i)
            }
        )
    await client.close() # the async client must be closed manually if it's not initialized in a with statement

Вместо открытия и закрытия клиента вручную настоятельно рекомендуется использовать ключевые async with слова. При этом создается диспетчер контекста, который инициализирует и затем закрывает клиент после завершения инструкции. В приведенном ниже примере показано, как это сделать.

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'

async def create_products():
    async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically initialize and close the async client
        database = client.get_database_client(DATABASE_NAME)
        container = database.get_container_client(CONTAINER_NAME)
        for i in range(10):
            await container.upsert_item({
                    'id': 'item{0}'.format(i),
                    'productName': 'Widget',
                    'productModel': 'Model {0}'.format(i)
                }
            )

Запросы с асинхронным клиентом

В отличие от синхронного клиента, асинхронный клиент не имеет enable_cross_partition флага в запросе. Запросы без указанного значения ключа секции по умолчанию будут пытаться выполнить межсекционный запрос.

Результаты запроса могут быть итерированы, но необработанные выходные данные запроса возвращают асинхронный итератор. Это означает, что каждый объект из итератора является ожидаемым объектом и пока не содержит истинный результат запроса. Чтобы получить результаты запроса, можно использовать асинхронный цикл for, который ожидает каждый результат при итерации по объекту, или ожидать каждый результат запроса вручную при переборе асинхронного итератора.

Поскольку результаты запроса являются асинхронным итератором, их нельзя привести в списки напрямую; Вместо этого, если вам нужно создать списки на основе результатов, используйте асинхронный цикл или понимание списка Python для заполнения списка:

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

async def create_lists():
    results = container.query_items(
            query='SELECT * FROM products p WHERE p.productModel = "Model 2"')

    # iterates on "results" iterator to asynchronously create a complete list of the actual query results

    item_list = []
    async for item in results:
        item_list.append(item)

    # Asynchronously creates a complete list of the actual query results. This code performs the same action as the for-loop example above.
    item_list = [item async for item in results]
    await client.close()

Использование встроенного кэша

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

Преимущество этого заключается в том, что точечное чтение и запросы, которые попадают в интегрированный кэш, не будут использовать ЕЗ. Это означает, что вы будете иметь гораздо более низкие затраты на операции, чем операции чтения из серверной части.

Настройка интегрированного кэша Azure Cosmos DB (предварительная версия)

import azure.cosmos.cosmos_client as cosmos_client
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = cosmos_client.CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)

def integrated_cache_snippet():
    item_id = body['id'] 
    query = 'SELECT * FROM c'

    #item cache
    container.read_item(item=item_id, partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

    #query cache   
    container.query_items(query=query,
         partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

Дополнительные сведения о интегрированном кэше см. в статье Обзор интегрированного кэша Azure Cosmos DB.

Устранение неполадок

Общие сведения

При взаимодействии с Cosmos DB с помощью пакета SDK для Python исключения, возвращаемые службой, соответствуют тем же кодам состояния HTTP, которые возвращаются для запросов REST API:

Коды состояния HTTP для Azure Cosmos DB

Например, при попытке создать контейнер с помощью идентификатора (имени), который уже используется в базе данных Cosmos DB, 409 возвращается ошибка, указывающая на конфликт. В следующем фрагменте кода ошибка корректно обрабатывается путем перехвата исключения и отображения дополнительной информации об этой ошибке.

try:
    database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    print("""Error creating container
HTTP status code 409: The ID (name) provided for the container is already in use.
The container name must be unique within the database.""")

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.

Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и нередактированные заголовки, можно включить на клиенте с помощью аргумента logging_enable :

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

Аналогичным образом с помощью параметра logging_enable можно включить подробное журналирование для отдельной операции (даже если этот режим не включен в клиенте):

database = client.create_database(DATABASE_NAME, logging_enable=True)

Кроме того, вы можете регистрироваться с помощью CosmosHttpLoggingPolicy, который расширяется от Azure Core HttpLoggingPolicy, передав средство logger ведения журнала в аргумент . По умолчанию он будет использовать поведение из HttpLoggingPolicy. Передача аргумента enable_diagnostics_logging позволит включить CosmosHttpLoggingPolicy и получить дополнительные сведения в ответе, относящся к отладке проблем Cosmos.

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

Аналогичным образом ведение журнала можно включить для одной операции, передав средство ведения журнала в отдельный запрос. Однако если вы хотите использовать CosmosHttpLoggingPolicy для получения дополнительных сведений, enable_diagnostics_logging аргумент необходимо передать в конструктор клиента.

# This example enables the CosmosHttpLoggingPolicy and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

Телеметрия

Azure Core предоставляет нашим пакетам SDK python возможность использовать с ними OpenTelemetry. Для использования этой функции необходимо установить только следующие пакеты:

pip install azure-core-tracing-opentelemetry
pip install opentelemetry-sdk

Для получения дополнительных сведений мы рекомендуем ознакомиться с этим документом в Azure Core, где описано, как его настроить. Мы также добавили пример файла , чтобы показать, как его можно использовать с нашим пакетом SDK. Это работает одинаково независимо от используемого клиента Cosmos.

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

Более подробную документацию по службе Cosmos DB см. в документации по Azure Cosmos DB на портале docs.microsoft.com.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.