Mengonfigurasi kontrol penyajian untuk penelusuran

Kontrol penayangan (juga disebut kontrol) mengubah perilaku default cara permintaan ditayangkan saat hasil ditampilkan. Kontrol penayangan bertindak di tingkat penyimpanan data.

Misalnya, kontrol dapat meningkatkan dan menyembunyikan hasil, memfilter entri dari hasil yang ditampilkan, mengaitkan string satu sama lain sebagai sinonim, atau mengalihkan hasil 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 media.

Tentang kontrol inferensi

Untuk mengubah hasil permintaan, buat kontrol penayangan terlebih dahulu. Kemudian, lampirkan kontrol tersebut ke konfigurasi penayangan aplikasi penelusuran. Konfigurasi penayangan mengonfigurasi metadata yang digunakan untuk menghasilkan hasil waktu penayangan, seperti hasil penelusuran atau jawaban. Kontrol penayangan hanya memengaruhi permintaan yang ditayangkan oleh aplikasi jika kontrol dilampirkan ke konfigurasi penayangan aplikasi.

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.

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 (pengindeksan situs lanjutan), 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 (pengindeksan situs lanjutan dan penelusuran situs dasar), data tidak terstruktur dengan metadata, atau data media
Kontrol sinonim Mengaitkan kueri satu sama lain Menelusuri aplikasi dengan situs (pengindeksan situs lanjutan), penyimpanan data terstruktur, tidak terstruktur, atau media
Kontrol pengalihan Mengalihkan ke URI yang ditentukan Semua aplikasi penelusuran
Promosikan kontrol Mempromosikan link yang ditentukan untuk kueri Hanya aplikasi penelusuran situs dasar

Tentang kondisi

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 opsional yang diterapkan 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 di satu Control.condition. Jika tidak ada istilah kueri yang ditentukan, kolom queryTerms akan diabaikan.

    Untuk kontrol penayangan promosi, batasan tambahan berikut berlaku:

    • Kondisi queryTerms tidak dapat ditentukan jika Anda menentukan kondisi queryRegex
    • fullMatch harus ditetapkan ke true

  • activeTimeRange. Kontrol opsional yang diterapkan saat permintaan terjadi dalam rentang waktu yang ditentukan. Fungsi ini memeriksa apakah waktu permintaan diterima antara activeTimeRange.startTime dan activeTimeRange.endTime. Maksimal 10 rentang activeTimeRange dapat ditentukan pada satu Control.condition. Jika kolom activeTimeRange tidak ditentukan, kolom tersebut akan diabaikan.

  • queryRegex. Hanya tersedia untuk kontrol penayangan promosi, kondisi opsional yang menerapkan kontrol saat kueri cocok dengan ekspresi reguler yang ditentukan. Kondisi ini tidak dapat ditentukan jika Anda menentukan kondisi queryTerms.

Jika beberapa kondisi ditentukan untuk kontrol, kontrol akan diterapkan ke permintaan penelusuran jika 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 mengetahui informasi selengkapnya, lihat kolom Condition dalam referensi API.

Membuat dan melampirkan kontrol penayangan boost

Kontrol penayangan boost ditentukan sebagai kontrol dengan boostAction.

