Prima di iniziare

Creare un progetto Google Cloud

  1. Nella pagina Gestisci risorse della console Google Cloud, 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 su un progetto.

Configurare l'API Retail

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

Per configurare l'API Retail, completa i seguenti passaggi:

  1. Vai alla pagina Retail nella console Google Cloud.

    Vai alla pagina Retail

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

  3. Quando API Retail e 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 relativi all'utilizzo dei dati.

    Quando accetti i termini per l'utilizzo dei dati, la console Google Cloud indica che sono stati accettati i termini per l'utilizzo dei dati dell'API Retail.

  5. Se vuoi utilizzare il progetto solo con i suggerimenti, fai clic su Inizia.

  6. Se vuoi attivare Retail Search oltre a Consigli, segui questi passaggi:

    1. Fai clic su Continua, quindi su Attiva nella pagina Attiva Retail Search (facoltativo).
    2. Fai clic su Inizia.

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

Configura l'API Retail per un progetto esistente

Se hai configurato l'API Retail in un progetto Google Cloud prima dell'entrata in vigore dei termini sull'utilizzo dei dati 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 Retail Search per quel progetto, se necessario.

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

  1. Vai alla pagina Retail nella console Google Cloud per il tuo progetto.

    Vai alla pagina Retail

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

  3. Se vuoi utilizzare il progetto solo con i suggerimenti, fai clic su Inizia.

  4. Se vuoi attivare Retail Search oltre a Consigli, segui questi passaggi:

    1. Fai clic su Continua, quindi su Attiva nella pagina Attiva Retail Search (facoltativo).
    2. Fai clic su Inizia.

Disattivare l'API Retail Search o l'API Retail

Disattiva Retail Search

Se non vuoi più utilizzare Retail Search, puoi disattivarlo inviando un ticket di assistenza.

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

  • Categoria: Machine learning
  • Componente: Retail Solutions: Retail Search
  • Sottocomponente: Amministrazione account e fatturazione

Per ulteriori informazioni sulla creazione di un ticket di assistenza, consulta Richiesta di assistenza.

Disattivare l'API Retail

Puoi disattivare l'API Retail in qualsiasi momento. Vengono disattivati sia i consigli che Retail Search.

Per disattivare l'API Retail, completa i seguenti passaggi:

  1. Vai alla pagina Dettagli servizio API Retail nella console Google Cloud.

    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.

Inizia a utilizzare l'API Retail

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

  • Dati > Catalogo: mostra il catalogo dei prodotti e un link per importare il catalogo.

  • Dati > Eventi: visualizza gli eventi utente e un link per importare gli eventi utente storici.

  • Configurazioni di pubblicazione: contiene 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.

Importa il catalogo dei prodotti

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

Sincronizzazione Merchant Center

  1. Fai clic su Importa catalogo dei 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. Controlla la sezione Accesso utenti se non visualizzi il tuo account.
  5. (Facoltativo) Seleziona Filtro feed di Merchant Center per importare solo le offerte dai feed selezionati.

    Se non specificato, verranno importate le offerte di tutti i feed (inclusi quelli futuri).
  6. (Facoltativo) Per importare solo le offerte indirizzate a determinati paesi o lingue, espandi Mostra opzioni avanzate e seleziona i paesi di vendita e le lingue di Merchant Center in base a cui filtrare.
  7. Seleziona il ramo in cui caricherai il catalogo.
  8. Fai clic su Importa.

Cloud Storage

  1. Fai clic su Importa catalogo dei prodotti per aprire il riquadro Importa dati.
  2. Scegli Catalogo dei prodotti come origine dati.
  3. Seleziona il ramo in cui caricherai il catalogo.
  4. Scegli Schema cataloghi dei prodotti per la 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. Modificare i livelli dei prodotti dopo l'importazione dei dati richiede un impegno significativo.

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

BigQuery

  1. Fai clic su Importa catalogo dei prodotti per aprire il riquadro Importa dati.
  2. Scegli Catalogo dei prodotti.
  3. Seleziona BigQuery come origine dati.
  4. Seleziona il ramo in cui caricherai il catalogo.
  5. Scegli uno dei seguenti schemi:
  6. Inserisci la tabella BigQuery in cui si trovano i 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 specificata, viene utilizzata una località predefinita. Se specificato, il bucket BigQuery e il bucket Cloud Storage devono trovarsi nella stessa regione.
  8. Se Retail Search non è abilitato e utilizzi lo schema di Merchant Center, seleziona il livello di prodotto.

    Devi selezionare il livello 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. Modificare i livelli dei prodotti dopo l'importazione dei dati richiede un impegno significativo.

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

Importa i tuoi eventi utente storici

