Halaman ini diterjemahkan oleh Cloud Translation API.

Mengonfigurasi kontrol penyajian untuk penelusuran

Kontrol penayangan (juga disebut kontrol) mengubah perilaku default permintaan.

Misalnya, kontrol dapat meningkatkan dan menyembunyikan hasil, memfilter entri dari hasil yang ditampilkan, mengaitkan kueri satu sama lain sebagai sinonim, atau mengalihkan kueri ke URI yang ditentukan.

Halaman ini menjelaskan kontrol penayangan untuk aplikasi penelusuran. Untuk informasi tentang penggunaan kontrol penayangan dengan rekomendasi media, lihat Membuat dan mengelola konfigurasi penayangan.

Tentang kontrol inferensi

Untuk mengubah hasil permintaan, buat kontrol penayangan terlebih dahulu. Kemudian, lampirkan kontrol tersebut ke aplikasi. Kontrol hanya memengaruhi permintaan yang ditayangkan oleh aplikasi tempat kontrol dilampirkan. Jika kontrol tidak dilampirkan ke aplikasi, kontrol tersebut tidak akan berpengaruh.

Beberapa kontrol, seperti kontrol peningkatan, memiliki dependensi pada penyimpanan data. Jika penyimpanan data dihapus dari aplikasi, kontrol apa pun yang bergantung pada penyimpanan data juga akan dihapus dari aplikasi tersebut dan menjadi tidak aktif, tetapi tidak dihapus.

Saat membuat kontrol, Anda dapat menentukan kondisi yang menentukan kapan kontrol diterapkan secara opsional. Kondisi ditentukan menggunakan kolom kondisi. Kolom kondisi berikut tersedia:

queryTerms. Kontrol diterapkan saat kueri tertentu ditelusuri.
activeTimeRange. Kontrol diterapkan saat permintaan terjadi dalam rentang waktu yang ditentukan.

Jika kedua jenis kondisi ditentukan untuk kontrol, kontrol akan diterapkan ke permintaan penelusuran saat kedua jenis kondisi terpenuhi. Jika beberapa nilai untuk kondisi yang sama ditentukan, hanya salah satu nilai yang perlu cocok agar kondisi tersebut terpenuhi.

Misalnya, pertimbangkan kondisi berikut dengan dua istilah kueri yang ditentukan:

"queryTerms": [
  {
    "value": "gShoe",
    "fullMatch": true
  },
  {
    "value": "gBoot",
    "fullMatch": true
  }
]

Kondisi akan terpenuhi untuk permintaan dengan SearchRequest.query="gShoe" atau permintaan dengan SearchRequest.query="gBoot", tetapi tidak akan terpenuhi dengan SearchRequest.query="gSandal" atau string lainnya.

Jika tidak ada kondisi yang ditentukan, kontrol akan selalu diterapkan.

Untuk informasi selengkapnya, lihat servingConfigs.search dalam referensi API.

Jenis kontrol penayangan

Jenis kontrol penayangan berikut tersedia:

Kontrol	Deskripsi	Tersedia untuk
Kontrol boost	Mengubah urutan hasil yang ditampilkan	Menelusuri aplikasi dengan penyimpanan data yang mendukung skema, seperti penyimpanan data yang berisi data terstruktur, situs dengan data terstruktur, data tidak terstruktur dengan metadata, atau data media
Kontrol filter	Menghapus entri dari hasil yang ditampilkan	Menelusuri aplikasi dengan penyimpanan data yang mendukung skema, seperti penyimpanan data yang berisi data terstruktur, situs dengan data terstruktur, data tidak terstruktur dengan metadata, atau data media
Kontrol sinonim	Mengaitkan kueri satu sama lain	Menelusuri aplikasi dengan penyimpanan data situs, terstruktur, tidak terstruktur, atau media
Kontrol pengalihan	Mengalihkan ke URI yang ditentukan	Semua aplikasi penelusuran

Tentang kontrol penayangan boost

Kontrol penayangan boost ditentukan sebagai kontrol dengan boostAction.

