Felelősséget kizáró nyilatkozat

Az Azure SDK Python-csomagok támogatása a Python 2.7-hez 2022. január 01-én véget ért. További információkért és kérdésekért lásd: https://github.com/Azure/azure-sdk-for-python/issues/20691

Azure Cosmos DB SQL API-ügyfélkódtár Pythonhoz – 4.5.1-es verzió

Az Azure Cosmos DB egy globálisan elosztott, többmodelles adatbázis-szolgáltatás, amely dokumentum és kulcs–érték típusú, valamint széles oszlopú és gráfadatbázisokat támogat.

A Pythonhoz készült Azure Cosmos DB SQL API SDK használatával kezelheti az ebben a NoSQL-adatbázisszolgáltatásban található adatbázisokat és JSON-dokumentumokat. A magas szintű képességek a következők:

• Cosmos DB-adatbázisok létrehozása és beállításaik módosítása
• Tárolók létrehozása és módosítása JSON-dokumentumok gyűjteményeinek tárolásához
• A tárolókban lévő elemek (JSON-dokumentumok) létrehozása, olvasása, frissítése és törlése
• Az adatbázis dokumentumainak lekérdezése SQL-szerű szintaxissal

SDK-forráskód | Csomag (PyPI) | Csomag (Conda) | API-referenciadokumentáció | Termékdokumentáció | Minták

Ezt az SDK-t az SQL API-hoz használjuk. Az összes többi API esetében tekintse meg az Azure Cosmos DB dokumentációját , és értékelje ki a projekthez legmegfelelőbb SDK-t.

Első lépések

Fontos frissítés a Python 2.x támogatásáról

Az SDK új kiadásai 2022. január 1-től nem támogatják a Python 2.x-et. További információért tekintse meg a CHANGELOG (VÁLTOZÁSNAPLÓ ) című témakört.

Előfeltételek

• Azure-előfizetés – Ingyenes fiók létrehozása
• Azure Cosmos DB-fiók – SQL API
• Python 3.6+

Ha Cosmos DB SQL API-fiókra van szüksége, létrehozhat egyet az Alábbi Azure CLI-paranccsal :

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

A csomag telepítése

pip install azure-cosmos

Virtuális környezet konfigurálása (nem kötelező)

Bár nem szükséges, az alaprendszert és az Azure SDK-környezeteket elkülönítheti egymástól, ha virtuális környezetet használ. Futtassa a következő parancsokat a venv virtuális környezetének konfigurálásához és megadásához:

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

Az ügyfél hitelesítése

A Cosmos DB-vel való interakció a CosmosClient osztály egy példányával kezdődik. Az ügyfélobjektum példányosításához szüksége lesz egy fiókra, annak URI-jára és egyik fiókkulcsára .

Az alábbi Azure CLI-kódrészlettel feltölthet két környezeti változót az adatbázisfiók URI-jával és elsődleges főkulcsával (ezeket az értékeket a Azure Portal is megtalálja). A kódrészlet a Bash-felülethez van formázva.

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)

Az ügyfél létrehozása

Miután kitöltötte a és ACCOUNT_KEY a ACCOUNT_URI környezeti változókat, létrehozhatja a CosmosClientet.

from azure.cosmos import CosmosClient

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

AAD-hitelesítés

Az ügyfél hitelesítéséhez használja a szolgáltatásnév AAD-hitelesítő adatait és az Azure-identitáscsomagot. A hitelesítő adatok közvetlenül átadhatók a ClientSecretCredentialnak, vagy használhatja a DefaultAzureCredential parancsot:

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)

Mindig győződjön meg arról, hogy az AAD-hitelesítéshez használt felügyelt identitás rendelkezik readMetadata engedélyekkel.
További információ az AAD-hitelesítés beállításáról: RBAC beállítása AAD-hitelesítéshez
További információ az AAD által hitelesített ügyfelek engedélyezett műveleteiről: RBAC-engedélymodell

Fő fogalmak

Miután inicializált egy CosmosClientet, használhatja a Cosmos DB elsődleges erőforrástípusait:

