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: Any, consistency_level: str | None = None, **kwargs: Any)

Parameter

url

str

Diperlukan

URL akun Cosmos DB.

credential

Union[str, Dict[str, str], TokenCredential]

Diperlukan

Dapat berupa kunci akun, atau kamus token sumber daya.

consistency_level

str

nilai default: None

Tingkat konsistensi yang digunakan untuk sesi. Nilai defaultnya adalah Tidak Ada (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:

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

Metode

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_account	Ambil informasi akun database.
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.

create_database

Buat database baru dengan ID (nama) yang diberikan.

create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Parameter

id

Diperlukan

ID (nama) database yang akan dibuat.

offer_throughput

Diperlukan

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

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 = 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.

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Parameter

id

Diperlukan

ID (nama) database yang akan dibaca atau dibuat.

populate_query_metrics

bool

Diperlukan

Aktifkan mengembalikan metrik kueri di header respons.

offer_throughput

int atau <xref:azure.cosmos.ThroughputProperties.>

Diperlukan

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

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.

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

Parameter

database

str atau dict(str, str) atau DatabaseProxy

Diperlukan

ID (nama), dict yang mewakili properti atau <xref:azure.cosmos.cosmos_client.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

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: Any | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Parameter

conn_str

str

Diperlukan

String koneksi.

credential

str atau dict(str, str)

nilai default: None

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

consistency_level

Optional[str]

nilai default: None

Tingkat konsistensi yang digunakan untuk sesi. Nilai defaultnya adalah Tidak Ada (Tingkat akun).

Pengecualian

CosmosResourceExistsError

Database dengan ID yang diberikan sudah ada.

get_database_account

Ambil informasi akun database.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parameter

response_hook

Callable

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Instans DatabaseAccount yang mewakili Akun Database Cosmos DB.

Tipe hasil

DatabaseAccount

Pengecualian

CosmosResourceExistsError

Database dengan ID yang diberikan sudah ada.

get_database_client

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

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

Parameter

database

str atau dict(str, str) atau DatabaseProxy

Diperlukan

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

Mengembalikan

Instans DatabaseProxy yang mewakili database yang diambil.

Tipe hasil

DatabaseProxy

Pengecualian

CosmosResourceExistsError

Database dengan ID yang diberikan sudah ada.

list_databases

Mencantumkan database dalam akun database Cosmos DB SQL.

list_databases(max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parameter

max_item_count

int

Diperlukan

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

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Iterable properti database (dicts).

Tipe hasil

Iterable[dict[str, str]]

Pengecualian

CosmosResourceExistsError

Database dengan ID yang diberikan sudah ada.

query_databases

Mengkueri database dalam akun database Cosmos DB SQL.

query_databases(query: str | None = None, parameters: List[Dict[str, Any]] | None = None, enable_cross_partition_query: bool | None = None, max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parameter

query

str

Diperlukan

Kueri Azure Cosmos DB SQL untuk dijalankan.

parameters

List[Dict[str, Any]]

Diperlukan

Array parameter opsional ke kueri. Diabaikan jika tidak ada kueri yang disediakan.

enable_cross_partition_query

bool

Diperlukan

Izinkan pemindaian pada kueri yang tidak dapat dilayani karena pengindeksan ditolak pada jalur yang diminta.

max_item_count

int

Diperlukan

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

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Iterable properti database (dicts).

Tipe hasil

Iterable[dict[str, str]]

Pengecualian

CosmosResourceExistsError

Database dengan ID yang diberikan sudah ada.