設定搜尋的供應控制選項

放送控制項 (也稱為控制項) 會變更要求傳回結果時的預設放送方式。在資料儲存層級執行放送控制項。

舉例來說，控制項可以提高/降低搜尋結果排名、從傳回的結果中篩除項目、將字串彼此關聯為同義詞，或將結果重新導向至指定 URI。

本頁面說明搜尋應用程式的放送控制選項。如要瞭解如何搭配媒體建議使用放送控制選項，請參閱「建立及管理媒體放送設定」。

關於供應控制項

如要變更要求結果，請先建立放送控制項。然後，將該控制項附加至搜尋應用程式的供應設定。供應設定會設定用於產生供應時間結果 (例如搜尋結果或答案) 的中繼資料。只有當供應控制項附加至應用程式的供應設定時，才會影響應用程式放送的請求。

部分控制選項 (例如升幅控制選項) 依附於資料儲存區。如果從應用程式中移除資料儲存庫，系統也會從該應用程式中移除任何依附於資料儲存庫的控制項，並停用這些控制項，但不會刪除。

供應控制項類型

可用的放送控制項類型如下：

控管	說明	適用的裝置
提升控制力	變更傳回結果的順序	具備支援結構定義的資料儲存庫的搜尋應用程式，例如包含結構化資料的資料儲存庫、具備結構化資料的網站 (進階網站索引)、具備中繼資料的非結構化資料，或媒體資料
篩選器控制項	從傳回的結果中移除項目	具備支援結構定義的資料儲存庫的搜尋應用程式，例如包含結構化資料、網站 (進階網站索引)、含中繼資料的非結構化資料或媒體資料的資料儲存庫
同義詞控制項	將查詢彼此建立關聯	搜尋應用程式 (具備進階網站索引建立功能) 搭配結構化、非結構化或媒體資料儲存庫
重新導向控制	重新導向至指定 URI	所有搜尋應用程式
宣傳控制項	針對查詢宣傳指定連結	所有搜尋應用程式

關於條件

建立控制項時，您可以選擇定義條件，決定何時套用控制項。條件是使用條件欄位定義的。可用的條件欄位如下：

• 查詢字詞 (queryTerms)：選用控制項，適用於搜尋特定查詢時。使用 queryTerms 條件時，如果 queryTerms 的值與 SearchRequest.query 中的字詞相符，就會套用控制項。只有在 Control.searchUseCase 設為 SOLUTION_TYPE_SEARCH 時，才能使用查詢字詞。單一 Control.condition 最多可指定 10 個不同的 queryTerms。如未指定任何查詢字詞，系統會忽略 queryTerms 欄位。

  如果是宣傳放送控制項，指定 queryRegex 條件時就無法指定 queryTerms，這只適用於基本網站搜尋。此外，如果指定 queryTerms，則基本網站搜尋的 fullMatch 欄位必須設為 true。如果是其他搜尋應用程式，則僅支援 queryTerms，且 fullMatch 可設為 true 或 false。

• 時間範圍 (activeTimeRange)：選用控制項，用於在指定時間範圍內發生要求時套用。並檢查收到要求的時間是否介於 activeTimeRange.startTime 和 activeTimeRange.endTime 之間。單一 Control.condition 最多可指定 10 個 activeTimeRange 範圍。如未指定 activeTimeRange 欄位，系統會忽略該欄位。

• queryRegex。僅適用於基本網站搜尋的宣傳放送控制項。這是選用條件，當查詢符合指定的規則運算式時，系統就會套用控制項。如果指定 queryTerms 條件，則無法指定此條件。

如果為控制項指定多個條件，則當兩種條件類型都符合時，系統會將控制項套用至搜尋要求。如果為相同條件指定多個值，只要其中一個值相符，該條件就會成立。

舉例來說，假設您指定了兩個查詢字詞，條件如下：

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

如果要求包含 SearchRequest.query="gShoe" 或 SearchRequest.query="gBoot"，條件就會成立，但如果包含 SearchRequest.query="gSandal" 或任何其他字串，條件就不會成立。

如未指定任何條件，系統一律會套用控管機制。

