Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 upphörde den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691

Azure Cosmos DB SQL API-klientbibliotek för Python – version 4.5.1

Azure Cosmos DB är en globalt distribuerad databastjänst för flera modeller som har stöd för dokument, nyckelvärden, breda kolumner och grafdatabaser.

Använd Azure Cosmos DB SQL API SDK för Python för att hantera databaser och JSON-dokument som de innehåller i den här NoSQL-databastjänsten. Funktioner på hög nivå är:

• Skapa Cosmos DB-databaser och ändra deras inställningar
• Skapa och ändra containrar för att lagra samlingar av JSON-dokument
• Skapa, läsa, uppdatera och ta bort objekten (JSON-dokument) i dina containrar
• Köra frågor mot dokumenten i databasen med sql-liknande syntax

SDK-källkod | Paket (PyPI) | Paket (Conda) | API-referensdokumentation | Produktdokumentation | Prover

Denna SDK används för SQL-API:et. För alla andra API:er kan du läsa Azure Cosmos DB-dokumentationen för att utvärdera det bästa SDK:t för ditt projekt.

Komma igång

Viktig uppdatering av Python 2.x-stöd

Nya versioner av denna SDK stöder inte Python 2.x från och med 1 januari 2022. Mer information finns i CHANGELOG .

Förutsättningar

• Azure-prenumeration – Skapa ett kostnadsfritt konto
• Azure Cosmos DB-konto – SQL API
• Python 3.6+

Om du behöver ett Cosmos DB SQL API-konto kan du skapa ett med det här Azure CLI-kommandot :

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

Installera paketet

pip install azure-cosmos

Konfigurera en virtuell miljö (valfritt)

Även om det inte krävs, du kan behålla dina grundläggande system- och Azure SDK-miljöer isolerade från varandra om du använder en virtuell miljö. Kör följande kommandon för att konfigurera och ange sedan en virtuell miljö med venv:

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

Autentisera klienten

Interaktionen med Cosmos DB börjar med en instans av klassen CosmosClient . Du behöver ett konto, dess URI och en av dess kontonycklar för att instansiera klientobjektet.

Använd Azure CLI-kodfragmentet nedan för att fylla i två miljövariabler med databaskontots URI och dess primära huvudnyckel (du hittar även dessa värden i Azure Portal). Kodfragmentet är formaterat för Bash-gränssnittet.

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)

Skapa klienten

När du har fyllt i ACCOUNT_URI miljövariablerna och ACCOUNT_KEY kan du skapa CosmosClient.

from azure.cosmos import CosmosClient

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

AAD-autentisering

Du kan också autentisera en klient med tjänstens huvudnamns AAD-autentiseringsuppgifter och Azure-identitetspaketet. Du kan skicka information om autentiseringsuppgifter direkt till ClientSecretCredential eller använda 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)

Se alltid till att den hanterade identitet som du använder för AAD-autentisering har readMetadata behörigheter.
Mer information om hur du konfigurerar AAD-autentisering: Konfigurera RBAC för AAD-autentisering
Mer information om tillåtna åtgärder för AAD-autentiserade klienter: RBAC-behörighetsmodell

Viktiga begrepp

När du har initierat en CosmosClient kan du interagera med de primära resurstyperna i Cosmos DB:

• Databas: Ett Cosmos DB-konto kan innehålla flera databaser. När du skapar en databas anger du det API som du vill använda när du interagerar med dess dokument: SQL, MongoDB, Gremlin, Cassandra eller Azure Table. Använd DatabaseProxy-objektet för att hantera dess containrar.

• Container: En container är en samling JSON-dokument. Du skapar (infogar), läser, uppdaterar och tar bort objekt i en container med hjälp av metoder i ContainerProxy-objektet .

• Objekt: Ett objekt är en ordlisteliknande representation av ett JSON-dokument som lagras i en container. Varje objekt som du lägger till i en container måste innehålla en id nyckel med ett värde som unikt identifierar objektet i containern.

Mer information om dessa resurser finns i Arbeta med Azure Cosmos-databaser, containrar och objekt.

