Importa informazioni del catalogo

In questa pagina viene descritto come importare le informazioni del catalogo e mantenerle aggiornate.

Le procedure di importazione in questa pagina si applicano sia ai suggerimenti che alla ricerca. Dopo l'importazione dei dati, entrambi i servizi possono utilizzarli, quindi non è necessario importare gli stessi dati due volte se li utilizzi.

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

Importa i 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 Procedura guidata:

Procedura guidata

Importa i 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 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 come configurare il progetto, creare un account di servizio e aggiungere l'account di servizio all'ambiente locale.

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

Best practice per l'importazione di cataloghi

Sono necessari dati di alta qualità per generare risultati di alta qualità. Se nei dati mancano campi o se sono presenti valori segnaposto invece di valori effettivi, la qualità delle previsioni e dei risultati di ricerca ne risentirà.

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

  • Assicurati di pensare attentamente al momento di determinare quali prodotti o gruppi di prodotti sono primari e quali sono varianti. Prima di caricare i dati, consulta 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 elementi delle varianti non lo sono.

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

  • Osserva i limiti di importazione degli articoli dei prodotti.

    Per l'importazione in blocco da Cloud Storage, la dimensione di ogni file deve essere massimo 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 di prodotto alla volta.

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

    Non utilizzare valori segnaposto.

  • Includi quante più informazioni di catalogo facoltative possibile.

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

  • Tieni aggiornato il catalogo.

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

  • Non registrare gli eventi utente per gli elementi dei prodotti non ancora importati.

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

    Sono previsti alcuni errori, ma se ne hai uno elevato, ti consigliamo di esaminarli e risolvere eventuali problemi di processo che hanno causato gli errori.

Informazioni sull'importazione dei dati del catalogo

Puoi importare i dati di prodotto da Merchant Center, Cloud Storage, BigQuery o specificare i dati incorporati nella richiesta. Ognuna di queste procedure viene importata una tantum, ad eccezione del collegamento di Merchant Center. Pianifica importazioni regolari (idealmente, giornaliere) per assicurarti che il catalogo sia aggiornato. Consulta la sezione Mantenere 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 che possono essere utilizzati per l'importazione in batch 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 for Retail. Dopo il collegamento, gli aggiornamenti ai dati del catalogo in Merchant Center vengono sincronizzati in tempo reale con Vertex AI Search for Retail.
Quando utilizzarlo Se hai già un'integrazione con Merchant Center.
Limitazioni Supporto limitato per lo schema. Ad esempio, le raccolte di prodotti non sono supportate da Merchant Center. Merchant Center diventa la fonte di riferimento per i dati fino a quando non viene scollegato, quindi è necessario aggiungere ai dati di Merchant Center eventuali attributi personalizzati necessari.

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

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

Se usi già BigQuery.
Limitazioni Richiede il passaggio aggiuntivo della creazione di una tabella BigQuery mappata allo schema di Vertex AI Search for Retail.
Cloud Storage Descrizione Importa i dati in formato JSON dai file caricati in un bucket Cloud Storage. Ogni file deve avere dimensioni massime di 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 devi caricare una grande quantità di dati in un solo passaggio.
Limitazioni Non ideale per cataloghi con aggiornamenti frequenti di inventario e prezzi perché le modifiche non vengono applicate immediatamente.
Importazione in linea Descrizione Esegui l'importazione con 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 for Retail, ma supporta gli attributi personalizzati.
Quando utilizzarlo Se disponi di dati di catalogo fissi e non relazionali o un'elevata frequenza di aggiornamenti di quantità o prezzo.
Limitazioni Non è possibile importare più di 100 articoli di catalogo alla volta. Tuttavia, possono essere eseguiti molti passaggi di caricamento; non esiste alcun limite di elementi.

Elimina definitivamente rami del catalogo

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