詳情請參閱 API 參考資料中的 Condition 欄位。

建立及附加放送量提升控制項

放送控制項會根據套用的條件，提升或降低結果的排名，藉此重新排序結果。如果文件符合加成條件，系統就會套用乘數，提高該文件的排名。

請按照下列操作說明建立放送量提升控制項。

控制台

如要使用 Google Cloud 控制台建立及附加升幅控制項，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「AI Applications」頁面。

   AI 應用程式

2. 選取要建立升級控制項的應用程式。

3. 在應用程式的總覽頁面中，確認您位於「系統總覽」分頁。

4. 在「信號」階段，按一下「升級/埋藏」圖塊。

5. 按一下「建立控制項」。

6. 在「為控制選項命名」中，輸入提高/降低排名控制選項的名稱，然後按一下「繼續」。

7. 在「設定規則範圍和影響」部分，定義要透過這個控制項觸發的動作：

   1. 從清單中選取資料儲存庫。如要將動作套用至多個資料存放區，請為每個資料存放區建立控制項。

   2. 如要篩選，請新增篩選條件。

      這是指文件必須符合的要求。只有在文件符合所有規定時，系統才會套用加成條件。否則不會有任何變更。如未指定篩選器，系統會將加成套用至資料存放區中的所有文件。

      如要瞭解如何編寫篩選運算式，請參閱「篩選自訂搜尋，找出結構化或非結構化資料」和「進階網站索引的語法」。

   3. 在「Boost/bury value」中，使用滑桿選取 [-1, 1] 範圍內的升級/埋沒值。滑桿會以 0.01 為單位移動。

   4. 按一下「繼續」。

8. 如要設定這項規則的啟用時間點 (選用)，請設定觸發控管的條件。如未設定任何條件，則此控制項隨時都會處於有效狀態：

   1. 新增部分比對查詢字詞。當查詢字詞部分相符時，這項控制項就會生效。

   2. 新增完全比對查詢字詞。只有在查詢字詞完全相符時，這項控制項才會生效。

   3. 如要新增有效時段，請按一下「新增時段」，然後設定「開始時間 1」和「結束時間 1」。這會定義條件處於有效狀態的視窗。最多可新增 10 個時間範圍。

   4. 按一下「繼續」。

9. 在「其他設定」中，選擇是否要啟用規則：

   1. 如不想在建立控管機制後立即啟用，請關閉「立即發布這項控管機制」。

   2. 按一下「繼續」。

10. 按一下「提交」。

REST

提升放送控制項是指具有 boostAction 的控制項。

請按照下列操作說明建立放送量提升控制項。

如需欄位詳細資料，請參閱 engines.controls API 參考資料和 engines.controls.create API 參考資料。

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

2. 執行下列 curl 指令來建立控制項。

   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"
    }
   }'

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的編號或 ID。
   • APP_ID：Vertex AI Search 應用程式的 ID。
   • CONTROL_ID：控制項的專屬 ID。 ID 可包含 [1-63] 個字元，可以是字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱應指出何時或為何要使用控制項。必須是長度介於 [1,128] 的 UTF-8 編碼字串。
   • USE_CASE：必須是 SEARCH_USE_CASE_SEARCH 或 SEARCH_USE_CASE_BROWSE。如果指定 SEARCH_USE_CASE_BROWSE，條件中就不能使用 Condition.queryTerms。
   • CONDITION：選用欄位，用於定義應套用控制項的時間。包含下列欄位：
     • VALUE：要比對的特定查詢值。這是長度為 [1, 5000] 的小寫 UTF-8 字串。如果 FULL_MATCH_1 為 true，這個欄位最多可包含三個以空格分隔的字詞。
     • FULL_MATCH：布林值，表示搜尋查詢是否需要與查詢字詞完全相符。設為 true 時，SearchRequest.query 必須與 queryTerm.value 完全相符。設為 false 時，SearchRequest.query 必須包含 queryTerm.value 做為子字串。
     • START_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的開始時間。
     • END_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的結尾。
   • BOOST_VALUE：範圍 [-1,1] 中的浮點數。如果值為負數，結果會遭到降級 (顯示在結果的較下方)。如果值為正數，結果就會獲得升級 (在結果中排名較高)。詳情請參閱 boostAction 的說明。
   • FILTER：指定文件必須符合哪些要求的字串。如果文件符合所有規定，系統就會套用加成。否則不會有任何變更。如果這個欄位留空，系統就會將提升效果套用至資料儲存庫中的所有文件。如要瞭解篩選語法，請參閱「篩選運算式語法」和「進階網站索引語法」。如需可在篩選器中使用的清單鍵屬性欄位，請參閱「支援篩選的鍵屬性」。
   • DATA_STORE_RESOURCE_PATH：資料存放區的完整資源路徑，該存放區的文件應由這項控制項提升。完整資源路徑的格式為 projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID。這個資料儲存庫必須附加至要求中指定的引擎。

