Importa le informazioni del catalogo

Questa pagina descrive come importare le informazioni del catalogo e mantenerle aggiornate.

Le procedure di importazione in questa pagina si applicano sia ai consigli sia alla ricerca. Dopo aver importato i dati, entrambi i servizi possono utilizzarli, quindi non è necessario importarli due volte se utilizzi entrambi i servizi.

Importa dati del catalogo da BigQuery

Questo tutorial mostra come utilizzare una tabella BigQuery per importare grandi quantità di dati di catalogo senza limiti.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Importare i dati di catalogo da Cloud Storage

Questo tutorial mostra come importare un numero elevato di articoli in un catalogo.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Importa i dati del catalogo in linea

Questo tutorial mostra come importare i prodotti in un catalogo in linea.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Prima di iniziare

Prima di poter importare le informazioni del catalogo, devi aver completato le istruzioni riportate in Prima di iniziare, in particolare configurare il progetto, creare un account di servizio e aggiungere l'account di servizio al tuo ambiente locale.

Per eseguire l'importazione, devi disporre del ruolo IAM Amministratore retail.

Best practice per l'importazione del catalogo

Per generare risultati di alta qualità sono necessari dati di alta qualità. Se i dati mancano di campi o contengono valori segnaposto anziché valori effettivi, la qualità delle previsioni e dei risultati di ricerca peggiora.

Quando importi i dati del catalogo, assicurati di implementare le seguenti best practice:

  • Assicurati di valutare attentamente quali prodotti o gruppi di prodotti sono principali e quali sono le varianti. Prima di caricare i dati, consulta la sezione Livelli di prodotto.

    Modificare la configurazione a livello di prodotto dopo aver importato i dati richiede un impegno significativo.

    Gli elementi principali vengono restituiti come risultati di ricerca o consigli. Gli articoli delle varianti non lo sono.

    Ad esempio, se il gruppo di SKU principale è "Camicia a V", il modello di consigli restituisce un articolo di camicia a V e, forse, una camicia a girocollo e una a scollo a V. Tuttavia, se le varianti non vengono utilizzate e ogni SKU è principale, ogni combinazione di colore/taglia della camicia con scollo a V viene restituita come articolo distinto nel riquadro dei consigli: "Camicia con scollo a V marrone, taglia XL", "Camicia con scollo a V marrone, taglia L", fino a "Camicia con scollo a V bianca, taglia M", "Camicia con scollo a V bianca, taglia S".

    Le collezioni possono essere riconosciute insieme, a condizione che gli ID variante siano inclusi insieme agli ID prodotto principali in collectionMemberIds[]. Di conseguenza, nell'evento utente viene acquisita una raccolta di prodotti, da cui un utente potrebbe aver acquistato uno o più prodotti del set, accreditando l'intero set all'acquisto. In questo modo, sarà più facile mostrare allo stesso utente altri prodotti di una determinata collezione in una query correlata futura. Ad esempio, vengono restituiti altri prodotti di una collezione di lenzuola, come le federe e il lenzuolo con angoli abbinati, dopo che un utente ha già acquistato il copripiumino.

  • Rispetta i limiti di importazione degli articoli del prodotto.

    Per l'importazione collettiva da Cloud Storage, le dimensioni di ogni file devono essere inferiori o uguali a 2 GB. Puoi includere fino a 100 file alla volta in un'unica richiesta di importazione collettiva.

    Per l'importazione in linea, non importare più di 5000 articoli del prodotto alla volta.

  • Assicurati che tutte le informazioni richieste per il catalogo siano incluse e corrette.

    Non utilizzare valori segnaposto.

  • Includi il maggior numero possibile di informazioni facoltative sul catalogo.

  • Assicurati che tutti gli eventi utilizzino una singola valuta, in particolare se prevedi di utilizzare la console Google Cloud per ottenere le metriche relative alle entrate. L'API Vertex AI Search for Retail non supporta l'utilizzo di più valute per catalogo.

  • Mantieni aggiornato il catalogo.

    Idealmente, dovresti aggiornare il tuo catalogo ogni giorno. La pianificazione delle importazioni periodiche del catalogo impedisce il calo della qualità del modello nel tempo. Puoi pianificare importazioni automatiche e ricorrenti quando importi il tuo catalogo utilizzando la console Ricerca per la vendita al dettaglio. In alternativa, puoi utilizzare Google Cloud Scheduler per automatizzare le importazioni.

  • Non registrare gli eventi utente per gli articoli dei prodotti che non sono stati ancora importati.

  • Dopo aver importato le informazioni del catalogo, esamina le informazioni di generazione di report sugli errori e di registrazione per il tuo progetto.

    È normale che si verifichino alcuni errori, ma se il numero è elevato, devi esaminarli e correggere eventuali problemi di elaborazione che li hanno causati.

Informazioni sull'importazione dei dati del catalogo

