Migrate to the Retail API from beta

Recommendations AI now uses the Retail API. This page explains the changes introduced and migration best practices when moving from the v1beta1 version of the Recommendations Engine API (service endpoint https://recommendationengine.googleapis.com) to the generally available Retail API (service endpoint https://retail.googleapis.com).

The Recommendations Engine API and its documentation set remain available, but they are no longer updated.

This document applies to you only if you started using Recommendations AI when it was in beta.

Best practices

  • Send validate-only traffic before fully migrating.
  • Incremental traffic migration is better than switching all at once. If possible, gradually migrate your traffic from v1beta1 to v2.
  • If you are running services in different regions, it's better to migrate regions one by one to avoid global outage.

Documentation changes

After you switch to the Retail console, we recommend that you exclusively use this Retail documentation at https://cloud.google.com/retail/docs.

The beta documentation set for Recommendations Engine API remains available, but is no longer updated.

Console changes

The Retail console replaces the Recommendations console.

The Retail Google Cloud console is publicly available as of January 20, 2022. If you use the Recommendations console, we recommend accessing your Recommendations AI projects from the Retail console.

For an explanation of changes in functionality and terminology in the Retail console compared to the Recommendations console, see Switch to the Retail console.

Serving configs and placements

The Retail API introduces serving configs, which replaces the concept of placements used by the Recommendations Engine API.

Serving configurations are available as of Recommendations AI v2 and Retail Search v2alpha, using the Retail API.

The servingConfig resource is available in Retail API versions v2beta and v2alpha. You can use this resource to create, view, edit, and remove serving configurations.

If you have existing placements, or create new placements, the Retail API automatically creates a serving configuration associated with each placement. Creating a serving configuration does not create a corresponding placement.

Deleting a serving configuration deletes its corresponding placement, and deleting a placement deletes its corresponding serving configuration.

Serving configurations allow you to edit diversity and price reranking options and have them take effect in near real-time. With placements, diversity and pricing settings can only be changed from the recommendation model that the placement points to.

Placements are still supported, but using serving configurations instead is recommended.

For more information about using serving configurations, see Serving configs and Creating serving configs.

REST and RPC paths

Many changes have been made to the REST and RPC paths. Make sure to review the API documentation for the Retail API to ensure you are calling the Retail API correctly.

All paths now use retail.googleapis.com instead of recommendationengine.googleapis.com.

For example:

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

Some resources and methods have been renamed, removed, or newly added. The table below compares v1beta1 and v2 resources and their associated methods side-by-side.

For example, the v1beta1 resource catalogs.catalogItems is equivalent to the v2 resource catalogs.branches.products. The list method, which was available in catalogs.catalogItems for v1beta1, is not available for catalogs.branches.products in v2, so it is indicated as Removed.

Note that links to v1beta1 resources go to the API documentation for v1beta1.

v1beta1 Resource Method v2 Resource Method
catalogs list catalogs list
patch patch
N/A catalogs.branches.operations get
catalogs.catalogItems create catalogs.branches.products create
delete delete
get get
import import
list Removed
patch patch
catalogs.operations get catalogs.operations get
list list
catalogs.eventStores.operations get Removed
list
catalogs.eventStores.placements predict catalogs.placements predict
catalogs.eventStores.predictionApiKeyRegistrations create Removed
delete
list
catalogs.eventStores.userEvents collect catalogs.userEvents collect
import import
list Removed
purge purge
rejoin rejoin
write write
N/A operations get
list

IAM changes

The following changes have been introduced to Retail Identity and Access Management (IAM) roles and permissions:

  • Retail uses IAM roles and permissions in the retail namespace instead of the automlrecommendations namespace that was used by Recommendations Engine v1beta1.
  • The role Admin Viewer has been removed.
  • Permissions for apiKeys have been removed because the predict method no longer requires its own API key.

Catalog and user event schemas

The schemas for catalog and user events have changed in the Retail API.