Importa le informazioni del catalogo

In questa pagina viene descritto come importare le informazioni del catalogo nell'API Retail e come mantenerle aggiornate.

Le procedure di importazione in questa pagina si applicano sia a Recommendations AI che a Retail Search. Una volta importati nell'API Retail, entrambi i servizi sono in grado di utilizzarli, quindi non è necessario importare due volte gli stessi dati se si utilizzano entrambi i servizi.

Importa dati del catalogo da BigQuery

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

Per seguire le istruzioni 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 istruzioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Importa dati di catalogo in linea

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

Per seguire le istruzioni 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 avere il ruolo IAM Amministratore retail.

Best practice per l'importazione del catalogo

L'API Retail richiede dati di alta qualità per generare risultati di alta qualità. Se nei dati mancano campi o hanno 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:

Considera con attenzione per determinare quali prodotti o gruppi di prodotti sono principali e quali sono le varianti. Prima di caricare qualsiasi dato, consulta Livelli di prodotto.

Modificare la configurazione a livello di prodotto dopo aver importato dati; è necessario uno sforzo significativo.

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

Ad esempio, se il gruppo di SKU principale è "camicia con scollo a V", il modello di suggerimento restituisce un capo di camicia con scollo a V e, magari, una camicia con scollo rotondo e una camicia con scollo rotondo. 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 marrone con scollo a V, taglia XL", "Camicia scollo a V marrone, taglia L" fino a "Camicia bianca con scollo a V, taglia M", "Camicia bianca con scollo a V, taglia S".
Rispettare i limiti di importazione degli articoli di prodotto.

Per l'importazione collettiva da Cloud Storage, la dimensione di ciascun file deve essere pari o inferiore a 2 GB. Puoi includere fino a 100 file contemporaneamente in una singola richiesta di importazione collettiva.

Per l'importazione in linea, importa non più di 5000 articoli del prodotto alla volta.
Assicurati che tutte le informazioni del catalogo richieste siano incluse e corrette.

Non utilizzare valori segnaposto.
Includi quante più informazioni facoltative di catalogo possibile.
Assicurati che tutti gli eventi utilizzino una sola valuta, specialmente se prevedi di utilizzare Google Cloud Console per ricevere metriche sulle entrate. L'API Retail non supporta l'utilizzo di più valute per catalogo.
Tieni il catalogo aggiornato.

Idealmente, dovresti aggiornare il catalogo ogni giorno. La pianificazione delle importazioni periodiche del catalogo impedisce la riduzione della qualità del modello nel tempo. Puoi pianificare importazioni automatiche e ricorrenti quando importi il catalogo utilizzando la console Google Cloud. In alternativa, puoi utilizzare Google Cloud Scheduler per automatizzare le importazioni.
Non registrare eventi utente per gli articoli del prodotto non ancora importati.
Dopo aver importato le informazioni del catalogo, consulta le segnalazioni degli errori e le informazioni di logging per il tuo progetto.

Sono previsti alcuni errori, ma se hai un numero elevato di errori, devi esaminarli e risolvere eventuali problemi relativi al processo che hanno causato gli errori.

Informazioni sull'importazione dei dati del catalogo

Puoi importare i tuoi dati di prodotto da Merchant Center, Cloud Storage, BigQuery o specificare i dati in linea nella richiesta. Ognuna di queste procedure è un'importazione una tantum, ad eccezione del collegamento di Merchant Center all'API Retail. Pianifica importazioni regolari del catalogo (idealmente, ogni giorno) per assicurarti che il catalogo sia aggiornato. Consulta l'articolo Mantenere aggiornato il catalogo.

Puoi anche importare singoli articoli del prodotto. Per scoprire di più, consulta la pagina Caricare un prodotto.

Considerazioni sull'importazione del catalogo

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