Se pubblichi traffico di ricerca o previsione in tempo reale e prevedi di eliminare definitivamente il ramo predefinito, valuta la possibilità di specificare un altro ramo come predefinito prima di eliminare definitivamente. Poiché il ramo predefinito fornirà 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 di catalogo, completa i seguenti passaggi:

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

    Vai alla pagina Dati

  2. Seleziona un ramo del catalogo dal campo Nome filiale.

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

    Viene visualizzato un messaggio che ti informa che stai per eliminare tutti i dati nel ramo, nonché gli eventuali attributi creati per quest'ultimo.

  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, il relativo stato viene visualizzato nell'elenco Catalogo prodotti nella finestra Stato attività.

Sincronizzare Merchant Center con Vertex AI Search for Retail

Per una sincronizzazione continua tra Merchant Center e Vertex AI Search for Retail, puoi collegare il tuo account Merchant Center a Vertex AI Search for Retail. Dopo il collegamento, le informazioni del catalogo nel tuo account Merchant Center vengono importate immediatamente in Vertex AI Search for Retail.

Quando configuri una sincronizzazione di Merchant Center per Vertex AI Search for Retail, devi avere assegnato il ruolo Amministratore in Merchant Center. Sebbene un ruolo di accesso standard ti consenta di leggere i feed di Merchant Center nell'interfaccia utente, quando tenti di 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 for Retail, dovrai eseguire l'upgrade del tuo ruolo di conseguenza.

Mentre Vertex AI Search for Retail è 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 for Retail. Se vuoi impedire che le modifiche di Merchant Center vengano sincronizzate con Vertex AI Search for Retail, puoi scollegare il tuo account Merchant Center.

Lo scollegamento del tuo account Merchant Center non comporta l'eliminazione di alcun prodotto in Vertex AI Search for Retail. 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 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 trovi il tuo account.
  6. (Facoltativo) Seleziona Filtro 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 da filtrare.
  8. Seleziona la filiale in 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 for Retail. Per verificare quali account hanno accesso al tuo account Merchant Center, consulta Accesso degli utenti a 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 indicato 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 nella 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. La mancata selezione dei feed comporta la condivisione di tutti i feed dell'account Merchant Center. Puoi trovare gli ID 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 di Cerca nella console Retail e fai clic sul pulsante Merchant Center in alto a destra. Si apre il riquadro Account Merchant Center collegati. Da questo riquadro puoi anche aggiungere altri account Merchant Center.

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

Elenca i link ai 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.

curl

Utilizza il metodo MerchantCenterAccountLink.list per elencare le risorse 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, l'account in questione non potrà sincronizzare i dati del catalogo con Vertex AI Search for Retail. Questa procedura non elimina i prodotti già caricati in Vertex AI Search for Retail.

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.

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 illimitato di rami del catalogo, ma un singolo ramo 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.

  • Il completamento della prima importazione dopo il collegamento dell'account Merchant Center può richiedere ore. La quantità di tempo dipende dal numero di offerte nell'account Merchant Center.

  • Qualsiasi modifica ai prodotti utilizzando i metodi API viene 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 quindi sincronizzate automaticamente con Vertex AI Search for Retail.

  • Il tipo di prodotto della raccolta non è supportato per i rami che utilizzano il collegamento a 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 sul prodotto.

Importa i dati del catalogo da Merchant Center