Puoi importare i dati di prodotto da Merchant Center, Cloud Storage, BigQuery o specificare i dati in linea nella richiesta. Ognuna di queste procedure è un'importazione una tantum, con l'eccezione del collegamento di Merchant Center. Pianifica importazioni regolari del catalogo (idealmente giornaliere) per assicurarti che sia aggiornato. Consulta Mantieni il catalogo aggiornato.

Puoi anche importare singoli articoli di prodotto. Per ulteriori informazioni, consulta la sezione Caricare un prodotto.

Considerazioni sull'importazione del catalogo

Questa sezione descrive i metodi che possono essere utilizzati per l'importazione collettiva dei dati del catalogo, quando è possibile utilizzare ciascun metodo e alcune delle relative limitazioni.

Sincronizzazione di Merchant Center Descrizione Importa i dati del catalogo tramite Merchant Center collegando l'account a Vertex AI Search per il retail. Dopo il collegamento, gli aggiornamenti ai dati del catalogo in Merchant Center vengono sincronizzati in tempo reale con Vertex AI Search per il retail.
Quando utilizzarli Se hai già un'integrazione con Merchant Center.
Limitazioni Supporto limitato degli schemi. Ad esempio, le collezioni di prodotti non sono supportate da Merchant Center. Merchant Center diventa l'origine attendibile dei dati finché non viene scollegato, pertanto tutti gli attributi personalizzati necessari devono essere aggiunti ai dati di Merchant Center.

Controllo limitato. Non puoi specificare determinati campi o insiemi di elementi da importare da Merchant Center; tutti gli elementi e i campi esistenti in Merchant Center vengono importati.
BigQuery Descrizione Importa i dati da una tabella BigQuery caricata in precedenza che utilizza lo schema di Vertex AI Search per la vendita al dettaglio o lo schema di Merchant Center. Può essere eseguita utilizzando la console Google Cloud o curl.
Quando utilizzarli Se hai cataloghi di prodotti con molti attributi. L'importazione di BigQuery utilizza lo schema di ricerca di Vertex AI per la vendita al dettaglio, che ha più attributi del prodotto rispetto ad altre opzioni di importazione, inclusi gli attributi personalizzati chiave/valore.

Se hai volumi di dati elevati. L'importazione di BigQuery non ha un limite di dati.

Se utilizzi già BigQuery.
Limitazioni Richiede il passaggio aggiuntivo della creazione di una tabella BigQuery che mappa allo schema di Vertex AI Search per il retail.
Cloud Storage Descrizione Importa i dati in formato JSON dai file caricati in un bucket Cloud Storage. Ogni file deve avere dimensioni non superiori a 2 GB ed è possibile importare fino a 100 file alla volta. L'importazione può essere eseguita utilizzando la console Google Cloud o curl. Utilizza il formato di dati JSON Product, che consente attributi personalizzati.
Quando utilizzarli Se devi caricare una grande quantità di dati in un unico passaggio.
Limitazioni Non è ideale per i cataloghi con aggiornamenti frequenti di inventario e prezzi perché le modifiche non vengono applicate immediatamente.
Importazione in linea Descrizione Esegui l'importazione utilizzando una chiamata al metodo Product.import. Utilizza l'oggetto ProductInlineSource, che ha meno attributi del catalogo di prodotti rispetto allo schema di Vertex AI Search for Retail, ma supporta gli attributi personalizzati.
Quando utilizzarli Se hai dati di cataloghi non relazionali e semplici o se hai aggiornamenti frequenti di quantità o prezzi.
Limitazioni Non è possibile importare più di 100 articoli del catalogo alla volta. Tuttavia, è possibile eseguire molti passaggi di caricamento; non è previsto alcun limite di elementi.

Eliminare definitivamente i branch del catalogo

Se stai importando nuovi dati di catalogo in un ramo esistente, è importante che il ramo del catalogo sia vuoto. In questo modo viene garantita l'integrità dei dati importati nel ramo. Quando il ramo è vuoto, puoi importare i nuovi dati del catalogo e poi collegarlo a un account commerciante.

Se stai pubblicando traffico di ricerca o di previsione in tempo reale e prevedi di eliminare il ramo predefinito, ti consigliamo di specificare prima un altro ramo come predefinito prima di procedere con l'eliminazione. Poiché il branch predefinito pubblicherà risultati vuoti dopo l'eliminazione, l'eliminazione di un branch predefinito attivo può causare un'interruzione del servizio.

Per eliminare i dati da un ramo del catalogo:

  1. Vai alla pagina Dati> nella console Ricerca per la vendita al dettaglio.

    Vai alla pagina Dati

  2. Seleziona un branch del catalogo dal campo Nome branch.

  3. Nel menu con tre puntini accanto al campo Nome agenzia, scegli Svuota agenzia.

    Viene visualizzato un messaggio che ti avvisa che stai per eliminare tutti i dati del ramo, nonché gli eventuali attributi creati per il ramo.

  4. Inserisci il ramo e fai clic su Conferma per eliminare definitivamente i dati del catalogo dal ramo.

    Viene avviata un'operazione a lunga esecuzione per eliminare definitivamente i dati dal branch del catalogo. Al termine dell'operazione di eliminazione definitiva, lo stato dell'eliminazione viene visualizzato nell'elenco Catalogo dei prodotti nella finestra Stato attività.

