Konektor konten adalah program software yang digunakan untuk menelusuri data dalam repositori perusahaan dan mengisi sumber data. Google menyediakan opsi berikut untuk mengembangkan konektor konten:
Content Connector SDK. Ini adalah pilihan yang baik jika Anda memprogram pada Java. Content Connector SDK adalah wrapper di sekitar REST API yang dapat Anda gunakan untuk membuat konektor dengan cepat. Untuk membuat konektor konten menggunakan SDK, lihat Membuat konektor konten menggunakan Content Connector SDK.
Library API atau REST API level rendah. Gunakan opsi ini jika Anda tidak melakukan pemrograman di Java atau jika memiliki codebase yang bisa mengakomodasi library atau REST API dengan lebih baik. Untuk membuat konektor konten menggunakan REST API, lihat Membuat konektor konten menggunakan REST API.
Konektor konten standar melakukan tugas-tugas berikut:
- Membaca dan memproses parameter konfigurasi.
- Menarik potongan data terpisah yang dapat diindeks, yang disebut "item," dari repositori konten pihak ketiga.
- Menggabungkan ACL, metadata, dan data konten ke dalam item yang dapat diindeks.
- Mengindeks item ke sumber data Cloud Search.
- (opsional) Mendeteksi pemberitahuan perubahan dari repositori konten pihak ketiga. Pemberitahuan perubahan diubah menjadi permintaan pengindeksan agar sumber data Cloud Search tetap sinkron dengan repositori pihak ketiga. Konektor hanya melakukan tugas ini jika repositori mendukung deteksi perubahan.
Buat konektor konten menggunakan Content Connector SDK
Bagian berikut menjelaskan cara membuat konektor konten menggunakan Content Connector SDK.
Menyiapkan dependensi
Anda harus menyertakan dependensi tertentu dalam file build Anda untuk menggunakan SDK. Klik tab di bawah ini untuk melihat dependensi lingkungan build Anda:
Maven
<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>
Gradle
compile group: 'com.google.enterprise.cloudsearch',
name: 'google-cloudsearch-indexing-connector-sdk',
version: 'v1-0.0.3'
Buat konfigurasi konektor Anda
Setiap konektor memiliki file konfigurasi yang berisi parameter yang digunakan oleh konektor, seperti ID untuk repositori Anda. Parameter didefinisikan sebagai
pasangan nilai kunci, seperti
api.sourceId=1234567890abcdef
.
Google Cloud Search SDK berisi beberapa parameter konfigurasi yang disediakan Google yang digunakan oleh semua konektor. Anda harus mendeklarasikan parameter yang disediakan Google berikut ini dalam file konfigurasi Anda:
- Untuk konektor konten, Anda harus mendeklarasikan
api.sourceId
danapi.serviceAccountPrivateKeyFile
sebagai parameter ini mengidentifikasi lokasi repositori dan kunci pribadi Anda yang diperlukan untuk mengakses repositori.
- Untuk konektor identitas, Anda harus mendeklarasikan
api.identitySourceId
sebagai ini mengidentifikasi lokasi sumber identitas eksternal Anda. Jika Anda menyinkronkan pengguna, Anda juga harus mendeklarasikanapi.customerId
sebagai ID unik untuk ke akun Google Workspace perusahaan Anda.
Kecuali jika Anda ingin mengganti nilai default parameter lain yang disediakan Google, Anda tidak perlu mendeklarasikannya dalam file konfigurasi Anda. Untuk informasi tambahan tentang parameter konfigurasi yang disediakan Google, seperti cara membuat ID dan kunci tertentu, lihat Parameter konfigurasi yang disediakan Google.
Anda juga dapat menentukan parameter spesifik repositori Anda sendiri untuk digunakan dalam file konfigurasi Anda.
Teruskan file konfigurasi ke konektor
Setel properti sistem config
untuk meneruskan file konfigurasi ke
konektor 20%. Anda dapat menetapkan properti menggunakan argumen -D
saat memulai
ke konektor. Misalnya, perintah berikut memulai konektor
dengan file konfigurasi MyConfig.properties
:
java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector
Jika argumen ini tidak ada, SDK akan mencoba mengakses konfigurasi default
file bernama connector-config.properties
.
Tentukan strategi traversal Anda
Fungsi utama konektor konten adalah untuk menelusuri repositori dan mengindeks datanya. Anda harus menerapkan strategi traversal berdasarkan ukuran dan tata letak data di repositori Anda. Anda dapat mendesain strategi Anda sendiri atau memilih dari strategi berikut yang diterapkan di SDK:
- Strategi traversal penuh
Strategi traversal penuh memindai seluruh repositori dan secara acak mengindeks setiap item. Strategi ini biasanya digunakan jika Anda memiliki repositori kecil dan dapat menanggung overhead ketika melakukan traversal penuh setiap kali Anda mengindeks.
Strategi traversal ini cocok untuk repositori kecil yang sebagian besarnya berisi data statis dan tidak hierarkis. Anda juga dapat menggunakan strategi traversal ini jika sulit mendeteksi perubahan atau tidak didukung oleh repositori.
- Strategi traversal daftar
Strategi traversal daftar memindai seluruh repositori, termasuk semua node turunan, yang menentukan status setiap item. Lalu, konektor mengambil lintasan kedua dan hanya mengindeks item yang baru atau telah diiupdate sejak pengindeksan terakhir. Strategi ini biasanya digunakan untuk melakukan update inkremental terhadap indeks yang ada (bukannya harus melakukan traversal penuh setiap kali Anda mengupdate indeks).
Strategi traversal ini cocok jika sulit mendeteksi perubahan atau tidak didukung oleh repositori, Anda memiliki data yang tidak hierarkis, dan Anda mengerjakan set data yang sangat besar.
- Traversal grafik
Strategi traversal grafik memindai seluruh node induk yang menentukan status setiap item. Lalu, konektor mengambil lintasan kedua dan hanya mengindeks item baru atau item yang telah diupdate dalam node root sejak pengindeksan terakhir. Akhirnya, konektor meneruskan ID turunan apa pun, lalu mengindeks item baru atau item yang telah diupdate dalam node turunan. Konektor terus berlanjut secara berulang melalui semua node turunan sampai semua item telah ditangani. Traversal semacam itu biasanya digunakan untuk repositori hierarkis yang tidak memungkinkan pembuatan daftar semua ID.
Strategi ini cocok jika Anda memiliki data hierarkis yang perlu di-crawl, seperti serangkaian direktori atau halaman web.
Tiap strategi traversal ini diterapkan oleh konektor template di SDK. Meskipun Anda dapat mengimplementasikan strategi traversal Anda sendiri, template sangat mempercepat pengembangan konektor Anda. Untuk membuat konektor menggunakan template, lanjutkan ke bagian yang sesuai dengan strategi traversal Anda:
- Membuat konektor traversal penuh menggunakan class template
- Membuat konektor traversal daftar menggunakan class template
- Membuat konektor traversal grafik menggunakan class template
Membuat konektor traversal penuh menggunakan class template
Bagian dokumen ini mengacu ke cuplikan kode dari contoh FullTraversalSample.
Menerapkan titik entri konektor
Titik entri ke konektor adalah
Metode main()
. Tugas utama metode ini adalah membuat instance
Application
dan memanggil
start()
untuk menjalankan konektor.
Sebelum menelepon
application.start()
,
gunakan
IndexingApplication.Builder
untuk membuat instance
FullTraversalConnector
{i>template<i}. Tujuan
FullTraversalConnector
menerima
Repository
yang metodenya Anda implementasikan. Cuplikan kode berikut menunjukkan cara
untuk mengimplementasikan metode main()
:
Di balik layar, SDK memanggil
initConfig()
setelah metode main()
konektor Anda memanggil
Application.build
.
Tujuan
initConfig()
metode
melakukan tugas berikut:
- Memanggil
Configuation.isInitialized()
untuk memastikan bahwaConfiguration
belum diinisialisasi. - Melakukan inisialisasi objek
Configuration
dengan nilai kunci yang disediakan Google pasangan. Setiap pasangan nilai kunci disimpan dalamConfigValue
dalam objekConfiguration
.
Menerapkan antarmuka Repository
Satu-satunya tujuan objek Repository
adalah untuk melakukan traversal dan
pengindeksan item repositori. Saat menggunakan
template, Anda hanya perlu mengganti metode tertentu dalam Repository
untuk membuat konektor konten. Metode yang Anda ganti bergantung pada template dan strategi traversal yang Anda gunakan. Untuk
FullTraversalConnector
, ganti metode berikut:
Tujuan
init()
. Untuk melakukan penyiapan dan inisialisasi repositori data, ganti Metodeinit()
.Tujuan
getAllDocs()
. Untuk menelusuri dan mengindeks semua item dalam repositori data, ganti MetodegetAllDocs()
. Metode ini dipanggil satu kali untuk setiap traversal terjadwal (sebagaimana ditentukan oleh konfigurasi Anda).(opsional)
getChanges()
. Jika repositori Anda mendukung deteksi perubahan, ganti MetodegetChanges()
. Metode ini dipanggil satu kali untuk setiap traversal inkremental terjadwal (sebagaimana ditentukan oleh konfigurasi Anda) untuk mengambil item yang dimodifikasi dan mengindeksnya.(opsional)
close()
. Jika Anda perlu melakukan pembersihan repositori, ganticlose()
. Metode ini dipanggil sekali selama penutupan konektor.
Tiap metode
Objek Repository
menampilkan beberapa jenis
ApiOperation
. Objek ApiOperation
melakukan tindakan dalam bentuk tunggal, atau
mungkin beberapa, IndexingService.indexItem()
untuk melakukan pengindeksan
repositori Anda yang sebenarnya.
Mendapatkan parameter konfigurasi khusus
Sebagai bagian dari penanganan konfigurasi konektor, Anda harus mendapatkan
parameter kustom dari
Configuration
. Tugas ini biasanya dilakukan di
Repository
kelas
Metode init()
.
Class Configuration
memiliki beberapa metode untuk mendapatkan berbagai jenis data
dari suatu konfigurasi. Setiap metode menampilkan objek ConfigValue
. Anda kemudian akan
gunakan objek ConfigValue
get()
untuk mengambil nilai aktual.
Cuplikan berikut, dari
FullTraversalSample
,
menunjukkan cara mengambil
nilai bilangan bulat kustom tunggal dari objek Configuration
:
Untuk mendapatkan dan mengurai parameter yang berisi beberapa nilai, gunakan salah satu metode
Parser jenis class Configuration
untuk mengurai data menjadi potongan terpisah.
Cuplikan berikut, dari konektor tutorial menggunakan
getMultiValue
untuk mendapatkan daftar nama repositori GitHub:
Melakukan traversal penuh
Ganti
getAllDocs()
untuk melakukan traversal penuh dan mengindeks repositori Anda. getAllDocs()
menerima sebuah checkpoint. Checkpoint digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu. Untuk setiap item dalam
repositori, lakukan langkah-langkah berikut dalam metode getAllDocs()
:
- Tetapkan izin.
- Tetapkan metadata untuk item yang Anda indeks.
- Menggabungkan metadata dan item ke dalam satu file yang dapat diindeks
RepositoryDoc
- Gabungkan setiap item yang dapat diindeks ke dalam iterator yang ditampilkan oleh
getAllDocs()
. Perhatikan bahwagetAllDocs()
sebenarnya menampilkanCheckpointCloseableIterable
yang merupakan iterasi dariApiOperation
masing-masing objek yang mewakili permintaan API yang dijalankan padaRepositoryDoc
, seperti mengindeksnya.
Jika kumpulan item terlalu besar untuk diproses dalam satu panggilan, sertakan
pos pemeriksaan dan mengatur
hasMore(true)
guna menunjukkan lebih banyak item
yang tersedia untuk diindeks.
Menetapkan izin untuk suatu item
Repositori Anda menggunakan Daftar Kontrol Akses (ACL) untuk mengidentifikasi pengguna atau grup yang memiliki akses ke suatu item. ACL adalah daftar ID untuk grup atau pengguna yang dapat mengakses item tersebut.
Anda harus menduplikasi ACL yang digunakan oleh repositori Anda untuk memastikan hanya pengguna tersebut yang memiliki akses ke item dapat melihat item tersebut dalam hasil penelusuran. Tujuan ACL untuk suatu item harus disertakan saat mengindeks item sehingga Google Cloud Search memiliki informasi yang diperlukan untuk memberikan tingkat akses yang benar ke item tersebut.
Content Connector SDK menyediakan banyak kumpulan class dan metode ACL untuk membuat model ACL dari sebagian besar repositori. Anda harus menganalisis ACL untuk setiap item dalam repositori Anda dan membuat ACL yang sesuai untuk Google Cloud Search ketika Anda mengindeks item. Jika ACL repositori Anda menggunakan konsep seperti warisan ACL, membuat model ACL tersebut bisa rumit. Untuk informasi lebih lanjut tentang Google Cloud Search ACL, lihat Google Cloud Search ACL.
Catatan: Cloud Search Indexing API mendukung ACL domain tunggal. ACL lintas domain tidak didukung. Gunakan
Acl.Builder
untuk mengatur akses ke
setiap item menggunakan ACL. Cuplikan kode berikut, diambil
dari sampel traversal penuh, memungkinkan
semua pengguna atau "akun utama"
(getCustomerPrincipal()
)
menjadi “pembaca” semua item
(.setReaders()
)
saat melakukan penelusuran.
Anda perlu memahami ACL untuk membuat model ACL dengan benar di repositori. Misalnya, Anda mungkin mengindeks file dalam sistem file yang menggunakan semacam model warisan dengan folder turunan mewarisi izin dari folder induk. Membuat model warisan ACL memerlukan informasi tambahan yang tercakup dalam Google Cloud Search ACL
Menetapkan metadata untuk suatu item
Metadata disimpan dalam objek Item
. Untuk membuat Item
, Anda memerlukan
minimum ID string unik, jenis item, ACL, URL, dan versi untuk item.
Cuplikan kode berikut menunjukkan cara mem-build Item
menggunakan
IndexingItemBuilder
.
Membuat item yang dapat diindeks
Setelah Anda menetapkan metadata untuk item, Anda dapat membuat
item menggunakan
RepositoryDoc.Builder
. Contoh berikut menunjukkan cara membuat item tunggal yang dapat diindeks.
RepositoryDoc
adalah jenis ApiOperation
yang menjalankan fungsi
Permintaan IndexingService.indexItem()
.
Anda juga dapat menggunakan
Metode setRequestMode()
dari
RepositoryDoc.Builder
untuk mengidentifikasi permintaan pengindeksan sebagai ASYNCHRONOUS
atau SYNCHRONOUS
:
ASYNCHRONOUS
- Mode asinkron menghasilkan latensi pengindeksan hingga penayangan yang lebih lama dan mengakomodasi kuota throughput yang besar untuk permintaan pengindeksan. Mode asinkron adalah direkomendasikan untuk pengindeksan awal (pengisian ulang) seluruh repositori.
SYNCHRONOUS
- Mode sinkron menghasilkan latensi pengindeksan hingga penayangan yang lebih pendek dan
mengakomodasi kuota throughput terbatas. Mode sinkron direkomendasikan untuk mengindeks update dan perubahan pada repositori. Jika
tidak ditentukan, mode permintaan ditetapkan secara default ke
SYNCHRONOUS
.
Gabungkan setiap item yang dapat diindeks dalam iterator
getAllDocs()
menampilkan Iterator
, khususnya metode
CheckpointCloseableIterable
,
pengguna
RepositoryDoc
objek terstruktur dalam jumlah besar. Anda dapat menggunakan
CheckpointClosableIterableImpl.Builder
untuk membangun dan mengembalikan iterator. Cuplikan kode berikut ini menunjukkan cara membuat dan menampilkan iterator.
SDK menjalankan setiap panggilan pengindeksan yang terkurung dalam iterator.
Langkah Berikutnya
Berikut beberapa langkah yang dapat Anda ambil:
- (opsional) Jika throughput pengindeksan Anda tampak lambat, lihat Meningkatkan rasio pengindeksan untuk
FullTraversalConnector
. - (opsional) Menerapkan
close()
untuk melepaskan resource apa pun sebelum dimatikan. - (opsional) Buat konektor identitas menggunakan Content Connector SDK.
Membuat konektor traversal daftar menggunakan class template
Cloud Search Indexing Queue digunakan untuk menyimpan ID dan nilai hash opsional untuk setiap item dalam repositori. Konektor traversal daftar mendorong ID item ke Google Cloud Search Indexing Queue dan mengambilnya satu per satu untuk diindeks. Google Cloud Search mengelola antrean dan membandingkan konten antrean untuk menentukan status item, seperti apakah suatu item telah dihapus dari repositori. Untuk informasi lebih lanjut tentang Antrean Pengindeksan, lihat Cloud Search Indexing Queue.
Bagian dokumen ini mengacu ke cuplikan kode dari contoh ListTraversalSample.
Menerapkan titik entri konektor
Titik entri ke konektor adalah
Metode main()
. Tugas utama metode ini adalah membuat instance
Application
dan memanggil
start()
untuk menjalankan konektor.
Sebelum menelepon
application.start()
,
gunakan
IndexingApplication.Builder
untuk membuat instance
ListingConnector
{i>template<i}. ListingConnector
menerima
Repository
yang metodenya Anda implementasikan. Cuplikan berikut menunjukkan cara
Buat instance ListingConnector
dan Repository
yang terkait:
Di balik layar, SDK memanggil
initConfig()
setelah metode main()
konektor Anda memanggil
Application.build
.
Metode initConfig()
:
- Memanggil
Configuation.isInitialized()
untuk memastikan bahwaConfiguration
belum diinisialisasi. - Melakukan inisialisasi objek
Configuration
dengan nilai kunci yang disediakan Google pasangan. Setiap pasangan nilai kunci disimpan dalamConfigValue
dalam objekConfiguration
.
Menerapkan antarmuka Repository
Satu-satunya tujuan objek Repository
adalah untuk melakukan traversal dan
pengindeksan item repositori. Saat menggunakan template, Anda hanya perlu mengganti
metode tertentu dalam antarmuka Repository
untuk membuat konektor konten.
Metode yang Anda ganti bergantung pada template dan strategi traversal yang Anda gunakan. Untuk
ListingConnector
,
mengganti metode berikut:
Tujuan
init()
. Untuk melakukan penyiapan dan inisialisasi repositori data, ganti Metodeinit()
.getIds()
. Untuk mengambil ID dan nilai hash untuk semua catatan dalam repositori, mengganti metodegetIds()
.getDoc()
. Untuk menambahkan, memperbarui, memodifikasi, atau menghapus item dari indeks, ganti MetodegetDoc()
.(opsional)
getChanges()
. Jika repositori Anda mendukung deteksi perubahan, ganti MetodegetChanges()
. Metode ini dipanggil satu kali untuk setiap traversal inkremental terjadwal (sebagaimana ditentukan oleh konfigurasi Anda) untuk mengambil item yang dimodifikasi dan mengindeksnya.(opsional)
close()
. Jika Anda perlu melakukan pembersihan repositori, ganticlose()
. Metode ini dipanggil sekali selama penutupan konektor.
Setiap metode objek Repository
menampilkan beberapa jenis
ApiOperation
. Objek ApiOperation
melakukan tindakan dalam bentuk tunggal, atau
mungkin beberapa, IndexingService.indexItem()
untuk melakukan pengindeksan
repositori Anda yang sebenarnya.
Mendapatkan parameter konfigurasi khusus
Sebagai bagian dari penanganan konfigurasi konektor, Anda harus mendapatkan
parameter kustom dari
Configuration
. Tugas ini biasanya dilakukan di
Repository
kelas
Metode init()
.
Class Configuration
memiliki beberapa metode untuk mendapatkan berbagai jenis data
dari suatu konfigurasi. Setiap metode menampilkan objek ConfigValue
. Anda kemudian akan
gunakan objek ConfigValue
get()
untuk mengambil nilai aktual.
Cuplikan berikut, dari
FullTraversalSample
,
menunjukkan cara mengambil
nilai bilangan bulat kustom tunggal dari objek Configuration
:
Untuk mendapatkan dan mengurai parameter yang berisi beberapa nilai, gunakan salah satu metode
Parser jenis class Configuration
untuk mengurai data menjadi potongan terpisah.
Cuplikan berikut, dari konektor tutorial menggunakan
getMultiValue
untuk mendapatkan daftar nama repositori GitHub:
Melakukan traversal daftar
Ganti
getIds()
untuk mengambil ID dan nilai hash untuk semua catatan dalam repositori.
Metode getIds()
menerima sebuah checkpoint. Checkpoint digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu.
Berikutnya, ganti
getDoc()
web untuk menangani setiap item dalam Cloud Search Indexing Queue.
Mendorong ID item dan nilai hash
Ganti
getIds()
untuk mengambil ID item dan nilai hash kontennya yang terkait dari
repositori resource. Pasangan nilai hash dan ID kemudian digabungkan ke dalam permintaan operasi push ke Cloud Search Indexing Queue. ID root atau induk biasanya didorong terlebih dahulu diikuti oleh ID turunan sampai seluruh hierarki item telah diproses.
Metode getIds()
menerima checkpoint yang mewakili item terakhir yang akan
terindeks. Checkpoint dapat digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu. Untuk setiap item dalam repositori Anda, lakukan
langkah-langkah dalam metode getIds()
:
- Dapatkan setiap ID item dan nilai hash terkait dari repositori.
- Kemas setiap pasangan ID dan nilai hash ke dalam
PushItems
. - Gabungkan setiap
PushItems
ke dalam iterator yang ditampilkan olehgetIds()
. Perhatikan bahwagetIds()
sebenarnya menampilkanCheckpointCloseableIterable
yang merupakan iterasi dariApiOperation
setiap objek yang mewakili permintaan API yang dijalankan padaRepositoryDoc
, seperti mendorong item ke antrean.
Cuplikan kode berikut menunjukkan cara mendapatkan setiap ID item dan nilai hash serta
masukkan mereka ke dalam
PushItems
PushItems
adalah permintaan ApiOperation
untuk mengirim item ke Cloud Search
Antrean Pengindeksan.
Cuplikan kode berikut menunjukkan cara menggunakan
PushItems.Builder
untuk memaketkan ID dan nilai hash ke dalam satu push
ApiOperation
.
Item didorong ke Cloud Search Indexing Queue untuk diproses lebih lanjut.
Mengambil dan menangani setiap item
Ganti
getDoc()
untuk menangani setiap item dalam Cloud Search Indexing Queue.
Item bisa baru, dimodifikasi, tidak berubah, atau tidak bisa lagi ada di repositori sumber. Ambil dan lakukan pengindeksan untuk setiap item baru atau yang sudah diubah. Hapus item dari indeks yang tidak ada lagi di repositori sumber.
Metode getDoc()
menerima Item dari Google Cloud Search
Antrean Pengindeksan. Untuk setiap item dalam antrean, lakukan langkah-langkah ini di
Metode getDoc()
:
Periksa apakah ID item dalam Google Cloud Search Indexing Queue ada di repositori. Jika tidak, hapus item dari indeks.
Lakukan polling indeks untuk status item dan jika suatu item tidak berubah (
ACCEPTED
), jangan lakukan apa pun.Indeks yang berubah atau item baru:
- Tetapkan izin.
- Tetapkan metadata untuk item yang Anda indeks.
- Menggabungkan metadata dan item ke dalam satu file yang dapat diindeks
RepositoryDoc
- Tampilkan
RepositoryDoc
.
Catatan: Template ListingConnector
tidak mendukung ditampilkannya null
pada
metode getDoc()
. Menampilkan null
akan menghasilkan NullPointerException.
Menangani item yang dihapus
Cuplikan kode berikut ini menunjukkan cara menentukan apakah suatu item ada di repositori dan, jika tidak, menghapus item tersebut.
Perhatikan bahwa documents
adalah struktur data yang mewakili repositori. Jika
documentID
tidak ditemukan di documents
, tampilkan
APIOperations.deleteItem(resourceName)
untuk menghapus item dari indeks.
Menangani item yang tidak berubah
Cuplikan kode berikut menunjukkan cara melakukan polling status item dalam Cloud Search Indexing Queue dan menangani item yang tidak berubah.
Untuk menentukan apakah item tidak dimodifikasi, periksa status item serta metadata lain yang mungkin mengindikasikan perubahan. Misalnya, hash metadata digunakan untuk menentukan apakah item telah diubah.
Menetapkan izin untuk suatu item
Repositori Anda menggunakan Daftar Kontrol Akses (ACL) untuk mengidentifikasi pengguna atau grup yang memiliki akses ke suatu item. ACL adalah daftar ID untuk grup atau pengguna yang dapat mengakses item tersebut.
Anda harus menduplikasi ACL yang digunakan oleh repositori Anda untuk memastikan hanya pengguna tersebut yang memiliki akses ke item dapat melihat item tersebut dalam hasil penelusuran. Tujuan ACL untuk suatu item harus disertakan saat mengindeks item sehingga Google Cloud Search memiliki informasi yang diperlukan untuk memberikan tingkat akses yang benar ke item tersebut.
Content Connector SDK menyediakan banyak kumpulan class dan metode ACL untuk membuat model ACL dari sebagian besar repositori. Anda harus menganalisis ACL untuk setiap item dalam repositori Anda dan membuat ACL yang sesuai untuk Google Cloud Search ketika Anda mengindeks item. Jika ACL repositori Anda menggunakan konsep seperti warisan ACL, membuat model ACL tersebut bisa rumit. Untuk informasi lebih lanjut tentang Google Cloud Search ACL, lihat Google Cloud Search ACL.
Catatan: Cloud Search Indexing API mendukung ACL domain tunggal. ACL lintas domain tidak didukung. Gunakan
Acl.Builder
untuk mengatur akses ke
setiap item menggunakan ACL. Cuplikan kode berikut, diambil
dari sampel traversal penuh, memungkinkan
semua pengguna atau "akun utama"
(getCustomerPrincipal()
)
menjadi “pembaca” semua item
(.setReaders()
)
saat melakukan penelusuran.
Anda perlu memahami ACL untuk membuat model ACL dengan benar di repositori. Misalnya, Anda mungkin mengindeks file dalam sistem file yang menggunakan semacam model warisan dengan folder turunan mewarisi izin dari folder induk. Membuat model warisan ACL memerlukan informasi tambahan yang tercakup dalam Google Cloud Search ACL
Menetapkan metadata untuk suatu item
Metadata disimpan dalam objek Item
. Untuk membuat Item
, Anda memerlukan
minimum ID string unik, jenis item, ACL, URL, dan versi untuk item.
Cuplikan kode berikut menunjukkan cara mem-build Item
menggunakan
IndexingItemBuilder
.
Membuat item yang dapat diindeks
Setelah Anda menetapkan metadata untuk item, Anda dapat membuat
item menggunakan
RepositoryDoc.Builder
Contoh berikut menunjukkan cara membuat item tunggal yang dapat diindeks.
RepositoryDoc
adalah jenis
ApiOperation
yang menjalankan
IndexingService.indexItem()
permintaan.
Anda juga dapat menggunakan
Metode setRequestMode()
dari
RepositoryDoc.Builder
untuk mengidentifikasi permintaan pengindeksan sebagai ASYNCHRONOUS
atau SYNCHRONOUS
:
ASYNCHRONOUS
- Mode asinkron menghasilkan latensi pengindeksan hingga penayangan yang lebih lama dan mengakomodasi kuota throughput yang besar untuk permintaan pengindeksan. Mode asinkron adalah direkomendasikan untuk pengindeksan awal (pengisian ulang) seluruh repositori.
SYNCHRONOUS
- Mode sinkron menghasilkan latensi pengindeksan hingga penayangan yang lebih pendek dan
mengakomodasi kuota throughput terbatas. Mode sinkron direkomendasikan untuk mengindeks update dan perubahan pada repositori. Jika
tidak ditentukan, mode permintaan ditetapkan secara default ke
SYNCHRONOUS
.
Langkah Berikutnya
Berikut beberapa langkah yang dapat Anda ambil:
- (opsional) Menerapkan
close()
untuk melepaskan resource apa pun sebelum dimatikan. - (opsional) Buat konektor identitas menggunakan Content Connector SDK.
Membuat konektor traversal grafik menggunakan class template
Cloud Search Indexing Queue digunakan untuk menyimpan ID dan nilai hash opsional untuk setiap item dalam repositori. Konektor traversal grafik mendorong ID item ke Google Cloud Search Indexing Queue dan mengambilnya satu per satu pengindeksan. Google Cloud Search mengelola antrean dan membandingkan konten antrean untuk menentukan status item, seperti apakah suatu item telah dihapus dari repositori. Untuk mengetahui informasi lebih lanjut tentang Cloud Search Indexing Queue, lihat dapat Google Cloud Search Indexing Queue.
Selama indeks, konten item diambil dari repositori data dan setiap ID item turunan didorong ke antrean. Konektor menghasilkan pemrosesan ID induk dan turunan secara berulang sampai semua item ditangani.
Bagian dokumen ini mengacu ke cuplikan kode dari contoh GraphTraversalSample.
Menerapkan titik entri konektor
Titik entri ke konektor adalah
Metode main()
. Tugas utama metode ini adalah membuat instance
Application
dan memanggil
start()
untuk menjalankan konektor.
Sebelum menelepon
application.start()
,
gunakan
IndexingApplication.Builder
untuk membuat instance template ListingConnector
. Tujuan
ListingConnector
menerima
Repository
yang metodenya Anda implementasikan.
Cuplikan berikut menunjukkan cara
Buat instance ListingConnector
dan Repository
yang terkait:
Di balik layar, SDK memanggil
initConfig()
setelah metode main()
konektor Anda memanggil
Application.build
.
Metode initConfig()
:
- Memanggil
Configuation.isInitialized()
untuk memastikan bahwaConfiguration
belum diinisialisasi. - Melakukan inisialisasi objek
Configuration
dengan nilai kunci yang disediakan Google pasangan. Setiap pasangan nilai kunci disimpan dalamConfigValue
dalam objekConfiguration
.
Menerapkan antarmuka Repository
Satu-satunya tujuan
Objek Repository
akan digunakan untuk melakukan traversal dan pengindeksan repositori
item. Saat menggunakan template, Anda hanya perlu mengganti metode tertentu dalam
Antarmuka Repository
untuk membuat konektor konten. Metode yang Anda ganti bergantung pada template dan strategi traversal yang Anda gunakan. Untuk
ListingConnector
,
Anda akan mengganti metode berikut:
Tujuan
init()
. Untuk melakukan penyiapan dan inisialisasi repositori data, ganti Metodeinit()
.getIds()
. Untuk mengambil ID dan nilai hash untuk semua catatan dalam repositori, mengganti metodegetIds()
.getDoc()
. Untuk menambahkan, memperbarui, memodifikasi, atau menghapus item dari indeks, ganti MetodegetDoc()
.(opsional)
getChanges()
. Jika repositori Anda mendukung deteksi perubahan, ganti MetodegetChanges()
. Metode ini dipanggil satu kali untuk setiap traversal inkremental terjadwal (sebagaimana ditentukan oleh konfigurasi Anda) untuk mengambil item yang dimodifikasi dan mengindeksnya.(opsional)
close()
. Jika Anda perlu melakukan pembersihan repositori, ganticlose()
. Metode ini dipanggil sekali selama penutupan konektor.
Tiap metode
Objek Repository
menampilkan beberapa jenis objek ApiOperation
. ApiOperation
objek melakukan tindakan dalam bentuk satu, atau mungkin beberapa,
IndexingService.indexItem()
untuk melakukan pengindeksan
repositori Anda yang sebenarnya.
Mendapatkan parameter konfigurasi khusus
Sebagai bagian dari penanganan konfigurasi konektor, Anda harus mendapatkan
parameter kustom dari
Configuration
. Tugas ini biasanya dilakukan di
Repository
kelas
Metode init()
.
Class Configuration
memiliki beberapa metode untuk mendapatkan berbagai jenis data
dari suatu konfigurasi. Setiap metode menampilkan objek ConfigValue
. Anda kemudian akan
gunakan objek ConfigValue
get()
untuk mengambil nilai aktual.
Cuplikan berikut, dari
FullTraversalSample
,
menunjukkan cara mengambil
nilai bilangan bulat kustom tunggal dari objek Configuration
:
Untuk mendapatkan dan mengurai parameter yang berisi beberapa nilai, gunakan salah satu metode
Parser jenis class Configuration
untuk mengurai data menjadi potongan terpisah.
Cuplikan berikut, dari konektor tutorial menggunakan
getMultiValue
untuk mendapatkan daftar nama repositori GitHub:
Melakukan traversal grafik
Ganti
getIds()
untuk mengambil ID dan nilai hash untuk semua catatan dalam repositori.
Metode getIds()
menerima sebuah checkpoint. Checkpoint digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu.
Berikutnya, ganti
getDoc()
web untuk menangani setiap item dalam Cloud Search Indexing Queue.
Mendorong ID item dan nilai hash
Ganti
getIds()
untuk mengambil ID item dan nilai hash kontennya yang terkait dari
repositori resource. Pasangan nilai hash dan ID kemudian digabungkan ke dalam permintaan operasi push ke Cloud Search Indexing Queue. ID root atau induk biasanya didorong terlebih dahulu diikuti oleh ID turunan sampai seluruh hierarki item telah diproses.
Metode getIds()
menerima checkpoint yang mewakili item terakhir yang akan
terindeks. Checkpoint dapat digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu. Untuk setiap item dalam repositori Anda, lakukan
langkah-langkah dalam metode getIds()
:
- Dapatkan setiap ID item dan nilai hash terkait dari repositori.
- Kemas setiap pasangan ID dan nilai hash ke dalam
PushItems
. - Gabungkan setiap
PushItems
ke dalam iterator yang ditampilkan oleh MetodegetIds()
. Perhatikan bahwagetIds()
sebenarnya menampilkanCheckpointCloseableIterable
yang merupakan iterasi dariApiOperation
setiap objek yang mewakili permintaan API yang dijalankan padaRepositoryDoc
, seperti mendorong item ke antrean.
Cuplikan kode berikut menunjukkan cara mendapatkan setiap ID item dan nilai hash serta
masukkan mereka ke dalam
PushItems
. PushItems
adalah
ApiOperation
untuk mengirim item ke Cloud Search Indexing Queue.
Cuplikan kode berikut menunjukkan cara menggunakan
PushItems.Builder
untuk memaketkan ID dan nilai hash ke dalam satu push
ApiOperation
Item didorong ke Cloud Search Indexing Queue untuk diproses lebih lanjut.
Mengambil dan menangani setiap item
Ganti
getDoc()
untuk menangani setiap item dalam Cloud Search Indexing Queue.
Item bisa baru, dimodifikasi, tidak berubah, atau tidak bisa lagi ada di repositori sumber. Ambil dan lakukan pengindeksan untuk setiap item baru atau yang sudah diubah. Hapus item dari indeks yang tidak ada lagi di repositori sumber.
Metode getDoc()
menerima Item dari Pengindeksan Cloud Search
Antrean. Untuk setiap item dalam antrean, lakukan langkah-langkah ini di
Metode getDoc()
:
Periksa apakah ID item, dalam Cloud Search Indexing Queue, ada di repositori. Jika tidak, hapus item dari indeks. Jika item tersebut ada, lanjutkan ke langkah berikutnya.
Indeks yang berubah atau item baru:
- Tetapkan izin.
- Tetapkan metadata untuk item yang Anda indeks.
- Menggabungkan metadata dan item ke dalam satu file yang dapat diindeks
RepositoryDoc
- Tempatkan ID turunan dalam Cloud Search Indexing Queue untuk diproses lebih lanjut.
- Tampilkan
RepositoryDoc
.
Menangani item yang dihapus
Cuplikan kode berikut ini menunjukkan cara menentukan apakah suatu item ada di indeks dan, jika tidak, hapus item tersebut.
Menetapkan izin untuk suatu item
Repositori Anda menggunakan Daftar Kontrol Akses (ACL) untuk mengidentifikasi pengguna atau grup yang memiliki akses ke suatu item. ACL adalah daftar ID untuk grup atau pengguna yang dapat mengakses item tersebut.
Anda harus menduplikasi ACL yang digunakan oleh repositori Anda untuk memastikan hanya pengguna tersebut yang memiliki akses ke item dapat melihat item tersebut dalam hasil penelusuran. Tujuan ACL untuk suatu item harus disertakan saat mengindeks item sehingga Google Cloud Search memiliki informasi yang diperlukan untuk memberikan tingkat akses yang benar ke item tersebut.
Content Connector SDK menyediakan banyak kumpulan class dan metode ACL untuk membuat model ACL dari sebagian besar repositori. Anda harus menganalisis ACL untuk setiap item dalam repositori Anda dan membuat ACL yang sesuai untuk Google Cloud Search ketika Anda mengindeks item. Jika ACL repositori Anda menggunakan konsep seperti warisan ACL, membuat model ACL tersebut bisa rumit. Untuk informasi lebih lanjut tentang Google Cloud Search ACL, lihat Google Cloud Search ACL.
Catatan: Cloud Search Indexing API mendukung ACL domain tunggal. ACL lintas domain tidak didukung. Gunakan
Acl.Builder
untuk mengatur akses ke
setiap item menggunakan ACL. Cuplikan kode berikut, diambil
dari sampel traversal penuh, memungkinkan
semua pengguna atau "akun utama"
(getCustomerPrincipal()
)
menjadi “pembaca” semua item
(.setReaders()
)
saat melakukan penelusuran.
Anda perlu memahami ACL untuk membuat model ACL dengan benar di repositori. Misalnya, Anda mungkin mengindeks file dalam sistem file yang menggunakan semacam model warisan dengan folder turunan mewarisi izin dari folder induk. Membuat model warisan ACL memerlukan informasi tambahan yang tercakup dalam Google Cloud Search ACL
Menetapkan metadata untuk suatu item
Metadata disimpan dalam objek Item
. Untuk membuat Item
, Anda memerlukan
minimum ID string unik, jenis item, ACL, URL, dan versi untuk item.
Cuplikan kode berikut menunjukkan cara mem-build Item
menggunakan
IndexingItemBuilder
.
Membuat item yang dapat diindeks
Setelah Anda menetapkan metadata untuk item, Anda dapat membuat
item menggunakan
RepositoryDoc.Builder
Contoh berikut menunjukkan cara membuat item tunggal yang dapat diindeks.
RepositoryDoc
adalah jenis ApiOperation
yang menjalankan fungsi
Permintaan IndexingService.indexItem()
.
Anda juga dapat menggunakan
Metode setRequestMode()
dari
RepositoryDoc.Builder
untuk mengidentifikasi permintaan pengindeksan sebagai ASYNCHRONOUS
atau SYNCHRONOUS
:
ASYNCHRONOUS
- Mode asinkron menghasilkan latensi pengindeksan hingga penayangan yang lebih lama dan mengakomodasi kuota throughput yang besar untuk permintaan pengindeksan. Mode asinkron adalah direkomendasikan untuk pengindeksan awal (pengisian ulang) seluruh repositori.
SYNCHRONOUS
- Mode sinkron menghasilkan latensi pengindeksan hingga penayangan yang lebih pendek dan
mengakomodasi kuota throughput terbatas. Mode sinkron direkomendasikan untuk mengindeks update dan perubahan pada repositori. Jika
tidak ditentukan, mode permintaan ditetapkan secara default ke
SYNCHRONOUS
.
Menempatkan ID turunan dalam Cloud Search Indexing Queue
Cuplikan kode berikut ini menunjukkan cara menyertakan ID turunan, untuk item induk yang sedang diproses, ke dalam antrean untuk diproses. ID ini diproses setelah item induk diindeks.
Langkah Berikutnya
Berikut beberapa langkah yang dapat Anda ambil:
- (opsional) Menerapkan
close()
untuk melepaskan resource apa pun sebelum dimatikan. - (opsional) Buat konektor identitas menggunakan Identity Connector SDK.
Membuat konektor konten menggunakan REST API
Bagian berikut menjelaskan cara membuat konektor konten menggunakan REST API.
Tentukan strategi traversal Anda
Fungsi utama konektor konten adalah untuk menelusuri repositori dan mengindeks datanya. Anda harus menerapkan strategi traversal berdasarkan ukuran dan tata letak data di repositori Anda. Berikut ini adalah tiga strategi traversal yang umum:
- Strategi traversal penuh
Strategi traversal penuh memindai seluruh repositori dan secara acak mengindeks setiap item. Strategi ini biasanya digunakan jika Anda memiliki repositori kecil dan dapat menanggung overhead ketika melakukan traversal penuh setiap kali Anda mengindeks.
Strategi traversal ini cocok untuk repositori kecil yang sebagian besarnya berisi data statis dan tidak hierarkis. Anda juga dapat menggunakan strategi traversal ini jika sulit mendeteksi perubahan atau tidak didukung oleh repositori.
- Strategi traversal daftar
Strategi traversal daftar memindai seluruh repositori, termasuk semua node turunan, yang menentukan status setiap item. Lalu, konektor mengambil lintasan kedua dan hanya mengindeks item yang baru atau telah diiupdate sejak pengindeksan terakhir. Strategi ini biasanya digunakan untuk melakukan update inkremental terhadap indeks yang ada (bukannya harus melakukan traversal penuh setiap kali Anda mengupdate indeks).
Strategi traversal ini cocok jika sulit mendeteksi perubahan atau tidak didukung oleh repositori, Anda memiliki data yang tidak hierarkis, dan Anda mengerjakan set data yang sangat besar.
- Traversal grafik
Strategi traversal grafik memindai seluruh node induk yang menentukan status setiap item. Lalu, konektor mengambil lintasan kedua dan hanya mengindeks item baru atau item yang telah diupdate dalam node root sejak pengindeksan terakhir. Akhirnya, konektor meneruskan ID turunan apa pun, lalu mengindeks item baru atau item yang telah diupdate dalam node turunan. Konektor terus berlanjut secara berulang melalui semua node turunan sampai semua item telah ditangani. Traversal semacam itu biasanya digunakan untuk repositori hierarkis yang tidak memungkinkan pembuatan daftar semua ID.
Strategi ini cocok jika Anda memiliki data hierarkis yang perlu di-crawl, seperti serangkaian direktori atau halaman web.
Menerapkan strategi traversal Anda dan item indeks
Setiap elemen yang dapat diindeks untuk Cloud Search disebut sebagai item di Cloud Search API. Item dapat berupa file, folder, baris di file CSV, atau pencatatan {i>database<i}.
Setelah skema Anda terdaftar, Anda dapat mengisi indeks dengan:
(opsional) Menggunakan
items.upload
mengunggah file yang berukuran lebih besar dari 100 KiB untuk pengindeksan. Untuk file yang lebih kecil, sematkan konten sebagai inlineContent menggunakanitems.index
(opsional) Menggunakan
media.upload
mengupload file media untuk pengindeksan.Menggunakan
items.index
untuk mengindeks item. Misalnya, jika skema Anda menggunakan definisi objek dalam format film schema, yaitu permintaan pengindeksan untuk satu item akan terlihat seperti ini:{ "name": "datasource/<data_source_id>/items/titanic", "acl": { "readers": [ { "gsuitePrincipal": { "gsuiteDomain": true } } ] }, "metadata": { "title": "Titanic", "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1", "objectType": "movie" }, "structuredData": { "object": { "properties": [ { "name": "movieTitle", "textValues": { "values": [ "Titanic" ] } }, { "name": "releaseDate", "dateValues": { "values": [ { "year": 1997, "month": 12, "day": 19 } ] } }, { "name": "actorName", "textValues": { "values": [ "Leonardo DiCaprio", "Kate Winslet", "Billy Zane" ] } }, { "name": "genre", "enumValues": { "values": [ "Drama", "Action" ] } }, { "name": "userRating", "integerValues": { "values": [ 8 ] } }, { "name": "mpaaRating", "textValues": { "values": [ "PG-13" ] } }, { "name": "duration", "textValues": { "values": [ "3 h 14 min" ] } } ] } }, "content": { "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.", "contentFormat": "TEXT" }, "version": "01", "itemType": "CONTENT_ITEM" }
(Opsional) Menggunakan items.get panggilan telepon untuk memverifikasi item telah diindeks.
Untuk melakukan traversal penuh, Anda akan mengindeks ulang seluruh repositori secara berkala. Untuk melakukan traversal daftar atau grafik, Anda perlu menerapkan kode untuk menangani perubahan repositori.
Menangani perubahan repositori
Anda dapat secara berkala mengumpulkan dan mengindeks setiap item dari repositori untuk melakukan pengindeksan penuh. Meskipun efektif untuk memastikan indeks Anda terbaru, pengindeksan penuh bisa mahal jika harus menangani repositori yang lebih besar atau hierarkis.
Sebagai ganti menggunakan panggilan indeks untuk mengindeks seluruh repositori yang terlalu sering, Anda juga dapat menggunakan Google Cloud Indexing Queue sebagai mekanisme untuk melacak perubahan dan hanya mengindeks item-item yang telah berubah. Anda dapat menggunakan items.push permintaan untuk mendorong item ke antrean untuk polling dan pembaruan berikutnya. Untuk selengkapnya informasi tentang Google Cloud Indexing Queue, Google Cloud Indexing Queue.
Untuk informasi lebih lanjut tentang Google Cloud Search API, lihat API Cloud Search.