Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python zestawu Azure SDK dla języka Python 2.7 została zakończona 01 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691

Biblioteka klienta interfejsu API SQL usługi Azure Cosmos DB dla języka Python — wersja 4.5.1

Azure Cosmos DB to globalnie dystrybuowana, wielomodelowa usługa bazy danych, która obsługuje bazy danych dokumentowe, typu klucz-wartość, szerokokolumnowe i grafowe.

Zestaw SDK interfejsu API SQL usługi Azure Cosmos DB dla języka Python umożliwia zarządzanie bazami danych i dokumentami JSON, które zawierają w tej usłudze bazy danych NoSQL. Funkcje wysokiego poziomu to:

• Tworzenie baz danych usługi Cosmos DB i modyfikowanie ich ustawień
• Tworzenie i modyfikowanie kontenerów do przechowywania kolekcji dokumentów JSON
• Tworzenie, odczytywanie, aktualizowanie i usuwanie elementów (dokumentów JSON) w kontenerach
• Wykonywanie zapytań dotyczących dokumentów w bazie danych przy użyciu składni podobnej do języka SQL

Kod | źródłowy zestawu SDKPakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | APIDokumentacja | produktuPróbki

Ten zestaw SDK jest używany dla interfejsu API SQL. W przypadku wszystkich innych interfejsów API zapoznaj się z dokumentacją usługi Azure Cosmos DB , aby ocenić najlepszy zestaw SDK dla projektu.

Wprowadzenie

Ważna aktualizacja obsługi języka Python 2.x

Nowe wersje tego zestawu SDK nie będą obsługiwać języka Python 2.x od 1 stycznia 2022 r. Aby uzyskać więcej informacji, zobacz CHANGELOG .

Wymagania wstępne

• Subskrypcja platformy Azure — można utworzyć bezpłatne konto
• Konto usługi Azure Cosmos DB — interfejs API SQL
• Python 3.6+

Jeśli potrzebujesz konta interfejsu API SQL usługi Cosmos DB, możesz go utworzyć za pomocą tego polecenia interfejsu wiersza polecenia platformy Azure :

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

Instalowanie pakietu

pip install azure-cosmos

Konfigurowanie środowiska wirtualnego (opcjonalnie)

Chociaż nie jest to wymagane, można odizolować od siebie środowiska podstawowego systemu i zestawu Azure SDK. Umożliwia to środowisko wirtualne. Wykonaj następujące polecenia, aby skonfigurować, a następnie wprowadź środowisko wirtualne z venv:

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

Uwierzytelnianie klienta

Interakcja z usługą Cosmos DB rozpoczyna się od wystąpienia klasy CosmosClient . Do utworzenia wystąpienia obiektu klienta potrzebne jest konto, jego identyfikator URI i jeden z jego kluczy konta .

Użyj poniższego fragmentu kodu interfejsu wiersza polecenia platformy Azure, aby wypełnić dwie zmienne środowiskowe identyfikatorem URI konta bazy danych i jego podstawowym kluczem głównym (te wartości można również znaleźć w Azure Portal). Ten fragment kodu został sformatowany dla powłoki 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)

Tworzenie klienta

Po wypełnieniu ACCOUNT_URI zmiennych środowiskowych i ACCOUNT_KEY możesz utworzyć obiekt CosmosClient.

from azure.cosmos import CosmosClient

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

Uwierzytelnianie za pomocą usługi AAD

Możesz również uwierzytelnić klienta przy użyciu poświadczeń usługi AAD jednostki usługi i pakietu tożsamości platformy Azure. Możesz bezpośrednio przekazać informacje o poświadczeniach do obiektu ClientSecretCredential lub użyć wartości 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)

Zawsze upewnij się, że tożsamość zarządzana używana do uwierzytelniania usługi AAD ma readMetadata uprawnienia.
Więcej informacji na temat konfigurowania uwierzytelniania usługi AAD: Konfigurowanie kontroli dostępu opartej na rolach na potrzeby uwierzytelniania usługi AAD
Więcej informacji na temat dozwolonych operacji dla uwierzytelnionych klientów usługi AAD: model uprawnień RBAC

Kluczowe pojęcia

Po zainicjowaniu elementu CosmosClient można wchodzić w interakcje z podstawowymi typami zasobów w usłudze Cosmos DB:

