Declinación de responsabilidades

Los paquetes de Python del SDK de Azure para Python 2.7 finalizaron el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Biblioteca cliente de SQL API de Azure Cosmos DB para Python: versión 4.5.1

Azure Cosmos DB es un servicio de base de datos multimodelo distribuido globalmente que admite bases de datos de documentos, pares clave-valor, basadas en columnas y gráficos.

Use el SDK de SQL API de Azure Cosmos DB para Python para administrar bases de datos y los documentos JSON que contienen en este servicio de base de datos NoSQL. Las funcionalidades de alto nivel son:

• Creación de bases de datos de Cosmos DB y modificación de su configuración
• Creación y modificación de contenedores para almacenar colecciones de documentos JSON
• Crear, leer, actualizar y eliminar los elementos (documentos JSON) en los contenedores
• Consulta de los documentos de la base de datos mediante la sintaxis similar a SQL

Código | fuente del SDKPaquete (PyPI) | Paquete (Conda) | Documentación | de referencia de APIDocumentación | del productoMuestras

Este SDK se usa para la API de SQL. Para todas las demás API, consulte la documentación de Azure Cosmos DB para evaluar el mejor SDK para el proyecto.

Introducción

Actualización importante en la compatibilidad con Python 2.x

Las nuevas versiones de este SDK no admitirán Python 2.x a partir del 1 de enero de 2022. Compruebe CHANGELOG para más información.

Prerrequisitos

• Una suscripción de Azure (cree una cuenta gratuita).
• Cuenta de Azure Cosmos DB: SQL API
• Python 3.6 o posterior

Si necesita una cuenta de SQL API de Cosmos DB, puede crear una con este comando de la CLI de Azure :

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

Instalar el paquete

pip install azure-cosmos

Configuración de un entorno virtual (opcional)

Aunque no es necesario, puede aislar el sistema base de los entornos de SDK de Azure si usa un entorno virtual. Ejecute los siguientes comandos para configurar y, a continuación, escriba un entorno virtual con venv:

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

Autenticar el cliente

La interacción con Cosmos DB comienza con una instancia de la clase CosmosClient . Necesita una cuenta, su URI y una de sus claves de cuenta para crear instancias del objeto de cliente.

Use el fragmento de código de la CLI de Azure siguiente para rellenar dos variables de entorno con el URI de la cuenta de base de datos y su clave maestra principal (también puede encontrar estos valores en el Azure Portal). El fragmento de código tiene el formato para el shell de 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)

Creación del cliente

Una vez que haya rellenado las ACCOUNT_URI variables de entorno y ACCOUNT_KEY , puede crear CosmosClient.

from azure.cosmos import CosmosClient

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

Autenticación de AAD

También puede autenticar un cliente mediante las credenciales de AAD de la entidad de servicio y el paquete de identidad de Azure. Puede pasar directamente la información de credenciales a ClientSecretCredential o 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)

Asegúrese siempre de que la identidad administrada que use para la autenticación de AAD tenga readMetadata permisos.
Más información sobre cómo configurar la autenticación de AAD: Configuración de RBAC para la autenticación de AAD
Más información sobre las operaciones permitidas para clientes autenticados de AAD: Modelo de permisos de RBAC

Conceptos clave

Una vez que haya inicializado CosmosClient, puede interactuar con los tipos de recursos principales de Cosmos DB:

• Base de datos: Una cuenta de Cosmos DB puede contener varias bases de datos. Al crear una base de datos, especifique la API que desea usar al interactuar con sus documentos: SQL, MongoDB, Gremlin, Cassandra, o Azure Table. Use el objeto DatabaseProxy para administrar sus contenedores.

• Contenedor: Un contenedor es una colección de documentos JSON. Puede crear (insertar), leer, actualizar y eliminar elementos en un contenedor mediante métodos en el objeto ContainerProxy .

• Elemento: un elemento es la representación similar al diccionario de un documento JSON almacenado en un contenedor. Cada elemento que agregue a un contenedor debe incluir una id clave con un valor que identifique de forma única el elemento dentro del contenedor.

Para más información sobre estos recursos, consulte Uso de bases de datos, contenedores y elementos de Azure Cosmos.

Cómo usar enable_cross_partition_query

