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
Membuat antarmuka penelusuran minimal memerlukan beberapa langkah:
- Mengonfigurasi 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 digunakan, tata urutan, filter, dan faset yang diminta. Jika diperlukan, Anda dapat mengganti parameter ini menggunakan query API.
Untuk informasi lebih lanjut tentang aplikasi penelusuran, lihat Menyesuaikan pengalaman penelusuran di Cloud Search.
Buat kredensial OAuth untuk aplikasi
Selain langkah-langkah dalam Mengonfigurasi akses ke Google Cloud Search API, 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 [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.
Buat kueri indeks
Gunakan metode search
untuk melakukan penelusuran terhadap indeks.
Setiap permintaan harus menyertakan dua informasi: teks query
untuk mencocokkan item dan searchApplicationId
yang mengidentifikasi ID untuk
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
Minimal, antarmuka penelusuran diharapkan untuk menampilkan item title
serta
link ke item asli. Anda dapat meningkatkan kualitas tampilan
hasil penelusuran dengan memanfaatkan informasi tambahan yang ada di hasil penelusuran
seperti cuplikan dan metadata.
Menangani hasil tambahan
Secara default, Cloud Search menampilkan hasil tambahan jika tidak ada hasil yang cukup untuk kueri pengguna. Kolom
queryInterpretation
dalam respons menunjukkan kapan hasil tambahan ditampilkan. Jika hanya
hasil tambahan yang ditampilkan, InterpretationType
akan ditetapkan ke REPLACE
. Jika beberapa hasil untuk kueri asli ditampilkan bersama dengan hasil tambahan, InterpretationType
akan ditetapkan ke BLEND
. Dalam kedua kasus tersebut,
QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
.
Saat beberapa hasil tambahan ditampilkan, pertimbangkan menyediakan teks
untuk menunjukkan hasil tambahan yang dikembalikan. Misalnya, dalam kasus
REPLACE
, Anda mungkin menampilkan string "Penelusuran Anda untuk kueri asli Anda
tidak cocok dengan hasil apa pun. Menampilkan hasil untuk kueri serupa.”
Dalam kasus BLEND
, Anda mungkin menampilkan string "Penelusuran Anda untuk
kueri asli Anda tidak cocok dengan hasil yang cukup. Menyertakan hasil untuk kueri serupa."
Menangani hasil penelusuran orang
Cloud Search menampilkan dua jenis "hasil orang": dokumen yang terkait dengan orang yang namanya digunakan dalam kueri dan informasi karyawan untuk orang yang namanya digunakan dalam kueri. Jenis hasil terakhir adalah fungsi dari fitur People Search di Cloud Search dan hasil untuk kueri tersebut dapat ditemukan di kolom structuredResults
pada respons API kueri:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
Nonaktifkan pengoptimalan, termasuk hasil tambahan
Secara default, pengoptimalan, seperti hasil tambahan, diaktifkan. Namun, Anda dapat menonaktifkan semua pengoptimalan atau hanya hasil tambahan di tingkat aplikasi penelusuran dan kueri:
Untuk menonaktifkan semua pengoptimalan di tingkat aplikasi penelusuran, termasuk termasuk hasil tambahan, sinonim, dan koreksi ejaan, tetapkan
QueryInterpretationConfig.force_verbatim_mode
ketrue
di aplikasi penelusuran.Untuk menonaktifkan semua pengoptimalan di tingkat kueri penelusuran, termasuk hasil tambahan, sinonim, dan koreksi ejaan, tetapkan
QueryInterpretationOptions.enableVerbatimMode
ketrue
dalam kueri penelusuran.Untuk menonaktifkan hasil tambahan di tingkat aplikasi penelusuran, tetapkan
QueryInterpretationOptions.forceDisableSupplementalResults
ketrue
dalam kueri penelusuran.Untuk menonaktifkan hasil tambahan pada tingkat kueri penelusuran, tetapkan
QueryInterpretationOptions.disableSupplementalResults
ketrue
dalam kueri penelusuran.
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 menandai teks yang cocok saat merender
hasil. Contoh JavaScript berikut mengonversi cuplikan 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
bagi pengguna. Kolom metadata
menyertakan createTime
dan
updateTime
item serta data terstruktur yang dapat ditampilkan, yang terkait
dengan item tersebut.
Untuk menampilkan data terstruktur, gunakan kolom
displayOptions
. Kolom displayOptions
berisi label tampilan untuk jenis objek
dan kumpulan 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 dengan kolom pageSize
.
Untuk menampilkan jumlah item yang ditampilkan atau untuk menampilkan kontrol paging guna menelusuri
item yang ditampilkan, gunakan kolom
resultCount
. Bergantung pada ukuran kumpulan hasil, nilai aktual atau nilai estimasi akan diberikan.
Urutkan 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,ASCENDING
atauDESCENDING
.
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 baik di aplikasi penelusuran maupun 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 jenis yang ditentukan seperti yang ditentukan dalam skema kustom. - 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 ditentukan 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 penajaman 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"
}
]
Hasil faset dengan kolom berbasis bilangan bulat
Anda juga dapat menampilkan hasil permintaan dengan kolom berbasis bilangan bulat. Misalnya, Anda
dapat menandai properti bilangan bulat yang disebut book_pages
sebagai facetable untuk menyaring
hasil penelusuran tentang buku dengan halaman "100-200".
Saat Anda menyiapkan skema kolom properti bilangan bulat, tetapkan
isFacetable
ke true
dan tambahkan opsi pengelompokan yang sesuai ke
integerPropertyOptions
.
Hal ini memastikan bahwa setiap properti integer-facetable memiliki opsi bucket default yang ditentukan.
Saat menentukan logika opsi pengelompokan, berikan array nilai inkremental yang menandakan rentang. Misalnya, jika pengguna akhir menentukan rentang sebagai
2, 5, 10, 100
, faset untuk <2
, [2-5)
, [5-10)
, [10-100)
, >=100
akan dihitung.
Anda dapat mengganti faset berbasis bilangan bulat dengan menentukan opsi bucketing yang sama ke
facetOptions
dalam permintaan. Jika diperlukan, Cloud Search akan menggunakan opsi pengelompokan yang ditentukan dalam
skema saat aplikasi penelusuran atau permintaan kueri tidak memiliki opsi
faset yang ditentukan. Faset yang ditentukan dalam kueri lebih diutamakan daripada faset yang ditentukan
dalam aplikasi penelusuran, dan faset yang ditentukan dalam aplikasi penelusuran akan lebih diutamakan
dari faset yang ditentukan dalam skema.
Hasil faset menurut ukuran atau tanggal dokumen
Anda dapat menggunakan operator yang dicadangkan untuk menyaring hasil penelusuran menurut ukuran file dokumen, diukur dalam byte, atau berdasarkan waktu pembuatan atau modifikasi dokumen. Anda tidak perlu menentukan skema kustom,
tetapi Anda harus menentukan nilai operatorName
dalam
FacetOptions
aplikasi penelusuran.
- Untuk menangani ukuran dokumen, gunakan
itemsize
dan tentukan opsi pengelompokan. - Untuk faset berdasarkan tanggal pembuatan dokumen, gunakan
createddatetimestamp
. - Untuk menghadapi tanggal modifikasi pada dokumen, gunakan
lastmodified
.
Menafsirkan bucket faset
Properti facetResults
dalam respons kueri penelusuran mencakup permintaan filter pengguna yang tepat
di kolom filter
untuk setiap
bucket
.
Untuk faset yang tidak didasarkan pada bilangan bulat, facetResults
menyertakan entri untuk setiap properti yang diminta. Untuk setiap properti, daftar nilai atau rentang, yang disebut 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.