• Baza danych: konto usługi Cosmos DB może zawierać wiele baz danych. Podczas tworzenia bazy danych należy określić interfejs API, którego chcesz użyć podczas interakcji z jego dokumentami: SQL, MongoDB, Gremlin, Cassandra lub Azure Table. Użyj obiektu DatabaseProxy do zarządzania kontenerami.

• Kontener: kontener to kolekcja dokumentów JSON. Elementy tworzone (wstawiania), odczytu, aktualizowania i usuwania w kontenerze przy użyciu metod w obiekcie ContainerProxy .

• Element: Element jest reprezentacją w słowniku dokumentu JSON przechowywanego w kontenerze. Każdy element dodany do kontenera musi zawierać id klucz o wartości, która jednoznacznie identyfikuje element w kontenerze.

Aby uzyskać więcej informacji na temat tych zasobów, zobacz Praca z bazami danych, kontenerami i elementami usługi Azure Cosmos.

Jak używać enable_cross_partition_query

Argument-słowa enable_cross_partition_query kluczowego akceptuje 2 opcje: None (wartość domyślna) lub True.

Uwaga dotycząca używania zapytań według identyfikatora

W przypadku używania zapytań, które próbują znaleźć elementy na podstawie wartości identyfikatora , zawsze upewnij się, że przekazujesz zmienną typu ciągu. Usługa Azure Cosmos DB zezwala tylko na wartości identyfikatorów ciągów, a jeśli używasz dowolnego innego typu danych, ten zestaw SDK nie zwróci żadnych wyników i żadnych komunikatów o błędach.

Uwaga dotycząca poziomów spójności klienta

Od wersji 4.3.0b3, jeśli użytkownik nie przekazuje jawnego poziomu spójności do inicjowania klienta, klient będzie używać domyślnego poziomu konta bazy danych. Wcześniej ustawienie domyślne było ustawione na spójność Session . Jeśli z jakiegoś powodu chcesz to zrobić, możesz zmienić inicjację klienta, aby uwzględnić jawny parametr dla tego, jak pokazano:

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

Ograniczenia

Obecnie poniższe funkcje nie są obsługiwane. Aby zapoznać się z opcjami alternatywnymi , zapoznaj się z poniższą sekcją Obejścia.

Ograniczenia płaszczyzny danych:

• Grupuj według zapytań
• Zapytania z LICZBĄ z odrębnego podquerii: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C) (SELECT DISTINCT C.ID FROM C)
• Przetwarzanie zbiorcze/transakcyjne wsadowe
• Bezpośredni dostęp do trybu TCP
• Obsługa tokenu kontynuacji dla zagregowanych zapytań między partycjami, takich jak sortowanie, liczenie i odrębne. Zapytania przesyłane strumieniowo, takie jak SELECT * FROM WHEREobsługują tokeny kontynuacji.
• Zestawienie zmian: procesor
• Zestawienie zmian: odczytywanie wielu wartości klucza partycji
• Zestawienie zmian: czas odczytu określony
• Zestawienie zmian: odczytywanie od początku
• Zestawienie zmian: model ściągania
• Między partycjami ORDER BY dla typów mieszanych
• Włączanie diagnostyki dla metod asynchronicznych typów zapytań

Ograniczenia płaszczyzny sterowania:

• Pobieranie metryk CollectionSizeUsage, DatabaseUsage i DocumentUsage
• Tworzenie indeksu geoprzestrzennych
• Pobieranie parametrów połączenia
• Pobieranie minimalnej liczby RU/s kontenera

Obejścia

Obejście ograniczenia przetwarzania zbiorczego

Jeśli chcesz używać zestawu SDK języka Python do wykonywania wstawiania zbiorczego do usługi Cosmos DB, najlepszym rozwiązaniem jest użycie procedur składowanych do zapisywania wielu elementów przy użyciu tego samego klucza partycji.

Obejście ograniczeń płaszczyzny sterowania

Zazwyczaj można użyć witryny Azure Portal, interfejsu API REST dostawcy zasobów usługi Azure Cosmos DB, interfejsu wiersza polecenia platformy Azure lub programu PowerShell w celu uzyskania nieobsługiwanych ograniczeń płaszczyzny sterowania.

