Questa è la documentazione di Recommendations AI, Retail Search e la nuova console di Retail.

Prima di iniziare

Creare un progetto Google Cloud

  1. Nella pagina Gestisci risorse di Google Cloud Console, seleziona o crea un progetto Google Cloud.

    Vai alla pagina Gestisci risorse

  2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Configurare l'API Retail

Per utilizzare l'API Retail, insieme a Recommendations AI, devi attivare l'API Retail e accettare i termini per l'utilizzo dei dati di Discovery Solutions. Se utilizzi anche Ricerca al dettaglio, devi attivarla. L'uso di Retail Search comporta costi aggiuntivi in base al numero di query. Per ulteriori informazioni, consulta la sezione Addebiti per la ricerca retail.

Per configurare l'API Retail:

  1. Vai alla pagina Vendita al dettaglio in Google Cloud Console.

    Vai alla pagina Vendita al dettaglio

  2. Nella pagina Configura l'API Retail, fai clic su Attiva API.

  3. Quando l'API Retail e l'opzione Recommendations AI vengono visualizzate come on, fai clic su Continua.

  4. Leggi i Termini per l'utilizzo dei dati di Discovery Solutions e fai clic su Accetta se accetti i termini per l'utilizzo dei dati.

    Quando accetti i termini per l'utilizzo dei dati, Google Cloud Console indica che tali termini sono accettati.

  5. Se vuoi utilizzare il progetto solo con Recommendations AI, fai clic su Inizia.

  6. Se vuoi attivare Ricerca al dettaglio oltre a Recommendations AI:

    1. Fai clic su Continua, poi fai clic su Attiva nella pagina Attiva la ricerca al dettaglio (facoltativo).
    2. Fai clic su Inizia.

Google Cloud Console mostra i componenti dell'API Retail che hai attivato. Ora puoi configurare le impostazioni iniziali del progetto.

Configurare l'API Retail per un progetto esistente

Se hai configurato l'API Retail in un progetto Google Cloud prima che i termini di utilizzo dei dati entreranno in vigore il 4 aprile 2022, devi accettare i termini di Discovery Solutions per continuare a utilizzare l'API Retail con il progetto in questione. Devi anche abilitare la ricerca retail per tale progetto, se necessario.

Per accettare i termini di utilizzo dei dati di Discovery Solutions per un progetto esistente, completa i passaggi seguenti:

  1. Vai alla pagina Vendita al dettaglio di Google Cloud Console per il tuo progetto.

    Vai alla pagina Vendita al dettaglio

  2. Nella pagina Termini di utilizzo dei dati, leggi i termini di utilizzo dei dati di Discovery Solutions e fai clic su Accetta se accetti i termini.

  3. Se vuoi utilizzare il progetto solo con Recommendations AI, fai clic su Inizia.

  4. Se vuoi attivare Ricerca al dettaglio oltre a Recommendations AI:

    1. Fai clic su Continua, poi fai clic su Attiva nella pagina Attiva la ricerca al dettaglio (facoltativo).
    2. Fai clic su Inizia.

Disattivare Retail Search o l'API Retail

Disattivare la ricerca per la vendita al dettaglio

Se non vuoi più utilizzare la Ricerca al dettaglio, puoi disattivarla inviando un ticket di assistenza.

Per impostare il ticket sul componente corretto, seleziona i seguenti campi:

  • Categoria: machine learning
  • Componente: soluzioni per il retail: ricerca al dettaglio
  • Sottocomponente: amministrazione dell'account e fatturazione; fatturazione

Per ulteriori informazioni sulla creazione di un ticket di assistenza, consulta la pagina Richiedere assistenza.

Disattivare l'API Retail

Puoi disattivare l'API Retail in qualsiasi momento disattivandola e Recommendations AI. Viene disattivata anche la ricerca retail.

Per disattivare l'API Retail, procedi nel seguente modo:

  1. Vai alla pagina Dettagli del servizio API Retail in Google Cloud Console.

    Vai alla pagina dei dettagli del servizio API Retail

  2. Fai clic su Disabilita API.

  3. Nella casella Disattivare l'API Retail?, fai clic su Disattiva.

  4. Nella casella Disabilitare Recommendations AI?, fai clic su Disattiva.

