Dichiarazione di non responsabilità

Articolo
09/13/2023

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato 01 gennaio 2022. Per altre informazioni e domande, vedere https://github.com/Azure/azure-sdk-for-python/issues/20691

Libreria client dell'API SQL di Azure Cosmos DB per Python - versione 4.5.1

Azure Cosmos DB è un servizio di database multimodello distribuito a livello globale che supporta database di documenti, con coppie chiave-valore, con colonne ampie e grafi.

Usare Azure Cosmos DB SQL API SDK per Python per gestire i database e i documenti JSON che contengono in questo servizio di database NoSQL. Le funzionalità di alto livello sono:

Creare database Cosmos DB e modificare le impostazioni
Creare e modificare contenitori per archiviare raccolte di documenti JSON
Creare, leggere, aggiornare ed eliminare gli elementi (documenti JSON) nei contenitori
Eseguire query sui documenti nel database usando la sintassi simile a SQL

Questo SDK viene usato per l'API SQL. Per tutte le altre API, consultare la documentazione di Azure Cosmos DB per valutare l'SDK migliore per il progetto.

Introduzione

Aggiornamento importante nel supporto di Python 2.x

Le nuove versioni di questo SDK non supportano Python 2.x a partire dal 1° gennaio 2022. Per altre informazioni, controllare CHANGELOG .

Prerequisiti

Sottoscrizione di Azure. Creare un account gratuito
Account Azure Cosmos DB - API SQL
Python 3.6+

Se è necessario un account API SQL di Cosmos DB, è possibile crearne uno con questo comando dell'interfaccia della riga di comando di Azure:

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

Installare il pacchetto

pip install azure-cosmos

Configurare un ambiente virtuale (facoltativo)

Nonostante non sia obbligatorio, è possibile mantenere gli ambienti del sistema di base e degli SDK di Azure isolati tra loro usando un ambiente virtuale. Eseguire i comandi seguenti per configurare e quindi immettere un ambiente virtuale con venv:

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

Autenticare il client

L'interazione con Cosmos DB inizia con un'istanza della classe CosmosClient . È necessario un account, il relativo URI e una delle relative chiavi di account per creare un'istanza dell'oggetto client.

