Mengonfigurasi kontrol penyajian

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

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

Tentang kontrol inferensi

Untuk mengubah hasil permintaan, buat kontrol penayangan terlebih dahulu. Kemudian, lampirkan kontrol tersebut ke konfigurasi penayangan aplikasi. Konfigurasi penayangan mengonfigurasi metadata yang digunakan untuk membuat 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 peningkat, memiliki dependensi pada penyimpanan data. Jika penyimpanan data dihapus dari aplikasi, semua kontrol 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 peningkatan Mengubah urutan hasil yang ditampilkan Menelusuri aplikasi dengan penyimpanan data yang mendukung skema, seperti penyimpanan data yang berisi data terstruktur atau data tidak terstruktur dengan metadata
Kontrol filter Menghapus entri dari hasil yang ditampilkan Menelusuri aplikasi dengan penyimpanan data yang mendukung skema, seperti penyimpanan data yang berisi data terstruktur atau data tidak terstruktur dengan metadata
Kontrol sinonim Mengaitkan kueri satu sama lain Menelusuri aplikasi dengan penyimpanan data terstruktur atau tidak terstruktur
Kontrol pengalihan Mengarahkan ke URI yang ditentukan Semua aplikasi penelusuran
Kontrol promosi Mempromosikan link tertentu untuk kueri Menelusuri aplikasi dengan penyimpanan data terstruktur atau tidak terstruktur

Tentang kondisi

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

  • queryTerms. Kontrol opsional yang diterapkan saat kueri tertentu dicari. Jika kondisi queryTerms digunakan, kontrol diterapkan saat nilai queryTerms cocok dengan istilah di SearchRequest.query. Istilah kueri hanya dapat digunakan jika Control.searchUseCase ditetapkan sebagai SOLUTION_TYPE_SEARCH. Hingga 10 queryTerms berbeda dapat ditentukan pada satu Control.condition. Jika tidak ada istilah kueri yang ditentukan, kolom queryTerms akan diabaikan.

    Agar berhasil membuat kontrol promosi, Anda harus menentukan kolom queryTerms dengan fullMatch yang ditetapkan ke true atau false.

  • activeTimeRange. Kontrol opsional yang diterapkan saat permintaan terjadi dalam rentang waktu yang ditentukan. Kebijakan ini memeriksa bahwa waktu permintaan diterima adalah antara activeTimeRange.startTime dan activeTimeRange.endTime. Hingga 10 rentang activeTimeRange dapat ditentukan pada satu Control.condition. Jika kolomactiveTimeRange tidak ditentukan, kolom akan diabaikan.

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 satu nilai yang harus 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 peningkat

Kontrol penayangan peningkat didefinisikan sebagai kontrol dengan boostAction.

Gunakan petunjuk berikut untuk membuat kontrol penayangan peningkat.

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 Gemini Enterprise.

      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.
    • 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 kontrol harus digunakan. 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 paling banyak tiga istilah yang dipisahkan spasi.
      • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika disetel ke true, SearchRequest.query harus cocok sepenuhnya dengan queryTerm.value. Jika disetel 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 RFC 3339 UTC "Zulu" untuk menunjukkan akhir rentang waktu.
    • BOOST_VALUE: bilangan floating point dalam rentang [-1,1]. Jika nilainya negatif, hasil akan diturunkan (hasil muncul lebih rendah dalam hasil). Jika nilainya positif, hasil akan dipromosikan (muncul lebih tinggi dalam hasil). Untuk informasi selengkapnya, lihat boostAction.
    • FILTER: string yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Jika dokumen memenuhi semua persyaratan, maka peningkatan diterapkan. Jika tidak, tidak ada perubahan. Jika kolom ini kosong, maka peningkatan 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 ditingkatkan 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 pada 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 Gemini Enterprise.

      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.
    • 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 kontrol harus digunakan. 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 paling banyak tiga istilah yang dipisahkan spasi.
      • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika disetel ke true, SearchRequest.query harus cocok sepenuhnya dengan queryTerm.value. Jika disetel 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 RFC 3339 UTC "Zulu" untuk menunjukkan akhir rentang waktu.
    • FILTER: string yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Jika dokumen cocok dengan semua persyaratan, dokumen akan ditampilkan dalam hasil. Jika tidak, dokumen tidak ada dalam hasil. Untuk sintaksis pemfilteran, lihat Sintaksis ekspresi filter. Untuk mengetahui 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 pada 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 Gemini Enterprise.

      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.
    • 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 kontrol harus digunakan. 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 paling banyak tiga istilah yang dipisahkan spasi.
      • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika disetel ke true, SearchRequest.query harus cocok sepenuhnya dengan queryTerm.value. Jika disetel 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 RFC 3339 UTC "Zulu" untuk menunjukkan akhir rentang waktu.
    • SYNONYMS_N: daftar string yang terkait satu sama lain, sehingga masing-masing lebih cenderung menampilkan hasil yang serupa. Meskipun Anda cenderung mendapatkan hasil yang serupa, saat Anda menelusuri setiap entri sinonim, Anda mungkin tidak menerima semua hasil yang relevan untuk semua sinonim terkait. Anda harus menentukan minimal dua sinonim dan Anda dapat menentukan hingga 100 sinonim. Setiap sinonim harus berenkode UTF-8 dan dalam huruf kecil. Tidak boleh ada string duplikat. Misalnya, Anda dapat menambahkan "pixel", "ponsel android", dan "ponsel google" sebagai sinonim. Untuk mengetahui 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 pada 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 Gemini Enterprise.

      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.
    • 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 kontrol harus digunakan. 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 paling banyak tiga istilah yang dipisahkan spasi.
      • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika disetel ke true, SearchRequest.query harus cocok sepenuhnya dengan queryTerm.value. Jika disetel 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 RFC 3339 UTC "Zulu" 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 mengetahui 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 pada langkah sebelumnya.

