Pembaruan dokumen parsial di Azure Cosmos DB

Artikel
06/06/2023

BERLAKU UNTUK: NoSQL

Fitur Pembaruan Dokumen Parsial Azure Cosmos DB (juga dikenal sebagai Patch API) menyediakan cara mudah untuk memodifikasi dokumen dalam kontainer. Saat ini, untuk memperbarui dokumen, klien perlu membacanya, menjalankan pemeriksaan Kontrol Konkurensi Optimis (jika perlu), memperbarui dokumen secara lokal kemudian mengirimkan dokumen tersebut melalui kabel sebagai panggilan API Ganti seluruh dokumen.

Fitur pembaruan dokumen parsial meningkatkan pengalaman ini secara signifikan. Klien hanya dapat mengirim properti/bidang yang dimodifikasi dalam dokumen tanpa melakukan operasi penggantian dokumen lengkap. Manfaat utama dari fitur ini meliputi:

Peningkatan produktivitas pengembang: Menyediakan API yang praktis untuk kemudahan penggunaan dan kemampuan untuk memperbarui dokumen secara kondisional.
Peningkatan performa: Hindari siklus CPU tambahan di sisi klien, mengurangi latensi end-to-end dan bandwidth jaringan.
Penulisan multi-wilayah: Mendukung resolusi konflik otomatis dan transparan dengan pembaruan parsial di jalur diskret di dalam dokumen yang sama.

Catatan

Operasi pembaruan dokumen parsial didasarkan pada JSON Patch RFC. Nama properti di jalur harus keluar dari ~ karakter dan / sebagai ~0 dan ~1, masing-masing.

Contoh dokumen JSON target:

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 455.95,
  "inventory": {
    "quantity": 15
  },
  "used": false,
  "categoryId": "road-bikes",
  "tags": ["r-series"]
}

Dokumen Patch JSON:

[
  { "op": "add", "path": "/color", "value": "silver" },
  { "op": "remove", "path": "/used" },
  { "op": "set", "path": "/price", "value": 355.45 }
  { "op": "incr", "path": "/inventory/quantity", "value": 10 },
  { "op": "add", "path": "/tags/-", "value": "featured-bikes" },
  { "op": "move", "from": "/color", "path": "/inventory/color" }
]

Dokumen JSON yang dihasilkan:

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 355.45,
  "inventory": {
    "quantity": 25,
    "color": "silver"
  },
  "categoryId": "road-bikes",
  "tags": ["r-series", "featured-bikes"]
}

Operasi yang didukung

Tabel ini meringkas operasi yang didukung oleh fitur ini.

Catatan

jalur target mengacu pada lokasi di dalam dokumen JSON

