Bagikan melalui

DatabaseProxy Kelas

  • Referensi

Antarmuka untuk berinteraksi dengan database tertentu.

Kelas ini tidak boleh diinstansiasi secara langsung. Sebagai gantinya, gunakan metode .get_database_client

Database berisi satu atau beberapa kontainer, yang masing-masing dapat berisi item, prosedur tersimpan, pemicu, dan fungsi yang ditentukan pengguna.

Database juga dapat memiliki pengguna terkait, yang masing-masing dikonfigurasi dengan sekumpulan izin untuk mengakses kontainer tertentu, prosedur tersimpan, pemicu, fungsi yang ditentukan pengguna, atau item.

Database Azure Cosmos DB SQL API memiliki properti yang dihasilkan sistem berikut. Properti ini bersifat baca-saja:

  • _rid: ID sumber daya.

  • _ts: Kapan sumber daya terakhir diperbarui. Nilainya adalah tanda waktu.

  • _self: URI unik yang dapat diatasi untuk sumber daya.

  • _etag: Etag sumber daya yang diperlukan untuk kontrol konkurensi optimis.

  • _colls: Jalur sumber daya koleksi yang dapat diatasi.

  • _users: Jalur sumber daya pengguna yang dapat diatasi.

Warisan
builtins.object
DatabaseProxy

Konstruktor

DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)

Parameter

client_connection
<xref:ClientSession>
Diperlukan

Klien tempat database ini diambil.

id
str
Diperlukan

ID (nama) database.

properties
nilai default: None

Variabel

id

ID (nama) database.

Metode

create_container

Buat kontainer baru dengan ID (nama) yang diberikan.

Jika kontainer dengan ID yang diberikan sudah ada, CosmosResourceExistsError akan dinaikkan.
create_container_if_not_exists

Buat kontainer jika belum ada.

Jika kontainer sudah ada, pengaturan yang ada akan dikembalikan. Catatan: ini tidak memeriksa atau memperbarui pengaturan kontainer yang ada atau menawarkan throughput jika mereka berbeda dari apa yang diteruskan ke dalam metode.
create_user

Buat pengguna baru di kontainer.

Untuk memperbarui atau mengganti pengguna yang sudah ada, gunakan metode .<xref:ContainerProxy.upsert_user>
delete_container

Hapus kontainer.
delete_user

Hapus pengguna yang ditentukan dari kontainer.
get_container_client

Dapatkan ContainerProxy untuk kontainer dengan ID (nama) tertentu.
get_throughput

Dapatkan objek ThroughputProperties untuk database ini. Jika tidak ada ThroughputProperties yang sudah ada untuk database, pengecualian akan dinaikkan. :keyword Callable response_hook: Panggilan yang dipanggil dengan metadata respons. :returns: ThroughputProperties untuk database. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Tidak ada properti throughput untuk kontainer atau

properti throughput tidak dapat diambil.
get_user_client

Dapatkan UserProxy untuk pengguna dengan ID tertentu.
list_containers

Mencantumkan kontainer dalam database.
list_users

Mencantumkan semua pengguna dalam kontainer.
query_containers

Mencantumkan properti untuk kontainer dalam database saat ini.
query_users

Mengembalikan semua pengguna yang cocok dengan kueri yang diberikan.
read

Membaca properti database.
read_offer

Dapatkan objek ThroughputProperties untuk database ini. Jika tidak ada ThroughputProperties yang sudah ada untuk database, pengecualian akan dinaikkan. :keyword Callable response_hook: Panggilan yang dipanggil dengan metadata respons. :returns: ThroughputProperties untuk database. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Tidak ada properti throughput untuk kontainer atau

properti throughput tidak dapat diambil.
replace_container

Reset properti kontainer.

Perubahan properti segera dipertahankan. Properti apa pun yang tidak ditentukan akan diatur ulang ke nilai defaultnya.
replace_throughput

Ganti throughput tingkat database.
replace_user

Menggantikan pengguna yang ditentukan jika ada dalam kontainer.
upsert_user

Sisipkan atau perbarui pengguna yang ditentukan.

Jika pengguna sudah ada dalam kontainer, pengguna akan diganti. Jika pengguna belum ada, pengguna akan dimasukkan.

create_container

Buat kontainer baru dengan ID (nama) yang diberikan.

Jika kontainer dengan ID yang diberikan sudah ada, CosmosResourceExistsError akan dinaikkan.

