設定供應控制項

供應控制項 (也稱為控制項) 會變更傳回結果時，系統處理要求的預設行為。放送控制項 會在資料儲存庫層級運作。

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

關於供應控制項

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

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

供應控制項類型

可用的供應控制項類型如下：

控制項	說明	適用的裝置
提升控制力	變更傳回結果的順序	資料儲存庫支援結構定義的搜尋應用程式，例如包含結構化資料或含中繼資料的非結構化資料的資料儲存庫
篩選器控制項	從傳回的結果中移除項目	資料儲存庫支援結構定義的搜尋應用程式，例如包含結構化資料或含中繼資料的非結構化資料的資料儲存庫
同義詞控制項	將查詢互相建立關聯	使用結構化或非結構化資料儲存庫的搜尋應用程式
重新導向控制項	重新導向至指定 URI	所有搜尋應用程式
宣傳控制項	為查詢宣傳指定連結	使用結構化或非結構化資料儲存庫的搜尋應用程式

關於條件

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

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

  如要成功建立提升控制項，您必須指定 queryTerms 欄位，並將 fullMatch 設為 true 或 false。

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

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

舉例來說，假設有以下條件，其中指定了兩個查詢字詞：

"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 控制台的「Gemini Enterprise」頁面。

   Gemini Enterprise

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

3. 依序點選「設定」和「控制項」分頁標籤。

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

5. 在「您想執行什麼操作？」部分，指定控制項名稱和類型：

   1. 在「控制項名稱」部分，輸入提高/降低排名控制項的名稱。

   2. 在「Control Type」(控制項類型) 部分，選取「Boost/bury」(提高/降低排名)。

   3. 按一下「繼續」。

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

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

   2. 在「篩選器」部分新增篩選器。

      這是指文件必須符合的要求。只有在文件符合所有條件時，系統才會套用調升條件。否則不會有任何變更。如未指定篩選器，則會對資料儲存庫中的所有文件套用提升。

      如要瞭解篩選語法，請參閱「篩選運算式語法」。

   3. 在「Boost/bury value」(提高/降低值)，使用滑桿選取 [-1, 1] 範圍內的提高/降低值。滑桿會以 0.01 為單位移動。

   4. 按一下「繼續」。

7. 在「選用：這項規則的啟用時間點」部分，設定觸發控制項的條件。如未設定條件，控制項就會一律發揮作用：

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

   2. 新增完全比對查詢字詞。如果這些查詢字詞完全相符，控制項就會生效。

   3. 如要新增有效時間範圍，請按一下「Add time range」(新增時間範圍)，然後設定「Start Time 1」(開始時間 1) 和「End Time 1」(結束時間 1)。這會定義條件有效時的視窗。最多可新增 10 個時間範圍。

   4. 按一下「繼續」。

8. 在「其他設定」部分，選擇是否要啟用規則：

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

   2. 按一下「繼續」。

9. 按一下「提交」。

REST

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

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

如要瞭解欄位詳情，請參閱 engines.controls API 參考資料和 engines.controls.create API 參考資料。

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

   1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

      前往「應用程式」

   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：應用程式 ID。
   • CONTROL_ID：控制項的專屬 ID。ID 可包含 [1-63] 個字元，包括英文字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱要指出何時或為何使用控制項。必須是 UTF-8 編碼字串，長度介於 1 至 128 個字元。
   • 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 UTC「Zulu」格式的時間戳記，表示日期範圍的起點。
     • END_TIMESTAMP：採用 RFC 3339 UTC「Zulu」格式的時間戳記，表示時間範圍的結束時間。
   • BOOST_VALUE：範圍 [-1,1] 內的浮點數。如果值為負數，結果會遭到降級 (顯示在結果的較下方)。如果值為正數，結果就會獲得升級 (在結果中排名較高)。詳情請參閱 boostAction 的說明。
   • FILTER：指定文件必須符合哪些要求的字串。如果文件符合所有規定，系統就會套用加成。否則不會有任何變更。如果這個欄位空白，系統就會將加成套用至資料儲存庫中的所有文件。如要瞭解篩選語法，請參閱「篩選運算式語法」。注意：無法篩選文件欄位 title。
   • 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。

建立及附加篩選器供應控制項

篩選器供應控制項是指具有 filterAction 的控制項。

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

