Importa informazioni del catalogo

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

Le procedure di importazione in questa pagina si applicano sia ai suggerimenti che alla ricerca. Dopo aver importato i dati, entrambi i servizi saranno in grado di utilizzare questi dati, quindi non è necessario importare due volte gli stessi dati 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 Aiuto:

Guidami

Importa dati del 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 Aiuto:

Guidami

Importa dati del catalogo in linea

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

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

Guidami

Prima di iniziare

Prima di poter importare le informazioni del catalogo, devi aver completato le istruzioni riportate in Prima di iniziare, in particolare la configurazione del progetto, la creazione di un account di servizio e l'aggiunta dell'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

Sono necessari dati di alta qualità per generare risultati di alta qualità. Se nei dati mancano campi o contengono valori segnaposto anziché valori effettivi, la qualità delle previsioni e dei risultati di ricerca ne risente.

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 varianti. Prima di caricare i dati, consulta Livelli del 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 elementi varianti non lo sono.

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

  • Rispetta i limiti di importazione degli articoli del prodotto.

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

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

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

    Non utilizzare valori segnaposto.

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

  • Assicurati che tutti i tuoi eventi utilizzino un'unica valuta, soprattutto se prevedi di utilizzare Google Cloud Console per visualizzare le metriche sulle entrate. L'API Vertex AI Search for Retail non supporta l'uso di più valute per catalogo.

  • Mantieni il catalogo aggiornato.

    Idealmente, dovresti aggiornare il catalogo ogni giorno. La pianificazione di importazioni periodiche del catalogo impedisce che la qualità del modello peggiori nel tempo. Puoi pianificare importazioni automatiche ricorrenti quando importi il catalogo utilizzando la console di Search for Retail. In alternativa, puoi utilizzare Google Cloud Scheduler per automatizzare le importazioni.

  • Non registrare gli eventi utente per gli articoli del prodotto che non sono stati ancora importati.

  • Dopo aver importato le informazioni del catalogo, esamina le informazioni di logging e segnalazione degli errori per il tuo progetto.

    Sono previsti alcuni errori, ma se riscontri un numero elevato di errori, ti consigliamo di esaminarli e risolvere eventuali problemi di procedura che hanno causato gli errori.

Informazioni sull'importazione dei dati del catalogo

Puoi importare i dati di prodotto da Merchant Center, Cloud Storage, BigQuery oppure specificare i dati in linea nella richiesta. Ognuna di queste procedure è importata una sola volta, ad eccezione del collegamento di Merchant Center. Programma importazioni regolari del catalogo (idealmente, ogni giorno) per assicurarti che il catalogo sia aggiornato. Consulta la pagina Mantieni aggiornato il catalogo.

Puoi anche importare singoli articoli di prodotto. Per maggiori informazioni, vedi Caricare un prodotto.

Considerazioni sull'importazione del catalogo

Questa sezione descrive i metodi utilizzabili per l'importazione in batch dei dati del catalogo, quando puoi utilizzare ciascun metodo, e alcune delle relative limitazioni.

Sincronizzazione Merchant Center Description Importa i dati del catalogo tramite Merchant Center collegando l'account a Vertex AI Search per la vendita al dettaglio. Dopo il collegamento, gli aggiornamenti ai dati del catalogo in Merchant Center vengono sincronizzati in tempo reale con Vertex AI Search per la vendita al dettaglio.
Quando utilizzarlo Se disponi già di un'integrazione con Merchant Center,
Limitazioni Supporto limitato degli schemi. Ad esempio, le raccolte di prodotti non sono supportate da Merchant Center. Merchant Center diventa la fonte attendibile per i dati fino a quando non vengono scollegati, quindi eventuali 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 articoli e i campi esistenti in Merchant Center vengono importati.
BigQuery Description 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 eseguito utilizzando la console Google Cloud o curl.
Quando utilizzarlo Se disponi di cataloghi di prodotti con molti attributi, L'importazione di BigQuery utilizza lo schema di Vertex AI Search per la vendita al dettaglio, che contiene più attributi del prodotto rispetto alle altre opzioni di importazione, inclusi attributi personalizzati chiave/valore.

