Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete na https://github.com/Azure/azure-sdk-for-python/issues/20691

Klientská knihovna rozhraní SQL API služby Azure Cosmos DB pro Python – verze 4.5.1

Azure Cosmos DB je globálně distribuovaná a databázová služba pro více modelů, která dokumentační databáze, databáze typu klíč-hodnota, databáze širokých sloupců a databáze grafů.

Pomocí sady SQL API SDK služby Azure Cosmos DB pro Python můžete spravovat databáze a dokumenty JSON, které obsahují v této databázové službě NoSQL. Mezi možnosti vysoké úrovně patří:

• Vytváření databází Cosmos DB a úprava jejich nastavení
• Vytváření a úpravy kontejnerů pro ukládání kolekcí dokumentů JSON
• Vytváření, čtení, aktualizace a odstraňování položek (dokumentů JSON) v kontejnerech
• Dotazování dokumentů v databázi pomocí syntaxe podobné SQL

Zdrojový kód | sady SDKBalíček (PyPI) | Balíček (Conda) | Referenční dokumentace k | rozhraní APIDokumentace k | produktuVzorky

Tato sada SDK se používá pro rozhraní SQL API. U všech ostatních rozhraní API si projděte dokumentaci ke službě Azure Cosmos DB a vyhodnoťte nejlepší sadu SDK pro váš projekt.

Začínáme

Důležitá aktualizace podpory Pythonu 2.x

Nové verze této sady SDK nebudou od 1. ledna 2022 podporovat Python 2.x. Další informace najdete v protokolu CHANGELOG .

Požadavky

• Předplatné Azure – Vytvoření bezplatného účtu
• Účet služby Azure Cosmos DB – ROZHRANÍ SQL API
• Python 3.6 nebo novější

Pokud potřebujete účet rozhraní SQL API služby Cosmos DB, můžete ho vytvořit pomocí tohoto příkazu Azure CLI :

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

Instalace balíčku

pip install azure-cosmos

Konfigurace virtuálního prostředí (volitelné)

I když to není povinné, pokud používáte virtuální prostředí, můžete zachovat vzájemnou izolaci prostředí základního systému a sady Azure SDK. Spusťte následující příkazy pro konfiguraci a pak zadejte virtuální prostředí pomocí příkazu venv:

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

Ověření klienta

Interakce se službou Cosmos DB začíná instancí třídy CosmosClient . K vytvoření instance objektu klienta potřebujete účet, jeho identifikátor URI a jeden z jeho klíčů účtu .

Následující fragment kódu Azure CLI použijte k naplnění dvou proměnných prostředí identifikátorem URI databázového účtu a jeho primárním hlavním klíčem (tyto hodnoty najdete také v Azure Portal). Fragment kódu je naformátovaný pro prostředí 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)

Vytvoření klienta

Po naplnění proměnných ACCOUNT_URI prostředí a ACCOUNT_KEY můžete vytvořit CosmosClient.

from azure.cosmos import CosmosClient

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

Ověřování AAD

Klienta můžete také ověřit pomocí přihlašovacích údajů AAD vašeho instančního objektu a balíčku identit Azure. Informace o přihlašovacích údajích můžete přímo předat clientSecretCredential nebo použít 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)

Vždy se ujistěte, že spravovaná identita, kterou používáte pro ověřování AAD, má readMetadata oprávnění.
Další informace o nastavení ověřování AAD: Nastavení RBAC pro ověřování AAD
Další informace o povolených operacích pro klienty ověřené službou AAD: Model oprávnění RBAC

Klíčové koncepty

Jakmile inicializujete CosmosClient, můžete pracovat s primárními typy prostředků ve službě Cosmos DB:

• Databáze: Účet služby Cosmos DB může obsahovat více databází. Při vytváření databáze zadáte rozhraní API, které chcete použít při práci s jejími dokumenty: SQL, MongoDB, Gremlin, Cassandra nebo Azure Table. Ke správě kontejnerů použijte objekt DatabaseProxy .

• Kontejner: Kontejner je kolekce dokumentů JSON. Položky v kontejneru můžete vytvářet (vkládat), číst, aktualizovat a odstraňovat pomocí metod v objektu ContainerProxy .

• Položka: Položka je slovníková reprezentace dokumentu JSON uloženého v kontejneru. Každá položka přidaná do kontejneru musí obsahovat id klíč s hodnotou, která jedinečně identifikuje položku v kontejneru.

Další informace o těchto prostředcích najdete v tématu Práce s databázemi, kontejnery a položkami Azure Cosmos.