Sincronizzazione Merchant Center	Description	Importa i dati del catalogo tramite Merchant Center collegando l'account all'API Retail. Dopo il collegamento, gli aggiornamenti ai dati del catalogo in Merchant Center vengono sincronizzati con l'API Retail in tempo reale.
	Quando utilizzarlo	Se disponi già di 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 attendibile per i dati finché non verrà scollegato, pertanto gli eventuali attributi personalizzati necessari dovranno 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	Description	Importa i dati da una tabella BigQuery caricata in precedenza che utilizza lo schema Retail o lo schema di Merchant Center. Può essere eseguito utilizzando la console Google Cloud o curl.
	Quando utilizzarlo	Se hai cataloghi dei prodotti con molti attributi. L'importazione BigQuery utilizza lo schema Retail, che ha più attributi di prodotto rispetto ad altre opzioni di importazione, inclusi gli attributi personalizzati chiave/valore. Se disponi di grandi volumi di dati, L'importazione BigQuery non ha un limite di dati. Se utilizzi già BigQuery.
	Limitazioni	Richiede il passaggio aggiuntivo per creare una tabella BigQuery mappata allo schema Retail.
Cloud Storage	Description	Importa i dati in formato JSON dai file caricati in un bucket Cloud Storage. Ogni file deve essere di dimensioni pari o inferiori a 2 GB e possono essere importati 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 è l'ideale per i cataloghi con frequenti aggiornamenti di inventario e prezzi, in quanto le modifiche non si riflettono immediatamente.
Importazione in linea	Description	Importa usando una chiamata al metodo `Product.import`. Utilizza l'oggetto `ProductInlineSource`, che ha meno attributi del catalogo dei prodotti rispetto allo schema Retail, ma supporta attributi personalizzati.
	Quando utilizzarlo	Se disponi di dati di catalogo fissi e non relazionali oppure di una frequenza elevata di aggiornamenti di prezzo o quantità.
	Limitazioni	Non è possibile importare più di 100 articoli del catalogo alla volta. Tuttavia, possono essere eseguiti molti passaggi di caricamento, senza limiti di elementi.

Elimina definitivamente i rami del catalogo

Se stai importando nuovi dati di catalogo in un ramo esistente, è importante che quest'ultimo sia vuoto. Questo assicura l'integrità dei dati importati nel ramo. Quando il ramo è vuoto, puoi importare nuovi dati di catalogo e poi collegare il ramo a un account commerciante.

Se gestisci il traffico in tempo reale o di ricerca e prevedi di eliminare definitivamente il ramo predefinito, valuta se 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 può causare un'interruzione.

Per eliminare definitivamente i dati di un ramo del catalogo, segui questi passaggi:

Vai alla pagina Dati retail nella console Google Cloud.

Vai alla pagina Dati
Seleziona un ramo catalogo dal campo Nome ramo.
Nel 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 e gli eventuali attributi creati per il ramo.

Nota: non puoi annullare l'eliminazione definitiva dei dati di un ramo del catalogo.
Inserisci il ramo e fai clic su Conferma per eliminare definitivamente i dati del catalogo dal ramo.

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

Nota: l'elenco dei dati del catalogo del ramo non viene aggiornato automaticamente al termine dell'eliminazione definitiva. Devi aggiornare la pagina per visualizzare un elenco aggiornato per il ramo.

Sincronizza Merchant Center con l'API Retail

Per la sincronizzazione continua tra Merchant Center e l'API Retail, puoi collegare il tuo account Merchant Center all'API Retail. Una volta eseguito il collegamento, le informazioni del catalogo nel tuo account Merchant Center vengono importate immediatamente nell'API Retail.

Sebbene l'API Retail sia collegata all'account Merchant Center, le modifiche ai dati di prodotto nell'account Merchant Center vengono aggiornate automaticamente in pochi minuti. Se vuoi impedire la sincronizzazione delle modifiche di Merchant Center con l'API Retail, puoi scollegare il tuo account Merchant Center.

Lo scollegamento del tuo account Merchant Center non elimina alcun prodotto nell'API Retail. Per eliminare i prodotti importati, consulta Eliminare le informazioni sui prodotti.

Sincronizza il tuo account Merchant Center

Per sincronizzare il tuo account Merchant Center, completa i passaggi riportati di seguito.

Console

Vai alla pagina Dati retail nella console Google Cloud.

Vai alla pagina Dati
Fai clic su Importa per aprire il riquadro Importa dati.
Scegli Catalogo dei prodotti.
Seleziona Sincronizzazione Merchant Center come origine dati.
Seleziona il tuo account Merchant Center. Se non vedi il tuo account, controlla Accesso utenti.
(Facoltativo) Seleziona il filtro dei feed di Merchant Center per importare solo le offerte dei feed selezionati.