Se disponi di grandi volumi di dati. L'importazione di BigQuery non ha un limite di dati.

Se utilizzi già BigQuery.
Limitazioni Richiede il passaggio aggiuntivo per la creazione di una tabella BigQuery mappata allo schema di Vertex AI Search per la vendita al dettaglio.
Cloud Storage Description Importa i dati in formato JSON dai file caricati in un bucket Cloud Storage. Ogni file deve avere dimensioni massime pari 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 dei dati JSON Product, che consente attributi personalizzati.
Quando utilizzarlo Se hai bisogno di caricare una grande quantità di dati in un solo passaggio.
Limitazioni Non ideale per i cataloghi con aggiornamenti frequenti di inventario e prezzi, perché le modifiche non vengono applicate immediatamente.
Importazione in linea Description Importa utilizzando una chiamata al metodo Product.import. Utilizza l'oggetto ProductInlineSource, che ha meno attributi del catalogo dei prodotti rispetto allo schema di Vertex AI Search per la vendita al dettaglio, ma supporta attributi personalizzati.
Quando utilizzarlo Se disponi di dati di catalogo fissi e non relazionali o con un'alta frequenza di aggiornamenti di quantità o prezzi.
Limitazioni Non puoi importare più di 100 articoli di catalogo alla volta. Tuttavia, è possibile eseguire molti passaggi di caricamento; non esiste alcun limite per gli elementi.

Elimina definitivamente i rami del catalogo

Se importi nuovi dati di catalogo in un ramo esistente, è importante che il ramo sia vuoto. Ciò garantisce l'integrità dei dati importati nel ramo. Se il ramo è vuoto, puoi importare nuovi dati del catalogo e collegare il ramo a un account commerciante.

Se gestisci il traffico di previsione o di ricerca in tempo reale e prevedi di eliminare definitivamente il ramo predefinito, valuta innanzitutto di specificare un altro ramo come predefinito prima di procedere con l'eliminazione definitiva. Poiché il ramo predefinito restituirà risultati vuoti dopo l'eliminazione definitiva, l'eliminazione definitiva di un ramo predefinito attivo può causare un'interruzione.

Per eliminare definitivamente i dati da un ramo del catalogo, completa i seguenti passaggi:

  1. Vai alla pagina Dati> nella console di Search for Retail.

    Vai alla pagina Dati

  2. Seleziona un ramo di catalogo dal campo Nome ramo.

  3. Dal menu con tre puntini accanto al campo Nome ramo, scegli Purge ramo.

    Viene visualizzato un messaggio che ti informa che stai per eliminare tutti i dati nel ramo, nonché tutti gli 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 ramo del catalogo. Al termine dell'operazione di eliminazione definitiva, lo stato dell'eliminazione viene visualizzato nell'elenco Catalogo dei prodotti nella finestra Stato attività.

Sincronizza Merchant Center con Vertex AI Search per la vendita al dettaglio

Per una 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 immediatamente importate in Vertex AI Search per la vendita al dettaglio.

Mentre Vertex AI Search per la vendita al dettaglio è collegato all'account Merchant Center, le modifiche ai dati di prodotto nell'account Merchant Center vengono aggiornate automaticamente in pochi minuti in Vertex AI Search per la vendita al dettaglio. Se vuoi impedire che le modifiche di Merchant Center vengano sincronizzate con Vertex AI Search per la vendita al dettaglio, puoi scollegare il tuo account Merchant Center.

Lo scollegamento del tuo account Merchant Center non elimina alcun prodotto in Vertex AI Search per la vendita al dettaglio. Per eliminare i prodotti importati, consulta la pagina Eliminare le informazioni sui prodotti.

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

Console

  1. Vai alla pagina Dati> nella console di Search for Retail.

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

    Se non specificata, vengono importate le offerte di tutti i feed (inclusi quelli futuri).
  7. (Facoltativo) Per importare solo offerte destinate a paesi o lingue specifici, espandi Mostra opzioni avanzate e seleziona i paesi di vendita e le lingue di Merchant Center per i filtri.
  8. Seleziona il ramo in cui caricherai il catalogo.
  9. Fai clic su Importa.

