Menggunakan ETag untuk Kontrol Serentak Objek Data

Vector Search 2.0 mendukung Optimistic Concurrency Control (OCC) menggunakan ETag (tag entitas), yang merupakan ID buram yang merepresentasikan versi Objek Data tertentu.

Jika beberapa proses beroperasi secara bersamaan pada set data yang sama, seperti update API real-time dan tugas impor massal, ada risiko bahwa proses tersebut akan saling menimpa perubahan (skenario penulisan terakhir yang menang). ETag memungkinkan Anda menjamin integritas data dan memastikan bahwa proses lain tidak mengubah data sejak terakhir kali Anda membacanya.

Cara kerja ETag

  1. Baca: Saat Anda membuat atau mendapatkan Objek Data, server akan menampilkan string ETag yang merepresentasikan versi Objek Data yang tepat.

  2. Ubah: Anda membuat perubahan pada Objek Data secara lokal.

  3. Tulis: Anda mengirimkan permintaan update atau hapus kembali ke Vector Search 2.0, termasuk ETag yang Anda terima sebelumnya.

  4. Verifikasi: Server memeriksa apakah ETag yang diberikan cocok dengan ETag saat ini yang disimpan dalam database.

    • Jika cocok, operasi akan berhasil dan server akan menampilkan ETag baru untuk Objek Data yang diperbarui.
    • Jika tidak cocok, operasi akan diblokir dan server akan menampilkan error ABORTED (HTTP 409 Conflict).

Mengambil ETag

Sebelum dapat menggunakan ETag untuk kontrol serentak, Anda harus mengambil versi terbaru dari sistem.

ETag dapat diambil dengan cara berikut:

  • Respons API Real-Time: Saat Anda memanggil metode baca atau tulis di DataObjectService (seperti GetDataObject, ListDataObjects, CreateDataObject, atau UpdateDataObject), resource Objek Data yang ditampilkan mencakup ETag saat ini.

  • Output Import API: Saat memanggil ImportDataObjects, Anda dapat menentukan awalan URI ke Cloud Storage di kolom GcsImportConfig output-uri. Jika tugas impor berhasil, file JSONL akan dibuat dengan setiap baris berisi ID dan ETag untuk Objek Data yang diimpor. Formatnya adalah sebagai berikut:

    { "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"}

  • Export API (ExportDataObjects) - Saat Anda mengekspor data dari Vector Search 2.0 ke Cloud Storage, file data JSONL kanonis yang dihasilkan berisi ETag untuk semua Objek Data yang diekspor.

Membuat Objek Data

Saat memanggil CreateDataObject atau BatchCreateDataObjects, ETag apa pun yang Anda berikan dalam permintaan akan diabaikan karena Objek Data belum ada.

Jika permintaan pembuatan berhasil, server akan menyertakan ETag yang baru dibuat dalam resource Objek Data yang ditampilkan.

Memperbarui Objek Data

Untuk memperbarui data yang ada secara aman menggunakan UpdateDataObject atau BatchUpdateDataObjects, sertakan ETag langsung dalam resource Objek Data dalam permintaan Anda.

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d",
  "data": {
    "genre": ["science-fiction", "thriller", "action"]
  }
}

Menghapus Objek Data

Karena metode DeleteDataObject dan BatchDeleteDataObjects tidak menggunakan resource Objek Data lengkap sebagai payload, ETag harus diberikan sebagai kolom tingkat teratas di DeleteDataObjectRequest.

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"
}

Menggunakan ETag dengan penyerapan massal (ImportDataObjects)

Penggunaan ImportDataObjects API berjalan secara asinkron dan berpotensi berkonflik dengan update real-time. Sertakan kolom etag dalam file impor JSONL untuk menerapkan kontrol serentak selama impor.

Vector Search otomatis mendeteksi mode penyelesaian konflik berdasarkan per-rekaman:

  • Dengan ETag (OCC): Jika ETag diberikan dan tidak cocok dengan versi saat ini di server, impor data tertentu akan gagal. Kegagalan tersebut kemudian dicatat ke URI error yang Anda tentukan, tetapi tugas impor lainnya akan dilanjutkan.

  • Tanpa ETag: Jika ETag tidak disertakan, data akan di-ingest, menggantikan data yang ada. Hal ini memaksimalkan throughput saat kontrol konkurensi tidak diperlukan.

Format JSONL

Sertakan ETag di tingkat root objek JSON dalam file impor Anda seperti yang ditunjukkan dalam contoh berikut.

{ "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d", "data":{ "genre": ["science-fiction", "thriller"] }, "vectors": { ... } }

Menangani Error Persamaan

Jika operasi gagal dalam pemeriksaan ETag, API akan menampilkan kode error ABORTED (HTTP 409 Conflict).

Penanganan Error yang Direkomendasikan:

Saat Anda menerima error ABORTED, aplikasi Anda harus:

  1. Mengambil ulang versi terbaru Objek Data dari server.

  2. Selesaikan konflik logika bisnis antara data yang baru diambil dan pembaruan yang Anda inginkan.

  3. Coba lagi operasi menggunakan ETag baru.

Apa langkah selanjutnya?