Google Cloud Search Indexing Queues

Connector SDK dan Google Cloud Search API memungkinkan pembuatan Cloud Search Indexing Queues yang digunakan untuk melakukan tugas berikut:

• Mempertahankan status tiap dokumen (status, nilai hash, dan sebagainya) yang dapat digunakan untuk tetap menyinkronkan indeks dengan repositori Anda.

• Mempertahankan daftar item yang akan diindeks sebagai ditemukan selama proses traversal.

• Memprioritaskan item dalam antrean berdasarkan status item.

• Mempertahankan informasi status tambahan untuk menciptakan integrasi yang efisien seperti checkpoint, token perubahan, dan lainnya.

Antrean adalah label yang ditetapkan ke item yang diindeks, seperti "default" untuk antrean default atau "B" untuk antrean B.

Status & prioritas

Prioritas dokumen dalam antrean didasarkan pada kode ItemStatus. Berikut adalah kode ItemStatus yang memungkinkan berdasarkan urutan prioritas (ditangani terlebih dahulu hingga ditangani terakhir):

• ERROR - Item mengalami error asinkron selama proses pengindeksan dan perlu diindeks ulang.

• MODIFIED - Item yang sebelumnya diindeks dan telah diubah di repositori sejak pengindeksan terakhir.

• NEW_ITEM - Item yang tidak diindeks.

• ACCEPTED - Dokumen yang sebelumnya diindeks dan tidak berubah di repositori sejak pengindeksan terakhir.

Jika dua item dalam antrean memiliki status yang sama, prioritas lebih tinggi diberikan untuk item yang telah berada dalam antrean untuk jangka waktu paling lama.

Ringkasan penggunaan antrean pengindeksan untuk mengindeks item baru atau yang diubah

Gambar 1 menunjukkan langkah-langkah dalam mengindeks item baru atau yang diubah menggunakan antrean pengindeksan. Langkah-langkah ini menunjukkan panggilan REST API. Untuk panggilan SDK yang setara, lihat Operasi antrean (SDK Konektor).

Gambar 1. Langkah pengindeksan untuk menambahkan atau memperbarui item

1. Konektor konten menggunakan items.push untuk mendorong item (metadata dan hash) ke antrean pengindeksan guna menetapkan status item (MODIFIED, NEW_ITEM, DELETED). Secara khusus:

   • Saat melakukan push, konektor secara eksplisit menyertakan push type atau contentHash.
   • Jika konektor tidak menyertakan type, Cloud Search akan otomatis menggunakan contentHash untuk menentukan status item.
   • Jika item tidak diketahui, status item akan ditetapkan ke NEW_ITEM.
   • Jika item ada dan nilai hash cocok, statusnya akan tetap ACCEPTED.
   • Jika item ada dan hash-nya berbeda, statusnya menjadi MODIFIED.

   Untuk mengetahui informasi selengkapnya tentang cara menetapkan status item, lihat kode contoh Melintasi repositori GitHub dalam tutorial memulai Cloud Search.

   Biasanya, push dikaitkan dengan proses traversal konten dan/atau deteksi perubahan di konektor.

2. Konektor konten menggunakan items.poll untuk melakukan polling antrean guna menentukan item yang akan diindeks. Cloud Search memberi tahu konektor item mana yang paling memerlukan pengindeksan, yang diurutkan terlebih dahulu berdasarkan kode status, lalu berdasarkan waktu dalam antrean.

3. Konektor mengambil item ini dari repositori dan membuat permintaan API indeks.

4. Konektor menggunakan items.index untuk mengindeks item. Item hanya memasuki status ACCEPTED setelah Cloud Search berhasil menyelesaikan pemrosesan item.

Konektor juga dapat menghapus item jika tidak ada lagi di repositori, atau mendorong item lagi jika tidak diubah atau jika ada error repositori sumber. Untuk informasi tentang penghapusan item, lihat bagian berikutnya.

Catatan: Beberapa strategi traversal, seperti traversal penuh, menggunakan lebih dari satu antrean pengindeksan. Untuk contoh cara menggunakan dua antrean, lihat bagian berikutnya.

Ringkasan penggunaan antrean pengindeksan untuk menghapus item

Strategi traversal penuh menggunakan proses dua antrean untuk mengindeks item dan mendeteksi penghapusan. Gambar 2 menunjukkan langkah-langkah dalam menghapus item menggunakan dua antrean pengindeksan. Secara khusus, Gambar 2 menunjukkan traversal kedua yang dilakukan menggunakan strategi traversal penuh. Langkah-langkah ini menggunakan panggilan REST API. Untuk panggilan SDK yang setara, lihat Operasi Antrean (SDK Konektor).

Gambar 2. Menghapus item

Catatan: Dalam daftar langkah berikut, langkah 1-4 tidak ditampilkan pada Gambar 2 karena sama dengan langkah 1-4 di diagram sebelumnya dan tidak termasuk dalam cakupan bagian ini. Langkah 5 tidak ditampilkan karena memanggil deleteQueueItems pada antrean kosong tidak termasuk dalam cakupan bagian ini. Diagram ini berfokus pada traversal kedua.

1. Pada traversal awal, konektor konten menggunakan items.push untuk memasukkan item (metadata dan hash) ke dalam antrean pengindeksan, "mengantrekan A" sebagai NEW_ITEM karena tidak ada dalam antrean. Setiap item diberi label "A" untuk "antrean A." Konten diindeks ke Cloud Search.

   Catatan: Konektor dapat menetapkan label antrean, menggunakan kolom queue item, ke item selama operasi item.push atau item.index. Label ini dapat diubah setiap kali item di-push ulang atau diindeks ulang.

