Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi lebih lanjut dan pertanyaan, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691

Pustaka klien Azure Cosmos DB SQL API untuk Python - versi 4.5.1

Azure Cosmos DB adalah layanan database multi model yang didistribusikan secara global yang mendukung database dokumen, nilai kunci, kolom lebar, dan grafik.

Gunakan Azure Cosmos DB SQL API SDK untuk Python untuk mengelola database dan dokumen JSON yang dikandungnya dalam layanan database NoSQL ini. Kemampuan tingkat tinggi adalah:

• Membuat database Cosmos DB dan mengubah pengaturannya
• Membuat dan memodifikasi kontainer untuk menyimpan koleksi dokumen JSON
• Membuat, membaca, memperbarui, dan menghapus item (dokumen JSON) di kontainer Anda
• Mengkueri dokumen dalam database Anda menggunakan sintaks seperti SQL

Kode | sumber SDKPaket (PyPI) | Paket (Conda) | Dokumentasi | referensi APIDokumentasi | produkSampel

SDK ini digunakan untuk SQL API. Untuk semua API lainnya, silakan periksa dokumentasi Azure Cosmos DB untuk mengevaluasi SDK terbaik untuk proyek Anda.

Memulai

Pembaruan penting tentang Dukungan Python 2.x

Rilis baru SDK ini tidak akan mendukung Python 2.x mulai 1 Januari 2022. Untuk informasi lebih lanjut, periksa CHANGELOG.

Prasyarat

• Langganan Azure - Membuat akun gratis
• Akun Azure Cosmos DB - SQL API
• Python 3.6+

Jika Anda memerlukan akun Cosmos DB SQL API, Anda dapat membuatnya dengan perintah Azure CLI ini:

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

Instal paketnya

pip install azure-cosmos

Mengonfigurasi lingkungan virtual (opsional)

Meskipun tidak diperlukan, Anda dapat menjaga sistem dasar dan lingkungan Azure SDK Anda terisolasi satu sama lain jika Anda menggunakan lingkungan virtual. Jalankan perintah berikut untuk mengonfigurasi lalu masukkan lingkungan virtual dengan venv:

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

Mengautentikasi klien

Interaksi dengan Cosmos DB dimulai dengan instans kelas CosmosClient . Anda memerlukan akun, URI-nya, dan salah satu kunci akunnya untuk membuat instans objek klien.

Gunakan cuplikan Azure CLI di bawah ini untuk mengisi dua variabel lingkungan dengan URI akun database dan kunci master utamanya (Anda juga dapat menemukan nilai-nilai ini di portal Azure). Cuplikan diformat untuk shell 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)

Membuat klien

Setelah mengisi ACCOUNT_URI variabel lingkungan dan ACCOUNT_KEY , Anda dapat membuat CosmosClient.

from azure.cosmos import CosmosClient

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

Autentikasi AAD

Anda juga dapat mengautentikasi klien yang menggunakan kredensial AAD perwakilan layanan Anda dan paket identitas azure. Anda dapat langsung meneruskan informasi kredensial ke ClientSecretCredential, atau menggunakan 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)

Selalu pastikan bahwa identitas terkelola yang Anda gunakan untuk autentikasi AAD memiliki readMetadata izin.
Informasi selengkapnya tentang cara menyiapkan autentikasi AAD: Menyiapkan RBAC untuk autentikasi AAD
Informasi selengkapnya tentang operasi yang diizinkan untuk klien terautentikasi AAD: Model Izin RBAC

Konsep utama

Setelah Anda menginisialisasi CosmosClient, Anda dapat berinteraksi dengan jenis sumber daya utama di Cosmos DB:

• Database: Akun Cosmos DB dapat berisi banyak database. Saat membuat database, Anda menentukan API yang ingin Anda gunakan saat berinteraksi dengan dokumen database: SQL, MongoDB, Gremlin, Cassandra, atau Azure Table. Gunakan objek DatabaseProxy untuk mengelola kontainernya.

• Kontainer: Kontainer adalah kumpulan dokumen JSON. Anda membuat (menyisipkan), membaca, memperbarui, dan menghapus item dalam kontainer dengan menggunakan metode pada objek ContainerProxy .

• Item: Item adalah representasi seperti kamus dari dokumen JSON yang disimpan dalam kontainer. Setiap Item yang Anda tambahkan ke kontainer harus menyertakan id kunci dengan nilai yang secara unik mengidentifikasi item dalam kontainer.

Untuk informasi selengkapnya tentang sumber daya ini, lihat Bekerja dengan database, kontainer, dan item Azure Cosmos.

Cara menggunakan enable_cross_partition_query

Argumen kata enable_cross_partition_query kunci menerima 2 opsi: None (default) atau True.

Catatan tentang menggunakan kueri menurut id