• Adatbázis: A Cosmos DB-fiókok több adatbázist is tartalmazhatnak. Adatbázis létrehozásakor meg kell adnia azt az API-t, amelyet használni szeretne a dokumentumaival való interakcióhoz: SQL, MongoDB, Gremlin, Cassandra vagy Azure Table. Használja a DatabaseProxy objektumot a tárolók kezeléséhez.

• Tároló: A tároló JSON-dokumentumok gyűjteménye. Elemeket hozhat létre (szúrhat be), olvashat, frissíthet és törölhet egy tárolóban a ContainerProxy objektum metódusainak használatával.

• Elem: Az elem egy tárolóban tárolt JSON-dokumentum szótárszerű ábrázolása. A tárolóhoz hozzáadott minden elemnek tartalmaznia kell egy id kulcsot egy olyan értékkel, amely egyedileg azonosítja az elemet a tárolóban.

További információ ezekről az erőforrásokról: Az Azure Cosmos-adatbázisok, -tárolók és -elemek használata.

Használat enable_cross_partition_query

A kulcsszó-argumentum enable_cross_partition_query 2 lehetőséget fogad el: None (alapértelmezett) vagy True.

Megjegyzés a lekérdezések azonosító alapján történő használatáról

Ha olyan lekérdezéseket használ, amelyek azonosítóérték alapján próbálnak elemeket keresni, mindig győződjön meg arról, hogy egy sztring típusú változót ad meg. Az Azure Cosmos DB csak sztringazonosító értékeket engedélyez, és ha bármilyen más adattípust használ, ez az SDK nem ad vissza eredményt, és nem kap hibaüzenetet.

Megjegyzés az ügyfélkonzisztencia szintjeiről

A 4.3.0b3-as kiadástól számítva, ha egy felhasználó nem ad át explicit konzisztenciaszintet az ügyfél inicializálásának, az ügyfél az adatbázisfiók alapértelmezett szintjét fogja használni. Korábban az alapértelmezett konzisztencia volt beállítva Session . Ha valamilyen okból továbbra is ezt szeretné tenni, módosíthatja az ügyfél inicializálását úgy, hogy tartalmazza az ehhez tartozó explicit paramétert az alábbi módon:

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

Korlátozások

Az alábbi funkciók jelenleg nem támogatottak. Alternatív lehetőségekért tekintse meg az alábbi Kerülő megoldások szakaszt.

Adatsíkra vonatkozó korlátozások:

• Csoportosítás lekérdezések szerint
• A COUNT függvénnyel rendelkező lekérdezések DISTINCT-al lekérdezésekből: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Tömeges/tranzakciós kötegelt feldolgozás
• Közvetlen TCP-mód elérése
• A folytatási jogkivonat támogatása a partíciók közötti összesítő lekérdezésekhez, például a rendezéshez, a számláláshoz és a különböző elemekhez. A streamelhető lekérdezések, például SELECT * FROM WHEREtámogatják a folytatási jogkivonatokat.
• Változáscsatorna: Processzor
• Változáscsatorna: Több partíció kulcsértékének olvasása
• Változáscsatorna: Olvasási idő
• Változáscsatorna: Olvasás az elejétől
• Változáscsatorna: Lekéréses modell
• Keresztpartíciós ORDER BY vegyes típusok esetén
• Diagnosztikák engedélyezése aszinkron lekérdezéstípusú metódusokhoz

Vezérlősík korlátozásai:

• CollectionSizeUsage, DatabaseUsage és DocumentUsage metrikák lekérése
• Térinformatikai index létrehozása
• A kapcsolati sztring lekérése
• Tároló minimális RU/s-jának lekérése

Kerülő megoldások

Tömeges feldolgozás korlátozásának megkerülő megoldása

Ha a Python SDK-val tömeges beszúrásokat szeretne végrehajtani a Cosmos DB-be, a legjobb megoldás, ha tárolt eljárásokkal több elemet ír ugyanarra a partíciókulcsra.

Vezérlősík korlátozásai – áthidaló megoldás

A vezérlősík nem támogatott korlátaihoz általában az Azure Portalt, az Azure Cosmos DB erőforrás-szolgáltató RESTAPI-t, az Azure CLI-t vagy a PowerShellt használhatja.

Logikai adattípus