Inizia a utilizzare l'API Retail

Quando configuri l'API Retail per un nuovo progetto, in Google Cloud Console vengono visualizzati i tre riquadri seguenti per aiutarti a configurare il progetto dell'API Retail:

  • Catalogo: visualizza il catalogo dei prodotti e un link per importare il catalogo.

  • Evento: visualizza gli eventi utente e un link per importare gli eventi utente storici.

  • Configurazioni di pubblicazione: contengono i dettagli sulla configurazione di pubblicazione e un link per creare una nuova configurazione di pubblicazione.

Puoi utilizzare questi riquadri per importare i dati e creare una configurazione iniziale per il tuo progetto API Retail.

Importare il catalogo dei prodotti

Per importare il catalogo dei prodotti, completa la procedura per l'origine dati. Per ulteriori informazioni sui cataloghi dei prodotti, vedi Importazione delle informazioni sul catalogo.

Sincronizzazione Merchant Center

  1. Fai clic su Importa catalogo prodotti per aprire il riquadro Importa dati.
  2. Scegli Catalogo dei prodotti.
  3. Seleziona Merchant Center Sync come origine dati.
  4. Seleziona il tuo account Merchant Center.
  5. Seleziona la filiale in cui caricherai il catalogo.
  6. Fai clic su Import (Importa).

Cloud Storage

  1. Fai clic su Importa catalogo prodotti per aprire il riquadro Importa dati.
  2. Scegli Catalogo dei prodotti come origine dati.
  3. Seleziona la filiale in cui caricherai il catalogo.
  4. Scegli Schema dei cataloghi dei prodotti di vendita al dettaglio come schema.
  5. Inserisci la località di Cloud Storage dei tuoi dati.
  6. Se Retail Search non è abilitato, seleziona i livelli di prodotto.

    Devi selezionare i livelli di prodotto se è la prima volta che importi il catalogo o se stai reimportando il catalogo dopo averlo eliminato definitivamente. Scopri di più sui livelli di prodotto. La modifica dei livelli dei prodotti dopo aver importato i dati richiede uno sforzo significativo.

    Importante: non puoi attivare Retail Search per i progetti con un catalogo dei prodotti che è stato importato come varianti.
  7. Fai clic su Import (Importa).

BigQuery

  1. Fai clic su Importa catalogo prodotti per aprire il riquadro Importa dati.
  2. Scegli Catalogo dei prodotti.
  3. Seleziona BigQuery come origine dati.
  4. Seleziona la filiale in cui caricherai il catalogo.
  5. Scegli uno dei seguenti schemi:
  6. Inserisci la tabella BigQuery in cui si trovano i tuoi dati.
  7. (Facoltativo) In Mostra opzioni avanzate, inserisci la località di un bucket Cloud Storage nel progetto come località temporanea per i tuoi dati.

    Se non è specificato, viene utilizzata una località predefinita. Se specificato, il bucket BigQuery e Cloud Storage devono trovarsi nella stessa area geografica.
  8. Se non hai attivato Retail Search e utilizzi lo schema di Merchant Center, seleziona il livello del prodotto.

    Devi selezionare il livello del prodotto se è la prima volta che importi il catalogo o lo importi di nuovo dopo averlo eliminato definitivamente. Scopri di più sui livelli di prodotto. La modifica dei livelli dei prodotti dopo aver importato i dati richiede uno sforzo significativo.

    Importante: non puoi attivare Retail Search per i progetti con un catalogo dei prodotti che è stato importato come varianti.
  9. Fai clic su Import (Importa).

Importare gli eventi utente storici

Per importare gli eventi utente storici, completa la procedura per l'origine dati. Per ulteriori informazioni sugli eventi utente storici, consulta Importare gli eventi utente storici.

Cloud Storage

  1. Fai clic su Importa eventi utente per aprire il riquadro Importa dati.
  2. Scegli Eventi utente.
  3. Seleziona Google Cloud Storage come origine dati.
  4. Scegli Schema eventi utente di vendita al dettaglio come schema.
  5. Inserisci la località di Cloud Storage dei tuoi dati.
  6. Fai clic su Import (Importa).