3. 使用 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"]
   }'

   將 BOOST_ID_N 替換為您在上一個步驟中建立的控制項 ID。

建立及附加篩選器放送控制項

放送控制篩選器會依據特定條件或規則進行篩選。舉例來說，在飯店網站上，您可以套用篩選器，只顯示每晚價格低於 $175 美元的寵物友善飯店。(price < 175 AND petfriendly = "true")

篩選器服務控制項定義為具有 filterAction 的控制項。

請按照下列操作說明建立篩選器放送控制選項。

如需欄位詳細資料，請參閱 engines.controls API 參考資料和 engines.controls.create API 參考資料。

控制台

如要使用 Google Cloud 控制台建立及附加篩選器控制項，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「AI Applications」頁面。

   AI 應用程式

2. 選取要建立宣傳控制項的應用程式。

3. 在應用程式的總覽頁面中，確認您位於「系統總覽」分頁。

4. 在「信號」階段，按一下「篩選器」圖塊。

5. 按一下「建立控制項」。

6. 在「為控制項命名」中，輸入篩選器控制項的名稱，然後按一下「繼續」。

7. 在「規則範圍和影響」部分，設定下列項目：

   1. 從清單中選取要附加這個篩選器控制項的資料儲存庫。如要對多個資料儲存庫套用動作，請為每個資料儲存庫建立控管。

   2. 如果是篩選器，請指定規則要尋找的項目。您可以使用 AND、OR、NOT 組合搜尋字詞，並使用 () 將字詞分組。如要搜尋完全符合詞組的項目，請使用半形引號 ""。例如：status: "open" AND priority:"P1"。

      如要瞭解如何編寫篩選運算式，請參閱「篩選結構化或非結構化資料的自訂搜尋」和「進階網站索引的語法」。

   3. 按一下「繼續」。

8. 在「選用：這項規則的啟用時間點」部分，定義要透過這個控制項觸發的動作。如未設定任何條件，控制項就會一律發揮作用：

   1. 新增部分比對查詢字詞。當查詢字詞部分相符時，這項控制項就會生效。

   2. 新增完全比對查詢字詞。只有在查詢字詞完全相符時，這項控管功能才會生效。

   3. 如要新增有效時段，請按一下「新增時段」，然後設定「開始時間 1」和「結束時間 1」。這會定義條件處於有效狀態的視窗。最多可新增 10 個時間範圍。

   4. 按一下「繼續」。

9. 在「其他設定」中，選擇是否要啟用規則：

   1. 如不想在建立這項控管機制後立即啟用，請關閉「立即發布這項控管機制」。

   2. 按一下「繼續」。

10. 按一下「提交」。

REST

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