Sincronizzare Merchant Center con Vertex AI Search per il retail

Per la sincronizzazione continua tra Merchant Center e Vertex AI Search per la vendita al dettaglio, puoi collegare il tuo account Merchant Center a Vertex AI Search per la vendita al dettaglio. Dopo il collegamento, le informazioni del catalogo nel tuo account Merchant Center vengono importate immediatamente in Vertex AI Search per la vendita al dettaglio.

Quando configuri una sincronizzazione di Merchant Center per Vertex AI Search for Retail, devi disporre del ruolo Amministratore assegnato in Merchant Center. Sebbene un ruolo di accesso standard ti consenta di leggere i feed di Merchant Center nell'interfaccia utente, quando provi a sincronizzare Merchant Center con Vertex AI Search for Retail, riceverai un messaggio di errore. Pertanto, prima di poter sincronizzare Merchant Center con Vertex AI Search per il retail, devi eseguire l'upgrade del tuo ruolo di conseguenza.

Anche se Vertex AI Search for Retail è collegato all'account Merchant Center, le modifiche ai dati di prodotto nell'account Merchant Center vengono aggiornate automaticamente in Vertex AI Search for Retail entro pochi minuti. Se vuoi impedire la sincronizzazione delle modifiche di Merchant Center con Vertex AI Search per la vendita al dettaglio, puoi scollegare il tuo account Merchant Center.

Lo scollegamento dell'account Merchant Center non comporta l'eliminazione di alcun prodotto in Vertex AI Search per la vendita al dettaglio. Per eliminare i prodotti importati, consulta la sezione Eliminare le informazioni sul prodotto.

Per sincronizzare il tuo account Merchant Center, completa i seguenti passaggi.

Console

  1. Vai alla pagina Dati> nella console Ricerca per la vendita al dettaglio.

    Vai alla pagina Dati
  2. Fai clic su Importa per aprire il riquadro Importa dati.
  3. Scegli Catalogo prodotti.
  4. Seleziona Sincronizzazione di Merchant Center come origine dati.
  5. Seleziona il tuo account Merchant Center. Seleziona Accesso utente se non vedi il tuo account.
  6. (Facoltativo) Seleziona Filtro dei feed di Merchant Center per importare solo le offerte dei feed selezionati.

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

curl

  1. Verifica che l'account di servizio nel tuo ambiente locale abbia accesso sia all'account Merchant Center sia a Vertex AI Search per la vendita al dettaglio. Per controllare quali account hanno accesso al tuo account Merchant Center, consulta Accesso utente per Merchant Center.

  2. Utilizza il metodo MerchantCenterAccountLink.create per stabilire il collegamento.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
  "merchantCenterAccountId": MERCHANT_CENTER_ID,
  "branchId": "BRANCH_ID",
  "feedFilters": [
    {"primaryFeedId": PRIMARY_FEED_ID_1}
    {"primaryFeedId": PRIMARY_FEED_ID_2}
  ],
  "languageCode": "LANGUAGE_CODE",
  "feedLabel": "FEED_LABEL",
 }' \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"
    • MERCHANT_CENTER_ID: l'ID dell'account Merchant Center.
    • BRANCH_ID: l'ID del ramo con cui stabilire il collegamento. Accetta i valori "0", "1" o "2".
    • LANGUAGE_CODE: (FACOLTATIVO) il codice lingua di due lettere dei prodotti che vuoi importare. Come mostrato in Merchant Center nella colonna Language del prodotto. Se non è impostato, vengono importate tutte le lingue.
    • FEED_LABEL: (FACOLTATIVO) l'etichetta del feed dei prodotti che vuoi importare. Puoi visualizzare l'etichetta del feed in Merchant Center nella colonna Etichetta feed del prodotto. Se non è impostato, vengono importate tutte le etichette del feed.
    • FEED_FILTERS: (FACOLTATIVO) Elenco dei feed principali da cui verranno importati i prodotti. Se non selezioni i feed, tutti i feed dell'account Merchant Center vengono condivisi. Gli ID si trovano nella risorsa Feed di dati dell'API Content o visitando Merchant Center, selezionando un feed e ottenendo l'ID feed dal parametro dataSourceId nell'URL del sito. Ad esempio, mc/products/sources/detail?a=MERCHANT_CENTER_ID&dataSourceId=PRIMARY_FEED_ID.

Per visualizzare Merchant Center collegato, vai alla pagina Dati della console Ricerca per la vendita al dettaglio e fai clic sul pulsante Merchant Center in alto a destra nella pagina. Si aprirà il riquadro Account Merchant Center collegati. Da questo riquadro puoi anche aggiungere altri account Merchant Center.

Consulta Visualizzare informazioni aggregate sul catalogo per istruzioni su come visualizzare i prodotti importati.

Elenca i link del tuo account Merchant Center.

Console

  1. Vai alla pagina Dati> nella console Ricerca per la vendita al dettaglio.

    Vai alla pagina Dati

  2. Fai clic sul pulsante Merchant Center in alto a destra nella pagina per aprire un elenco dei tuoi account Merchant Center collegati.

