Membuat antarmuka penelusuran dengan Query API

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 selengkapnya, lihat Membuat antarmuka penelusuran dengan widget penelusuran

Membuat antarmuka penelusuran

Perlu beberapa langkah untuk membuat antarmuka penelusuran minimal:

  1. Mengonfigurasi aplikasi penelusuran
  2. Buat kredensial OAuth untuk aplikasi
  3. Buat kueri indeks
  4. 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 untuk kueri, seperti sumber data yang akan digunakan, tata urutan, filter, dan faset yang dapat diminta. Jika perlu, Anda dapat mengganti parameter ini menggunakan Query API.

Untuk informasi selengkapnya tentang aplikasi penelusuran, lihat Menyesuaikan pengalaman penelusuran di Cloud Search.

Buat kredensial OAuth untuk aplikasi

Selain langkah-langkah dalam Konfigurasikan 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"}.

Membuat kueri indeks

Menggunakan search untuk melakukan pencarian 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

Setidaknya, antarmuka penelusuran diharapkan menampilkan item title sebagai serta tautan ke item aslinya. Anda dapat lebih meningkatkan 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 ada hasil yang tidak memadai untuk kueri pengguna. Tujuan queryInterpretation dalam respons menunjukkan kapan hasil tambahan dikembalikan. Jika saja hasil tambahan ditampilkan, InterpretationType disetel ke REPLACE. Jika beberapa hasil untuk kueri asli dikembalikan bersama dengan hasil, InterpretationType ditetapkan ke BLEND. Dalam kedua kasus QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

Saat beberapa hasil tambahan dikembalikan, pertimbangkan untuk menyediakan teks untuk menunjukkan hasil tambahan dikembalikan. Misalnya, dalam kasus REPLACE, Anda mungkin menampilkan string "Penelusuran Anda untuk kueri awal melakukan tidak cocok dengan hasil apa pun. Menampilkan hasil untuk kueri serupa”.

Dalam kasus BLEND, Anda mungkin menampilkan string "Penelusuran Anda untuk kueri asli tidak cocok dengan hasil yang memadai. Termasuk hasil untuk penelusuran serupa kueri".

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 seseorang yang namanya digunakan dalam kueri. Jenis hasil yang terakhir adalah fungsi dari {i>Cloud<i} Fitur Penelusuran Orang pada Penelusuran dan hasil untuk kueri semacam itu dapat ditemukan di tindakan structuredResults respons API kueri:

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

Pencocokan Laporan Langsung

Pencocokan Laporan Langsung adalah fitur {i> People Search<i} dari Cloud Search yang memungkinkan pengguna melihat bawahan langsung dari seseorang di organisasi mereka. Hasilnya tersedia dalam kolom structuredResults.

Untuk kueri tentang manajer atau bawahan langsung seseorang, responsnya memiliki assistCardProtoHolder dalam structuredResults. Tujuan assistCardProtoHolder memiliki kolom bernama cardType yang akan sama dengan RELATED_PEOPLE_ANSWER_CARD. assistCardProtoHolder berisi kartu yang disebut relatedPeopleAnswerCard yang berisi respons sebenarnya. Kolom ini berisi subject (orang yang disertakan dalam kueri) dan relatedPeople yang merupakan kumpulan orang yang terkait dengan subjek. Tujuan Kolom relationType menampilkan nilai MANAGER atau DIRECT_REPORTS.

Kode berikut menunjukkan contoh respons untuk pencocokan laporan langsung kueri:

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

Menonaktifkan pengoptimalan, termasuk hasil tambahan

Secara default, pengoptimalan, seperti hasil tambahan, diaktifkan. Anda bisa, tetapi menonaktifkan semua pengoptimalan atau hanya hasil tambahan di tingkat aplikasi dan 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 rendering hasilnya. Contoh javascript berikut mengonversi cuplikan menjadi Markup HTML dengan setiap rentang yang cocok yang digabungkan dalam 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...

Metadata Display