Boolean, typ danych

Podczas gdy język Python używa wartości "True" i "False" dla typów logicznych, usługa Cosmos DB akceptuje tylko wartość "true" i "false". Innymi słowy język Python używa wartości logicznych z pierwszą wielką literą i wszystkimi innymi małymi literami, podczas gdy usługa Cosmos DB i jej język SQL używają tylko małych liter dla tych samych wartości logicznych. Jak poradzić sobie z tym wyzwaniem?

• Dokumenty JSON utworzone za pomocą języka Python muszą używać wartości "True" i "False", aby przekazać walidację języka. Zestaw SDK przekonwertuje go na wartość "true" i "false" dla Ciebie. Oznacza to, że wartości "true" i "false" są przechowywane w usłudze Cosmos DB.
• W przypadku pobierania tych dokumentów za pomocą Data Explorer portalu usługi Cosmos DB zobaczysz wartość "true" i "false".
• W przypadku pobierania tych dokumentów przy użyciu tego zestawu SDK języka Python wartości "true" i "false" zostaną automatycznie przekonwertowane na wartości "True" i "False".

Zapytania SQL x KLAUZULA FROM Subitems

Ten zestaw SDK używa metody query_items do przesyłania zapytań SQL do usługi Azure Cosmos DB.

Język SQL usługi Cosmos DB umożliwia uzyskanie poditemów przy użyciu klauzuli FROM, aby zmniejszyć źródło do mniejszego podzestawu. Na przykład można użyć select * from Families.children polecenia zamiast select * from Families. Należy jednak pamiętać, że:

• W przypadku zapytań SQL korzystających z query_items metody ten zestaw SDK wymaga określenia partition_key lub użycia flagi enable_cross_partition_query .
• Jeśli otrzymujesz subitems i określasz partition_keyelement , upewnij się, że klucz partycji jest uwzględniony w subitemach, co nie jest prawdziwe w większości przypadków.

Maksymalna liczba elementów

Jest to parametr metody query_items, liczba całkowita wskazująca maksymalną liczbę elementów do zwrócenia na stronę. Można None określić wartość, aby umożliwić usłudze określenie optymalnej liczby elementów. Jest to zalecana wartość konfiguracji i domyślne zachowanie tego zestawu SDK, gdy nie jest ono ustawione.

Przykłady

W poniższych sekcjach przedstawiono kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań usługi Cosmos DB, w tym:

• Tworzenie bazy danych
• Tworzenie kontenera
• Tworzenie kontenera z włączonym magazynem analitycznym
• Pobieranie istniejącego kontenera
• Wstawianie danych
• Usuwanie danych
• Wykonywanie zapytań względem bazy danych
• Pobieranie właściwości bazy danych
• Uzyskiwanie przepływności bazy danych i kontenera
• Modyfikowanie właściwości kontenera
• Używanie klienta asynchronicznego

Tworzenie bazy danych

Po uwierzytelnieniu elementu CosmosClient możesz pracować z dowolnym zasobem na koncie. Poniższy fragment kodu tworzy bazę danych interfejsu API SQL, która jest domyślna, gdy nie określono interfejsu API po wywołaniu create_database .

from azure.cosmos import CosmosClient, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
try:
    database = client.create_database(DATABASE_NAME)
except exceptions.CosmosResourceExistsError:
    database = client.get_database_client(DATABASE_NAME)

Tworzenie kontenera

W tym przykładzie tworzony jest kontener z ustawieniami domyślnymi. Jeśli kontener o tej samej nazwie już istnieje w bazie danych (generując 409 Conflict błąd), istniejący kontener zostanie uzyskany zamiast tego.

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

Tworzenie kontenera z włączonym magazynem analitycznym

W tym przykładzie tworzony jest kontener z włączonym magazynem analitycznym na potrzeby raportowania, analizy biznesowej, sztucznej inteligencji i zaawansowanej analizy za pomocą usługi Azure Synapse Link.

Dostępne są następujące opcje analytical_storage_ttl:

• 0 lub null lub nie jest informowany: Nie włączono.
• -1: Dane będą przechowywane w nieskończoność.
• Dowolna inna liczba: rzeczywisty czas wygaśnięcia w sekundach.

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