Merchant Center è uno strumento che puoi utilizzare per rendere i tuoi dati del negozio e di prodotto 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 tuo catalogo da Merchant Center, completa i seguenti passaggi:

  1. Utilizzando le istruzioni riportate in Trasferimenti di Merchant Center, configura un trasferimento da Merchant Center a BigQuery.

    Utilizzerai 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 for Retail possa accedere al set di dati BigQuery. Ulteriori informazioni

  3. Importa i dati del tuo catalogo da BigQuery in Vertex AI Search for Retail.

    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.

    3. Scegli Catalogo dei prodotti.

    4. Seleziona BigQuery come origine dati.

    5. Seleziona la filiale in cui caricherai il catalogo.

    6. Seleziona Merchant Center come schema dei dati.

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

    8. (Facoltativo) Inserisci la località di un bucket Cloud Storage nel progetto come posizione temporanea per i 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 se lo stai reimportando dopo averlo eliminato, seleziona i livelli di prodotto. Scopri di più sui livelli di prodotto.

      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 se reimporti il catalogo dopo averlo eliminato, imposta i livelli di prodotto utilizzando il metodo Catalog.patch. Questa operazione richiede il ruolo Amministratore retail. Scopri di più sui livelli di prodotto.

      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 in cui si trovano i tuoi dati.
      • STAGING_DIRECTORY: facoltativo. Una directory di Cloud Storage utilizzata come posizione provvisoria per i dati prima che vengano importati in BigQuery. Lascia vuoto questo campo per creare automaticamente una directory temporanea (consigliato).
      • ERROR_DIRECTORY: facoltativo. Una directory di Cloud Storage per le informazioni sugli errori dell'importazione. Lascia vuoto questo campo per creare automaticamente una directory temporanea (consigliato).
      • 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 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 gestire temporaneamente i dati nella stessa directory e potenzialmente reimportare gli stessi dati). Dopo tre giorni, il bucket e le directory vengono eliminati automaticamente per ridurre i costi di archiviazione.

      Il nome di un 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 denominate staging o errors e vengono 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 riuscirà. Fornisci le directory di gestione temporanea 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 da BigQuery nel formato corretto, utilizza lo schema di Vertex AI Search for Retail per creare una tabella BigQuery con il formato corretto e caricare la tabella vuota con i dati del catalogo. Quindi, carica i dati in Vertex AI Search for Retail.

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 Procedura guidata:

Procedura guidata

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 for Retail possa accedere al set di dati BigQuery. Ulteriori informazioni

  2. Importa i dati del tuo catalogo in Vertex AI Search for Retail.

    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 la filiale in cui caricherai il catalogo.
    6. Scegli Schema cataloghi dei prodotti per il retail. Questo è lo schema del prodotto per Vertex AI Search for Retail.
    7. Inserisci la tabella BigQuery in cui si trovano i dati.
    8. (Facoltativo) In Mostra opzioni avanzate, inserisci la località di un bucket Cloud Storage nel progetto come posizione temporanea per i dati.

      Se non specificata, viene utilizzata una località predefinita. Se specificato, i bucket BigQuery e Cloud Storage devono trovarsi nella stessa regione.
    9. Se la ricerca non è abilitata e utilizzi lo schema di Merchant Center, seleziona il livello di prodotto.

      Devi selezionare il livello di prodotto se è la prima volta che importi il catalogo o se stai reimportando il catalogo dopo averlo eliminato. Scopri di più sui livelli di prodotto. Modificare i 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.

    curl

    1. Se è la prima volta che carichi il catalogo o se reimporti il catalogo dopo averlo eliminato, imposta i livelli di prodotto 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 in cui si trovano 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 di Cloud Storage utilizzata come posizione provvisoria per i dati prima che vengano importati in BigQuery. Lascia vuoto questo campo per creare automaticamente una directory temporanea (consigliato).
      • ERROR_DIRECTORY: facoltativo. Una directory di Cloud Storage per le informazioni sugli errori dell'importazione. Lascia vuoto questo campo per creare automaticamente una directory temporanea (consigliato).
      • dataSchema: per la proprietà dataSchema, utilizza il valore product (predefinito). Utilizzerai lo schema di Vertex AI Search for 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 (il che impedisce a più job di importazione di gestire temporaneamente i dati nella stessa directory e potenzialmente reimportare gli stessi dati). Dopo tre giorni, il bucket e le directory vengono eliminati automaticamente per ridurre i costi di archiviazione.

      Il nome di un 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 denominate staging o errors e vengono 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 riuscirà. Fornisci le directory di gestione temporanea 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 tuo catalogo effettuando una richiesta POST al metodo REST Products:import, specificando 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 name con il valore restituito dal metodo import, 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/import-products-123456"

      Al termine dell'operazione, l'oggetto restituito avrà 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 controllare i file nella directory degli errori in Cloud Storage per vedere 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 dal servizio Vertex AI Search for Retail, completa i passaggi riportati di seguito.

  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 con il nome Retail Service Account.

    Se non hai già 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 avvia l'importazione. Quando l'operazione non riesce a causa di errori di autorizzazione, torna qui e completa questa attività.

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

  5. Passa al tuo 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 for Retail 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 aggiungerlo direttamente al set di dati. Ulteriori informazioni

  8. Fai clic su Salva.