2. 執行下列 curl 指令來建立控制項。

   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"
    }
   }'

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的編號或 ID。
   • APP_ID：Vertex AI Search 應用程式的 ID。
   • CONTROL_ID：控制項的專屬 ID。 ID 可包含 [1-63] 個字元，可以是字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱應指出何時或為何要使用控制項。必須是長度介於 [1,128] 的 UTF-8 編碼字串。
   • USE_CASE：必須是 SEARCH_USE_CASE_SEARCH 或 SEARCH_USE_CASE_BROWSE。如果指定 SEARCH_USE_CASE_BROWSE，條件中就不能使用 Condition.queryTerms。
   • CONDITION：選用欄位，用於定義應套用控制項的時間。包含下列欄位：
     • VALUE：要比對的特定查詢值。這是長度為 [1, 5000] 的小寫 UTF-8 字串。如果 FULL_MATCH_1 為 true，這個欄位最多可包含三個以空格分隔的字詞。
     • FULL_MATCH：布林值，表示搜尋查詢是否需要與查詢字詞完全相符。設為 true 時，SearchRequest.query 必須與 queryTerm.value 完全相符。設為 false 時，SearchRequest.query 必須包含 queryTerm.value 做為子字串。
     • START_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的開始時間。
     • END_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的結尾。

   • FILTER：指定文件必須符合哪些要求的字串。如果文件符合所有規定，就會在結果中傳回。否則，文件不會出現在結果中。

     詳情請參閱「filterAction」。如要瞭解篩選語法，請參閱「篩選運算式語法」和「進階網站索引語法」。

     注意： 文件欄位 title 無法篩選。

3. 使用 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"]
   }'

   將 FILTER_ID_N 替換為您在上一個步驟中建立的控制項 ID。

建立及附加同義字放送控制項

同義字放送控制項是指具有 synonymsAction 的控制項。

請按照下列操作說明建立同義字放送控制項。

如需欄位詳細資料，請參閱 engines.controls API 參考資料和 engines.controls.create API 參考資料。

控制台

如要使用 Google Cloud 控制台建立及附加同義字控制項，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「AI Applications」頁面。

   AI 應用程式

2. 選取要建立同義字控制項的應用程式。

3. 在應用程式的總覽頁面中，確認您位於「系統總覽」分頁。

4. 在「準備」階段，按一下「同義詞」圖塊。

5. 按一下「建立控制項」。

6. 在「為控制項命名」部分輸入同義字控制項的名稱，然後按一下「繼續」。

7. 「規則範圍和影響」：

   1. 輸入要納入控制項的同義字。舉例來說，請先輸入「貓」，然後按下 Enter 鍵 (而非逗號)，再輸入「貓科動物」。

   2. 輸入同義字後，按一下「繼續」。

8. 在「選用：這項規則的啟用時間點」部分，定義要透過這個控制項觸發的動作。如未設定任何條件，控制項就會一律發揮作用：

   1. 如要新增有效時段，請按一下「新增時段」，然後設定「開始時間 1」和「結束時間 1」。這會定義條件處於有效狀態的視窗。最多可新增 10 個時間範圍。

   2. 按一下「繼續」。

9. 在「其他設定」中，選擇是否要啟用規則：

   1. 如不想在建立這項控管機制後立即啟用，請關閉「立即發布這項控管機制」。

   2. 按一下「繼續」。

10. 按一下「提交」。

REST

1. 執行下列 curl 指令來建立控制項。

   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"]
    }
   }'

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的編號或 ID。
   • APP_ID：Vertex AI Search 應用程式的 ID。
   • CONTROL_ID：控制項的專屬 ID。 ID 可包含 [1-63] 個字元，可以是字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱應指出何時或為何要使用控制項。必須是長度介於 [1,128] 的 UTF-8 編碼字串。
   • USE_CASE：必須是 SEARCH_USE_CASE_SEARCH 或 SEARCH_USE_CASE_BROWSE。如果指定 SEARCH_USE_CASE_BROWSE，條件中就不能使用 Condition.queryTerms。
   • CONDITION：選用欄位，用於定義應套用控制項的時間。包含下列欄位：
     • VALUE：要比對的特定查詢值。這是長度為 [1, 5000] 的小寫 UTF-8 字串。如果 FULL_MATCH_1 為 true，這個欄位最多可包含三個以空格分隔的字詞。
     • FULL_MATCH：布林值，表示搜尋查詢是否需要與查詢字詞完全相符。設為 true 時，SearchRequest.query 必須與 queryTerm.value 完全相符。設為 false 時，SearchRequest.query 必須包含 queryTerm.value 做為子字串。
     • START_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的開始時間。
     • END_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的結尾。
   • SYNONYMS_N：相關字串清單，可讓每個字串顯示類似結果的機率更高。雖然搜尋同義字時，您很可能會得到類似的結果，但搜尋每個同義字時，您可能無法取得所有相關同義字的所有相關結果。您至少須指定兩個同義字，最多可指定 100 個同義字。每個同義詞都必須採用 UTF-8 編碼，且為小寫。字串不得重複。舉例來說，您可以將「Pixel」、「Android 手機」和「Google 手機」新增為同義詞。詳情請參閱「synonymsAction」。