Poprzednie fragmenty kodu obsługują również wyjątek CosmosHttpResponseError , jeśli tworzenie kontenera nie powiodło się. Aby uzyskać więcej informacji na temat obsługi błędów i rozwiązywania problemów, zobacz sekcję .

Pobieranie istniejącego kontenera

Pobierz istniejący kontener z bazy danych:

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)

Wstawianie danych

Aby wstawić elementy do kontenera, przekaż słownik zawierający dane do ContainerProxy.upsert_item. Każdy element dodany do kontenera musi zawierać id klucz o wartości, która jednoznacznie identyfikuje element w kontenerze.

W tym przykładzie wstawia kilka elementów do kontenera, z których każdy ma unikatową wartość 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)
        }
    )

Usuwanie danych

Aby usunąć elementy z kontenera, użyj ContainerProxy.delete_item. Interfejs API SQL w usłudze Cosmos DB nie obsługuje instrukcji 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')

UWAGA: Jeśli używasz kolekcji partycjonowanej, wartość partitionKey w powyższym przykładowym kodzie powinna być ustawiona na wartość klucza partycji dla tego konkretnego elementu, a nie nazwę kolumny klucza partycji w kolekcji. Ma to wartość true dla operacji odczytu i usuwania punktów.

Wykonywanie zapytań względem bazy danych

Baza danych interfejsu API SQL usługi Cosmos DB obsługuje wykonywanie zapytań dotyczących elementów w kontenerze przy użyciu ContainerProxy.query_items przy użyciu składni podobnej do języka SQL.

W tym przykładzie jest wysyłany zapytanie do kontenera dla elementów o określonym idobiekcie :

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

UWAGA: Chociaż można określić dowolną wartość nazwy kontenera w FROM klauzuli, zalecamy użycie nazwy kontenera na potrzeby spójności.

Wykonaj zapytania sparametryzowane, przekazując słownik zawierający parametry i ich wartości 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))

Aby uzyskać więcej informacji na temat wykonywania zapytań dotyczących baz danych usługi Cosmos DB przy użyciu interfejsu API SQL, zobacz Wykonywanie zapytań dotyczących danych usługi Azure Cosmos DB za pomocą zapytań SQL.

Pobieranie właściwości bazy danych

Pobierz i wyświetl właściwości bazy danych:

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

Uzyskiwanie przepływności bazy danych i kontenera

Pobierz i wyświetl wartości przepływności bazy danych i kontenera z dedykowaną przepływnością:

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

Modyfikowanie właściwości kontenera

Niektóre właściwości istniejącego kontenera można modyfikować. W tym przykładzie ustawia domyślny czas wygaśnięcia (TTL) dla elementów w kontenerze 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']))

Aby uzyskać więcej informacji na temat czasu wygaśnięcia, zobacz Time to Live for Azure Cosmos DB data (Czas wygaśnięcia dla danych usługi Azure Cosmos DB).

Używanie klienta asynchronicznego

Klient asynchroniczny cosmos jest oddzielnym klientem, który wygląda i działa w podobny sposób do istniejącego klienta synchronicznego. Jednak klient asynchroniczny musi być importowany oddzielnie, a jego metody muszą być używane ze słowami kluczowymi async/await. Klient asynchroniczny musi zostać zainicjowany i zamknięty po użyciu, który można wykonać ręcznie lub za pomocą menedżera kontekstu. W poniższym przykładzie pokazano, jak to zrobić ręcznie.

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

Zamiast ręcznie otwierać i zamykać klienta, zdecydowanie zaleca się użycie async with słów kluczowych. Spowoduje to utworzenie menedżera kontekstu, który zainicjuje i później zamknie klienta po zakończeniu instrukcji. W poniższym przykładzie pokazano, jak to zrobić.

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

Zapytania z klientem asynchronicznym

W przeciwieństwie do klienta synchronicznego klient asynchroniczny nie ma enable_cross_partition flagi w żądaniu. Zapytania bez określonej wartości klucza partycji będą domyślnie podejmować próby wykonania zapytania obejmującego wiele partycji.