Usare il frammento di interfaccia della riga di comando di Azure seguente per popolare due variabili di ambiente con l'URI dell'account di database e la relativa chiave master primaria (è anche possibile trovare questi valori nell'portale di Azure). Il frammento è presentato nel formato per la shell 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)

Creare il client

Dopo aver popolato le ACCOUNT_URI variabili di ambiente e ACCOUNT_KEY , è possibile creare CosmosClient.

from azure.cosmos import CosmosClient

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

Autenticazione AAD

È anche possibile autenticare un client usando le credenziali AAD dell'entità servizio e il pacchetto di identità di Azure. È possibile passare direttamente le informazioni sulle credenziali a ClientSecretCredential oppure usare 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)

Assicurarsi sempre che l'identità gestita usata per l'autenticazione AAD disponga readMetadata delle autorizzazioni.
Altre informazioni su come configurare l'autenticazione AAD: Configurare il controllo degli accessi in base al ruolo per l'autenticazione AAD
Altre informazioni sulle operazioni consentite per i client autenticati AAD: Modello di autorizzazione RBAC

Concetti chiave

Dopo aver inizializzato CosmosClient, è possibile interagire con i tipi di risorse primari in Cosmos DB:

Database: Un account di Cosmos DB può contenere più database. Quando si crea un database, si specifica l'API che si vuole usare quando si interagisce con questi documenti: SQL, MongoDB, Gremlin, Cassandra o Tabella di Azure. Usare l'oggetto DatabaseProxy per gestire i contenitori.
Contenitore: Un contenitore è una raccolta di documenti JSON. È possibile creare (inserire), leggere, aggiornare ed eliminare elementi in un contenitore usando i metodi nell'oggetto ContainerProxy .
Elemento: un elemento è la rappresentazione simile al dizionario di un documento JSON archiviato in un contenitore. Ogni elemento aggiunto a un contenitore deve includere una chiave con un id valore che identifica in modo univoco l'elemento all'interno del contenitore.

Per altre informazioni su queste risorse, vedere Usare database, contenitori ed elementi di Azure Cosmos.

Come usare `enable_cross_partition_query`

L'argomento enable_cross_partition_query della parola chiave accetta 2 opzioni: None (impostazione predefinita) o True.

Nota sull'uso di query in base all'ID

Quando si usano query che tentano di trovare elementi in base a un valore ID , assicurarsi sempre di passare una variabile di tipo stringa. Azure Cosmos DB consente solo valori id stringa e, se si usa qualsiasi altro tipo di dati, questo SDK restituirà nessun risultato e nessun messaggio di errore.

Nota sui livelli di coerenza client

A partire dalla versione 4.3.0b3, se un utente non passa un livello di coerenza esplicito all'inizializzazione client, il client userà il livello predefinito dell'account di database. In precedenza, il valore predefinito è stato impostato sulla Session coerenza. Se per qualche motivo si vuole continuare a eseguire questa operazione, è possibile modificare l'inizializzazione client in modo da includere il parametro esplicito per questo come illustrato:

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

Limitazioni

Attualmente le funzionalità seguenti non sono supportate. Per le opzioni alternative, selezionare la sezione Soluzioni alternative riportate di seguito.

Limitazioni del piano dati:

Raggruppa per query
Query con COUNT da una sottoquery DISTINCT: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
Elaborazione batch bulk/transazionale
Accesso diretto alla modalità TCP
Supporto del token di continuazione per le query tra partizioni aggregate, ad esempio l'ordinamento, il conteggio e i distinti. Query streamable, ad esempioSELECT * FROM WHERE, supportano i token di continuazione.
Feed di modifiche: Processore
Feed di modifiche: leggere più valori chiave delle partizioni
Feed di modifiche: lettura di tempo specifico
Feed di modifiche: leggere dall'inizio
Feed di modifiche: modello pull
ORDER BY tra partizioni per tipi misti
Abilitazione della diagnostica per i metodi di tipo query asincroni

Limitazioni del piano di controllo:

Ottenere le metriche CollectionSizeUsage, DatabaseUsage e DocumentUsage
Creare un indice geospaziale
Ottenere la stringa di connessione
Ottenere l'UR/s minimo di un contenitore

Soluzioni alternative

Soluzione alternativa per la limitazione dell'elaborazione bulk

Se si vuole usare Python SDK per eseguire inserimenti bulk in Cosmos DB, l'alternativa migliore consiste nell'usare stored procedure per scrivere più elementi con la stessa chiave di partizione.

Limitazioni del piano di controllo soluzione alternativa

In genere, è possibile usare il portale di Azure, l'API REST del provider di risorse Azure Cosmos DB, l'interfaccia della riga di comando di Azure o PowerShell per il piano di controllo non supportato.

Tipo di dati Boolean

Mentre il linguaggio Python usa "True" e "False" per i tipi booleani, Cosmos DB accetta solo "true" e "false". In altre parole, il linguaggio Python usa valori booleani con la prima lettera maiuscola e tutte le altre lettere minuscole, mentre Cosmos DB e il relativo linguaggio SQL usano solo lettere minuscole per gli stessi valori booleani. Come affrontare questa sfida?

I documenti JSON creati con Python devono usare "True" e "False", per passare la convalida del linguaggio. L'SDK lo convertirà in "true" e "false" per l'utente. Ciò significa che "true" e "false" è ciò che verrà archiviato in Cosmos DB.
Se si recuperano i documenti con la Esplora dati del portale di Cosmos DB, verrà visualizzato "true" e "false".
Se si recuperano i documenti con questo SDK Python, i valori "true" e "false" verranno convertiti automaticamente in "True" e "False".

Sottoelementi della clausola SQL query x FROM

Questo SDK usa il metodo query_items per inviare query SQL ad Azure Cosmos DB.

Il linguaggio SQL di Cosmos DB consente di ottenere elementi secondari usando la clausola FROM, per ridurre l'origine a un subset più piccolo. Ad esempio, è possibile usare select * from Families.children anziché select * from Families. Ma si noti che:

Per le query SQL usando il query_items metodo, questo SDK richiede di specificare o partition_key usare il enable_cross_partition_query flag.
Se si ottengono elementi secondari e si specifica partition_key, assicurarsi che la chiave di partizione sia inclusa negli elementi secondari, che non è true per la maggior parte dei casi.

Numero massimo di elementi

Si tratta di un parametro del metodo query_items, un intero che indica il numero massimo di elementi da restituire per pagina. Il None valore può essere specificato per consentire al servizio di determinare il numero ottimale di elementi. Si tratta del valore di configurazione consigliato e del comportamento predefinito di questo SDK quando non è impostato.

Esempio

Le sezioni seguenti contengono diversi frammenti di codice relativi ad alcune delle attività più comuni di Cosmos DB:

Creare un database
Creare un contenitore
Creare un contenitore abilitato per l'archivio analitico
Ottenere un contenitore esistente
Inserire dati
Eliminare i dati
Eseguire query sul database
Ottenere le proprietà del database
Ottenere la velocità effettiva del database e del contenitore
Modificare le proprietà del contenitore
Uso del client asincrono

Creazione di un database

Dopo aver autenticato CosmosClient, è possibile usare qualsiasi risorsa nell'account. Il frammento di codice seguente crea un database API SQL, ovvero il valore predefinito quando non viene specificata alcuna API quando viene richiamata 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)

Creare un contenitore

In questo esempio viene creato un contenitore con impostazioni predefinite. Se un contenitore con lo stesso nome esiste già nel database (generando un 409 Conflict errore), il contenitore esistente viene ottenuto invece.

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

Creare un contenitore abilitato per l'archivio analitico

In questo esempio viene creato un contenitore con Archivio analitico abilitato, per report, BI, intelligenza artificiale e Analisi avanzata con Azure Synapse Collegamento.

Le opzioni per analytical_storage_ttl sono:

0 o Null o non informato: non abilitato.
-1: i dati verranno archiviati infinitamente.
Qualsiasi altro numero: il ttl effettivo, in secondi.

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

I frammenti precedenti gestiscono anche l'eccezione CosmosHttpResponseError se la creazione del contenitore non è riuscita. Per altre informazioni sulla gestione degli errori e sulla risoluzione dei problemi, vedere la sezione .

Ottenere un contenitore esistente

Recuperare un contenitore esistente dal database:

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)

