Bildirim

Python 2.7 için Azure SDK Python paketleri desteği 01 Ocak 2022'de sona erdi. Daha fazla bilgi ve soru için lütfen https://github.com/Azure/azure-sdk-for-python/issues/20691

Python için Azure Cosmos DB SQL API istemci kitaplığı - sürüm 4.5.1

Azure Cosmos DB, belge, anahtar-değer, geniş sütun ve graf veritabanlarını destekleyen, global olarak dağıtılmış çok modelli bir veritabanı hizmetidir.

Bu NoSQL veritabanı hizmetinde bulunan veritabanlarını ve JSON belgelerini yönetmek için Python için Azure Cosmos DB SQL API SDK'sını kullanın. Üst düzey özellikler şunlardır:

• Cosmos DB veritabanları oluşturma ve ayarlarını değiştirme
• JSON belge koleksiyonlarını depolamak için kapsayıcı oluşturma ve değiştirme
• Kapsayıcılarınızdaki öğeleri (JSON belgeleri) oluşturma, okuma, güncelleştirme ve silme
• SQL benzeri söz dizimini kullanarak veritabanınızdaki belgeleri sorgulama

SDK kaynak kodu | Paket (PyPI) | Paket (Conda) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Bu SDK , SQL API için kullanılır. Diğer tüm API'ler için lütfen Azure Cosmos DB belgelerini gözden geçirin ve projeniz için en iyi SDK'yı değerlendirin.

Başlarken

Python 2.x Desteği ile ilgili önemli güncelleştirme

Bu SDK'nın yeni sürümleri 1 Ocak 2022'den itibaren Python 2.x'i desteklemeyecektir. Daha fazla bilgi için lütfen CHANGELOG'a bakın.

Önkoşullar

• Azure aboneliği - Ücretsiz hesap oluşturma
• Azure Cosmos DB hesabı - SQL API
• Python 3.6+

Cosmos DB SQL API hesabına ihtiyacınız varsa şu Azure CLI komutuyla bir hesap oluşturabilirsiniz:

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

Paketi yükleme

pip install azure-cosmos

Sanal ortam yapılandırma (isteğe bağlı)

Gerekli olmasa da, bir sanal ortam kullanıyorsanız temel sisteminizi ve Azure SDK ortamlarınızı birbirinden yalıtılmış halde tutabilirsiniz. Yapılandırmak için aşağıdaki komutları yürüterek venv ile bir sanal ortam girin:

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

İstemcinin kimliğini doğrulama

Cosmos DB ile etkileşim, CosmosClient sınıfının bir örneğiyle başlar. İstemci nesnesinin örneğini oluşturabilmek için bir hesaba, URI'sine ve hesap anahtarlarından birine ihtiyacınız vardır.

İki ortam değişkenini veritabanı hesabı URI'siyle ve birincil ana anahtarıyla doldurmak için aşağıdaki Azure CLI kod parçacığını kullanın (bu değerleri Azure portal de bulabilirsiniz). Kod parçacığı Bash kabuğu için biçimlendirilir.

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)

İstemci oluşturma

ve ACCOUNT_KEY ortam değişkenlerini doldurduktan ACCOUNT_URI sonra CosmosClient'ı oluşturabilirsiniz.

from azure.cosmos import CosmosClient

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

AAD Kimlik Doğrulaması

Ayrıca hizmet sorumlunuzun AAD kimlik bilgilerini ve azure kimlik paketini kullanarak bir istemcinin kimliğini doğrulayabilirsiniz. Kimlik bilgileri bilgilerini doğrudan ClientSecretCredential'a geçirebilir veya DefaultAzureCredential değerini kullanabilirsiniz:

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)

AAD kimlik doğrulaması için kullandığınız yönetilen kimliğin her zaman izinlere sahip readMetadata olduğundan emin olun.
AAD kimlik doğrulamasını ayarlama hakkında daha fazla bilgi: AAD kimlik doğrulaması için RBAC'yi ayarlama
AAD kimliği doğrulanmış istemciler için izin verilen işlemler hakkında daha fazla bilgi: RBAC İzin Modeli

Önemli kavramlar

CosmosClient'ı başlatdıktan sonra, Cosmos DB'deki birincil kaynak türleriyle etkileşim kurabilirsiniz:

