Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações e tirar dúvidas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Biblioteca de clientes da API sql do Azure Cosmos DB para Python – versão 4.5.1

O Azure Cosmos DB é um serviço de banco de dados multimodelo globalmente distribuído que dá suporte a bancos de dados de documentos, valor-chave, coluna larga e grafo.

Use o SDK da API sql do Azure Cosmos DB para Python para gerenciar bancos de dados e os documentos JSON que eles contêm neste serviço de banco de dados NoSQL. Os recursos de alto nível são:

• Criar bancos de dados do Cosmos DB e modificar suas configurações
• Criar e modificar contêineres para armazenar coleções de documentos JSON
• Criar, ler, atualizar e excluir os itens (documentos JSON) em seus contêineres
• Consultar os documentos em seu banco de dados usando a sintaxe semelhante a SQL

Código-fonte | do SDKPacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIDocumentação do produto | Amostras

Esse SDK é usado para a API do SQL. Para todas as outras APIs, marcar a documentação do Azure Cosmos DB para avaliar o melhor SDK para seu projeto.

Introdução

Atualização importante no suporte ao Python 2.x

Novas versões desse SDK não darão suporte ao Python 2.x a partir de 1º de janeiro de 2022. Verifique o LOG DE MUDANÇAS para obter mais informações.

Pré-requisitos

• Assinatura do Azure – Criar uma conta gratuita
• Conta do Azure Cosmos DB – API do SQL
• Python 3.6 e superior

Se você precisar de uma conta da API do SQL do Cosmos DB, poderá criar uma com este comando da CLI do Azure :

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

Instalar o pacote

pip install azure-cosmos

Configurar um ambiente virtual (opcional)

Embora não seja necessário, você poderá manter o sistema base e os ambientes do SDK do Azure isolados uns dos outros se você usar um ambiente virtual. Execute os seguintes comandos para configurar e, em seguida, insira um ambiente virtual com venv:

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

Autenticar o cliente

A interação com o Cosmos DB começa com uma instância da classe CosmosClient . Você precisa de uma conta, seu URI e uma de suas chaves de conta para instanciar o objeto cliente.

Use o snippet da CLI do Azure abaixo para preencher duas variáveis de ambiente com o URI da conta de banco de dados e sua chave de master primária (você também pode encontrar esses valores no portal do Azure). O snippet é formatado para o shell do 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)

Crie o cliente

Depois de preencher as ACCOUNT_URI variáveis de ambiente e ACCOUNT_KEY , você pode criar o CosmosClient.

from azure.cosmos import CosmosClient

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

Autenticação do AAD

Você também pode autenticar um cliente utilizando as credenciais do AAD da entidade de serviço e o pacote de identidade do azure. Você pode transmitir diretamente as informações de credenciais para ClientSecretCredential ou usar 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)

Sempre verifique se a identidade gerenciada que você usa para autenticação do AAD tem readMetadata permissões.
Mais informações sobre como configurar a autenticação do AAD: configurar o RBAC para autenticação do AAD
Mais informações sobre operações permitidas para clientes autenticados do AAD: modelo de permissão RBAC

Principais conceitos

Depois de inicializar um CosmosClient, você pode interagir com os tipos de recursos primários no Cosmos DB:

• Banco de dados: Uma conta do Cosmos DB pode conter vários bancos de dados. Ao criar um banco de dados, você especifica a API que quer usar para interagir com os respectivos documentos: SQL, MongoDB, Gremlin, Cassandra ou Tabelas do Azure. Use o objeto DatabaseProxy para gerenciar seus contêineres.

• Contêiner: Um contêiner é uma coleção de documentos JSON. Você cria (inserir), lê, atualiza e exclui itens em um contêiner usando métodos no objeto ContainerProxy .

• Item: Um Item é a representação semelhante ao dicionário de um documento JSON armazenado em um contêiner. Cada Item adicionado a um contêiner deve incluir uma id chave com um valor que identifique exclusivamente o item dentro do contêiner.

Para obter mais informações sobre esses recursos, confira Trabalhar com bancos de dados, contêineres e itens do Azure Cosmos.

Como usar enable_cross_partition_query

O argumento enable_cross_partition_query palavra-chave aceita duas opções: None (padrão) ou True.