Saat menggunakan kueri yang mencoba menemukan item berdasarkan nilai id , selalu pastikan Anda meneruskan variabel jenis string. Azure Cosmos DB hanya mengizinkan nilai id string dan jika Anda menggunakan jenis data lainnya, SDK ini tidak akan mengembalikan hasil dan tidak ada pesan kesalahan.

Catatan tentang tingkat konsistensi klien

Pada rilis versi 4.3.0b3, jika pengguna tidak meneruskan tingkat konsistensi eksplisit ke inisialisasi klien mereka, klien mereka akan menggunakan tingkat default akun database mereka. Sebelumnya, default sedang diatur ke Session konsistensi. Jika karena alasan tertentu Anda ingin terus melakukan ini, Anda dapat mengubah inisialisasi klien untuk menyertakan parameter eksplisit untuk ini seperti yang ditunjukkan:

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

Batasan

Saat ini, fitur di bawah ini tidak didukung. Untuk opsi alternatif, periksa bagian Solusi di bawah ini.

Batasan Sarana Data:

• Kelompokkan Menurut kueri
• Kueri dengan COUNT dari subkueri DISTINCT: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Pemrosesan batch Massal/Transaksi
• Akses Mode TCP Langsung
• Dukungan token kelanjutan untuk kueri lintas partisi agregat seperti pengurutan, penghitungan, dan perbedaan. Kueri yang dapat dialirkan seperti SELECT * FROM WHEREmendukung token kelanjutan.
• Umpan Perubahan: Prosesor
• Umpan Perubahan: Membaca beberapa nilai kunci partisi
• Umpan Perubahan: Membaca waktu tertentu
• Ubah Umpan: Baca dari awal
• Umpan Perubahan: Model penarikan
• ORDER BY lintas partisi untuk jenis campuran
• Mengaktifkan diagnostik untuk metode jenis kueri asinkron

Batasan Sarana Kontrol:

• Mendapatkan metrik CollectionSizeUsage, DatabaseUsage, dan DocumentUsage
• Membuat Indeks Geospasial
• Dapatkan string koneksi
• Mendapatkan RU/dtk minimum kontainer

Penyelesaian masalah

Solusi Batasan Pemrosesan Massal

Jika Anda ingin menggunakan Python SDK untuk melakukan penyisipan massal ke Cosmos DB, alternatif terbaik adalah menggunakan prosedur tersimpan untuk menulis beberapa item dengan kunci partisi yang sama.

Solusi Batasan Sarana Kontrol

Biasanya, Anda dapat menggunakan Portal Microsoft Azure, REST API Penyedia Sumber Daya Azure Cosmos DB, Azure CLI , atau PowerShell untuk batasan sarana kontrol yang tidak didukung.

Jenis Data Boolean

Sementara bahasa Python menggunakan "True" dan "False" untuk jenis boolean, Cosmos DB hanya menerima "true" dan "false". Dengan kata lain, bahasa Python menggunakan nilai Boolean dengan huruf besar pertama dan semua huruf kecil lainnya, sementara Cosmos DB dan bahasa SQL-nya hanya menggunakan huruf kecil untuk nilai Boolean yang sama. Bagaimana cara menghadapi tantangan ini?

• Dokumen JSON Anda yang dibuat dengan Python harus menggunakan "True" dan "False", untuk melewati validasi bahasa. SDK akan mengonversinya menjadi "true" dan "false" untuk Anda. Artinya "true" dan "false" adalah apa yang akan disimpan di Cosmos DB.
• Jika Anda mengambil dokumen tersebut dengan Data Explorer Portal Cosmos DB, Anda akan melihat "true" dan "false".
• Jika Anda mengambil dokumen tersebut dengan Python SDK ini, nilai "true" dan "false" akan secara otomatis dikonversi ke "True" dan "False".

Kueri SQL x Subitem Klausa FROM

SDK ini menggunakan metode query_items untuk mengirimkan kueri SQL ke Azure Cosmos DB.

Bahasa Cosmos DB SQL memungkinkan Anda mendapatkan subitem dengan menggunakan klausa FROM, untuk mengurangi sumber ke subset yang lebih kecil. Sebagai contoh, Anda dapat menggunakan select * from Families.children alih-alih select * from Families. Tapi harap dicatat bahwa:

• Untuk kueri SQL menggunakan query_items metode , SDK ini menuntut Anda menentukan partition_key atau menggunakan enable_cross_partition_query bendera .
• Jika Anda mendapatkan subitem dan menentukan partition_key, pastikan bahwa kunci partisi Anda disertakan dalam subitem, yang tidak benar untuk sebagian besar kasus.

Jumlah Maksimal Item

Ini adalah parameter metode query_items, bilangan bulat yang menunjukkan jumlah maksimum item yang akan dikembalikan per halaman. Nilai None dapat ditentukan untuk membiarkan layanan menentukan jumlah item yang optimal. Ini adalah nilai konfigurasi yang direkomendasikan, dan perilaku default SDK ini ketika tidak diatur.

