从 Beta 版迁移到 Retail API

Recommendations 现在使用 Retail API。本页面介绍了从 v1beta1 版本 Recommendations Engine API（服务端点 https://recommendationengine.googleapis.com）迁移到正式版 Retail API（服务端点 https://retail.googleapis.com）所引入的变更和迁移最佳做法。

Recommendations Engine API 及其文档集仍然可用，但不再更新。

本文档仅适用于在“建议”功能处于 Beta 版阶段时开始使用该服务的情况。

最佳实践

  • 在完全迁移前发送仅用于验证的流量。
  • 增量流量迁移优于一次性切换所有流量。如果可能，逐步将流量从 v1beta1 迁移到 v2。
  • 如果您在不同区域运行服务，最好逐个迁移区域以避免全球服务中断。

文档变更

切换到 Retail 控制台后，我们建议您仅使用 https://cloud.google.com/retail/docs 上的此 Retail 文档。

Recommendations Engine API 的 Beta 版文档集仍然可用，但不再更新。

控制台更改

Retail 控制台会替换 Recommendations 控制台。

零售业 Google Cloud 控制台自 2022 年 1 月 20 日起已公开发布。如果您使用 Recommendations 控制台，我们建议您从 Retail 控制台访问 Recommendations 项目。

如需了解与 Recommendations 控制台相比，Retail 控制台在功能和术语方面的变化，请参阅切换到 Retail 控制台。

目录和用户事件架构

Retail API 中目录和用户事件的架构已更改。

投放配置和展示位置

Retail API 引入了服务配置，此配置取代了 Recommendations Engine API 所使用的展示位置的概念。

从 Recommendations v2 和 Retail Search v2alpha 开始，可通过 Retail API 使用服务配置。

servingConfig 资源可在 Retail API 版本 v2beta 和 v2alpha 中使用。您可以使用此资源创建、查看、修改和移除服务配置。

如果您已有展示位置，或创建新的展示位置，Retail API 会自动创建与每个展示位置关联的投放配置。创建投放配置不会创建相应的展示位置。

删除投放配置会删除其相应的展示位置，而删除展示位置将会删除其相应的投放配置。

借助投放配置，您可以修改多样性和价格重排序选项，并使它们近乎实时地生效。对于展示位置，您只能通过展示位置指向的建议模型来更改多样性和价格设置。

展示位置仍受支持，但建议改用投放配置。

如需详细了解如何使用服务配置，请参阅服务配置和创建服务配置。

REST 和 RPC 路径

我们对 REST 和 RPC 路径进行了许多更改。请务必查看 Retail API 的 API 文档，以确保正确调用 Retail API。

现在，所有路径都使用 retail.googleapis.com 而不是 recommendationengine.googleapis.com。

例如：

v1beta1 Recommendations Engine API：

GET https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

v2 Retail API：

GET https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

部分资源和方法已重命名、移除或新增。下表并排比较了 v1beta1 和 v2 资源及其关联方法。

例如，v1beta1 资源 catalogs.catalogItems 等同于 v2 资源 catalogs.branches.products。list 方法（在 v1beta1 的 catalogs.catalogItems 中可用）在 v2 中不适用于 catalogs.branches.products，因此表示为“已移除”。

请注意，指向 v1beta1 资源的链接会转到 v1beta1 的 API 文档。

v1beta1 资源 方法 v2 资源 方法
catalogs list catalogs list
patch patch
不适用 catalogs.branches.operations get
catalogs.catalogItems create catalogs.branches.products create
delete delete
get get
import import
list 已移除
patch patch
catalogs.operations get catalogs.operations get
list list
catalogs.eventStores.operations get 已移除
list
catalogs.eventStores.placements predict catalogs.placements predict
catalogs.eventStores.predictionApiKeyRegistrations create 已移除
delete
list
catalogs.eventStores.userEvents collect catalogs.userEvents collect
import import
list 已移除
purge purge
rejoin rejoin
write write
不适用 operations get
list

IAM 更改

Retail Identity and Access Management (IAM) 角色和权限引入了以下更改：

  • Retail 使用 retail 命名空间（而不是 Recommendations Engine v1beta1 使用的 automlrecommendations 命名空间）中的 IAM 角色和权限。
  • Admin Viewer 角色已移除。
  • 移除了 apiKeys 的权限，因为 predict 方法不再需要自己的 API 密钥。