控制台

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

1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

   Gemini Enterprise

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

3. 按一下「設定」，然後按一下「控制」分頁標籤。

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

5. 在「你想要做什麼？」部分，指定控制項名稱和類型：

   1. 在「控制項名稱」部分，輸入篩選器控制項的名稱。

   2. 在「控制項類型」部分，選取「篩選器」。

   3. 按一下「繼續」。

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

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

   2. 在「篩選器」部分，指定規則要尋找的項目。您可以使用 AND、OR NOT 組合搜尋字詞，並使用 () 將字詞分組。如要搜尋確切詞組，請使用引號 ("")。例如：category: "electronics" AND price < 500, status: "open" AND priority:"P1"。

      如要瞭解篩選語法，請參閱「篩選運算式語法」。

   3. 按一下「繼續」。

7. 在「選用：這項規則的啟用時間點」部分，設定觸發控制項的條件。如未設定條件，控制項就會一律發揮作用：

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

   2. 新增完全比對查詢字詞。如果這些查詢字詞完全相符，控制項就會生效。

   3. 如要新增有效時間範圍，請按一下「Add time range」(新增時間範圍)，然後設定「Start Time 1」(開始時間 1) 和「End Time 1」(結束時間 1)。這會定義條件有效時的視窗。最多可新增 10 個時間範圍。

   4. 按一下「繼續」。

8. 在「其他設定」部分，選擇是否要啟用規則：

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

   2. 按一下「繼續」。

9. 按一下「提交」。

REST

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

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

   1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

      前往「應用程式」

   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：應用程式 ID。
   • CONTROL_ID：控制項的專屬 ID。ID 可包含 [1-63] 個字元，包括英文字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱要指出何時或為何使用控制項。必須是 UTF-8 編碼字串，長度介於 1 至 128 個字元。
   • 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 UTC「Zulu」格式的時間戳記，表示日期範圍的起點。
     • END_TIMESTAMP：採用 RFC 3339 UTC「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 的控制項。

請按照下列操作說明，建立同義詞供應控制項。

控制台

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

1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

   Gemini Enterprise

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

3. 依序點選「設定」和「控制項」分頁標籤。

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

5. 在「你想要做什麼？」部分，指定控制項名稱和類型：

   1. 在「為控制項命名」中，輸入同義字控制項的名稱。

   2. 在「控制項類型」部分，選取「同義字」。

   3. 按一下「繼續」。

6. 在「Set Rule Scope & Impact」(設定規則範圍和影響) 部分，定義要透過這個控制項觸發的動作：

   1. 輸入要納入控制項的同義詞。舉例來說，請先輸入「cats」，然後按 Enter 鍵 (而非逗號)，再輸入「feline」。

   2. 按一下「繼續」。

7. 在「選用：這項規則的啟用時間點」部分，設定觸發控制項的條件。如未設定條件，控制項就會一律發揮作用：

   1. 如要新增有效時間範圍，請按一下「Add time range」(新增時間範圍)，然後設定「Start Time 1」(開始時間 1) 和「End Time 1」(結束時間 1)。這會定義條件生效的時間範圍。最多可新增 10 個時間範圍。

   2. 按一下「繼續」。

8. 在「其他設定」部分，選擇是否要啟用規則：

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

   2. 按一下「繼續」。

9. 按一下「提交」。

REST