Se non specificati, vengono importate le offerte di tutti i feed (inclusi i feed futuri).
(Facoltativo) Per importare solo le offerte che hanno come target determinati paesi o lingue, espandi Mostra opzioni avanzate e seleziona i paesi di vendita e le lingue di Merchant Center da utilizzare per filtrare.
Seleziona il ramo in cui caricherai il catalogo.
Fai clic su Import (Importa).

ricci

Verifica che l'account di servizio nel tuo ambiente locale abbia accesso sia all'account Merchant Center sia all'API Retail. Per verificare quali account hanno accesso al tuo account Merchant Center, consulta Accesso degli utenti a Merchant Center.
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 da importare. Quello che vedi in Merchant Center sotto la colonna Language del prodotto. Se non viene impostato, tutte le lingue vengono importate.
- 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 impostato, tutte le etichette dei feed vengono importate.
- FEED_FILTERS: (FACOLTATIVO) l'elenco di feed principali da cui verranno importati i prodotti. Se non selezioni i feed, tutti i feed dell'account Merchant Center vengono condivisi. Puoi trovare gli ID nella risorsa feed di dati di Content API o 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 Merchant Center collegato, vai alla pagina Dati della console Google Cloud e fai clic sul pulsante Merchant Center in alto a destra. Si apre il riquadro Account Merchant Center collegati. In questo riquadro puoi anche aggiungere altri account Merchant Center.

Consulta l'articolo Visualizzare informazioni aggregate sul catalogo per visualizzare le istruzioni su come visualizzare i prodotti importati nell'API Retail.

Elenca i collegamenti del tuo account Merchant Center

Elenca i link al tuo account Merchant Center.

Console

Vai alla pagina Dati retail nella console Google Cloud.

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

ricci

Utilizzare il metodo MerchantCenterAccountLink.list per elencare la risorsa 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"

Scollegare l'account Merchant Center

Se scolleghi il tuo account Merchant Center, questo account non sincronizzerà più i dati del catalogo con l'API Retail. Questa procedura non elimina nell'API Retail i prodotti già caricati.

Console

Vai alla pagina Dati retail nella console Google Cloud.

Vai alla pagina Dati
Fai clic sul pulsante Merchant Center in alto a destra nella pagina per aprire un elenco dei tuoi account Merchant Center collegati.
Fai clic su Scollega accanto all'account Merchant Center che vuoi scollegare, quindi conferma la tua scelta nella finestra di dialogo visualizzata.

ricci

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 al collegamento a Merchant Center

Un account Merchant Center può essere collegato a un numero qualsiasi di rami di catalogo, ma un singolo ramo di catalogo può essere collegato a un solo account Merchant Center.
Un account Merchant Center non può essere un account multi-cliente (AMC). Tuttavia, puoi collegare singoli subaccount.
Il primo importazione dopo il collegamento del tuo account Merchant Center potrebbe richiedere alcune ore. La quantità di tempo dipende dal numero di offerte nell'account Merchant Center.
Eventuali modifiche al prodotto che utilizzano i metodi dell'API Retail vengono disattivate 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. Le modifiche vengono quindi sincronizzate automaticamente con l'API Retail.
Il tipo di prodotto di raccolta non è supportato per i rami che utilizzano il collegamento a Merchant Center.
Il tuo account Merchant Center può essere collegato solo ai rami vuoti del catalogo per garantire la correttezza dei dati. Per eliminare i prodotti da un ramo del catalogo, consulta la sezione Eliminare le informazioni sui prodotti.

Importare i dati del catalogo da Merchant Center

Merchant Center è uno strumento che puoi utilizzare per rendere disponibili i dati di negozio e di prodotto 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 Recommendations AI).

Importazione collettiva da Merchant Center

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

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