El argumento enable_cross_partition_query de palabra clave acepta 2 opciones: None (valor predeterminado) o True.

Nota sobre el uso de consultas por identificador

Al usar consultas que intentan buscar elementos basados en un valor id , asegúrese siempre de pasar una variable de tipo de cadena. Azure Cosmos DB solo permite valores de identificador de cadena y, si usa cualquier otro tipo de datos, este SDK no devolverá ningún resultado y ningún mensaje de error.

Nota sobre los niveles de coherencia del cliente

A partir de la versión 4.3.0b3, si un usuario no pasa un nivel de coherencia explícito a su inicialización de cliente, su cliente usará el nivel predeterminado de su cuenta de base de datos. Anteriormente, el valor predeterminado estaba establecido en Session coherencia. Si por algún motivo desea seguir haciendo esto, puede cambiar la inicialización del cliente para incluir el parámetro explícito para esto como se muestra:

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

Limitaciones

Actualmente, no se admiten las características siguientes. Para ver las opciones alternativas, consulte la sección Soluciones alternativas a continuación.

Limitaciones del plano de datos:

• Agrupar por consultas
• Consultas con COUNT desde una subconsulta DISTINCT: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Procesamiento por lotes masivo/transaccional
• Acceso directo al modo TCP
• Compatibilidad con tokens de continuación para consultas agregadas entre particiones, como la ordenación, el recuento y la diferenciación. Las consultas que se pueden transmitir, como SELECT * FROM WHERE, por ejemplo, admiten tokens de continuación.
• Fuente de cambios: procesador
• Fuente de cambios: leer varios valores de clave de particiones
• Fuente de cambios: hora específica de lectura
• Fuente de cambios: lectura desde el principio
• Fuente de cambios: Modelo de extracción
• ORDER BY entre particiones para tipos mixtos
• Habilitación de diagnósticos para métodos de tipo de consulta asincrónicos

Limitaciones del plano de control:

• Obtener métricas CollectionSizeUsage, DatabaseUsage y DocumentUsage
• Creación de un índice geoespacial
• Obtención de la cadena de conexión
• Obtención de las RU/s mínimas de un contenedor

Soluciones alternativas

Solución alternativa de limitación de procesamiento masivo

Si desea usar el SDK de Python para realizar inserciones masivas en Cosmos DB, la mejor alternativa es usar procedimientos almacenados para escribir varios elementos con la misma clave de partición.

Solución alternativa a las limitaciones del plano de control

Normalmente, puede usar Azure Portal, la API REST del proveedor de recursos de Azure Cosmos DB, la CLI de Azure o PowerShell para las limitaciones no admitidas del plano de control.

Tipo de datos Boolean

Aunque el lenguaje Python usa "True" y "False" para tipos booleanos, Cosmos DB solo acepta "true" y "false". En otras palabras, el lenguaje Python usa valores booleanos con la primera letra mayúscula y todas las demás letras minúsculas, mientras que Cosmos DB y su lenguaje SQL usan solo letras minúsculas para esos mismos valores booleanos. ¿Cómo lidiar con este desafío?

• Los documentos JSON creados con Python deben usar "True" y "False" para pasar la validación del lenguaje. El SDK lo convertirá en "true" y "false" automáticamente. Lo que significa que "true" y "false" es lo que se almacenará en Cosmos DB.
• Si recupera esos documentos con el Data Explorer del portal de Cosmos DB, verá "true" y "false".
• Si recupera esos documentos con este SDK de Python, los valores "true" y "false" se convertirán automáticamente en "True" y "False".

Subitems de la cláusula SQL Queries x FROM

Este SDK usa el método query_items para enviar consultas SQL a Azure Cosmos DB.

El lenguaje SQL de Cosmos DB permite obtener subelementos mediante la cláusula FROM para reducir el origen a un subconjunto más pequeño. Por ejemplo, puede usar select * from Families.children en lugar de select * from Families. Pero tenga en cuenta que:

• Para las consultas SQL que usan el query_items método , este SDK exige que especifique o partition_key use la enable_cross_partition_query marca .
• Si obtiene subelementos y especifica , partition_keyasegúrese de que la clave de partición se incluye en los subelementos, que no es true para la mayoría de los casos.

