Disclaimer

Ondersteuning voor Azure SDK Python-pakketten voor Python 2.7 is beëindigd op 1 januari 2022. Voor meer informatie en vragen raadpleegt u https://github.com/Azure/azure-sdk-for-python/issues/20691

Azure Cosmos DB SQL API-clientbibliotheek voor Python - versie 4.5.1

Azure Cosmos DB is een wereldwijd gedistribueerde databaseservice met meerdere modellen waarmee databases voor document-, sleutelwaarde-, kolom- en grafiekdatabases worden ondersteund.

Gebruik de Azure Cosmos DB SQL API SDK voor Python voor het beheren van databases en de JSON-documenten die ze bevatten in deze NoSQL-databaseservice. Mogelijkheden op hoog niveau zijn:

• Cosmos DB-databases maken en de instellingen wijzigen
• Containers maken en wijzigen voor het opslaan van verzamelingen JSON-documenten
• De items (JSON-documenten) in uw containers maken, lezen, bijwerken en verwijderen
• Query's uitvoeren op de documenten in uw database met behulp van SQL-achtige syntaxis

SDK-broncode | Pakket (PyPI) | Pakket (Conda) | API-referentiedocumentatie | Productdocumentatie | Monsters

Deze SDK wordt gebruikt voor de SQL-API. Voor alle andere API's raadpleegt u de Documentatie van Azure Cosmos DB om de beste SDK voor uw project te evalueren.

Aan de slag

Belangrijke update voor ondersteuning voor Python 2.x

Nieuwe releases van deze SDK bieden vanaf 1 januari 2022 geen ondersteuning voor Python 2.x. Raadpleeg de CHANGELOG voor meer informatie.

Vereisten

• Azure-abonnement: maak een gratis account
• Azure Cosmos DB-account - SQL-API
• Python 3.6+

Als u een Cosmos DB SQL API-account nodig hebt, kunt u er een maken met deze Azure CLI-opdracht :

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

Het pakket installeren

pip install azure-cosmos

Een virtuele omgeving configureren (optioneel)

Hoewel dit niet is vereist, kunt u met een virtuele omgeving uw basissysteem en Azure SDK-omgevingen van elkaar geïsoleerd houden. Voer de volgende opdrachten uit om te configureren en voer vervolgens een virtuele omgeving in met venv:

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

De client verifiëren

Interactie met Cosmos DB begint met een exemplaar van de cosmosClient-klasse . U hebt een account, de bijbehorende URI en een van de accountsleutels nodig om het clientobject te instantiëren.

Gebruik het onderstaande Azure CLI-fragment om twee omgevingsvariabelen te vullen met de URI van het databaseaccount en de primaire hoofdsleutel (u vindt deze waarden ook in de Azure Portal). Het codefragment is geformatteerd voor de Bash-shell.

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)

De client maken

Nadat u de ACCOUNT_URI omgevingsvariabelen en ACCOUNT_KEY hebt ingevuld, kunt u de CosmosClient maken.

from azure.cosmos import CosmosClient

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

Microsoft Azure Active Directory-verificatie

U kunt ook een client verifiëren met behulp van de AAD-referenties van uw service-principal en het Azure-identiteitspakket. U kunt de referentiegegevens rechtstreeks doorgeven aan ClientSecretCredential of de DefaultAzureCredential gebruiken:

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)

Zorg er altijd voor dat de beheerde identiteit die u gebruikt voor AAD-verificatie machtigingen heeft readMetadata .
Meer informatie over het instellen van AAD-verificatie: RBAC instellen voor AAD-verificatie
Meer informatie over toegestane bewerkingen voor AAD-geverifieerde clients: RBAC-machtigingsmodel

Belangrijkste concepten

Nadat u een CosmosClient hebt geïnitialiseerd, kunt u werken met de primaire resourcetypen in Cosmos DB:

• Database: een Cosmos DB-account kan meerdere databases bevatten. Wanneer u een database maakt, geeft u de API op die u wilt gebruiken bij de interactie met de bijbehorende documenten: SQL, MongoDB, Gremlin, Cassandra of Azure Table. Gebruik het object DatabaseProxy om de containers te beheren.

• Container: een container is een verzameling JSON-documenten. U kunt items in een container maken (invoegen), lezen, bijwerken en verwijderen met behulp van methoden voor het object ContainerProxy .

• Item: Een item is de woordenlijstachtige weergave van een JSON-document dat is opgeslagen in een container. Elk item dat u aan een container toevoegt, moet een id sleutel bevatten met een waarde die het item in de container uniek identificeert.

Zie Werken met Azure Cosmos-databases, -containers en -items voor meer informatie over deze resources.

Gebruik van enable_cross_partition_query

Het trefwoordargument enable_cross_partition_query accepteert twee opties: None (standaard) of True.

Opmerking over het gebruik van query's op id

