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 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:

  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 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 dan api.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 mendeklarasikan api.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

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():

FullTraversalSample.java
/**
 * 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 initConfig() setelah metode main() konektor Anda memanggil Application.build. Tujuan initConfig() metode melakukan tugas berikut:

  1. Memanggil Configuation.isInitialized() untuk memastikan bahwa Configuration belum diinisialisasi.
  2. Melakukan inisialisasi objek Configuration dengan nilai kunci yang disediakan Google pasangan. Setiap pasangan nilai kunci disimpan dalam ConfigValue dalam objek Configuration.

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 Metode init().

  • Tujuan 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) 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) close() . Jika Anda perlu melakukan pembersihan repositori, ganti close() . 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:

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

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:

GithubRepository.java
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. 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():

  1. Tetapkan izin.
  2. Tetapkan metadata untuk item yang Anda indeks.
  3. Menggabungkan metadata dan item ke dalam satu file yang dapat diindeks RepositoryDoc
  4. Gabungkan setiap item yang dapat diindeks ke dalam iterator yang ditampilkan oleh getAllDocs() . Perhatikan bahwa getAllDocs() sebenarnya menampilkan CheckpointCloseableIterable yang merupakan iterasi dari ApiOperation masing-masing objek yang mewakili permintaan API yang dijalankan pada RepositoryDoc, 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.

FullTraversalSample.java
// 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 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 .

FullTraversalSample.java
// 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 menggunakan RepositoryDoc.Builder . Contoh berikut menunjukkan cara membuat item tunggal yang dapat diindeks.

FullTraversalSample.java
// 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 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.

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

SDK menjalankan setiap panggilan pengindeksan yang terkurung dalam iterator.

Langkah Berikutnya

Berikut beberapa langkah yang dapat Anda ambil:

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:

ListTraversalSample.java
/**
 * 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 initConfig() setelah metode main() konektor Anda memanggil Application.build. Metode initConfig():

  1. Memanggil Configuation.isInitialized() untuk memastikan bahwa Configuration belum diinisialisasi.
  2. Melakukan inisialisasi objek Configuration dengan nilai kunci yang disediakan Google pasangan. Setiap pasangan nilai kunci disimpan dalam ConfigValue dalam objek Configuration.

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 Metode init().

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

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

  • (opsional) 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) close() . Jika Anda perlu melakukan pembersihan repositori, ganti close() . 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:

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

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:

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

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 oleh getIds() . Perhatikan bahwa getIds() sebenarnya menampilkan CheckpointCloseableIterable yang merupakan iterasi dari ApiOperation setiap objek yang mewakili permintaan API yang dijalankan pada RepositoryDoc , 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.

ListTraversalSample.java
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 PushItems.Builder untuk memaketkan ID dan nilai hash ke dalam satu push ApiOperation.

ListTraversalSample.java
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 Antrean Pengindeksan. Untuk setiap item dalam antrean, lakukan langkah-langkah ini di 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. Menggabungkan metadata dan item ke dalam satu file yang dapat diindeks RepositoryDoc
    4. 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.

ListTraversalSample.java
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
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
/**
 * 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 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.

FullTraversalSample.java
// 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 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 .

ListTraversalSample.java
// 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 menggunakan RepositoryDoc.Builder Contoh berikut menunjukkan cara membuat item tunggal yang dapat diindeks.

ListTraversalSample.java
// 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 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:

GraphTraversalSample.java
/**
 * 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 initConfig() setelah metode main() konektor Anda memanggil Application.build. Metode initConfig():

  1. Memanggil Configuation.isInitialized() untuk memastikan bahwa Configuration belum diinisialisasi.
  2. Melakukan inisialisasi objek Configuration dengan nilai kunci yang disediakan Google pasangan. Setiap pasangan nilai kunci disimpan dalam ConfigValue dalam objek Configuration.

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 Metode init().

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

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

  • (opsional) 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) close() . Jika Anda perlu melakukan pembersihan repositori, ganti close() . 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:

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

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:

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

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 Metode getIds(). Perhatikan bahwa getIds() sebenarnya menampilkan CheckpointCloseableIterable yang merupakan iterasi dari ApiOperation setiap objek yang mewakili permintaan API yang dijalankan pada RepositoryDoc , 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.

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

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

GraphTraversalSample.java
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 Pengindeksan Cloud Search Antrean. Untuk setiap item dalam antrean, lakukan langkah-langkah ini di 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. Menggabungkan metadata dan item ke dalam satu file yang dapat diindeks RepositoryDoc
    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
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 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.

FullTraversalSample.java
// 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 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 .

GraphTraversalSample.java
// 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 menggunakan RepositoryDoc.Builder Contoh berikut menunjukkan cara membuat item tunggal yang dapat diindeks.

GraphTraversalSample.java
// 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 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.

GraphTraversalSample.java
// 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();

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:

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

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

  3. 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"
    }
    
  4. (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.