Observação sobre como usar consultas por id

Ao usar consultas que tentam localizar itens com base em um valor de ID , sempre verifique se você está passando uma variável de tipo de cadeia de caracteres. O Azure Cosmos DB permite apenas valores de ID de cadeia de caracteres e, se você usar qualquer outro tipo de dados, esse SDK não retornará resultados nem mensagens de erro.

Observação sobre os níveis de consistência do cliente

A partir da versão 4.3.0b3, se um usuário não passar um nível de consistência explícito para a inicialização do cliente, o cliente usará o nível padrão da conta de banco de dados. Anteriormente, o padrão estava sendo definido como Session consistência. Se, por algum motivo, você quiser continuar fazendo isso, poderá alterar a inicialização do cliente para incluir o parâmetro explícito para isso, como mostrado:

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')

Limitações

Atualmente, não há suporte para os recursos abaixo. Para opções alternativas, marcar a seção Soluções alternativas abaixo.

Limitações do plano de dados:

• Agrupar por consultas
• Consultas com COUNT de uma subconsulta DISTINCT: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Processamento em lote em massa/transacional
• Acesso direto ao modo TCP
• Suporte de token de continuação para consultas de partição cruzada agregadas, como classificação, contagem e distintas. Consultas que podem ser transmitidas como SELECT * FROM WHEREdão suporte a tokens de continuação.
• Feed de Alterações: Processador
• Feed de Alterações: ler valores de chave de várias partições
• Feed de Alterações: tempo específico de leitura
• Feed de Alterações: leitura desde o início
• Feed de Alterações: Modelo de pull
• ORDER BY entre partições para tipos mistos
• Habilitando diagnóstico para métodos de tipo de consulta assíncrona

Limitações do plano de controle:

• Obter métricas CollectionSizeUsage, DatabaseUsage e DocumentUsage
• Criar índice geoespacial
• Obtenha a cadeia de conexão
• Obter as RU/s mínimas de um contêiner

Soluções Alternativas

Solução alternativa de limitação de processamento em massa

Se você quiser usar o SDK do Python para executar inserções em massa no Cosmos DB, a melhor alternativa é usar procedimentos armazenados para gravar vários itens com a mesma chave de partição.

Solução alternativa de limitações do painel de controle

Normalmente, você pode usar o Portal do Azure, a API REST do Provedor de Recursos do Azure Cosmos DB, a CLI do Azure ou o PowerShell para as limitações sem suporte do painel de controle.

Tipo de dados booliano

Embora a linguagem Python use "True" e "False" para tipos boolianos, o Cosmos DB aceita apenas "true" e "false". Em outras palavras, a linguagem Python usa valores boolianos com a primeira letra maiúscula e todas as outras letras minúsculas, enquanto o Cosmos DB e sua linguagem SQL usam apenas letras minúsculas para esses mesmos valores boolianos. Como lidar com esse desafio?

• Seus documentos JSON criados com Python devem usar "True" e "False" para passar na validação do idioma. O SDK o converterá em "true" e "false" para você. Significa que "true" e "false" é o que será armazenado no Cosmos DB.
• Se você recuperar esses documentos com a Data Explorer do Portal do Cosmos DB, verá "true" e "false".
• Se você recuperar esses documentos com esse SDK do Python, os valores "true" e "false" serão convertidos automaticamente em "True" e "False".

Consultas SQL x subitens da cláusula FROM

Esse SDK usa o método query_items para enviar consultas SQL ao Azure Cosmos DB.

A linguagem SQL do Cosmos DB permite que você obtenha subitens usando a cláusula FROM para reduzir a origem a um subconjunto menor. Por exemplo, você pode usar select * from Families.children em vez de select * from Families. Mas observe que:

• Para consultas SQL que usam o query_items método , esse SDK exige que você especifique ou partition_key use o enable_cross_partition_query sinalizador.
• Se você estiver recebendo subitens e especificando o partition_key, verifique se a chave de partição está incluída nos subitens, o que não é verdade para a maioria dos casos.

Contagem máxima de itens