2. Konektor konten menggunakan items.poll untuk melakukan polling pada antrean A guna menentukan item yang akan diindeks. Cloud Search memberi tahu konektor item mana yang paling memerlukan pengindeksan, yang diurutkan terlebih dahulu berdasarkan kode status, lalu berdasarkan waktu dalam antrean.

3. Konektor mengambil item ini dari repositori dan membuat permintaan API indeks.

4. Konektor menggunakan items.index untuk mengindeks item. Item hanya memasuki status ACCEPTED setelah Cloud Search berhasil menyelesaikan pemrosesan item.

5. Metode deleteQueueItems dipanggil pada "antrean B". Namun, tidak ada item yang didorong ke antrean B, sehingga tidak ada yang dapat dihapus.

6. Pada traversal penuh kedua, konektor konten menggunakan items.push untuk mengirim item (metadata dan hash) ke antrean B:

   • Saat mendorong, konektor secara eksplisit menyertakan type atau contentHash push.
   • Jika konektor tidak menyertakan type, Cloud Search akan otomatis menggunakan contentHash untuk menentukan status item.
   • Jika item tidak diketahui, status item ditetapkan ke NEW_ITEM dan label antrean diubah menjadi "B".
   • Jika item ada dan nilai hash cocok, status akan tetap sebagai ACCEPTED dan label antrean akan diubah menjadi "B".
   • Jika item ada dan hash-nya berbeda, statusnya menjadi MODIFIED dan label antrean diubah menjadi "B".

7. Konektor konten menggunakan items.poll untuk melakukan polling pada antrean guna menentukan item yang akan diindeks. Cloud Search memberi tahu konektor item mana yang paling memerlukan pengindeksan, yang diurutkan terlebih dahulu berdasarkan kode status, lalu berdasarkan waktu dalam antrean.

8. Konektor mengambil item ini dari repositori dan membuat permintaan API indeks.

9. Konektor menggunakan items.index untuk mengindeks item. Item hanya memasuki status ACCEPTED setelah Cloud Search berhasil menyelesaikan pemrosesan item.

10. Terakhir, deleteQueueItems dipanggil di antrean A untuk menghapus semua item CCloud Search yang diindeks sebelumnya yang masih memiliki label antrean "A".

11. Dengan traversal penuh berikutnya, antrean yang digunakan untuk pengindeksan dan antrean yang digunakan untuk menghapus akan ditukar.

Operasi antrean (SDK Konektor)

SDK Konektor Konten menyediakan operasi untuk mendorong item ke dan menarik item dari antrean.

Untuk mengemas dan mendorong item ke antrean, gunakan class pembuat pushItems.

Anda tidak perlu melakukan hal khusus untuk memproses penarikan item dari antrean. Sebagai gantinya, SDK otomatis mengambil item dari antrean, sesuai urutan prioritas, menggunakan metode getDoc class Repository.

Operasi antrean (REST API)

REST API menyediakan dua metode berikut untuk mendorong item ke dan menarik item dari antrean:

• Untuk mendorong item ke antrean, gunakan Items.push.
• Untuk melakukan polling item dalam antrean, gunakan Items.poll.

Anda juga dapat menggunakan Items.index untuk memasukkan item ke antrean selama pengindeksan. Item yang dikirim ke antrean selama pengindeksan tidak memerlukan type dan secara otomatis diberi status ACCEPTED.

Items.push

Metode Items.push menambahkan ID ke antrean. Metode ini dapat dipanggil dengan nilai type tertentu yang menentukan hasil operasi push. Untuk daftar nilai type, lihat kolom item.type dalam metode Items.push.

Mendorong ID baru akan menghasilkan penambahan entri baru dengan kode NEW_ITEM ItemStatus.

Payload opsional selalu disimpan, diperlakukan sebagai nilai buram, dan ditampilkan dari Items.poll.

Saat ditarik, item akan memiliki status dipesan, artinya item tersebut tidak dapat ditampilkan oleh panggilan lain ke Items.poll. Menggunakan Items.push dengan type sebagai NOT_MODIFIED, REPOSITORY_ERROR, atau REQUEUE, unreservasi entri yang dikumpulkan. Untuk mengetahui informasi lebih lanjut tentang entri yang dipesan dan tidak dipesan, lihat bagian Items.poll.

Items.push dengan hash

Google Cloud Search API mendukung penentuan nilai hash konten dan metadata pada permintaan Items.index. Alih-alih menentukan type, nilai hash konten dan/atau metadata dapat ditentukan dengan permintaan push. Cloud Search Indexing Queue membandingkan nilai hash yang diberikan dengan nilai tersimpan yang tersedia pada item di sumber data. Jika tidak cocok, entri tersebut ditandai sebagai MODIFIED. Jika item yang sesuai tidak ada dalam indeks, statusnya adalah NEW_ITEM.

Catatan: Nilai hash yang diberikan dengan permintaan Items.push tidak disimpan dengan item. Item tersebut hanya digunakan untuk menentukan apakah item dimodifikasi atau tidak.

Items.poll

Metode Items.poll mengambil entri dengan prioritas tertinggi dari antrean. Nilai status yang diminta dan ditampilkan menunjukkan status antrean prioritas yang diminta atau status ID yang ditampilkan.

Secara default, entri dari setiap bagian antrean dapat ditampilkan berdasarkan prioritasnya. Setiap entri yang ditampilkan memiliki status reservasi, dan tidak ditampilkan oleh panggilan lain ke Items.poll hingga salah satu dari kasus berikut terpenuhi:

• Waktu reservasi habis.
• Entri dimasukkan dalam antrean lagi oleh Items.index.
• Items.push dipanggil dengan nilai type NOT_MODIFIED, REPOSITORY_ERROR, atau REQUEUE.