2. 使用 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"]
   }'

   將 SYNONYMS_ID_N 替換為您在上一個步驟中建立的控制項 ID。

建立並附加重新導向供應控制項

重新導向放送控制項可將使用者重新導向至提供的 URI。重新導向控制項定義為具有 redirectAction 的控制項。

請按照下列操作說明建立重新導向供應控制項。

如需欄位詳細資料，請參閱 engines.controls API 參考資料和 engines.controls.create API 參考資料。

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

2. 執行下列 curl 指令來建立控制項。

   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"
    }
   }'

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的編號或 ID。
   • APP_ID：Vertex AI Search 應用程式的 ID。
   • CONTROL_ID：控制項的專屬 ID。 ID 可包含 [1-63] 個字元，可以是字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱應指出何時或為何要使用控制項。必須是長度介於 [1,128] 的 UTF-8 編碼字串。
   • USE_CASE：必須是 SEARCH_USE_CASE_SEARCH 或 SEARCH_USE_CASE_BROWSE。如果指定 SEARCH_USE_CASE_BROWSE，條件中就不能使用 Condition.queryTerms。
   • CONDITION：選用欄位，用於定義應套用控制項的時間。包含下列欄位：
     • VALUE：要比對的特定查詢值。這是長度為 [1, 5000] 的小寫 UTF-8 字串。如果 FULL_MATCH_1 為 true，這個欄位最多可包含三個以空格分隔的字詞。
     • FULL_MATCH：布林值，表示搜尋查詢是否需要與查詢字詞完全相符。設為 true 時，SearchRequest.query 必須與 queryTerm.value 完全相符。設為 false 時，SearchRequest.query 必須包含 queryTerm.value 做為子字串。
     • START_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的開始時間。
     • END_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的結尾。
   • REDIRECT_URI_N：重新導向的 URI。長度上限為 2000 個半形字元。舉例來說，如果查詢字詞的值是「支援」，您可以將重新導向設為技術支援頁面，而不是傳回 (或無法傳回)「支援」的搜尋結果。在本範例中，重新導向 URI 會變成 "https://www.example.com/support"。詳情請參閱「redirectAction」。

3. 使用 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"]
   }'

   將 REDIRECT_ID_N 替換為您在上一個步驟中建立的控制項 ID。

建立及附加宣傳放送控制項

宣傳供應控制項可讓您將連結顯示為宣傳結果，適用於下列類型的搜尋資料儲存庫：

• 提供基本網站搜尋功能的網站資料儲存庫：這類資料儲存庫不需要將宣傳控制項附加至應用程式的服務設定。建立並啟用宣傳控制項後，宣傳控制項就會啟動。您可以啟用或停用宣傳控制項，藉此開啟或關閉這項功能。

• 包含結構化和非結構化資料的資料儲存庫、具備進階網站索引建立功能的網站資料，以及混合式搜尋應用程式：對於這些資料儲存庫，您需要將升級控制項附加至服務設定。

宣傳控制項是使用 promoteAction 定義。

如要順利建立升級控制項，建立要求中必須包含下列其中一個欄位：

• queryTerms：如果您指定 queryRegex 條件 (僅適用於基本網站搜尋)，就無法指定這項條件。如要進行基本網站搜尋，如果指定 queryTerms，則 fullMatch 必須設為 true。如果是其他搜尋應用程式，則只支援 queryTerms，且 fullMatch 可設為 true 或 false。
• queryRegex。僅適用於基本網站搜尋的宣傳放送控制項。如果查詢符合指定的規則運算式，這項條件就會套用控制項。如果指定 queryTerms 條件，則無法指定此條件。