curl

Utilizza il metodo MerchantCenterAccountLink.list per elencare la risorsa dei link.

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"

Se scolleghi il tuo account Merchant Center, questo non sincronizzerà più i dati del catalogo con Vertex AI Search per la vendita al dettaglio. Questa procedura non elimina i prodotti in Vertex AI Search for Retail che sono già stati caricati.

Console

  1. Vai alla pagina Dati> nella console Ricerca per la vendita al dettaglio.

    Vai alla pagina Dati

  2. Fai clic sul pulsante Merchant Center in alto a destra nella pagina per aprire un elenco dei tuoi account Merchant Center collegati.

  3. Fai clic su Scollega accanto all'account Merchant Center che stai scollegando e conferma la tua scelta nella finestra di dialogo visualizzata.

curl

Utilizza il metodo MerchantCenterAccountLink.delete per rimuovere la risorsa MerchantCenterAccountLink.

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

Limitazioni relative al collegamento a Merchant Center

  • Un account Merchant Center può essere collegato a un numero qualsiasi di rami del catalogo, ma un singolo ramo del catalogo può essere collegato a un solo account Merchant Center.

  • Un account Merchant Center non può essere un account multi-cliente (AMC). Tuttavia, puoi collegare singoli subaccount.

  • La prima importazione dopo il collegamento dell'account Merchant Center potrebbe richiedere diverse ore. La quantità di tempo dipende dal numero di offerte nell'account Merchant Center.

  • Eventuali modifiche ai prodotti che utilizzano i metodi dell'API sono disabilitate per i rami collegati a un account Merchant Center. Eventuali modifiche ai dati del catalogo dei prodotti in questi reparti devono essere apportate utilizzando Merchant Center. Queste modifiche vengono quindi sincronizzate automaticamente con Vertex AI Search per il retail.

  • Il tipo di prodotto della collezione non è supportato per i reparti che utilizzano il collegamento a Merchant Center.

  • Il tuo account Merchant Center può essere collegato solo a rami del catalogo vuoti per garantire la correttezza dei dati. Per eliminare i prodotti da un ramo del catalogo, consulta Eliminare le informazioni sul prodotto.

Importare i dati del catalogo da Merchant Center

Merchant Center è uno strumento che puoi utilizzare per rendere disponibili i dati del tuo negozio e dei tuoi prodotti per gli annunci Shopping e altri servizi Google.

Puoi importare collettivamente i dati del catalogo da Merchant Center come procedura singola da BigQuery utilizzando lo schema di Merchant Center (solo consigli).

Importazione collettiva da Merchant Center

Puoi importare i dati del catalogo da Merchant Center utilizzando la console Ricerca per la vendita al dettaglio o il metodo products.import. L'importazione collettiva è una procedura una tantum ed è supportata solo per i consigli.

Per importare il tuo catalogo da Merchant Center, segui questi passaggi:

  1. Segui le istruzioni riportate in Trasferimenti di Merchant Center per configurare un trasferimento da Merchant Center a BigQuery.

    Dovrai utilizzare lo schema della tabella dei prodotti di Google Merchant Center. Configura il trasferimento in modo che si ripeta ogni giorno, ma configura la data di scadenza del set di dati su 2 giorni.

  2. Se il tuo set di dati BigQuery si trova in un altro progetto, configura le autorizzazioni richieste in modo che Vertex AI Search per la vendita al dettaglio possa accedere al set di dati BigQuery. Scopri di più.

  3. Importa i dati del tuo catalogo da BigQuery in Vertex AI Search per la vendita al dettaglio.

    Console

    1. Vai alla pagina Dati> nella console Ricerca per la vendita al dettaglio.

      Vai alla pagina Dati

    2. Fai clic su Importa per aprire il riquadro Importa.

    3. Scegli Catalogo prodotti.

    4. Seleziona BigQuery come origine dati.

    5. Seleziona il branch su cui caricherai il catalogo.

    6. Seleziona Merchant Center come schema di dati.

    7. Inserisci la tabella BigQuery in cui si trovano i dati.

    8. (Facoltativo) Inserisci la posizione di un bucket Cloud Storage nel tuo progetto come posizione temporanea per i dati.

      Se non specificato, viene utilizzata una posizione predefinita. Se specificato, i bucket BigQuery e Cloud Storage devono trovarsi nella stessa regione.

    9. Scegli se pianificare un caricamento ricorrente dei dati del catalogo.

    10. Se è la prima volta che importi il catalogo o lo stai rielaborando dopo averlo eliminato definitivamente, seleziona i livelli di prodotto. Scopri di più sui livelli dei prodotti.

      Modificare la configurazione a livello di prodotto dopo aver importato i dati richiede un impegno significativo.

      .

    11. Fai clic su Importa.

    curl

    1. Se è la prima volta che carichi il catalogo o lo stai nuovamente importando dopo averlo svuotato, imposta i livelli di prodotto utilizzando il metodo Catalog.patch. Questa operazione richiede il ruolo Amministratore vendita al dettaglio. Scopri di più sui livelli dei prodotti.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