Wanneer u query's gebruikt die items zoeken op basis van een id-waarde , moet u er altijd voor zorgen dat u een variabele van het tekenreekstype doorgeeft. Azure Cosmos DB staat alleen tekenreeks-id-waarden toe en als u een ander gegevenstype gebruikt, retourneert deze SDK geen resultaten en geen foutberichten.

Opmerking over clientconsistentieniveaus

Vanaf releaseversie 4.3.0b3 gebruikt de client het standaardniveau van het databaseaccount als een gebruiker geen expliciet consistentieniveau doorgeeft aan de clientinitialisatie. Voorheen werd de standaardwaarde ingesteld op Session consistentie. Als u dit om een of andere reden wilt blijven doen, kunt u de initialisatie van de client wijzigen door de expliciete parameter hiervoor op te nemen, zoals wordt weergegeven:

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

Beperkingen

De onderstaande functies worden momenteel niet ondersteund. Raadpleeg de sectie Tijdelijke oplossingen hieronder voor alternatieve opties.

Beperkingen van gegevensvlak:

• Groeperen op-query's
• Query's met COUNT uit een DISTINCT-subquery: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Bulk-/transactionele batchverwerking
• Toegang tot directe TCP-modus
• Ondersteuning voor vervolgtoken voor statistische query's tussen partities, zoals sorteren, tellen en uniek. Streambare query's zoals SELECT * FROM WHEREondersteuning voor vervolgtokens.
• Wijzigingenfeed: Processor
• Wijzigingenfeed: sleutelwaarden voor meerdere partities lezen
• Wijzigingenfeed: specifieke tijd lezen
• Wijzigingenfeed: lezen vanaf het begin
• Wijzigingenfeed: Pull-model
• ORDER BY voor meerdere partities voor gemengde typen
• Diagnostische gegevens inschakelen voor methoden van het asynchrone querytype

Beperkingen van besturingsvlak:

• Metrische gegevens van CollectionSizeUsage, DatabaseUsage en DocumentUsage ophalen
• Georuimtelijke index maken
• De verbindingsreeks ophalen
• De minimale RU/s van een container ophalen

Tijdelijke oplossingen

Tijdelijke oplossing voor beperking van bulkverwerking

Als u python-SDK wilt gebruiken om bulksgewijs in te voegen in Cosmos DB, kunt u het beste opgeslagen procedures gebruiken om meerdere items met dezelfde partitiesleutel te schrijven.

Tijdelijke oplossing voor beperkingen van besturingsvlak

Normaal gesproken kunt u Azure Portal, Azure Cosmos DB Resource Provider REST API, Azure CLI of PowerShell gebruiken voor de niet-ondersteunde beperkingen van het besturingsvlak.

Booleaanse gegevenstype

Hoewel de Python-taal 'True' en 'False' gebruikt voor booleaanse typen, accepteert Cosmos DB alleen 'true' en 'false'. Met andere woorden, de Python-taal gebruikt Booleaanse waarden met de eerste hoofdletter en alle andere kleine letters, terwijl Cosmos DB en de SQL-taal alleen kleine letters gebruiken voor dezelfde Booleaanse waarden. Hoe ga je met deze uitdaging om?

• Uw JSON-documenten die met Python zijn gemaakt, moeten 'True' en 'False' gebruiken om de taalvalidatie te kunnen doorstaan. De SDK converteert deze voor u naar 'true' en 'false'. Dit betekent dat 'true' en 'false' worden opgeslagen in Cosmos DB.
• Als u deze documenten ophaalt met de Data Explorer van de Cosmos DB-portal, ziet u 'true' en 'false'.
• Als u deze documenten ophaalt met deze Python SDK, worden de waarden 'true' en 'false' automatisch geconverteerd naar 'True' en 'False'.

SQL Query's x FROM-componentsubitems

Deze SDK gebruikt de methode query_items om SQL-query's te verzenden naar Azure Cosmos DB.

Met de SQL-taal van Cosmos DB kunt u subitems ophalen met behulp van de FROM-component om de bron te beperken tot een kleinere subset. U kunt bijvoorbeeld gebruiken select * from Families.children in plaats van select * from Families. Maar houd er rekening mee dat:

• Voor SQL-query's die de query_items methode gebruiken, vereist deze SDK dat u de partition_key of de enable_cross_partition_query vlag opgeeft.
• Als u subitems krijgt en de partition_keyopgeeft, moet u ervoor zorgen dat uw partitiesleutel is opgenomen in de subitems. Dit geldt niet voor de meeste gevallen.

Maximumaantal items

Dit is een parameter van de methode query_items, een geheel getal dat het maximum aantal items aangeeft dat per pagina moet worden geretourneerd. De None waarde kan worden opgegeven om de service het optimale aantal items te laten bepalen. Dit is de aanbevolen configuratiewaarde en het standaardgedrag van deze SDK wanneer deze niet is ingesteld.