Importa i dati del catalogo da Cloud Storage

Per importare i dati di catalogo in formato JSON, devi creare uno o più file JSON contenenti i dati di catalogo da importare e caricarli in Cloud Storage. Da qui, puoi importarla in Vertex AI Search for Retail.

Per un esempio del formato dei dati JSON degli articoli di prodotto, consulta Formato dei dati JSON degli articoli del prodotto.

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

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

    L'account di servizio Vertex AI Search for Retail è elencato nella pagina IAM della console Google Cloud con il nome Account di servizio Retail. Utilizza l'identificatore dell'account di servizio, che appare come 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 tuo 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 la filiale in cui caricherai il catalogo.
    5. Scegli Schema cataloghi dei prodotti retail come schema.
    6. Inserisci la località di Cloud Storage dei tuoi dati.
    7. Se la ricerca non è abilitata, seleziona i livelli di prodotto.

      Devi selezionare i livelli di prodotto se è la prima volta che importi il catalogo o se stai reimportando il catalogo dopo averlo eliminato. Scopri di più sui livelli di prodotto. Modificare i 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.

    curl

    1. Se è la prima volta che carichi il catalogo o se reimporti il catalogo dopo averlo eliminato, imposta i livelli di prodotto utilizzando il metodo Catalog.patch. Scopri di più sui livelli di prodotto.

      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 in modo che punti al bucket Cloud Storage.

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

      • INPUT_FILE: uno o più file di Cloud Storage contenenti i dati del tuo catalogo.
      • ERROR_DIRECTORY: una directory di Cloud Storage per le informazioni sugli errori dell'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 tuo catalogo effettuando 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 verificare 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 name con il valore restituito dal metodo di importazione, finché il campo done non 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 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 vedere che tipo di errori si sono verificati durante l'importazione.

Importa i dati del catalogo in linea

curl

Puoi importare 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.

Fornire un prodotto completo su una sola linea. Ogni prodotto dovrebbe essere su una riga separata.

Per un esempio del formato dei dati JSON degli articoli di prodotto, consulta Formato dei dati JSON degli articoli del prodotto.

  1. Crea il file JSON del prodotto e assegnagli il nome ./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 l'aspetto degli esempi riportati di seguito.

Fornire un prodotto completo su una sola linea. Ogni prodotto dovrebbe 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 del catalogo storici

Vertex AI Search for Retail supporta l'importazione e la gestione dei dati del catalogo storico. I dati storici del catalogo possono essere utili quando usi eventi utente storici per l'addestramento del modello. Le informazioni passate sui prodotti possono essere utilizzate 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 della ricerca, ma sono visibili alle chiamate API Update, List e Delete.

Importa i dati del catalogo storici

Quando il campo expireTime di un prodotto è impostato su un timestamp precedente, il prodotto è considerato un prodotto storico. Imposta la disponibilità del prodotto su OUT_OF_STOCK per evitare di influire 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 precedente.

Importazione in linea di prodotti scaduti

I passaggi sono identici a quelli dell'importazione in linea, ma i campi expireTime dei prodotti devono essere impostati su un timestamp passato.

Fornire un prodotto completo su una sola linea. Ogni prodotto dovrebbe essere su una riga separata.

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

Importa prodotti scaduti da BigQuery o Cloud Storage

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

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 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 importare l'intero catalogo. Se importi prodotti già presenti nel catalogo, questi non verranno aggiunti di nuovo. Tutti gli elementi modificati vengono aggiornati.

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

Aggiornamento batch

Puoi usare il metodo di importazione per aggiornare in batch il catalogo. Esegui questa operazione come per l'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 un'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 sulla pagina Qualità dei dati.

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

    Vai alla pagina Qualità dei dati

  3. Per creare avvisi che ti informino se si verificano problemi durante il caricamento dei dati, segui le procedure in Configurare gli avvisi di Cloud Monitoring.

    Mantenere aggiornato il catalogo è importante per ottenere risultati di alta qualità. Utilizza gli avvisi per monitorare i tassi di errore delle importazioni e intervenire se necessario.

Passaggi successivi