Jenis operasi	Deskripsi
Tambahkan	`Add` menjalankan salah satu dari yang berikut, tergantung pada jalur target: • Jika jalur target menentukan elemen yang tidak ada, maka akan ditambahkan. • Jika jalur target menentukan elemen yang sudah ada, nilainya akan diganti. • Jika jalur target adalah indeks array yang valid, elemen baru dimasukkan ke dalam array pada indeks yang ditentukan. Ini menggeser elemen yang ada setelah elemen baru. • Jika indeks yang ditentukan sama dengan panjang array, ia menambahkan elemen ke array. Alih-alih menentukan indeks, Anda juga dapat menggunakan karakter `-`. Ini juga menghasilkan elemen yang ditambahkan ke array. Catatan: Menentukan indeks yang lebih besar dari panjang array menghasilkan kesalahan.
Tetapkan	`Set` operasi mirip dengan `Add` kecuali dengan jenis data Array. Jika jalur target adalah indeks array yang valid, elemen yang ada di indeks tersebut akan diperbarui.
Replace	Operasi `Replace` mirip dengan `Set`, kecuali operasi tersebut mematuhi penggantian ketat hanya semantik. Jika jalur target menentukan elemen atau array yang tidak ada, jalur target menghasilkan kesalahan.
Hapus	`Remove` menjalankan salah satu dari yang berikut, tergantung pada jalur target: • Jika jalur target menentukan elemen yang tidak ada, itu menghasilkan kesalahan. • Jika jalur target menentukan elemen yang sudah ada, maka akan dihapus. • Jika jalur target adalah indeks array, jalur tersebut dihapus dan elemen apa pun di atas indeks yang ditentukan digeser kembali satu posisi. Catatan: Menentukan indeks yang setara atau lebih besar dari panjang array akan mengakibatkan kesalahan.
Tahapan	Operator ini menambahkan bidang sebesar nilai yang ditentukan. Bidang tersebut dapat menerima nilai positif maupun negatif. Jika bidang tidak ada, bidang akan membuat bidang dan mengaturnya ke nilai yang ditentukan.
Bergerak	Operator ini menghapus nilai di lokasi tertentu dan menambahkannya ke lokasi target. Objek operasi HARUS berisi anggota "dari", yang merupakan string yang berisi nilai Penunjuk JSON yang mereferensikan lokasi dalam dokumen target untuk memindahkan nilai. Lokasi "dari" HARUS ada agar operasi berhasil. Jika lokasi "jalur" menyarankan objek yang tidak ada, itu akan membuat objek dan mengatur nilai yang sama dengan nilai di lokasi "dari" •Jika lokasi "jalur" menyarankan objek yang sudah ada, itu akan menggantikan nilai di lokasi "jalur" dengan nilai di lokasi "dari" Atribut •"Path" tidak boleh menjadi anak JSON dari lokasi JSON "from"

Mode yang didukung

Fitur pembaruan dokumen parsial mendukung mode operasi berikut. Lihat dokumen Memulai untuk contoh kode.

Patch dokumen tunggal: Anda dapat menerapkan patch ke dokumen tunggal berdasarkan ID dan kunci partisinya. Dimungkinkan untuk menjalankan beberapa operasi patch pada satu dokumen. Batas maksimum adalah 10 operasi.
Patch multi-dokumen: Beberapa dokumen di kunci partisi yang sama dapat di-patch sebagai bagian dari transaksi. Transaksi multi-dokumen ini dilakukan hanya jika semua operasi berhasil dalam urutan yang dijelaskan. Jika ada operasi yang gagal, seluruh transaksi digulung balik.
Pembaruan Bersyarat: Untuk mode yang disebutkan di atas, dimungkinkan juga untuk menambahkan predikat filter seperti SQL (misalnya, from c where c.taskNum = 3) sehingga operasi gagal jika prasyarat yang ditentukan dalam predikat tidak terpenuhi.
Anda juga dapat menggunakan API massal SDK yang didukung untuk menjalankan satu operasi patch atau lebih di beberapa dokumen.

Kesamaan dan perbedaan

Mari kita bandingkan persamaan dan perbedaan antara mode yang didukung.

Tambah vs Atur

Operasi Set mirip dengan Add untuk semua jenis data kecuali Array. Operasi Add pada indeks (valid) apa pun, menghasilkan penambahan elemen pada indeks yang ditentukan dan elemen yang ada dalam array akhirnya bergeser setelah elemen yang ada. Perilaku ini berbeda dengan Set operasi yang memperbarui elemen yang ada pada indeks yang ditentukan.

Tambah vs Ganti

Operasi Add menambahkan properti jika properti tersebut belum ada (termasuk jenis data Array). Replace operasi gagal jika properti tidak ada (berlaku untuk Array jenis data juga).

Atur vs Ganti

Operasi Set menambahkan properti jika properti tersebut belum ada (kecuali jika ada Array). Replace operasi gagal jika properti tidak ada (berlaku untuk Array jenis data juga).

Catatan

Replace adalah kandidat yang baik di mana pengguna mengharapkan beberapa properti untuk selalu ada dan memungkinkan Anda untuk menegaskan/memberlakukan properti tersebut.

Referensi REST API untuk Pembaruan dokumen sebagian