Míg a Python-nyelv az "Igaz" és a "Hamis" értéket használja a logikai típusokhoz, a Cosmos DB csak az "igaz" és a "hamis" értéket fogadja el . Más szóval a Python nyelv logikai értékeket használ az első nagybetűvel és az összes többi kisbetűvel, míg a Cosmos DB és az SQL-nyelv csak kisbetűket használ ugyanezekhez a logikai értékekhez. Hogyan kell kezelni ezt a kihívást?

• A Pythonnal létrehozott JSON-dokumentumoknak az "Igaz" és a "Hamis" értéket kell használniuk a nyelvérvényesítéshez. Az SDK átalakítja "igaz" és "hamis" értékre. Ez azt jelenti, hogy az "igaz" és a "hamis" a Cosmos DB-ben tárolt érték.
• Ha lekéri ezeket a dokumentumokat a Cosmos DB Portál Data Explorer, az "igaz" és a "hamis" szöveget fogja látni.
• Ha ezzel a Python SDK-val kéri le ezeket a dokumentumokat, a "true" és a "false" értékek automatikusan "Igaz" és "Hamis" értékké lesznek konvertálva.

SQL-lekérdezések x FROM záradék alelemek

Ez az SDK a query_items metódussal küld SQL-lekérdezéseket az Azure Cosmos DB-nek.

A Cosmos DB SQL-nyelv lehetővé teszi részelemek lekérését a FROM záradék használatával, hogy a forrást kisebb részhalmazra csökkentse. Például a helyett használhatja a parancsot select * from Families.childrenselect * from Families. Vegye figyelembe azonban, hogy:

• A metódust használó SQL-lekérdezések esetében ez az query_items SDK megköveteli a partition_key jelölő megadását vagy használatát enable_cross_partition_query .
• Ha alelemeket kap, és megadja a partition_keyelemet, győződjön meg arról, hogy a partíciókulcs szerepel az alelemekben, ami a legtöbb esetben nem igaz.

Maximális elemszám

Ez a query_items metódus paramétere, amely egy egész szám, amely az egyes oldalakon visszaadandó elemek maximális számát jelzi. Az None érték megadható, hogy a szolgáltatás határozza meg az optimális elemszámot. Ez az ajánlott konfigurációs érték, és az SDK alapértelmezett viselkedése, ha nincs beállítva.

Példák

A következő szakaszok számos kódrészletet biztosítanak, amelyek a leggyakoribb Cosmos DB-feladatokat fedik le, többek között:

• Adatbázis létrehozása
• Tároló létrehozása
• Elemzési tárat engedélyező tároló létrehozása
• Meglévő tároló lekérése
• Adatok beszúrása
• Adatok törlése
• Az adatbázis lekérdezése
• Adatbázis-tulajdonságok lekérése
• Adatbázis és tároló átviteli sebességének lekérése
• Tároló tulajdonságainak módosítása
• Az aszinkron ügyfél használata

Adatbázis létrehozása

A CosmosClient hitelesítése után a fiók bármely erőforrásával dolgozhat. Az alábbi kódrészlet létrehoz egy SQL API-adatbázist, amely az alapértelmezett, ha nem ad meg API-t create_database meghívásakor.

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)

Tároló létrehozása

Ez a példa egy alapértelmezett beállításokkal rendelkező tárolót hoz létre. Ha már létezik azonos nevű tároló az adatbázisban (hibát generál 409 Conflict ), a rendszer ehelyett a meglévő tárolót kéri le.

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

Elemzési tárat engedélyező tároló létrehozása

Ez a példa létrehoz egy tárolót, amelyen engedélyezve van az Elemzési tár, jelentéskészítéshez, BI-hoz, AI-hoz és Advanced Analyticshez Azure Synapse Linkkel.

A analytical_storage_ttl lehetőségei a következők:

• 0 vagy Null, vagy nincs tájékoztatva: Nincs engedélyezve.
• -1: Az adatok végtelenül lesznek tárolva.
• Bármely más szám: a tényleges ttl, másodpercben.

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

Az előző kódrészletek a CosmosHttpResponseError kivételt is kezelik, ha a tároló létrehozása sikertelen volt. A hibakezeléssel és a hibaelhárítással kapcsolatos további információkért tekintse meg a hibaelhárítása című szakaszt .

Meglévő tároló lekérése

Meglévő tároló lekérése az adatbázisból:

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)