Inserire i dati

Per inserire elementi in un contenitore, passare un dizionario contenente i dati a ContainerProxy.upsert_item. Ogni elemento aggiunto a un contenitore deve includere una chiave con un id valore che identifica in modo univoco l'elemento all'interno del contenitore.

In questo esempio vengono inseriti diversi elementi nel contenitore, ognuno con un oggetto univoco 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)
        }
    )

Eliminare i dati

Per eliminare elementi da un contenitore, usare ContainerProxy.delete_item. L'API SQL in Cosmos DB non supporta l'istruzione 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 si usa la raccolta partizionata, il valore del partitionKey codice di esempio precedente deve essere impostato sul valore della chiave di partizione per questo particolare elemento, non sul nome della colonna della chiave di partizione nella raccolta. Questo valore è true per le letture e le eliminazioni dei punti.

Eseguire query sul database

Un database API SQL di Cosmos DB supporta l'esecuzione di query sugli elementi in un contenitore con ContainerProxy.query_items usando la sintassi simile a SQL.

Questo esempio esegue una query su un contenitore per gli elementi con una specifica 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: anche se è possibile specificare qualsiasi valore per il nome del contenitore nella clausola, è consigliabile usare il nome del FROM contenitore per la coerenza.

Eseguire query con parametri passando un dizionario contenente i parametri e i relativi valori per 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))

Per altre informazioni sull'esecuzione di query su database Cosmos DB tramite l'API SQL, vedere Eseguire query SQL sui dati di Azure Cosmos DB.

Ottenere le proprietà del database

Ottenere e visualizzare le proprietà di un database:

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

Ottenere la velocità effettiva del database e del contenitore

Ottenere e visualizzare i valori di velocità effettiva di un database e di un contenitore con velocità effettiva dedicata:

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

Modificare le proprietà del contenitore

È possibile modificare alcune proprietà di un contenitore esistente. In questo esempio viene impostata la durata predefinita (TTL) per gli elementi nel contenitore su 10 secondi:

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

Per altre informazioni sul TTL, vedere Time to Live for Azure Cosmos DB data (Time to Live for Azure Cosmos DB data).

Uso del client asincrono

