Eseguire la migrazione dalla versione beta all'API Retail

I suggerimenti ora utilizzano l'API Retail. Questa pagina spiega le modifiche introdotte e le best practice per la migrazione durante il passaggio dalla versione v1beta1 dell'API Recommendations Engine (endpoint di servizio https://recommendationengine.googleapis.com) all'API Retail in disponibilità generale (endpoint di servizio https://retail.googleapis.com).

L'API Recommendations Engine e il relativo set di documentazione rimangono disponibili, ma non vengono più aggiornati.

Questo documento si applica solo se hai iniziato a utilizzare la pagina Consigli quando era in versione beta.

best practice

  • Invia traffico di sola convalida prima della migrazione completa.
  • La migrazione del traffico incrementale è preferibile alla migrazione di tutti i dati contemporaneamente. Se possibile, esegui la migrazione graduale del traffico dalla versione v1beta1 alla versione v2.
  • Se esegui servizi in regioni diverse, è meglio eseguire la migrazione delle regioni una alla volta per evitare un'interruzione globale.

Modifiche alla documentazione

Dopo aver effettuato il passaggio alla console Retail, ti consigliamo di utilizzare esclusivamente questa documentazione di Retail all'indirizzo https://cloud.google.com/retail/docs.

La documentazione beta impostata per l'API Recommendations Engine rimane disponibile, ma non viene più aggiornata.

Modifiche alla console

La console Retail sostituisce la console Consigli.

La console Google Cloud Retail è disponibile pubblicamente dal 20 gennaio 2022. Se utilizzi la console dei suggerimenti, ti consigliamo di accedere ai tuoi progetti di suggerimenti dalla console Retail.

Per una spiegazione delle modifiche alle funzionalità e alla terminologia della console Retail rispetto alla console dei suggerimenti, consulta Passare alla console Retail.

Schemi di eventi utente e catalogo

Gli schemi per gli eventi catalogo e utente sono cambiati nell'API Retail.

Configurazioni di pubblicazione e posizionamenti

L'API Retail introduce configurazioni di pubblicazione che sostituisce il concetto di posizionamenti utilizzati dall'API Recommendations Engine.

Le configurazioni di pubblicazione sono disponibili a partire da Recommendations v2 e Retail Search v2alpha, utilizzando l'API Retail.

La risorsa servingConfig è disponibile nelle versioni v2beta e v2alpha dell'API Retail. Puoi utilizzare questa risorsa per creare, visualizzare, modificare e rimuovere le configurazioni di pubblicazione.

Se disponi di posizionamenti esistenti o ne crei nuovi, l'API Retail crea automaticamente una configurazione di pubblicazione associata a ogni posizionamento. La creazione di una configurazione di pubblicazione non crea un posizionamento corrispondente.

L'eliminazione di una configurazione di pubblicazione comporta l'eliminazione del posizionamento corrispondente, mentre l'eliminazione di un posizionamento comporta l'eliminazione della configurazione di pubblicazione corrispondente.

Le configurazioni di pubblicazione ti consentono di modificare le opzioni di diversità e di re-ranking dei prezzi e di renderle effettive quasi in tempo reale. Con i posizionamenti, le impostazioni relative a diversità e prezzi possono essere modificate solo dal modello di suggerimento a cui rimanda il posizionamento.

I posizionamenti sono ancora supportati, ma è consigliabile utilizzare le configurazioni di pubblicazione.

Per ulteriori informazioni sull'utilizzo delle configurazioni di pubblicazione, consulta gli articoli Configurazioni di pubblicazione e Creazione di configurazioni di pubblicazione.

Percorsi REST e RPC

Sono state apportate molte modifiche ai percorsi REST e RPC. Assicurati di consultare la documentazione dell'API Retail per assicurarti di chiamare correttamente l'API Retail.

Tutti i percorsi ora utilizzano retail.googleapis.com anziché recommendationengine.googleapis.com.

Ad esempio:

API Recommendations Engine v1beta1: 

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

API Retail v2:

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

Alcune risorse e metodi sono stati rinominati, rimossi o aggiunti di recente. La tabella riportata di seguito confronta le risorse v1beta1 e v2 e i relativi metodi associati fianco a fianco.

Ad esempio, la risorsa v1beta1 catalogs.catalogItems equivale alla risorsa v2 catalogs.branches.products. Il metodo list, che era disponibile in catalogs.catalogItems per v1beta1, non è disponibile per catalogs.branches.products nella v2, quindi è indicato come Rimosso.

Tieni presente che i link alle risorse v1beta1 rimandano alla documentazione dell'API per v1beta1.

Risorsa v1beta1 Metodo Risorsa v2 Metodo
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 Rimosso
patch patch
catalogs.operations get catalogs.operations get
list list
catalogs.eventStores.operations get Rimosso
list
catalogs.eventStores.placements predict catalogs.placements predict
catalogs.eventStores.predictionApiKeyRegistrations create Rimosso
delete
list
catalogs.eventStores.userEvents collect catalogs.userEvents collect
import import
list Rimosso
purge purge
rejoin rejoin
write write
N/A operations get
list

Modifiche IAM

Sono state introdotte le seguenti modifiche ai ruoli e alle autorizzazioni di Identity and Access Management (IAM) di Retail:

  • Retail utilizza ruoli e autorizzazioni IAM nello spazio dei nomi retail anziché nello spazio dei nomi automlrecommendations utilizzato da Recommendations Engine v1beta1.
  • Il ruolo Admin Viewer è stato rimosso.
  • Le autorizzazioni per apiKeys sono state rimosse perché il metodo predict non richiede più una propria chiave API.