Sintaksis untuk boostAction adalah sebagai berikut:

{
    "boost": "BOOST",
    "filter": "FILTER",
    "dataStore": "DATA_STORE_RESOURCE_PATH"
}

BOOST: Float antara -1 dan 1. Jika nilainya negatif, hasil akan didemosikan agar muncul nanti di hasil penelusuran. Jika nilainya positif, hasil akan dipromosikan untuk muncul lebih awal di hasil penelusuran.
FILTER: String yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Jika dokumen cocok dengan semua persyaratan, peningkatan akan diterapkan. Jika tidak, tidak ada perubahan. Jika kolom ini kosong, peningkatan akan diterapkan ke semua dokumen di penyimpanan data. Untuk sintaks pemfilteran, lihat Sintaksis ekspresi filter.
DATA_STORE_RESOURCE_PATH: Jalur resource lengkap penyimpanan data yang dokumennya harus dioptimalkan oleh kontrol ini. Format jalur resource lengkap adalah projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Penyimpanan data ini harus dilampirkan ke mesin yang ditentukan dalam permintaan.

Tentang kontrol penayangan filter

Kontrol penayangan filter ditentukan sebagai kontrol dengan filterAction.

Sintaksis untuk filterAction adalah sebagai berikut:

{
    "filter": "FILTER"
}

FILTER: String yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Jika dokumen cocok dengan semua persyaratan, hasilnya akan disertakan dalam daftar hasil. Jika tidak, hasilnya akan dihapus dari daftar hasil. Untuk sintaksis pemfilteran, lihat Sintaksis ekspresi filter.

Tentang kontrol penayangan sinonim

Kontrol penayangan sinonim ditentukan sebagai kontrol dengan synonymsAction.

Sintaksis untuk synonymsAction adalah sebagai berikut:

{
    "synonyms": "SYNONYMS"
}

SYNONYMS: String yang akan dikaitkan satu sama lain, sehingga setiap string lebih cenderung menampilkan hasil yang serupa. Anda harus menentukan setidaknya dua string, dan Anda dapat menentukan hingga 100 string. String harus berupa UTF-8 dan huruf kecil. String duplikat tidak diizinkan.

Contoh:

{
    "synonyms": ["pixel", "android phone", "google phone"]
}

Tentang kontrol penayangan pengalihan

Kontrol penayangan pengalihan memungkinkan pengalihan pengguna ke URI yang disediakan.

Kontrol pengalihan ditentukan sebagai kontrol dengan redirectAction.

Sintaksis untuk redirectAction:

{
    "redirect_uri": "REDIRECT_URI"
}

REDIRECT_URI: URI maksimal 2.000 karakter.

Misalnya, jika nilai istilah kueri adalah "dukungan", Anda dapat menetapkan pengalihan ke halaman dukungan teknis, bukan menampilkan (atau gagal menampilkan) hasil penelusuran untuk "dukungan".

{
    "redirect_uri": ["https://www.example.com/support"]
}

Tentang kondisi `queryTerms`

queryTerms bersifat opsional. Gunakan jika Anda ingin kontrol penayangan digunakan saat kueri tertentu ditelusuri. Saat kondisi queryTerms digunakan, kontrol diterapkan saat nilai queryTerms cocok dengan istilah dalam SearchRequest.query.

Istilah kueri hanya dapat digunakan jika Control.searchUseCase ditetapkan sebagai SOLUTION_TYPE_SEARCH.

Maksimal 10 queryTerms yang berbeda dapat ditentukan pada satu Control.condition. Jika tidak ada istilah kueri yang ditentukan, kolom akan diabaikan.

Sintaksis untuk satu queryTerm adalah sebagai berikut:

{
    "value": "VALUE_1",
    "fullMatch": "FULL_MATCH_1"
}