--data '{
"productLevelConfig": {
  "ingestionProductType": "PRODUCT_TYPE",
  "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
}
}' \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

    2. Importa il catalogo utilizzando il metodo Products.import.

      • DATASET_ID: l'ID del set di dati BigQuery.
      • TABLE_ID: l'ID della tabella BigQuery che contiene i dati.
      • STAGING_DIRECTORY: facoltativo. Una directory Cloud Storage utilizzata come posizione intermedia per i dati prima che vengano importati in BigQuery. Lascia vuoto questo campo per creare automaticamente una directory temporanea (opzione consigliata).
      • ERROR_DIRECTORY: facoltativo. Una directory Cloud Storage per le informazioni sugli errori relativi all'importazione. Lascia vuoto questo campo per creare automaticamente una directory temporanea (opzione consigliata).
      • dataSchema: per la proprietà dataSchema, utilizza il valore product_merchant_center. Consulta lo schema della tabella dei prodotti di Merchant Center.

      Ti consigliamo di non specificare le directory di gestione temporanea o degli errori, in modo da creare automaticamente un bucket Cloud Storage con nuove directory di gestione temporanea e degli errori. Queste directory vengono create nella stessa regione del set di dati BigQuery e sono univoche per ogni importazione (il che impedisce a più job di importazione di eseguire il staging dei dati nella stessa directory e potenzialmente di reimportare gli stessi dati). Dopo tre giorni, il bucket e le directory vengono eliminati automaticamente per ridurre i costi di archiviazione.

      Un nome del bucket creato automaticamente include l'ID progetto, la regione del bucket e il nome dello schema di dati, separati da trattini bassi (ad esempio, 4321_us_catalog_retail). Le directory create automaticamente si chiamano staging o errors, con un numero aggiunto (ad esempio, staging2345 o errors5678).

      Se specifichi le directory, il bucket Cloud Storage deve trovarsi nella stessa regione del set di dati BigQuery, altrimenti l'importazione non andrà a buon fine. Fornisci le directory di staging e degli errori nel formato gs://<bucket>/<folder>/; devono essere diverse. 

      curl -X POST \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "inputConfig":{
            "bigQuerySource": {
              "datasetId":"DATASET_ID",
              "tableId":"TABLE_ID",
              "dataSchema":"product_merchant_center"
            }
          }
      }' \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

Importa dati del catalogo da BigQuery

Per importare i dati del catalogo nel formato corretto da BigQuery, utilizza lo schema di Vertex AI Search per la vendita al dettaglio per creare una tabella BigQuery con il formato corretto e caricare la tabella vuota con i dati del tuo catalogo. Poi carica i dati in Vertex AI Search per il retail.