Voorbeelden

De volgende secties bevatten verschillende codefragmenten die betrekking hebben op enkele van de meest voorkomende Cosmos DB-taken, waaronder:

• Een database maken
• Een container maken
• Een container met analytische opslag maken
• Een bestaande container ophalen
• Gegevens invoegen
• Gegevens verwijderen
• Query's uitvoeren op de database
• Database-eigenschappen ophalen
• Doorvoer van databases en containers ophalen
• Containereigenschappen wijzigen
• De asynchrone client gebruiken

Een database maken

Nadat u uw CosmosClient hebt geverifieerd, kunt u met elke resource in het account werken. Met het onderstaande codefragment wordt een SQL API-database gemaakt. Dit is de standaarddatabase wanneer er geen API wordt opgegeven wanneer create_database wordt aangeroepen.

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)

Een container maken

In dit voorbeeld wordt een container met standaardinstellingen gemaakt. Als er al een container met dezelfde naam in de database bestaat (waardoor een 409 Conflict fout wordt gegenereerd), wordt in plaats daarvan de bestaande container verkregen.

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

Een container met analytische opslag maken

In dit voorbeeld wordt een container gemaakt met analytische opslag ingeschakeld, voor rapportage, BI, AI en Geavanceerde analyse met Azure Synapse Link.

De opties voor analytical_storage_ttl zijn:

• 0 of Null of niet geïnformeerd: niet ingeschakeld.
• -1: De gegevens worden oneindig opgeslagen.
• Een ander getal: de werkelijke ttl, in seconden.

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

De voorgaande fragmenten verwerken ook de CosmosHttpResponseError-uitzondering als het maken van de container is mislukt. Zie de sectie voor meer informatie over foutafhandeling en probleemoplossing.

Een bestaande container ophalen

Een bestaande container ophalen uit de 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)

Gegevens invoegen

Als u items in een container wilt invoegen, geeft u een woordenlijst met uw gegevens door aan ContainerProxy.upsert_item. Elk item dat u aan een container toevoegt, moet een id sleutel bevatten met een waarde die het item in de container uniek identificeert.

In dit voorbeeld worden verschillende items in de container ingevoegd, elk met een unieke 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)
        }
    )

Gegevens verwijderen

Gebruik ContainerProxy.delete_item om items uit een container te verwijderen. De SQL-API in Cosmos DB biedt geen ondersteuning voor de SQL-instructie 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')

OPMERKING: Als u gepartitioneerde verzameling gebruikt, moet de waarde van de partitionKey in de bovenstaande voorbeeldcode worden ingesteld op de waarde van de partitiesleutel voor dit specifieke item, niet op de naam van de kolom partitiesleutel in uw verzameling. Dit geldt voor zowel puntlees- als verwijderingen.

Een query uitvoeren op de database

Een Cosmos DB SQL API-database ondersteunt het uitvoeren van query's op de items in een container met ContainerProxy.query_items met behulp van SQL-achtige syntaxis.

In dit voorbeeld wordt een query uitgevoerd op een container voor items met een specifieke 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))

OPMERKING: Hoewel u elke waarde voor de containernaam in de FROM component kunt opgeven, raden we u aan de containernaam te gebruiken voor consistentie.

Voer geparameteriseerde query's uit door een woordenlijst met de parameters en hun waarden door te geven aan 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))

Zie Query's uitvoeren op Azure Cosmos DB-gegevens met SQL-query's voor meer informatie over het uitvoeren van query's op Cosmos DB-databases met behulp van de SQL-API.

Database-eigenschappen ophalen

De eigenschappen van een database ophalen en weergeven:

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

Doorvoer van databases en containers ophalen

De doorvoerwaarden van een database en van een container met toegewezen doorvoer ophalen en weergeven:

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

Containereigenschappen wijzigen

Bepaalde eigenschappen van een bestaande container kunnen worden gewijzigd. In dit voorbeeld wordt de standaard TTL (Time to Live) voor items in de container ingesteld op 10 seconden:

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

Zie Time to Live voor Azure Cosmos DB-gegevens voor meer informatie over TTL.

De asynchrone client gebruiken

De asynchrone cosmos-client is een afzonderlijke client die er op een vergelijkbare manier uitziet en werkt als de bestaande synchrone client. De asynchrone client moet echter afzonderlijk worden geïmporteerd en de bijbehorende methoden moeten worden gebruikt met de trefwoorden async/await. De Async-client moet worden geïnitialiseerd en gesloten na gebruik, wat handmatig of met behulp van een contextbeheer kan worden gedaan. In het onderstaande voorbeeld ziet u hoe u dit handmatig doet.

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