arricciatura

  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 verificare quali account hanno accesso al tuo account Merchant Center, consulta Accesso degli utenti 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 viene configurato, 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 nel prodotto della colonna Etichetta del feed del prodotto. Se non viene configurato, vengono importate tutte le etichette dei feed.
    • FEED_FILTERS: (FACOLTATIVO) elenco dei feed principali da cui verranno importati i prodotti. Se non selezioni i feed, verranno condivisi tutti i feed dell'account Merchant Center. Gli ID sono disponibili nella risorsa dei feed di dati dell'API Content oppure visitando Merchant Center, selezionando un feed e recuperando 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 il tuo account Merchant Center collegato, vai alla pagina Dati della console Search for Retail 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 la pagina Visualizzazione di informazioni aggregate sul tuo catalogo per istruzioni su come visualizzare i prodotti importati.

Elenca i collegamenti dei tuoi account Merchant Center.

Console

  1. Vai alla pagina Dati> nella console di Search for Retail.

    Vai alla pagina Dati

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

arricciatura

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"

e interromperne la sincronizzazione dei dati del catalogo con Vertex AI Search per la vendita al dettaglio. Questa procedura non elimina alcun prodotto già caricato in Vertex AI Search per la vendita al dettaglio.

Console

  1. Vai alla pagina Dati> nella console di Search for Retail.

    Vai alla pagina Dati

  2. Fai clic sul pulsante Merchant Center in alto a destra nella pagina per aprire un elenco degli 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.

arricciatura

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 di 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 del tuo account Merchant Center potrebbe richiedere ore per essere completata. La quantità di tempo dipende dal numero di offerte nell'account Merchant Center.

  • Qualsiasi modifica al prodotto che utilizza metodi API è disabilitata per i rami collegati a un account Merchant Center. Eventuali modifiche ai dati del catalogo dei prodotti in questi rami devono essere apportate utilizzando Merchant Center. Queste modifiche vengono poi sincronizzate automaticamente con Vertex AI Search per la vendita al dettaglio.

  • Il tipo di prodotto della raccolta non è supportato per i rami che utilizzano il collegamento di Merchant Center.

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

Importa i dati del catalogo da Merchant Center

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

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

Importazione collettiva da Merchant Center

Puoi importare i dati del catalogo da Merchant Center utilizzando la console Search for Retail o il metodo products.import. L'importazione collettiva è una procedura una tantum ed è supportata solo per i suggerimenti.