• Veritabanı: Cosmos DB hesabı birden çok veritabanı içerebilir. Bir veritabanı oluşturduğunuzda, belgeleriyle etkileşim kurarken kullanmak istediğiniz API'yi belirtirsiniz: SQL, MongoDB, Gremlin, Cassandra veya Azure Tablosu. Kapsayıcılarını yönetmek için DatabaseProxy nesnesini kullanın.

• Kapsayıcı: Kapsayıcı, JSON belgelerinden oluşan bir koleksiyondur. ContainerProxy nesnesindeki yöntemleri kullanarak kapsayıcıdaki öğeleri oluşturur (ekler), okur, güncelleştirir ve silersiniz.

• Öğe: Öğe, kapsayıcıda depolanan bir JSON belgesinin sözlük benzeri gösterimidir. Kapsayıcıya eklediğiniz her Öğe, kapsayıcı içindeki öğeyi benzersiz olarak tanımlayan bir değere sahip bir anahtar içermelidir id .

Bu kaynaklar hakkında daha fazla bilgi için bkz. Azure Cosmos veritabanları, kapsayıcıları ve öğeleriyle çalışma.

Nasıl kullanılır? enable_cross_partition_query

anahtar sözcük-bağımsız değişkeni enable_cross_partition_query 2 seçeneği kabul eder: None (varsayılan) veya True.

Kimliklere göre sorguları kullanma hakkında not

Kimlik değerine göre öğeleri bulmaya çalışan sorguları kullanırken, her zaman bir dize türü değişkeni geçirdiğinizden emin olun. Azure Cosmos DB yalnızca dize kimliği değerlerine izin verir ve başka bir veri türü kullanırsanız bu SDK hiçbir sonuç döndürmez ve hata iletisi döndürmez.

İstemci tutarlılığı düzeyleriyle ilgili not

Sürüm 4.3.0b3 itibarıyla, bir kullanıcı istemci başlatmasına açık bir tutarlılık düzeyi geçirmezse, istemcisi veritabanı hesabının varsayılan düzeyini kullanır. Daha önce, varsayılan değer tutarlılık olarak Session ayarlanıyordu. Herhangi bir nedenle bunu yapmaya devam etmek isterseniz, istemci başlatmanızı aşağıdaki gibi bunun için açık parametresini içerecek şekilde değiştirebilirsiniz:

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

Sınırlamalar

Şu anda aşağıdaki özellikler desteklenmiyor. Alternatif seçenekler için aşağıdaki Geçici çözümler bölümüne bakın.

Veri Düzlemi Sınırlamaları:

• Sorgulara Göre Gruplandır
• DISTINCT alt sorgusundan COUNT içeren sorgular: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Toplu/İşlemsel toplu işleme
• Doğrudan TCP Modu erişimi
• Sıralama, sayma ve benzersiz gibi toplu bölümler arası sorgular için devamlılık belirteci desteği. Do gibi SELECT * FROM WHERE akışla aktarılabilir sorgular devamlılık belirteçlerini destekler.
• Değişiklik Akışı: İşlemci
• Değişiklik Akışı: Birden çok bölüm anahtarı değerini okuma
• Değişiklik Akışı: Belirli bir saati okuma
• Değişiklik Akışı: Baştan okuma
• Değişiklik Akışı: Çekme modeli
• Karma türler için bölümler arası ORDER BY
• Zaman uyumsuz sorgu türü yöntemleri için tanılamayı etkinleştirme

Denetim Düzlemi Sınırlamaları:

• CollectionSizeUsage, DatabaseUsage ve DocumentUsage ölçümlerini alma
• Jeo-uzamsal dizin oluşturma
• Bağlantı dizesini alma
• Kapsayıcının en düşük RU/sn'sini alma

Geçici Çözümler

Toplu işleme Sınırlaması Geçici Çözümü

Cosmos DB'ye toplu eklemeler yapmak için Python SDK'sını kullanmak istiyorsanız, en iyi alternatif aynı bölüm anahtarına sahip birden çok öğe yazmak için saklı yordamları kullanmaktır.

Denetim Düzlemi Sınırlamaları Geçici Çözümü

Genellikle, desteklenmeyen sınırlamalar için Azure Portal, Azure Cosmos DB Kaynak Sağlayıcısı REST API'sini, Azure CLI'yı veya PowerShell'i kullanabilirsiniz.

Boolean Veri Türü