Så här använder du enable_cross_partition_query

Nyckelordsargumentet enable_cross_partition_query accepterar 2 alternativ: None (standard) eller True.

Observera att du använder frågor efter ID

När du använder frågor som försöker hitta objekt baserat på ett ID-värde kontrollerar du alltid att du skickar in en strängtypvariabel. Azure Cosmos DB tillåter endast sträng-ID-värden och om du använder någon annan datatyp returnerar denna SDK inga resultat och inga felmeddelanden.

Anmärkning om klientkonsekvensnivåer

Från och med version 4.3.0b3 använder klienten standardnivån för databaskontot om en användare inte skickar en explicit konsekvensnivå till klientinitiering. Tidigare angavs standardinställningen konsekvens Session . Om du av någon anledning vill fortsätta göra detta kan du ändra klientinitiering till att inkludera den explicita parametern för den här typen som visas:

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

Begränsningar

För närvarande stöds inte funktionerna nedan. Alternativ finns i avsnittet Lösningar nedan.

Begränsningar för dataplanet:

• Gruppera efter frågor
• Frågor med COUNT från en DISTINKT underfråga: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Mass-/transaktionell batchbearbetning
• Direkt åtkomst till TCP-läge
• Stöd för fortsättningstoken för aggregerade frågor mellan partitioner som sortering, inventering och distinkta. Strömmande frågor som SELECT * FROM WHEREstöder fortsättningstoken.
• Ändringsflöde: Processor
• Ändringsflöde: Läsa nyckelvärden för flera partitioner
• Ändringsflöde: Läs specifik tid
• Ändringsflöde: Läsa från början
• Ändringsflöde: Pull-modell
• ORDER BY mellan partitioner för blandade typer
• Aktivera diagnostik för asynkrona metoder av frågetyp

Begränsningar för kontrollplan:

• Hämta måtten CollectionSizeUsage, DatabaseUsage och DocumentUsage
• Skapa geospatialt index
• Hämta anslutningssträngen
• Hämta minsta RU/s för en container

Provisoriska lösningar

Lösning för begränsning av massbearbetning

Om du vill använda Python SDK för att utföra massinfogningar i Cosmos DB är det bästa alternativet att använda lagrade procedurer för att skriva flera objekt med samma partitionsnyckel.

Lösning för kontrollplansbegränsningar

Vanligtvis kan du använda Azure-portalen, REST-API:et för Azure Cosmos DB-resursprovidern, Azure CLI eller PowerShell för begränsningar som inte stöds av kontrollplanet.

Boolesk datatyp

Python-språket använder "True" och "False" för booleska typer, men Cosmos DB accepterar endast "true" och "false". Med andra ord använder Python-språket booleska värden med den första versaler och alla andra gemener, medan Cosmos DB och dess SQL-språk endast använder gemener för samma booleska värden. Hur hanterar jag den här utmaningen?

• Dina JSON-dokument som skapats med Python måste använda "True" och "False" för att klara språkverifieringen. SDK konverterar den till "true" och "false" åt dig. Det innebär att "true" och "false" är det som kommer att lagras i Cosmos DB.
• Om du hämtar dessa dokument med Cosmos DB-portalens Data Explorer visas "true" och "false".
• Om du hämtar dessa dokument med python-SDK:t konverteras värdena "true" och "false" automatiskt till "True" och "False".

SQL-frågor x FROM-satsunderobjekt

Denna SDK använder metoden query_items för att skicka SQL-frågor till Azure Cosmos DB.

Med Cosmos DB SQL-språket kan du hämta underobjekt med hjälp av FROM-satsen för att minska källan till en mindre delmängd. Du kan till exempel använda select * from Families.children i stället för select * from Families. Observera dock att:

• För SQL-frågor som använder query_items metoden kräver denna SDK att du anger partition_key eller använder enable_cross_partition_query flaggan .
• Om du får underobjekt och anger partition_key, kontrollerar du att partitionsnyckeln ingår i underobjekten, vilket inte är sant i de flesta fall.

Maximalt antal objekt

