Importa le informazioni del catalogo

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

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

Tutorial video

Guarda questo video per scoprire come importare un catalogo utilizzando l'API Retail.

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 di catalogo da Cloud Storage

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

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

Procedura guidata

Importa i dati del catalogo in linea

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

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

Procedura guidata

Prima di iniziare

Prima di poter importare le informazioni del catalogo, devi aver completato le istruzioni riportate in Prima di iniziare, in particolare la configurazione del progetto, la creazione di un service account e l'aggiunta del account di servizio all'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 nei tuoi dati mancano campi o sono presenti 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 distinguere con attenzione i prodotti principali dalle varianti. Prima di caricare i dati, consulta la sezione Livelli di prodotto.

  • Modifica la configurazione a livello di prodotto dopo aver dedicato uno sforzo significativo all'importazione dei dati. Gli articoli principali, non le varianti, vengono restituiti come risultati di ricerca o consigli.

  • Esempio: se il gruppo di SKU principale è Maglietta a V,il modello di raccomandazione restituisce una maglietta a V e, magari, magliette a girocollo e a barchetta. Tuttavia, se le varianti non vengono utilizzate e ogni SKU è primario, ogni combinazione di colore o taglia della maglietta a V viene restituita come articolo distinto nel riquadro dei consigli: maglietta a V marrone, taglia XL, maglietta a V marrone, taglia L,fino a maglietta a V bianca, taglia M, maglietta a V bianca, taglia S.

  • Le raccolte possono essere riconosciute insieme se gli ID variante sono inclusi insieme agli ID prodotto principali in collectionMemberIds[]. In questo modo, una raccolta di prodotti, da cui un utente potrebbe aver acquistato uno o più prodotti del set, viene acquisita nell'evento utente, accreditando l'intero set all'acquisto. Ciò facilita la pubblicazione di altri prodotti della stessa raccolta per lo stesso utente in una query correlata futura.

  • Esempio: un utente ha acquistato in precedenza una coperta, quindi vengono restituiti i prodotti corrispondenti in una collezione di lenzuola, come le federe.

• Rispetta i limiti di importazione degli articoli di prodotto.

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

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

• Assicurati che le informazioni richieste del catalogo siano incluse e corrette. Non utilizzare valori segnaposto.

• Includi quante più informazioni facoltative del catalogo possibile.

• Assicurati che tutti i tuoi eventi utilizzino una singola valuta, soprattutto se prevedi di utilizzare la consoleGoogle Cloud per ottenere le metriche sulle entrate. L'API Vertex AI Search for Commerce non supporta l'utilizzo di più valute per catalogo.

• Mantieni il catalogo aggiornato, idealmente ogni giorno. La pianificazione di importazioni periodiche del catalogo impedisce che la qualità del modello diminuisca nel tempo. Puoi pianificare importazioni automatiche e ricorrenti quando importi il catalogo utilizzando la console Search for commerce. In alternativa, puoi utilizzare Google Cloud Scheduler per automatizzare le importazioni.

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

• Dopo aver importato le informazioni del catalogo, esamina le informazioni su registrazione e segnalazione degli errori per il tuo progetto. Se trovi più di qualche errore, esamina e correggi eventuali problemi di processo che hanno causato gli errori.

Informazioni sull'importazione dei dati del catalogo

Puoi importare i dati di prodotto da BigQuery o specificare i dati incorporati nella richiesta. Ciascuna di queste procedure è un'importazione una tantum, ad eccezione del collegamento di Merchant Center. Pianifica importazioni regolari del catalogo (idealmente, una volta al giorno) per verificare che sia aggiornato.

Consulta Mantieni il catalogo aggiornato.

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

Considerazioni sull'importazione del catalogo

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

Struttura dei dati di prodotto per l'importazione del catalogo

Questa sezione descrive come preparare i dati di prodotto per l'importazione del catalogo.

Prodotti principali

I prodotti principali fungono da contenitori per raggruppare varianti dei prodotti e da voci nella griglia di ricerca. Devono essere specificati solo gli attributi comuni condivisi tra le varianti dei prodotti principali. tra cui:

• ID prodotto principale
• ID prodotto (identico all'ID prodotto principale)
• Titolo
• Descrizione

Varianti di prodotto

I prodotti varianti ereditano gli attributi comuni dal prodotto principale, ma possono anche specificare valori unici.

Gli attributi obbligatori includono:

• Tutti gli attributi specificati per i prodotti principali (titolo, descrizione). Il prezzo, il titolo e la descrizione possono essere diversi dal prodotto principale.
• Attributi delle varianti specifici (colore, taglia e altre varianti di prodotto pertinenti).

Recupero degli attributi

Il processo di recupero prende in considerazione tutti gli attributi disponibili per la ricerca sia per i prodotti principali sia per le varianti.

Punteggio di pertinenza

Il punteggio di pertinenza si basa esclusivamente sui campi del titolo e della descrizione. Per garantire una differenziazione adeguata, modifica leggermente la variante rispetto ai titoli dei prodotti principali (ad esempio, Nome prodotto + Colore).

Corrispondenza delle varianti nei risultati di ricerca

La corrispondenza delle varianti (ad esempio, abito blu) filtra i risultati in base ad attributi delle varianti predefiniti come colore e taglia. I risultati di ricerca restituiscono fino a cinque varianti corrispondenti per ogni prodotto principale.

Elimina definitivamente i branch del catalogo

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

Se pubblichi traffico di ricerca o previsione in tempo reale e prevedi di eliminare il ramo predefinito, ti consigliamo di specificare prima un altro ramo come predefinito. Poiché il ramo predefinito restituirà risultati vuoti dopo l'eliminazione, l'eliminazione di un ramo predefinito attivo può causare un'interruzione.

Per eliminare i dati da un ramo del catalogo:

1. Vai alla pagina Dati nella console Cerca per il commercio.
   
   Vai alla pagina Dati

2. Seleziona un branch catalogo dal campo Nome branch.

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

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

4. Inserisci la filiale e fai clic su Conferma per eliminare definitivamente i dati del catalogo dalla filiale.

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

Sincronizzare Merchant Center con Vertex AI Search for Commerce

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.

Per la sincronizzazione continua tra Merchant Center e Vertex AI Search per il commercio, puoi collegare il tuo account Merchant Center a Vertex AI Search per il commercio.

Quando configuri una sincronizzazione di Merchant Center per Vertex AI Search for Commerce, devi disporre del ruolo IAM Amministratore assegnato in Merchant Center. Sebbene un ruolo di accesso standard ti consenta di leggere i feed Merchant Center, quando provi a sincronizzare Merchant Center con Vertex AI Search for Commerce, viene visualizzato un messaggio di errore. Pertanto, prima di poter sincronizzare correttamente Merchant Center con Vertex AI Search for Commerce, esegui l'upgrade del tuo ruolo.

Collega il tuo account Merchant Center

Anche se Vertex AI Search for Commerce è 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 Commerce. Se vuoi impedire la sincronizzazione delle modifiche di Merchant Center con Vertex AI Search for commerce, puoi scollegare il tuo account Merchant Center.

Scollegare l'account Merchant Center non elimina i prodotti in Vertex AI Search per il commercio. Per eliminare i prodotti importati, consulta la sezione Eliminare le informazioni sui prodotti.

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

Sincronizzare l'account Merchant Center

Per visualizzare il tuo account Merchant Center collegato, vai alla pagina Cerca nella console per il commercio Dati e fai clic sul pulsante Merchant Center in alto a destra nella pagina. Si aprirà il riquadro Account Merchant Center collegati. Da questo pannello puoi anche aggiungere altri account Merchant Center.

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

Elenca i link agli account Merchant Center

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"

Scollegare l'account Merchant Center

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

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 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 account secondari.

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

• Qualsiasi modifica dei prodotti tramite i metodi API è disattivata per i rami collegati a un account Merchant Center. Eventuali modifiche ai dati del catalogo prodotti in questi rami devono essere apportate utilizzando Merchant Center. Queste modifiche vengono poi sincronizzate automaticamente con Vertex AI Search for Commerce.

• Il tipo di prodotto raccolta non è supportato per le filiali che utilizzano il collegamento a Merchant Center.

• Per garantire l'accuratezza dei dati, il tuo account Merchant Center può essere collegato solo a rami vuoti del catalogo. Per eliminare i prodotti da un ramo del catalogo, vedi Eliminare le informazioni sui prodotti.

Importa dati del catalogo da BigQuery

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

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

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

Procedura guidata

Per importare il tuo catalogo:

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

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

   console Cloud

   1. Vai alla pagina Dati nella console Cerca per il commercio.
      
      Vai alla pagina Dati
   2. Fai clic su Importa per aprire il riquadro Importa dati.
   3. Scegli Catalogo prodotti.
   4. Seleziona BigQuery come origine dati.
   5. Seleziona il ramo in cui caricherai il catalogo.
   6. Scegli Schema cataloghi dei prodotti di Retail. Questo è lo schema del prodotto per Vertex AI Search for Commerce.
   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 tuoi dati.
      
      Se non specificata, viene utilizzata una posizione predefinita. Se specificati, BigQuery e il bucket Cloud Storage devono trovarsi nella stessa regione.
   9. Se la ricerca non è attivata e utilizzi lo schema Merchant Center, seleziona il livello prodotto.
      
      Devi selezionare il livello prodotto se è la prima volta che importi il catalogo o se lo reimporti dopo averlo eliminato. Scopri di più sui livelli dei prodotti. Modificare i livelli di prodotto dopo aver importato i dati richiede un impegno significativo.
      
      Importante:non puoi attivare la ricerca per i progetti con un catalogo di prodotti importato come varianti.
   10. Fai clic su Importa.

   curl

   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. Questa operazione richiede il ruolo di amministratore retail.

      • ingestionProductType: supporta i valori primary (predefinito) e variant.
      • merchantCenterProductIdField: supporta i valori offerId e itemGroupId. Se non utilizzi Merchant Center, non devi impostare questo campo.

      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 indirizzare il tuo set di dati BigQuery.

      • DATASET_ID: l'ID del set di dati BigQuery.
      • TABLE_ID: l'ID della tabella BigQuery che contiene 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 principale.
      • STAGING_DIRECTORY: (Facoltativo) Una directory Cloud Storage utilizzata come posizione temporanea per i dati prima che vengano importati in BigQuery. Lascia vuoto questo campo per creare automaticamente una directory temporanea (opzione consigliata).
      • ERROR_DIRECTORY: (Facoltativo) Una directory Cloud Storage per le informazioni sugli errori relativi all'importazione. Lascia vuoto questo campo per creare automaticamente una directory temporanea (consigliato).
      • dataSchema: per la proprietà dataSchema, utilizza il valore product (predefinito). Utilizzerai lo schema di Vertex AI Search for Commerce.

      Ti consigliamo di non specificare directory di gestione temporanea o di errore, in modo che venga creato automaticamente un bucket Cloud Storage con nuove directory di gestione temporanea e di 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 lo staging dei dati nella stessa directory e potenzialmente di reimportare gli stessi dati). Dopo tre giorni, il bucket e le directory vengono eliminati automaticamente per ridurre i costi di archiviazione.

      Un nome 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, a cui viene aggiunto 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 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 (in questo caso, mostrato come input.json).

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

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

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

      Il campo nome è l'ID dell'oggetto operazione. Per richiedere lo stato di questo oggetto, sostituisci il campo del nome con il valore restituito dal metodo import, 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/import-products-123456"

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

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

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

Configurare l'accesso al set di dati BigQuery

Per configurare l'accesso quando il set di dati BigQuery si trova in un progetto diverso da quello del servizio Vertex AI Search for commerce, completa i seguenti passaggi.

1. Apri la pagina IAM nella console Google Cloud .

   Apri la pagina IAM

2. Seleziona il progetto Vertex AI Search for Commerce.

3. Trova il account di servizio con il nome Retail Service Account.

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

4. Copia l'identificatore del account di servizio, che ha l'aspetto di 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 person_add Concedi l'accesso.

6. Per Nuovi principal, inserisci l'identificatore dell'account di servizio Vertex AI Search per il commercio 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. Scopri di più.

8. Fai clic su Salva.

Importa 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 importarlo in Vertex AI Search for Commerce.

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

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

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

   Il account di servizio di Vertex AI Search for Commerce è elencato nella pagina IAM nella console Google Cloud con il nome Service account retail. Utilizza l'identificatore del account di servizio, che ha l'aspetto di 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 Cloud

   1. Vai alla pagina Dati nella console Cerca per il commercio.
      
      Vai alla pagina Dati
   2. Fai clic su Importa per aprire il riquadro Importa dati.
   3. Scegli Catalogo prodotti come origine dati.
   4. Seleziona il ramo in cui caricherai il catalogo.
   5. Scegli Schema cataloghi dei prodotti di Retail come schema.
   6. Inserisci la posizione Cloud Storage dei tuoi dati.
   7. Se la ricerca non è attivata, seleziona i livelli di prodotto.
      
      Devi selezionare i livelli di prodotto se è la prima volta che importi il catalogo o se lo importi di nuovo dopo averlo eliminato. Scopri di più sui livelli dei prodotti. Modificare i livelli di prodotto dopo aver importato i dati richiede un impegno significativo.
      
      Importante:non puoi attivare la ricerca per i progetti con un catalogo di prodotti importato come varianti.
   8. Fai clic su Importa.

   curl

   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.

      • ingestionProductType: supporta i valori primary (predefinito) e variant.
      • merchantCenterProductIdField: supporta i valori offerId e itemGroupId. Se non utilizzi Merchant Center, non devi impostare questo campo.

      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 tuo bucket Cloud Storage.

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

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

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

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

   3. Importa le informazioni del catalogo inviando una richiesta POST al metodo REST Products:import, fornendo il nome del file di dati (in questo caso, 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 saperne di più, 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 nome è 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 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 di true e include un oggetto Stato 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 il tipo di errori che si sono verificati durante l'importazione.

Importa i dati del catalogo in linea

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

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

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

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

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

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

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

  return operationName;
}

Formato dei dati JSON degli articoli di prodotto

Le voci Product nel file JSON devono essere simili agli esempi riportati di seguito.

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

Campi minimi 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 storici del catalogo

Vertex AI Search for Commerce supporta l'importazione e la gestione dei dati storici del catalogo. 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 prodotti scaduti. Non vengono restituiti nelle risposte di ricerca, ma sono visibili alle chiamate API Update, List e Delete.

Importare i dati storici del catalogo

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

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

• Chiamata del metodo Product.Create.
• Importazione in linea di prodotti scaduti.
• Importazione di prodotti scaduti da BigQuery.

Chiama il metodo Product.Create

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

Importare in linea i prodotti scaduti

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

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

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

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

Importare prodotti scaduti da BigQuery o Cloud Storage

Utilizza le stesse procedure documentate per importare i dati di catalogo da BigQuery o importare i 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 il catalogo quotidianamente 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 consoleGoogle 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 vengono aggiunti di nuovo. Qualsiasi elemento modificato viene aggiornato.

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

Aggiornamento batch

Puoi utilizzare il metodo di importazione per aggiornare in batch il catalogo. Per farlo, segui la stessa procedura dell'importazione iniziale, descritta in Importare i dati del catalogo.

Monitorare l'integrità dell'importazione

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

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

   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 i livelli di rendimento della ricerca, consulta Sbloccare i livelli di rendimento 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 informano 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 i tassi di errore di importazione e intraprendere azioni se necessario.

Passaggi successivi

• Inizia a registrare gli eventi utente.
• Visualizzare informazioni aggregate sul tuo catalogo.
• Configura gli avvisi di caricamento dei dati.