为搜索配置投放控制

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

投放控件（也称为控件）用于更改在返回结果时请求的默认处理方式。投放控制功能在数据存储区一级发挥作用。

例如，控件可以提升和掩埋结果、过滤返回结果中的条目、将字符串相互关联为同义词，或将结果重定向到指定的 URI。

本页介绍了搜索应用的投放控制功能。如需了解如何将投放控制功能与媒体推荐功能搭配使用，请参阅创建和管理媒体投放配置。

服务控件简介

如需更改请求的结果，请先创建投放控件。然后，将该控件附加到搜索应用的投放配置。投放配置用于配置用于生成投放时间结果（例如搜索结果或回答）的元数据。只有当服务控件附加到应用的服务配置时，才会影响应用提供的请求。

某些控件（例如提升控件）依赖于数据存储区。如果从应用中移除数据存储区，则任何依赖于数据存储区的控件也会从该应用中移除并变为无效，但不会被删除。

投放控件类型

您可以使用以下类型的投放控件：

条件简介

创建控件时，您可以选择定义一个条件，以确定何时应用控件。条件使用条件字段进行定义。可用的条件字段如下：

• queryTerms。可选控件，用于在搜索特定查询时应用。使用 queryTerms 条件时，当 queryTerms 的值与 SearchRequest.query 中的字词匹配时，系统会应用控制。只有在 Control.searchUseCase 设置为 SOLUTION_TYPE_SEARCH 时，才能使用查询字词。在单个 Control.condition 上，最多可以指定 10 个不同的 queryTerms。如果未指定任何查询字词，系统会忽略 queryTerms 字段。

  对于促销投放控制，适用以下额外约束条件：

  • 如果您指定了 queryRegex 条件，则无法指定 queryTerms 条件
  • fullMatch 必须设置为 true

• 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 字段。

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

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

按照以下说明创建提升投放控制。

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

1. 找到您的应用 ID。如果您已经有应用 ID，请跳至下一步。

   1. 在 Google Cloud 控制台中，前往 AI 应用页面。

      前往“应用”

   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 可以包含 [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。此数据存储区必须附加到请求中指定的引擎。

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 的控件。

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

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

1. 找到您的应用 ID。如果您已经有应用 ID，请跳至下一步。

   1. 在 Google Cloud 控制台中，前往 AI 应用页面。

      前往“应用”

   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 可以包含 [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。

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

1. 找到您的应用 ID。如果您已经有应用 ID，请跳至下一步。

   1. 在 Google Cloud 控制台中，前往 AI 应用页面。

      前往“应用”

   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：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。

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 控制台中，前往 AI 应用页面。

      前往“应用”

   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 可以包含 [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 个字符。例如，如果查询字词的值为“support”，您可以设置重定向到技术支持页面，而不是返回（或未返回）与“support”相关的搜索结果。在此示例中，重定向 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 定义宣传控件。

如需成功创建宣传控件，创建请求中必须包含以下字段之一：

• 将 fullMatch 设置为 true 的 queryTerms 字段
• queryRegex 字段

按照以下说明创建促销投放控制。

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

1. 找到您的应用 ID。如果您已经有应用 ID，请跳至下一步。

   1. 在 Google Cloud 控制台中，前往 AI 应用页面。

      前往“应用”

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

   替换以下内容：

   • 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。此数据存储区必须附加到请求中指定的引擎。
   • URI_TITLE：必填字段，用于指定 URI 的标题，该标题会显示在搜索结果中。
   • URI：必填字段，用于指定搜索结果将用户引导到的 URI 链接。此 URI 无需包含在数据存储区中。
   • URI_DESCRIPTION：用于描述 URI 的可选字段，该字段会显示在搜索结果中。
   • 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   }  } } 

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

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

 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 响应的 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"     }   ] } 

后续步骤

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