Gunakan petunjuk berikut untuk membuat kontrol penayangan boost.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

  1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

    1. Di konsol Google Cloud, buka halaman Agent Builder.

      Buka Aplikasi

    2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

  2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

    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/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": [
  "USE_CASE"
],
"conditions": {
 "queryTerms": [
   {
     "value": "VALUE",
     "fullMatch": FULL_MATCH
   }
 ],
 "activeTimeRange": [
   {
     "startTime": "START_TIMESTAMP",
     "endTime": "END_TIMESTAMP"
   }
 ]
},
"boostAction": {
  "boost": BOOST_VALUE,
  "filter": "FILTER",
  "dataStore": "DATA_STORE_RESOURCE_PATH"
 }
}'

    Ganti kode berikut:

    • PROJECT_ID: nomor atau ID Google Cloud project Anda.
    • APP_ID: ID aplikasi Vertex AI Search.
    • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, 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 menggunakan kontrol. Harus berupa string berenkode 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: kolom opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
      • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000]. Jika FULL_MATCH_1 adalah true, kolom ini dapat memiliki maksimal tiga istilah yang dipisahkan spasi.
      • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika ditetapkan ke true, SearchRequest.query harus sepenuhnya cocok dengan queryTerm.value. Jika ditetapkan ke false, SearchRequest.query harus berisi queryTerm.value sebagai substring.
      • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
      • END_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan akhir rentang waktu.
    • BOOST_VALUE: bilangan floating point dalam rentang [-1,1]. Jika nilainya negatif, hasil akan diturunkan (muncul lebih rendah dalam hasil). Jika nilainya positif, hasil akan dipromosikan (muncul lebih tinggi di hasil). Untuk informasi selengkapnya, lihat boostAction.
    • 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, pengoptimalan akan diterapkan ke semua dokumen di penyimpanan data. Untuk sintaksis pemfilteran, lihat Sintaksis ekspresi filter. Catatan: Kolom dokumen title tidak dapat difilter.
    • DATA_STORE_RESOURCE_PATH: jalur resource lengkap dari penyimpanan data yang dokumennya harus dioptimalkan oleh kontrol ini. Format jalur resource lengkap adalah projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Penyimpanan data ini harus dilampirkan ke mesin yang ditentukan dalam permintaan.

  3. Lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch.

    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/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
-d '{
 "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]
}'

    Ganti BOOST_ID_N dengan ID kontrol yang Anda buat di langkah sebelumnya.

Membuat dan melampirkan kontrol penayangan filter

Kontrol penayangan filter ditentukan sebagai kontrol dengan filterAction.

Gunakan petunjuk berikut untuk membuat kontrol penayangan filter.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

  1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

    1. Di konsol Google Cloud, buka halaman Agent Builder.

      Buka Aplikasi

    2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

  2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

    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/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"filterAction": {
  "filter": "FILTER"
 }
}'

    Ganti kode berikut:

    • PROJECT_ID: nomor atau ID Google Cloud project Anda.
    • APP_ID: ID aplikasi Vertex AI Search.
    • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, 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 menggunakan kontrol. Harus berupa string berenkode 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: kolom opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
      • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000]. Jika FULL_MATCH_1 adalah true, kolom ini dapat memiliki maksimal tiga istilah yang dipisahkan spasi.
      • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika ditetapkan ke true, SearchRequest.query harus sepenuhnya cocok dengan queryTerm.value. Jika ditetapkan ke false, SearchRequest.query harus berisi queryTerm.value sebagai substring.
      • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
      • END_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan akhir rentang waktu.
    • FILTER: string yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Jika dokumen cocok dengan semua persyaratan, dokumen tersebut akan ditampilkan dalam hasil. Jika tidak, dokumen tidak akan ada dalam hasil. Untuk sintaksis pemfilteran, lihat Sintaksis ekspresi filter. Untuk informasi selengkapnya, lihat filterAction. Catatan: Kolom dokumen title tidak dapat difilter.

  3. Lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch.

    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/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
-d '{
  "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]
}'

    Ganti FILTER_ID_N dengan ID kontrol yang Anda buat di langkah sebelumnya.

Membuat dan melampirkan kontrol penayangan sinonim

Kontrol penayangan sinonim ditentukan sebagai kontrol dengan synonymsAction.