Esse é um parâmetro do método query_items, um inteiro que indica o número máximo de itens a serem retornados por página. O None valor pode ser especificado para permitir que o serviço determine a contagem de itens ideal. Esse é o valor de configuração recomendado e o comportamento padrão desse SDK quando ele não está definido.

Exemplos

As seguintes seções fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Cosmos DB, incluindo:

• Criar um banco de dados
• Criar um contêiner
• Criar um contêiner habilitado para repositório analítico
• Obter um contêiner existente
• Inserir dados
• Excluir dados
• Consultar o banco de dados
• Obter propriedades do banco de dados
• Obter taxas de transferência de banco de dados e contêiner
• Modificar propriedades do contêiner
• Usando o cliente assíncrono

Criar um banco de dados

Depois de autenticar o CosmosClient, você pode trabalhar com qualquer recurso na conta. O snippet de código abaixo cria um banco de dados de API sql, que é o padrão quando nenhuma API é especificada quando create_database é invocado.

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)

Criar um contêiner

Este exemplo cria um contêiner com configurações padrão. Se um contêiner com o mesmo nome já existir no banco de dados (gerando um 409 Conflict erro), o contêiner existente será obtido.

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

Criar um contêiner habilitado para repositório analítico

Este exemplo cria um contêiner com o Repositório Analítico habilitado para relatórios, BI, IA e Análise Avançada com Azure Synapse Link.

As opções para analytical_storage_ttl são:

• 0 ou Nulo ou não informado: não habilitado.
• -1: os dados serão armazenados infinitamente.
• Qualquer outro número: o ttl real, em segundos.

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

Os snippets anteriores também manipulam a exceção CosmosHttpResponseError se a criação do contêiner falhou. Para obter mais informações sobre tratamento de erros e solução de problemas, consulte a seção de solução de problemas .

Obter um contêiner existente

Recupere um contêiner existente do banco de dados:

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)

Inserir dados

Para inserir itens em um contêiner, passe um dicionário que contém seus dados para ContainerProxy.upsert_item. Cada item adicionado a um contêiner deve incluir uma id chave com um valor que identifique exclusivamente o item dentro do contêiner.

Este exemplo insere vários itens no contêiner, cada um com um exclusivo 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)
        }
    )

Excluir dados

Para excluir itens de um contêiner, use ContainerProxy.delete_item. A API do SQL no Cosmos DB não dá suporte à instrução 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')

OBSERVAÇÃO: se você estiver usando a coleção particionada, o valor do no código de partitionKey exemplo acima deverá ser definido como o valor da chave de partição para este item específico, não o nome da coluna de chave de partição em sua coleção. Isso vale para leituras e exclusões de ponto.

Consultar o banco de dados

Um banco de dados da API SQL do Cosmos DB dá suporte à consulta dos itens em um contêiner com ContainerProxy.query_items usando a sintaxe semelhante ao SQL.

Este exemplo consulta um contêiner para itens com um específico 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))

OBSERVAÇÃO: embora você possa especificar qualquer valor para o nome do FROM contêiner na cláusula , recomendamos que você use o nome do contêiner para consistência.

Execute consultas parametrizadas passando um dicionário que contém os parâmetros e seus valores para 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))

Para obter mais informações de como consultar bancos de dados do Cosmos BD usando a API de SQL, confira Consultar dados do Azure Cosmos DB com consultas SQL.

Obter propriedades do banco de dados

Obtenha e exiba as propriedades de um banco de dados:

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))

Obter taxas de transferência de banco de dados e contêiner

Obtenha e exiba os valores de taxa de transferência de um banco de dados e de um contêiner com taxa de transferência dedicada:

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']))

Modificar propriedades do contêiner

Determinadas propriedades de um contêiner existente podem ser modificadas. Este exemplo define o tempo de vida padrão (TTL) para itens no contêiner como 10 segundos:

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']))

Para obter mais informações sobre TTL, consulte Vida Útil para dados do Azure Cosmos DB.

Usando o cliente assíncrono

O cliente cosmos assíncrono é um cliente separado que parece e funciona de maneira semelhante ao cliente síncrono existente. No entanto, o cliente assíncrono precisa ser importado separadamente e seus métodos precisam ser usados com as palavras-chave assíncronas/await. O cliente Async precisa ser inicializado e fechado após o uso, o que pode ser feito manualmente ou com o uso de um gerenciador de contexto. O exemplo a seguir mostra como fazer isso manualmente.

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

Em vez de abrir e fechar manualmente o cliente, é altamente recomendável usar as async with palavras-chave. Isso cria um gerenciador de contexto que inicializará e fechará posteriormente o cliente quando você estiver fora da instrução. O exemplo a seguir mostra como fazer isso.

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)
                }
            )

Consultas com o cliente assíncrono

Ao contrário do cliente síncrono, o cliente assíncrono não tem um enable_cross_partition sinalizador na solicitação. Consultas sem um valor de chave de partição especificado tentarão fazer uma consulta entre partições por padrão.

Os resultados da consulta podem ser iterados, mas a saída bruta da consulta retorna um iterador assíncrono. Isso significa que cada objeto do iterador é um objeto aguardável e ainda não contém o resultado da consulta verdadeira. Para obter os resultados da consulta, você pode usar um loop assíncrono para, que aguarda cada resultado à medida que você itera no objeto ou aguarda manualmente cada resultado de consulta à medida que itera sobre o iterador assíncrono.

Como os resultados da consulta são um iterador assíncrono, eles não podem ser convertidos em listas diretamente; Em vez disso, se você precisar criar listas com base nos resultados, use um loop assíncrono para loop ou a compreensão da lista do Python para preencher uma lista:

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()

Usando o Cache Integrado

Um cache integrado é um cache na memória que ajuda você a garantir custos gerenciáveis e baixa latência à medida que o volume de solicitação aumenta. O cache integrado tem duas partes: um cache de itens para leituras de ponto e um cache de consultas para consultas. O snippet de código abaixo mostra como usar esse recurso com os métodos de cache de leitura e consulta de ponto.

O benefício de usar isso é que as leituras de ponto e consultas que atingem o cache integrado não usarão nenhuma RUs. Isso significa que você terá um custo por operação muito menor do que as leituras do back-end.

Como configurar o cache integrado do Azure Cosmos DB (versão prévia)

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)

Para obter mais informações sobre o Cache Integrado, consulte Cache integrado do Azure Cosmos DB – Visão geral.

Solução de problemas

Geral

Quando você interage com o Cosmos DB usando o SDK do Python, as exceções retornadas pelo serviço correspondem aos mesmos códigos http status retornados para solicitações de API REST:

Códigos de status HTTP para o Azure Cosmos DB

Por exemplo, se você tentar criar um contêiner usando uma ID (nome) que já está em uso no banco de dados do Cosmos DB, um 409 erro será retornado, indicando o conflito. No snippet a seguir, o erro é tratado normalmente capturando a exceção e exibindo informações adicionais sobre o erro.

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.""")

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado do nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um cliente com o logging_enable argumento :

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)

Da mesma forma, logging_enable pode habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

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

Como alternativa, você pode fazer logon usando o CosmosHttpLoggingPolicy, que se estende do HttpLoggingPolicy principal do azure, passando o agente para o logger argumento . Por padrão, ele usará o comportamento de HttpLoggingPolicy. Passar o enable_diagnostics_logging argumento habilitará o CosmosHttpLoggingPolicy e terá informações adicionais na resposta relevante para depurar problemas do 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)

Da mesma forma, o log pode ser habilitado para uma única operação passando um agente para a solicitação singular. No entanto, se você quiser usar o CosmosHttpLoggingPolicy para obter informações adicionais, o enable_diagnostics_logging argumento precisará ser passado no construtor do cliente.

# 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)

Telemetria

O Azure Core fornece a capacidade de nossos SDKs do Python usarem o OpenTelemetry com eles. Os únicos pacotes que precisam ser instalados para usar essa funcionalidade são os seguintes:

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

Para obter mais informações sobre isso, recomendamos dar uma olhada neste documento do Azure Core descrevendo como configurá-lo. Também adicionamos um arquivo de exemplo para mostrar como ele pode ser usado com nosso SDK. Isso funciona da mesma maneira, independentemente do cliente Cosmos que você está usando.

Próximas etapas

Para obter uma documentação mais abrangente sobre o serviço Cosmos BD, confira a documentação do Azure Cosmos DB em docs.microsoft.com.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.