Query API memberikan fungsi penelusuran dan menyarankan metode untuk membuat antarmuka penelusuran atau menyematkan hasil penelusuran dalam aplikasi.
Untuk aplikasi web dengan persyaratan minimum, pertimbangkanlah untuk menggunakan widget penelusuran. Untuk informasi lebih lanjut, lihat Membuat antarmuka penelusuran dengan widget penelusuran
Membuat antarmuka penelusuran
Berikut langkah-langkah untuk membuat antarmuka penelusuran yang sederhana:
- Konfigurasikan aplikasi penelusuran
- Buat kredensial OAuth untuk aplikasi
- Buat kueri indeks
- Tampilkan hasil kueri
Anda dapat menyempurnakan antarmuka penelusuran dengan berbagai fitur, seperti paging, pengurutan, pemfilteran, faset, dan saran otomatis.
Mengonfigurasi aplikasi penelusuran
Anda harus membuat setidaknya satu aplikasi penelusuran untuk dikaitkan dengan setiap antarmuka penelusuran yang dibuat. Aplikasi penelusuran memberikan parameter default untuk kueri, seperti sumber data yang akan dimasukkan, tata urutan, filter, dan faset yang diminta. Jika perlu, Anda dapat mengganti parameter ini menggunakan Query API.
Untuk informasi lebih lanjut tentang aplikasi penelusuran, lihat Membuat pengalaman penelusuran khusus.
Membuat kredensial OAuth untuk aplikasi
Selain langkah-langkah dalam Mengonfigurasi akses ke REST API Google Cloud Search, Anda juga harus membuat kredensial OAuth untuk aplikasi web. Jenis kredensial yang dibuat bergantung pada konteks tempat penggunaan API.
Gunakan kredensial untuk meminta otorisasi atas nama pengguna. Gunakan cakupan https://www.googleapis.com/auth/cloud_search.query saat meminta otorisasi.
Untuk informasi tambahan tentang opsi OAuth dan library klien, lihat Platform Google Identity
Membuat kueri indeks
Gunakan metode search untuk menelusuri indeks.
Setiap permintaan harus menyertakan dua informasi: query teks untuk mencocokkan item dan searchApplicationId yang mengidentifikasi ID aplikasi penelusuran yang akan digunakan.
Cuplikan berikut menampilkan kueri ke sumber data film untuk film Titanic:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
Menampilkan hasil kueri
Pada tingkat minimum, antarmuka penelusuran setidaknya harus menampilkan title item serta link ke item asli. Anda dapat menyempurnakan tampilan hasil penelusuran dengan memanfaatkan informasi tambahan yang ada dalam hasil penelusuran, seperti cuplikan dan metadata.
Menyoroti cuplikan
Untuk item yang ditampilkan berisi teks terindeks atau konten HTML, cuplikan dari konten akan ditampilkan. Konten ini membantu pengguna menentukan relevansi item yang ditampilkan.
Jika istilah kueri ada dalam cuplikan, satu atau beberapa rentang kecocokan yang mengidentifikasi lokasi istilah juga akan ditampilkan.
Gunakan matchRanges untuk menyoroti teks yang cocok saat proses rendering
hasil. Contoh javascript berikut mengonversi cuplikan potongan menjadi markup HTML dengan setiap rentang yang cocok digabungkan dengan tag <span>.
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 kolom metadata untuk menampilkan informasi tambahan tentang item yang ditampilkan, yang mungkin relevan dengan pengguna. Kolom metadata mencakup createTime dan updateTime item serta data terstruktur yang dapat ditampilkan, yang terkait dengan item.
Untuk menampilkan data terstruktur, gunakan kolom displayOptions. Kolom displayOptions berisi label tampilan untuk jenis objek dan serangkaian metalines. Setiap metaline adalah array dari label tampilan dan pasangan nilai seperti yang dikonfigurasi dalam skema.
Mengambil hasil tambahan
Untuk mengambil hasil tambahan, tetapkan kolom start dalam permintaan ke offset yang diinginkan. Anda dapat menyesuaikan ukuran setiap halaman di kolom pageSize.
Untuk menampilkan jumlah item yang ditampilkan atau untuk menampilkan kontrol paging halaman melalui item yang ditampilkan, gunakan kolom resultCount. Bergantung pada ukuran kumpulan hasil, nilai aktual atau nilai estimasi akan diberikan.
Mengurutkan hasil
Gunakan kolom sortOptions untuk menentukan urutan item yang ditampilkan. Nilai sortOptions adalah objek dengan dua kolom:
operatorName— operator untuk properti data terstruktur yang akan diurutkan. Untuk properti yang memiliki beberapa operator, Anda hanya dapat mengurutkan menggunakan operator kesetaraan utama.sortOrder— arah pengurutan,ASCENDINGatauDESCENDING.
Relevansi juga digunakan sebagai kunci pengurutan sekunder. Jika tidak ada tata urutan yang ditentukan dalam kueri, hasil akan diurutkan hanya berdasarkan relevansi.
"sortOptions": {
"operatorName": "priority",
"sortOrder": "DESCENDING"
}
Menambahkan filter
Selain ekspresi kueri, Anda juga dapat membatasi hasil dengan menerapkan filter. Anda dapat menentukan filter di aplikasi penelusuran dan di permintaan penelusuran.
Untuk menambahkan filter dalam permintaan atau aplikasi penelusuran, tambahkan filter di kolom dataSourceRestrictions.filterOptions[].
Ada dua cara utama untuk memfilter sumber data lebih lanjut:
- Filter objek, melalui properti
filterOptions[].objectType- membatasi item yang cocok dengan tipe yang ditentukan seperti yang ditentukan dalam skema khusus. - Filter nilai - membatasi item yang cocok berdasarkan operator kueri dan nilai yang diberikan.
Filter komposit memungkinkan menggabungkan beberapa filter nilai ke dalam ekspresi logis untuk kueri yang lebih kompleks.
Dalam contoh skema film, Anda dapat menerapkan batasan usia berdasarkan pengguna saat ini dan membatasi film yang tersedia berdasarkan rating MPAA.
{
"query": "adventure",
"requestOptions": {
"searchApplicationId": "<search_app_id>"
},
"dataSourceRestrictions": [
{
"source": {
"name": "datasources/<data_source_id>"
},
"filterOptions": [
{
"objectType": "movie",
"filter": {
"compositeFilter": {
"logicOperator": "AND"
"subFilters": [
{
"compositeFilter": {
"logicOperator": "OR"
"subFilters": [
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "G"
}
}
},
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "PG"
}
}
}
]
}
]
}
}
}
]
}
]
}
Menyaring hasil dengan faset
Faset adalah properti terindeks yang merepresentasikan kategori untuk menyaring hasil penelusuran. Gunakan faset untuk membantu pengguna menyaring kueri secara interaktif dan menemukan item yang relevan dengan lebih cepat.
Faset dapat ditetapkan dalam aplikasi penelusuran Anda dan diganti dengan setelan dalam kueri Anda.
Saat meminta faset, Cloud Search menghitung nilai yang paling sering digunakan untuk properti yang diminta di antara item yang cocok. Nilai-nilai ini ditampilkan dalam respons. Gunakan nilai-nilai ini untuk membuat filter yang mempersempit hasil pada kueri berikutnya.
Pola interaksi standar dengan faset adalah:
- Membuat kueri awal yang menentukan properti yang akan disertakan dalam hasil faset.
- Melakukan render hasil penelusuran dan faset.
- Pengguna memilih satu atau beberapa nilai faset untuk menyaring hasilnya.
- Mengulangi kueri dengan filter berdasarkan nilai yang dipilih.
Misalnya, untuk mengaktifkan penyaringan kueri film berdasarkan tahun dan rating MPAA, sertakan properti facetOptions dalam kueri.
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
Menafsirkan bucket faset
Properti facetResults dalam respons mencakup entri untuk setiap properti yang diminta. Untuk setiap properti, daftar nilai atau rentang bernama buckets disediakan. Nilai yang paling sering digunakan akan muncul terlebih dahulu.
Saat pengguna memilih satu atau beberapa nilai untuk difilter, buat kueri baru dengan filter yang dipilih dan buat kueri API lagi.
Menambahkan saran
Gunakan API saran untuk memberikan penyelesaian otomatis untuk kueri yang didasarkan pada histori kueri pribadi pengguna, serta kontak dan korpus dokumen mereka.
Misalnya, panggilan berikut memberi saran untuk frasa sebagian jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Anda kemudian dapat menampilkan saran yang dihasilkan sesuai kebutuhan aplikasi Anda.