此页面由 Cloud Translation API 翻译。

为搜索配置投放控制

投放控件（也称为控件）会更改返回结果时请求的默认投放行为。提供控制变量在数据存储区级层发挥作用。

例如，控件可以提升和掩埋结果、从返回的结果中过滤条目、将字符串彼此关联为同义词，或将结果重定向到指定的 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 控制台中，前往 AI Applications 页面。

AI 应用
选择要为其创建提升控制设置的应用。
在应用的概览页面上，选择信号阶段中列出的提升/埋没。
在信号页面上，点击创建控件。
在创建控制变量窗格中，执行以下操作：
1. 输入升推/降推控制的名称，然后点击继续。
2. 设置触发控制的以下条件。如果未配置任何条件，此控件将始终有效：
  1. 添加部分匹配的查询字词。当这些搜索字词部分匹配时，该控制设置会生效。
  2. 添加完全匹配的查询字词。当这些搜索字词完全匹配时，该控制功能才会生效。
  3. 如需添加有效的时间范围，请点击添加时间范围，然后设置开始时间 1 和结束时间 1。此属性用于定义条件处于有效状态的时间窗口。您最多可以添加 10 个时间范围。
  4. 点击继续。
3. 定义您要使用此控件触发的操作：
  1. 从列表中选择数据存储区。如果您希望将操作应用于多个数据存储区，请为每个数据存储区创建一个控制变量。
  2. 添加过滤条件。
    
    这是一个字符串，用于说明文档必须满足哪些要求。只有当文档满足所有要求时，才会应用提升条件。否则，不会有任何变化。如果您未指定过滤条件，则系统会将提升应用于数据存储区中的所有文档。
    
    如需了解如何编写过滤表达式，请参阅过滤表达式语法和过滤表达式示例。
  3. 使用滑块选择 [-1, 1] 范围内的提升/掩埋值。滑块以 0.01 为步长移动。
  4. 点击继续。
4. 如果您想在创建控件后立即应用，请开启立即发布此控件，然后点击继续。
点击提交。
如需修改控件的配置，请执行以下操作：
1. 在信号页面上，在应用的提升/埋没控件列表中，点击要修改的控件对应的，然后点击修改。
2. 在修改控件窗格中修改控件。
如需启用或停用某个控制项，请在 Signal 页面上，在应用的升推/降推控制项列表中，点击要启用或停用的控制项对应的，然后分别点击启用或停用。
如需删除控制变量，请在信号页面上，在应用的提升/埋没控制变量列表中，点击要删除的控制变量对应的，然后点击删除。

REST

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

按照以下说明创建提升服务控制变量。

如需了解字段详情，请参阅 engines.controls API 参考文档和 engines.controls.create API 参考文档。

查找应用 ID。如果您已拥有应用 ID，请跳到下一步。
1. 在 Google Cloud 控制台中，前往 AI Applications 页面。
  
  前往“应用”
2. 在应用页面上，找到应用的名称，并从 ID 列获取应用的 ID。
运行以下 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 可以包含 [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 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。此数据存储区必须附加到请求中指定的引擎。

使用 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 的控制。

按照以下说明创建过滤条件投放控制。

如需了解字段详情，请参阅 engines.controls API 参考文档和 engines.controls.create API 参考文档。

查找应用 ID。如果您已拥有应用 ID，请跳到下一步。
1. 在 Google Cloud 控制台中，前往 AI Applications 页面。
  
  前往“应用”
2. 在应用页面上，找到应用的名称，并从 ID 列获取应用的 ID。
运行以下 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 可以包含 [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 UTC“Zulu”格式的时间戳，用于指示时间范围的开始时间。
  - END_TIMESTAMP：采用 RFC 3339 UTC“Zulu”格式的时间戳，用于指示时间范围的结束时间。
- FILTER：一个字符串，用于说明文档必须满足哪些要求。如果文档符合所有要求，则会在结果中返回该文档。否则，相应文档不会出现在结果中。如需了解过滤语法，请参阅过滤表达式语法。如需了解详情，请参阅 filterAction。注意：无法过滤文档字段 title。

使用 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 参考文档。

查找应用 ID。如果您已拥有应用 ID，请跳到下一步。
1. 在 Google Cloud 控制台中，前往 AI Applications 页面。
  
  前往“应用”
2. 在应用页面上，找到应用的名称，并从 ID 列获取应用的 ID。
运行以下 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 可以包含 [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 UTC“Zulu”格式的时间戳，用于指示时间范围的开始时间。
  - END_TIMESTAMP：采用 RFC 3339 UTC“Zulu”格式的时间戳，用于指示时间范围的结束时间。
- SYNONYMS_N：彼此关联的字符串列表，可让每个字符串更有可能显示相似的结果。虽然您更有可能获得相似的结果，但当您搜索每个同义词条目时，可能无法获得所有相关同义词的所有相关结果。您必须指定至少两个同义词，最多可指定 100 个同义词。每个同义词都必须采用 UTF-8 编码并以小写形式呈现。不允许使用重复的字符串。例如，您可以添加“Pixel”“Android 手机”和“Google 手机”作为同义词。如需了解详情，请参阅 synonymsAction。

使用 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 参考文档。

查找应用 ID。如果您已拥有应用 ID，请跳到下一步。
1. 在 Google Cloud 控制台中，前往 AI Applications 页面。
  
  前往“应用”
2. 在应用页面上，找到应用的名称，并从 ID 列获取应用的 ID。
运行以下 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 可以包含 [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 UTC“Zulu”格式的时间戳，用于指示时间范围的开始时间。
  - END_TIMESTAMP：采用 RFC 3339 UTC“Zulu”格式的时间戳，用于指示时间范围的结束时间。
- REDIRECT_URI_N：您将被重定向到的 URI。长度上限为 2000 个字符。例如，如果搜索字词的值为“支持”，您可以设置重定向到技术支持页面，而不是返回（或无法返回）“支持”的搜索结果。在此示例中，重定向 URI 变为 "https://www.example.com/support"。如需了解详情，请参阅 redirectAction。

使用 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 参考文档。

查找应用 ID。如果您已拥有应用 ID，请跳到下一步。
1. 在 Google Cloud 控制台中，前往 AI Applications 页面。
  
  前往“应用”
2. 在应用页面上，找到应用的名称，并从 ID 列获取应用的 ID。
运行以下 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 可以包含 [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 UTC“Zulu”格式的时间戳，用于指示时间范围的开始时间。
    - END_TIMESTAMP：采用 RFC 3339 UTC“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
  }
 }
}
```

对于除基本网站搜索之外的所有搜索应用，请使用 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。

可选：对于基本网站搜索，您无需将控件附加到应用的提供配置。不过，对于基本网站搜索，您可以在创建提升控件后通过调用 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
  }
 }
}

然后，您发送以下搜索请求：

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

后续步骤

如需了解投放控制对自定义搜索应用的搜索质量有何影响，请评估搜索质量。如需了解详情，请参阅评估搜索质量。

为搜索配置投放控制 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

服务控件简介

投放控制类型

关于条件

创建并附加提升效果投放控件

控制台

REST

创建和附加过滤条件投放控件

创建并附加同义词投放控件

创建并附加重定向投放控件

创建并附加推广投放控件

响应

示例

后续步骤

为搜索配置投放控制