BigQuery

  1. Fai clic su Importa eventi utente per aprire il riquadro Importa dati.
  2. Scegli Eventi utente.
  3. Seleziona BigQuery come origine dati.
  4. Scegli Schema eventi utente di vendita al dettaglio come schema.
  5. Inserisci la tabella BigQuery in cui si trovano i tuoi dati.
  6. (Facoltativo) Inserisci la località di un bucket Cloud Storage nel progetto come località temporanea per i tuoi dati.
    Se non specificato, viene utilizzata una località predefinita. Se specificato, il bucket BigQuery e Cloud Storage devono trovarsi nella stessa area geografica.
  7. (Facoltativo) In Mostra opzioni avanzate, inserisci la località di un bucket Cloud Storage nel progetto come località temporanea per i tuoi dati.

    Se non è specificato, viene utilizzata una località predefinita. Se specificato, il bucket BigQuery e Cloud Storage devono trovarsi nella stessa area geografica.
  8. Fai clic su Import (Importa).

Crea una configurazione di pubblicazione

Una configurazione per la pubblicazione è un'entità di pubblicazione che associa un modello o un insieme di controlli utilizzati per generare i risultati di ricerca o di consigli.

Per creare una configurazione di pubblicazione:

  1. Nel riquadro Configurazioni di pubblicazione, fai clic su Crea configurazione di pubblicazione.
  2. Nella pagina Crea configurazione di pubblicazione, scegli Ricerca come prodotto per il quale verrà utilizzata la configurazione della pubblicazione.
  3. Specifica un nome per la configurazione di pubblicazione.

    Il nome deve avere una lunghezza massima di 1024 caratteri e può contenere solo caratteri alfanumerici, trattini bassi, trattini e spazi.
  4. (Facoltativo) Se necessario, aggiorna l'ID.

    L'ID viene generato dal nome fornito e deve essere univoco all'interno del progetto. Deve contenere un massimo di 50 caratteri e non può contenere spazi.
  5. Fai clic su Continua.
  6. Scegli se attivare il facet dinamico per questa configurazione di pubblicazione.
  7. Scegli o crea controlli di pubblicazione con cui ottimizzare le ricerche.

    Per ulteriori informazioni sui controlli, consulta Creazione e gestione dei controlli.

Dashboard per la vendita al dettaglio

Dopo aver completato la configurazione iniziale del progetto, nella console retail viene visualizzato lo stato del sistema dell'API Retail. La console Retail consente di gestire le risorse retail e di monitorarne l'attività.

Vai a Google Cloud Console per il retail

Per ulteriori informazioni sulla console di vendita al dettaglio, consulta la Console di amministrazione per la vendita al dettaglio.

Configurare l'autenticazione per l'applicazione

Per accedere all'API Retail devi configurare entrambi i metodi di autenticazione seguenti:

  • Account di servizio: le applicazioni utilizzano un account di servizio per autenticare le chiamate a Product.

  • Chiave API: le applicazioni utilizzano una chiave API per le chiamate alle API user event logging.

Crea un account di servizio

  1. Vai alla pagina Credenziali di Google Cloud Console.

  2. Seleziona il progetto per cui stai creando le credenziali (il progetto potrebbe essere già selezionato).

  3. Fai clic su Crea credenziali, quindi seleziona Chiave account di servizio.

  4. Compila i seguenti campi:

    Campo Valore
    Account di servizio Nuovo account di servizio
    Nome account di servizio enter a name for your service account
    Ruolo Account di servizio > Creator account token di servizio
    Retail > Editor retail
    Tipo di chiave JSON
  5. Fai clic su Crea per creare l'account di servizio.

    Il file JSON contenente la chiave pubblica/privata per il nuovo account di servizio viene scaricato automaticamente sul computer. Questo file JSON è l'unica copia della chiave per il tuo account di servizio. Assicurati di conservarlo in una posizione sicura. Il file della chiave JSON deve essere archiviato in una posizione accessibile dalla tua applicazione (vedi your-service-account-json-key-file in Autenticarsi utilizzando un account di servizio (OAuth 2.0).

Aggiungi l'account di servizio al tuo ambiente locale

Se vuoi effettuare chiamate all'API Retail utilizzando lo strumento a riga di comando cURL, devi rendere disponibile il tuo account di servizio nel tuo ambiente locale. cURL utilizza il comando gcloud auth application-default print-access-token per ottenere un token di accesso per il tuo account di servizio utilizzando l'interfaccia a riga di comando di Google Cloud. Per scaricare e installare l'interfaccia a riga di comando gcloud, vedi gcloud CLI. Se utilizzi Cloud Shell, l'interfaccia a riga di comando gcloud è già installata.

La variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS non continuerà a esistere se chiudi la finestra di comando. Per assicurarti che la variabile sia impostata sul percorso del file dell'account di servizio quando apri una nuova finestra di comando, imposta il valore in uno script shell di inizializzazione.

  export GOOGLE_APPLICATION_CREDENTIALS=path-to-service-account-json-key-file

Crea una chiave API

  1. Vai alla pagina Credenziali di Google Cloud Console.

  2. Nel menu a discesa del progetto nella parte superiore della pagina di Google Cloud Console, seleziona il progetto in modo da selezionarlo già.

  3. Fai clic su Crea credenziali e seleziona Chiave API. Non aggiungere restrizioni per i referrer. Alcune impostazioni sulla privacy dell'utente sono note per non passare l'URL del referrer.

    • Prendi nota della chiave API generata, che utilizzerai per chiamare il logging degli eventi utente.
  4. Per maggiore sicurezza, aggiungi una limitazione HTTP alla tua chiave API per limitare l'accesso al servizio Retail all'indirizzo https://retail.googleapis.com/*.

Esempi

Autenticazione con un account di servizio (OAuth 2.0)

Ecco un esempio in Java di autenticazione OAuth 2.0 tramite account di servizio. Istruzioni più dettagliate sono disponibili nella documentazione sull'autenticazione. Google offre librerie client in 7 lingue che puoi utilizzare per implementare l'autenticazione OAuth2 nella tua applicazione. Se preferisci implementare direttamente il protocollo HTTP/REST, segui le istruzioni per l'autenticazione REST.

Nell'esempio, sostituisci your-service-account-json-key-file con il percorso del file della chiave JSON dell'account di servizio.

// Simple Java example of using Google Cloud OAuth client library.
//
// Please see here for the list of libraries in different languages:
// https://developers.google.com/identity/protocols/OAuth2#libraries
//
// The following example depends on the google api client library.
//
// Maven:
//    <dependency>
//      <groupId>com.google.api-client</groupId>
//      <artifactId>google-api-client</artifactId>
//      <version>1.22.0</version>
//    </dependency>
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.GenericJson;
import com.google.api.client.json.jackson2.JacksonFactory;
import java.io.FileInputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class RetailApiSample {
  public static final String CREATE_PRODUCT_URL =
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products";

  public static GoogleCredential authorize() throws Exception {
    return GoogleCredential.fromStream(new FileInputStream("your-service-account-json-key-file"))
        .createScoped(Collections.singleton("https://www.googleapis.com/auth/cloud-platform"))
        .setExpirationTimeMilliseconds(new Long(3600 * 1000));;
  }

  // Build an example product.
  public static GenericJson getProduct() {
    GenericJson categories = new GenericJson()
        .set("categories", Arrays.asList("Electronics > Computers", "Laptops"));
    GenericJson priceInfo = new GenericJson()
        .set("currency_code", "USD")
        .set("price", 800.00)
        .set("original_price", 1000.00);

    return new GenericJson()
        .set("name", "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/[ProductName]")
        .set("title", "Sample Laptop")
        .set("description", "Indisputably the most fantastic laptop ever created.")
        .set("categories", categories)
        .set("price_info", priceInfo)
        .set("availability", "IN_STOCK")
        .set("available_quantity", 1219);
  }

  public static void main(String[] args) {
    try {
      GoogleCredential credential = RetailApiSample.authorize();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      HttpRequestFactory requestFactory = httpTransport.createRequestFactory();
      HttpRequest request = requestFactory.buildPostRequest(new GenericUrl(CREATE_PRODUCT_URL),
          new JsonHttpContent(new JacksonFactory(), RetailApiSample.getProduct()));
      credential.initialize(request);
      HttpResponse response = request.execute();
      System.out.println("Response content: " + response.parseAsString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Passaggi successivi