Python dilinde boole türleri için "True" ve "False" kullanılırken , Cosmos DB yalnızca "true" ve "false" değerlerini kabul eder . Başka bir deyişle, Python dilinde ilk büyük harf ve diğer tüm küçük harflerle Boole değerleri kullanılırken, Cosmos DB ve SQL dili aynı Boole değerleri için yalnızca küçük harfler kullanır. Bu sınamayla nasıl başa çıkılır?

• Python ile oluşturulan JSON belgeleriniz, dil doğrulamasını geçirmek için "True" ve "False" kullanmalıdır. SDK bunu sizin için "true" ve "false" olarak dönüştürür. Yani Cosmos DB'de depolanacak olan "true" ve "false" olacaktır.
• Bu belgeleri Cosmos DB Portalı'nın Veri Gezgini alırsanız "true" ve "false" değerlerini görürsünüz.
• Bu Python SDK'sı ile bu belgeleri alırsanız, "true" ve "false" değerleri otomatik olarak "True" ve "False" değerlerine dönüştürülür.

SQL Sorguları x FROM Yan Tümce Alt Öğeleri

Bu SDK, SQL sorgularını Azure Cosmos DB'ye göndermek için query_items yöntemini kullanır.

Cosmos DB SQL dili, kaynağı daha küçük bir alt kümeye küçültmek için FROM yan tümcesini kullanarak alt öğeleri almanıza olanak tanır. Örneğin yerine kullanabilirsiniz select * from Families.childrenselect * from Families. Ancak lütfen şunları unutmayın:

• yöntemini kullanan query_items SQL sorguları için bu SDK, veya bayrağını partition_key belirtmenizi enable_cross_partition_query ister.
• Alt öğeler alıyor ve öğesini belirtiyorsanız partition_key, bölüm anahtarınızın alt öğelere eklendiğinden emin olun; bu durumların çoğu için geçerli değildir.

En Fazla Öğe Sayısı

Bu, sayfa başına döndürülecek en fazla öğe sayısını gösteren bir tamsayı olan query_items yönteminin parametresidir. Değeri None , hizmetin en uygun öğe sayısını belirlemesine izin vermek için belirtilebilir. Bu önerilen yapılandırma değeridir ve ayarlanmadığında bu SDK'nın varsayılan davranışıdır.

Örnekler

Aşağıdaki bölümlerde, en yaygın Cosmos DB görevlerinden bazılarını kapsayan çeşitli kod parçacıkları sağlanır:

• Veritabanı oluşturma
• Kapsayıcı oluşturma
• Analiz deposu etkinleştirilmiş bir kapsayıcı oluşturma
• Mevcut kapsayıcıyı alma
• Veri ekleme
• Verileri silme
• Veritabanını sorgulama
• Veritabanı özelliklerini alma
• Veritabanı ve kapsayıcı aktarım hızı alma
• Kapsayıcı özelliklerini değiştirme
• Zaman uyumsuz istemciyi kullanma

Veritabanı oluşturma

CosmosClient'ınızın kimliğini doğruladıktan sonra hesaptaki herhangi bir kaynakla çalışabilirsiniz. Aşağıdaki kod parçacığı, create_database çağrıldığında api belirtilmediğinde varsayılan olan bir SQL API veritabanı oluşturur.

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)

Kapsayıcı oluşturma

Bu örnek, varsayılan ayarlarla bir kapsayıcı oluşturur. Veritabanında aynı ada sahip bir kapsayıcı zaten varsa (hata 409 Conflict oluşturuluyor), bunun yerine mevcut kapsayıcı elde edilir.

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

Analiz deposu etkinleştirilmiş bir kapsayıcı oluşturma

Bu örnek raporlama, BI, AI ve Azure Synapse Link ile Gelişmiş Analiz için Analiz Deposu etkinleştirilmiş bir kapsayıcı oluşturur.

analytical_storage_ttl seçenekleri şunlardır:

• 0 veya Null veya bilgi verilmedi: Etkin değil.
• -1: Veriler sonsuz olarak depolanır.
• Diğer herhangi bir sayı: saniye olarak gerçek ttl.

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

Yukarıdaki kod parçacıkları, kapsayıcı oluşturma işlemi başarısız olursa CosmosHttpResponseError özel durumunu da işler. Hata işleme ve sorun giderme hakkında daha fazla bilgi için Giderme bölümüne bakın.

Mevcut kapsayıcıyı alma

Veritabanından var olan bir kapsayıcıyı alın:

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)

Veri ekleme

