Retail 将更名为 Vertex AI Search for Retail。我们正在更新内容以反映新的品牌。

管理服务控件

本页面介绍如何查看、修改、删除、导出和导入服务控件。

有关服务控件的一般信息以及如何创建投放控件的说明，请参阅投放控件简介和创建投放控件。

查看和修改服务控件

您可以使用控制台和 API 查看适用于零售业的 Vertex AI Search 的服务控件。

在控制台中查看和修改服务控件

“控件”页面的服务控件标签页列出了您的所有服务控件及其关联的服务配置。点击某个控件的 修改控件图标，即可在修改控件面板中更改其设置和关联的服务配置。点击某个控件的 删除控件图标可将其删除，此操作会同时将其从所有服务配置中移除。

您还可以在服务配置页面上查看和修改特定服务配置的控件。点击一项服务配置可查看其详细信息页面，其中列出了该配置的所有服务控件。点击控件的 修改控件图标，即可在修改控件面板中更改其设置。点击 移除控件图标，以解除控件与服务配置之间的关联（此操作不会删除该控件）。

新创建的或更新的控件需要几分钟时间才能准备好传送实时流量。您可以在控制台的评估页面上测试您的更改是否已应用。

就地查看投放控件

如需查看内嵌的单个投放控件，请使用 Control.get。

如需详细了解此方法，请参阅 Control.get API 参考文档。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
'https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls/CONTROL_ID'

如需以内嵌方式列出多个服务控件，请使用 Controls.list。

或者，您可以使用参数 pageSize 设置要返回的结果数上限。如果有更多结果，list 响应会包含页面令牌。您可以在 list 请求的 pageToken 参数中传递页面令牌，以检索下一页结果。

如需仅列出与特定服务配置相关联的控件，请使用 filter 查询参数指定服务配置 ID。

如需详细了解此方法，请参阅 Control.list API 参考文档。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
'https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=servingConfig=SERVING_CONFIG_ID

以内嵌方式修补投放控件

如需更新服务控件中的字段，请使用 Controls.patch，并在请求正文中包含 Control 的实例。使用 updateMask 参数指定要更新的字段，或未设置以更新所有支持的字段。

如需详细了解此方法，请参阅 Controls.patch API 参考文档。

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
      "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls/CONTROL_ID",
      "FIELD_NAME_1": "NEW_FIELD_VALUE_1"
      "FIELD_NAME_2": "NEW_FIELD_VALUE_2"
    }' \
'https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls/CONTROL_ID?updateMask=FIELD_NAME_1,FIELD_NAME_2'

以内嵌方式向服务配置添加控件

如需将控件添加到服务配置，请使用 ServingConfig.addControl。

如需详细了解此方法，请参阅 ServingConfig.addControl API 参考文档。

如需查看此方法的示例，请参阅管理服务配置。

以内嵌方式从服务配置中移除控件

如需从服务配置中移除控件，请使用 ServingConfig.removeControl。

如需详细了解此方法，请参阅 ServingConfig.addControl API 参考文档。

如需查看此方法的示例，请参阅管理服务配置。

删除投放控件

您可以使用 Controls.delete 方法从控制台或以内嵌方式删除服务控件。

在控制台中删除服务控件

删除服务控件，即可将该控件从使用该控件的所有服务配置中移除。

转到 Search for Retail 控制台中的控件页面。

前往“控件”页面
在计划要移除的控件的表行中，点击删除。
在确认窗口中，点击删除以完成删除。

以内嵌方式删除服务控件

如需以内嵌方式删除服务控件，请使用 Controls.delete。

如需详细了解此方法，请参阅 Controls.delete API 参考文档。

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
'https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls/SERVING_CONTROL_ID'

导出服务控件

您可以将服务控件导出到 Cloud Storage 存储桶中的文件。

您可能需要导出和导入服务控件的原因有以下两种：

将服务控件从一个项目移至另一个项目。
对所有或部分投放控件执行批量修改。请导出投放控件，修改导出的文件，然后导入文件以更改或添加投放控件。

您可以通过 Search for Retail 控制台导出和导入。导出服务控件时，系统会导出项目中的所有服务控件。

如需导出服务控件，请执行以下操作：

转到 Search for Retail 控制台中的控件页面。

前往“控件”页面
在服务控件标签页上，点击导出控件。
在 Export Serving Controls 窗口中，选择要将控件文件导出到的目标 Cloud Storage 存储桶。
点击导出。

导出的控件将保存到所选存储桶的 NDJSON 文件中，其名称采用以下格式：
```
projects_PROJECT_ID_TIMESTAMP_exported_controls.ndjson
```
导出操作完成后，您可以在导出活动窗口的批量导入、导出、删除活动列表中查看操作状态。点击消息窗口中的显示，或按照查看特定集成操作的状态中的说明打开 Export activity 窗口。

导入服务控件

如需批量添加投放控件或修改现有控件，您可以在导出的控件文件中进行更改。然后，您可以将它们导入原始项目或其他项目中。

有关导入投放控件的注意事项：

如果服务控件文件同时包含搜索和推荐服务控件，则无法导入该文件。
导入服务控件时，文件中的所有服务控件都会与您在导入时指定的服务配置相关联。如果一个服务控件已与项目中的另一个服务配置关联，则该关联也将保持不变。

如需导入服务控件，请执行以下操作：

修改和查看导出的服务控制文件，并将该文件放在 Cloud Storage 存储桶中。（如需导出服务控件，请参阅前面的导出服务控件任务。）

确保文件仅包含搜索服务控件或仅包含建议服务控件。您无法导入同时包含这两种类型的文件。
转到 Search for Retail 控制台中的控件页面。

前往“控件”页面
在服务控件标签页上，点击导入控件。
在 Import Serving Controls 窗口中：
1. 浏览并选择包含要导入的控件的 Cloud Storage 存储桶和 NDJSON 文件。
2. 选择要将导入的服务控件与之关联的服务配置。
3. 查看“导入预览”计划。将创建的控件显示在 New 标签页上，将要修改的控件显示在 Modified 标签页上。
点击导入。

系统会开始一个长时间运行的操作，以导入新控件和修改后的控件。
导入操作完成后，您可以在 Activity status 窗口的 Controls 标签页中查看操作状态。点击消息窗口中的显示，或按照查看特定集成操作的状态中的说明操作，打开活动状态窗口。