Membuat konektor konten

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 opsi yang tepat jika Anda melakukan pemrograman di 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:

1. Membaca dan memproses parameter konfigurasi.
2. Menarik potongan data terpisah yang dapat diindeks, yang disebut "item," dari repositori konten pihak ketiga.
3. Menggabungkan ACL, metadata, dan data konten ke dalam item yang dapat diindeks.
4. Mengindeks item ke sumber data Cloud Search.
5. (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 ditetapkan 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 dan api.serviceAccountPrivateKeyFile karena parameter ini mengidentifikasi lokasi repositori dan kunci pribadi yang diperlukan untuk mengakses repositori.

Catatan: Jika file kunci pribadi Anda bukan kunci JSON, Anda juga harus mengganti api.serviceAccountId.

• Untuk konektor identitas, Anda harus mendeklarasikan api.identitySourceId karena parameter ini mengidentifikasi lokasi sumber identitas eksternal Anda. Jika menyinkronkan pengguna, Anda juga harus mendeklarasikan api.customerId sebagai ID unik untuk 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.

Catatan: Tidak ada persyaratan penamaan yang ketat untuk file properti konektor, tetapi sebaiknya simpan file menggunakan ekstensi .properties atau .config.

Teruskan file konfigurasi ke konektor

Tetapkan properti sistem config untuk meneruskan file konfigurasi ke konektor Anda. Anda dapat menetapkan properti menggunakan argumen -D saat memulai 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 file konfigurasi default 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.

Catatan: Istilah "item" dan "dokumen" sama dalam dokumen dan kode sampel ini.

Masing-masing strategi traversal ini diterapkan oleh class konektor template di SDK. Meskipun Anda dapat menerapkan strategi traversal Anda sendiri, template ini sangat mempercepat pengembangan konektor Anda. Untuk membuat konektor menggunakan template, lanjutkan ke bagian yang sesuai dengan strategi traversal Anda:

• Membuat konektor traversal lengkap 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 class Application dan memanggil metode start() untuk menjalankan konektor.

Sebelum memanggil application.start(), gunakan class IndexingApplication.Builder untuk membuat instance template FullTraversalConnector. FullTraversalConnector menerima objek Repository yang metodenya Anda terapkan. Cuplikan kode berikut menunjukkan cara menerapkan metode main():

FullTraversalSample.java

Lihat di GitHub

/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Di balik layar, SDK memanggil metode initConfig() setelah metode main() konektor Anda memanggil Application.build. Metode initConfig() melakukan tugas-tugas berikut:

1. Memanggil metode Configuation.isInitialized() untuk memastikan bahwa Configuration belum diinisialisasi.
2. Menginisialisasi objek Configuration dengan key-value pair yang disediakan Google. Setiap key-value pair disimpan dalam objek ConfigValue dalam objek Configuration.

Mengimplementasikan 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 FullTraversalConnector, ganti metode berikut:

• Metode init(). Untuk melakukan penyiapan dan inisialisasi repositori data, ganti metode init().

• Metode getAllDocs(). Untuk menelusuri dan mengindeks semua item dalam repositori data, ganti metode getAllDocs(). Metode ini dipanggil satu kali untuk setiap traversal terjadwal (sebagaimana ditentukan oleh konfigurasi Anda).

• (opsional) Metode getChanges(). Jika repositori Anda mendukung deteksi perubahan, ganti metode getChanges(). Metode ini dipanggil satu kali untuk setiap traversal inkremental terjadwal (sebagaimana ditentukan oleh konfigurasi Anda) untuk mengambil item yang dimodifikasi dan mengindeksnya.

• (opsional) Metode close(). Jika Anda perlu melakukan pembersihan repositori, ganti metode close(). Metode ini dipanggil sekali selama penutupan konektor.

Setiap metode objek Repository menampilkan beberapa jenis objek ApiOperation. Objek ApiOperation melakukan tindakan dalam bentuk panggilan IndexingService.indexItem() tunggal, atau beberapa panggilan, untuk melakukan pengindeksan yang sebenarnya dari repositori Anda.

Mendapatkan parameter konfigurasi khusus

Sebagai bagian dari penanganan konfigurasi konektor, Anda harus mendapatkan parameter khusus dari objek Configuration. Tugas ini biasanya dilakukan dalam metode init() class Repository.

Class Configuration memiliki beberapa metode untuk mendapatkan berbagai jenis data dari konfigurasi. Setiap metode menampilkan objek ConfigValue. Kemudian, Anda akan menggunakan metode get() objek ConfigValue untuk mengambil nilai yang sebenarnya. Cuplikan berikut, dari FullTraversalSample, menunjukkan cara mengambil satu nilai bilangan bulat kustom dari objek Configuration:

FullTraversalSample.java

Lihat di GitHub

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Untuk mendapatkan dan menguraikan parameter yang berisi beberapa nilai, gunakan salah satu jenis parser class Configuration untuk mengurai data menjadi potongan terpisah. Cuplikan berikut, dari konektor tutorial, menggunakan metode getMultiValue untuk mendapatkan daftar nama repositori GitHub:

GithubRepository.java

Lihat di GitHub

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Melakukan traversal penuh

Ganti getAllDocs() untuk melakukan traversal penuh dan mengindeks repositori Anda. Metode getAllDocs() menerima checkpoint. Checkpoint digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu. Untuk setiap item di repositori Anda, lakukan langkah-langkah ini dalam metode getAllDocs():

1. Tetapkan izin.
2. Tetapkan metadata untuk item yang Anda indeks.
3. Gabungkan metadata dan item ke dalam satu RepositoryDoc yang dapat diindeks.
4. Gabungkan setiap item yang dapat diindeks ke dalam iterator yang ditampilkan oleh metode getAllDocs(). Perhatikan bahwa getAllDocs() sebenarnya menampilkan CheckpointCloseableIterable yang merupakan iterasi dari objek ApiOperation, setiap objek mewakili permintaan API yang dilakukan pada RepositoryDoc, seperti mengindeksnya.

Jika kumpulan item terlalu besar untuk diproses dalam satu panggilan, sertakan checkpoint dan tetapkan hasMore(true) untuk 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 untuk memastikan hanya pengguna yang memiliki akses ke item yang dapat melihat item tersebut dalam hasil penelusuran. 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 class Acl.Builder untuk menetapkan akses ke setiap item menggunakan ACL. Cuplikan kode berikut, yang diambil dari contoh traversal lengkap, memungkinkan semua pengguna atau “prinsipal” (getCustomerPrincipal()) menjadi “pembaca” semua item (.setReaders()) saat melakukan penelusuran.

FullTraversalSample.java

Lihat di GitHub

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Anda perlu memahami ACL untuk membuat model ACL dengan benar untuk 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 minimal ID string unik, jenis item, ACL, URL, dan versi untuk item tersebut. Cuplikan kode berikut menunjukkan cara mem-build Item menggunakan class bantuan IndexingItemBuilder.

FullTraversalSample.java

Lihat di GitHub

// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Membuat item yang dapat diindeks

Setelah Anda menetapkan metadata untuk item, Anda dapat membuat item sebenarnya yang dapat diindeks menggunakan class RepositoryDoc.Builder. Contoh berikut menunjukkan cara membuat item tunggal yang dapat diindeks.

FullTraversalSample.java

Lihat di GitHub

// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc adalah jenis ApiOperation yang melakukan permintaan IndexingService.indexItem() yang sebenarnya.

Anda juga dapat menggunakan metode setRequestMode() dari class 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 besar untuk permintaan pengindeksan. Mode asinkron 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 ke SYNCHRONOUS secara default.

Gabungkan setiap item yang dapat diindeks dalam iterator

Metode getAllDocs() akan menampilkan Iterator, khususnya CheckpointCloseableIterable, dari objek RepositoryDoc. Anda dapat menggunakan class CheckpointClosableIterableImpl.Builder untuk membuat dan menampilkan iterator. Cuplikan kode berikut ini menunjukkan cara membuat dan menampilkan iterator.

FullTraversalSample.java

Lihat di GitHub

CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

SDK menjalankan setiap panggilan pengindeksan yang terkurung dalam iterator.

Catatan: Cloud Search mengindeks metadata untuk semua file. Bergantung pada jenis file suatu item, Cloud Search juga mengindeks konten teks, termasuk menggunakan Pengenalan Karakter Optik (OCR) pada gambar dan file lainnya. Untuk daftar jenis file yang mendukung ekstraksi teks, lihat Jenis file yang didukung untuk ekstraksi teks.

Langkah Berikutnya

Berikut beberapa langkah yang dapat Anda ambil:

• (opsional) Jika throughput pengindeksan Anda tampak lambat, lihat Meningkatkan rasio pengindeksan untuk FullTraversalConnector.
• (opsional) Terapkan metode close() untuk merilis resource apa pun sebelum penghentian.
• (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 Cloud Search Indexing Queue, 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 class Application dan memanggil metode start() untuk menjalankan konektor.

Sebelum memanggil application.start(), gunakan class IndexingApplication.Builder untuk membuat instance template ListingConnector. ListingConnector menerima objek Repository yang metodenya Anda terapkan. Cuplikan berikut menunjukkan cara membuat instance ListingConnector dan Repository terkait:

ListTraversalSample.java

Lihat di GitHub

/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Di balik layar, SDK memanggil metode initConfig() setelah metode main() konektor Anda memanggil Application.build. Metode initConfig():

1. Memanggil metode Configuation.isInitialized() untuk memastikan bahwa Configuration belum diinisialisasi.
2. Menginisialisasi objek Configuration dengan key-value pair yang disediakan Google. Setiap key-value pair disimpan dalam objek ConfigValue dalam objek Configuration.

Mengimplementasikan 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, ganti metode berikut:

• Metode init(). Untuk melakukan penyiapan dan inisialisasi repositori data, ganti metode init().

• Metode getIds(). Untuk mengambil ID dan nilai hash untuk semua catatan dalam repositori, ganti metode getIds().

• Metode getDoc(). Untuk menambahkan, mengupdate, memodifikasi, atau menghapus item baru dari indeks, ganti metode getDoc().

• (opsional) Metode getChanges(). Jika repositori Anda mendukung deteksi perubahan, ganti metode getChanges(). Metode ini dipanggil satu kali untuk setiap traversal inkremental terjadwal (sebagaimana ditentukan oleh konfigurasi Anda) untuk mengambil item yang dimodifikasi dan mengindeksnya.

• (opsional) Metode close(). Jika Anda perlu melakukan pembersihan repositori, ganti metode close(). Metode ini dipanggil sekali selama penutupan konektor.

Setiap metode objek Repository menampilkan beberapa jenis objek ApiOperation. Objek ApiOperation melakukan tindakan dalam bentuk panggilan IndexingService.indexItem() tunggal, atau beberapa panggilan, untuk melakukan pengindeksan yang sebenarnya dari repositori Anda.

Mendapatkan parameter konfigurasi khusus

Sebagai bagian dari penanganan konfigurasi konektor, Anda harus mendapatkan parameter khusus dari objek Configuration. Tugas ini biasanya dilakukan dalam metode init() class Repository.

Class Configuration memiliki beberapa metode untuk mendapatkan berbagai jenis data dari konfigurasi. Setiap metode menampilkan objek ConfigValue. Kemudian, Anda akan menggunakan metode get() objek ConfigValue untuk mengambil nilai yang sebenarnya. Cuplikan berikut, dari FullTraversalSample, menunjukkan cara mengambil satu nilai bilangan bulat kustom dari objek Configuration:

FullTraversalSample.java

Lihat di GitHub

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Untuk mendapatkan dan menguraikan parameter yang berisi beberapa nilai, gunakan salah satu jenis parser class Configuration untuk mengurai data menjadi potongan terpisah. Cuplikan berikut, dari konektor tutorial, menggunakan metode getMultiValue untuk mendapatkan daftar nama repositori GitHub:

GithubRepository.java

Lihat di GitHub

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Melakukan traversal daftar

Ganti metode getIds() untuk mengambil ID dan nilai hash untuk semua catatan dalam repositori. Metode getIds() menerima checkpoint. Checkpoint digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu.

Selanjutnya, ganti metode getDoc() untuk menangani setiap item dalam Cloud Search Indexing Queue.

Mendorong ID item dan nilai hash

Ganti getIds() untuk mengambil ID item dan nilai hash konten terkait dari repositori. 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 diindeks. Checkpoint dapat digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu. Untuk setiap item dalam repositori Anda, lakukan langkah-langkah ini dalam metode getIds():

• Dapatkan setiap ID item dan nilai hash terkait dari repositori.
• Gabungkan setiap ID dan pasangan nilai hash ke dalam PushItems.
• Gabungkan setiap PushItems ke dalam iterator yang ditampilkan oleh metode getIds(). Perhatikan bahwa getIds() sebenarnya menampilkan CheckpointCloseableIterable yang merupakan iterasi dari objek ApiOperation, setiap objek mewakili permintaan API yang dilakukan pada RepositoryDoc, seperti mendorong item ke antrean.

Cuplikan kode berikut menunjukkan cara mendapatkan setiap ID item dan nilai hash dan menyisipkannya ke dalam PushItems. PushItems adalah permintaan ApiOperation untuk mendorong item ke Cloud Search Indexing Queue.

ListTraversalSample.java

Lihat di GitHub

PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

Cuplikan kode berikut menunjukkan cara menggunakan class PushItems.Builder untuk memaketkan ID dan nilai hash ke dalam satu push ApiOperation.

ListTraversalSample.java

Lihat di GitHub

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;

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 Indexing Queue. Untuk setiap item dalam antrean, lakukan langkah-langkah ini dalam metode getDoc():

1. Periksa apakah ID item dalam Google Cloud Search Indexing Queue ada di repositori. Jika tidak, hapus item dari indeks.

2. Lakukan polling indeks untuk status item dan jika suatu item tidak berubah (ACCEPTED), jangan lakukan apa pun.

3. Indeks yang berubah atau item baru:

   1. Tetapkan izin.
   2. Tetapkan metadata untuk item yang Anda indeks.
   3. Gabungkan metadata dan item ke dalam satu RepositoryDoc yang dapat diindeks.
   4. Tampilkan RepositoryDoc.

Catatan: Template ListingConnector tidak mendukung ditampilkannya null pada metode getDoc(). Menampilkan hasil null dalam NullPointerException.

Menangani item yang dihapus

Cuplikan kode berikut ini menunjukkan cara menentukan apakah suatu item ada di repositori dan, jika tidak, menghapus item tersebut.

ListTraversalSample.java

Lihat di GitHub

String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}

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.

ListTraversalSample.java

Lihat di GitHub

String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

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.

ListTraversalSample.java

Lihat di GitHub

/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}

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 untuk memastikan hanya pengguna yang memiliki akses ke item yang dapat melihat item tersebut dalam hasil penelusuran. 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 class Acl.Builder untuk menetapkan akses ke setiap item menggunakan ACL. Cuplikan kode berikut, yang diambil dari contoh traversal lengkap, memungkinkan semua pengguna atau “prinsipal” (getCustomerPrincipal()) menjadi “pembaca” semua item (.setReaders()) saat melakukan penelusuran.

FullTraversalSample.java

Lihat di GitHub

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Anda perlu memahami ACL untuk membuat model ACL dengan benar untuk 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 minimal ID string unik, jenis item, ACL, URL, dan versi untuk item tersebut. Cuplikan kode berikut menunjukkan cara mem-build Item menggunakan class bantuan IndexingItemBuilder.

ListTraversalSample.java

Lihat di GitHub

// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();

Membuat item yang dapat diindeks

Setelah Anda menetapkan metadata untuk item, Anda dapat membuat item sebenarnya yang dapat diindeks menggunakan RepositoryDoc.Builder. Contoh berikut menunjukkan cara membuat item tunggal yang dapat diindeks.

ListTraversalSample.java

Lihat di GitHub

// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc adalah jenis ApiOperation yang melakukan permintaan IndexingService.indexItem() yang sebenarnya.

Anda juga dapat menggunakan metode setRequestMode() dari class 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 besar untuk permintaan pengindeksan. Mode asinkron 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 ke SYNCHRONOUS secara default.

Catatan: Cloud Search mengindeks metadata untuk semua file. Bergantung pada jenis file suatu item, Cloud Search juga mengindeks konten teks, termasuk menggunakan Pengenalan Karakter Optik (OCR) pada konten tulisan tangan. Untuk daftar jenis file yang mendukung ekstraksi teks, lihat Jenis file yang didukung untuk ekstraksi teks.

Langkah Berikutnya

Berikut beberapa langkah yang dapat Anda ambil:

• (opsional) Terapkan metode close() untuk merilis resource apa pun sebelum penghentian.
• (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 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 Cloud Search Indexing Queue, lihat 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 class Application dan memanggil metode start() untuk menjalankan konektor.

Sebelum memanggil application.start(), gunakan class IndexingApplication.Builder untuk membuat instance template ListingConnector. ListingConnector menerima objek Repository yang metodenya Anda terapkan.

Catatan: Strategi traversal grafik menggunakan class template yang sama, ListingConnector, seperti strategi traversal daftar.

Cuplikan berikut menunjukkan cara membuat instance ListingConnector dan Repository terkait:

GraphTraversalSample.java

Lihat di GitHub

/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Di balik layar, SDK memanggil metode initConfig() setelah metode main() konektor Anda memanggil Application.build. Metode initConfig():

1. Memanggil metode Configuation.isInitialized() untuk memastikan bahwa Configuration belum diinisialisasi.
2. Menginisialisasi objek Configuration dengan key-value pair yang disediakan Google. Setiap key-value pair disimpan dalam objek ConfigValue dalam objek Configuration.

Mengimplementasikan 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, Anda mengganti metode berikut:

• Metode init(). Untuk melakukan penyiapan dan inisialisasi repositori data, ganti metode init().

• Metode getIds(). Untuk mengambil ID dan nilai hash untuk semua catatan dalam repositori, ganti metode getIds().

• Metode getDoc(). Untuk menambahkan, mengupdate, memodifikasi, atau menghapus item baru dari indeks, ganti metode getDoc().

• (opsional) Metode getChanges(). Jika repositori Anda mendukung deteksi perubahan, ganti metode getChanges(). Metode ini dipanggil satu kali untuk setiap traversal inkremental terjadwal (sebagaimana ditentukan oleh konfigurasi Anda) untuk mengambil item yang dimodifikasi dan mengindeksnya.

• (opsional) Metode close(). Jika Anda perlu melakukan pembersihan repositori, ganti metode close(). Metode ini dipanggil sekali selama penutupan konektor.

Setiap metode objek Repository menampilkan beberapa jenis objek ApiOperation. Objek ApiOperation melakukan tindakan dalam bentuk panggilan IndexingService.indexItem() tunggal, atau beberapa panggilan, untuk melakukan pengindeksan yang sebenarnya dari repositori Anda.

Mendapatkan parameter konfigurasi khusus

Sebagai bagian dari penanganan konfigurasi konektor, Anda harus mendapatkan parameter khusus dari objek Configuration. Tugas ini biasanya dilakukan dalam metode init() class Repository.

Class Configuration memiliki beberapa metode untuk mendapatkan berbagai jenis data dari konfigurasi. Setiap metode menampilkan objek ConfigValue. Kemudian, Anda akan menggunakan metode get() objek ConfigValue untuk mengambil nilai yang sebenarnya. Cuplikan berikut, dari FullTraversalSample, menunjukkan cara mengambil satu nilai bilangan bulat kustom dari objek Configuration:

FullTraversalSample.java

Lihat di GitHub

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Untuk mendapatkan dan menguraikan parameter yang berisi beberapa nilai, gunakan salah satu jenis parser class Configuration untuk mengurai data menjadi potongan terpisah. Cuplikan berikut, dari konektor tutorial, menggunakan metode getMultiValue untuk mendapatkan daftar nama repositori GitHub:

GithubRepository.java

Lihat di GitHub

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Melakukan traversal grafik

Ganti metode getIds() untuk mengambil ID dan nilai hash untuk semua catatan dalam repositori. Metode getIds() menerima checkpoint. Checkpoint digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu.

Selanjutnya, ganti metode getDoc() untuk menangani setiap item dalam Cloud Search Indexing Queue.

Mendorong ID item dan nilai hash

Ganti getIds() untuk mengambil ID item dan nilai hash konten terkait dari repositori. 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 diindeks. Checkpoint dapat digunakan untuk melanjutkan pengindeksan pada item tertentu jika prosesnya terganggu. Untuk setiap item dalam repositori Anda, lakukan langkah-langkah ini dalam metode getIds():

• Dapatkan setiap ID item dan nilai hash terkait dari repositori.
• Gabungkan setiap ID dan pasangan nilai hash ke dalam PushItems.
• Gabungkan setiap PushItems ke dalam iterator yang ditampilkan oleh metode getIds(). Perhatikan bahwa getIds() sebenarnya menampilkan CheckpointCloseableIterable yang merupakan iterasi dari objek ApiOperation, setiap objek mewakili permintaan API yang dilakukan pada RepositoryDoc, seperti mendorong item ke antrean.

Cuplikan kode berikut menunjukkan cara mendapatkan setiap ID item dan nilai hash dan menyisipkannya ke dalam PushItems. PushItems adalah permintaan ApiOperation untuk mendorong item ke Cloud Search Indexing Queue.

GraphTraversalSample.java

Lihat di GitHub

PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);

Cuplikan kode berikut menunjukkan cara menggunakan class PushItems.Builder untuk memaketkan ID dan nilai hash ke dalam satu push ApiOperation.

GraphTraversalSample.java

Lihat di GitHub

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();

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 Cloud Search Indexing Queue. Untuk setiap item dalam antrean, lakukan langkah-langkah ini dalam metode getDoc():

1. 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.

2. Indeks yang berubah atau item baru:

   1. Tetapkan izin.
   2. Tetapkan metadata untuk item yang Anda indeks.
   3. Gabungkan metadata dan item ke dalam satu RepositoryDoc yang dapat diindeks.
   4. Tempatkan ID turunan dalam Cloud Search Indexing Queue untuk diproses lebih lanjut.
   5. 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.

GraphTraversalSample.java

Lihat di GitHub

String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);

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 untuk memastikan hanya pengguna yang memiliki akses ke item yang dapat melihat item tersebut dalam hasil penelusuran. 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 class Acl.Builder untuk menetapkan akses ke setiap item menggunakan ACL. Cuplikan kode berikut, yang diambil dari contoh traversal lengkap, memungkinkan semua pengguna atau “prinsipal” (getCustomerPrincipal()) menjadi “pembaca” semua item (.setReaders()) saat melakukan penelusuran.

FullTraversalSample.java

Lihat di GitHub

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Anda perlu memahami ACL untuk membuat model ACL dengan benar untuk 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 minimal ID string unik, jenis item, ACL, URL, dan versi untuk item tersebut. Cuplikan kode berikut menunjukkan cara mem-build Item menggunakan class bantuan IndexingItemBuilder.

GraphTraversalSample.java

Lihat di GitHub

// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Membuat item yang dapat diindeks

Setelah Anda menetapkan metadata untuk item, Anda dapat membuat item sebenarnya yang dapat diindeks menggunakan RepositoryDoc.Builder. Contoh berikut menunjukkan cara membuat item tunggal yang dapat diindeks.

GraphTraversalSample.java

Lihat di GitHub

// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);

RepositoryDoc adalah jenis ApiOperation yang menjalankan permintaan IndexingService.indexItem() yang sebenarnya.

Anda juga dapat menggunakan metode setRequestMode() dari class 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 besar untuk permintaan pengindeksan. Mode asinkron 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 ke SYNCHRONOUS secara default.

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.

GraphTraversalSample.java

Lihat di GitHub

// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

Catatan: Cloud Search mengindeks metadata untuk semua file. Bergantung pada jenis file suatu item, Cloud Search juga mengindeks konten teks, termasuk menggunakan Pengenalan Karakter Optik (OCR) pada konten tulisan tangan. Untuk daftar jenis file yang mendukung ekstraksi teks, lihat Jenis file yang didukung untuk ekstraksi teks.

Langkah Berikutnya

Berikut beberapa langkah yang dapat Anda ambil:

• (opsional) Terapkan metode close() untuk merilis resource apa pun sebelum penghentian.
• (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.

Catatan: Istilah "item" dan "dokumen" sama dalam dokumen dan kode sampel ini.

Menerapkan strategi traversal Anda dan item indeks

Setiap elemen yang dapat diindeks untuk Cloud Search disebut sebagai item dalam Cloud Search API. Item mungkin berupa file, folder, baris dalam file CSV, atau catatan database.

Setelah skema Anda terdaftar, Anda dapat mengisi indeks dengan:

1. (opsional) Menggunakan items.upload untuk mengupload file yang lebih besar dari 100 KiB untuk pengindeksan. Untuk file yang lebih kecil, sematkan konten sebagai inlineContent menggunakan items.index.

2. (opsional) Menggunakan media.upload untuk mengupload file media untuk pengindeksan.

3. Menggunakan items.index untuk mengindeks item. Misalnya, jika skema Anda menggunakan definisi objek dalam skema film, 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"
   }
   

4. (Opsional) Menggunakan panggilan items.get untuk memverifikasi bahwa item telah diindeks.

Untuk melakukan traversal penuh, Anda akan mengindeks ulang seluruh repositori secara berkala. Untuk melakukan traversal grafik atau daftar, Anda perlu menerapkan kode untuk menangani perubahan repositori.