Jak používat enable_cross_partition_query

Argument klíčového slova enable_cross_partition_query přijímá 2 možnosti: None (výchozí) nebo True.

Poznámka k použití dotazů podle ID

Při použití dotazů, které se snaží najít položky na základě hodnoty ID , se vždy ujistěte, že předáváte proměnnou typu řetězce. Azure Cosmos DB povoluje pouze hodnoty ID řetězců, a pokud použijete jakýkoli jiný datový typ, tato sada SDK nevrátí žádné výsledky a žádné chybové zprávy.

Poznámka k úrovním konzistence klienta

Od verze 4.3.0b3 platí, že pokud uživatel nepředá explicitní úroveň konzistence inicializaci klienta, použije jeho klient výchozí úroveň účtu databáze. Dříve se výchozí hodnota nastavovala na Session konzistenci. Pokud byste to z nějakého důvodu chtěli dál dělat, můžete změnit inicializaci klienta tak, aby zahrnovala explicitní parametr pro tento postup, jak je znázorněno na obrázku:

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

Omezení

V současné době nejsou podporované následující funkce. Alternativní možnosti najdete v části Alternativní řešení níže.

Omezení roviny dat:

• Seskupovat podle dotazů
• Dotazy s počtem z poddotazů DISTINCT: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Hromadné/transakční dávkové zpracování
• Přímý přístup k režimu TCP
• Podpora tokenů pokračování pro agregované dotazy napříč oddíly, jako je řazení, počítání a jedinečné. Streamovatelné dotazy, jako je SELECT * FROM WHEREdo, podporují tokeny pokračování.
• Kanál změn: Procesor
• Kanál změn: Čtení hodnot klíčů pro více oddílů
• Kanál změn: Čtení konkrétního času
• Kanál změn: Čtení od začátku
• Kanál změn: Vyžádání modelu
• Order BY napříč oddíly pro smíšené typy
• Povolení diagnostiky pro asynchronní metody typu dotazu

Omezení řídicí roviny:

• Získání metrik CollectionSizeUsage, DatabaseUsage a DocumentUsage
• Vytvoření geoprostorových indexů
• Získání připojovacího řetězce
• Získání minimálních RU/s kontejneru

Alternativní řešení

Alternativní řešení omezení hromadného zpracování

Pokud chcete pomocí sady Python SDK provádět hromadné vkládání do služby Cosmos DB, nejlepší alternativou je použít uložené procedury k zápisu více položek se stejným klíčem oddílu.

Alternativní řešení omezení řídicí roviny

Pro nepodporovaná omezení řídicí roviny můžete obvykle použít Azure Portal, rozhraní REST API poskytovatele prostředků služby Azure Cosmos DB, Azure CLI nebo PowerShell .

Boolean – datový typ

Zatímco jazyk Python používá pro logické typy "True" a "False", Cosmos DB přijímá pouze "true" a "false". Jinými slovy, jazyk Python používá logické hodnoty s prvními velkými písmeny a všemi ostatními malými písmeny, zatímco Cosmos DB a její jazyk SQL používají pro stejné logické hodnoty pouze malá písmena. Jak se s touto výzvou vypořádat?

• Dokumenty JSON vytvořené pomocí Pythonu musí k ověření jazyka používat hodnoty True a False. Sada SDK ho za vás převede na true a false. To znamená, že "true" a "false" jsou to, co se uloží ve službě Cosmos DB.
• Pokud tyto dokumenty načtete pomocí Data Explorer portálu Cosmos DB, zobrazí se "true" a "false".
• Pokud tyto dokumenty načtete pomocí této sady Python SDK, hodnoty true a false se automaticky převedou na True a False.

Dotazy SQL x PODsložky klauzule FROM

Tato sada SDK používá metodu query_items k odesílání dotazů SQL do služby Azure Cosmos DB.

Jazyk SQL služby Cosmos DB umožňuje získat podřízené položky pomocí klauzule FROM a snížit tak zdroj na menší podmnožinu. Jako příklad můžete místo select * from Familiespoužít .select * from Families.children Mějte ale na paměti, že:

• U dotazů SQL používajících metodu query_items tato sada SDK vyžaduje, abyste zadali partition_key nebo použili enable_cross_partition_query příznak .
• Pokud se zobrazují podřízené položky a zadáváte partition_key, ujistěte se, že je klíč oddílu zahrnutý v podpoložkách, což ve většině případů neplatí.

Maximální počet položek