create_container(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Parameter

id
Diperlukan

ID (nama) kontainer yang akan dibuat.

partition_key
Diperlukan

Kunci partisi yang digunakan untuk kontainer.

indexing_policy
Diperlukan

Kebijakan pengindeksan yang akan diterapkan ke kontainer.

default_ttl
Diperlukan

Waktu hidup (TTL) default untuk item dalam kontainer. Jika tidak ditentukan, item tidak akan kedaluwarsa.

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

Throughput yang disediakan untuk penawaran ini.

unique_key_policy
Diperlukan

Kebijakan kunci unik untuk diterapkan ke kontainer.

conflict_resolution_policy
Diperlukan

Kebijakan penyelesaian konflik untuk diterapkan ke kontainer.

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.

analytical_storage_ttl
int

Time to live (TTL) penyimpanan analitis untuk item dalam kontainer. Nilai Tidak Ada membuat penyimpanan analitis nonaktif dan nilai -1 mengaktifkan penyimpanan analitis tanpa TTL. Harap dicatat bahwa penyimpanan analitik hanya dapat diaktifkan pada akun yang diaktifkan Synapse Link.

Mengembalikan

Instans ContainerProxy yang mewakili kontainer baru.

Tipe hasil

ContainerProxy

Pengecualian

CosmosHttpResponseError

Pembuatan kontainer gagal.

Contoh

Buat kontainer dengan pengaturan default:


   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)

Buat kontainer dengan pengaturan tertentu; dalam hal ini, kunci partisi kustom:


   customer_container_name = "customers"
   try:
       customer_container = database.create_container(
           id=customer_container_name,
           partition_key=PartitionKey(path="/city"),
           default_ttl=200,
       )
   except exceptions.CosmosResourceExistsError:
       customer_container = database.get_container_client(customer_container_name)

create_container_if_not_exists

Buat kontainer jika belum ada.

Jika kontainer sudah ada, pengaturan yang ada akan dikembalikan. Catatan: ini tidak memeriksa atau memperbarui pengaturan kontainer yang ada atau menawarkan throughput jika mereka berbeda dari apa yang diteruskan ke dalam metode.