VALUE_1: String UTF-8 huruf kecil dengan panjang [1, 5000]. Jika FULL_MATCH_1 adalah true, FULL_MATCH_1 dapat memiliki maksimal tiga istilah yang dipisahkan spasi.
FULL_MATCH_1: Boolean. Jika ditetapkan ke true, SearchRequest.query harus sepenuhnya cocok dengan queryTerm.value. Jika ditetapkan ke false, SearchRequest.query harus berisi queryTerm.value sebagai substring.

Tentang kondisi `activeTimeRange`

activeTimeRange bersifat opsional. Fungsi ini memeriksa apakah waktu permintaan diterima berada antara activeTimeRange.startTime dan activeTimeRange.endTime.

Maksimal 10 rentang activeTimeRange dapat ditentukan pada satu Control.condition. Jika tidak ada rentang activeTimeRange yang ditentukan, kolom akan diabaikan.

Sintaksis untuk satu activeTimeRange adalah sebagai berikut:

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]

START_TIMESTAMP_1: Menentukan waktu paling awal (inklusif) saat kontrol akan diterapkan. Stempel waktu dalam format RFC 3339 UTC "Zulu", dengan resolusi nanodetik dan hingga sembilan digit pecahan—misalnya, "2023-10-02T15:01:23Z".
END_TIMESTAMP_1: Menentukan waktu terbaru (inklusif) saat kontrol akan diterapkan. Waktu ini harus di masa mendatang.

Petunjuk API: Mengubah perilaku permintaan penelusuran default dengan kontrol penayangan

Untuk mengubah perilaku permintaan penelusuran default, Anda membuat kontrol penayangan dan melampirkannya ke konfigurasi penayangan default.

Sebelum memulai

Jika Anda ingin membuat kontrol penayangan, hubungi tim akun Google Anda dan minta untuk ditambahkan ke daftar yang diizinkan untuk kontrol penayangan.

Membuat kontrol inferensi

Gunakan petunjuk berikut untuk membuat kontrol penayangan.

Untuk mengetahui detail kolom, lihat referensi API Controls dan referensi API Controls.create.

Temukan ID penyimpanan data Anda. Jika Anda sudah memiliki ID penyimpanan data, lanjutkan ke langkah berikutnya.
1. Di konsol Google Cloud, buka halaman Agent Builder dan di menu navigasi, klik Data Stores.
  
  Buka halaman Data Store
2. Klik nama penyimpanan data Anda.
3. Di halaman Data untuk penyimpanan data Anda, dapatkan ID penyimpanan data.

Pilih jenis kondisi dan nilai kolom untuk kontrol Anda.

Berikut adalah contoh kondisi yang terpotong:

{
  "queryTerms": [
      {
        "value": "VALUE_1",
        "fullMatch": FULL_MATCH_1
      },
      {
        "value": "VALUE_2",
        "fullMatch": FULL_MATCH_2
      },
    ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP_1",
      "endTime": "END_TIMESTAMP_1"
    },
    {
      "startTime": "START_TIMESTAMP_2",
      "endTime": "END_TIMESTAMP_2"
    },
  ]
}

Jalankan perintah curl berikut untuk membuat kontrol Anda.

Kontrol boost: Klik untuk melihat perintah curl guna membuat kontrol boost.

Jalankan perintah curl berikut:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/controls?CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "boostAction": "BOOST_ACTION",
    }'

Filter control: Klik untuk melihat perintah curl guna membuat kontrol filter.

Jalankan perintah curl berikut:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "filterAction": "FILTER_ACTION",
    }'

Kontrol sinonim: Klik untuk melihat perintah curl guna membuat kontrol sinonim.

Jalankan perintah curl berikut:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "synonymsAction": "SYNONYMS_ACTION",
    }'

Kontrol pengalihan: Klik untuk melihat perintah curl guna membuat kontrol pengalihan.

Jalankan perintah curl berikut:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "redirectAction": "REDIRECT_ACTION",
    }'