如要瞭解欄位詳情，請參閱 engines.controls API 參考資料和 engines.controls.create API 參考資料。

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

   1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

      前往「應用程式」

   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"
       }
     ]
   },
   "synonymsAction": {
     "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
    }
   }'

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的編號或 ID。
   • APP_ID：應用程式 ID。
   • CONTROL_ID：控制項的專屬 ID。ID 可包含 [1-63] 個字元，包括英文字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱要指出何時或為何使用控制項。必須是 UTF-8 編碼字串，長度介於 1 至 128 個字元。
   • 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 UTC「Zulu」格式的時間戳記，表示日期範圍的起點。
     • END_TIMESTAMP：採用 RFC 3339 UTC「Zulu」格式的時間戳記，表示時間範圍的結束時間。
   • SYNONYMS_N：相關聯的字串清單，可讓每個字串顯示類似結果的機率更高。雖然您更有可能取得類似的結果，但搜尋每個同義詞項目時，可能不會收到所有相關同義詞的所有相關結果。你必須指定至少兩個同義字，最多可指定 100 個同義字。每個同義字都必須採用 UTF-8 編碼，且為小寫。不得重複。例如，您可以將「像素」、「android phone」和「Google 手機」新增為同義詞。詳情請參閱「synonymsAction」。

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=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 控制台的「Gemini Enterprise」頁面。

      前往「應用程式」

   2. 在「Apps」(應用程式) 頁面中，找出應用程式名稱，然後從「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：應用程式 ID。
   • CONTROL_ID：控制項的專屬 ID。ID 可包含 [1-63] 個字元，包括英文字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱要指出何時或為何使用控制項。必須是 UTF-8 編碼字串，長度介於 1 至 128 個字元。
   • 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 UTC「Zulu」格式的時間戳記，表示日期範圍的起點。
     • END_TIMESTAMP：採用 RFC 3339 UTC「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 欄位，並將 fullMatch 設為 true 或 false。

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

控制台

如要建立提升供應控制項，請按照「REST」分頁中的指示操作。

REST

如要瞭解欄位詳情，請參閱 engines.controls API 參考資料和 engines.controls.create API 參考資料。

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

   1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

      前往「應用程式」

   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"
       }
     ]
   },
   "promoteAction": {
     "dataStore": "DATA_STORE_RESOURCE_PATH",
     "searchLinkPromotion": {
        "document": "DOCUMENT_RESOURCE_PATH",
        "title": "TITLE",
        "uri": "URI",
        "description": "URI_DESCRIPTION"
     }
    }
   }'

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的編號或 ID。
   • APP_ID：應用程式 ID。
   • CONTROL_ID：控制項的專屬 ID。ID 可包含 [1-63] 個字元，包括英文字母、數字、連字號和底線。
   • DISPLAY_NAME：控制項的人類可讀名稱。Google 建議這個名稱要指出何時或為何使用控制項。必須是 UTF-8 編碼字串，長度介於 1 至 128 個字元。
   • USE_CASE：必須是 SEARCH_USE_CASE_SEARCH 或 SEARCH_USE_CASE_BROWSE。如果指定 SEARCH_USE_CASE_BROWSE，則條件中無法使用 Condition.queryTerms。
   • CONDITION：選用欄位，定義應套用控制項的時間。包含下列欄位：
     • VALUE：要比對的特定查詢值。這是長度為 [1, 5000] 的小寫 UTF-8 字串。
     • FULL_MATCH：布林值，表示查詢字詞是否必須完全相符。
     • START_TIMESTAMP：採用 RFC 3339 UTC「Zulu」格式的時間戳記，表示日期範圍的起點。
     • END_TIMESTAMP：採用 RFC 3339 UTC「Zulu」格式的時間戳記，表示時間範圍的結束時間。
   • DATA_STORE_RESOURCE_PATH：資料儲存庫的完整資源路徑，該儲存庫的搜尋結果包含促銷活動網址。完整資源路徑的格式為 projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID。這個資料儲存庫必須附加至要求中指定的引擎。

   • DOCUMENT_RESOURCE_PATH：用於指定要宣傳的文件資源路徑的欄位。您必須在 DOCUMENT_RESOURCE_PATH 欄位中提供文件 ID、在 URI 欄位中提供 URI，或同時提供兩者。

     完整資源路徑的格式為：projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID。

   • TITLE：必填欄位，用於指定要宣傳的文件或網頁標題。這個標題會顯示在搜尋結果中。

   • URI：這個欄位用於指定搜尋結果將使用者導向的 URI。您必須在 DOCUMENT_RESOURCE_PATH 欄位中提供文件 ID、在 URI 欄位中提供 URI，或同時提供兩者。

   • URI_DESCRIPTION：選用欄位，用於說明 URI，並顯示在搜尋結果中。

   回應

   您應該會收到如下的 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
     }
    }
   }
   

   回應中包含宣傳控制項 ID，您需要將宣傳控制項附加至搜尋應用程式。

3. 使用 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。

修改供應控制項

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

1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

   Gemini Enterprise

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

3. 依序點選「設定」和「控制項」分頁標籤。

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

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

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

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

後續步驟

• 如要瞭解放送控制項對應用程式搜尋品質的影響，請評估搜尋品質。