Azure Cosmos DB REST API menyediakan akses terprogram ke sumber daya Azure Cosmos DB untuk membuat, mengkueri, dan menghapus database, kumpulan dokumen, dan dokumen. Selain menjalankan operasi sisipkan, ganti, hapus, baca, enumerasi, dan kueri pada dokumen JSON dalam kumpulan, Anda dapat menggunakan metode HTTP PATCH untuk operasi Pembaruan dokumen sebagian. Lihat Referensi REST API Azure Cosmos DB untuk detailnya.

Misalnya, berikut tampilan permintaan untuk set operasi menggunakan pembaruan dokumen parsial.

PATCH https://querydemo.documents.azure.com/dbs/FamilyDatabase/colls/FamilyContainer/docs/Andersen.1 HTTP/1.1
x-ms-documentdb-partitionkey: ["Andersen"]
x-ms-date: Tue, 29 Mar 2016 02:28:29 GMT
Authorization: type%3dmaster%26ver%3d1.0%26sig%3d92WMAkQv0Zu35zpKZD%2bcGSH%2b2SXd8HGxHIvJgxhO6%2fs%3d
Content-Type:application/json_patch+json
Cache-Control: no-cache
User-Agent: Microsoft.Azure.DocumentDB/2.16.12
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=602; x-ms-session-token=602
Content-Length: calculated when request is sent
Connection: keep-alive

{
  "operations": [
    {
      "op": "set",
      "path": "/Parents/0/FamilyName",
      "value": "Bob"
    }
  ]
}

Resolusi konflik tingkat dokumen vs tingkat jalur

Jika akun Azure Cosmos DB Anda dikonfigurasi dengan beberapa wilayah penulisan, kebijakan konflik dan resolusi konflik dapat diterapkan pada tingkat dokumen, dengan Last Write Wins (LWW) sebagai kebijakan resolusi konflik default. Untuk pembaruan dokumen parsial, operasi patch di beberapa wilayah mendeteksi dan menyelesaikan konflik pada tingkat jalur yang lebih terperinci.

Resolusi konflik dapat dipahami dengan lebih baik dengan contoh.

Semisal Anda memiliki dokumen berikut di Azure Cosmos DB:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345", "67890"],
  "level": "gold"
}

Klien yang berbeda mengeluarkan operasi Patch secara bersamaan di berbagai wilayah:

Set atribut /level ke platinum
Remove 67890 dari /phone

Karena permintaan Patch dibuat untuk jalur nonkonflik dalam dokumen, permintaan ini diselesaikan secara otomatis dan transparan (dibandingkan dengan Last Writer Wins pada tingkat dokumen).

Klien akan melihat dokumen berikut setelah resolusi konflik:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345"],
  "level": "platinum"
}

Catatan

Dalam kasus properti yang sama dari suatu dokumen di-patch secara bersamaan di berbagai wilayah, kebijakan resolusi konflik reguler berlaku.

Umpan perubahan

Ubah umpan di Azure Cosmos DB mendengarkan kontainer untuk setiap perubahan dan kemudian mengeluarkan dokumen yang diubah. Menggunakan umpan perubahan, Anda melihat semua pembaruan pada dokumen termasuk pembaruan dokumen sebagian dan penuh. Saat Anda memproses item dari umpan perubahan, dokumen lengkap dikembalikan meskipun pembaruan adalah hasil dari operasi patch.

Untuk informasi selengkapnya tentang umpan perubahan di Azure Cosmos DB, lihat Mengubah umpan di Azure Cosmos DB.

Langkah berikutnya

Pelajari cara memulai dengan Pembaruan Dokumen Parsial menggunakan .NET, Java, dan Node
Pertanyaan yang sering diajukan tentang Pembaruan Dokumen Parsial

Bagikan melalui

Pembaruan dokumen parsial di Azure Cosmos DB

Operasi yang didukung

Mode yang didukung

Kesamaan dan perbedaan

Tambah vs Atur

Tambah vs Ganti

Atur vs Ganti

Referensi REST API untuk Pembaruan dokumen sebagian

Resolusi konflik tingkat dokumen vs tingkat jalur

Umpan perubahan

Langkah berikutnya

Sumber Daya Tambahan: