Importa informazioni del catalogo

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

Le procedure di importazione in questa pagina si applicano sia ai consigli sia alla ricerca. Dopo aver importato i dati, Entrambi i servizi sono in grado di utilizzare quei dati, quindi non devi importare i dati due volte se utilizzi entrambi i servizi.

Importa dati del catalogo da BigQuery

Questo tutorial mostra come utilizzare una tabella BigQuery per l'importazione di cataloghi senza limiti.

Per seguire una guida passo passo per questa attività direttamente nel Editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Importare i dati di catalogo da Cloud Storage

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

Per seguire una guida passo passo per questa attività direttamente nel Editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Importa i dati del catalogo in linea

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

Per seguire una guida passo passo per questa attività direttamente nel Editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Prima di iniziare

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

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

Best practice per l'importazione del catalogo

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

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

  • Rifletti attentamente nel determinare quali prodotti o gruppi di I prodotti sono primari e quali sono le varianti. Prima di caricare qualsiasi dato, consulta Livelli di prodotto.

    Modificare la configurazione a livello di prodotto dopo aver importato i dati richiede uno sforzo significativo.

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

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

  • Rispetta i limiti di importazione degli articoli del prodotto.

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

    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 il maggior numero possibile di informazioni facoltative sul catalogo.

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

  • Tieni aggiornato il catalogo.

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

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

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

    Sono previsti alcuni errori, ma se ne hai molti, esaminali e correggi 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 o specifica i dati in linea nella richiesta. Ognuna di queste procedure viene importata una tantum ad eccezione del collegamento di Merchant Center. Programma importazioni di cataloghi regolari (idealmente, ogni giorno) per garantire che il catalogo sia aggiornato. Consulta la sezione Mantenere aggiornato il catalogo.

Puoi anche importare singoli articoli di prodotto. Per ulteriori informazioni, vedi Carica un prodotto.

Considerazioni sull'importazione del catalogo

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

Sincronizzazione di Merchant Center Descrizione Importa i dati del catalogo tramite Merchant Center collegando l'account a Vertex AI Search per il retail. Dopo il collegamento, gli aggiornamenti ai dati del catalogo in Merchant Center vengono sincronizzati in tempo reale con Vertex AI Search per il retail.
Quando utilizzarlo Se hai già un'integrazione con Merchant Center.
Limitazioni Supporto limitato degli schemi. Ad esempio, le collezioni di prodotti non sono supportate da Merchant Center. Merchant Center diventa la fonte attendibile dei dati fino a quando non vengono scollegati, quindi eventuali gli attributi richiesti devono essere aggiunti ai dati di Merchant Center.

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

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

Se utilizzi già BigQuery.
Limitazioni Richiede il passaggio aggiuntivo di creazione di una tabella BigQuery viene mappato 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 e massimo 100 file alla volta possono essere importati. L'importazione può essere eseguita utilizzando la console Google Cloud o curl. Utilizza il formato di 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 si riflettono immediatamente.
Importazione in linea Descrizione Importa utilizzando una chiamata al metodo Product.import. Utilizza l'oggetto ProductInlineSource, che ha meno attributi del catalogo di prodotti rispetto allo schema di Vertex AI Search for Retail, ma supporta gli attributi personalizzati.
Quando utilizzarlo Se disponi di dati di catalogo piatti e non relazionali o un'alta frequenza aggiornamenti di quantità o prezzi.
Limitazioni Non è possibile importare più di 100 articoli di catalogo alla volta. Tuttavia, molti i passaggi di caricamento; non c'è nessun limite di elementi.

Eliminare definitivamente i rami del catalogo

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

Se pubblichi previsioni o traffico di ricerca in tempo reale e prevedi di eliminare definitivamente il traffico predefinito ramo, considera innanzitutto di specificare un altro ramo come predefinito prima di eliminarlo. Poiché il ramo predefinito pubblicherà risultati vuoti dopo l'eliminazione, l'eliminazione di un ramo predefinito attivo può causare un'interruzione del servizio.

Per eliminare i dati da un ramo del catalogo:

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

    Vai alla pagina Dati

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

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

    Viene visualizzato un messaggio che ti informa che stai per eliminare tutti i dati in del ramo, oltre agli eventuali attributi creati per il ramo.

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

    Viene avviata un'operazione a lunga esecuzione per eliminare definitivamente i dati dal ramo del catalogo. Quando l'operazione di eliminazione definitiva è completata, il relativo stato viene visualizzato in Elenco Catalogo dei prodotti in Stato attività finestra.

Sincronizzare Merchant Center con Vertex AI Search for Retail

Per la sincronizzazione continua tra Merchant Center e Vertex AI Search per la vendita al dettaglio, puoi collegare il tuo account Merchant Center a Vertex AI Search per la vendita al dettaglio. Dopo il collegamento, le informazioni del catalogo nel tuo L'account Merchant Center viene importato immediatamente Vertex AI Search for Retail.

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

Sebbene Vertex AI Search for Retail sia collegato a Merchant Center, le modifiche ai dati di prodotto in Merchant Center, vengono aggiornati automaticamente in Vertex AI Search for Retail. Se vuoi impedire la sincronizzazione delle modifiche apportate in Merchant Center a Vertex AI Search for Retail, puoi scollegare Account Merchant Center.

Se scolleghi il tuo account Merchant Center, non vengono eliminati in Vertex AI Search for Retail. Per eliminare i prodotti importati, consulta Eliminare le informazioni sul prodotto.

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

Console

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

    Vai alla pagina Dati
  2. Fai clic su Importa per aprire il riquadro Importa dati.
  3. Scegli Catalogo dei prodotti.
  4. Seleziona Sincronizzazione di Merchant Center 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 ha accesso sia all'account Merchant Center Vertex AI Search for Retail. Per controllare quali account hanno accesso al tuo account Merchant Center, consulta Accesso utente per Merchant Center.

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

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

Per visualizzare gli account Merchant Center collegati, vai alla Cerca la pagina Dati della Console Retail e fai clic su Merchant Center. in alto a destra nella pagina. Viene aperto il account Merchant Center collegato Account. Da questo riquadro puoi anche aggiungere altri account Merchant Center.

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

Elenca i link del tuo account Merchant Center.

Console

  1. Vai alla scheda Dati > nella console Search for Retail.

    Vai alla pagina Dati

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

curl

Utilizza il metodo MerchantCenterAccountLink.list per elencare 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 verrà sospeso da la sincronizzazione dei dati del catalogo con Vertex AI Search for Retail. Questa procedura non eliminare in Vertex AI Search for Retail tutti i prodotti che sono già stati caricato.

Console

  1. Vai alla scheda Dati > nella console Search for Retail.

    Vai alla pagina Dati

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

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

curl

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

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

Limitazioni relative al collegamento a Merchant Center

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

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

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

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

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

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

Importa i dati del catalogo da Merchant Center

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

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

Importazione collettiva da Merchant Center

Puoi importare i dati del catalogo da Merchant Center utilizzando il Cerca la console Retail o il metodo products.import. In blocco l'importazione è una procedura una tantum ed è supportata solo personalizzati.

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

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

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

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

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

    Console

    1. Vai alla scheda Dati > nella console 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 il ramo su cui caricherai il catalogo.

    6. Seleziona Merchant Center come schema di dati.

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

    8. (Facoltativo) Inserisci la località di un bucket Cloud Storage in il tuo progetto come posizione temporanea per i tuoi dati.

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

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

    10. Se è la prima volta che importi il catalogo o reimportando il catalogo dopo averlo eliminato,seleziona livelli di prodotto. Scopri di più sui livelli di prodotto.

      Modificare la configurazione a livello di prodotto dopo aver importato qualsiasi dati richiede uno sforzo significativo.

    11. Fai clic su Importa.

    curl

    1. Se è la prima volta che carichi il catalogo o reimportando il catalogo dopo averlo eliminato, imposta il valore livelli di prodotto utilizzando Catalog.patch. Questa operazione richiede il ruolo Amministratore vendita al dettaglio. 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 Products.import .

      • DATASET_ID: l'ID del set di dati BigQuery.
      • TABLE_ID: l'ID della tabella BigQuery che contiene i dati.
      • STAGING_DIRECTORY: facoltativo. Una directory Cloud Storage utilizzata come posizione intermedia per i dati prima che vengano importati in BigQuery. Lascia vuoto questo campo per creare automaticamente una directory temporanea (opzione consigliata).
      • ERROR_DIRECTORY: facoltativo. 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 di Merchant Center.

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

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

      Se specifichi le directory, il bucket Cloud Storage deve trovarsi nella stessa regione del set di dati BigQuery, altrimenti l'importazione non andrà a buon fine. Fornisci le directory di gestione temporanea e degli errori nel formato gs://<bucket>/<folder>/; e 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 nel formato corretto da BigQuery, utilizza lo schema di Vertex AI Search for Retail crea una tabella BigQuery con il formato corretto e carica la tabella vuota con i tuoi dati di catalogo. Poi carica i dati in Vertex AI Search per il retail.

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

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

Procedura guidata

Per importare il catalogo:

  1. Se il set di dati BigQuery si trova in un altro progetto, configura autorizzazioni necessarie affinché Vertex AI Search for Retail possa accedere set di dati BigQuery. Scopri di più.

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

    Console

    1. Vai alla scheda Dati > nella console 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 su 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 posizione di un bucket Cloud Storage nel tuo 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 è attivata e utilizzi lo schema di Merchant Center, seleziona il livello di prodotto.

      Devi selezionare il livello di prodotto se è la prima volta che importi il catalogo o se lo stai reimportando dopo averlo svuotato. Scopri di più sui livelli di prodotto. 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 di prodotti importati come varianti.
    10. Fai clic su Importa.

    curl

    1. Se è la prima volta che carichi il catalogo o reimportando il catalogo dopo averlo eliminato, imposta il valore livelli di prodotto utilizzando Catalog.patch. Questa operazione richiede il ruolo Amministratore vendita al dettaglio.

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

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

      Utilizza l'oggetto BigQuerySource per puntare al tuo set di dati BigQuery.

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

      Ti consigliamo di non specificare directory di gestione temporanea o di errore, in questo modo in bucket Cloud Storage con nuove directory di gestione temporanea e degli errori, creato automaticamente. Queste directory vengono create nello stesso regione come set di dati BigQuery e sono univoci per ogni importazione (che impedisce a più job di importazione di inserire temporaneamente i dati nella stessa directory, e potenzialmente reimportare gli stessi dati). Dopo tre giorni, i bucket vengono eliminate automaticamente per ridurre i costi di archiviazione.

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

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

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

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

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

      Puoi controllare lo stato in modo programmatico utilizzando l'API. Dovresti ricevere un oggetto 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. A per richiedere lo stato di questo oggetto, sostituisci il campo name con valore restituito dal metodo import, fino a quando il campo done restituisce come true:

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

      Al termine dell'operazione, l'oggetto restituito ha un valore done 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 ispezionare i file nella directory degli errori in Cloud Storage per verificare se si sono verificati errori durante l'importazione.

Configurare l'accesso al set di dati BigQuery

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

  1. Apri la pagina IAM nella console Google Cloud.

    Aperto pagina IAM

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

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

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

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

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

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

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

    Se non vuoi fornire il ruolo Editor dati all'intera organizzazione puoi aggiungere questo ruolo direttamente al set di dati. Scopri di più.

  8. Fai clic su Salva.

Importare i dati di catalogo da Cloud Storage

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

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

Per assistenza con il caricamento di file in Cloud Storage, vedi Carica oggetti.

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

    L'account di servizio Vertex AI Search for Retail è elencato in Pagina IAM nella console Google Cloud con il nome Retail Service Account. Utilizza le funzionalità di l'identificatore dell'account di servizio, che appare come un indirizzo email (ad esempio, service-525@gcp-sa-retail.iam.gserviceaccount.com), quando aggiungendo l'account alle autorizzazioni del bucket.

  2. Importa i dati del catalogo.

    Console

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

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

      Devi seleziona i livelli di prodotto se è la prima volta che importi il catalogo o reimportare il catalogo dopo averlo eliminato. Scopri di più sui livelli dei prodotti. Modifica in corso di prodotto dopo l'importazione dei dati richiede un impegno significativo.

      Importante: non puoi attivare la ricerca di progetti con un di prodotti importati come varianti.
    8. Fai clic su Importa.

    curl

    1. Se è la prima volta che carichi il catalogo o reimportando il catalogo dopo averlo eliminato, imposta il valore i livelli di prodotto con 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 la GcsSource in modo che punti all'oggetto nel bucket Cloud Storage.

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

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

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

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

    3. Importa le informazioni del tuo catalogo effettuando una richiesta POST al REST di 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 è la console Google Cloud. Per ulteriori 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 di risposta simile al seguente:

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

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

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

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

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

      Puoi esaminare i file nella directory degli errori in a Cloud Storage per vedere che tipo di errori si sono verificati durante l'importazione.

Importa i dati del catalogo in linea

curl

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

Fornire un prodotto completo su una singola linea. Ogni prodotto deve essere su una riga distinta.

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

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

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

  2. Chiama il metodo POST:

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

Java

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

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

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

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

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

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

  return operationName;
}

Formato dei dati JSON dell'articolo di prodotto

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

Fornire un prodotto completo su una singola linea. Ogni prodotto deve essere indipendente dalla riga di comando.

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 storici dei cataloghi. I dati storici del catalogo possono essere utili quando utilizzi gli eventi utente storici per l'addestramento del modello. Le informazioni sui prodotti passati possono essere utilizzate per arricchire i dati storici sugli eventi utente e migliorare l'accuratezza del modello.

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

Importa i dati storici del catalogo

Quando il campo expireTime di un prodotto è impostato su un timestamp passato, il prodotto viene considerato storico. Imposta il prodotto availability [disponibilità] su OUT_OF_STOCK per evitare ripercussioni personalizzati.

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

Chiama il metodo Product.Create

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

Importazione in linea di prodotti scaduti

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

Fornisci un intero prodotto su una singola riga. Ogni prodotto deve essere indipendente dalla riga di comando.

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 descritte per l'importazione dei dati di catalogo da BigQuery o l'importazione dei dati di 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 catalogo su base giornaliera per assicurarti che sia aggiornato. Puoi utilizzare Google Cloud Scheduler per pianificare le importazioni o scegliere un'opzione di pianificazione automatica quando importi i dati utilizzando la console Google Cloud.

Puoi aggiornare solo i prodotti nuovi o modificati oppure puoi importare l'intero catalogo. Se importi prodotti già presenti nel tuo catalogo, non aggiunto di nuovo. Tutti gli elementi modificati vengono aggiornati.

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

Aggiornamento batch

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

Monitorare lo stato di integrità dell'importazione

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

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

    Vai alla pagina Dati

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

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

    Vai alla pagina Qualità dei dati

  3. Per creare avvisi che ti informino se si verificano problemi con i 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 i tassi di errore dell'importazione e intervenire nel caso necessaria.

Passaggi successivi