Gunakan petunjuk berikut untuk membuat kontrol penayangan sinonim.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

  1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

    1. Di konsol Google Cloud, buka halaman Agent Builder.

      Buka Aplikasi

    2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

  2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

    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/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"synonymsAction": {
  "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
 }
}'

    Ganti kode berikut:

    • PROJECT_ID: nomor atau ID Google Cloud project Anda.
    • APP_ID: ID aplikasi Vertex AI Search.
    • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, 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 menggunakan kontrol. Harus berupa string berenkode 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: kolom opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
      • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000]. Jika FULL_MATCH_1 adalah true, kolom ini dapat memiliki maksimal tiga istilah yang dipisahkan spasi.
      • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika ditetapkan ke true, SearchRequest.query harus sepenuhnya cocok dengan queryTerm.value. Jika ditetapkan ke false, SearchRequest.query harus berisi queryTerm.value sebagai substring.
      • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
      • END_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan akhir rentang waktu.
    • SYNONYMS_N: daftar string yang terkait satu sama lain, sehingga setiap string lebih cenderung menampilkan hasil yang serupa. Meskipun Anda cenderung mendapatkan hasil yang serupa, saat menelusuri setiap entri sinonim, Anda mungkin tidak menerima semua hasil yang relevan untuk semua sinonim terkait. Anda harus menentukan minimal dua sinonim dan dapat menentukan hingga 100 sinonim. Setiap sinonim harus dienkode UTF-8 dan dalam huruf kecil. String duplikat tidak diizinkan. Misalnya, Anda dapat menambahkan "pixel", "ponsel android", dan "ponsel google" sebagai sinonim. Untuk informasi selengkapnya, lihat synonymsAction.

  3. Lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch.

    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/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
-d '{
  "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]
}'

    Ganti SYNONYMS_ID_N dengan ID kontrol yang Anda buat di langkah sebelumnya.

Membuat dan melampirkan kontrol penayangan pengalihan

Kontrol penayangan pengalihan memungkinkan pengalihan pengguna ke URI yang disediakan. Kontrol pengalihan ditentukan sebagai kontrol dengan redirectAction.

Gunakan petunjuk berikut untuk membuat kontrol penayangan pengalihan.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

  1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

    1. Di konsol Google Cloud, buka halaman Agent Builder.

      Buka Aplikasi

    2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

  2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

    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/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"redirectAction": {
  "redirectURI": "REDIRECT_URI"
 }
}'

    Ganti kode berikut:

    • PROJECT_ID: nomor atau ID Google Cloud project Anda.
    • APP_ID: ID aplikasi Vertex AI Search.
    • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, 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 menggunakan kontrol. Harus berupa string berenkode 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: kolom opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
      • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000]. Jika FULL_MATCH_1 adalah true, kolom ini dapat memiliki maksimal tiga istilah yang dipisahkan spasi.
      • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika ditetapkan ke true, SearchRequest.query harus sepenuhnya cocok dengan queryTerm.value. Jika ditetapkan ke false, SearchRequest.query harus berisi queryTerm.value sebagai substring.
      • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
      • END_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan akhir rentang waktu.
    • REDIRECT_URI_N: URI tempat Anda dialihkan. Dapat memiliki panjang maksimum 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". Dalam contoh ini, URI pengalihan menjadi "https://www.example.com/support". Untuk informasi selengkapnya, lihat redirectAction.

  3. Lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch.

    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/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
-d '{
  "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]
}'

    Ganti REDIRECT_ID_N dengan ID kontrol yang Anda buat di langkah sebelumnya.

Membuat dan melampirkan kontrol penayangan promosi

Kontrol penayangan promosi memungkinkan Anda menampilkan link sebagai hasil yang dipromosikan. Kontrol ini hanya tersedia untuk penyimpanan data situs dengan penelusuran situs dasar.

Tidak seperti kontrol penayangan lainnya, Anda tidak perlu melampirkan kontrol promosi ke konfigurasi penayangan aplikasi. Membuat dan mengaktifkan kontrol promosi untuk aplikasi akan mengaktifkan kontrol promosi. Selain itu, tidak seperti kontrol penayangan lainnya, Anda dapat mengaktifkan atau menonaktifkan kontrol promosi dengan mengaktifkan atau menonaktifkannya.

Kontrol promosi ditentukan menggunakan promoteAction.

Agar berhasil membuat kontrol promosi, salah satu kolom berikut diperlukan dalam permintaan pembuatan:

  • Kolom queryTerms dengan fullMatch ditetapkan ke true
  • Kolom queryRegex