create_container_if_not_exists(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Parameter

id
Diperlukan

ID (nama) kontainer untuk dibaca atau dibuat.

partition_key
Diperlukan

Kunci partisi yang digunakan untuk kontainer.

indexing_policy
Diperlukan

Kebijakan pengindeksan yang akan diterapkan ke kontainer.

default_ttl
Diperlukan

Waktu hidup (TTL) default untuk item dalam kontainer. Jika tidak ditentukan, item tidak akan kedaluwarsa.

populate_query_metrics
Diperlukan

Aktifkan metrik kueri yang dikembalikan di header respons.

offer_throughput
Diperlukan

Throughput yang disediakan untuk penawaran ini.

unique_key_policy
Diperlukan

Kebijakan kunci unik untuk diterapkan ke kontainer.

conflict_resolution_policy
Diperlukan

Kebijakan penyelesaian konflik untuk diterapkan ke kontainer.

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.

analytical_storage_ttl
int

Time to live (TTL) penyimpanan analitis untuk item dalam kontainer. Nilai Tidak Ada membuat penyimpanan analitis nonaktif dan nilai -1 mengaktifkan penyimpanan analitis tanpa TTL. Harap dicatat bahwa penyimpanan analitik hanya dapat diaktifkan pada akun yang diaktifkan Synapse Link.

Mengembalikan

Instans ContainerProxy yang mewakili kontainer.

Tipe hasil

ContainerProxy

Pengecualian

CosmosHttpResponseError

Pembacaan atau pembuatan kontainer gagal.

create_user

Buat pengguna baru di kontainer.

Untuk memperbarui atau mengganti pengguna yang sudah ada, gunakan metode .<xref:ContainerProxy.upsert_user>

create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parameter

body
Diperlukan

Objek seperti dikte dengan kunci id dan nilai yang mewakili pengguna yang akan dibuat. ID pengguna harus unik dalam database, dan terdiri dari tidak lebih dari 255 karakter.

response_hook
Callable

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Instans UserProxy yang mewakili pengguna baru.

Tipe hasil

UserProxy

Pengecualian

CosmosHttpResponseError

Jika pengguna yang diberikan tidak dapat dibuat.

Contoh

Buat pengguna database:


   try:
       database.create_user(dict(id="Walter Harp"))
   except exceptions.CosmosResourceExistsError:
       print("A user with that ID already exists.")
   except exceptions.CosmosHttpResponseError as failure:
       print("Failed to create user. Status code:{}".format(failure.status_code))

delete_container

Hapus kontainer.

delete_container(container: str | ContainerProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None

Parameter

container
Diperlukan

ID (nama) kontainer yang akan dihapus. Anda dapat meneruskan ID kontainer untuk dihapus, instans, ContainerProxy atau dict yang mewakili properti kontainer.

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 kontainer tidak dapat dihapus.

delete_user

Hapus pengguna yang ditentukan dari kontainer.

delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> None

Parameter

user
Diperlukan

ID (nama), dict yang mewakili properti atau UserProxy instans pengguna yang akan dihapus.

response_hook
Callable

Panggilan yang dipanggil dengan metadata respons.

Tipe hasil

None

Pengecualian

CosmosHttpResponseError

Pengguna tidak berhasil dihapus.

CosmosResourceNotFoundError

Pengguna tidak ada dalam kontainer.

get_container_client

Dapatkan ContainerProxy untuk kontainer dengan ID (nama) tertentu.

get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxy

Parameter

container
Diperlukan

ID (nama) kontainer, ContainerProxy instans, atau dict yang mewakili properti kontainer yang akan diambil.

Mengembalikan

Instans ContainerProxy yang mewakili database yang diambil.

Tipe hasil

ContainerProxy

Pengecualian

CosmosHttpResponseError

Pembuatan kontainer gagal.

Contoh

Dapatkan kontainer yang sudah ada, menangani kegagalan jika ditemui:


   database = client.get_database_client(database_name)
   container = database.get_container_client(container_name)

get_throughput

Dapatkan objek ThroughputProperties untuk database ini. Jika tidak ada ThroughputProperties yang sudah ada untuk database, pengecualian akan dinaikkan. :keyword Callable response_hook: Panggilan yang dipanggil dengan metadata respons. :returns: ThroughputProperties untuk database. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Tidak ada properti throughput untuk kontainer atau

properti throughput tidak dapat diambil.

get_throughput(**kwargs: Any) -> ThroughputProperties

Tipe hasil

ThroughputProperties

Pengecualian

CosmosHttpResponseError

Pembuatan kontainer gagal.

get_user_client

Dapatkan UserProxy untuk pengguna dengan ID tertentu.

get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxy

Parameter

user
Diperlukan

ID (nama), dict yang mewakili properti atau UserProxy instans pengguna yang akan diambil.

Mengembalikan

Instans UserProxy yang mewakili pengguna yang diambil.

Tipe hasil

UserProxy

Pengecualian

CosmosHttpResponseError

Pembuatan kontainer gagal.

list_containers

Mencantumkan kontainer dalam database.

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

Parameter

max_item_count
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 kontainer (dicts).

Tipe hasil

Iterable[dict[str, Any]]

Pengecualian

CosmosHttpResponseError

Pembuatan kontainer gagal.

Contoh

Cantumkan semua kontainer dalam database:


   database = client.get_database_client(database_name)
   for container in database.list_containers():
       print("Container ID: {}".format(container['id']))

list_users

Mencantumkan semua pengguna dalam kontainer.

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

Parameter

max_item_count
Diperlukan

Jumlah maksimum pengguna yang akan dikembalikan dalam operasi enumerasi.

response_hook
Callable

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Iterable properti pengguna (dicts).

Tipe hasil

Iterable[dict[str, Any]]

Pengecualian

CosmosHttpResponseError

Pembuatan kontainer gagal.

query_containers

Mencantumkan properti untuk kontainer dalam database saat ini.

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

Parameter

query
Diperlukan

Kueri Azure Cosmos DB SQL untuk dijalankan.

parameters
Diperlukan

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

max_item_count
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 kontainer (dicts).

Tipe hasil

Iterable[dict[str, Any]]

Pengecualian

CosmosHttpResponseError

Pembuatan kontainer gagal.

query_users

Mengembalikan semua pengguna yang cocok dengan kueri yang diberikan.

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

Parameter

query
Diperlukan

Kueri Azure Cosmos DB SQL untuk dijalankan.

parameters
Diperlukan

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

max_item_count
Diperlukan

Jumlah maksimum pengguna yang akan dikembalikan dalam operasi enumerasi.

response_hook
Callable

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Iterable properti pengguna (dicts).

Tipe hasil

Iterable[str, Any]

Pengecualian

CosmosHttpResponseError

Pembuatan kontainer gagal.

read

Membaca properti database.

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

Parameter

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.

Tipe hasil

Dict[<xref:Str>, Any]

Pengecualian

CosmosHttpResponseError

Jika database yang diberikan tidak dapat diambil.

read_offer

Dapatkan objek ThroughputProperties untuk database ini. Jika tidak ada ThroughputProperties yang sudah ada untuk database, pengecualian akan dinaikkan. :keyword Callable response_hook: Panggilan yang dipanggil dengan metadata respons. :returns: ThroughputProperties untuk database. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Tidak ada properti throughput untuk kontainer atau

properti throughput tidak dapat diambil.

read_offer(**kwargs: Any) -> ThroughputProperties

Tipe hasil

ThroughputProperties

Pengecualian

CosmosHttpResponseError

Pembuatan kontainer gagal.

replace_container

Reset properti kontainer.

Perubahan properti segera dipertahankan. Properti apa pun yang tidak ditentukan akan diatur ulang ke nilai defaultnya.

replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> ContainerProxy

Parameter

container
Diperlukan

ID (nama), dict yang mewakili properti atau ContainerProxy instans kontainer yang akan diganti.

partition_key
Diperlukan

Kunci partisi yang digunakan untuk kontainer.

indexing_policy
Diperlukan

Kebijakan pengindeksan untuk diterapkan ke kontainer.

default_ttl
Diperlukan

Waktu hidup (TTL) default untuk item dalam kontainer. Jika tidak ditentukan, item tidak kedaluwarsa.

conflict_resolution_policy
Diperlukan

Kebijakan resolusi konflik untuk diterapkan ke kontainer.

populate_query_metrics
Diperlukan

Aktifkan mengembalikan metrik kueri di header respons.

session_token
str

Token untuk digunakan dengan konsistensi Sesi.

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.

initial_headers
dict[str,str]

Header awal yang akan dikirim sebagai bagian dari permintaan.

response_hook
Callable

Panggilan yang dipanggil dengan metadata respons.

analytical_storage_ttl
int

Time to live (TTL) penyimpanan analitis untuk item dalam kontainer. Nilai Tidak Ada membuat penyimpanan analitis nonaktif dan nilai -1 mengaktifkan penyimpanan analitik tanpa TTL. Harap dicatat bahwa penyimpanan analitik hanya dapat diaktifkan pada akun yang diaktifkan Synapse Link.

Mengembalikan

Instans ContainerProxy yang mewakili kontainer setelah penggantian selesai.

Tipe hasil

ContainerProxy

Pengecualian

CosmosHttpResponseError

Dimunculkan jika kontainer tidak dapat diganti. Ini termasuk jika kontainer dengan id yang diberikan tidak ada.

Contoh

Reset properti TTL pada kontainer, dan tampilkan properti yang diperbarui:


   # Set the TTL on the container to 3600 seconds (one hour)
   database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

   # Display the new TTL setting for the container
   container_props = database.get_container_client(container_name).read()
   print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))

