Bagikan melalui

Pembaruan dokumen parsial di Azure Cosmos DB

  • 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, melakukan pemeriksaan Kontrol Konkurensi Optimis (jika perlu), memperbarui dokumen secara lokal, lalu mengirimkannya melalui jaringan sebagai panggilan API Replace untuk 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: Menghindari 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 pada jalur diskrit dalam dokumen yang sama.

Note

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": "eeeeeeee-4444-5555-6666-ffffffffffff",
  "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": "eeeeeeee-4444-5555-6666-ffffffffffff",
  "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.

Note

jalur target mengacu pada lokasi dalam dokumen JSON.

Jenis operasi Description
Add Add melakukan salah satu hal berikut, tergantung pada jalur target:
• Jika jalur target menentukan elemen yang tidak ada, elemen tersebut 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 penambahan 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.
Set Set mirip dengan Add kecuali menggunakan jenis data array. Jika jalur target adalah indeks array yang valid, elemen yang ada di indeks tersebut diperbarui.
Replace Replace mirip dengan Set kecuali mengikuti semantik penggantian saja yang ketat. Jika jalur target menentukan elemen atau array yang tidak ada, jalur tersebut menghasilkan kesalahan.
Remove Remove melakukan salah satu hal berikut, tergantung pada jalur target:
• Jika jalur target menentukan elemen yang tidak ada, itu menghasilkan kesalahan.
• Jika jalur target menentukan elemen yang sudah ada, jalur tersebut akan dihapus.
• Jika jalur target adalah indeks array, itu dihapus dan elemen apa pun di atas indeks yang ditentukan digeser kembali satu posisi.
Catatan: Menentukan indeks yang sama dengan atau lebih besar dari panjang array akan mengakibatkan kesalahan.
Increment Operator ini menambahkan bidang sebesar nilai yang ditentukan. Bidang tersebut dapat menerima nilai positif maupun negatif. Jika bidang tidak ada, bidang tersebut akan dibuat dan diatur ke nilai yang ditentukan.
Move 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 "path" menyarankan objek yang tidak ada, sistem akan membuat objek tersebut dan menetapkan nilainya sama dengan nilai di lokasi "from".
• Jika lokasi "path" menunjukkan objek yang sudah ada, maka nilai di lokasi "path" digantikan dengan nilai di lokasi "from"
•Atribut "path" tidak boleh menjadi elemen turunan 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 dalam 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 sebelumnya, 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 kesamaan dan perbedaan antara mode yang didukung.

Tambah vs Atur

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

Tambah vs Ganti

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

Tentukan vs Gantikan

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

Note

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, begini tampilan permintaan untuk operasi set yang 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 lintasan

Jika akun Azure Cosmos DB Anda dikonfigurasi dengan beberapa wilayah tulis, konflik dan kebijakan resolusi konflik berlaku di tingkat dokumen, dengan Last Write Wins (LWW) menjadi 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 lebih dipahami 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

Diagram yang memperlihatkan resolusi konflik dalam operasi pembaruan parsial multi-wilayah bersamaan.

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 melihat dokumen berikut setelah resolusi konflik:

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

Note

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

Umpan perubahan data

Umpan perubahan di Azure Cosmos DB mendengarkan kontainer untuk setiap perubahan lalu menghasilkan 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 selanjutnya

  • Last updated on