Membuat antarmuka penelusuran dengan Query API

Query API memberikan fungsi penelusuran dan menyarankan metode untuk membuat antarmuka penelusuran atau menyematkan hasil dalam aplikasi.

Untuk aplikasi web dengan persyaratan minimum, pertimbangkanlah untuk menggunakan widget penelusuran. Lihat Membuat antarmuka penelusuran dengan widget penelusuran.

Membuat antarmuka penelusuran

Berikut langkah-langkah untuk membuat antarmuka penelusuran yang sederhana:

1. Mengonfigurasi aplikasi penelusuran.
2. Membuat kredensial OAuth untuk aplikasi.
3. Membuat kueri indeks.
4. Menampilkan hasil kueri.

Anda dapat meningkatkan kualitas antarmuka dengan fitur seperti paging, pengurutan, pemfilteran, faset, dan pelengkapan otomatis.

Mengonfigurasi aplikasi penelusuran

Anda harus membuat setidaknya satu aplikasi penelusuran untuk setiap antarmuka penelusuran. Aplikasi penelusuran memberikan parameter default, seperti sumber data, urutan pengurutan, filter, dan faset. Anda dapat mengganti parameter ini menggunakan Query API.

Anda tidak dapat meningkatkan jumlah sumber data yang digunakan dalam kueri lebih dari yang sudah dikonfigurasi dalam aplikasi penelusuran. Anda dapat membatasi kueri ke subset sumber ini menggunakan dataSourceRestrictions.

Catatan: Cloud Search memperbarui aplikasi penelusuran saat Anda memperbarui atau menghapus skema. Misalnya, mengubah nama operator skema juga akan mengubah namanya dalam aplikasi penelusuran. Jika pembaruan tidak kompatibel, pembaruan skema akan gagal.

Untuk mengetahui informasi selengkapnya, lihat Menyesuaikan pengalaman penelusuran.

Membuat kredensial OAuth untuk aplikasi

Selain langkah-langkah dalam Mengonfigurasi akses ke Cloud Search API, Anda harus membuat kredensial OAuth untuk aplikasi web.

Gunakan kredensial untuk meminta otorisasi atas nama pengguna. Gunakan cakupan https://www.googleapis.com/auth/cloud_search.query.

Untuk mengetahui informasi selengkapnya tentang opsi OAuth, lihat Platform Google Identity.

Membuat kueri indeks

Gunakan search metode untuk menelusuri indeks.

Setiap permintaan harus menyertakan query teks dan searchApplicationId.

Contoh ini membuat kueri sumber data film:

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  }
}

Menampilkan hasil kueri

Antarmuka penelusuran harus menampilkan title item dan link ke item asli. Anda juga dapat menggunakan cuplikan dan metadata untuk meningkatkan kualitas tampilan.

Catatan: Jika Anda tidak melihat hasil, pastikan Anda telah membuat aplikasi penelusuran kustom dan mengaktifkan sumber data untuk aplikasi tersebut.

Menangani hasil tambahan

Cloud Search menampilkan hasil tambahan jika tidak ada kecocokan yang cukup untuk kueri. Kolom queryInterpretation menunjukkan hal ini. Jika hanya hasil tambahan yang ditampilkan, InterpretationType adalah REPLACE. Jika digabungkan, hasilnya adalah BLEND.

Saat menampilkan hasil tambahan, pertimbangkan untuk memberi tahu pengguna. Untuk REPLACE, Anda dapat mengatakan: "Penelusuran Anda tidak cocok dengan hasil apa pun. Menampilkan hasil untuk kueri serupa".

Menangani hasil penelusuran orang

Cloud Search menampilkan dokumen yang terkait dengan informasi orang dan karyawan menggunakan fitur Penelusuran Orang. Hasilnya ada di structuredResults kolom:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

Catatan: Jika Anda menentukan lebih dari 20 atribut kustom, Penelusuran Orang hanya akan menggunakan 20 atribut.

Pencocokan Bawahan Langsung