Per importare gli eventi utente storici, completa la procedura per l'origine dati. Per ulteriori informazioni sulla cronologia degli eventi utente, 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 per la vendita al dettaglio come schema.
  5. Inserisci la località di Cloud Storage dei tuoi dati.
  6. Fai clic su 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. Seleziona lo schema dei dati.

  5. Inserisci la tabella BigQuery in cui si trovano i dati.
  6. (Facoltativo) Inserisci la località di un bucket Cloud Storage nel progetto come località temporanea per i dati.
    Se non specificata, viene utilizzata una località predefinita. Se specificato, il bucket BigQuery e il bucket Cloud Storage devono trovarsi nella stessa regione.
  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 specificata, viene utilizzata una località predefinita. Se specificato, il bucket BigQuery e il bucket Cloud Storage devono trovarsi nella stessa regione.
  8. Fai clic su Importa.

Crea una configurazione di pubblicazione

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

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 cui verrà utilizzata la configurazione di 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 che hai fornito e deve essere univoco in tutto il progetto. Deve avere una lunghezza massima di 50 caratteri e non può contenere spazi.
  5. Fai clic su Continua.
  6. Scegli se attivare il faceting 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

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

Vai alla console Google Cloud Retail

Configura l'autenticazione per l'app

Devi configurare l'autenticazione in modo che le app, ad esempio il tuo sito di e-commerce, possano accedere all'API Retail:

  • Account di servizio. Le app utilizzano un account di servizio per autenticare le chiamate a Product. Per configurare un account di servizio, consulta la sezione Creare un account di servizio di seguito.

  • Chiave API. Le app utilizzano una chiave API per le chiamate al metodo userEvents.Collect. Devi configurare questo metodo di autenticazione solo se intendi acquisire gli eventi utente dai browser degli utenti tramite un pixel JavaScript o Google Tag Manager. Per configurare una chiave API, consulta la sezione Creare una chiave API di seguito.

Crea un account di servizio

  1. Vai alla pagina Credenziali della console Google Cloud.

  2. Seleziona il progetto in cui stai creando un account di servizio (il progetto potrebbe essere già selezionato).

  3. Fai clic su Crea credenziali e seleziona Account di servizio.

    Viene visualizzata la pagina Crea account di servizio.

  4. In Dettagli account di servizio, compila i seguenti campi:

    • Nome account di servizio: il nome visualizzato dell'account di servizio.
    • ID account di servizio: un nome univoco per l'account di servizio. Puoi utilizzare l'ID predefinito fornito o sostituirlo con un ID personalizzato.
    • Descrizione dell'account di servizio: facoltativa. Una descrizione dell'account.
  5. Fai clic su Crea e continua per creare l'account di servizio e procedere con la concessione dell'accesso all'account di servizio al tuo progetto.

  6. In Concedi a questo account di servizio l'accesso al progetto, aggiungi i seguenti ruoli:

    • Account di servizio > Creatore token account di servizio
    • Altro > Editor Retail
  7. (Facoltativo) Per concedere l'accesso all'account di servizio a utenti o gruppi che devono eseguire azioni per conto di questo account di servizio, fai clic su Continua e inserisci i dati dell'account dell'utente o del gruppo.

  8. Fai clic su Fine per salvare le modifiche.

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.

Per ottenere un file JSON della chiave dell'account di servizio, segui le istruzioni in Creare e gestire gli account di servizio.

Il file JSON contiene la chiave pubblica/privata del tuo account di servizio. Questo file JSON è l'unica copia della chiave per il tuo account di servizio. Assicurati di conservarlo in un luogo sicuro.

Il file della chiave JSON deve essere archiviato in una posizione accessibile dalla tua app.

cURL utilizza il comando gcloud auth application-default print-access-token per ottenere un token di accesso per il tuo account di servizio utilizzando Google Cloud CLI. Per scaricare e installare gcloud CLI, vedi gcloud CLI. Se usi Cloud Shell, gcloud CLI è già installato.

La variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS non durerà 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

È necessaria una chiave API se utilizzi un pixel JavaScript o un tag di Tag Manager per acquisire gli eventi utente dai browser degli utenti. Per ulteriori informazioni su come acquisire gli eventi utente, consulta Registrare eventi utente in tempo reale.

Per creare una chiave API per le chiamate al metodo userEvents.Collect, completa i seguenti passaggi:

  1. Vai alla pagina Credenziali della console Google Cloud.

  2. Nel menu a discesa del progetto nella parte superiore della pagina della console Google Cloud, seleziona il tuo progetto (potrebbe essere già selezionato).

  3. Fai clic su Crea credenziali e seleziona Chiave API. Non aggiungere limitazioni alle applicazioni per i siti web. Alcune impostazioni sulla privacy dell'utente non trasmettono l'URL referrer.

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

Esempi

Esegui l'autenticazione utilizzando un account di servizio (OAuth 2.0)

Ecco un esempio Java di autenticazione OAuth 2.0 mediante un account di servizio. Istruzioni più dettagliate sono disponibili nella documentazione per l'autenticazione. Google dispone di librerie client in sette lingue che puoi utilizzare per implementare l'autenticazione OAuth2 nella tua app. Se preferisci implementare direttamente HTTP/REST, segui le istruzioni per l'autenticazione REST.

Nell'esempio, sostituisci your-service-account-json-key-file con il percorso al file di chiavi JSON per il tuo 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