Utilizzando le istruzioni riportate in Trasferimenti di Merchant Center, imposta un trasferimento da Merchant Center in 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 su 2 giorni.
Se il set di dati BigQuery si trova in un altro progetto, configura le autorizzazioni richieste in modo che l'API Retail possa accedere al set di dati BigQuery. Scopri di più
Importa i dati del tuo catalogo da BigQuery nell'API Retail.
Console
1. Vai alla pagina Dati retail nella console Google Cloud.
  
  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 in 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 nel progetto come posizione temporanea per i tuoi dati.
  
  Se non specificata, viene utilizzata una località predefinita. Se specificato, il bucket BigQuery e Cloud Storage devono essere nella stessa regione.
9. Scegli se pianificare un caricamento ricorrente dei dati del catalogo.
10. Se è la prima volta che importi il catalogo o lo reimporti in seguito alla sua eliminazione definitiva, seleziona i livelli di prodotto. Scopri di più sui livelli di prodotto.
  
  Modificare la configurazione a livello di prodotto dopo aver importato tutti i dati richiede uno sforzo significativo.
  
  Importante: non puoi attivare Retail Search per i progetti con un catalogo dei prodotti che è stato importato solo sotto forma di varianti. Se vuoi utilizzare Retail Search e importare varianti, utilizza il livello prodotto di primary.
11. Fai clic su Import (Importa).
ricci
1. Se è la prima volta che carichi il catalogo o reimporti il catalogo dopo averlo eliminato definitivamente, imposta i livelli di prodotto utilizzando il metodo Catalog.patch. Questa operazione richiede il ruolo Amministratore rivenditore. Scopri di più sui livelli di prodotto.
  - ingestionProductType: supporta i valori primary (predefinito) e variant.
  - merchantCenterProductIdField: supporta i valori offerId (valore predefinito) e itemGroupId. Se non utilizzi Merchant Center, imposta il valore predefinito su offerId.
```
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 contenente i tuoi dati.
  - STAGING_DIRECTORY: facoltativo. Una directory Cloud Storage utilizzata come località temporanea per i tuoi dati prima che venga importata in BigQuery. Lascia vuoto questo campo per consentire all'API Retail di creare automaticamente una directory temporanea (consigliato).
  - ERROR_DIRECTORY: facoltativo. Una directory Cloud Storage per le informazioni sugli errori relativi all'importazione. Lascia vuoto questo campo per consentire all'API Retail di creare automaticamente una directory temporanea (scelta consigliata).
  - dataSchema: per la proprietà dataSchema, utilizza il valore product_merchant_center. Consulta lo schema di tabella dei prodotti di Merchant Center.
  Ti consigliamo di non specificare directory di gestione temporanea o di errore in modo che l'API Retail possa creare automaticamente un bucket Cloud Storage con le nuove directory di gestione temporanea ed errore. Questi vengono creati nella stessa area geografica del set di dati BigQuery e sono univoci per ogni importazione (il che impedisce a più job di importazione di inserire dati nella stessa directory e reimportare potenzialmente gli stessi dati). Dopo tre giorni, il bucket e le directory vengono eliminati automaticamente per ridurre i costi di archiviazione.
  
  Un nome di bucket creato automaticamente include l'ID progetto, l'area geografica del bucket e il nome dello schema dei dati, separati da trattini bassi (ad esempio 4321_us_catalog_retail). Le directory create automaticamente sono chiamate staging o errors, aggiunte da un numero (ad esempio staging2345 o errors5678).
  
  Se specifichi le directory, il bucket Cloud Storage deve trovarsi nella stessa regione del set di dati BigQuery, altrimenti l'importazione non riuscirà. Fornisci le directory di gestione temporanea ed errore nel formato gs://<bucket>/<folder>/; devono essere diverse.
```
  curl -X POST \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "inputConfig":{
            "bigQuerySource": {
              "datasetId":"DATASET_ID",
              "tableId":"TABLE_ID",
              "dataSchema":"product_merchant_center"
            }
          }
      }' \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"