也就是說，如要進行基本網站搜尋，您必須指定 queryTerms 欄位，並將 fullMatch 設為 true，或是指定 queryRegex 欄位。如要進行其他類型的搜尋，請指定 queryTerms 欄位，並將 fullMatch 設為 true 或 false。

請按照下列操作說明建立宣傳放送控制項。

如需欄位詳細資料，請參閱 engines.controls API 參考資料和 engines.controls.create API 參考資料。

控制台

如要使用 Google Cloud 控制台，為基本網站搜尋應用程式建立及附加升級控制項，請按照下列步驟操作。如要為其他應用程式類型建立升級控制項，請按照「REST」分頁中的指示操作。

1. 前往 Google Cloud 控制台的「AI Applications」頁面。

   AI 應用程式

2. 選取要建立篩選器控制項的應用程式。

3. 在應用程式的總覽頁面中，確認您位於「系統總覽」分頁。

4. 在「信號」階段，按一下「升級」圖塊。

5. 按一下「建立控制項」。

6. 在「為控制選項命名」中，輸入宣傳控制選項的名稱，然後按一下「繼續」。

7. 在「規則範圍和影響」部分，設定下列項目：

   1. 從清單中選取要附加這個篩選器控制項的資料儲存庫。如要對多個資料儲存庫套用動作，請為每個資料儲存庫建立控管。

   2. 輸入宣傳標題，例如「觀看最新影片」。

   3. 輸入宣傳網址，例如影片位置。

   4. 輸入宣傳圖片網址，例如縮圖或螢幕截圖。

   5. 輸入簡短的宣傳說明，例如影片內容。 最多 250 個半形字元。

8. 如要設定「選用：這項規則的啟用時間點」，請定義要透過這個控制項觸發的動作。如未設定任何條件，則此控制項隨時都會處於有效狀態：

   1. 新增完全比對查詢字詞。只有在查詢字詞完全相符時，這項控制項才會生效。

   2. 如要新增有效時段，請按一下「新增時段」，然後設定「開始時間 1」和「結束時間 1」。這會定義條件處於有效狀態的視窗。最多可新增 10 個時間範圍。

   3. 按一下「繼續」。

9. 按一下「提交」。

REST

1. 執行下列 curl 指令來建立控制項。

   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": {
        "document": "DOCUMENT_RESOURCE_PATH",
        "title": "TITLE",
        "uri": "URI",
        "description": "DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE,
     }
    }
   }'

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的編號或 ID。
   • APP_ID：Vertex AI Search 應用程式的 ID。
   • CONTROL_ID：控制項的專屬 ID。 ID 可包含 [1-63] 個字元，可以是字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱應指出何時或為何要使用控制項。必須是長度介於 [1,128] 的 UTF-8 編碼字串。
   • USE_CASE：必須是 SEARCH_USE_CASE_SEARCH 或 SEARCH_USE_CASE_BROWSE。如果指定 SEARCH_USE_CASE_BROWSE，條件中就不能使用 Condition.queryTerms。
   • Condition：選用物件，用於定義何時應套用控制項。包含下列欄位：
     • queryTerms：無法與 queryRegex 欄位搭配使用。
       • VALUE：要比對的特定查詢值。這是長度為 [1, 5000] 的小寫 UTF-8 字串。
     • activeTimeRange：
       • START_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的開始時間。
       • END_TIMESTAMP：RFC 3339 世界標準時間「Zulu」格式的時間戳記，表示時間範圍的結尾。
     • queryRegex：僅適用於具備基本網站搜尋功能的資料儲存空間。這個欄位無法與 queryTerms 欄位搭配使用。
       • VALUE_REGEX：用來比對查詢的規則運算式。
   • DATA_STORE_RESOURCE_PATH：資料存放區的完整資源路徑，該存放區的搜尋結果包含宣傳的網址。完整資源路徑的格式為 projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID。這個資料儲存庫必須附加至要求中指定的引擎。
   • DOCUMENT_RESOURCE_PATH：用於指定要升級的文件資源路徑的欄位：
     • 如果是含有結構化和非結構化資料的搜尋資料儲存庫，您必須在 DOCUMENT_RESOURCE_PATH 欄位中提供文件資源路徑，或在 URI 欄位中提供 URI，或同時提供兩者。完整資源路徑的格式為 projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID。
     • 如果是網站資料儲存庫，這個欄位必須未設定，並改為設定 URI 欄位。
   • TITLE：必要欄位，用於指定要宣傳的文件或網頁標題。這個標題會顯示在搜尋結果中。
   • URI：必要欄位，用於指定搜尋結果將使用者導向的 URI 連結。這個 URI 不一定要納入資料儲存庫。
     • 如果是含有結構化和非結構化資料的搜尋資料儲存庫，您必須在 DOCUMENT_RESOURCE_PATH 欄位中提供文件資源路徑，或在 URI 欄位中提供 URI，或同時提供兩者。
     • 如果是網站資料儲存庫，這是必填欄位，請務必設定。
   • DESCRIPTION：選用欄位，用於說明要宣傳的文件或網頁，並顯示在搜尋結果中。
   • ENABLED_TRUE|FALSE：選用的布林值欄位，用來指出宣傳控制選項是否已開啟並附加至應用程式。這個欄位僅適用於具有基本網站搜尋功能的網站資料儲存庫。將這個欄位設為 false 時，宣傳活動放送控制項會關閉，且您必須按照下一個步驟的說明啟用控制項，控制項才會生效。詳情請參閱「promoteAction」。

   回應

   您應該會收到如下的 JSON 回覆：

   {
    "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls/PROMOTE_CONTROL_ID",
    "displayName": "PROMOTE_CONTROL_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "conditions": [
      {
        "queryTerms": [
          {
            "value": "VALUE",
            "fullMatch": true
          }
        ]
      }
    ],
    "useCases": [
      "SEARCH_USE_CASE_SEARCH"
    ],
    "promoteAction": {
      "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID",
      "searchLinkPromotion": {
        "title": "URI_TITLE",
        "uri": "URI",
        "description": "URI_DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE
     }
    }
   }
   

2. 除了基本網站搜尋以外，所有搜尋應用程式都必須使用 engines.servingConfigs.patch 方法，將控制項附加至應用程式的供應設定。在下列要求中附加 promoteControlIds 的順序，就是系統傳回的升級結果順序。

   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"]
   }'

   將 PROMOTE_ID_N 替換為您在上一個步驟中建立的控制項 ID。

3. 選用：如要進行基本網站搜尋，不必將控制項附加至應用程式的服務設定。不過，如果是基本網站搜尋，您可以在建立升級控制項後開啟或關閉該控制項，並呼叫 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,
     }
   }
   }'

範例

當您向應用程式傳送搜尋要求，且查詢內容符合宣傳控制項指定的查詢或查詢規則運算式時，回應中就會顯示宣傳連結。

舉例來說，假設您在基本網站搜尋的資料儲存庫中，使用下列設定建立升級控制項：

{
 "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
  }
 }
}

接著，您會傳送下列 search 要求：

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"
}'

您應該會收到類似以下截斷式回應的 JSON 回應。 回應包含 searchLinkPromotions 欄位，內含宣傳連結。

{
 "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"
    }
  ]
}

修改供應控制項

如要修改控制項的設定，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「AI Applications」頁面。

   AI 應用程式

2. 選取要修改控制選項的應用程式。

3. 在「系統總覽」分頁中，選取控制項所在的「準備」或「信號」階段。

4. 在應用程式控制項清單中，按一下要修改的控制項 ，然後按一下「編輯」。

5. 在「編輯控制項」窗格中編輯控制項：

   1. 如要啟用或停用控制項，請在應用程式篩選控制項清單中，按一下要啟用或停用控制項的 ，然後分別點選「啟用」或「停用」。

   2. 如要刪除控制項，請在應用程式控制項清單中，按一下要刪除的控制項的 ，然後按一下「刪除」。

後續步驟

• 如要瞭解供應控制項對自訂搜尋應用程式搜尋品質的影響，請評估搜尋品質。詳情請參閱評估搜尋品質。