Wyniki zapytania mogą być iteracyjne, ale nieprzetworzone dane wyjściowe zapytania zwracają iterator asynchroniczny. Oznacza to, że każdy obiekt z iteratora jest obiektem oczekiwanym i nie zawiera jeszcze rzeczywistego wyniku zapytania. Aby uzyskać wyniki zapytania, można użyć asynchronicznej pętli, która oczekuje na każdy wynik w miarę iteracji obiektu lub ręcznie oczekuje na każdy wynik zapytania podczas iteracji względem iteratora asynchronicznego.

Ponieważ wyniki zapytania są iteratorem asynchronicznym, nie można ich bezpośrednio rzutować na listy; Zamiast tego, jeśli musisz utworzyć listy na podstawie wyników, użyj asynchronicznego pętli lub zrozumienia listy języka Python, aby wypełnić listę:

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

Używanie zintegrowanej pamięci podręcznej

Zintegrowana pamięć podręczna to pamięć podręczna w pamięci, która ułatwia zarządzanie kosztami i małym opóźnieniem w miarę wzrostu woluminu żądania. Zintegrowana pamięć podręczna ma dwie części: pamięć podręczną elementów dla odczytów punktów i pamięć podręczną zapytań dla zapytań. Poniższy fragment kodu pokazuje, jak używać tej funkcji z metodami odczytu punktów i pamięci podręcznej zapytań.

Zaletą korzystania z tego jest to, że punkt odczytuje i zapytania, które trafią do zintegrowanej pamięci podręcznej, nie będą używać żadnych jednostek RU. Oznacza to, że koszt operacji będzie znacznie niższy niż odczyt z zaplecza.

Jak skonfigurować zintegrowaną pamięć podręczną usługi Azure Cosmos DB (wersja zapoznawcza)

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)

Aby uzyskać więcej informacji na temat zintegrowanej pamięci podręcznej, zobacz Zintegrowana pamięć podręczna usługi Azure Cosmos DB — omówienie.

Rozwiązywanie problemów

Ogólne

Podczas interakcji z usługą Cosmos DB przy użyciu zestawu SDK języka Python wyjątki zwrócone przez usługę odpowiadają tym samym kodom stanu HTTP zwracanym dla żądań interfejsu API REST:

Kody stanu HTTP dla usługi Azure Cosmos DB

Jeśli na przykład spróbujesz utworzyć kontener przy użyciu identyfikatora (nazwy), który jest już używany w bazie danych usługi Cosmos DB, 409 zostanie zwrócony błąd wskazujący konflikt. W poniższym fragmencie kodu przedstawiono bezpieczną obsługę błędu opartą na przechwyceniu wyjątku i wyświetleniu dodatkowych informacji o błędzie.

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

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z 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)

Podobnie może logging_enable włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

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

Możesz też zalogować się przy użyciu obiektu CosmosHttpLoggingPolicy, który rozciąga się od podstawowego obiektu HttpLoggingPolicy platformy Azure, przekazując rejestrator do argumentu logger . Domyślnie będzie ona używać zachowania z protokołu HttpLoggingPolicy. Przekazanie argumentu enable_diagnostics_logging spowoduje włączenie funkcji CosmosHttpLoggingPolicy i będzie zawierać dodatkowe informacje w odpowiedzi dotyczącej debugowania problemów z usługą 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)

Podobnie rejestrowanie można włączyć dla pojedynczej operacji, przekazując rejestrator do pojedynczego żądania. Jeśli jednak chcesz użyć obiektu CosmosHttpLoggingPolicy do uzyskania dodatkowych informacji, enable_diagnostics_logging argument musi zostać przekazany w konstruktorze 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)

Telemetria

Platforma Azure Core umożliwia korzystanie z zestawów SDK języka Python przy użyciu biblioteki OpenTelemetry. Jedynymi pakietami, które należy zainstalować w celu korzystania z tej funkcji, są następujące:

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

Aby uzyskać więcej informacji na ten temat, zalecamy zapoznanie się z tym dokumentem z platformy Azure Core opisującym sposób jej konfigurowania. Dodaliśmy również przykładowy plik , aby pokazać, jak można go używać z naszym zestawem SDK. Działa to w taki sam sposób, niezależnie od używanego klienta usługi Cosmos.

Następne kroki

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Cosmos DB, zobacz dokumentację usługi Azure Cosmos DB dotyczącą docs.microsoft.com.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.