Il client cosmos asincrono è un client separato che cerca e funziona in modo simile al client sincrono esistente. Tuttavia, il client asincrono deve essere importato separatamente e i relativi metodi devono essere usati con le parole chiave async/await. Il client asincrono deve essere inizializzato e chiuso dopo l'utilizzo, che può essere eseguito manualmente o con l'uso di una gestione contesto. Nell'esempio seguente viene illustrato come eseguire manualmente questa operazione.

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

Invece di aprire e chiudere manualmente il client, è consigliabile usare le async with parole chiave. In questo modo viene creato un gestore di contesto che inizializzerà e in seguito chiuderà il client dopo l'uscita dall'istruzione. L'esempio seguente illustra come eseguire questa operazione.

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

Query con il client asincrono

A differenza del client sincrono, il client asincrono non ha un enable_cross_partition flag nella richiesta. Le query senza un valore di chiave di partizione specificata tenteranno di eseguire una query tra partizioni per impostazione predefinita.

I risultati delle query possono essere iterazione, ma l'output non elaborato della query restituisce un iteratore asincrono. Ciò significa che ogni oggetto dall'iteratore è un oggetto attendebile e non contiene ancora il risultato della query true. Per ottenere i risultati della query, è possibile usare un ciclo asincrono, che attende ogni risultato durante l'iterazione dell'oggetto oppure attendere manualmente ogni risultato di query durante l'iteratore asincrono.

Poiché i risultati della query sono un iteratore asincrono, non possono essere caricati direttamente in elenchi; Se invece è necessario creare elenchi dai risultati, usare un asincrono per la comprensione dell'elenco o dell'elenco di Python per popolare un elenco:

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 della cache integrata

Una cache integrata è una cache in memoria che consente di garantire costi gestibili e bassa latenza man mano che il volume delle richieste aumenta. La cache integrata include due parti: una cache degli elementi per le letture del punto e una cache di query per le query. Il frammento di codice seguente illustra come usare questa funzionalità con i metodi di lettura punto e cache delle query.

Il vantaggio dell'uso di questo è che il punto legge e le query che colpiscono la cache integrata non useranno alcuna unità UR. Ciò significa che si avrà un costo molto inferiore per operazione rispetto alle letture dal back-end.

Come configurare la cache integrata di Azure Cosmos DB (anteprima)

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)

Per altre informazioni su Cache integrata, vedere Cache integrata di Azure Cosmos DB - Panoramica.

Risoluzione dei problemi

Generale

Quando si interagisce con Cosmos DB usando Python SDK, le eccezioni restituite dal servizio corrispondono agli stessi codici di stato HTTP restituiti per le richieste api REST:

Codici di stato HTTP per Azure Cosmos DB

Ad esempio, se si tenta di creare un contenitore usando un ID (nome) già usato nel database Cosmos DB, viene restituito un 409 errore che indica il conflitto. Nel frammento di codice seguente, l'errore viene gestito normalmente rilevando l'eccezione e visualizzando informazioni aggiuntive sull'errore.

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

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

La registrazione dettagliata del livello DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non attendibili, può essere abilitata in un client con l'argomento 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)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:

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

In alternativa, è possibile registrare usando CosmosHttpLoggingPolicy, che si estende dal core httpLoggingPolicy di azure, passando il logger all'argomento logger . Per impostazione predefinita, userà il comportamento di HttpLoggingPolicy. Il passaggio dell'argomento enable_diagnostics_logging abiliterà CosmosHttpLoggingPolicy e avrà informazioni aggiuntive nella risposta pertinente al debug dei problemi di 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)

Analogamente, la registrazione può essere abilitata per una singola operazione passando un logger alla richiesta singolare. Tuttavia, se si desidera usare CosmosHttpLoggingPolicy per ottenere informazioni aggiuntive, l'argomento enable_diagnostics_logging deve essere passato al costruttore client.

# 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

Azure Core offre la possibilità per gli SDK Python di usare OpenTelemetry con essi. Gli unici pacchetti che devono essere installati per usare questa funzionalità sono i seguenti:

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

Per altre informazioni su questo argomento, è consigliabile esaminare questo documento da Azure Core che descrive come configurarlo. È stato aggiunto anche un file di esempio per mostrare come può essere usato con l'SDK. Questo funziona allo stesso modo indipendentemente dal client Cosmos in uso.

Passaggi successivi

Per una documentazione più completa sul servizio Cosmos DB, vedere la documentazione di Azure Cosmos DB su docs.microsoft.com.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Condividi tramite