Menggunakan ETag untuk Kontrol Serentak Objek Data

Agent Retrieval (sebelumnya Penelusuran Vektor 2.0) mendukung kontrol konkurensi Optimistic (OCC) menggunakan ETag (tag entity), yang merupakan ID buram yang mewakili versi Objek Data tertentu.

Jika beberapa proses beroperasi secara serentak pada set data yang sama, seperti update API real-time dan tugas impor massal, ada risiko bahwa proses tersebut dapat saling menimpa perubahan (skenario last-write-wins). ETag memungkinkan Anda menjamin integritas data dan memastikan bahwa proses lain belum 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 mewakili versi persis Objek Data.

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

  3. Tulis: Anda mengirim permintaan update atau delete kembali ke Agent Retrieval, termasuk ETag yang awalnya Anda terima.

  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 konkurensi, 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 menyertakan ETag saat ini.

  • Output API Impor: 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 sebagai berikut:

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

  • Export API (ExportDataObjects) - Saat Anda mengekspor data dari Agent Retrieval 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 dengan 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-nya, ETag harus disediakan sebagai kolom level 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 bertabrakan dengan update real-time. Sertakan kolom etag dalam file impor JSONL Anda untuk menerapkan kontrol konkurensi selama impor.

Penelusuran Vektor di Gemini Enterprise Agent Platform otomatis mendeteksi mode penyelesaian konflik per data:

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

  • Tanpa ETag: Jika ETag dihilangkan, data akan diserap, sehingga menggantikan data yang ada. Hal ini memaksimalkan throughput saat kontrol konkurensi tidak diperlukan.

Format JSONL

Sertakan ETag di level 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 Konkurensi

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. Ambil ulang versi terbaru Objek Data dari server.

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

  3. Coba lagi operasi menggunakan ETag baru.

Apa langkah selanjutnya?