Exclusão de Responsabilidade

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

Biblioteca de cliente da API SQL do Azure Cosmos DB para Python – versão 4.5.1

O Azure Cosmos DB é um serviço de base de dados com vários modelos distribuído globalmente que suporta bases de dados de documento, chave-valor, colunas e grafo.

Utilize o SDK da API SQL do Azure Cosmos DB para Python para gerir bases de dados e os documentos JSON que contêm neste serviço de base de dados NoSQL. As capacidades de alto nível são:

• Criar bases de dados do Cosmos DB e modificar as respetivas definições
• Criar e modificar contentores para armazenar coleções de documentos JSON
• Criar, ler, atualizar e eliminar os itens (documentos JSON) nos seus contentores
• Consultar os documentos na base de dados com a sintaxe semelhante a SQL

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

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

Introdução

Atualização importante no Suporte do Python 2.x

As novas versões deste SDK não suportarão o Python 2.x a partir de 1 de janeiro de 2022. Verifique o REGISTO DE ALTERAÇÕES para obter mais informações.

Pré-requisitos

• Subscrição do Azure – Criar uma conta gratuita
• Conta do Azure Cosmos DB – API SQL
• Python 3.6 e superior

Se precisar de uma conta da API SQL do Cosmos DB, pode 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, pode manter o sistema base e os ambientes do SDK do Azure isolados uns dos outros se utilizar um ambiente virtual. Execute os seguintes comandos para configurar e, em seguida, introduza 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 . Precisa de uma conta, do respetivo URI e de uma das respetivas chaves de conta para instanciar o objeto de cliente.

Utilize o fragmento da CLI do Azure abaixo para preencher duas variáveis de ambiente com o URI da conta de base de dados e a chave mestra primária (também pode encontrar estes valores no portal do Azure). O fragmento está formatado para a 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)

Criar o cliente

Depois de preencher as ACCOUNT_URI variáveis de ambiente e ACCOUNT_KEY , 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

Também pode autenticar um cliente com as credenciais do AAD do principal de serviço e o pacote de identidade do azure. Pode transmitir diretamente as informações das credenciais para ClientSecretCredential ou utilizar 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)

Certifique-se sempre de que a identidade gerida que utiliza para a 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 as operações permitidas para clientes autenticados do AAD: Modelo de Permissão RBAC

Conceitos-chave

Depois de inicializar um CosmosClient, pode interagir com os tipos de recursos principais no Cosmos DB:

• Base de dados: uma conta do Cosmos DB pode conter várias bases de dados. Quando cria uma base de dados, especifica a API que pretende utilizar ao interagir com os respetivos documentos: SQL, MongoDB, Gremlin, Cassandra ou Tabela do Azure. Utilize o objeto DatabaseProxy para gerir os respetivos contentores.

• Contentor: um contentor é uma coleção de documentos JSON. Pode criar (inserir), ler, atualizar e eliminar itens num contentor através de métodos no objeto ContainerProxy .

• Item: um Item é a representação semelhante ao dicionário de um documento JSON armazenado num contentor. Cada Item que adicionar a um contentor tem de incluir uma id chave com um valor que identifique exclusivamente o item no contentor.

Para obter mais informações sobre estes recursos, veja Trabalhar com bases de dados, contentores e itens do Azure Cosmos.

Como utilizar enable_cross_partition_query

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

Nota sobre a utilização de consultas por ID

Ao utilizar consultas que tentam localizar itens com base num valor de ID , certifique-se sempre de que está a transmitir uma variável de tipo de cadeia. O Azure Cosmos DB só permite valores de ID de cadeia e, se utilizar outro tipo de dados, este SDK não devolverá resultados nem mensagens de erro.

Nota sobre os níveis de consistência do cliente

A partir da versão 4.3.0b3, se um utilizador não transmitir um nível de consistência explícito à inicialização do cliente, o cliente utilizará o nível predefinido da conta de base de dados. Anteriormente, a predefinição estava a ser definida como Session consistência. Se, por algum motivo, quiser continuar a fazê-lo, pode alterar a inicialização do cliente para incluir o parâmetro explícito, 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, as funcionalidades abaixo não são suportadas. Para obter opções alternativas, consulte a secção Soluções abaixo.

Limitações do Plano de Dados:

• Agrupar Por consultas
• Consultas com CONTAR 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 tokens de continuação para consultas entre partições agregadas, como ordenação, contagem e distinção. As consultas passíveis de transmissão em fluxo, como SELECT * FROM WHEREsuportam tokens de continuação.
• Feed de Alterações: Processador
• Feed de Alterações: ler vários valores de chave de partições
• Feed de Alterações: ler hora específica
• Feed de Alterações: Lido desde o início
• Feed de Alterações: modelo pull
• ORDEM POR entre partições para tipos mistos
• Ativar diagnósticos para métodos de tipo de consulta assíncrono

Limitações do Plano de Controlo:

• Obter métricas CollectionSizeUsage, DatabaseUsage e DocumentUsage
• Criar Índice Geoespacial
• Obter a cadeia de ligação
• Obter as RU/s mínimas de um contentor

Soluções

Solução de Limitação do Processamento em Massa

Se quiser utilizar o SDK python para efetuar inserções em massa no Cosmos DB, a melhor alternativa é utilizar procedimentos armazenados para escrever vários itens com a mesma chave de partição.

Solução Para As Limitações do Plano de Controlo

Normalmente, pode utilizar o Portal do Azure, a API REST do Fornecedor de Recursos do Azure Cosmos DB, a CLI do Azure ou o PowerShell para as limitações não suportadas do plano de controlo.

Tipo de Dados Booleano

Embora a linguagem Python utilize "Verdadeiro" e "Falso" para tipos booleanos, o Cosmos DB só aceita "verdadeiro" e "falso". Por outras palavras, a linguagem Python utiliza valores booleanos com a primeira letra maiúscula e todas as outras letras minúsculas, enquanto o Cosmos DB e a respetiva linguagem SQL utilizam apenas letras minúsculas para esses mesmos valores Booleanos. Como lidar com este desafio?

• Os documentos JSON criados com Python têm de utilizar "Verdadeiro" e "Falso" para transmitir a validação de idioma. O SDK irá convertê-lo em "verdadeiro" e "falso" para si. O que significa que "verdadeiro" e "falso" é o que será armazenado no Cosmos DB.
• Se obter esses documentos com a Data Explorer do Portal do Cosmos DB, verá "verdadeiro" e "falso".
• Se obter esses documentos com este SDK Python, os valores "verdadeiro" e "falso" serão automaticamente convertidos em "Verdadeiro" e "Falso".

Consultas SQL x Subsistemas de Cláusula FROM

Este SDK utiliza o método query_items para submeter consultas SQL para o Azure Cosmos DB.

A linguagem SQL do Cosmos DB permite-lhe obter subsistemas com a cláusula FROM para reduzir a origem a um subconjunto mais pequeno. Por exemplo, pode utilizar select * from Families.children em vez de select * from Families. No entanto, tenha em atenção que:

• Para consultas SQL com o query_items método , este SDK exige que especifique ou partition_key utilize o enable_cross_partition_query sinalizador .
• Se estiver a obter subsistemas e a especificar o partition_key, certifique-se de que a chave de partição está incluída nos subsistemas, o que não é verdade para a maioria dos casos.

Contagem Máxima de Itens

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

Exemplos

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

• Criar uma base de dados
• Criar um contentor
• Criar um contentor ativado para arquivo analítico
• Obter um contentor existente
• Inserir dados
• Eliminar dados
• Consultar a base de dados
• Obter propriedades da base de dados
• Obter débitos de base de dados e contentores
• Modificar as propriedades do contentor
• Utilizar o cliente assíncrono

Criar uma base de dados

Depois de autenticar o CosmosClient, pode trabalhar com qualquer recurso na conta. O fragmento de código abaixo cria uma base de dados da API SQL, que é a predefinição quando não é especificada nenhuma API quando create_database é invocada.

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 contentor

Este exemplo cria um contentor com predefinições. Se já existir um contentor com o mesmo nome na base de dados (gerando um 409 Conflict erro), é obtido o contentor existente.

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 contentor ativado para arquivo analítico

Este exemplo cria um contentor com o Arquivo Analítico ativado, para relatórios, BI, IA e Análise Avançada com o Azure Synapse Link.

As opções para analytical_storage_ttl são:

• 0 ou Nulo ou não informado: Não ativado.
• -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 fragmentos anteriores também processam a exceção CosmosHttpResponseError se a criação do contentor tiver falhado. Para obter mais informações sobre o processamento de erros e a resolução de problemas, veja a secção .

Obter um contentor existente

Obter um contentor existente a partir da base 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 num contentor, transmita um dicionário que contenha os seus dados para ContainerProxy.upsert_item. Cada item que adicionar a um contentor tem de incluir uma id chave com um valor que identifique exclusivamente o item no contentor.

Este exemplo insere vários itens no contentor, 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)
        }
    )

Eliminar dados

Para eliminar itens de um contentor, utilize ContainerProxy.delete_item. A API SQL no Cosmos DB não suporta a 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')

NOTA: se estiver a utilizar a coleção particionada, o valor do partitionKey no código de exemplo acima deve ser definido para o valor da chave de partição para este item específico e não para o nome da coluna da chave de partição na coleção. Isto aplica-se a leituras e eliminações de pontos.

Consultar a base de dados

Uma base de dados da API SQL do Cosmos DB suporta a consulta dos itens num contentor com ContainerProxy.query_items através da sintaxe semelhante a SQL.

Este exemplo consulta um contentor 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))

NOTA: embora possa especificar qualquer valor para o nome do FROM contentor na cláusula, recomendamos que utilize o nome do contentor para consistência.

Execute consultas parametrizadas ao transmitir um dicionário que contém os parâmetros e os respetivos 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 sobre como consultar bases de dados do Cosmos DB com a API SQL, veja Consultar dados do Azure Cosmos DB com consultas SQL.

Obter propriedades da base de dados

Obtenha e apresente as propriedades de uma base 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 débitos de base de dados e contentores

Obtenha e apresente os valores de débito de uma base de dados e de um contentor com débito dedicado:

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 as propriedades do contentor

Determinadas propriedades de um contentor existente podem ser modificadas. Este exemplo define o tempo de vida predefinido (TTL) para itens no contentor para 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 o TTL, veja Time to Live para dados do Azure Cosmos DB.

Utilizar o cliente assíncrono

O cliente cosmos assíncrono é um cliente separado que tem um aspeto e funciona de forma semelhante ao cliente síncrono existente. No entanto, o cliente assíncrono tem de ser importado separadamente e os respetivos métodos têm de ser utilizados com as palavras-chave assíncronas/de espera. O cliente Async tem de ser inicializado e fechado após a utilização, o que pode ser feito manualmente ou com a utilização de um gestor de contexto. O exemplo abaixo mostra como fazê-lo 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 recomendado utilizar as async with palavras-chave. Esta ação cria um gestor de contexto que irá inicializar e, mais tarde, fechar o cliente assim que estiver fora da instrução. O exemplo abaixo mostra como fazê-lo.

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 no pedido. As consultas sem um valor de chave de partição especificada tentarão efetuar uma consulta entre partições por predefinição.

Os resultados da consulta podem ser iterados, mas a saída não processada da consulta devolve um iterador assíncrono. Isto significa que cada objeto do iterador é um objeto de espera e ainda não contém o resultado da consulta verdadeira. Para obter os resultados da consulta, pode utilizar uma assíncrona para ciclo, que aguarda cada resultado à medida que itera no objeto ou aguarda manualmente cada resultado da consulta à medida que itera sobre o iterador assíncrono.

Uma vez que os resultados da consulta são um iterador assíncrono, não podem ser convertidos diretamente em listas; em vez disso, se precisar de criar listas a partir dos resultados, utilize uma assíncrona para ciclo 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()

Utilizar a Cache Integrada

Uma cache integrada é uma cache dentro da memória que o ajuda a garantir custos geríveis e baixa latência à medida que o volume de pedidos aumenta. A cache integrada tem duas partes: uma cache de itens para leituras de pontos e uma cache de consulta para consultas. O fragmento de código abaixo mostra-lhe como utilizar esta funcionalidade com os métodos de cache de consulta e leitura de pontos.

A vantagem de utilizar isto é que as consultas e leituras de pontos que atingem a cache integrada não irão utilizar RUs. Isto significa que terá um custo por operação muito mais baixo do que as leituras do back-end.

Como configurar a cache integrada do Azure Cosmos DB (Pré-visualização)

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 a Cache Integrada, veja Cache integrada do Azure Cosmos DB – Descrição Geral.

Resolução de problemas

Geral

Quando interage com o Cosmos DB com o SDK python, as exceções devolvidas pelo serviço correspondem aos mesmos códigos de estado HTTP devolvidos para pedidos da API REST:

Códigos de Estado HTTP para o Azure Cosmos DB

Por exemplo, se tentar criar um contentor com um ID (nome) que já está a ser utilizado na base de dados do Cosmos DB, é devolvido um 409 erro que indica o conflito. No fragmento seguinte, o erro é processado corretamente através da deteção da exceção e da apresentação de 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.""")

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registo. As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.

O registo detalhado ao nível da DEBUG, incluindo os corpos de pedido/resposta e os cabeçalhos não retotados, pode ser ativado num 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 ativar o registo detalhado para uma única operação, mesmo quando não está ativado para o cliente:

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

Em alternativa, pode iniciar sessão com o CosmosHttpLoggingPolicy, que se estende do httploggingPolicy principal do azure, ao transmitir o seu logger para o logger argumento . Por predefinição, utilizará o comportamento de HttpLoggingPolicy. Transmitir o enable_diagnostics_logging argumento ativará o CosmosHttpLoggingPolicy e terá informações adicionais na resposta relevantes para a depuração de 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 registo pode ser ativado para uma única operação ao transmitir um logger para o pedido singular. No entanto, se pretender utilizar o CosmosHttpLoggingPolicy para obter informações adicionais, o enable_diagnostics_logging argumento tem de ser transmitido no construtor 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 para os nossos SDKs Python utilizarem o OpenTelemetry com eles. Os únicos pacotes que precisam de ser instalados para utilizar esta funcionalidade são os seguintes:

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

Para obter mais informações, recomendamos que veja este documento a partir do Azure Core, descrevendo como configurá-lo. Também adicionámos um ficheiro de exemplo para mostrar como pode ser utilizado com o nosso SDK. Isto funciona da mesma forma, independentemente do cliente do Cosmos que estiver a utilizar.

Passos seguintes

Para obter documentação mais extensa sobre o serviço Cosmos DB, veja a documentação do Azure Cosmos DB sobre docs.microsoft.com.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.