Recuento máximo de elementos

Se trata de un parámetro del método query_items, un entero que indica el número máximo de elementos que se devolverán por página. El None valor se puede especificar para permitir que el servicio determine el recuento óptimo de elementos. Este es el valor de configuración recomendado y el comportamiento predeterminado de este SDK cuando no se establece.

Ejemplos

Las secciones siguientes proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes de Cosmos DB, entre las que se incluyen las siguientes:

• Creación de una base de datos
• Creación de un contenedor
• Creación de un contenedor habilitado para el almacén analítico
• Obtención de un contenedor existente
• Insertar datos
• Eliminar datos
• Consulta de la base de datos
• Obtención de las propiedades de la base de datos
• Obtención de rendimientos de base de datos y contenedor
• Modificación de las propiedades del contenedor
• Uso del cliente asincrónico

Crear una base de datos

Después de autenticar CosmosClient, puede trabajar con cualquier recurso de la cuenta. El fragmento de código siguiente crea una base de datos de SQL API, que es el valor predeterminado cuando no se especifica ninguna API cuando se invoca create_database .

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)

Crear un contenedor

En este ejemplo se crea un contenedor con la configuración predeterminada. Si ya existe un contenedor con el mismo nombre en la base de datos (lo que genera un 409 Conflict error), el contenedor existente se obtiene en su lugar.

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

Crear un contenedor habilitado para el almacén analítico.

En este ejemplo se crea un contenedor con el Almacén analítico habilitado, para informes, BI, IA y Análisis avanzado con Azure Synapse Link.

Las opciones de analytical_storage_ttl son:

• 0 o Null o no informado: No habilitado.
• -1: Los datos se almacenarán infinitamente.
• Cualquier otro número: el ttl real, en 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

Los fragmentos de código anteriores también controlan la excepción CosmosHttpResponseError si se produjo un error en la creación del contenedor. Para obtener más información sobre el control de errores y la solución de problemas, consulte la sección .

Obtención de un contenedor existente

Recuperar un contenedor existente de la base de datos:

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)

Insertar datos

Para insertar elementos en un contenedor, pase un diccionario que contenga los datos a ContainerProxy.upsert_item. Cada elemento que agregue a un contenedor debe incluir una id clave con un valor que identifique de forma única el elemento dentro del contenedor.

En este ejemplo se insertan varios elementos en el contenedor, cada uno con un valor único 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)
        }
    )

Eliminación de datos

Para eliminar elementos de un contenedor, use ContainerProxy.delete_item. La API de SQL en Cosmos DB no admite la instrucción 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: Si usa la colección con particiones, el valor de en el código de partitionKey ejemplo anterior debe establecerse en el valor de la clave de partición para este elemento en particular, no en el nombre de la columna de clave de partición de la colección. Esto se aplica tanto a las lecturas puntuales como a las eliminaciones.

Consulta de la base de datos

Una base de datos de SQL API de Cosmos DB admite la consulta de los elementos de un contenedor con ContainerProxy.query_items mediante la sintaxis similar a SQL.

En este ejemplo se consulta un contenedor para los elementos con un elemento 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: Aunque puede especificar cualquier valor para el nombre del contenedor en la FROM cláusula , se recomienda usar el nombre del contenedor para la coherencia.

Para realizar consultas con parámetros, pase un diccionario que contenga los parámetros y sus valores a 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 más información sobre cómo consultar bases de datos de Cosmos DB mediante SQL API, consulte Consulta de datos de Azure Cosmos DB con consultas SQL.

Obtención de las propiedades de la base de datos

Obtenga y muestre las propiedades de una base de datos:

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

Obtención de rendimientos de base de datos y contenedor

Obtenga y muestre los valores de rendimiento de una base de datos y de un contenedor con rendimiento 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']))

Modificación de las propiedades del contenedor

Se pueden modificar determinadas propiedades de un contenedor existente. En este ejemplo se establece el período de vida predeterminado (TTL) para los elementos del contenedor en 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 más información sobre TTL, consulte Período de vida para los datos de Azure Cosmos DB.

Uso del cliente asincrónico