Toto je parametr metody query_items, celé číslo označující maximální počet položek, které mají být vráceny na stránku. Hodnotu None lze zadat, aby služba určila optimální počet položek. Toto je doporučená hodnota konfigurace a výchozí chování této sady SDK, pokud není nastavená.

Příklady

Následující části obsahují několik fragmentů kódu, které pokrývají některé z nejběžnějších úloh Cosmos DB, mezi které patří:

• Vytvoření databáze
• Vytvoření kontejneru
• Vytvoření kontejneru s povoleným analytickým úložištěm
• Získání existujícího kontejneru
• Vložení dat
• Odstranit data
• Dotazování databáze
• Získání vlastností databáze
• Získání propustnosti databáze a kontejneru
• Úprava vlastností kontejneru
• Použití asynchronního klienta

Vytvoření databáze

Po ověření klienta CosmosClient můžete pracovat s libovolným prostředkem v účtu. Následující fragment kódu vytvoří databázi rozhraní SQL API, což je výchozí nastavení, když se při vyvolání create_database nezadá žádné rozhraní API.

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)

Vytvoření kontejneru

Tento příklad vytvoří kontejner s výchozím nastavením. Pokud kontejner se stejným názvem již v databázi existuje (vygeneruje 409 Conflict chybu), získá se místo toho existující kontejner.

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

Vytvoření kontejneru s povoleným analytickým úložištěm

Tento příklad vytvoří kontejner s povoleným analytickým úložištěm pro vytváření sestav, BI, AI a advanced analytics s Azure Synapse Link.

Možnosti pro analytical_storage_ttl jsou:

• 0 nebo Null nebo není informováno: Není povoleno.
• -1: Data budou uložena nekonečně.
• Jakékoli jiné číslo: skutečná hodnota ttl (v sekundách).

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

Předchozí fragmenty kódu také zpracovávají výjimku CosmosHttpResponseError , pokud se vytvoření kontejneru nezdařilo. Další informace o zpracování chyb a řešení potíží najdete v části .

Získání existujícího kontejneru

Načtení existujícího kontejneru z databáze:

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)

Vložení dat

Pokud chcete vložit položky do kontejneru, předejte slovník obsahující vaše data do ContainerProxy.upsert_item. Každá položka přidaná do kontejneru musí obsahovat id klíč s hodnotou, která položku v kontejneru jednoznačně identifikuje.

Tento příklad vloží do kontejneru několik položek, z nichž každá má jedinečnou idhodnotu :

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

Odstranění dat

K odstranění položek z kontejneru použijte ContainerProxy.delete_item. Rozhraní SQL API ve službě Cosmos DB nepodporuje příkaz 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')

POZNÁMKA: Pokud používáte dělenou kolekci, měla by být hodnota partitionKey v ukázkovém kódu výše nastavena na hodnotu klíče oddílu pro tuto konkrétní položku, nikoli na název sloupce klíče oddílu ve vaší kolekci. To platí pro čtení i odstranění bodů.

Dotazování databáze

Databáze rozhraní SQL API Cosmos DB podporuje dotazování položek v kontejneru pomocí ContainerProxy.query_items pomocí syntaxe podobné SQL.

Tento příklad se dotazuje kontejneru na položky s konkrétním 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))

POZNÁMKA: I když můžete v klauzuli zadat libovolnou hodnotu pro název kontejneru FROM , doporučujeme použít název kontejneru pro konzistenci.

Provádějte parametrizované dotazy předáním slovníku obsahujícího parametry a jejich hodnoty do 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))

Další informace o dotazování databází Cosmos DB pomocí rozhraní SQL API najdete v tématu Dotazování dat služby Azure Cosmos DB pomocí dotazů SQL.

Získání vlastností databáze

Získání a zobrazení vlastností databáze:

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

Získání propustnosti databáze a kontejneru

Získání a zobrazení hodnot propustnosti databáze a kontejneru s vyhrazenou propustností:

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

Úprava vlastností kontejneru

Některé vlastnosti existujícího kontejneru je možné upravit. Tento příklad nastaví výchozí hodnotu TTL (Time to Live) pro položky v kontejneru na 10 sekund:

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

Další informace o hodnotě TTL najdete v tématu Hodnota TTL pro data služby Azure Cosmos DB.

Použití asynchronního klienta

Asynchronní klient cosmos je samostatný klient, který vypadá a funguje podobným způsobem jako existující synchronní klient. Asynchronní klient se ale musí importovat samostatně a jeho metody je potřeba použít s klíčovými slovy async/await. Po použití je potřeba inicializovat a zavřít asynchronního klienta, což lze provést ručně nebo pomocí správce kontextu. Následující příklad ukazuje, jak to udělat ručně.

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