Catatan: Kolom objectType di ItemMetadata harus cocok dengan nama definisi objek dalam skema. Dengan cara ini, Cloud Search mengidentifikasi struktur objek yang diharapkan dalam permintaan indeks. Jika, dalam permintaan pengindeksan, Anda mengirim data terstruktur yang berisi properti yang tidak terdaftar dengan skema saat ini, atau Anda memberikan jenis objek yang tidak sesuai dengan nama salah satu definisi objek dalam skema, objek atau properti akan diabaikan. Selain itu, jika Anda mengirim properti dengan jenis yang berbeda dari jenis yang terdaftar dalam skema, Cloud Search akan menampilkan respons error pada waktu pengindeksan.

Catatan: Setiap koneksi HTTP yang dibuat klien Anda akan menghasilkan overhead. Untuk mengurangi overhead, Anda dapat mengelompokkan beberapa panggilan API menjadi satu permintaan HTTP tunggal. Untuk mempelajari cara mengurangi overhead koneksi HTTP Anda, lihat Meminta batching. Untuk mempelajari cara menangani upload media besar, lihat Upload Media Langsung dan yang Dapat Dilanjutkan.

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 permintaan items.push untuk mendorong item ke antrean untuk polling dan update berikutnya. Untuk informasi lebih lanjut tentang Google Cloud Indexing Queue, lihat Google Cloud Indexing Queue.

Untuk informasi lebih lanjut tentang Google Cloud Search API, lihat Cloud Search API.