CosmosClient Kelas

Representasi logis sisi klien dari akun Azure Cosmos DB.

Gunakan klien ini untuk mengonfigurasi dan menjalankan permintaan ke layanan Azure Cosmos DB.

Disarankan untuk mempertahankan satu instans CosmosClient per masa pakai aplikasi yang memungkinkan manajemen dan performa koneksi yang efisien.

Inisialisasi CosmosClient adalah operasi berat - jangan gunakan inisialisasi instans CosmosClient sebagai kredensial atau validasi konektivitas jaringan.

Buat instans CosmosClient baru.

Warisan

builtins.object

CosmosClient

Konstruktor

CosmosClient(url: str, credential: str | Dict[str, str] | TokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

Parameter

url

str

Diperlukan

URL akun Cosmos DB.

credential

Union[str, Dict[str, str], AsyncTokenCredential]

Diperlukan

Dapat berupa kunci akun, atau kamus token sumber daya.

consistency_level

str

Tingkat konsistensi yang digunakan untuk sesi. Nilai defaultnya adalah None (tingkat akun). Selengkapnya tentang tingkat konsistensi dan nilai yang mungkin: https://aka.ms/cosmos-consistency-levels

timeout

int

Batas waktu absolut dalam hitungan detik, untuk gabungan permintaan HTTP dan pemrosesan respons.

connection_timeout

int

Batas waktu permintaan HTTP dalam hitung detik.

connection_mode

str

Mode koneksi untuk klien - saat ini hanya mendukung 'Gateway'.

proxy_config

ProxyConfiguration

Konfigurasi proksi koneksi.

ssl_config

SSLConfiguration

Konfigurasi SSL koneksi.

connection_verify

bool

Apakah akan memverifikasi koneksi, nilai defaultnya adalah True.

connection_cert

str

Sertifikat alternatif untuk memverifikasi koneksi.

retry_total

int

Upaya coba lagi maksimum.

retry_backoff_max

int

Waktu tunggu coba lagi maksimum dalam detik.

retry_fixed_interval

int

Memperbaiki interval coba lagi dalam milidetik.

retry_read

int

Jumlah maksimum upaya coba lagi baca soket.

retry_connect

int

Jumlah maksimum upaya coba lagi kesalahan koneksi.

retry_status

int

Jumlah maksimum upaya coba lagi pada kode status kesalahan.

retry_on_status_codes

list[int]

Daftar kode status tertentu untuk mencoba kembali.

retry_backoff_factor

float

Faktor untuk menghitung waktu tunggu antara upaya coba lagi.

enable_endpoint_discovery

bool

Aktifkan penemuan titik akhir untuk akun database yang direplikasi secara geografis. (Default: True)

preferred_locations

list[str]

Lokasi yang disukai untuk akun database yang direplikasi secara geografis.

enable_diagnostics_logging

bool

Aktifkan kebijakan CosmosHttpLogging. Harus digunakan bersama dengan pencatat untuk bekerja.

logger

Logger

Pencatat yang akan digunakan untuk mengumpulkan diagnostik permintaan. Dapat diteruskan di tingkat klien (untuk mencatat semua permintaan) atau pada satu tingkat permintaan. Permintaan akan dicatat di tingkat INFO.

Contoh

Buat instans baru klien Cosmos DB:

       async with CosmosClient(url, key) as client:

Metode

close	Tutup instans CosmosClient ini.
create_database	Buat database baru dengan ID (nama) yang diberikan.
create_database_if_not_exists	Buat database jika belum ada. Jika database sudah ada, pengaturan yang ada akan dikembalikan. .. catatan:: Fungsi ini tidak memeriksa atau memperbarui pengaturan database yang ada atau menawarkan throughput jika berbeda dari apa yang diteruskan.
delete_database	Hapus database dengan ID (nama) yang diberikan.
from_connection_string	Buat instans CosmosClient dari string koneksi. Ini dapat diambil dari portal Azure. Untuk daftar lengkap argumen kata kunci opsional, lihat konstruktor CosmosClient.
get_database_client	Ambil database yang sudah ada dengan ID (nama) id.
list_databases	Mencantumkan database dalam akun database Cosmos DB SQL.
query_databases	Mengkueri database dalam akun database Cosmos DB SQL.

close

Tutup instans CosmosClient ini.

async close() -> None

create_database

Buat database baru dengan ID (nama) yang diberikan.

async create_database(id: str, **kwargs: Any) -> DatabaseProxy

Parameter

id

str

Diperlukan

ID (nama) database yang akan dibuat.

offer_throughput

Union[int, ThroughputProperties]

Throughput yang disediakan untuk penawaran ini.

session_token

str

Token untuk digunakan dengan konsistensi Sesi.

initial_headers

dict[str, str]

Header awal yang akan dikirim sebagai bagian dari permintaan.

etag

str

Nilai ETag, atau karakter kartubebas (*). Digunakan untuk memeriksa apakah sumber daya telah berubah, dan bertindak sesuai dengan kondisi yang ditentukan oleh parameter match_condition .

match_condition

MatchConditions

Kondisi kecocokan untuk digunakan pada etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Instans DatabaseProxy yang mewakili database baru.

Tipe hasil

DatabaseProxy

Pengecualian

CosmosResourceExistsError

Database dengan ID yang diberikan sudah ada.

Contoh

Buat database di akun Cosmos DB:

           database_name = "testDatabase"
           try:
               database = await client.create_database(id=database_name)
           except exceptions.CosmosResourceExistsError:
               database = client.get_database_client(database=database_name)

create_database_if_not_exists

Buat database jika belum ada.

Jika database sudah ada, pengaturan yang ada akan dikembalikan.

.. catatan:: Fungsi ini tidak memeriksa atau memperbarui pengaturan database yang ada atau menawarkan throughput jika berbeda dari apa yang diteruskan.

async create_database_if_not_exists(id: str, **kwargs: Any) -> DatabaseProxy

Parameter

id

str

Diperlukan

ID (nama) database yang akan dibaca atau dibuat.

offer_throughput

Union[int, ThroughputProperties]

Throughput yang disediakan untuk penawaran ini.

session_token

str

Token untuk digunakan dengan konsistensi Sesi.

initial_headers

dict[str, str]

Header awal yang akan dikirim sebagai bagian dari permintaan.

etag

str

Nilai ETag, atau karakter kartubebas (*). Digunakan untuk memeriksa apakah sumber daya telah berubah, dan bertindak sesuai dengan kondisi yang ditentukan oleh parameter match_condition .

match_condition

MatchConditions

Kondisi kecocokan untuk digunakan pada etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Instans DatabaseProxy yang mewakili database.

Tipe hasil

DatabaseProxy

Pengecualian

CosmosHttpResponseError

Pembacaan atau pembuatan database gagal.

delete_database

Hapus database dengan ID (nama) yang diberikan.

async delete_database(database: str | DatabaseProxy | Dict[str, Any], **kwargs: Any) -> None

Parameter

database

Union[str, DatabaseProxy, Dict[str, Any]]

Diperlukan

ID (nama), dict yang mewakili properti, atau DatabaseProxy instans database yang akan dihapus.

session_token

str

Token untuk digunakan dengan konsistensi Sesi.

initial_headers

dict[str, str]

Header awal yang akan dikirim sebagai bagian dari permintaan.

etag

str

Nilai ETag, atau karakter kartubebas (*). Digunakan untuk memeriksa apakah sumber daya telah berubah, dan bertindak sesuai dengan kondisi yang ditentukan oleh parameter match_condition .

match_condition

MatchConditions

Kondisi kecocokan untuk digunakan pada etag.

response_hook

Callable[[Dict[str, str]], None]

Panggilan yang dipanggil dengan metadata respons.

Tipe hasil

None

Pengecualian

CosmosHttpResponseError

Jika database tidak dapat dihapus.

from_connection_string

Buat instans CosmosClient dari string koneksi.

Ini dapat diambil dari portal Azure. Untuk daftar lengkap argumen kata kunci opsional, lihat konstruktor CosmosClient.

from_connection_string(conn_str: str, *, credential: str | Dict[str, str] | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Parameter

conn_str

str

Diperlukan

String koneksi.

credential

Union[str, Dict[str, str]]

Kredensial alternatif untuk digunakan alih-alih kunci yang disediakan dalam string koneksi.

consistency_level

str

Tingkat konsistensi yang digunakan untuk sesi. Nilai defaultnya adalah None (tingkat akun). Selengkapnya tentang tingkat konsistensi dan nilai yang mungkin: https://aka.ms/cosmos-consistency-levels

Mengembalikan

instans CosmosClient

Tipe hasil

CosmosClient

get_database_client

Ambil database yang sudah ada dengan ID (nama) id.

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

Parameter

database

Union[str, DatabaseProxy, Dict[str, Any]]

Diperlukan

ID (nama), dict yang mewakili properti, atau DatabaseProxy instans database yang akan didapatkan.

Mengembalikan

Instans DatabaseProxy yang mewakili database yang diambil.

Tipe hasil

DatabaseProxy

list_databases

Mencantumkan database dalam akun database Cosmos DB SQL.

list_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parameter

max_item_count

int

Jumlah maksimum item yang akan dikembalikan dalam operasi enumerasi.

session_token

str

Token untuk digunakan dengan konsistensi Sesi.

initial_headers

dict[str, str]

Header awal yang akan dikirim sebagai bagian dari permintaan.

response_hook

Callable[[Dict[str, str]], None]

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

AsyncItemPaged dari properti database (dicts).

Tipe hasil

<xref:AsyncItemPaged>[Dict[str, str]]

query_databases

Mengkueri database dalam akun database Cosmos DB SQL.

query_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parameter

query

Union[str, Dict[str, Any]]

Kueri Azure Cosmos DB SQL untuk dijalankan.

parameters

List[Dict[str, Any]]

Array parameter opsional ke kueri. Setiap parameter adalah dict() dengan kunci 'nama' dan 'nilai'.

max_item_count

int

Jumlah maksimum item yang akan dikembalikan dalam operasi enumerasi.

session_token

str

Token untuk digunakan dengan konsistensi Sesi.

initial_headers

dict[str, str]

Header awal yang akan dikirim sebagai bagian dari permintaan.

response_hook

Callable[[Dict[str, str]], None]

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

AsyncItemPaged dari properti database (dicts).

Tipe hasil

<xref:AsyncItemPaged>[Dict[str, str]]