Per ulteriore assistenza sulle tabelle BigQuery, consulta Introduzione alle tabelle. Per assistenza con le query BigQuery, consulta Panoramica sull'esecuzione di query sui dati di BigQuery.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Per importare il tuo catalogo:

  1. Se il set di dati BigQuery si trova in un altro progetto, configura le autorizzazioni richieste in modo che Vertex AI Search per la vendita al dettaglio possa accedere al set di dati BigQuery. Scopri di più.

  2. Importa i dati del tuo catalogo in Vertex AI Search per il retail.

    Console

    1. Vai alla pagina Dati> nella console Ricerca per la vendita al dettaglio.

      Vai alla pagina Dati
    2. Fai clic su Importa per aprire il riquadro Importa dati.
    3. Scegli Catalogo prodotti.
    4. Seleziona BigQuery come origine dati.
    5. Seleziona il branch su cui caricherai il catalogo.
    6. Scegli Schema cataloghi dei prodotti di Retail. Questo è lo schema dei prodotti per Vertex AI Search per il retail.
    7. Inserisci la tabella BigQuery in cui si trovano i dati.
    8. (Facoltativo) In Mostra opzioni avanzate, inserisci la posizione di un bucket Cloud Storage nel tuo progetto come posizione temporanea per i dati.

      Se non specificato, viene utilizzata una posizione predefinita. Se specificato, i bucket BigQuery e Cloud Storage devono trovarsi nella stessa regione.
    9. Se la ricerca non è attivata 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 lo stai reimportando dopo averlo svuotato. Scopri di più sui livelli dei prodotti. La modifica dei livelli di prodotto dopo l'importazione dei dati richiede un impegno significativo.

      Importante: non puoi attivare la ricerca per i progetti con un catalogo di prodotti che è stato importato come varianti.
    10. Fai clic su Importa.

    curl

    1. Se è la prima volta che carichi il catalogo o lo stai nuovamente importando dopo averlo svuotato, imposta i livelli di prodotto utilizzando il metodo Catalog.patch. Questa operazione richiede il ruolo Amministratore vendita al dettaglio.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
   "productLevelConfig": {
     "ingestionProductType": "PRODUCT_TYPE",
     "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
   }
 }' \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

    2. Crea un file di dati per i parametri di input per l'importazione.

      Utilizza l'oggetto BigQuerySource per fare riferimento al set di dati BigQuery.

      • DATASET_ID: l'ID del set di dati BigQuery.
      • TABLE_ID: l'ID della tabella BigQuery che contiene i dati.
      • PROJECT_ID: l'ID progetto in cui si trova l'origine BigQuery. Se non specificato, l'ID progetto viene ereditato dalla richiesta principale.
      • STAGING_DIRECTORY: facoltativo. Una directory Cloud Storage utilizzata come posizione intermedia per i dati prima che vengano importati in BigQuery. Lascia vuoto questo campo per creare automaticamente una directory temporanea (opzione consigliata).
      • ERROR_DIRECTORY: facoltativo. Una directory Cloud Storage per le informazioni sugli errori relativi all'importazione. Lascia vuoto questo campo per creare automaticamente una directory temporanea (opzione consigliata).
      • dataSchema: per la proprietà dataSchema, utilizza il valore product (predefinito). Utilizzerai lo schema di Vertex AI Search per il retail.

      Ti consigliamo di non specificare le directory di gestione temporanea o degli errori, in modo da creare automaticamente un bucket Cloud Storage con nuove directory di gestione temporanea e degli errori. Queste directory vengono create nella stessa regione del set di dati BigQuery e sono univoche per ogni importazione (in modo da impedire a più job di importazione di eseguire il staging dei dati nella stessa directory e potenzialmente di reimportare gli stessi dati). Dopo tre giorni, il bucket e le directory vengono eliminati automaticamente per ridurre i costi di archiviazione.

      Un nome del bucket creato automaticamente include l'ID progetto, la regione del bucket e il nome dello schema di dati, separati da trattini bassi (ad esempio, 4321_us_catalog_retail). Le directory create automaticamente si chiamano staging o errors, con un numero aggiunto (ad esempio, staging2345 o errors5678).

      Se specifichi le directory, il bucket Cloud Storage deve trovarsi nella stessa regione del set di dati BigQuery, altrimenti l'importazione non andrà a buon fine. Fornisci le directory di staging e degli errori nel formato gs://<bucket>/<folder>/; devono essere diverse. 

      {
   "inputConfig":{
     "bigQuerySource": {
       "projectId":"PROJECT_ID",
       "datasetId":"DATASET_ID",
       "tableId":"TABLE_ID",
       "dataSchema":"product"}
      }
}

    3. Importa le informazioni del catalogo inviando una richiesta POST al metodo REST Products:import, fornendo il nome del file di dati (qui mostrato come input.json).

      curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" -d @./input.json \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      Puoi controllare lo stato in modo programmatico utilizzando l'API. Dovresti ricevere un oggetto di risposta simile al seguente:

      {
"name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"done": false
}

      Il campo name è l'ID dell'oggetto operazione. Per richiedere lo stato di questo oggetto, sostituisci il campo name con il valore restituito dal metodo import, finché il campo done non viene restituito come true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456"

      Al termine dell'operazione, l'oggetto restituito ha un valore done di true e include un oggetto Status simile al seguente esempio:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
  "createTime": "2020-01-01T03:33:33.000001Z",
  "updateTime": "2020-01-01T03:34:33.000001Z",
  "successCount": "2",
  "failureCount": "1"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse",
},
"errorsConfig": {
  "gcsPrefix": "gs://error-bucket/error-directory"
}
}

      Puoi ispezionare i file nella directory degli errori in Cloud Storage per verificare se si sono verificati errori durante l'importazione.

Configurare l'accesso al set di dati BigQuery

Per configurare l'accesso quando il set di dati BigQuery si trova in un progetto diverso rispetto al servizio Vertex AI Search per la vendita al dettaglio, completa i seguenti passaggi.

  1. Apri la pagina IAM nella console Google Cloud.

    Apri la pagina IAM

  2. Seleziona il tuo progetto Vertex AI Search for Retail.

  3. Trova l'account di servizio denominato Account di servizio per la vendita al dettaglio.

    Se non hai mai avviato un'operazione di importazione, questo account di servizio potrebbe non essere elencato. Se non vedi questo account di servizio, torna all'attività di importazione e avviala. Se l'operazione non va a buon fine a causa di errori di autorizzazione, torna qui e completa questa attività.

  4. Copia l'identificatore dell'account di servizio, che ha il formato di un indirizzo email (ad esempio service-525@gcp-sa-retail.iam.gserviceaccount.com).

  5. Passa al tuo progetto BigQuery (stessa pagina IAM e amministrazione) e fai clic su  Concedi accesso.

  6. Per Nuovi principali, inserisci l'identificatore dell'account di servizio Vertex AI Search per la vendita al dettaglio e seleziona il ruolo BigQuery > Utente BigQuery.

  7. Fai clic su Aggiungi un altro ruolo e seleziona BigQuery > Editor dati BigQuery.

    Se non vuoi assegnare il ruolo Editor di dati all'intero progetto, puoi aggiungerlo direttamente al set di dati. Scopri di più.

  8. Fai clic su Salva.