Pencocokan Bawahan Langsung memungkinkan pengguna melihat bawahan langsung seseorang. Respons mencakup assistCardProtoHolder dengan cardType RELATED_PEOPLE_ANSWER_CARD.

Menonaktifkan pengoptimalan

Pengoptimalan seperti hasil tambahan diaktifkan secara default. Anda dapat menonaktifkannya:

• Tingkat aplikasi penelusuran: Tetapkan force_verbatim_mode ke true.
• Tingkat kueri: Tetapkan enableVerbatimMode ke true.

Menyoroti cuplikan

Cloud Search menampilkan cuplikan untuk teks atau HTML yang diindeks. Jika ada istilah kueri, matchRanges akan mengidentifikasi lokasinya. Gunakan rentang ini untuk menyoroti teks.

function highlightSnippet(snippet) {
  let text = snippet.snippet;
  let formattedText = text;
  if (snippet.matchRanges) {
    let parts = [];
    let index = 0;
    for (let match of snippet.matchRanges) {
      let start = match.start || 0; // Default to 0 if omitted
      let end = match.end;
      if (index < start) { // Include any leading text before/between ranges
        parts.push(text.slice(index, start));
      }
      parts.push('<span class="highlight">');
      parts.push(text.slice(start, end));
      parts.push('</span>');
      index = end;
    }
    parts.push(text.slice(index)); // Include any trailing text after last range
    formattedText = parts.join('');
  }
  return formattedText;
}

Jika cuplikannya adalah berikut ini:

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

String HTML yang dihasilkan adalah:

This is an <span class="highlight">example</span> snippet...

Menampilkan metadata

Gunakan metadata kolom untuk informasi seperti createTime, updateTime, dan data terstruktur. Gunakan displayOptions untuk menampilkan data terstruktur.

Mengambil hasil tambahan

Untuk mengambil hasil lainnya, tetapkan kolom start ke offset yang dipilih. Sesuaikan ukuran halaman dengan pageSize. Gunakan resultCount untuk menampilkan total item atau perkiraan jumlah.

Mengurutkan hasil

Gunakan sortOptions untuk menentukan urutan:

• operatorName: properti yang akan diurutkan.
• sortOrder: ASCENDING atau DESCENDING.

Relevansi adalah kunci pengurutan default dan sekunder.

Menambahkan filter

Batasi hasil dengan filter di aplikasi atau permintaan penelusuran. Jika keduanya menentukan filter untuk sumber, keduanya harus dievaluasi ke true.

Terapkan filter di dataSourceRestrictions.filterOptions[]. Jenis filter utama:

• Filter objek: membatasi kecocokan ke jenis tertentu.
• Filter nilai: membatasi kecocokan berdasarkan operator dan nilai.

Filter komposit menggabungkan beberapa filter nilai.

Menyaring hasil dengan faset

Faset membantu pengguna menyaring kueri secara interaktif. Saat Anda meminta faset, Cloud Search menghitung nilai yang paling sering digunakan untuk properti tersebut.

Pola umum: 1. Kueri yang menentukan properti faset. 1. Melakukan render hasil penelusuran dan faset. 1. Pengguna memilih nilai faset. 1. Mengulangi kueri dengan filter berdasarkan pilihan.

Catatan: Hanya properti data terstruktur yang mendukung faset.

Hasil faset dengan kolom berbasis bilangan bulat

Tandai properti bilangan bulat sebagai dapat difasetkan untuk menyaring hasil berdasarkan rentang (misalnya, halaman "100-200"). Tetapkan isFacetable ke true dan tentukan opsi pengelompokan default dalam skema.

Hasil faset berdasarkan ukuran atau tanggal dokumen

Gunakan operator yang dicadangkan:

• itemsize: untuk ukuran file dalam byte.
• createddatetimestamp: untuk tanggal pembuatan.
• lastmodified: untuk tanggal modifikasi.

Menambahkan saran

Gunakan API saran untuk pelengkapan otomatis berdasarkan histori kueri, kontak, dan konten dokumen.