服务控件（也称为控件）会更改返回结果时请求的默认服务行为。服务控件在数据存储区级层发挥作用。
例如，控件可以置顶和沉底结果、从返回的结果中过滤条目、将字符串彼此关联为同义词，或将结果重定向到指定的 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 控制台创建并附加提升控制变量，请执行以下操作：
在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
选择要为其创建提升控制设置的应用。
点击配置，然后点击控制标签页。
点击创建控制变量。
对于 What do you want to do?（您想做什么？），指定控件名称和类型：
在控件名称中，输入提升/掩埋控件的名称。
对于控件类型，选择提升/掩埋。
点击继续。
在设置规则范围和影响部分，定义您要使用此控件触发的操作：
从列表中选择数据存储区。如果您希望将操作应用于多个数据存储区，请为每个数据存储区创建一个控件。
在过滤条件部分，添加过滤条件。
这是一个字符串，用于说明文档必须满足哪些要求。只有当文档满足所有要求时，才会应用提升条件。否则，不会有任何变化。如果您未指定过滤条件，则系统会将提升应用于数据存储区中的所有文档。
如需了解过滤表达式语法，请参阅过滤表达式语法。
对于提升/掩埋值，请使用滑块选择 [-1, 1] 范围内的提升/掩埋值。滑块以 0.01 为步长移动。
点击继续。
对于可选：激活此规则的时机，请设置触发控制的以下条件。如果未配置任何条件，此控制将始终有效：
添加部分匹配的查询字词。当这些查询字词部分匹配时，控制变量会生效。
添加完全匹配的查询字词。当这些查询字词完全匹配时，该控制措施会生效。
如需添加有效的时间范围，请点击添加时间范围，然后设置开始时间 1 和结束时间 1。这会定义条件处于有效状态的时间段。您最多可以添加 10 个时间范围。
点击继续。
对于其他设置，请选择是否要启用相应规则：
如果您不想在创建此控件后立即将其激活，请关闭立即发布此控件。
点击继续。
点击提交。
REST
提升服务控件是指具有 boostAction 的控件。
按照以下说明创建提升服务控件。
如需了解字段详情，请参阅 engines.controls API 参考文档和 engines.controls.create API 参考文档。
找到应用 ID。如果您已拥有应用 ID，请跳到下一步。
在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
在应用页面上，找到应用的名称，并从 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：应用的 ID。CONTROL_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。此数据存储区必须附加到请求中指定的引擎。
使用
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 控制台创建和附加过滤条件控件，请执行以下操作：
在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
选择要为其创建过滤条件控件的应用。
点击配置，然后点击控制标签页。
点击创建控制变量。
对于 What do you want to do?（您想做什么？），指定控件名称和类型：
在控件名称中，输入过滤控件的名称。
在控件类型中，选择过滤条件。
点击继续。
在设置规则范围和影响部分，定义您要使用此控件触发的操作：
从列表中选择数据存储区。如果您希望将操作应用于多个数据存储区，请为每个数据存储区创建一个控件。
对于过滤，请告知规则要查找哪些特定项。您可以使用
AND、OR、NOT组合搜索字词，并使用()对字词进行分组。对于完全匹配的短语，请使用英文引号 ("")。例如：category: "electronics" AND price < 500, status: "open" AND priority:"P1"。如需了解过滤表达式语法，请参阅过滤表达式语法。
点击继续。
对于可选：激活此规则的时机，请设置触发控制的以下条件。如果未配置任何条件，此控制将始终有效：
添加部分匹配的查询字词。当这些查询字词部分匹配时，控制变量会生效。
添加完全匹配的查询字词。当这些查询字词完全匹配时，该控制措施会生效。
如需添加有效的时间范围，请点击添加时间范围，然后设置开始时间 1 和结束时间 1。这会定义条件处于有效状态的时间段。您最多可以添加 10 个时间范围。
点击继续。
对于其他设置，请选择是否要启用相应规则：
如果您不想在创建此控件后立即将其激活，请关闭立即发布此控件。
点击继续。
点击提交。
REST
如需了解字段详情，请参阅 engines.controls API 参考文档和 engines.controls.create API 参考文档。
找到应用 ID。如果您已拥有应用 ID，请跳到下一步。
在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
在应用页面上，找到应用的名称，并从 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：应用的 ID。CONTROL_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。
使用
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 控制台创建并附加同义词控制变量，请执行以下操作：
在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
选择要为其创建同义词控件的应用。
点击配置，然后点击控制标签页。
点击创建控制变量。
对于 What do you want to do?（您想做什么？），指定控件名称和类型：
在为控制变量命名部分，为同义词控制变量输入一个名称。
对于控制类型，选择同义词。
点击继续。
在设置规则范围和影响部分，定义您要使用此控件触发的操作：
输入您希望在控制组中考虑的同义词。例如，输入 cats，然后按回车键（而非逗号），再输入 feline。
点击继续。
对于可选：激活此规则的时机，请设置触发控制的以下条件。如果未配置任何条件，此控制将始终有效：
如需添加有效的时间范围，请点击添加时间范围，然后设置开始时间 1 和结束时间 1。这会定义条件处于有效状态的时间段。您最多可以添加 10 个时间范围。
点击继续。
对于其他设置，请选择是否要启用相应规则：
如果您不想在创建此控件后立即将其激活，请关闭立即发布此控件。
点击继续。
点击提交。
REST
如需了解字段详情，请参阅 engines.controls API 参考文档和 engines.controls.create API 参考文档。
找到应用 ID。如果您已拥有应用 ID，请跳到下一步。
在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
在应用页面上，找到应用的名称，并从 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：应用的 ID。CONTROL_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 编码并以小写形式呈现。不允许出现重复的字符串。例如，您可以添加“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，请跳到下一步。
在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
在应用页面上，找到应用的名称，并从 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：应用的 ID。CONTROL_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。
使用
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 参考文档。
找到应用 ID。如果您已拥有应用 ID，请跳到下一步。
在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
在应用页面上，找到应用的名称，并从 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" } ] }, "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 可以包含 [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。
响应包含您需要附加到搜索应用的推广控件 ID。
使用
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。
修改服务控件
如需修改控制变量的配置，请执行以下操作：
在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
选择要修改控件的应用。
点击配置，然后点击控制标签页。
在应用控件列表中，点击要修改的控件对应的 ，然后点击修改。
在修改控件窗格中修改控件：
如需启用或停用某个控件，请在应用的过滤条件控件列表中，点击要启用或停用的控件对应的 ，然后分别点击启用或停用。
如需删除控件，请在应用的控件列表中，点击要删除的控件对应的 ，然后点击删除。
后续步骤
- 如需了解服务控件对应用搜索质量的影响，请评估搜索质量。