Importare i dati di catalogo da Cloud Storage

Per importare i dati del catalogo in formato JSON, crea uno o più file JSON che contengono i dati del catalogo da importare e caricali su Cloud Storage. Da qui, puoi importarli in Vertex AI Search for Retail.

Per un esempio del formato dell'elemento prodotto JSON, consulta Formato dei dati JSON dell'elemento prodotto.

Per assistenza con il caricamento di file in Cloud Storage, consulta Caricare oggetti.

  1. Assicurati che l'account di servizio Vertex AI Search for Retail abbia l'autorizzazione di lettura e scrittura nel bucket.

    L'account di servizio Vertex AI Search for Retail è elencato nella pagina IAM nella console Google Cloud con il nome Account di servizio per la vendita al dettaglio. Utilizza l'identificatore dell'account di servizio, che assomiglia a un indirizzo email (ad es.service-525@gcp-sa-retail.iam.gserviceaccount.com), quando aggiungi l'account alle autorizzazioni del bucket.

  2. Importa i dati del catalogo.

    Console

    1. Vai alla pagina Dati> nella console Ricerca per la vendita al dettaglio.

      Vai alla pagina Dati
    2. Fai clic su Importa per aprire il riquadro Importa dati.
    3. Scegli Catalogo dei prodotti come origine dati.
    4. Seleziona il branch su cui caricherai il catalogo.
    5. Scegli Schema cataloghi dei prodotti di Retail come schema.
    6. Inserisci la posizione in Cloud Storage dei dati.
    7. Se la ricerca non è attivata, seleziona i livelli di prodotto.

      Devi selezionare i livelli di prodotto se è la prima volta che importi il catalogo o se lo stai reimportando dopo averlo svuotato. Scopri di più sui livelli dei prodotti. La modifica dei livelli di prodotto dopo l'importazione dei dati richiede un impegno significativo.

      Importante: non puoi attivare la ricerca per i progetti con un catalogo di prodotti che è stato importato come varianti.
    8. Fai clic su Importa.

    curl

    1. Se è la prima volta che carichi il catalogo o lo stai nuovamente importando dopo averlo svuotato, imposta i livelli dei prodotti utilizzando il metodo Catalog.patch. Scopri di più sui livelli dei prodotti.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
   "productLevelConfig": {
     "ingestionProductType": "PRODUCT_TYPE",
     "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
   }
 }' \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

    2. Crea un file di dati per i parametri di input per l'importazione. Utilizza l'oggetto GcsSource per fare riferimento al tuo bucket Cloud Storage.

      Puoi fornire più file o solo uno. Questo esempio utilizza due file.

      • INPUT_FILE: uno o più file in Cloud Storage contenente i dati del tuo catalogo.
      • ERROR_DIRECTORY: una directory Cloud Storage per le informazioni sugli errori relativi all'importazione.

      I campi del file di input devono essere nel formato gs://<bucket>/<path-to-file>/. La directory degli errori deve essere nel formato gs://<bucket>/<folder>/. Se la directory degli errori non esiste, viene creata. Il bucket deve esistere già.

      {
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
  }
},
"errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}

    3. Importa le informazioni del catalogo inviando una richiesta POST al metodo REST Products:import, fornendo il nome del file di dati (qui visualizzato come input.json).

      curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" -d @./input.json \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      Il modo più semplice per controllare lo stato dell'operazione di importazione è utilizzare la console Google Cloud. Per ulteriori informazioni, vedi Visualizzare lo stato di un'operazione di integrazione specifica.

      Puoi anche controllare lo stato in modo programmatico utilizzando l'API. Dovresti ricevere un oggetto di risposta simile al seguente:

      {
"name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"done": false
}

      Il campo name è l'ID dell'oggetto operazione. Richiedi lo stato di questo oggetto, sostituendo il campo del nome con il valore restituito dal metodo di importazione, finché il campo done non viene restituito come true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/[OPERATION_NAME]"

      Al termine dell'operazione, l'oggetto restituito ha un valore done di true e include un oggetto Status simile al seguente esempio:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
  "createTime": "2020-01-01T03:33:33.000001Z",
  "updateTime": "2020-01-01T03:34:33.000001Z",
  "successCount": "2",
  "failureCount": "1"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse"
},
"errorsConfig": {
  "gcsPrefix": "gs://error-bucket/error-directory"
}
}

      Puoi ispezionare i file nella directory degli errori in Cloud Storage per vedere quali tipi di errori si sono verificati durante l'importazione.

Importa i dati del catalogo in linea

curl

Importa le informazioni del catalogo in linea inviando una richiesta POST al metodo REST Products:import, utilizzando l'oggetto productInlineSource per specificare i dati del catalogo.

Fornisci un intero prodotto su una singola riga. Ogni prodotto deve essere su una riga distinta.