Per importare il catalogo da Merchant Center, completa i seguenti passaggi:

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

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

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

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

    Console

    1. Vai alla pagina Dati> nella console di Search for Retail.

      Vai alla pagina Dati

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

    3. Scegli Catalogo dei prodotti.

    4. Seleziona BigQuery come origine dati.

    5. Seleziona il ramo in cui caricherai il catalogo.

    6. Seleziona Merchant Center come schema di dati.

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

    8. (Facoltativo) 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 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 reimporti il catalogo dopo averlo eliminato definitivamente, seleziona i livelli di prodotto. Scopri di più sui livelli dei prodotti.

      Modificare la configurazione a livello di prodotto dopo l'importazione dei dati richiede uno sforzo significativo.

    11. Fai clic su Importa.

    arricciatura

    1. Se è la prima volta che carichi il catalogo o reimporti il catalogo dopo averlo eliminato, imposta i livelli dei prodotti utilizzando il metodo Catalog.patch. Questa operazione richiede il ruolo Amministratore retail. 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 con i tuoi dati.
      • STAGING_DIRECTORY: facoltativo. Una directory Cloud Storage che viene utilizzata come posizione provvisoria 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 dell'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 Merchant Center.

      Ti consigliamo di non specificare directory di gestione temporanea o di errore. In questo modo, potrai creare automaticamente un bucket Cloud Storage con nuove directory di gestione temporanea ed errore. 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 la gestione temporanea 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 dei dati, separati da trattini bassi (ad esempio 4321_us_catalog_retail). Le directory create automaticamente sono chiamate staging o errors, aggiunte da un numero (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 gestione temporanea ed errore nel formato gs://<bucket>/<folder>/; devono essere diversi. 

      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 da BigQuery nel formato corretto, utilizza lo schema di Vertex AI Search per la vendita al dettaglio per creare una tabella BigQuery con il formato corretto e carica la tabella vuota con i dati del tuo catalogo. poi carica i dati su Vertex AI Search per la vendita al dettaglio.

Per ulteriori informazioni sulle tabelle BigQuery, consulta Introduzione alle tabelle. Per assistenza con le query di BigQuery, consulta Panoramica dell'esecuzione di query sui dati di BigQuery.

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

Guidami

Per importare il 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 il retail possa accedere al set di dati BigQuery. Scopri di più.

  2. Importa i dati del catalogo in Vertex AI Search per la vendita al dettaglio.

    Console

    1. Vai alla pagina Dati> nella console di Search for Retail.

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

      Se non specificata, viene utilizzata una località predefinita. Se specificato, il bucket BigQuery e Cloud Storage devono essere nella stessa regione.
    9. Se non hai abilitato la ricerca 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 lo reimporti dopo averlo eliminato definitivamente. 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 di progetti con un catalogo dei prodotti che è stato importato come varianti.
    10. Fai clic su Importa.

    arricciatura

    1. Se è la prima volta che carichi il catalogo o reimporti il catalogo dopo averlo eliminato, imposta i livelli dei prodotti utilizzando il metodo Catalog.patch. Questa operazione richiede il ruolo Amministratore retail.

      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 puntare al tuo set di dati BigQuery.

      • DATASET_ID: l'ID del set di dati BigQuery.
      • TABLE_ID: l'ID della tabella BigQuery con i tuoi dati.
      • PROJECT_ID: l'ID progetto in cui si trova l'origine BigQuery. Se non specificato, l'ID progetto viene ereditato dalla richiesta padre.
      • STAGING_DIRECTORY: facoltativo. Una directory Cloud Storage che viene utilizzata come posizione provvisoria 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 dell'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 la vendita al dettaglio.

      Ti consigliamo di non specificare directory di gestione temporanea o di errore. In questo modo, potrai creare automaticamente un bucket Cloud Storage con nuove directory di gestione temporanea ed errore. 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 la gestione temporanea 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 dei dati, separati da trattini bassi (ad esempio 4321_us_catalog_retail). Le directory create automaticamente sono chiamate staging o errors, aggiunte da un numero (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 gestione temporanea ed errore nel formato gs://<bucket>/<folder>/; devono essere diversi. 

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

    3. Importa le informazioni del tuo 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 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 del nome con il valore restituito dal metodo import, fino a quando il campo done restituirà 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 pari a true e include un oggetto Status simile all'esempio seguente:

      { "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 esaminare i file nella directory degli errori in Cloud Storage per verificare se si sono verificati errori durante l'importazione.

Configura l'accesso al tuo set di dati BigQuery

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

  1. Apri la pagina IAM nella console Google Cloud.

    Apri la pagina IAM

  2. Seleziona il progetto Vertex AI Search per la vendita al dettaglio.

  3. Trova l'account di servizio con il nome Account di servizio Retail.

    Se non hai già avviato un'operazione di importazione, questo account di servizio potrebbe non essere in elenco. Se non vedi questo account di servizio, torna all'attività di importazione e avvia l'importazione. Se l'attività non riesce a causa di errori di autorizzazione, torna qui e completa questa attività.

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

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

  6. In Nuove entità, 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 fornire il ruolo Editor dati all'intero progetto, puoi aggiungere questo ruolo direttamente al set di dati. Scopri di più.

  8. Fai clic su Salva.

Importa dati del catalogo da Cloud Storage

Per importare i dati del catalogo in formato JSON, devi creare uno o più file JSON che contengono i dati del catalogo che vuoi importare e caricarli in Cloud Storage. Da qui, puoi importarlo in Vertex AI Search per la vendita al dettaglio.

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

Per assistenza sul caricamento di file in Cloud Storage, consulta Caricamento di oggetti.

  1. Assicurati che l'account di servizio Vertex AI Search per il retail disponga dell'autorizzazione di lettura e scrittura nel bucket.

    L'account di servizio Vertex AI Search per la vendita al dettaglio è elencato nella pagina IAM della console Google Cloud con il nome Account di servizio retail. Utilizza l'identificatore dell'account di servizio, che è simile a un indirizzo email (ad esempio, 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 di Search for Retail.

      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 ramo in cui caricherai il catalogo.
    5. Scegli Schema dei cataloghi dei prodotti per la vendita al dettaglio come schema.
    6. Inserisci il percorso di Cloud Storage dei tuoi dati.
    7. Se non hai attivato la ricerca, seleziona i livelli di prodotto.

      Devi selezionare i livelli di prodotto se è la prima volta che importi il catalogo o se reimporti il catalogo dopo averlo eliminato definitivamente. 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 di progetti con un catalogo dei prodotti che è stato importato come varianti.
    8. Fai clic su Importa.

    arricciatura

    1. Se è la prima volta che carichi il catalogo o lo reimporti dopo averlo eliminato, imposta i livelli di prodotto 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 puntare al bucket Cloud Storage.

      Puoi fornire più file o solo uno. In questo esempio vengono utilizzati due file.

      • INPUT_FILE: uno o più file in Cloud Storage contenenti i dati del tuo catalogo.
      • ERROR_DIRECTORY: una directory Cloud Storage per informazioni di errore sull'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 già esistere.

      {
"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, 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"

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

      Puoi anche controllare lo stato in modo programmatico utilizzando l'API. Dovresti ricevere un oggetto 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 restituisce 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 pari a 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 esaminare i file nella directory degli errori in Cloud Storage per vedere che tipo di errori si sono verificati durante l'importazione.

Importa dati del catalogo in linea

curl

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

Fornisci un intero prodotto in un'unica riga. Ogni prodotto deve essere su una riga separata.

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

  1. Crea il file JSON del prodotto e denominalo ./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 dell'articolo di prodotto

Le voci Product nel file JSON dovrebbero avere il seguente aspetto negli esempi riportati di seguito.

Fornisci un intero prodotto in un'unica riga. Ogni prodotto deve essere su una riga separata.

Numero minimo di campi obbligatori:

  {
    "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 di catalogo storici

Vertex AI Search per la vendita al dettaglio supporta l'importazione e la gestione dei dati storici di catalogo. I dati storici del catalogo sono utili quando si usano gli eventi utente storici per l'addestramento del modello. Le informazioni precedenti sui prodotti possono essere usate per arricchire i dati storici sugli eventi utente e migliorare l'accuratezza del modello.

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

Importa dati storici del catalogo

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

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 all'importazione in linea, ad eccezione del fatto che i campi expireTime dei prodotti devono avere un timestamp passato.

Fornisci un intero prodotto in un'unica riga. Ogni prodotto deve essere su una riga separata.

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
            }
          }
      ]
    }
  }
}

Importa i prodotti scaduti da BigQuery o Cloud Storage

Utilizza le stesse procedure documentate per l'importazione dei dati del catalogo da BigQuery o per l'importazione dei dati del catalogo da Cloud Storage. Tuttavia, assicurati di impostare il campo expireTime su un timestamp passato.

Mantieni il catalogo aggiornato

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

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

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

Aggiornamento batch

Puoi utilizzare il metodo di importazione per eseguire l'aggiornamento in gruppo del catalogo. Esegui la stessa procedura dell'importazione iniziale: segui i passaggi descritti in Importare i dati del catalogo.

Monitora l'integrità dell'importazione

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

  1. Visualizza informazioni aggregate sul tuo catalogo e visualizza l'anteprima dei prodotti caricati nella scheda Catalogo della pagina Dati di Search for Retail.

    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 prestazioni della ricerca nella pagina Qualità dei dati.

    Per saperne di più su come controllare la qualità dei dati di ricerca e visualizzare i livelli di rendimento della ricerca, consulta Sbloccare i livelli di prestazioni della ricerca. Per un riepilogo delle metriche disponibili del catalogo in questa pagina, consulta le metriche sulla qualità del catalogo.

    Vai alla pagina Qualità dei dati

  3. Per creare avvisi utili in caso di problemi 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 errori di importazione e intervieni se necessario.

Passaggi successivi