In plaats van de client handmatig te openen en te sluiten, wordt het ten zeerste aanbevolen om de async with trefwoorden te gebruiken. Hiermee maakt u een contextbeheerder die de client initialiseert en later sluit wanneer u de instructie niet meer hebt. In het onderstaande voorbeeld ziet u hoe u dit doet.

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's met de asynchrone client

In tegenstelling tot de synchrone client heeft enable_cross_partition de asynchrone client geen vlag in de aanvraag. Query's zonder een opgegeven partitiesleutelwaarde proberen standaard een partitieoverschrijdende query uit te voeren.

Queryresultaten kunnen worden gecureerd, maar de onbewerkte uitvoer van de query retourneert een asynchrone iterator. Dit betekent dat elk object van de iterator een wachtbaar object is en nog niet het werkelijke queryresultaat bevat. Als u de queryresultaten wilt verkrijgen, kunt u een asynchrone voor-lus gebruiken, die wacht op elk resultaat wanneer u het object herhaald, of handmatig wachten op elk queryresultaat wanneer u de asynchrone iterator doorloopt.

Omdat de queryresultaten een asynchrone iterator zijn, kunnen ze niet rechtstreeks in lijsten worden gecast; Als u in plaats daarvan lijsten wilt maken van uw resultaten, gebruikt u een asynchrone lus of python's lijstbegrip om een lijst te vullen:

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

Geïntegreerde cache gebruiken

Een geïntegreerde cache is een cache in het geheugen waarmee u kunt zorgen voor beheersbare kosten en lage latentie naarmate uw aanvraagvolume groeit. De geïntegreerde cache bestaat uit twee delen: een itemcache voor puntleesbewerkingen en een querycache voor query's. In het onderstaande codefragment ziet u hoe u deze functie kunt gebruiken met de cachemethoden voor puntlezen en query's.

Het voordeel van het gebruik hiervan is dat het punt leest en query's die de geïntegreerde cache raken, geen RU's gebruiken. Dit betekent dat de kosten per bewerking veel lager zijn dan leesbewerkingen uit de back-end.

De geïntegreerde Azure Cosmos DB-cache configureren (preview)

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)

Zie Geïntegreerde azure Cosmos DB-cache - Overzicht voor meer informatie over geïntegreerde cache.

Problemen oplossen

Algemeen

Wanneer u communiceert met Cosmos DB met behulp van de Python SDK, komen uitzonderingen die door de service worden geretourneerd, overeen met dezelfde HTTP-statuscodes die worden geretourneerd voor REST API-aanvragen:

HTTP-statuscodes voor Azure Cosmos DB

Als u bijvoorbeeld een container probeert te maken met behulp van een id (naam) die al in gebruik is in uw Cosmos DB-database, wordt er een 409 fout geretourneerd die het conflict aangeeft. In het volgende codefragment wordt de fout mooi verwerkt door de uitzondering vast te leggen en aanvullende informatie over de fout weer te geven.

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

Logboekregistratie

Deze bibliotheek gebruikt de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-geredigeerde headers, kan worden ingeschakeld op een client met het logging_enable argument:

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)

Op dezelfde manier kan logging_enable logboekregistratie voor één bewerking inschakelen, zelfs wanneer dit niet is ingeschakeld voor de client:

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

U kunt ook logboekregistratie uitvoeren met behulp van CosmosHttpLoggingPolicy, dat zich uitstrekt van de Azure-kern HttpLoggingPolicy, door uw logboekregistratie door te geven aan het logger argument. Standaard wordt het gedrag van HttpLoggingPolicy gebruikt. Als u het enable_diagnostics_logging argument doorgeeft, wordt CosmosHttpLoggingPolicy ingeschakeld en krijgt u aanvullende informatie in het antwoord dat relevant is voor het opsporen van problemen met 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)

Op dezelfde manier kan logboekregistratie worden ingeschakeld voor één bewerking door een logboekregistratie door te geven aan de enkelvoudige aanvraag. Als u echter cosmosHttpLoggingPolicy wilt gebruiken om aanvullende informatie te verkrijgen, moet het enable_diagnostics_logging argument worden doorgegeven aan de clientconstructor.

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

Telemetrie

Azure Core biedt de mogelijkheid voor onze Python-SDK's om OpenTelemetry te gebruiken. De enige pakketten die moeten worden geïnstalleerd om deze functionaliteit te gebruiken, zijn de volgende:

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

Voor meer informatie hierover raden we u aan dit document van Azure Core te bekijken waarin wordt beschreven hoe u dit kunt instellen. We hebben ook een voorbeeldbestand toegevoegd om te laten zien hoe het kan worden gebruikt met onze SDK. Dit werkt op dezelfde manier, ongeacht de Cosmos-client die u gebruikt.

Volgende stappen

Zie de Azure Cosmos DB-documentatie over docs.microsoft.com voor uitgebreidere documentatie over de Cosmos DB-service .

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.