Per un esempio del formato dell'elemento prodotto JSON, consulta Formato dei dati JSON dell'elemento prodotto.

  1. Crea il file JSON per il tuo prodotto e chiamalo ./data.json:

    {
"inputConfig": {
"productInlineSource": {
  "products": [
    { PRODUCT_1 }
    { PRODUCT_2 }
  ]
}
}
}

  2. Chiama il metodo POST:

    curl -X POST \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 --data @./data.json \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

Java

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Formato dei dati JSON degli articoli del prodotto

Le voci Product nel file JSON devono avere l'aspetto degli esempi riportati di seguito.

Fornisci un intero prodotto su una singola riga. Ogni prodotto deve essere su una riga distinta.

Campi obbligatori minimi:

  {
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers"
  }
  {
    "id": "5839",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt"
  }

Oggetto completo:

  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers",
    "description": "Sneakers for the rest of us",
    "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50
    },
    "availableTime": "2020-01-01T03:33:33.000001Z",
    "availableQuantity": "1",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img1", "height": 320, "width": 320 }
    ]
  }
  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
    "id": "4567",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt",
    "description": "A casual shirt for a casual day",
    "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
    },
    "availableTime": "2020-02-01T04:44:44.000001Z",
    "availableQuantity": "2",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img2", "height": 320, "width": 320 }
    ]
  }

Dati storici del catalogo

Vertex AI Search for Retail supporta l'importazione e la gestione dei dati storici dei cataloghi. I dati storici del catalogo possono essere utili quando utilizzi gli eventi utente storici per l'addestramento del modello. Le informazioni sui prodotti passati possono essere utilizzate per arricchire i dati storici sugli eventi utente e migliorare l'accuratezza del modello.

I prodotti storici vengono archiviati come scaduti. Non vengono restituiti nelle risposte di ricerca, ma sono visibili alle chiamate dell'API Update, List e Delete.

Importa i dati storici del catalogo

Quando il campo expireTime di un prodotto è impostato su un timestamp passato, il prodotto è considerato storico. Imposta la disponibilità del prodotto su OUT_OF_STOCK per evitare di influire sui consigli.

Ti consigliamo di utilizzare i seguenti metodi per importare i dati storici del catalogo:

Chiama il metodo Product.Create

Utilizza il metodo Product.Create per creare una voce Product con il campo expireTime impostato su un timestamp passato.

Importazione in linea di prodotti scaduti

I passaggi sono identici a quelli dell'importazione in linea, tranne per il fatto che i prodotti devono avere i campi expireTime impostati su un timestamp passato.

Fornisci un intero prodotto su una singola riga. Ogni prodotto deve essere su una riga distinta.

Un esempio di ./data.json utilizzato nella richiesta di importazione in linea:

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

Importare i prodotti scaduti da BigQuery o Cloud Storage

Utilizza le stesse procedure descritte per importare i dati del catalogo da BigQuery o importare i dati del catalogo da Cloud Storage. Tuttavia, assicurati di impostare il campo expireTime su un timestamp passato.

Mantieni aggiornato il catalogo

Per ottenere risultati ottimali, il catalogo deve contenere informazioni aggiornate. Ti consigliamo di importare il catalogo su base giornaliera per assicurarti che sia aggiornato. Puoi utilizzare Google Cloud Scheduler per pianificare le importazioni o scegliere un'opzione di pianificazione automatica quando importi i dati utilizzando la console Google Cloud.

Puoi aggiornare solo gli articoli di prodotto nuovi o modificati oppure puoi importare l'intero catalogo. Se importi prodotti già presenti nel tuo catalogo, questi non vengono aggiunti di nuovo. Tutti gli elementi che sono stati modificati vengono aggiornati.

Per aggiornare un singolo articolo, consulta Aggiornare le informazioni sul prodotto.

Aggiornamento batch

Puoi utilizzare il metodo di importazione per aggiornare il catalogo in blocco. Procedi come per l'importazione iniziale; segui i passaggi descritti in Importare i dati del catalogo.

Monitorare lo stato di integrità dell'importazione

Per monitorare l'importazione e l'integrità del catalogo:

  1. Visualizza le informazioni aggregate sul tuo catalogo e visualizza l'anteprima dei prodotti caricati nella scheda Catalogo della pagina di ricerca dei dati di vendita al dettaglio.

    Vai alla pagina Dati

  2. Valuta se devi aggiornare i dati del catalogo per migliorare la qualità dei risultati di ricerca e sbloccare i livelli di rendimento nella pagina Qualità dei dati.

    Per scoprire di più su come controllare la qualità dei dati di ricerca e visualizzare i livelli di rendimento della ricerca, consulta Ottenere i livelli di rendimento della ricerca. Per un riepilogo delle metriche del catalogo disponibili in questa pagina, consulta Metriche relative alla qualità del catalogo.

    Vai alla pagina Qualità dei dati

  3. Per creare avvisi che ti comunichino se si verifica un problema con i caricamenti dei dati, segui le procedure descritte in Configurare gli avvisi di Cloud Monitoring.

    Mantenere aggiornato il catalogo è importante per ottenere risultati di alta qualità. Utilizza gli avvisi per monitorare le percentuali di errore di importazione e intervenire se necessario.

Passaggi successivi