Místo ručního otevírání a zavírání klienta se důrazně doporučuje používat async with klíčová slova . Tím se vytvoří správce kontextu, který inicializuje a později zavře klienta, jakmile se z příkazu dostanete mimo příkaz . Následující příklad ukazuje, jak to udělat.

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

Dotazy s asynchronním klientem

Na rozdíl od synchronního klienta nemá asynchronní klient enable_cross_partition v požadavku příznak. Dotazy bez zadané hodnoty klíče oddílu se ve výchozím nastavení pokusí provést dotaz napříč oddíly.

Výsledky dotazu je možné iterovat, ale nezpracovaný výstup dotazu vrátí asynchronní iterátor. To znamená, že každý objekt z iterátoru je objekt awaitable a ještě neobsahuje skutečný výsledek dotazu. Pokud chcete získat výsledky dotazu, můžete použít asynchronní smyčku for, která čeká na každý výsledek při iteraci objektu, nebo ručně vyčkejte na každý výsledek dotazu při iteraci asynchronního iterátoru.

Vzhledem k tomu, že výsledky dotazu jsou asynchronní iterátor, nelze je přetypovat do seznamů přímo; Pokud místo toho potřebujete vytvořit seznamy z výsledků, použijte asynchronní smyčku pro smyčku nebo porozumění seznamu Pythonu k naplnění seznamu:

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

Použití integrované mezipaměti

Integrovaná mezipaměť je mezipaměť v paměti, která pomáhá zajistit spravovatelné náklady a nízkou latenci s rostoucím objemem požadavků. Integrovaná mezipaměť má dvě části: mezipaměť položek pro čtení bodů a mezipaměť dotazů pro dotazy. Následující fragment kódu ukazuje, jak tuto funkci používat s metodami čtení bodů a ukládání dotazů do mezipaměti.

Výhodou tohoto použití je, že bod přečte a dotazy, které narazí na integrovanou mezipaměť, nebudou používat žádné RU. To znamená, že budete mít mnohem nižší náklady na operaci než čtení z back-endu.

Postup konfigurace integrované mezipaměti služby Azure Cosmos DB (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)

Další informace o integrované mezipaměti najdete v tématu Integrovaná mezipaměť Azure Cosmos DB – přehled.

Poradce při potížích

Obecné

Při interakci se službou Cosmos DB pomocí sady Python SDK odpovídají výjimky vrácené službou stejným stavovým kódům HTTP vráceným pro požadavky rozhraní REST API:

Stavové kódy HTTP pro službu Azure Cosmos DB

Pokud se například pokusíte vytvořit kontejner s použitím ID (názvu), které se už používá ve vaší databázi Cosmos DB, 409 vrátí se chyba označující konflikt. V následujícím fragmentu kódu se chyba elegantně zpracuje zachycením výjimky a zobrazením dalších informací o chybě.

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

protokolování

Tato knihovna používá k protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a nezopravovaných hlaviček, je možné povolit na klientovi s argumentem 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)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

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

Alternativně můžete protokolovat pomocí zásady CosmosHttpLoggingPolicy, která se rozšiřuje ze základní zásady HttpLoggingPolicy v Azure, a to předáním protokolovacího nástroje argumentu logger . Ve výchozím nastavení se použije chování z HttpLoggingPolicy. Předání argumentu enable_diagnostics_logging povolí zásadu CosmosHttpLoggingPolicy a bude obsahovat další informace v odpovědi související s laděním problémů se službou 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)

Podobně lze protokolování povolit pro jednu operaci předáním protokolovacího nástroje do jednotného požadavku. Pokud však chcete použít CosmosHttpLoggingPolicy k získání dalších informací, enable_diagnostics_logging je nutné předat argument v konstruktoru klienta.

# 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 poskytuje našim sadm Python SDK možnost používat s nimi OpenTelemetry. Jediné balíčky, které je potřeba nainstalovat, aby bylo možné tuto funkci používat, jsou následující:

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

Další informace k tomuto tématu najdete v tomto dokumentu z Azure Core, který popisuje, jak ho nastavit. Přidali jsme také ukázkový soubor , který ukazuje, jak ho můžete použít s naší sadou SDK. To funguje stejným způsobem bez ohledu na klienta Cosmos, který používáte.

Další kroky

Podrobnější dokumentaci ke službě Cosmos DB najdete v dokumentaci ke službě Azure Cosmos DB týkající se docs.microsoft.com.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.