```

Importa dati del catalogo da BigQuery

Per importare i dati del catalogo nel formato corretto da BigQuery, utilizza lo schema di Retail per creare una tabella BigQuery con il formato corretto e carica la tabella vuota con i dati di catalogo. Carica i dati nell'API Retail.

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

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

Procedura guidata

Per importare il catalogo:

Se il set di dati BigQuery si trova in un altro progetto, configura le autorizzazioni richieste in modo che l'API Retail possa accedere al set di dati BigQuery. Scopri di più
Importa i dati del catalogo nell'API Retail.
Console
1. Vai alla pagina Dati retail nella console Google Cloud.
  
  Vai alla pagina Dati
2. Fai clic su Importa per aprire il riquadro Importa dati.
3. Scegli Catalogo dei prodotti.
4. Seleziona BigQuery come origine dati.
5. Seleziona il ramo in cui caricherai il catalogo.
6. Scegli Schema dei cataloghi dei prodotti di vendita al dettaglio. Questo è lo schema dell'API 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 tuoi dati.
  
  Se non specificata, viene utilizzata una località predefinita. Se specificato, il bucket BigQuery e Cloud Storage devono essere nella stessa regione.
9. Se non hai abilitato Retail Search e stai utilizzando lo schema di Merchant Center, seleziona il livello del prodotto.
  
  Devi selezionare il livello del prodotto se è la prima volta che importi il catalogo o reimporti il catalogo dopo l'eliminazione definitiva. Scopri di più sui livelli di prodotto. La modifica dei livelli di prodotto dopo aver importato eventuali dati richiede uno sforzo significativo.
  
  Importante: non puoi attivare Retail Search per i progetti con un catalogo dei prodotti che è stato importato come variante.
10. Fai clic su Import (Importa).
ricci
1. Se è la prima volta che carichi il catalogo o reimporti il catalogo dopo averlo eliminato definitivamente, imposta i livelli di prodotto utilizzando il metodo Catalog.patch. Questa operazione richiede il ruolo Amministratore rivenditore.
  - ingestionProductType: supporta i valori primary (impostazione predefinita) e variant.
  - merchantCenterProductIdField: supporta i valori offerId e itemGroupId. Se non utilizzi Merchant Center, non è necessario 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 puntare al tuo set di dati BigQuery.
  - DATASET_ID: l'ID del set di dati BigQuery.
  - TABLE_ID: l'ID della tabella BigQuery contenente 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 località temporanea per i tuoi dati prima che venga importata in BigQuery. Lascia vuoto questo campo per consentire all'API Retail di creare automaticamente una directory temporanea (consigliato).
  - ERROR_DIRECTORY: facoltativo. Una directory Cloud Storage per le informazioni sugli errori relativi all'importazione. Lascia vuoto questo campo per consentire all'API Retail di creare automaticamente una directory temporanea (scelta consigliata).
  - dataSchema: per la proprietà dataSchema, utilizza il valore product (valore predefinito). Utilizzerai lo schema di Retail.
  Ti consigliamo di non specificare directory di gestione temporanea o di errore in modo che l'API Retail possa creare automaticamente un bucket Cloud Storage con le nuove directory di gestione temporanea ed errore. Questi vengono creati nella stessa area geografica del set di dati BigQuery e sono univoci per ogni importazione (il che impedisce a più job di importazione di inserire dati nella stessa directory e reimportare potenzialmente gli stessi dati). Dopo tre giorni, il bucket e le directory vengono eliminati automaticamente per ridurre i costi di archiviazione.
  
  Un nome di bucket creato automaticamente include l'ID progetto, l'area geografica del bucket e il nome dello schema dei dati, separati da trattini bassi (ad esempio 4321_us_catalog_retail). Le directory create automaticamente sono chiamate staging o errors, aggiunte da un numero (ad esempio staging2345 o errors5678).
  
  Se specifichi le directory, il bucket Cloud Storage deve trovarsi nella stessa regione del set di dati BigQuery, altrimenti l'importazione non riuscirà. Fornisci le directory di gestione temporanea ed errore 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 nell'API Retail effettuando una richiesta POST per il 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 di risposta simile al seguente:
```
{
"name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"done": false
}
```
  Il campo name è l'ID dell'oggetto operazione. Per richiedere lo stato di questo oggetto, sostituisci il campo 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 di stato 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 di 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 Retail, procedi nel seguente modo.

Apri la pagina IAM nella console Google Cloud.

Apri la pagina IAM
Seleziona il progetto Retail.
Trova l'account di servizio con il nome Account di servizio Retail.

Se non hai già avviato un'operazione di importazione con l'API Retail, 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 riesce a causa di errori delle autorizzazioni, torna qui e completa questa attività.
Copia l'identificatore per l'account di servizio, che sembra un indirizzo email (ad esempio, service-525@gcp-sa-retail.iam.gserviceaccount.com).
Passa al tuo progetto BigQuery (nella stessa pagina IAM e amministrazione) e fai clic su Concedi l'accesso.
In Nuove entità, inserisci l'identificatore dell'account di servizio Retail e seleziona il ruolo BigQuery > Utente BigQuery.
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ù
Fai clic su Salva.

Importa i dati del 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 che vuoi importare e caricali in Cloud Storage. Da qui, puoi importarlo nell'API Retail.

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

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

Assicurati che l'account di servizio Retail abbia l'autorizzazione per leggere e scrivere nel bucket.

L'account di servizio Retail è elencato nella pagina IAM della console Google Cloud con il nome Retail Service Account (Account di servizio Retail). Utilizza l'identificatore dell'account di servizio, simile a un indirizzo email (ad esempio, service-525@gcp-sa-retail.iam.gserviceaccount.com), quando aggiungi l'account alle autorizzazioni del bucket.
Importa i dati del catalogo nell'API Retail.
Console
1. Vai alla pagina Dati retail nella console Google Cloud.
  
  Vai alla pagina Dati
2. Fai clic su Importa per aprire il riquadro Importa dati.
3. Scegli Catalogo dei prodotti come origine dati.
4. Seleziona il ramo in cui caricherai il catalogo.
5. Scegli Schema dei cataloghi dei prodotti di vendita al dettaglio come schema.
6. Inserisci il percorso dei dati Cloud Storage.
7. Se non hai abilitato Retail Search, seleziona i livelli di prodotto.
  
  Devi selezionare i livelli di prodotto se è la prima volta che importi il catalogo o reimporti il catalogo dopo averlo eliminato definitivamente. Scopri di più sui livelli di prodotto. La modifica dei livelli di prodotto dopo aver importato eventuali dati richiede uno sforzo significativo.
  
  Importante: non puoi attivare Retail Search per i progetti con un catalogo dei prodotti che è stato importato come variante.
8. Fai clic su Import (Importa).
ricci
1. Se è la prima volta che carichi il catalogo o lo stai reimportando, dopo averlo eliminato definitivamente, imposta i livelli di prodotto utilizzando il metodo Catalog.patch. Scopri di più sui livelli di prodotto.
  - ingestionProductType: supporta i valori primary (predefinito) e variant.
  - merchantCenterProductIdField: supporta i valori offerId e itemGroupId. Se non utilizzi Merchant Center, non è necessario 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 indirizzare il tuo bucket Cloud Storage.
  
  Puoi fornire più file o solo uno; in questo esempio vengono utilizzati due file.
  - INPUT_FILE: uno o più file in Cloud Storage contenenti i tuoi dati di catalogo.
  - ERROR_DIRECTORY: una directory di 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 di errore non esiste, l'API Retail la crea. Il bucket deve già esistere.
```
{
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
  }
},
"errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}
```
3. Importa le informazioni del catalogo nell'API Retail effettuando una richiesta POST per il 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 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 name con il valore restituito dal metodo di importazione, fino a quando il campo done restituisce true come valore di seguito:
```
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 true e include un oggetto Status simile al seguente esempio:
```
{ "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
  "createTime": "2020-01-01T03:33:33.000001Z",
  "updateTime": "2020-01-01T03:34:33.000001Z",
  "successCount": "2",
  "failureCount": "1"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse"
},
"errorsConfig": {
  "gcsPrefix": "gs://error-bucket/error-directory"
}
}
```
  Puoi esaminare i file nella directory degli errori in Cloud Storage per vedere che tipo di errori si sono verificati durante l'importazione.