replace_throughput

Ganti throughput tingkat database.

replace_throughput(throughput: int | ThroughputProperties | None, **kwargs: Any) -> ThroughputProperties

Parameter

throughput
Diperlukan

Throughput yang akan diatur (bilangan bulat).

response_hook
Callable

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

ThroughputProperties untuk database, diperbarui dengan throughput baru.

Tipe hasil

ThroughputProperties

Pengecualian

CosmosHttpResponseError

Jika tidak ada properti throughput untuk database atau jika properti throughput tidak dapat diperbarui.

replace_user

Menggantikan pengguna yang ditentukan jika ada dalam kontainer.

replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parameter

user
Diperlukan

ID (nama), dict yang mewakili properti atau UserProxy instans pengguna yang akan diganti.

body
Diperlukan

Objek seperti dikte yang mewakili pengguna untuk diganti.

response_hook
Callable

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Instans UserProxy yang mewakili pengguna setelah penggantian dilalui.

Tipe hasil

UserProxy

Pengecualian

CosmosHttpResponseError

Jika penggantian gagal atau pengguna dengan ID yang diberikan tidak ada.

upsert_user

Sisipkan atau perbarui pengguna yang ditentukan.

Jika pengguna sudah ada dalam kontainer, pengguna akan diganti. Jika pengguna belum ada, pengguna akan dimasukkan.

upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parameter

body
Diperlukan

Objek seperti dikte yang mewakili pengguna untuk diperbarui atau disisipkan.

response_hook
Callable

Panggilan yang dipanggil dengan metadata respons.

Mengembalikan

Instans UserProxy yang mewakili pengguna yang ditingkatkan.

Tipe hasil

UserProxy

Pengecualian

CosmosHttpResponseError

Jika pengguna yang diberikan tidak dapat di-upsert.