Det här är en parameter för metoden query_items, ett heltal som anger det maximala antalet objekt som ska returneras per sida. Värdet None kan anges så att tjänsten kan fastställa det optimala antalet objekt. Detta är det rekommenderade konfigurationsvärdet och standardbeteendet för detta SDK när det inte har angetts.

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste Cosmos DB-uppgifterna, inklusive:

• Skapa en databas
• Skapa en container
• Skapa en container med aktiverat analysarkiv
• Hämta en befintlig container
• Infoga data
• Ta bort data
• Fråga databasen
• Hämta databasegenskaper
• Hämta dataflöden för databaser och containrar
• Ändra containeregenskaper
• Använda den asynkrona klienten

Skapa en databas

När du har autentiserat Din CosmosClient kan du arbeta med valfri resurs i kontot. Kodfragmentet nedan skapar en SQL API-databas, vilket är standard när inget API anges när create_database anropas.

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)

Skapa en container

I det här exemplet skapas en container med standardinställningar. Om det redan finns en container med samma namn i databasen (vilket genererar ett 409 Conflict fel) hämtas den befintliga containern i stället.

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

Skapa en container med aktiverat analysarkiv

I det här exemplet skapas en container med Analysarkiv aktiverat för rapportering, BI, AI och Avancerad analys med Azure Synapse Link.

Alternativen för analytical_storage_ttl är:

• 0 eller Null eller inte informerad: Inte aktiverat.
• -1: Data kommer att lagras oändligt.
• Valfritt annat tal: det faktiska ttl-värdet, i sekunder.

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

Föregående kodfragment hanterar även CosmosHttpResponseError-undantaget om det inte gick att skapa containern. Mer information om felhantering och felsökning finns i felsökningsavsnittet.

Hämta en befintlig container

Hämta en befintlig container från databasen:

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)

Infoga data

Om du vill infoga objekt i en container skickar du en ordlista som innehåller dina data till ContainerProxy.upsert_item. Varje objekt som du lägger till i en container måste innehålla en id nyckel med ett värde som unikt identifierar objektet i containern.

Det här exemplet infogar flera objekt i containern, var och en med en unik 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)
        }
    )

Ta bort data

Om du vill ta bort objekt från en container använder du ContainerProxy.delete_item. SQL-API:et i Cosmos DB stöder inte SQL-instruktionen 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')

Obs! Om du använder partitionerad samling ska värdet partitionKey för i exempelkoden ovan anges till värdet för partitionsnyckeln för det här specifika objektet, inte namnet på partitionsnyckelkolumnen i din samling. Detta gäller både punktläsningar och borttagningar.

Fråga databasen

En Cosmos DB SQL API-databas stöder frågor mot objekten i en container med ContainerProxy.query_items med hjälp av SQL-liknande syntax.

Det här exemplet frågar en container efter objekt med en specifik 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))

Obs! Även om du kan ange valfritt värde för containernamnet i FROM -satsen rekommenderar vi att du använder containernamnet för konsekvens.

Utför parametriserade frågor genom att skicka en ordlista som innehåller parametrarna och deras värden till 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))

Mer information om hur du kör frågor mot Cosmos DB-databaser med hjälp av SQL-API:et finns i Köra frågor mot Azure Cosmos DB-data med SQL-frågor.

Hämta databasegenskaper

Hämta och visa egenskaperna för en databas:

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

Hämta dataflöden för databaser och containrar

Hämta och visa dataflödesvärdena för en databas och för en container med dedikerat dataflöde:

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

Ändra containeregenskaper

Vissa egenskaper för en befintlig container kan ändras. I det här exemplet anges standardtid till live (TTL) för objekt i containern till 10 sekunder:

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

Mer information om TTL finns i Time to Live för Azure Cosmos DB-data.

Använda den asynkrona klienten

Den asynkrona cosmos-klienten är en separat klient som ser ut och fungerar på ett liknande sätt som den befintliga synkrona klienten. Asynkron klient måste dock importeras separat och dess metoder måste användas med nyckelorden async/await. Async-klienten måste initieras och stängas efter användning, vilket kan göras manuellt eller med hjälp av en kontexthanterare. Exemplet nedan visar hur du gör det manuellt.

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