Kapsayıcıya öğe eklemek için verilerinizi içeren bir sözlüğü ContainerProxy.upsert_item geçirin. Kapsayıcıya eklediğiniz her öğe, kapsayıcı içindeki öğeyi benzersiz olarak tanımlayan bir değere sahip bir anahtar içermelidir id .

Bu örnekte kapsayıcıya her biri benzersiz idolan birkaç öğe eklenir:

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

Verileri silme

Kapsayıcıdaki öğeleri silmek için ContainerProxy.delete_item kullanın. Cosmos DB'deki SQL API'si SQL DELETE deyimini desteklemez.

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

NOT: Bölümlenmiş koleksiyon kullanıyorsanız, yukarıdaki örnek koddaki değerinin partitionKey , koleksiyonunuzdaki bölüm anahtarı sütununun adı değil, bu öğe için bölüm anahtarının değerine ayarlanması gerekir. Bu, hem nokta okuma hem de silme işlemleri için geçerlidir.

Veritabanını sorgulama

Cosmos DB SQL API veritabanı, SQL benzeri söz dizimini kullanarak ContainerProxy.query_items ile kapsayıcıdaki öğelerin sorgulanması için destek sağlar.

Bu örnek, belirli idbir öğesine sahip öğeler için kapsayıcıyı sorgular:

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

NOT: Yan tümcesinde kapsayıcı adı için herhangi bir değer belirtebilse de FROM , tutarlılık için kapsayıcı adını kullanmanızı öneririz.

Parametreleri ve değerlerini içeren bir sözlüğü ContainerProxy.query_items geçirerek parametreli sorgular gerçekleştirin:

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

SQL API'sini kullanarak Cosmos DB veritabanlarını sorgulama hakkında daha fazla bilgi için bkz. SQL sorguları ile Azure Cosmos DB verilerini sorgulama.

Veritabanı özelliklerini alma

Veritabanının özelliklerini alma ve görüntüleme:

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

Veritabanı ve kapsayıcı aktarım hızı alma

Ayrılmış aktarım hızına sahip bir veritabanının ve kapsayıcının aktarım hızı değerlerini alın ve görüntüleyin:

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

Kapsayıcı özelliklerini değiştirme

Mevcut bir kapsayıcının belirli özellikleri değiştirilebilir. Bu örnek, kapsayıcıdaki öğeler için varsayılan yaşam süresini (TTL) 10 saniye olarak ayarlar:

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

TTL hakkında daha fazla bilgi için bkz. Azure Cosmos DB verileri için Yaşam Süresi.

Zaman uyumsuz istemciyi kullanma

Zaman uyumsuz cosmos istemcisi, mevcut zaman uyumlu istemciye benzer şekilde görünen ve çalışan ayrı bir istemcidir. Ancak, zaman uyumsuz istemcinin ayrı olarak içeri aktarılması ve yöntemlerinin async/await anahtar sözcükleriyle kullanılması gerekir. Kullanımdan sonra zaman uyumsuz istemcinin başlatılması ve kapatılması gerekir. Bu işlem el ile veya bağlam yöneticisi kullanımıyla yapılabilir. Aşağıdaki örnekte bunu el ile nasıl yapacağınız gösterilmektedir.

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

İstemciyi el ile açmak ve kapatmak yerine anahtar sözcükleri kullanmanız async with kesinlikle önerilir. Bu, deyiminden çıktıktan sonra istemciyi başlatacak ve daha sonra kapatacak bir bağlam yöneticisi oluşturur. Aşağıdaki örnekte bunun nasıl yapıldığını gösterilmektedir.

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

Zaman uyumsuz istemciyle sorgular

Zaman uyumlu istemcinin aksine, zaman uyumsuz istemcinin istekte bir enable_cross_partition bayrağı yoktur. Belirtilen bölüm anahtarı değeri olmayan sorgular varsayılan olarak çapraz bölüm sorgusu yapmayı dener.

Sorgu sonuçları yinelenebilir, ancak sorgunun ham çıkışı zaman uyumsuz bir yineleyici döndürür. Bu, yineleyicideki her nesnenin beklenebilir bir nesne olduğu ve henüz gerçek sorgu sonucunu içermediği anlamına gelir. Sorgu sonuçlarını elde etmek için, nesnede yineleme yaptığınızda her sonucu bekleyen bir zaman uyumsuz for döngüsü kullanabilir veya zaman uyumsuz yineleyici üzerinde yineleme yaptığınızda her sorgu sonucunu el ile bekleyebilirsiniz.

