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 theautomlrecommendations
namespace that was used by Recommendations Engine v1beta1. - The role
Admin Viewer
has been removed. - Permissions for
apiKeys
have been removed because thepredict
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.
When importing catalog data from BigQuery, use the schema for Retail: Retail catalog schema
When recording user event data, use the appropriate schema for each user event: Retail user event schemas