Importa dati di catalogo in linea

curl

Importa i dati del catalogo nell'API Retail in linea facendo una richiesta POST al metodo REST Products:import, utilizzando l'oggetto productInlineSource per specificare i dati del catalogo.

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

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

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

{
"inputConfig": {
"productInlineSource": {
  "products": [
    { PRODUCT_1 }
    { PRODUCT_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'elemento di prodotto

Le voci Product nel file JSON dovrebbero essere simili ai seguenti esempi.

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

Campi obbligatori minimi:

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

Completa l'oggetto:

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

L'API Retail 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. L'API Retail può utilizzare le informazioni sul prodotto passate per arricchire i dati storici sugli eventi utente e migliorare la precisione 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.

Importa i dati storici del catalogo

Quando il campo expireTime di un prodotto è impostato su un timestamp precedente, questo prodotto viene considerato come prodotto storico. Imposta la disponibilità del prodotto su OUT_OF_STOCK per evitare di influire su Recommendations AI.

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

Chiama il metodo `Product.Create`

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

Importazione in linea di prodotti scaduti

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

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

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

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

Importa i prodotti scaduti da BigQuery o Cloud Storage

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

Tieni aggiornato il catalogo

L'API Retail si basa sulle informazioni correnti sui prodotti per fornire i risultati migliori. Ti consigliamo di importare il catalogo ogni giorno per assicurarti che sia aggiornato. Puoi utilizzare Google Cloud Scheduler per pianificare le importazioni oppure scegliere un'opzione di pianificazione automatica quando importi i dati utilizzando la console Google Cloud.

Puoi aggiornare solo gli articoli di prodotto nuovi o modificati oppure importare l'intero catalogo. Se importi prodotti che sono già nel tuo catalogo, non vengono aggiunti di nuovo. Qualsiasi elemento modificato è stato aggiornato.

Per aggiornare un singolo articolo, consulta la sezione Aggiornare le informazioni sui prodotti.

Aggiornamento in batch

Puoi usare il metodo di importazione per aggiornare in batch il catalogo. L'operazione viene eseguita nello stesso modo per l'importazione iniziale; segui i passaggi descritti in Importare i dati del catalogo.

Monitora integrità importazione

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

Visualizza le informazioni aggregate sul tuo catalogo e visualizza l'anteprima dei prodotti caricati nella scheda Catalogo della pagina Dati della console Google Cloud Retail.

Vai alla pagina Dati
Valuta se devi aggiornare i dati del catalogo per migliorare la qualità dei risultati della Ricerca al dettaglio e sbloccare i livelli di rendimento della ricerca nella pagina Qualità dei dati.

Per scoprire di più su come controllare la qualità dei dati di ricerca e visualizzare i livelli di rendimento della ricerca, consulta l'articolo 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
Per creare avvisi che ti permettono di sapere se si verificano problemi con i caricamenti dei dati, segui le procedure descritte in Impostare gli avvisi.

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

Passaggi successivi

Inizia a registrare gli eventi utente.
Visualizza informazioni aggregate sul tuo catalogo.
Impostare gli avvisi di caricamento dei dati.

Importa le informazioni del catalogo

Importa dati del catalogo da BigQuery

Importa i dati del catalogo da Cloud Storage

Importa dati di catalogo in linea

Prima di iniziare

Best practice per l'importazione del catalogo

Informazioni sull'importazione dei dati del catalogo

Considerazioni sull'importazione del catalogo

Elimina definitivamente i rami del catalogo

Sincronizza Merchant Center con l'API Retail

Sincronizza il tuo account Merchant Center

Console

ricci

Elenca i collegamenti del tuo account Merchant Center

Console

ricci

Scollegare l'account Merchant Center

Console

ricci

Limitazioni al collegamento a Merchant Center

Importare i dati del catalogo da Merchant Center

Importazione collettiva da Merchant Center

Console

ricci

Importa dati del catalogo da BigQuery

Console

ricci

Configurare l'accesso al set di dati BigQuery

Importa i dati del catalogo da Cloud Storage

Console

ricci

Importa dati di catalogo in linea

curl

Java

Formato dei dati JSON dell'elemento di prodotto

Dati storici del catalogo

Importa i dati storici del catalogo

Chiama il metodo Product.Create

Importazione in linea di prodotti scaduti

Importa i prodotti scaduti da BigQuery o Cloud Storage

Tieni aggiornato il catalogo

Aggiornamento in batch

Monitora integrità importazione

Passaggi successivi

Chiama il metodo `Product.Create`