Contoh

Bagian berikut menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Cosmos DB yang paling umum, termasuk:

• Membuat database
• Membuat kontainer
• Membuat kontainer yang diaktifkan penyimpanan analitis
• Mendapatkan kontainer yang sudah ada
• Menyisipkan data
• Menghapus data
• Mengkueri database
• Mendapatkan properti database
• Mendapatkan throughput database dan kontainer
• Mengubah properti kontainer
• Menggunakan klien asinkron

Buat database

Setelah mengautentikasi CosmosClient, Anda dapat bekerja dengan semua sumber daya di akun. Cuplikan kode di bawah ini membuat database SQL API, yang merupakan default ketika tidak ada API yang ditentukan saat create_database dipanggil.

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)

Buat kontainer

Contoh ini membuat kontainer dengan pengaturan default. Jika kontainer dengan nama yang sama sudah ada dalam database (menghasilkan 409 Conflict kesalahan), kontainer yang ada diperoleh sebagai gantinya.

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

Membuat kontainer yang didukung penyimpanan analitik

Contoh ini membuat kontainer dengan Analytical Store diaktifkan, untuk pelaporan, BI, AI, dan Advanced Analytics dengan Azure Synapse Link.

Opsi untuk analytical_storage_ttl adalah:

• 0 atau Null atau tidak diinformasikan: Tidak diaktifkan.
• -1: Data akan disimpan tanpa batas.
• Angka lain: ttl aktual, dalam hitungan detik.

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

Cuplikan sebelumnya juga menangani pengecualian CosmosHttpResponseError jika pembuatan kontainer gagal. Untuk informasi selengkapnya tentang penanganan kesalahan dan pemecahan masalah, lihat bagian .

Mendapatkan kontainer yang sudah ada

Ambil kontainer yang sudah ada dari database:

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

Menyisipkan data

Untuk menyisipkan item ke dalam kontainer, teruskan kamus yang berisi data Anda ke ContainerProxy.upsert_item. Setiap item yang Anda tambahkan ke kontainer harus menyertakan id kunci dengan nilai yang secara unik mengidentifikasi item dalam kontainer.

Contoh ini menyisipkan beberapa item ke dalam kontainer, masing-masing dengan yang unik 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)
        }
    )

Menghapus data

Untuk menghapus item dari kontainer, gunakan ContainerProxy.delete_item. SQL API di Cosmos DB tidak mendukung pernyataan 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')

CATATAN: Jika Anda menggunakan koleksi yang dipartisi, nilai partitionKey dalam contoh kode di atas, harus diatur ke nilai kunci partisi untuk item tertentu ini, bukan nama kolom kunci partisi dalam koleksi Anda. Ini berlaku untuk pembacaan dan penghapusan titik.

Mengkueri database

Database Cosmos DB SQL API mendukung kueri item dalam kontainer dengan ContainerProxy.query_items menggunakan sintaks seperti SQL.

Contoh ini mengkueri kontainer untuk item dengan :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))

CATATAN: Meskipun Anda dapat menentukan nilai apa pun untuk nama kontainer dalam FROM klausul , kami sarankan Anda menggunakan nama kontainer untuk konsistensi.

Lakukan kueri berparameter dengan meneruskan kamus yang berisi parameter dan nilainya untuk 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))

Untuk informasi selengkapnya tentang mengkueri database Cosmos DB menggunakan API SQL, lihat Mengkueri data Azure Cosmos DB dengan kueri SQL.

Mendapatkan properti database

Dapatkan dan tampilkan properti database:

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

Mendapatkan throughput database dan kontainer

Dapatkan dan tampilkan nilai throughput database dan kontainer dengan throughput khusus:

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

Mengubah properti kontainer

Properti tertentu dari kontainer yang ada dapat dimodifikasi. Contoh ini mengatur time to live (TTL) default untuk item dalam kontainer menjadi 10 detik:

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

Untuk informasi selengkapnya tentang TTL, lihat Data Time to Live for Azure Cosmos DB.

Menggunakan klien asinkron

Klien kosmos asinkron adalah klien terpisah yang terlihat dan bekerja dengan cara yang sama dengan klien sinkron yang ada. Namun, klien asinkron perlu diimpor secara terpisah dan metodenya perlu digunakan dengan kata kunci asinkron/menunggu. Klien Asinkron perlu diinisialisasi dan ditutup setelah penggunaan, yang dapat dilakukan secara manual atau dengan penggunaan manajer konteks. Contoh di bawah ini menunjukkan cara melakukannya secara manual.

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

Alih-alih membuka dan menutup klien secara manual, sangat disarankan untuk menggunakan async with kata kunci. Ini membuat manajer konteks yang akan menginisialisasi dan kemudian menutup klien setelah Anda keluar dari pernyataan. Contoh di bawah ini menunjukkan cara melakukannya.

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

Kueri dengan klien asinkron

Tidak seperti klien sinkron, klien asinkron tidak memiliki enable_cross_partition bendera dalam permintaan. Kueri tanpa nilai kunci partisi tertentu akan mencoba melakukan kueri lintas partisi secara default.

Hasil kueri dapat diulang, tetapi output mentah kueri mengembalikan iterator asinkron. Ini berarti bahwa setiap objek dari iterator adalah objek yang dapat ditunggu, dan belum berisi hasil kueri yang sebenarnya. Untuk mendapatkan hasil kueri, Anda dapat menggunakan asinkron untuk perulangan, yang menunggu setiap hasil saat Anda melakukan iterasi pada objek, atau secara manual menunggu setiap hasil kueri saat Anda melakukan iterasi melalui iterator asinkron.

Karena hasil kueri adalah iterator asinkron, mereka tidak dapat ditransmisikan ke dalam daftar secara langsung; sebagai gantinya, jika Anda perlu membuat daftar dari hasil Anda, gunakan asinkron untuk perulangan atau pemahaman daftar Python untuk mengisi daftar:

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

Menggunakan Cache Terintegrasi

Cache terintegrasi adalah cache dalam memori yang membantu Anda memastikan biaya yang dapat dikelola dan latensi rendah saat volume permintaan Anda tumbuh. Cache terintegrasi memiliki dua bagian: cache item untuk pembacaan titik dan cache kueri untuk kueri. Cuplikan kode di bawah ini menunjukkan kepada Anda cara menggunakan fitur ini dengan metode baca titik dan cache kueri.

Manfaat menggunakan ini adalah bahwa titik baca dan kueri yang mencapai cache terintegrasi tidak akan menggunakan RU apa pun. Ini berarti Anda akan memiliki biaya per operasi yang jauh lebih rendah daripada bacaan dari backend.

Cara mengonfigurasi cache terintegrasi Azure Cosmos DB (Pratinjau)

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)

Untuk informasi selengkapnya tentang Cache Terintegrasi, lihat Cache terintegrasi Azure Cosmos DB - Gambaran Umum.

Pemecahan Masalah

Umum

Saat Anda berinteraksi dengan Cosmos DB menggunakan Python SDK, pengecualian yang dikembalikan oleh layanan sesuai dengan kode status HTTP yang sama yang dikembalikan untuk permintaan REST API:

Kode Status HTTP untuk Azure Cosmos DB

Misalnya, jika Anda mencoba membuat kontainer menggunakan ID (nama) yang sudah digunakan dalam database Cosmos DB Anda, kesalahan 409 dikembalikan, menunjukkan konflik. Dalam cuplikan berikut, kesalahan ditangani dengan baik dengan menangkap pengecualian dan menampilkan informasi tambahan tentang kesalahan tersebut.

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

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaksikan, dapat diaktifkan pada klien dengan logging_enable argumen :

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)

Demikian pula, logging_enable dapat mengaktifkan pengelogan mendetail untuk satu operasi, meskipun tidak diaktifkan untuk klien:

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

Atau, Anda bisa masuk menggunakan CosmosHttpLoggingPolicy, yang meluas dari inti azure HttpLoggingPolicy, dengan meneruskan pencatat Anda ke logger argumen . Secara default, ini akan menggunakan perilaku dari HttpLoggingPolicy. Meneruskan enable_diagnostics_logging argumen akan mengaktifkan CosmosHttpLoggingPolicy, dan akan memiliki informasi tambahan dalam respons yang relevan dengan penelusuran kesalahan masalah 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)

Demikian pula, pengelogan dapat diaktifkan untuk satu operasi dengan meneruskan pencatat ke permintaan tunggal. Namun, jika Anda ingin menggunakan CosmosHttpLoggingPolicy untuk mendapatkan informasi tambahan, enable_diagnostics_logging argumen perlu diteruskan di konstruktor klien.

# 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 menyediakan kemampuan bagi SDK Python kami untuk menggunakan OpenTelemetry dengannya. Satu-satunya paket yang perlu diinstal untuk menggunakan fungsi ini adalah sebagai berikut:

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

Untuk informasi selengkapnya tentang ini, sebaiknya lihat dokumen ini dari Azure Core yang menjelaskan cara menyiapkannya. Kami juga telah menambahkan file sampel untuk menunjukkan bagaimana file tersebut dapat digunakan dengan SDK kami. Ini bekerja dengan cara yang sama terlepas dari klien Cosmos yang Anda gunakan.

Langkah berikutnya

Untuk dokumentasi yang lebih lengkap tentang layanan Cosmos DB, lihat dokumentasi Azure Cosmos DB di docs.microsoft.com.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.