Adat beszúrása

Ha elemeket szeretne beszúrni egy tárolóba, adja át az adatokat tartalmazó szótárat ContainerProxy.upsert_item. A tárolóhoz hozzáadott minden elemnek tartalmaznia kell egy id kulcsot egy olyan értékkel, amely egyedileg azonosítja az elemet a tárolóban.

Ez a példa több elemet szúr be a tárolóba, amelyek mindegyike egyedi 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)
        }
    )

Adat törlése

Ha törölni szeretne elemeket egy tárolóból, használja a ContainerProxy.delete_item. A Cosmos DB SQL API-ja nem támogatja az SQL-utasítást 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')

MEGJEGYZÉS: Particionált gyűjtemény használata esetén a fenti példakódban szereplő értéknek partitionKey az adott elem partíciókulcsának értékére kell állítania, nem pedig a gyűjtemény partíciókulcs-oszlopának nevére. Ez a pontolvasásokra és a törlésekre egyaránt igaz.

Az adatbázis lekérdezése

A Cosmos DB SQL API-adatbázisok támogatják a tároló elemeinek lekérdezését ContainerProxy.query_items SQL-szerű szintaxissal.

Ez a példa lekérdez egy tárolót egy adott idelemhez:

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

MEGJEGYZÉS: Bár a záradékban bármilyen értéket megadhat a FROM tárolónévhez, javasoljuk, hogy a tároló nevét használja a konzisztencia érdekében.

Paraméteres lekérdezések végrehajtásához adjon át egy szótárt, amely tartalmazza a paramétereket és azok értékeit 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))

További információ a Cosmos DB-adatbázisok SQL API-val történő lekérdezéséről: Azure Cosmos DB-adatok lekérdezése SQL-lekérdezésekkel.

Adatbázis-tulajdonságok lekérése

Adatbázis tulajdonságainak lekérése és megjelenítése:

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

Adatbázis és tároló átviteli sebességének lekérése

Lekérheti és megjelenítheti egy adatbázis és egy dedikált átviteli sebességgel rendelkező tároló átviteli sebességét:

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

Tároló tulajdonságainak módosítása

A meglévő tárolók bizonyos tulajdonságai módosíthatók. Ez a példa a tárolóban lévő elemek alapértelmezett élettartamát (TTL) 10 másodpercre állítja:

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

További információ a TTL-ről: Élettartam az Azure Cosmos DB-adatokhoz.

Az aszinkron ügyfél használata

Az aszinkron cosmos-ügyfél egy különálló ügyfél, amely a meglévő szinkron ügyfélhez hasonlóan néz ki és működik. Az aszinkron ügyfelet azonban külön kell importálni, és a metódusait az async/await kulcsszavakkal kell használni. Az Async-ügyfelet használat után inicializálni és bezárni kell, ami manuálisan vagy környezetkezelő használatával végezhető el. Az alábbi példa bemutatja, hogyan teheti ezt meg manuálisan.

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

Ahelyett, hogy manuálisan nyithatná meg és zárhatná be az ügyfelet, erősen ajánlott a async with kulcsszavakat használni. Ez létrehoz egy környezetkezelőt, amely inicializálja, majd később bezárja az ügyfelet, miután már nem használja a utasítást. Az alábbi példa bemutatja, hogyan teheti ezt meg.

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

Lekérdezések az aszinkron ügyféllel

A szinkron ügyféltől eltérően az aszinkron ügyfélnek nincs enable_cross_partition jelzője a kérelemben. A megadott partíciókulcs-értékkel nem rendelkező lekérdezések alapértelmezés szerint partíciók közötti lekérdezést kísérelnek meg végrehajtani.

A lekérdezés eredményei iterálhatók, de a lekérdezés nyers kimenete aszinkron iterátort ad vissza. Ez azt jelenti, hogy az iterátor minden objektuma egy várandós objektum, és még nem tartalmazza a valódi lekérdezési eredményt. A lekérdezési eredmények lekéréséhez használhat egy aszinkron for loopot, amely az objektum iterációja során várja az egyes eredményeket, vagy manuálisan várja meg az egyes lekérdezési eredményeket az aszinkron iterátor iterációja során.

Mivel a lekérdezési eredmények egy aszinkron iterátor, nem vethetők közvetlenül listákba; ehelyett, ha listákat kell létrehoznia az eredményekből, használjon aszinkron for loopot vagy Python-listaértelmezést egy lista feltöltéséhez:

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

Integrált gyorsítótár használata

Az integrált gyorsítótár egy memóriabeli gyorsítótár, amely segít biztosítani a kezelhető költségeket és a kérések mennyiségének növekedésével járó alacsony késést. Az integrált gyorsítótár két részből áll: egy elemgyorsítótár a pontolvasásokhoz és egy lekérdezési gyorsítótár a lekérdezésekhez. Az alábbi kódrészlet bemutatja, hogyan használhatja ezt a funkciót a pontolvasási és lekérdezési gyorsítótár-metódusokkal.

Ennek az az előnye, hogy az integrált gyorsítótárat elérő pontolvasások és lekérdezések nem használnak kérelemegységeket. Ez azt jelenti, hogy a műveletenkénti költségek sokkal alacsonyabbak lesznek, mint a háttérrendszerből származó olvasások.

Az Azure Cosmos DB integrált gyorsítótárának konfigurálása (előzetes verzió)

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)

További információ az integrált gyorsítótárról: Azure Cosmos DB integrált gyorsítótár – Áttekintés.

Hibaelhárítás

Általános kérdések

Amikor a Python SDK-val kommunikál a Cosmos DB-vel, a szolgáltatás által visszaadott kivételek ugyanazoknak a HTTP-állapotkódoknak felelnek meg, amelyeket a REST API-kérések esetében ad vissza:

HTTP-állapotkódok az Azure Cosmos DB-hez

Ha például olyan azonosítóval (névvel) próbál tárolót létrehozni, amely már használatban van a Cosmos DB-adatbázisban, a 409 rendszer hibát ad vissza, jelezve az ütközést. Az alábbi kódrészletben a rendszer a kivétel elfogásával és a hibával kapcsolatos további információk megjelenítésével kezeli a hibát.

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

Naplózás

Ez a kódtár a szabványos naplózási kódtárat használja a naplózáshoz. A HTTP-munkamenetekkel (URL-címekkel, fejlécekkel stb.) kapcsolatos alapvető információkat az INFO szinten naplózza a rendszer.

A hibakeresési szint részletes naplózása, beleértve a kérelem-/választörzseket és a nem felügyelt fejléceket, engedélyezhető az ügyfélen a logging_enable következő argumentummal:

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)

Hasonlóképpen logging_enable engedélyezheti a részletes naplózást egyetlen művelethez, még akkor is, ha nincs engedélyezve az ügyfél számára:

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

Másik lehetőségként a CosmosHttpLoggingPolicy használatával is bejelentkezhet, amely az azure core HttpLoggingPolicy-ból terjed ki, ha a naplózót átadja az logger argumentumnak. Alapértelmezés szerint a HttpLoggingPolicy viselkedését fogja használni. Az argumentum átadásával enable_diagnostics_logging engedélyezve lesz a CosmosHttpLoggingPolicy, és további információval fog rendelkezni a Cosmos-problémák hibakereséséhez kapcsolódó válaszban.

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)

Hasonlóképpen, a naplózás egyetlen művelethez is engedélyezhető, ha egy naplózót ad át az egyes kérésnek. Ha azonban a CosmosHttpLoggingPolicy használatával szeretne további információkat beszerezni, az enable_diagnostics_logging argumentumot az ügyfélkonstruktornál kell átadni.

# 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

Az Azure Core lehetővé teszi a Python SDK-k számára az OpenTelemetry használatát velük. A funkció használatához csak a következő csomagokat kell telepíteni:

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

Ezzel kapcsolatban javasoljuk, hogy tekintse meg ezt a dokumentumot az Azure Core-ból, amely leírja a beállítását. Hozzáadtunk egy mintafájlt is, amely bemutatja, hogyan használható az SDK-val. Ez ugyanúgy működik, függetlenül a használt Cosmos-ügyféltől.

Következő lépések

A Cosmos DB szolgáltatás részletesebb dokumentációját az Azure Cosmos DB dokumentációjában találja a docs.microsoft.com.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. További részletekért lásd: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.