PROJECT_ID: Nomor atau ID project Google Cloud Anda.
DATA_STORE_ID: ID unik penyimpanan data.
CONTROL_ID: ID unik (dalam penyimpanan data) untuk kontrol. ID dapat berisi huruf kecil, angka, tanda hubung, dan garis bawah.
DISPLAY_NAME: Nama yang dapat dibaca manusia untuk kontrol. Google merekomendasikan agar nama ini memberikan indikasi kapan atau mengapa kontrol harus digunakan. Harus berupa string UTF-8 dengan panjang [1,128].
USE_CASE: Harus SEARCH_USE_CASE_SEARCH atau SEARCH_USE_CASE_BROWSE. Jika SEARCH_USE_CASE_BROWSE ditentukan, Condition.queryTerms tidak dapat digunakan dalam kondisi.
CONDITION: (Opsional) Menentukan kapan kontrol harus diterapkan.
BOOST_ACTION: Digunakan untuk menentukan kontrol boost. Lihat referensi API boostAction.
FILTER_ACTION: Digunakan untuk menentukan kontrol filter. Lihat referensi API filterAction.
SYNONYMS_ACTION: Digunakan untuk menentukan kontrol sinonim. Lihat referensi API synonymsAction.
REDIRECT_ACTION: Digunakan untuk menentukan URI pengalihan. Lihat referensi API redirectAction.

Lampirkan kontrol ke aplikasi.

Kontrol peningkatan: Klik untuk melihat perintah curl untuk kontrol peningkatan.

Jalankan perintah curl berikut untuk melampirkan kontrol boost ke konfigurasi penayangan untuk mengaktifkan penggunaan pada permintaan penayangan:

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
    -d '{
      "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2" … ]
    }'

BOOST_ID_1 dan BOOST_ID_2: Merepresentasikan ID kontrol yang Anda buat di langkah sebelumnya.

Kontrol filter: Klik perintah curl untuk kontrol filter.

Jalankan perintah curl berikut untuk melampirkan kontrol filter ke konfigurasi penayangan untuk mengaktifkan penggunaan pada permintaan penayangan:

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
    -d '{
      "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2" … ]
    }'

FILTER_ID_1 dan FILTER_ID_2: Merepresentasikan ID kontrol yang Anda buat di langkah sebelumnya.

Kontrol sinonim: Klik untuk melihat perintah curl untuk kontrol sinonim.

Jalankan perintah curl berikut untuk melampirkan kontrol sinonim ke aplikasi guna mengaktifkan penggunaan pada permintaan penayangan:

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
    -d '{
     "synonymsControlIds": ["SYNONYM_ID_1", "SYNONYM_ID_2" … ]
    }'

SYNONYM_ID_1 dan SYNONYM_ID_2: Merepresentasikan ID kontrol yang Anda buat di langkah sebelumnya.

Kontrol pengalihan: Klik untuk melihat perintah curl untuk kontrol pengalihan.

Jalankan perintah curl berikut untuk melampirkan kontrol pengalihan ke aplikasi guna mengaktifkan penggunaan pada permintaan penayangan:

    curl -X PATCH
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
    -d '{
      "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2" … ]
    }'

REDIRECT_ID_1 dan REDIRECT_ID_2: Merepresentasikan ID kontrol yang Anda buat di langkah sebelumnya.

Langkah selanjutnya

Untuk memahami dampak kontrol penayangan pada kualitas penelusuran aplikasi penelusuran umum, evaluasi kualitas penelusuran. Untuk informasi selengkapnya, lihat Mengevaluasi kualitas penelusuran.

Mengonfigurasi kontrol penyajian untuk penelusuran

Tentang kontrol inferensi

Jenis kontrol penayangan

Tentang kontrol penayangan boost

Tentang kontrol penayangan filter

Tentang kontrol penayangan sinonim

Tentang kontrol penayangan pengalihan

Tentang kondisi queryTerms

Tentang kondisi activeTimeRange

Petunjuk API: Mengubah perilaku permintaan penelusuran default dengan kontrol penayangan

Sebelum memulai

Membuat kontrol inferensi

Langkah selanjutnya

Tentang kondisi `queryTerms`

Tentang kondisi `activeTimeRange`