I stället för att öppna och stänga klienten manuellt rekommenderar vi starkt att du använder nyckelorden async with . Detta skapar en kontexthanterare som initierar och senare stänger klienten när du är ute ur -instruktionen. Exemplet nedan visar hur du gör det.

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

Frågor med den asynkrona klienten

Till skillnad från den synkrona klienten har enable_cross_partition asynkron klient ingen flagga i begäran. Frågor utan ett angivet partitionsnyckelvärde försöker utföra en fråga mellan partitioner som standard.

Frågeresultat kan itereras, men frågans råutdata returnerar en asynkron iterator. Det innebär att varje objekt från iteratorn är ett inväntningsbart objekt och ännu inte innehåller det sanna frågeresultatet. För att hämta frågeresultatet kan du använda en asynkron for-loop som väntar på varje resultat när du itererar på objektet, eller väntar manuellt på varje frågeresultat när du itererar över den asynkrona iteratorn.

Eftersom frågeresultaten är en asynkron iterator kan de inte omvandlas direkt till listor. Om du i stället behöver skapa listor från dina resultat använder du en asynkron för loop eller Pythons listförståelse för att fylla i en 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()

Använda integrerad cache

En integrerad cache är en minnesintern cache som hjälper dig att säkerställa hanterbara kostnader och låg svarstid när begärandevolymen växer. Den integrerade cachen har två delar: en objektcache för punktläsningar och en frågecachen för frågor. Kodfragmentet nedan visar hur du använder den här funktionen med metoder för punktläsning och frågecache.

Fördelen med att använda detta är att punkten läser och frågor som träffar den integrerade cachen inte använder några RU:er. Det innebär att du får en mycket lägre kostnad per åtgärd än läsningar från serverdelen.

Så här konfigurerar du azure Cosmos DB-integrerad cache (förhandsversion)

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)

Mer information om integrerad cache finns i Integrerad cache i Azure Cosmos DB – Översikt.

Felsökning

Allmänt

När du interagerar med Cosmos DB med Hjälp av Python SDK motsvarar undantag som returneras av tjänsten samma HTTP-statuskoder som returneras för REST API-begäranden:

HTTP-statuskoder för Azure Cosmos DB

Om du till exempel försöker skapa en container med ett ID (namn) som redan används i Cosmos DB-databasen returneras ett 409 fel som anger konflikten. I följande kodfragment hanteras felet korrekt genom att fånga upp undantaget och visa ytterligare information om felet.

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

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med logging_enable argumentet :

import sys
import logging
from azure.cosmos import CosmosClient

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

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

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

logging_enable På samma sätt kan aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

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

Du kan också logga med hjälp av CosmosHttpLoggingPolicy, som sträcker sig från Azure Core HttpLoggingPolicy, genom att skicka in loggaren logger till argumentet . Som standard använder den beteendet från HttpLoggingPolicy. Om du skickar enable_diagnostics_logging argumentet aktiveras CosmosHttpLoggingPolicy och ytterligare information finns i svaret som är relevant för felsökning av Cosmos-problem.

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)

På samma sätt kan loggning aktiveras för en enda åtgärd genom att en loggare skickas till den enskilda begäran. Men om du vill använda CosmosHttpLoggingPolicy för att hämta ytterligare information enable_diagnostics_logging måste argumentet skickas i klientkonstruktorn.

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

Telemetri

Azure Core ger våra Python-SDK:er möjlighet att använda OpenTelemetry med dem. De enda paket som behöver installeras för att använda den här funktionen är följande:

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

För mer information om detta rekommenderar vi att du tar en titt på det här dokumentet från Azure Core som beskriver hur du konfigurerar det. Vi har också lagt till en exempelfil för att visa hur den kan användas med vår SDK. Detta fungerar på samma sätt oavsett vilken Cosmos-klient du använder.

Nästa steg

Mer omfattande dokumentation om Cosmos DB-tjänsten finns i Azure Cosmos DB-dokumentationen om docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.