Gunakan petunjuk berikut untuk membuat kontrol penayangan promosi.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

  1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

    1. Di konsol Google Cloud, buka halaman Agent Builder.

      Buka Aplikasi

    2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

  2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

    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/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": true
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ],
  "queryRegex": "VALUE_REGEX"
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "title": "URI_TITLE",
     "uri": "URI",
     "description": "URI_DESCRIPTION",
     "enabled": ENABLED_TRUE|FALSE,
  }
 }
}'

    Ganti kode berikut:

    • PROJECT_ID: nomor atau ID Google Cloud project Anda.
    • APP_ID: ID aplikasi Vertex AI Search.
    • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, 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 menggunakan kontrol. Harus berupa string berenkode 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: objek opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
      • queryTerms: Tidak dapat digunakan dengan kolom queryRegex.
        • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000].
      • activeTimeRange:
        • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
        • END_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan akhir rentang waktu.
      • queryRegex: Tidak dapat digunakan dengan kolom queryTerms.
        • VALUE_REGEX: ekspresi reguler yang akan dicocokkan dengan kueri. Fitur ini hanya tersedia untuk kontrol penayangan promosi.
    • DATA_STORE_RESOURCE_PATH: jalur resource lengkap dari penyimpanan data yang hasil penelusurannya berisi URL yang dipromosikan. Format jalur resource lengkap adalah projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Penyimpanan data ini harus dilampirkan ke mesin yang ditentukan dalam permintaan.
    • URI_TITLE: kolom wajib untuk menentukan judul URI, yang ditampilkan di hasil penelusuran.
    • URI: kolom wajib untuk menentukan link URI tempat hasil penelusuran mengarahkan pengguna. URI ini tidak perlu disertakan dalam penyimpanan data.
    • URI_DESCRIPTION: kolom opsional untuk mendeskripsikan URI, yang ditampilkan di hasil penelusuran.
    • ENABLED_TRUE|FALSE: kolom boolean opsional untuk menunjukkan apakah kontrol promosi diaktifkan dan dilampirkan ke aplikasi. Saat menetapkan kolom ini ke false, kontrol penayangan promosi akan dinonaktifkan dan agar kontrol tersebut diterapkan, Anda harus memperbarui kontrol dengan mengaktifkannya, seperti yang dijelaskan pada langkah berikutnya. Untuk informasi selengkapnya, lihat promoteAction.

  3. Opsional: Untuk mengaktifkan atau menonaktifkan kontrol promosi setelah kontrol dibuat, panggil metode engines.control.patch.

    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/engines/APP_ID/controls/CONTROL_ID?updateMask=promoteAction.searchLinkPromotion.enabled" \
-d '{
"promoteAction": {
  "searchLinkPromotion": {
     "enabled": ENABLED_TRUE|FALSE,
  }
}
}'

Contoh

Saat Anda mengirim permintaan penelusuran ke aplikasi dengan kueri yang cocok dengan kueri atau ekspresi reguler kueri yang ditentukan untuk kontrol promosi, link yang dipromosikan akan muncul dalam respons.

Misalnya, Anda membuat kontrol promosi dengan konfigurasi berikut:

{
 "conditions": [
   {
     "queryTerms": [
       {
         "value": "artificial intelligence",
         "fullMatch": true
       }
     ]
   }
 ]"
 ...
 promoteAction": {
  "dataStore": "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/dataStores/basic-website-data-store" \
  "searchLinkPromotion": {
    "title": "What is AI?",
    "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
    "description": "Explain what is AI"
    "enabled": true
  }
 }
}

Kemudian, kirim permintaan penelusuran berikut:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/engines/basic-website-app/servingConfigs/default_search:search" \
  -d '{
"query": "artificial intelligence"
}'

Anda akan menerima respons JSON yang mirip dengan respons yang terpotong berikut. Responsnya berisi kolom searchLinkPromotions yang berisi link yang dipromosikan.

{
 "results": [...],
  "totalSize": 3,
  "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB",
  "guidedSearchResult": {},
  "summary": {},
  "searchLinkPromotions": [
    {
      "title": "What is AI?",
      "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
      "description": "Explain what is AI"
    }
  ]
}

Langkah berikutnya

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