Menggunakan metadata kolom ini untuk menampilkan informasi tambahan tentang item yang dikembalikan yang mungkin relevan kepada pengguna. Kolom metadata mencakup createTime dan updateTime item serta data terstruktur apa pun yang dapat ditampilkan dengan item tersebut.

Untuk menampilkan data terstruktur, gunakan displayOptions kolom tersebut. 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, setel start dalam permintaan ke offset yang diinginkan. Anda dapat menyesuaikan ukuran setiap halaman dengan atribut pageSize kolom tersebut.

Untuk menampilkan jumlah item yang ditampilkan atau untuk menampilkan kontrol paging kepada melalui item yang dikembalikan, gunakan resultCount kolom tersebut. Bergantung pada ukuran kumpulan hasil, nilai aktual atau nilai estimasi akan diberikan.

Urutkan hasil

Menggunakan sortOptions untuk menentukan urutan item yang dikembalikan. 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 atau DESCENDING.

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 serta 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 mencocokkan item dengan jenis tertentu, seperti yang didefinisikan 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.

Facet dapat didefinisikan dalam aplikasi penelusuran. dan diganti oleh 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:

  1. Membuat kueri awal yang menentukan properti yang akan disertakan dalam hasil faset.
  2. Melakukan render hasil penelusuran dan faset.
  3. Pengguna memilih satu atau beberapa nilai faset untuk menyaring hasilnya.
  4. Mengulangi kueri dengan filter berdasarkan nilai yang dipilih.

Misalnya, untuk memungkinkan penyempurnaan 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 bidang berbasis bilangan bulat

Anda juga dapat membagi hasil permintaan dengan kolom berbasis bilangan bulat. Sebagai contoh, Anda mungkin menandai properti bilangan bulat yang disebut book_pages sebagai tabel yang dapat difilter hasil untuk penelusuran tentang buku dengan "100-200" halaman.

Saat menyiapkan skema kolom properti bilangan bulat, tetapkan isFacetable ke true, lalu tambahkan opsi pengelompokan yang sesuai ke integerPropertyOptions. Hal ini memastikan bahwa setiap properti bilangan bulat yang dapat facetable memiliki bucketing default menentukan.

Saat menentukan logika opsi bucketing, berikan array nilai inkremental menandakan rentang. Misalnya, jika pengguna akhir menentukan rentang sebagai 2, 5, 10, 100, lalu facet untuk <2, [2-5), [5-10), [10-100), >=100 dihitung.

Anda bisa mengganti faset berbasis bilangan bulat dengan menentukan opsi pengelompokan yang sama untuk facetOptions dalam permintaan. Jika diperlukan, Cloud Search menggunakan opsi pengelompokan yang ditentukan dalam skema ketika aplikasi penelusuran atau permintaan kueri tidak memiliki faset menentukan. Facet yang ditentukan dalam kueri lebih diprioritaskan daripada facet yang ditentukan di aplikasi pencarian, dan {i>facet <i}yang didefinisikan dalam aplikasi pencarian, lebih diprioritaskan daripada faset yang ditentukan dalam skema.

Hasil {i>facet<i} berdasarkan ukuran atau tanggal dokumen

Anda dapat menggunakan operator yang dicadangkan untuk menyaring hasil penelusuran menurut ukuran file dokumen, diukur dalam byte, atau menurut sebuah dokumen dibuat atau diubah. Anda tidak perlu menentukan skema khusus, tetapi Anda perlu menentukan nilai operatorName dalam atribut FacetOptions.

  • Untuk facet menurut ukuran dokumen, gunakan itemsize dan tentukan opsi pengelompokan.
  • Untuk facet menurut tanggal pembuatan dokumen, gunakan createddatetimestamp.
  • Untuk facet berdasarkan tanggal perubahan dokumen, gunakan lastmodified.

Menafsirkan bucket faset

facetResults di respons kueri penelusuran mencakup permintaan filter yang sama persis dari pengguna 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, diberikan. 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.