El cliente de Cosmos asincrónico es un cliente independiente que tiene un aspecto y funciona de forma similar al cliente sincrónico existente. Sin embargo, el cliente asincrónico debe importarse por separado y sus métodos deben usarse con las palabras clave async/await. El cliente asincrónico debe inicializarse y cerrarse después del uso, que se puede realizar manualmente o con el uso de un administrador de contexto. En el ejemplo siguiente se muestra cómo hacerlo 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

En lugar de abrir y cerrar manualmente el cliente, se recomienda encarecidamente usar las async with palabras clave. Esto crea un administrador de contexto que inicializará y cerrará más adelante el cliente una vez que esté fuera de la instrucción . En el ejemplo siguiente se muestra cómo hacerlo.

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 con el cliente asincrónico

A diferencia del cliente sincrónico, el cliente asincrónico no tiene una enable_cross_partition marca en la solicitud. Las consultas sin un valor de clave de partición especificado intentarán realizar una consulta entre particiones de forma predeterminada.

Los resultados de la consulta se pueden iterar, pero la salida sin procesar de la consulta devuelve un iterador asincrónico. Esto significa que cada objeto del iterador es un objeto que se puede esperar y que aún no contiene el resultado de la consulta true. Para obtener los resultados de la consulta, puede usar un bucle async for, que espera cada resultado a medida que itera en el objeto, o bien esperar manualmente cada resultado de consulta a medida que recorre en iteración el iterador asincrónico.

Dado que los resultados de la consulta son un iterador asincrónico, no se pueden convertir directamente en listas; en su lugar, si necesita crear listas a partir de los resultados, use un bucle async for o la comprensión de lista de Python para rellenar una 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()

Uso de caché integrada

Una caché integrada es una caché en memoria que le ayuda a garantizar costos administrables y baja latencia a medida que crece el volumen de solicitudes. La caché integrada tiene dos partes: una caché de elementos para lecturas puntuales y una caché de consultas para consultas. El fragmento de código siguiente muestra cómo usar esta característica con los métodos de caché de lectura y consulta puntuales.

La ventaja de usar esto es que el punto lee y las consultas que alcanzan la memoria caché integrada no usarán ninguna RU. Esto significa que tendrá un costo mucho menor por operación que las lecturas del back-end.

Cómo configurar la caché integrada de Azure Cosmos DB (versión preliminar)

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 más información sobre la caché integrada, consulte Caché integrada de Azure Cosmos DB: información general.

Solución de problemas

General

Al interactuar con Cosmos DB mediante el SDK de Python, las excepciones devueltas por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de la API REST:

Códigos de estado HTTP para Azure Cosmos DB

Por ejemplo, si intenta crear un contenedor con un identificador (nombre) que ya está en uso en la base de datos de Cosmos DB, se devuelve un 409 error que indica el conflicto. En el siguiente fragmento, el error se controla correctamente al detectar la excepción y mostrar información adicional sobre el error.

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

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel de DEPURACIÓN, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el 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)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

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

Como alternativa, puede iniciar sesión mediante CosmosHttpLoggingPolicy, que se extiende desde el núcleo de Azure HttpLoggingPolicy, pasando el registrador al logger argumento . De forma predeterminada, usará el comportamiento de HttpLoggingPolicy. Pasar el enable_diagnostics_logging argumento habilitará CosmosHttpLoggingPolicy y tendrá información adicional en la respuesta pertinente para depurar problemas de 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)

Del mismo modo, el registro se puede habilitar para una sola operación pasando un registrador a la solicitud singular. Sin embargo, si desea usar CosmosHttpLoggingPolicy para obtener información adicional, el enable_diagnostics_logging argumento debe pasarse en el constructor de 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)

Telemetría

Azure Core proporciona la capacidad de nuestros SDK de Python para usar OpenTelemetry con ellos. Los únicos paquetes que deben instalarse para usar esta funcionalidad son los siguientes:

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

Para más información sobre esto, se recomienda echar un vistazo a este documento de Azure Core que describe cómo configurarlo. También hemos agregado un archivo de ejemplo para mostrar cómo se puede usar con nuestro SDK. Esto funciona de la misma manera independientemente del cliente de Cosmos que use.

Pasos siguientes

Para obtener documentación ampliada sobre el servicio Cosmos DB, consulte la documentación de Azure Cosmos DB en docs.microsoft.com.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.