Membuat dan melampirkan kontrol penayangan promosi

Kontrol penayangan promosi memungkinkan Anda menampilkan link sebagai hasil promosi. Kontrol ini tersedia untuk aplikasi penelusuran dengan penyimpanan data terstruktur atau tidak terstruktur dan aplikasi penelusuran gabungan.

Agar kontrol promosi diterapkan, Anda harus melampirkannya ke konfigurasi penayangan aplikasi.

Kontrol promosi ditentukan menggunakan promoteAction.

Agar berhasil membuat kontrol promosi, Anda harus menentukan kolom queryTerms dengan fullMatch yang ditetapkan ke true atau false.

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 Gemini Enterprise.

      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_TRUE|FALSE
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ],
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "document": "DOCUMENT_RESOURCE_PATH",
     "title": "TITLE",
     "uri": "URI",
     "description": "URI_DESCRIPTION",
  }
 }
}'

    Ganti kode berikut:

    • PROJECT_ID: nomor atau ID Google Cloud project Anda.
    • APP_ID: ID aplikasi.
    • 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 kontrol harus digunakan. 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:
        • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000].
        • FULL_MATCH_TRUE|FALSE: boolean untuk menunjukkan apakah istilah kueri harus cocok sepenuhnya.
      • activeTimeRange:
        • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
        • END_TIMESTAMP: stempel waktu dalam format RFC 3339 UTC "Zulu" untuk menunjukkan akhir rentang waktu.
    • DATA_STORE_RESOURCE_PATH: jalur resource lengkap 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.

    • DOCUMENT_RESOURCE_PATH: kolom untuk menentukan jalur resource dokumen yang akan dipromosikan. Anda harus memberikan ID dokumen di kolom DOCUMENT_RESOURCE_PATH, URI di kolom URI, atau keduanya.

      Format jalur resource lengkap adalah: projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.

    • TITLE: kolom wajib diisi untuk menentukan judul dokumen atau halaman web yang akan dipromosikan. Judul ini ditampilkan di hasil penelusuran.

    • URI: kolom untuk menentukan URI tempat hasil penelusuran mengarahkan pengguna. Anda harus memberikan ID dokumen di kolom DOCUMENT_RESOURCE_PATH, URI di kolom URI, atau keduanya.

    • URI_DESCRIPTION: kolom opsional untuk mendeskripsikan URI, yang ditampilkan dalam hasil penelusuran.

    Respons berisi ID kontrol promosi yang perlu Anda lampirkan kontrol promosi ke aplikasi penelusuran Anda.

  3. Lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch. Urutan saat Anda melampirkan promoteControlIds dalam permintaan berikut adalah urutan saat hasil promosi ditampilkan.

    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=promote_control_ids" \
-d '{
  "promoteControlIds": ["PROMOTE_ID_1", "PROMOTE_ID_2"]
}'

    Ganti PROMOTE_ID_N dengan ID kontrol yang Anda terima pada langkah sebelumnya.

Langkah berikutnya