Sorgu sonuçları zaman uyumsuz bir yineleyici olduğundan, bunlar doğrudan listelere aktarılamaz; bunun yerine, sonuçlarınızdan listeler oluşturmanız gerekiyorsa, bir listeyi doldurmak için döngü için zaman uyumsuz veya Python'ın liste kavramasını kullanın:

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

Tümleşik Önbelleği Kullanma

Tümleşik önbellek, istek hacminiz büyüdükçe yönetilebilir maliyetler ve düşük gecikme süresi sağlamanıza yardımcı olan bir bellek içi önbellektir. Tümleşik önbelleğin iki bölümü vardır: nokta okumaları için bir öğe önbelleği ve sorgular için sorgu önbelleği. Aşağıdaki kod parçacığında bu özelliğin nokta okuma ve sorgu önbelleği yöntemleriyle nasıl kullanılacağı gösterilmektedir.

Bunu kullanmanın avantajı, noktanın okuması ve tümleşik önbelleğe isabet eden sorguların hiçbir RU kullanmamasını sağlar. Bu, işlem başına maliyetin arka uçtan gelen okumalardan çok daha düşük olacağı anlamına gelir.

Azure Cosmos DB tümleşik önbelleğini yapılandırma (Önizleme)

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)

Tümleşik Önbellek hakkında daha fazla bilgi için bkz. Azure Cosmos DB tümleşik önbelleği - Genel Bakış.

Sorun giderme

Genel

Python SDK'sını kullanarak Cosmos DB ile etkileşime geçtiğiniz zaman, hizmet tarafından döndürülen özel durumlar REST API istekleri için döndürülen aynı HTTP durum kodlarına karşılık gelir:

Azure Cosmos DB için HTTP Durum Kodları

Örneğin, Cosmos DB veritabanınızda zaten kullanımda olan bir kimlik (ad) kullanarak bir kapsayıcı oluşturmaya çalışırsanız, çakışmayı belirten bir 409 hata döndürülür. Aşağıdaki kod parçacığında hata, özel durum yakalanarak ve hata hakkında ek bilgiler görüntülenerek düzgün bir şekilde işlenir.

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

Günlüğe Kaydetme

Bu kitaplık, günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumlarıyla ilgili temel bilgiler (URL'ler, üst bilgiler vb.) BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve kaydedilmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğe kaydetme, bir istemcide şu bağımsız değişkenle logging_enable etkinleştirilebilir:

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)

Benzer şekilde, logging_enable istemci için etkinleştirilmemiş olsa bile tek bir işlem için ayrıntılı günlüğe kaydetmeyi etkinleştirebilir:

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

Alternatif olarak, günlükçünüzü logger bağımsız değişkenine geçirerek azure çekirdek HttpLoggingPolicy'den genişletilen CosmosHttpLoggingPolicy'yi kullanarak oturum açabilirsiniz. Varsayılan olarak, HttpLoggingPolicy'den gelen davranışı kullanır. bağımsız değişkeninin enable_diagnostics_logging geçirilmesi CosmosHttpLoggingPolicy'yi etkinleştirir ve Yanıtta Cosmos sorunlarının hatalarını ayıklamayla ilgili ek bilgiler bulunur.

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)

Benzer şekilde, günlükçü tekil isteğe geçirilerek tek bir işlem için günlüğe kaydetme etkinleştirilebilir. Ancak, ek bilgi edinmek için CosmosHttpLoggingPolicy kullanmak istiyorsanız, bağımsız değişkenin enable_diagnostics_logging istemci oluşturucusunda geçirilmesi gerekir.

# This example enables the CosmosHttpLoggingPolicy and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

Telemetri

Azure Core, Python SDK'larımızın OpenTelemetry'yi kullanmasına olanak sağlar. Bu işlevi kullanmak için yüklenmesi gereken paketler şunlardır:

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

Bu konuda daha fazla bilgi için Azure Core'dan bu belgeyi ayarlamayı açıklayan bir belgeyi incelemenizi öneririz. Sdk'mızla nasıl kullanılabileceğini göstermek için bir örnek dosya da ekledik. Bu, kullandığınız Cosmos istemcisi ne olursa olsun aynı şekilde çalışır.

Sonraki adımlar

Cosmos DB hizmeti hakkında daha kapsamlı belgeler için docs.microsoft.com ile ilgili Azure Cosmos DB belgelerine bakın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .