此页面由 Cloud Translation API 翻译。

为搜索配置投放控制

投放控制（也称为控制）用于更改请求的默认行为。

例如，控件可以提升和隐藏结果、过滤返回结果中的条目、将查询作为同义词相互关联，或将查询重定向到指定的 URI。

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

服务控件简介

如需更改请求的结果，请先创建投放控件。然后，将该控件附加到应用。控件只会影响其附加到的应用提供的请求。如果控件未附加到应用，则不会产生任何影响。

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

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

queryTerms。在搜索特定查询时应用此控件。
activeTimeRange。当请求在指定的时间范围内发生时，系统会应用此控件。

如果为控件指定了这两种类型的条件，当这两种条件类型都满足时，系统会将该控件应用于搜索请求。如果为同一条件指定了多个值，则只需其中一个值匹配即可满足该条件。

例如，请考虑以下指定了两个查询字词的条件：

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

SearchRequest.query="gShoe" 或 SearchRequest.query="gBoot" 请求将满足该条件，但 SearchRequest.query="gSandal" 或任何其他字符串都不会满足该条件。

如果未指定任何条件，则控件将始终应用。

如需了解详情，请参阅 API 参考文档中的 servingConfigs.search。

投放控件类型

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

控制	说明	支持的设备
提升控制	更改返回的结果顺序	使用支持架构的数据存储区的搜索应用，例如包含结构化数据的数据存储区、包含结构化数据的网站、包含元数据的非结构化数据或媒体数据
过滤器控件	从返回的结果中移除条目	使用支持架构的数据存储区的搜索应用，例如包含结构化数据的数据存储区、包含结构化数据的网站、包含元数据的非结构化数据或媒体数据
同义词控件	将查询相互关联	使用网站数据存储区、结构化数据存储区、非结构化数据存储区或媒体数据存储区的搜索应用
重定向控件	重定向到指定的 URI	所有搜索应用

关于提升广告投放效果的控件

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

boostAction 的语法如下：

{
    "boost": "BOOST",
    "filter": "FILTER",
    "dataStore": "DATA_STORE_RESOURCE_PATH"
}

BOOST：介于 -1 和 1 之间的浮点数。如果该值为负，则相应结果会被降级，在搜索结果中显示得更靠后。当该值为正时，系统会将结果提升到搜索结果中的更前面的位置。
FILTER：一个字符串，用于指定文档必须满足的要求。如果文档符合所有要求，系统就会应用该提升幅度。否则，不会有任何变化。如果此字段为空，则对数据存储区中的所有文档应用该提升因子。如需了解过滤语法，请参阅过滤条件表达式语法。
DATA_STORE_RESOURCE_PATH：应通过此控件提升文档排名的数据存储区的完整资源路径。完整资源路径的格式为 projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID。此数据存储区必须附加到请求中指定的引擎。

过滤条件投放控件简介

过滤器投放控件定义为具有 filterAction 的控件。

filterAction 的语法如下：

{
    "filter": "FILTER"
}

FILTER：一个字符串，用于指定文档必须满足的要求。如果文档符合所有要求，则结果会包含在结果列表中。否则，系统会将结果从结果列表中移除。如需了解过滤语法，请参阅过滤表达式语法。

同义词投放控件简介

同义词投放控件定义为具有 synonymsAction 的控件。

synonymsAction 的语法如下：

{
    "synonyms": "SYNONYMS"
}

SYNONYMS：将相互关联的字符串，使每个字符串都更有可能显示类似的结果。您必须至少指定两个字符串，最多可指定 100 个字符串。字符串必须采用 UTF-8 编码且采用小写形式。不允许使用重复的字符串。

例如：

{
    "synonyms": ["pixel", "android phone", "google phone"]
}

重定向投放控件简介

重定向投放控制功能可将用户重定向到所提供的 URI。

重定向控件定义为带有 redirectAction 的控件。

redirectAction 的语法：

{
    "redirect_uri": "REDIRECT_URI"
}

REDIRECT_URI：一个长度不超过 2000 个字符的 URI。

例如，如果查询字词的值为“支持”，您可以设置重定向到技术支持页面，而不是返回（或未返回）“支持”的搜索结果。

{
    "redirect_uri": ["https://www.example.com/support"]
}

`queryTerms` 条件简介

queryTerms 为可选项。如果您希望在搜索特定查询时使用投放控制，请使用此属性。使用 queryTerms 条件时，当 queryTerms 的值与 SearchRequest.query 中的字词匹配时，系统会应用控制。

只有在 Control.searchUseCase 设置为 SOLUTION_TYPE_SEARCH 时才能使用查询字词。

在单个 Control.condition 上，最多可以指定 10 个不同的 queryTerms。如果未指定查询字词，系统会忽略该字段。

单个 queryTerm 的语法如下：

{
    "value": "VALUE_1",
    "fullMatch": "FULL_MATCH_1"
}

VALUE_1：长度为 [1, 5000] 的 UTF-8 小写字符串。如果 FULL_MATCH_1 为 true，则最多只能包含三个以空格分隔的项。
FULL_MATCH_1：布尔值。设置为 true 时，要求 SearchRequest.query 与 queryTerm.value 完全匹配。设置为 false 时，要求 SearchRequest.query 包含 queryTerm.value 作为子字符串。

`activeTimeRange` 条件简介

activeTimeRange 为可选项。它会检查收到请求的时间是否在 activeTimeRange.startTime 和 activeTimeRange.endTime 之间。

在单个 Control.condition 上，最多可以指定 10 个 activeTimeRange 范围。如果未指定任何 activeTimeRange 范围，系统会忽略该字段。

单个 activeTimeRange 的语法如下：

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]

START_TIMESTAMP_1：定义将应用控制的 earliestTime（包括该时间）。时间戳采用 RFC 3339 世界协调时间 (UTC)“Zulu”格式，精确到纳秒且最多有 9 位小数，例如 "2023-10-02T15:01:23Z"。
END_TIMESTAMP_1：定义将应用控制的最新时间（包括该时间）。此时间必须是将来的时间。

API 说明：使用投放控制更改默认搜索请求行为

如需更改默认搜索请求行为，您可以创建一个投放控件，并将其附加到默认投放配置。

准备工作

如果您想创建投放控制功能，请与您的 Google 客户支持团队联系，请求将您添加到投放控制功能的许可名单中。

创建投放控件

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

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

找到您的数据存储区 ID。如果您已拥有数据存储区 ID，请跳至下一步。
1. 在 Google Cloud 控制台中，前往 Agent Builder 页面，然后在导航菜单中点击数据存储区。
  
  前往“数据存储区”页面
2. 点击您的数据存储区的名称。
3. 在数据存储区的数据页面上，获取数据存储区 ID。

为控件选择条件类型和字段值。

以下是条件的截断示例：

{
  "queryTerms": [
      {
        "value": "VALUE_1",
        "fullMatch": FULL_MATCH_1
      },
      {
        "value": "VALUE_2",
        "fullMatch": FULL_MATCH_2
      },
    ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP_1",
      "endTime": "END_TIMESTAMP_1"
    },
    {
      "startTime": "START_TIMESTAMP_2",
      "endTime": "END_TIMESTAMP_2"
    },
  ]
}

运行以下 curl 命令以创建控件。

提升控件：点击此选项可查看用于创建提升控件的 curl 命令。

运行以下 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/dataStores/DATA_STORE_ID/controls?CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "boostAction": "BOOST_ACTION",
    }'

过滤器控件：点击此选项可查看用于创建过滤器控件的 curl 命令。

运行以下 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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "filterAction": "FILTER_ACTION",
    }'

同义词控件：点击此选项可查看用于创建同义词控件的 curl 命令。

运行以下 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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "synonymsAction": "SYNONYMS_ACTION",
    }'

重定向控件：点击此处可查看用于创建重定向控件的 curl 命令。

运行以下 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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "redirectAction": "REDIRECT_ACTION",
    }'

PROJECT_ID：您的 Google Cloud 项目的项目编号或 ID。
DATA_STORE_ID：数据存储区的唯一 ID。
CONTROL_ID：控件的唯一标识符（在数据存储区区内）。ID 可以包含小写字母、数字、连字符和下划线。
DISPLAY_NAME：控件的直观易懂的名称。Google 建议此名称应能说明何时或为何使用该控件。必须是长度为 [1,128] 的 UTF-8 字符串。
USE_CASE：必须是 SEARCH_USE_CASE_SEARCH 或 SEARCH_USE_CASE_BROWSE。如果指定了 SEARCH_USE_CASE_BROWSE，则无法在条件中使用 Condition.queryTerms。
CONDITION：（可选）定义应何时应用控制。
BOOST_ACTION：用于定义提升控件。请参阅 boostAction API 参考文档。
FILTER_ACTION：用于定义过滤器控件。请参阅 filterAction API 参考文档。
SYNONYMS_ACTION：用于定义同义词控件。请参阅 synonymsAction API 参考文档。
REDIRECT_ACTION：用于指定重定向 URI。请参阅 redirectAction API 参考文档。

将控件附加到应用。

提升控件：点击此按钮可查看提升控件的 curl 命令。

运行以下 curl 命令，将提升控制器附加到广告投放配置，以便在广告投放请求中使用：

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
    -d '{
      "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2" … ]
    }'

BOOST_ID_1 和 BOOST_ID_2：表示您在上一步中创建的控件 ID。

过滤器控件：点击过滤器控件的 curl 命令。

运行以下 curl 命令，将过滤条件控件附加到广告投放配置，以便在广告投放请求中使用：

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
    -d '{
      "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2" … ]
    }'

FILTER_ID_1 和 FILTER_ID_2：表示您在上一步中创建的控件 ID。

同义词控件：点击此处查看同义词控件的 curl 命令。

运行以下 curl 命令，将同义词控制器附加到应用，以便在处理请求时使用：

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
    -d '{
     "synonymsControlIds": ["SYNONYM_ID_1", "SYNONYM_ID_2" … ]
    }'

SYNONYM_ID_1 和 SYNONYM_ID_2：表示您在上一步中创建的控件 ID。

重定向控件：点击此按钮可查看重定向控件的 curl 命令。

运行以下 curl 命令，将重定向控件附加到应用，以便在处理请求时使用：

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
    -d '{
      "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2" … ]
    }'

REDIRECT_ID_1 和 REDIRECT_ID_2：表示您在上一步中创建的控件 ID。

后续步骤

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

为搜索配置投放控制

服务控件简介

投放控件类型

关于提升广告投放效果的控件

过滤条件投放控件简介

同义词投放控件简介

重定向投放控件简介

queryTerms 条件简介

activeTimeRange 条件简介

API 说明：使用投放控制更改默认搜索请求行为

准备工作

创建投放控件

后续步骤

`queryTerms` 条件简介

`activeTimeRange` 条件简介